@akira-tl/forgerelay 0.3.4 → 0.3.6

package/docs/gotchas.md

@@ -234,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:
@@ -245,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/roadmap.md

@@ -170,7 +170,18 @@ capability
 - 删除已经完成迁移的 dedicated low-frequency tool aliases，确保新增 Capability 不再扩大常驻 tool count；
 - 简化 fingerprint，使其用于版本/运行时能力摘要与 stale-Host 诊断，而不是重新枚举 tool implementation；
 - 对 `open_workspace → catalog → capability describe/read/run`、managed worktree close、长进程 interaction、review/artifact capability、MCP App 与 stale-schema 情况做 7677 acceptance 和新 Host 会话验收；
-- 0.3.5 通过后，0.3 的 MCP progressive-disclosure 主题视为完成，0.4 回到原定 LSP code intelligence v1。
+- 0.3.5 完成 canonical MCP surface 与 fresh-Host 主验收后，0.3 的 progressive-disclosure 主体设计视为稳定；后续 0.3.x 只接收验收暴露出的兼容性或 lifecycle 补丁，0.4 仍回到原定 LSP code intelligence v1。
+
+### 0.3.6 — Workspace bootstrap 与 inventory 补丁
+
+0.3.6 处理 0.3.5 fresh-Host 验收后暴露的 Workspace 上下文与 logical-workspace 管理问题，不增加新的常驻 MCP tool，也不改变 0.4 的 LSP 主路线：
+
+- `open_workspace` 的 bootstrap 去重从 logical `workspaceId` 身份提升为 conversation scope + canonical workspace target + context fingerprint；同一 conversation 切换到同一物理 checkout/worktree 的其他 logical workspace 时，只要 AGENTS、Skills、Capability guide/profile 等相关上下文没有变化，就不重复注入完整 bootstrap；
+- `open_workspace` 提供 `context="auto" | "full" | "none"`。`auto` 默认只在当前 fingerprint 尚未交付或已变化时返回完整上下文，`full` 强制刷新，`none` 只取得 workspace handle/metadata 且不会把该 fingerprint 标记为已交付；
+- context-delivery 状态与 conversation 当前绑定的 logical workspace 分离持久化，因此关闭或切换 logical handle 不会让 Agent 在同一 conversation 中忘记已经收到的项目上下文；delivery 状态继续服从有限生命周期清理，而不是永久缓存；
+- `open_workspace(action="list")` 成为按需 logical-workspace inventory 入口，不增加 `list_workspaces`/`workspace.list` 第十个 Core tool；普通开发仍直接使用默认 `action="open"`，只有续接旧任务、选择 workspace 或整理状态时才读取 inventory；
+- inventory 区分持久化 `status` 与派生 `state`：`status="active"` 表示尚未显式关闭，`state` 再区分 active、stale、invalid 与 closed；missing root 或外部删除的 managed worktree 可以保持可诊断的 active record，同时显示为 invalid；
+- inventory 查看本身不刷新 workspace `lastUsedAt`，支持过滤与分页，并继续让现有 `close_workspace` 承担用户确认后的实际清理/finalize lifecycle。
 
 必要安全语义始终留在 Core tool interface、Capability contract 或自动 Hook report 中；渐进式披露不能成为隐藏权限、隐式 autonomous workflow 或绕过 allowed roots/auth 的机制。`rename` 继续作为文件和目录 move/rename 的统一 primitive。
 

package/docs/security.md

@@ -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.4",
+  "version": "0.3.6",
   "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,11 +131,17 @@ try {
     params: {},
   }).message.result.tools;
   const toolNames = tools.map((tool) => tool.name);
-  for (const expected of ["open_workspace", "close_workspace", "read", "write", "edit", "rename", "delete", "grep", "glob", "ls", "bash", "capability"]) {
-    assert.ok(toolNames.includes(expected), `missing debug tool ${expected}`);
-  }
-  assert.equal(toolNames.includes("close_worktree"), false);
-  assert.equal(toolNames.includes("write_stdin"), false);
+  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/);
@@ -152,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, {
@@ -213,13 +223,16 @@ try {
   assert.equal(historicalTemplate.text, template.text);
   pass("MCP app template", `${templateUri} + legacy/history compatibility -> ${scriptUrl}`);
 
+  const workspaceConversationMeta = { "openai/session": "acceptance-workspace" };
   const opened = callTool(oauth.accessToken, sessionId, 3, "open_workspace", {
     path: checkoutWorkspace,
-  });
+  }, workspaceConversationMeta);
   const workspaceId = opened.structuredContent.workspaceId;
   assert.match(workspaceId, /^ws_/);
+  assert.equal(opened.structuredContent.action, "open");
   assert.equal(opened.structuredContent.root, checkoutWorkspace);
   assert.equal(opened.structuredContent.mode, "checkout");
+  assert.equal(typeof opened.structuredContent.contextFingerprint, "string");
   assert.deepEqual(opened.structuredContent.capabilityFingerprint, {
     version: packageJson.version,
     toolMode: "full",
@@ -231,14 +244,69 @@ try {
       "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 freshLogical = callTool(oauth.accessToken, sessionId, 84, "open_workspace", {
+    path: checkoutWorkspace,
+    newWorkspace: true,
+  }, workspaceConversationMeta);
+  const freshLogicalId = freshLogical.structuredContent.workspaceId;
+  assert.notEqual(freshLogicalId, workspaceId);
+  assert.equal(freshLogical.structuredContent.action, "open");
+  assert.equal(
+    freshLogical.structuredContent.contextFingerprint,
+    opened.structuredContent.contextFingerprint,
+  );
+  assert.equal(freshLogical.structuredContent.agentsFiles, undefined);
+  assert.equal(freshLogical.structuredContent.capabilityGuides, undefined);
+
+  const workspaceInventory = callTool(oauth.accessToken, sessionId, 85, "open_workspace", {
+    action: "list",
+    root: checkoutWorkspace,
+  }, workspaceConversationMeta);
+  assert.equal(workspaceInventory.structuredContent.action, "list");
+  assert.equal(workspaceInventory.structuredContent.summary.matching, 2);
+  const inventoryEntries = workspaceInventory.structuredContent.workspaces;
+  assert.equal(inventoryEntries.length, 2);
+  assert.equal(
+    inventoryEntries.find((entry) => entry.workspaceId === freshLogicalId)?.current,
+    true,
+  );
+  assert.equal(
+    inventoryEntries.find((entry) => entry.workspaceId === workspaceId)?.current,
+    false,
+  );
+
+  const closedFreshLogical = callTool(oauth.accessToken, sessionId, 86, "close_workspace", {
+    workspaceId: freshLogicalId,
+  });
+  assert.equal(closedFreshLogical.isError, undefined);
+  const resumedOriginal = callTool(oauth.accessToken, sessionId, 87, "open_workspace", {
+    workspaceId,
+  }, workspaceConversationMeta);
+  assert.equal(resumedOriginal.structuredContent.workspaceId, workspaceId);
+  assert.equal(resumedOriginal.structuredContent.agentsFiles, undefined);
+  assert.equal(
+    resumedOriginal.structuredContent.contextFingerprint,
+    opened.structuredContent.contextFingerprint,
+  );
+  pass(
+    "workspace context + inventory",
+    `${workspaceId} -> ${freshLogicalId} -> list -> close -> resume without bootstrap replay`,
+  );
+
   const directCapability = callTool(oauth.accessToken, sessionId, 79, "capability", {
     workspaceId,
     name: "hooks.check",
@@ -255,6 +323,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",
@@ -267,6 +347,7 @@ try {
   assert.deepEqual(capabilityGuides.map((guide) => guide.name), [
     "lifecycle-hooks",
     "managed-worktrees",
+    "artifacts-review",
     "host-integration",
     "shell-processes",
   ]);
@@ -292,6 +373,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",
@@ -549,12 +643,16 @@ function mcpRequest(accessToken, sessionId, request) {
   return { response, message: parseMcpMessage(response.body, request.id) };
 }
 
-function callTool(accessToken, sessionId, id, name, args) {
+function callTool(accessToken, sessionId, id, name, args, meta) {
   const message = mcpRequest(accessToken, sessionId, {
     jsonrpc: "2.0",
     id,
     method: "tools/call",
-    params: { name, arguments: args },
+    params: {
+      name,
+      arguments: args,
+      ...(meta ? { _meta: meta } : {}),
+    },
   }).message;
   assert.equal(message.id, id);
   assert.ok(message.result, `tool ${name} did not return a result`);