@akira-tl/forgerelay 0.2.3 → 0.2.5

package/docs/roadmap.md

@@ -82,6 +82,26 @@ Hooks v1 的目标是给用户和 Agent 一个很小、自动、可组合的生
 
 0.2 不引入审批 UI、HTTP/prompt/agent handler、Git 字符串解析器或插件注册表。只有出现真实需求时再扩展 handler 类型。
 
+### 0.2.5 — MCP App template reliability
+
+0.2.5 收敛 ChatGPT/MCP App 模板身份与排障链路：
+
+- 当前 UI resource URI 由实际构建出的 JavaScript/CSS 内容哈希生成，而不是仅依赖 npm 版本；
+- `ui://forgerelay/workspace-app.html` 继续作为 legacy pointer；
+- 历史 `workspace-app-*.html` URI 通过兼容 resource template 继续读取当前模板，避免旧 metadata snapshot 直接变成 missing resource；
+- debug 日志区分 current / legacy / historical template read，并保留 asset request trace；
+- 7677 acceptance 覆盖 tool metadata、resource list/template list、三类 template read 和静态 bundle HTTP fetch。
+
+### 0.2.6 — identity and transport terminology
+
+0.2.6 整理 ForgeRelay 中多个 `session` 含义，不改变 workspace-first 架构：
+
+- `workspaceId` 是唯一持久的逻辑工作身份，跨请求和 transport 重连保持连续；
+- `requestId` 只追踪单次 HTTP/JSON-RPC 请求，不持久化；
+- MCP 协议层 session 在内部和 debug 输出中明确称为 `transportSessionId`，业务状态不得依赖它；
+- 后台命令句柄逐步迁移为 `processId` / process handle；若公开 schema 改名需要兼容窗口，则在明确的版本边界完成；
+- 为 stateless MCP transport 做准备，同时保留旧协议兼容 adapter，避免把 transport 生命周期重新提升成 ForgeRelay 会话模型。
+
 ## 0.3 — LSP code intelligence v1
 
 LSP is moderate implementation complexity if ForgeRelay does not become a
@@ -90,6 +110,12 @@ language-server installer.
 The first version should launch only language servers already available on the
 user's machine or explicitly configured by the user/project.
 
+During 0.3 development, MCP App UI hardening can land alongside the LSP work when
+it does not distort the code-intelligence scope. In particular, evaluate a more
+self-contained template/bootstrap bundle, reduce avoidable external chunk fetches,
+and keep the current content-hash/compatibility-resource contract intact. This is
+reliability work, not a requirement to move application state into the UI.
+
 Initial operations:
 
 - diagnostics;

package/docs/security.md

@@ -122,6 +122,16 @@ The security model is therefore based on:
 
 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 process `sessionId` and leaves the process alive. `write_stdin` can poll,
+wait, interact, or explicitly interrupt it. 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
+that completion scope as well. Hook handlers keep their separate bounded timeout
+policy because they are lifecycle gates rather than user-command execution.
+
 ## Lifecycle hooks
 
 Hook command 是本地代码执行，使用与 ForgeRelay 相同的操作系统用户权限并继承进程环境。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -41,7 +41,7 @@
     "debug:accept": "node scripts/debug/accept.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/logger.test.ts && tsx src/hooks.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/logger.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/debug/accept.mjs

@@ -38,7 +38,13 @@ await assertDebugPortFree();
 rmSync(acceptanceRoot, { recursive: true, force: true });
 mkdirSync(acceptanceRoot, { recursive: true });
 
-const { env } = createDebugEnvironment({ ownerToken, stateDir, worktreeRoot, hookLog });
+const { env } = createDebugEnvironment({
+  ownerToken,
+  stateDir,
+  worktreeRoot,
+  hookLog,
+  widgets: "full",
+});
 const server = spawn(process.execPath, ["--import", "tsx", "src/cli.ts", "serve"], {
   cwd: repoRoot,
   env,
@@ -108,15 +114,80 @@ try {
     params: {},
   }).message.result.tools;
   const toolNames = tools.map((tool) => tool.name);
-  for (const expected of ["open_workspace", "close_worktree", "read", "write", "edit", "rename", "delete", "grep", "glob", "ls", "bash"]) {
+  for (const expected of ["open_workspace", "close_workspace", "close_worktree", "read", "write", "edit", "rename", "delete", "grep", "glob", "ls", "bash", "write_stdin"]) {
     assert.ok(toolNames.includes(expected), `missing debug tool ${expected}`);
   }
   const bashTool = tools.find((tool) => tool.name === "bash");
   assert.match(bashTool?.description ?? "", /may modify ordinary project files/);
   assert.match(bashTool?.description ?? "", /\/etc\/sudoers/);
   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);
+  const openWorkspaceTool = tools.find((tool) => tool.name === "open_workspace");
+  assert.ok(openWorkspaceTool?.inputSchema?.properties?.workspaceId);
+  assert.ok(openWorkspaceTool?.inputSchema?.properties?.newWorkspace);
+  assert.ok(openWorkspaceTool?.outputSchema?.properties?.staleWorkspaces);
+  const templateUri = bashTool?._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);
   pass("MCP tools/list", `${toolNames.length} tools: ${toolNames.join(", ")}`);
 
+  const resources = mcpRequest(oauth.accessToken, sessionId, {
+    jsonrpc: "2.0",
+    id: 21,
+    method: "resources/list",
+    params: {},
+  }).message.result.resources;
+  assert.ok(resources.some((resource) => resource.uri === templateUri));
+  assert.ok(resources.some((resource) => resource.uri === "ui://forgerelay/workspace-app.html"));
+
+  const resourceTemplates = mcpRequest(oauth.accessToken, sessionId, {
+    jsonrpc: "2.0",
+    id: 22,
+    method: "resources/templates/list",
+    params: {},
+  }).message.result.resourceTemplates;
+  assert.ok(resourceTemplates.some(
+    (resourceTemplate) => resourceTemplate.uriTemplate === "ui://forgerelay/workspace-app-{revision}.html",
+  ));
+
+  const readTemplate = (id, uri) => mcpRequest(oauth.accessToken, sessionId, {
+    jsonrpc: "2.0",
+    id,
+    method: "resources/read",
+    params: { uri },
+  }).message.result.contents[0];
+
+  const template = readTemplate(23, templateUri);
+  assert.equal(template.uri, templateUri);
+  assert.equal(template.mimeType, "text/html;profile=mcp-app");
+  assert.match(template.text ?? "", /<script type="module" crossorigin src="[^"]+\/mcp-app-assets\//);
+  assert.ok(template._meta?.ui?.csp?.resourceDomains?.includes(debugBaseUrl));
+  const scriptUrl = template.text?.match(/<script type="module" crossorigin src="([^"]+)"/)?.[1];
+  assert.ok(scriptUrl);
+  const scriptAsset = curlRequest({ method: "GET", url: scriptUrl });
+  assert.equal(scriptAsset.status, 200, scriptAsset.body);
+
+  const legacyTemplate = readTemplate(24, "ui://forgerelay/workspace-app.html");
+  assert.equal(legacyTemplate.uri, "ui://forgerelay/workspace-app.html");
+  assert.equal(legacyTemplate.mimeType, "text/html;profile=mcp-app");
+  assert.equal(legacyTemplate.text, template.text);
+
+  const historicalUri = "ui://forgerelay/workspace-app-0.2.4.html";
+  const historicalTemplate = readTemplate(25, historicalUri);
+  assert.equal(historicalTemplate.uri, historicalUri);
+  assert.equal(historicalTemplate.mimeType, "text/html;profile=mcp-app");
+  assert.equal(historicalTemplate.text, template.text);
+  pass("MCP app template", `${templateUri} + legacy/history compatibility -> ${scriptUrl}`);
+
   const opened = callTool(oauth.accessToken, sessionId, 3, "open_workspace", {
     path: checkoutWorkspace,
   });
@@ -145,7 +216,8 @@ try {
     command: "printf debug-bash-ok",
   });
   assert.match(shell.structuredContent.result, /debug-bash-ok/);
-  pass("bash", "debug-bash-ok");
+  assert.equal(shell.structuredContent.running, false);
+  pass("bash", "foreground command completed through ProcessSessionManager");
 
   const failedEdit = callTool(oauth.accessToken, sessionId, 7, "edit", {
     workspaceId,
@@ -354,7 +426,13 @@ function initializeRequest(id) {
     method: "initialize",
     params: {
       protocolVersion: "2025-06-18",
-      capabilities: {},
+      capabilities: {
+        extensions: {
+          "io.modelcontextprotocol/ui": {
+            mimeTypes: ["text/html;profile=mcp-app"],
+          },
+        },
+      },
       clientInfo: { name: "forgerelay-debug-acceptance", version: "1.0.0" },
     },
   };

package/scripts/debug/runtime.mjs

@@ -20,6 +20,7 @@ export function createDebugEnvironment({
   stateDir = resolve(debugRoot, "state"),
   worktreeRoot = resolve(debugRoot, "worktrees"),
   hookLog = debugHookLog,
+  widgets = process.env.FORGERELAY_DEBUG_WIDGETS ?? "off",
 } = {}) {
   const token = ownerToken ?? process.env.FORGERELAY_DEBUG_OWNER_TOKEN ?? createDebugOwnerToken();
   mkdirSync(debugRoot, { recursive: true });
@@ -37,7 +38,7 @@ export function createDebugEnvironment({
       FORGERELAY_WORKTREE_ROOT: worktreeRoot,
       FORGERELAY_OAUTH_OWNER_TOKEN: token,
       FORGERELAY_TOOL_MODE: "full",
-      FORGERELAY_WIDGETS: "off",
+      FORGERELAY_WIDGETS: widgets,
       FORGERELAY_LOG_LEVEL: process.env.FORGERELAY_LOG_LEVEL ?? "info",
       FORGERELAY_LOG_FORMAT: process.env.FORGERELAY_LOG_FORMAT ?? "pretty",
       FORGERELAY_DEBUG_HOOK_RECORDER: debugHookRecorder,