@akira-tl/forgerelay 0.3.3 → 0.3.5

package/docs/configuration.md

@@ -78,7 +78,7 @@ FORGERELAY_ARTIFACTS=1 npx @akira-tl/forgerelay serve
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `FORGERELAY_ARTIFACTS` | `0` | Expose `download_artifact` for trusted native files. |
+| `FORGERELAY_ARTIFACTS` | `0` | Advertise the `artifact.download` Capability for trusted native files. |
 | `FORGERELAY_ARTIFACT_MAX_FILE_BYTES` | `104857600` | Maximum streamed size of one file (100 MiB). |
 
 The same settings may be persisted as `artifactsEnabled` and
@@ -115,20 +115,22 @@ MCP clients discover metadata from:
 
 | Value | Behavior |
 | --- | --- |
-| `minimal` | Default. Exposes `open_workspace`, `close_workspace`, `read`, `write`, `edit`, `rename`, `delete`, `bash`, `write_stdin`, and `close_worktree`. |
-| `full` | Adds dedicated `grep`, `glob`, and `ls` tools. |
-| `codex` | Experimental Codex-shaped tool surface using `open_workspace`, `close_workspace`, `read`, `rename`, `delete`, `apply_patch`, `exec_command`, `write_stdin`, and `close_worktree`. |
+| `minimal` | Default canonical surface: `open_workspace`, `capability`, `close_workspace`, `read`, `write`, `edit`, `rename`, `delete`, and `bash`. |
+| `full` | Compatibility value. Uses the same canonical 9-tool surface as `minimal`; search and directory inspection go through `bash`. |
+| `codex` | Experimental Codex-shaped compatibility adapter using `open_workspace`, `close_workspace`, `read`, `rename`, `delete`, `apply_patch`, `exec_command`, `write_stdin`, and `capability`. It does not define the ForgeRelay canonical interface. |
 
 `FORGERELAY_MINIMAL_TOOLS` remains a compatibility-style boolean alias when the
 explicit tool mode is unset. The corresponding legacy `DEVSPACE_*` names are
 also accepted.
 
-The selected mode controls the real `tools/list` surface. ForgeRelay does not
-hide callable tools behind capability documentation. In every mode,
+`minimal` and `full` now resolve to the same regular 9-tool `tools/list`; `full`
+is retained only as a configuration-compatibility value. `codex` selects a
+separate compatibility adapter. ForgeRelay does not hide core callable tools
+behind capability documentation. In every mode,
 `open_workspace` returns a `capabilityFingerprint` containing the package
 version, tool mode, and stable semantic capability names. The fingerprint also
 reports enabled optional domains such as subagent profile discovery, native
-artifact download, MCP App UI, or aggregate `show_changes` review when those
+artifact download, MCP App UI, or aggregate `review.changes` when those
 features are actually available; it remains a semantic summary rather than a
 copy of `tools/list`.
 
@@ -142,8 +144,8 @@ the corresponding feature is enabled, so disabled features do not add bootstrap
 context.
 
 There is no separate progressive-disclosure configuration switch. Capability
-Guide discovery is built in, while actual tool exposure continues to be
-controlled by `FORGERELAY_TOOL_MODE` and feature-specific settings. If the
+Guide discovery is built in, while optional low-frequency actions are advertised
+through the workspace Capability catalog instead of adding top-level tools. If the
 fingerprint reports a capability that is missing from the Host's current tool
 snapshot, treat that as stale Host MCP metadata: reconnect/refresh the integration
 or use a Host context that reloads `tools/list`. The ForgeRelay process cannot
@@ -163,16 +165,21 @@ current conversation. `newWorkspace: true` allocates a new logical handle withou
 creating another checkout or Git worktree and should be used only on explicit user
 request. Logical workspaces idle for more than two days are returned in `staleWorkspaces` so
 the user can choose whether to resume or release them. `close_workspace` removes a
-logical handle without deleting checkout files; it refuses to remove the last
-handle anchoring a physical worktree.
-
-`bash` has no execution-timeout input. It waits in the foreground for at most 300
-seconds; if the process is still alive, the result contains `running: true` and a
-canonical `processId`. `write_stdin` can poll or interact with that process for up
-to another 300 seconds per call. The former `sessionId` field remains a deprecated
-alias during the 0.2.x compatibility window. ForgeRelay does not kill a process
-merely because a wait window expires. Completed background processes are delivered once with a later
-tool result for the same logical workspace ID.
+checkout-backed logical handle without deleting checkout files. For a managed-worktree-backed
+workspace, `close_workspace` requires `commitMessage` and runs the existing safe
+worktree finalize lifecycle: close Hooks, commit when needed, fast-forward-only
+integration, cleanup, and alias invalidation.
+
+Regular `bash` has no execution-timeout input. `action="run"` (the default) waits
+in the foreground for at most 300 seconds; if the process is still alive, the
+result contains `running: true` and a canonical `processId`. Reuse the same `bash`
+with `action="process"` to poll/wait, send `input`, resize a PTY, or set
+`interrupt:true`; each wait can be up to 300 seconds. ForgeRelay does not kill a
+process merely because a wait window expires. Completed background processes are
+delivered once with a later tool result for the same logical workspace ID.
+
+Codex mode retains `write_stdin` only as an experimental compatibility adapter;
+regular Agent workflows should use the single `bash` process lifecycle.
 
 ## Widgets
 
@@ -181,7 +188,7 @@ tool result for the same logical workspace ID.
 | Value | Behavior |
 | --- | --- |
 | `full` | Default. Attach UI to exposed workspace/file/edit/shell tools. |
-| `changes` | Attach UI to `open_workspace` and aggregate `show_changes`. |
+| `changes` | Attach UI to `open_workspace` and Capability Gateway review results from `review.changes`. |
 | `off` | Disable widget UI. |
 
 ## Lifecycle hooks

package/docs/debugging.md

@@ -59,11 +59,11 @@ The acceptance checks:
 3. unauthenticated `/mcp` rejection;
 4. dynamic OAuth client registration, PKCE Owner-password approval, and access-token exchange;
 5. MCP `initialize`, including package/server version consistency and the shell mutation safety contract;
-6. `tools/list` for the full debug tool surface, including `close_workspace`, `write_stdin`, canonical `processId` plus the deprecated `sessionId` compatibility alias, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, workspace resume/stale-workspace schema, and MCP App tool metadata;
+6. `tools/list` for the exact canonical 9-tool regular surface, including unified `close_workspace`, the single `capability` Gateway, canonical `bash` `action="run"` / `action="process"` plus `processId`, absence of retired dedicated aliases/search tools, the non-blanket shell mutation policy, workspace resume/stale-workspace schema, and MCP App tool metadata;
 7. the full MCP App template chain: `resources/list`, `resources/templates/list`, current content-hashed `resources/read`, legacy/historical template compatibility reads, `text/html;profile=mcp-app`, the unique app domain plus CSP resource domains, and an HTTP fetch of the JavaScript asset referenced by the template;
-8. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash` through `ProcessManager`, and a deliberate failed `edit`;
+8. a real Git checkout workspace with Capability catalog/describe/read/run, `review.changes`, `write`, `read`, `rename`, `delete`, foreground `bash`, `bash` long-process `run` → `processId` → `process`, and a deliberate failed `edit`; on Linux the catalog/describe path also verifies `artifact.download` native-file transport metadata;
 9. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP transport session, plus rejection of an arbitrary path outside the workspace/temp roots;
-10. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;
+10. a temporary Git repository with managed worktree creation, file modification, and `close_workspace` worktree finalization;
 11. 本地 bare remote 上的 release-tag-push Hook：成功 Hook 必须先运行再允许 `v0.2.0` push，失败 Hook 必须在 remote mutation 前阻断 `v0.2.1`；
 12. deterministic local subagent error path，不联系任何模型 provider；
 13. debug hook recorder 覆盖全部九个 Hooks v1 lifecycle events。

package/docs/gotchas.md

@@ -165,18 +165,19 @@ Legacy persisted `devspace/*` branches remain valid and closable.
 Uncommitted source-checkout changes are not automatically copied into a newly
 created worktree.
 
-## `close_worktree` refuses to finish
+## `close_workspace` refuses to finalize a managed worktree
 
-Close is deliberately refused when:
+For a managed-worktree-backed workspace, close is deliberately refused when:
 
 - the source checkout is dirty;
 - the source checkout is no longer on the recorded target branch;
 - the managed worktree is on the wrong branch;
 - source and managed histories diverged.
 
-Integration is fast-forward-only. If histories diverge, rebase and verify inside
-the managed worktree, then retry. ForgeRelay does not intentionally leave the
-source checkout in a merge-conflict state.
+A `commitMessage` is also required for managed-worktree-backed close. Integration
+is fast-forward-only. If histories diverge, rebase and verify inside the managed
+worktree, then retry the same `close_workspace` call with the original workspaceId.
+ForgeRelay does not intentionally leave the source checkout in a merge-conflict state.
 
 ## Windows shell commands fail
 
@@ -233,8 +234,8 @@ Per-tool widgets default to:
 FORGERELAY_WIDGETS=full
 ```
 
-Use `FORGERELAY_WIDGETS=changes` for aggregate `show_changes`, or `off` to
-disable UI. Plain MCP clients may ignore MCP App widget metadata.
+Use `FORGERELAY_WIDGETS=changes` for aggregate `review.changes` Capability results,
+or `off` to disable UI. Plain MCP clients may ignore MCP App widget metadata.
 
 If ChatGPT shows `Failed to fetch template`, first verify the server-side template
 chain with:
@@ -244,7 +245,7 @@ npm run build
 npm run debug:accept
 ```
 
-The acceptance runner enables full widgets and checks that the tool advertises a
+The acceptance runner enables review-focused widgets and checks that the Gateway advertises a
 content-hashed `ui://forgerelay/workspace-app-<hash>.html` resource, that
 `resources/read` returns `text/html;profile=mcp-app`, and that the referenced
 JavaScript asset is reachable. ForgeRelay also keeps the legacy

package/docs/security.md

@@ -141,9 +141,9 @@ Do not describe ForgeRelay as a sandboxed coding environment.
 
 Shell execution has a 300-second foreground wait ceiling, not a 300-second
 process lifetime. When `bash` is still running after that window, ForgeRelay
-returns a canonical `processId` and leaves the process alive. `write_stdin` can
-poll, wait, interact, or explicitly interrupt it. The former process `sessionId`
-remains a deprecated compatibility alias during 0.2.x. An asynchronously completed process
+returns a canonical `processId` and leaves the process alive. Regular tool modes
+reuse `bash(action="process")` to poll, wait, write input, resize a PTY, or
+explicitly interrupt that process. An asynchronously completed process
 is reported on a later tool result for the same logical workspace ID, including
 error-result paths, and is never broadcast to another workspace ID. Explicitly
 resuming the same workspace ID in another conversation intentionally transfers
@@ -179,8 +179,9 @@ the source checkout into a merge-conflict state.
 
 ## Native artifact download
 
-When enabled, `download_artifact` accepts only the supported native file value
-provided by the MCP host. It does not accept arbitrary signed URLs, local paths,
+When enabled, the registered `artifact.download` Capability accepts only the supported
+native file value provided by the MCP host through the `capability` Gateway. It does
+not accept arbitrary signed URLs, local paths,
 embedded credentials, or base64 strings as substitutes.
 
 Downloads are streamed, size-limited, created without overwrite, and published

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",

package/scripts/debug/accept.mjs

@@ -37,14 +37,16 @@ assertCurlAvailable();
 await assertDebugPortFree();
 rmSync(acceptanceRoot, { recursive: true, force: true });
 mkdirSync(acceptanceRoot, { recursive: true });
+setupGitProject(checkoutWorkspace);
 
 const { env } = createDebugEnvironment({
   ownerToken,
   stateDir,
   worktreeRoot,
   hookLog,
-  widgets: "full",
+  widgets: "changes",
 });
+env.FORGERELAY_ARTIFACTS = "1";
 const doctor = spawnSync(process.execPath, ["--import", "tsx", "src/cli.ts", "doctor"], {
   cwd: repoRoot,
   env,
@@ -53,7 +55,7 @@ const doctor = spawnSync(process.execPath, ["--import", "tsx", "src/cli.ts", "do
 assert.equal(doctor.status, 0, doctor.stderr);
 assert.match(doctor.stdout, /Public base URL: http:\/\/127\.0\.0\.1:7677/);
 assert.match(doctor.stdout, /Tool mode: full/);
-assert.match(doctor.stdout, /Widgets: full/);
+assert.match(doctor.stdout, /Widgets: changes/);
 assert.match(doctor.stdout, /Trust proxy: off/);
 pass("doctor resolved MCP shape", "public URL + tool/widgets/proxy state");
 
@@ -129,9 +131,17 @@ try {
     params: {},
   }).message.result.tools;
   const toolNames = tools.map((tool) => tool.name);
-  for (const expected of ["open_workspace", "close_workspace", "close_worktree", "read", "write", "edit", "rename", "delete", "grep", "glob", "ls", "bash", "write_stdin", "capability"]) {
-    assert.ok(toolNames.includes(expected), `missing debug tool ${expected}`);
-  }
+  assert.deepEqual(toolNames, [
+    "open_workspace",
+    "capability",
+    "close_workspace",
+    "read",
+    "write",
+    "edit",
+    "rename",
+    "delete",
+    "bash",
+  ]);
   const bashTool = tools.find((tool) => tool.name === "bash");
   assert.match(bashTool?.description ?? "", /local user's authority/);
   assert.doesNotMatch(bashTool?.description ?? "", /may modify ordinary project files/);
@@ -139,18 +149,10 @@ try {
   assert.doesNotMatch(bashTool?.description ?? "", /external device or hardware mutations/);
   assert.doesNotMatch(bashTool?.description ?? "", /Do not use bash to create, move, rename, or delete project files/);
   assert.equal(bashTool?.inputSchema?.properties?.timeout, undefined);
-  assert.match(bashTool?.description ?? "", /waits up to 300 seconds/);
-  assert.match(bashTool?.description ?? "", /write_stdin/);
-  const writeStdinTool = tools.find((tool) => tool.name === "write_stdin");
-  assert.equal(writeStdinTool?.inputSchema?.properties?.yieldTimeMs?.maximum, 300000);
-  assert.match(
-    writeStdinTool?.inputSchema?.properties?.processId?.description ?? "",
-    /Canonical process identifier/,
-  );
-  assert.match(
-    writeStdinTool?.inputSchema?.properties?.sessionId?.description ?? "",
-    /Deprecated alias for processId/,
-  );
+  assert.match(bashTool?.description ?? "", /action=process/);
+  assert.equal(bashTool?.inputSchema?.properties?.yieldTimeMs?.maximum, 300000);
+  assert.match(bashTool?.inputSchema?.properties?.processId?.description ?? "", /action=process/);
+  assert.match(bashTool?.inputSchema?.properties?.interrupt?.description ?? "", /SIGINT/);
   const openWorkspaceTool = tools.find((tool) => tool.name === "open_workspace");
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.workspaceId);
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.newWorkspace);
@@ -158,14 +160,16 @@ try {
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityFingerprint);
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityCatalog);
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityGuides);
-  const templateUri = bashTool?._meta?.ui?.resourceUri;
+  const capabilityTool = tools.find((tool) => tool.name === "capability");
+  assert.deepEqual(capabilityTool?._meta?.["openai/fileParams"], ["file"]);
+  const templateUri = capabilityTool?._meta?.ui?.resourceUri;
   assert.match(
     templateUri ?? "",
     /^ui:\/\/forgerelay\/workspace-app-[0-9a-f]{12}\.html$/,
     JSON.stringify(bashTool ?? {}),
   );
-  assert.deepEqual(bashTool?._meta?.ui?.visibility, ["model", "app"]);
-  assert.equal(bashTool?._meta?.["openai/outputTemplate"], templateUri);
+  assert.deepEqual(capabilityTool?._meta?.ui?.visibility, ["model", "app"]);
+  assert.equal(capabilityTool?._meta?.["openai/outputTemplate"], templateUri);
   pass("MCP tools/list", `${toolNames.length} tools: ${toolNames.join(", ")}`);
 
   const resources = mcpRequest(oauth.accessToken, sessionId, {
@@ -234,15 +238,20 @@ try {
       "worktree.managed",
       "filesystem.rename-move",
       "filesystem.delete",
-      "process.write-stdin",
+      "process.lifecycle",
       "hooks.lifecycle",
       "capability-guides.read",
-      "inspection.search-tools",
+      ...(process.platform === "linux" ? ["artifact.native-download"] : []),
       "ui.mcp-app",
+      "review.changes",
     ],
   });
   const capabilityCatalog = opened.structuredContent.capabilityCatalog;
-  assert.deepEqual(capabilityCatalog.map((entry) => entry.name), ["hooks.check"]);
+  assert.deepEqual(capabilityCatalog.map((entry) => entry.name), [
+    "hooks.check",
+    "review.changes",
+    ...(process.platform === "linux" ? ["artifact.download"] : []),
+  ]);
   assert.equal(capabilityCatalog[0].available, true);
   assert.equal(capabilityCatalog[0].guide.name, "lifecycle-hooks");
   const directCapability = callTool(oauth.accessToken, sessionId, 79, "capability", {
@@ -261,6 +270,18 @@ try {
   assert.equal(describedCapability.isError, undefined);
   assert.equal(describedCapability.structuredContent.capability.guide.name, "lifecycle-hooks");
   assert.equal(describedCapability.structuredContent.capability.inputSchema.type, "object");
+  if (process.platform === "linux") {
+    const describedArtifact = callTool(oauth.accessToken, sessionId, 82, "capability", {
+      workspaceId,
+      name: "artifact.download",
+      action: "describe",
+    });
+    assert.equal(describedArtifact.isError, undefined);
+    assert.deepEqual(describedArtifact.structuredContent.capability.transport, {
+      nativeFileArgument: "file",
+      gatewayParameter: "file",
+    });
+  }
   const unknownCapability = callTool(oauth.accessToken, sessionId, 81, "capability", {
     workspaceId,
     name: "unknown.capability",
@@ -273,6 +294,7 @@ try {
   assert.deepEqual(capabilityGuides.map((guide) => guide.name), [
     "lifecycle-hooks",
     "managed-worktrees",
+    "artifacts-review",
     "host-integration",
     "shell-processes",
   ]);
@@ -298,6 +320,19 @@ try {
   assert.match(read.structuredContent.result, /forgerelay 7677 acceptance/);
   pass("write + read", JSON.stringify(read.structuredContent));
 
+  const reviewed = callTool(oauth.accessToken, sessionId, 83, "capability", {
+    workspaceId,
+    name: "review.changes",
+    action: "run",
+    arguments: {},
+  });
+  assert.equal(reviewed.isError, undefined);
+  assert.match(reviewed.structuredContent.result.result, /Changed 1 file/);
+  assert.equal(reviewed._meta?.tool, "capability");
+  assert.equal(reviewed._meta?.card?.capabilityName, "review.changes");
+  assert.match(reviewed._meta?.card?.payload?.patch ?? "", /acceptance\.txt/);
+  pass("review.changes", "Capability Gateway produced the aggregate review card");
+
   const shell = callTool(oauth.accessToken, sessionId, 6, "bash", {
     workspaceId,
     command: "printf debug-bash-ok",
@@ -306,6 +341,25 @@ try {
   assert.equal(shell.structuredContent.running, false);
   pass("bash", "foreground command completed through ProcessManager");
 
+  const background = callTool(oauth.accessToken, sessionId, 61, "bash", {
+    workspaceId,
+    action: "run",
+    command: `${JSON.stringify(process.execPath)} -e "setTimeout(() => console.log('debug-process-ok'), 100)"`,
+    yieldTimeMs: 0,
+  });
+  assert.equal(background.structuredContent.running, true);
+  assert.equal(typeof background.structuredContent.processId, "number");
+  const polled = callTool(oauth.accessToken, sessionId, 62, "bash", {
+    workspaceId,
+    action: "process",
+    processId: background.structuredContent.processId,
+    yieldTimeMs: 5_000,
+  });
+  assert.equal(polled.structuredContent.running, false);
+  assert.equal(polled.structuredContent.exitCode, 0);
+  assert.match(polled.structuredContent.result, /debug-process-ok/);
+  pass("bash process", "action=run -> processId -> action=process completed through one MCP tool");
+
   const failedEdit = callTool(oauth.accessToken, sessionId, 7, "edit", {
     workspaceId,
     path: "acceptance.txt",
@@ -390,7 +444,7 @@ try {
     path: "feature.txt",
     content: "debug worktree acceptance\n",
   });
-  const closed = callTool(oauth.accessToken, sessionId, 10, "close_worktree", {
+  const closed = callTool(oauth.accessToken, sessionId, 10, "close_workspace", {
     workspaceId: worktreeWorkspaceId,
     commitMessage: "test(debug): verify 7677 worktree lifecycle",
   });
@@ -401,7 +455,7 @@ try {
     "debug worktree acceptance\n",
   );
   pass(
-    "managed worktree close",
+    "managed worktree workspace close",
     `${closed.structuredContent.branch} -> ${closed.structuredContent.targetBranch}`,
   );
 
@@ -734,6 +788,7 @@ function exerciseReleaseTagHooks(accessToken, sessionId) {
   assert.ok(existsSync(join(releaseProject, "release-ci-ran.txt")));
   assert.deepEqual(JSON.parse(readFileSync(join(releaseProject, "release-ci-ran.txt"), "utf8")), {
     tool: "bash",
+    action: "run",
     command: "git push origin v0.2.0",
     workingDirectory: ".",
     originalCommand: "git status --short && git push origin v0.2.0 && echo release-pushed",