Run 与沙箱模型（Run and Sandbox Model）

目标关联

该特性支撑专业工作执行、可审计交付、上下文连续性、未来群组协作和专业可靠性。

实现的关键特性：

• Sandbox-First Work Execution
• Tool-Mediated Action System
• Memory-Aware Context System
• Quality and Governance System
• Professional Workflow Orchestration

技术设计对齐

• durable artifacts 是 source of truth。
• 本地 filesystem sandbox 是 Phase 1 workspace。
• 每次 run 都有稳定 session_id、task_id、run_id。
• config snapshot 不可变。
• events 和 records append-only。
• run layout scheduler-ready。
• 环境可从 artifacts 重建。

范围

Phase 1 包含稳定 IDs、确定性 run directory、run state、config/prompt snapshot、effective prompt archive、workspace、deliverables、archive、logs、sandbox manifest、artifact manifest 和 filesystem path guards。

排除 distributed artifact store、remote sandbox execution、container isolation、full environment snapshotting、advanced quota、full resume/revise。

概念模型

Session -> one or more Tasks -> one or more Runs -> one Sandbox -> many Artifacts

• Session：连续工作线程。
• Task：Session 中的工作单元。
• Run：Task 的一次执行尝试。
• Sandbox：Run 的文件系统工作区。
• Artifact：Run 产出或消费的持久文件。

Sandbox Layout

runs/<run-id>/
  run.json
  session.json
  task.yaml
  prompt.md
  config.yaml
  effective-system-prompt.md
  sandbox-manifest.json
  artifact-manifest.json
  events.jsonl
  transcript.md
  workspace/
  deliverables/
  archive/
  logs/

Phase 1 必须生成：

• run.json
• prompt.md
• config.yaml
• effective-system-prompt.md
• sandbox-manifest.json
• artifact-manifest.json
• events.jsonl
• transcript.md

session.json、task.yaml 和高级 archive 文件可后续引入。

Run State

建议状态：

pending
running
waiting_for_tool
waiting_for_user
review_required
revision_required
completed
failed
cancelled

Phase 1 可使用 pending、running、completed、failed。

run.json 是 Phase 1 的 run state source of truth，至少包含 session_id、task_id、run_id、profile_id、config_fingerprint、status、created_at、updated_at、started_at、completed_at、failure_reason。

接口

CLI：

kgent run --config kgent.yaml --prompt "..." --sandbox ./runs/demo-001

可选：

--session-id
--task-id
--run-id

Python：

def create_run_context(config, prompt, sandbox_path, session_id=None, task_id=None, run_id=None) -> RunContext:
    ...

def update_run_state(context: RunContext, status: RunStatus) -> None:
    ...

def resolve_sandbox_path(context: RunContext, user_path: str) -> Path:
    ...

运行时行为

1. 创建或接收 IDs。
2. 创建 sandbox directories。
3. 写入 prompt、config snapshot、initial run metadata。
4. 初始化 events、transcript、logs。
5. 写入 sandbox manifest。
6. Filesystem tools 使用 sandbox path resolution。
7. Deliverables 写入 deliverables/。
8. 更新 run state。
9. 写入 artifact manifest 和最终 status。

产物

run.json 示例：

{
  "session_id": "...",
  "task_id": "...",
  "run_id": "...",
  "profile_id": "...",
  "config_fingerprint": "...",
  "status": "running",
  "created_at": "...",
  "updated_at": "...",
  "started_at": "...",
  "completed_at": null,
  "failure_reason": null
}

sandbox-manifest.json 和 artifact-manifest.json 分别记录 sandbox 边界和 artifacts。

质量和治理

• 禁止 path traversal。
• 只允许写入允许目录。
• 默认禁用 delete。
• 必需交付物必须在 deliverables/ 下。
• config/prompt snapshots 在 run start 后不可变。
• 所有文件操作被记录。

性能和调度考虑

Sandbox creation 是轻量目录创建；manifests 是小 JSON；events/logs append-only；artifact scanning 有边界。IDs、run state、manifest 和 config snapshot 为未来 scheduler、revision 和环境重建打底。

验收标准

1. 每个 run 有 session_id、task_id、run_id。
2. 创建确定性 sandbox directory。
3. 创建 workspace、deliverables、archive、logs。
4. 复制 prompt 和 resolved config。
5. 写入 run.json。
6. run state 可持久更新。
7. filesystem paths 通过 sandbox guards 解析。
8. sandbox 外写入被拒绝。
9. Phase 1 生成 sandbox 和 artifact manifests。
10. 模型没有不受限制的 filesystem access。