Agent 主会话

Agent 主会话的 origin.type 是 agent，session_id 等于 Agent 的 id。它保存用户与 Agent 的持续对话，并可以派发、查看、回复和停止工作会话。

Desktop 中的专属目录

Desktop 为每个 Agent 提供固定目录：

~/.downcity/agents/<agent_id>/main/

这是主会话自己的 Workspace，为文件、Shell 和 Power 提供执行环境。它不出现在 Works 项目列表里；切换项目或重新打开 Agent 都不会改变主会话目录。会话消息仍保存在 sessions/agent/<agent_id>/，与 main 中的文件分开。

项目任务由 work 会话执行。派发时必须明确指定项目 Workspace，不能继承主会话的 main 目录。

SDK 取用与恢复

SDK 不决定目录在磁盘上的位置，目录由宿主提供。首次取用可以传入专属 Workspace：

const agent = new Agent({
  id: "coder",
  model,
  workspace: main_workspace,
  resolve_work_workspace: async (workspace_id) => {
    const workspace = project_workspaces.get(workspace_id);
    if (!workspace) throw new Error("Project Workspace not found");
    return workspace;
  },
});

await agent.sessions.self({ workspace: main_workspace });

// self 的 Workspace 只用于创建；已有会话通过 get 明确恢复运行时实例。
const session = await agent.sessions.get(agent.id, "agent", {
  workspace: main_workspace,
});
const turn = await session.prompt({ query: "请检查项目 CI，并派发修复任务" });
await turn.finished;

project_workspaces 和 main_workspace 由宿主创建和持有。resolve_work_workspace 仅解析项目工作目标，不负责恢复主会话，也不自动选择项目。宿主应拒绝未登记的项目与主会话私有目录。

Workspace 实例不落盘，Session 只保存 workspace_id。每次重启后由宿主重新注入实例；仅有持久化 ID 并不意味着文件与 Shell 已经可用。get() 在缓存实例存在但目录实例尚未恢复时也会应用注入。

派发工作

Agent 主会话与 Messenger 的 channel 会话拥有以下工具；work 会话不递归派发：

模型先通过 context.workspaces.list 查看可用目录，再提供项目 ID：

session_start({
  workspace_id: "project-workspace-id",
  query: "修复 CI 中失败的三个测试，说明原因与验证结果。",
  title: "修复 CI"
})

工作会话只收到完整任务文本与目标项目目录，不继承主会话历史或私有目录。session_start 返回 session_id 和 delegation_id；运行时自动记录实际发起会话，完成或失败后回传到该会话。用户可继续交流，只有询问进度或处理待响应交互时才需要 session_check。

回传通过父会话的 prompt() 提交带 delegation_result 来源标记的上下文，沿用现有输入队列。工作输入和结果输入都使用稳定的 request_id，包括并入运行中 Turn 的输入，重复投递不会生成第二条用户消息。幂等输入在入库前被停止或持久化失败时，prompt() 拒绝提交，原结果保留待重试。子执行输出是参考数据，不代表新的用户指令。父会话已归档或不可用时保留结果，不自动创建替代会话。

恢复委派

SDK 宿主在绑定持久化存储并完成 Workspace、Power 和消息订阅装配后调用：

await agent.resume_work();

该方法启动未完成委派的后台恢复，也可重试此前失败的投递；它不等待工作完成。Desktop 在启动时自动调用。独立 SDK 默认使用进程内存储，跨进程恢复需要 City 提供持久化存储。

恢复沿用 Session 的既有语义：已完成的 Turn 复用持久化结果；尚未执行的输入可继续提交；已有流式输出的中断 Turn 收口为中断失败并回传，不自动重做已经发生的工具操作。

主目录通过 Agent 的 workspace 提供，项目目录通过 resolve_work_workspace 恢复。宿主如需恢复 Session 专属模型或消息订阅，可提供幂等的 prepare_work_session(session)；它在子执行及父会话接收结果之前调用。该回调仅装配资源，不提交模型输入。

session_stop 先持久化取消状态再停止子执行，尚未提交的结果不会自动回传。已被父会话接收的结果无法通过停止子执行撤回。Agent 释放期间暂停回传，已完成的结果保留供下次恢复。

会话身份

agent.sessions.list() 默认只列出 work 分区，因此主会话不会混入项目会话列表。归档或删除主会话后，再次取用会重建会话，专属 main 目录中的文件仍独立于会话历史。