@akira-tl/forgerelay 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-08-30
+
+### Added
+
+- `subagent.session resume` 现在基于 provider-native continuation 继续已有 Session；Codex、Claude、OpenCode、Pi 支持真实 continuation，Cursor/Copilot 明确保持 start-only。
+
+### Changed
+
+- Session 固定创建时的 provider/profile/model/thinking，并严格限制在所属 Execution Workspace；busy resume、跨 Workspace 访问和不受支持的 continuation 都返回明确错误。
+
+### Fixed
+
+- Windows restart mailbox 测试在清理临时 SQLite state 前显式关闭 restored server，避免 `EBUSY`。
+
+## [0.7.0] - 2026-08-30
+
+### Added
+
+- 新增 first-class `subagent.session` Capability tracer：Host 可通过现有 Capability Gateway 发现并启动 provider-backed Subagent Session、查询 `status`、列出当前 Execution Workspace 拥有的 Session，并通过有界单次 delivery mailbox 接收后台 Run 的最终结果；canonical Core MCP tool 仍保持九个。
+- 为 ForgeRelay Subagent 引入稳定的 Session / Run identity 和 workspace-scoped coordination，使每次 delegated execution 都有明确的 Run 生命周期、Activity 关联和 provider continuation 映射，而无需经由 `bash -> forgerelay agents ...` CLI 间接执行。
+
+### Changed
+
+- 将 Claude Code、Codex、OpenCode、Pi 等 provider 的原生 session store 作为 conversation history 真源；ForgeRelay SQLite 停止写入 delegated prompt、profile body、final response、Hook report history 和 provider event/items，仅保留轻量 ownership、provider/profile/model/thinking 与 active/latest Run 协调元数据。
+- Provider adapter contract 收敛为 continuation identity、final response 与必要执行元数据，provider streaming/messages/events 只瞬时消费；profile body 仅在 Session 首次启动时交给 provider，ForgeRelay 不保存正文副本。
+
+## [0.6.2] - 2026-08-29
+
+### Added
+
+- Added Composite Workspace as a first-class Workspace kind on the existing `open_workspace` surface. A Composite Workspace has its own persistent `cws_...` identity, may start with zero members, and can mount named local, managed-worktree, or relayed Workspaces with Agent-facing purpose descriptions.
+- Added explicit member routing across filesystem, capability, Bash/process, and Codex-compatible `apply_patch` / `exec_command` / `write_stdin` surfaces. The Composite Workspace ID remains Host-facing while each operation must name its execution member; ForgeRelay never selects or falls back to another member automatically.
+- Added one Composite Host Turn / Activity presentation that aggregates local and remote member activity with member labels while keeping audit, process, filesystem, and remote execution facts owned by the actual member Workspace/Execution ForgeRelay.
+
+### Changed
+
+- `close_workspace` now dissolves a Composite Workspace without closing member Workspaces, finalizing managed worktrees, interrupting member processes, deleting files, or removing Workspace Relay routes.
+- Interactive debug launchers now derive their displayed local endpoints from the selected `FORGERELAY_DEBUG_CONFIG_DIR/config.json`, allowing multiple isolated debug instances to use separate config/state/worktree directories and different ports such as 7677 and 6768.
+
+### Fixed
+
+- Routed Codex-compatible process and patch tools through the same Workspace Relay and Composite member resolution path as the canonical tool surface, including explicit no-fallback behavior for remote members.
+
 ## [0.6.1] - 2026-08-28
 
 ### Added

package/README.md

@@ -101,6 +101,44 @@ Once a workspace is open, the host can:
 Normal work happens in your existing checkout. ForgeRelay does not silently move
 every task into a worktree.
 
+## Composite workspaces across multiple devices
+
+When one task needs more than one execution environment, a Composite Workspace keeps
+one Host-facing working context while preserving each member Workspace as a separate
+execution boundary. For example, `code` can point at a local checkout while
+`compute` points through Workspace Relay at a GPU machine.
+
+Composite Workspaces use the same lifecycle entry points as ordinary Workspaces:
+
+```text
+open_workspace({ kind: "composite", name: "research-project" })
+open_workspace({
+  action: "member",
+  workspaceId: "cws_...",
+  memberAction: "add",
+  member: {
+    name: "compute",
+    purpose: "GPU and high-performance computation",
+    path: "/srv/research",
+    relay: "gpu-server"
+  }
+})
+```
+
+Work still names the member explicitly:
+
+```text
+read({ workspaceId: "cws_...", member: "code", path: "src/model.py" })
+bash({ workspaceId: "cws_...", member: "compute", command: "python train.py" })
+```
+
+ForgeRelay does not merge member filesystems, Git state, Hooks, Skills, processes,
+or audit facts, and it never infers a member from the tool type or purpose text.
+The Composite Activity Panel presents member operations in one Host Turn while the
+actual facts remain owned by the member Workspace. `close_workspace` on a Composite
+Workspace means **dissolve**: the Composite identity and membership are removed, but
+member Workspaces, worktrees, running jobs, files, and relay routes are preserved.
+
 ### Progressive MCP context
 
 ForgeRelay keeps the callable MCP surface and its low-frequency operating manuals

package/capabilities/subagents/GUIDE.md

@@ -1,69 +1,129 @@
-# ForgeRelay Subagents
+# ForgeRelay Subagent
 
-当任务涉及委派给另一个本地 coding agent、获取第二意见、并行调查，或用户明确点名 subagent 时读取本指南。
+当任务需要委派给另一个本地 coding agent、获取第二意见、并行调查，或用户明确点名 Subagent/provider 时读取本指南。
 
-## 当前接口边界
+## 当前接口
 
-0.3 仍然使用 ForgeRelay CLI 协调 provider-backed local subagent；当前没有 first-class MCP subagent tool。不要把 Host 自己的 subagent 功能与 ForgeRelay subagent 混为一谈。
+启用 Subagent 后，`open_workspace` 会在 `capabilityCatalog` 中公开 `subagent.session`，同时返回紧凑的 provider/profile 元数据。不要为 Subagent 寻找或假设额外的 Core MCP tool；长期可见 Core tool surface 保持不变。
 
-启用方式：
+通过统一 `capability` gateway 调用：
 
-```bash
-FORGERELAY_SUBAGENTS=1 forgerelay serve
+```text
+name = subagent.session
+action = run
 ```
 
-启用后，`open_workspace` 会返回紧凑的 `agentProviders` 和 `agents` 元数据。配置 profile 通常来自全局 ForgeRelay 配置目录以及项目内：
+当前支持四个 operation：
 
-```text
-.forgerelay/agents/*.md
-.devspace/agents/*.md
+- `start`：创建 Subagent Session，并立即启动第一个 Subagent Run；
+- `resume`：在支持真实 continuation 的 provider 上继续现有 Session；
+- `status`：读取当前 Workspace 中一个 Session 的协调状态；
+- `list`：列出当前 Workspace 拥有的 Session 摘要。
+
+`subagent.session` 不支持 `batch.execute`。
+
+## start
+
+使用 profile：
+
+```json
+{
+  "operation": "start",
+  "target": "reviewer",
+  "prompt": "检查当前改动的并发与错误处理。"
+}
 ```
 
-旧 `.devspace` 路径仅用于迁移兼容。
+也可以把 ForgeRelay 支持的 provider 名直接作为 `target`。创建新 Session 时可以显式给出 `model` / `thinking`；profile 已有默认值时通常无需重复覆盖。
 
-## 何时使用
+返回值包含：
 
-不要因为存在 profile 就自动委派普通开发工作。只有在用户要求委派、第二意见、并行工作或指定 subagent/provider 时才使用，并明确告诉用户正在使用另一个 subagent。
+- `session.id`：ForgeRelay 的 Subagent Session identity；
+- `session.status`：`running` 或 `idle`；
+- `run.id`：本次 delegated execution 的 Subagent Run identity；
+- provider/profile/model 等紧凑协调元数据。
 
-选择 profile 时以 `open_workspace` 返回的 compact profile catalog 为准。`forgerelay agents ls` 显示的是当前 workspace 的已有 subagent sessions，不是 profile 定义列表。
+首次 `start` 使用当时有效的 profile body 作为 provider-native conversation 的初始 instructions。ForgeRelay 不把 profile body 复制进自己的 Session SQLite。
 
-## 常用命令
+## resume
 
-正常委派只需要：
+已有 Session 完成一次 Run 后，可发送新的 delegated prompt：
 
-```bash
-forgerelay agents ls
-forgerelay agents run <profile-or-provider-or-id> "<prompt>"
-forgerelay agents show <id>
+```json
+{
+  "operation": "resume",
+  "sessionId": "agt_...",
+  "prompt": "继续检查测试覆盖。"
+}
 ```
 
-语义：
+`resume` 只接受 `sessionId + prompt`，不能改变 model/thinking。Session 创建时确定的 provider/profile/model/thinking 在整个 Session 生命周期中保持固定；resume 不重新读取或注入当前 profile body，而是使用 provider-native continuation history。
 
-- `run <profile>`：启动配置好的 profile；
-- `run <provider>`：没有合适 profile 时直接启动 ForgeRelay 内建 provider；
-- `run <id>`：向现有 agent session 发送 follow-up；
-- `show <id>`：查看状态和最新响应；仍在运行时可稍后再次调用；
-- shell workspace 环境会把 CLI 操作自动限定到当前 ForgeRelay workspace。
+同一个 Session 最多只有一个 active Run；Session 正在执行时再次 resume 会返回 `subagent.busy`，不会排队或并发执行。Codex、Claude、OpenCode、Pi 支持真实 continuation；Cursor/Copilot 当前明确标记为 start-only，resume 返回 `subagent.continuation_unsupported`，不会伪装成新 provider session。
 
-如确实需要覆盖 profile/provider 默认值，可使用：
+## status / list
 
-```bash
-forgerelay agents run <profile-or-provider> --model <model> "<prompt>"
-forgerelay agents run <profile-or-provider> --thinking <level> "<prompt>"
+查询一个 Session：
+
+```json
+{
+  "operation": "status",
+  "sessionId": "agt_..."
+}
 ```
 
-`thinking` 是 provider-specific passthrough；ForgeRelay 不在 provider 之间翻译 reasoning level。
+列出当前 Workspace 的 Session：
+
+```json
+{
+  "operation": "list"
+}
+```
+
+Session 受实际 Execution Workspace 所有权约束；Session ID 不是跨 Workspace 的访问凭证。`status` / `resume` 都只能访问当前实际 Execution Workspace 拥有的 Session，`list` 也只返回当前 Workspace 的紧凑摘要。
+
+Session 返回中会给出 `continuationSupported` 与 `resumable`；`open_workspace` 的 provider metadata 也会明确给出 `continuationSupported`。当前尚未通过 first-class Capability 开放 `stop` 或 `delete`，不要伪造这些 operation，也不要用新的 Core MCP tool 绕过 Capability Gateway。
+
+## 后台完成与结果交付
+
+`start` 接受执行后会尽快把 Session/Run identity 返回给 Host，Subagent Run 在后台继续执行。
+
+Run 完成后：
+
+- ForgeRelay 创建一个 linked `subagent_result` Activity，只记录 Session/Run/provider/status 等有界元数据；
+- final response 放入有界 delivery mailbox，等待同一 Workspace 的后续 ForgeRelay 调用领取；
+- 成功领取后 mailbox 条目立即删除，同一个 completion 不重复交付；
+- 未领取 completion 可以跨正常 ForgeRelay 进程重启保留。
+
+如果需要等待结果，使用 `status` 进行有节制的后续查询；不要高频短轮询。
+
+## 数据所有权
+
+Claude Code、Codex、OpenCode、Pi 等 provider 自己的 session store 是 conversation history 的真源。ForgeRelay 只保存恢复、Workspace ownership 和执行协调所需的小型元数据。
+
+ForgeRelay 不把以下内容保存进 Subagent Session SQLite 或 Activity Audit：
+
+- delegated prompt；
+- profile body；
+- provider transcript/messages/events/items；
+- final response 正文；
+- 完整 Hook report 历史；
+- 完整 Subagent Run 历史。
+
+Activity 只保留操作摘要；delivery mailbox 只用于尚未交付的 bounded completion，不是 conversation/history store。
+
+## Hooks
 
-除非正在明确调试 ForgeRelay provider integration，不要绕过 ForgeRelay 直接运行 `codex`、`claude`、`opencode`、`pi`、`cursor-agent`、`copilot` 等 provider CLI。
+`SubagentStart` / `SubagentStop` 在每一次 Subagent Run 生命周期中触发。Hook payload 使用 Session/Run/profile/provider/model/thinking/status 等协调元数据，不包含 delegated prompt 或 final response。
 
-## Prompt 与验证
+## CLI 兼容
 
-Subagent 只收到你发送的 prompt 和它自己的 profile instructions，因此 prompt 必须自包含：目标、相关模块/文件、约束、验收标准，以及它能否修改文件。
+`forgerelay agents` 仍可用于本地诊断和兼容性操作，但 Host 正常委派优先使用 `subagent.session` Capability，不要通过 `bash -> forgerelay agents ...` 实现 first-class Subagent。
 
-Subagent 的结果不是自动验证过的最终答案。收到响应后：
+## 验证责任
 
-- 写入型任务：检查实际改动并运行相关测试；
-- 只读调查：核对关键结论是否有仓库证据；
-- 向用户说明使用了哪个 profile/provider、它给出的结论、你做了哪些验证，以及剩余风险。
+Subagent 返回不是自动验证过的最终结论。收到结果后仍应按照任务类型验证：
 
-`SubagentStart` / `SubagentStop` lifecycle Hooks 会在 worker 生命周期中触发；异步报告会随 ForgeRelay session 持久化并可由 `forgerelay agents show` 查看。
+- 写入型任务检查真实 diff，并运行相关测试；
+- 只读调查核对关键结论对应的仓库事实；
+- 向用户说明使用的 profile/provider、核心结论、已做验证与剩余风险。

package/dist/activity/lifecycle.js

@@ -32,7 +32,7 @@ export class ActivityLifecycle {
         const activityId = executionContext.activityId;
         try {
             const result = await options.operation(executionContext);
-            this.finish(activityId, result, options.outcome?.(result) ?? { type: "succeeded" });
+            this.finish(activityId, options.auditResult?.(result) ?? result, options.outcome?.(result) ?? { type: "succeeded" });
             return result;
         }
         catch (error) {

package/dist/activity/mcp-query-tools.js

@@ -20,6 +20,7 @@ const activitySummarySchema = z.object({
     target: z.string(),
     detailAvailable: z.boolean(),
     workspaceId: z.string().optional(),
+    member: z.string().optional(),
     processId: z.number().int().positive().optional(),
     outputId: z.string().optional(),
     commandLength: z.number().int().nonnegative().optional(),

package/dist/activity/query-service.js

@@ -126,6 +126,7 @@ function toSummary(record) {
         target: activityTarget(record, request, result, structured),
         detailAvailable: !bulkGroup && record.tool !== "rename" && record.tool !== "delete" && record.tool !== "batch",
         ...(record.workspace.id ? { workspaceId: record.workspace.id } : {}),
+        ...(stringField(request, "member") ? { member: stringField(request, "member") } : {}),
         ...(processId !== undefined ? { processId } : {}),
         ...(outputId !== undefined ? { outputId } : {}),
         ...(bashLike && command !== undefined ? { commandLength: command.length } : {}),

package/dist/capabilities.js

@@ -92,7 +92,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         capabilities.push("batch.execute");
     }
     if (config.subagents) {
-        capabilities.push("subagent.profiles");
+        capabilities.push("subagent.session");
     }
     if (config.artifactsEnabled && context.artifactDownloadSupported) {
         capabilities.push("artifact.native-download");

package/dist/capability-registry.js

@@ -130,6 +130,25 @@ export function createCapabilityRegistry(dependencies) {
         line: z.number().int(),
         column: z.number().int(),
     };
+    const subagentSessionInput = z.discriminatedUnion("operation", [
+        z.object({
+            operation: z.literal("start"),
+            target: z.string().min(1),
+            prompt: z.string().min(1),
+            model: z.string().min(1).optional(),
+            thinking: z.string().min(1).optional(),
+        }).strict(),
+        z.object({
+            operation: z.literal("resume"),
+            sessionId: z.string().min(1),
+            prompt: z.string().min(1),
+        }).strict(),
+        z.object({
+            operation: z.literal("status"),
+            sessionId: z.string().min(1),
+        }).strict(),
+        z.object({ operation: z.literal("list") }).strict(),
+    ]);
     const codeIntelligenceInput = z.discriminatedUnion("operation", [
         z.object({ operation: z.literal("definition"), ...positionInput }).strict(),
         z.object({ operation: z.literal("hover"), ...positionInput }).strict(),
@@ -201,6 +220,21 @@ export function createCapabilityRegistry(dependencies) {
                     run: async (input, context, options) => dependencies.codeIntelligence.run(input, context, options),
                 }]
             : []),
+        ...(dependencies.subagentSession
+            ? [{
+                    name: "subagent.session",
+                    description: "Coordinate provider-backed Subagent Sessions in the current Execution Workspace.",
+                    guideName: "subagents",
+                    readGuideBeforeFirstUse: true,
+                    batchPolicy: "unsupported",
+                    inputSchema: subagentSessionInput,
+                    availability: () => ({
+                        available: dependencies.subagentSession?.available ?? false,
+                        reason: dependencies.subagentSession?.unavailableReason,
+                    }),
+                    run: async (input, context, options) => dependencies.subagentSession.run(input, context, options),
+                }]
+            : []),
         ...(dependencies.batchExecute
             ? [{
                     name: "batch.execute",