@akira-tl/forgerelay 0.2.6 → 0.3.0

package/docs/roadmap.md

@@ -102,7 +102,33 @@ Hooks v1 的目标是给用户和 Agent 一个很小、自动、可组合的生
 - 后台命令句柄以 `processId` / process handle 为 canonical 名称，旧 `sessionId` 在 0.2.x 保留 deprecated alias 兼容窗口；
 - 为 stateless MCP transport 做准备，同时保留旧协议兼容 adapter，避免把 transport 生命周期重新提升成 ForgeRelay 会话模型。
 
-## 0.3 — LSP code intelligence v1
+## 0.3 — MCP loading 与渐进式能力披露
+
+0.3 的目标是缩小 MCP 首次加载时注入给 Agent 的上下文，同时保持工具可调用性、安全边界和 Host 编排权不变。ForgeRelay 不再把所有低频能力说明都塞进 server instructions 或工具 description，而是把模型接口拆成三层：
+
+- `tools/list` 继续暴露真实可调用 primitive，并只携带调用该工具所必需的简洁语义；
+- `open_workspace` 返回紧凑的 server/capability 摘要与版本指纹，帮助 Agent 发现能力，并识别 Host 持有旧 tool schema snapshot 的情况；
+- ForgeRelay-owned capability guide 提供低频能力的完整说明，由 Agent 在任务相关时显式 `read`，而不是首次连接时自动注入。
+
+首版优先复用现有 Skill-style 的 advertised path / `read` 授权机制，而不是新增第二套文档加载协议。Capability guide 与 Skill 的语义所有权保持区分：Skill 描述用户、项目或生态工作流；capability guide 描述 ForgeRelay 自身、与版本绑定的产品能力。
+
+Core Capability Contract 必须始终内联保留至少这些信息：
+
+- `workspaceId` 生命周期与 workspace 复用规则；
+- 常用文件读写改、`rename` 同时承担 move/rename、删除的核心语义；
+- shell 以本地用户权限执行且不是 OS sandbox；
+- `processId` / `write_stdin` 的基本长进程语义；
+- Hook 阻断结果必须对 Agent 可见；
+- 关键 mutation/safety invariant；
+- `close_workspace` 与 `close_worktree` 的区别。
+
+适合按需读取的首批领域包括：生命周期 Hooks、managed worktree 高级流程、subagents、artifact/review 工作流、debug/MCP App、OAuth/deployment，以及 shell/PTTY/process 的低频边界情况。首个实现切片迁移 Hooks 与 managed worktree 高级说明；第二切片继续覆盖 subagents、artifact/review、Host/OAuth/MCP App integration 与 shell/PTTY/process，并把历史 bundled `subagent-delegation` Skill 的默认自动发现迁回 ForgeRelay-owned capability guide。必要安全语义始终保留在 core contract 或真实 tool schema/description 中。
+
+Capability/version fingerprint 必须是轻量、语义化、稳定的摘要，不复制完整 `tools/list`。当 server 报告的能力与 Host 当前暴露的 tool snapshot 明显不一致时，Agent 应能判断为 Host metadata stale，并建议刷新 MCP 或开启新会话，而不是错误断言 ForgeRelay 缺少能力。
+
+0.3 不隐藏 callable tool，不增加隐式 autonomous workflow，也不把 Host Refresh/session 行为归到 ForgeRelay。`rename` 继续作为文件和目录 move/rename 的统一 primitive。
+
+## 0.4 — LSP code intelligence v1
 
 LSP is moderate implementation complexity if ForgeRelay does not become a
 language-server installer.
@@ -110,7 +136,7 @@ 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
+During 0.4 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
@@ -144,7 +170,7 @@ Candidate servers include `typescript-language-server`/tsserver, Pyright,
 `rust-analyzer`, `gopls`, and `clangd`, but ForgeRelay should treat server
 commands/configuration as external dependencies.
 
-## 0.4 — First-class subagent MCP
+## 0.5 — First-class subagent MCP
 
 ForgeRelay already owns provider adapters and resumable local agent sessions.
 The next step is to remove the current `bash -> forgerelay agents ...` indirection

package/docs/security.md

@@ -28,6 +28,17 @@ Filesystem-oriented tools canonicalize existing path segments before access so
 symlinks inside either the workspace or OS temp directory cannot escape to
 arbitrary filesystem locations.
 
+`read` has one narrow additional path class for explicitly advertised documents.
+`open_workspace` may advertise a Skill entry file or a ForgeRelay capability
+Guide outside the normal workspace/temp roots. Only that advertised entry file is
+readable initially; after it is read, files inside that advertised document's
+own directory may be read as supporting material. This does not expand write,
+edit, rename, delete, shell working-directory, or workspace-open roots.
+
+Capability Guides are ForgeRelay-owned, versioned package documentation. Their
+paths are surfaced by the running server rather than guessed by the Agent. This
+keeps progressive disclosure from becoming a general arbitrary-file read escape.
+
 ## Owner-password OAuth
 
 New installations store local configuration in:
@@ -100,13 +111,19 @@ for dynamically crossing such a boundary.
 The Agent-facing shell contract therefore does not ban every command that can
 change files. Commands may modify ordinary project files when that is a natural
 part of the user's requested development task, including package managers,
-generators, formatters, and similar tooling. The contract does prohibit shell
-mutation of security- or privilege-sensitive operating-system files and
-credential material such as `/etc/sudoers`, `/etc/passwd`, `/etc/shadow`, PAM or
-authentication policy, SSH private keys, and equivalent privileged targets.
-Configuration files may be changed through shell only when the user's request
-explicitly calls for that configuration change rather than merely making it a
-convenient implementation detail.
+generators, formatters, and similar tooling. Shell commands may also perform
+external device or hardware mutations when the user's current request explicitly
+asks for the actual device-changing operation. ForgeRelay does not assume a
+particular flashing protocol, transport, device path, or firmware workflow. A
+check, audit, probe, backup, verification, dry-run, or build-only request must not
+be treated as authorization for a later persistent hardware write.
+
+The contract does prohibit shell mutation of security- or privilege-sensitive
+operating-system files and credential material such as `/etc/sudoers`,
+`/etc/passwd`, `/etc/shadow`, PAM or authentication policy, SSH private keys, and
+equivalent privileged targets. Configuration files may be changed through shell
+only when the user's request explicitly calls for that configuration change
+rather than merely making it a convenient implementation detail.
 
 This is an Agent execution policy, not an OS-level sandbox or command parser.
 Operators that need a stronger project-specific runtime gate can use blocking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -24,6 +24,7 @@
     "examples",
     "scripts",
     "skills",
+    "capabilities",
     "README.md",
     "CHANGELOG.md",
     "NOTICE.md"
@@ -34,14 +35,14 @@
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && npm run build:app && tsc -p tsconfig.build.json",
+    "build": "npm run clean && npm run build:app && tsc -p tsconfig.build.json && node scripts/ensure-cli-executable.mjs",
     "build:app": "vite build",
     "dev": "node scripts/debug/serve.mjs",
     "debug:serve": "node scripts/debug/serve.mjs",
     "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/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",
+    "test": "tsx src/config.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.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

@@ -93,6 +93,9 @@ try {
   assert.match(serverInstructions, /Shell commands may modify ordinary project files/);
   assert.match(serverInstructions, /\/etc\/sudoers/);
   assert.match(serverInstructions, /configuration files through shell only when the user's request explicitly calls for that configuration change/);
+  assert.match(serverInstructions, /managed-worktrees capability guide/);
+  assert.ok(serverInstructions.length < 3_000, `server instructions should stay compact, got ${serverInstructions.length} characters`);
+  assert.doesNotMatch(serverInstructions, /fast-forwards the original target branch/);
   assert.doesNotMatch(serverInstructions, /Do not create or modify files with bash/);
   pass(
     "MCP initialize",
@@ -118,8 +121,10 @@ try {
     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.match(bashTool?.description ?? "", /local user's authority/);
+  assert.doesNotMatch(bashTool?.description ?? "", /may modify ordinary project files/);
+  assert.doesNotMatch(bashTool?.description ?? "", /\/etc\/sudoers/);
+  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/);
@@ -138,6 +143,8 @@ try {
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.workspaceId);
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.newWorkspace);
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.staleWorkspaces);
+  assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityFingerprint);
+  assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityGuides);
   const templateUri = bashTool?._meta?.ui?.resourceUri;
   assert.match(
     templateUri ?? "",
@@ -203,7 +210,35 @@ try {
   assert.match(workspaceId, /^ws_/);
   assert.equal(opened.structuredContent.root, checkoutWorkspace);
   assert.equal(opened.structuredContent.mode, "checkout");
-  pass("open_workspace", `${workspaceId} -> ${opened.structuredContent.root}`);
+  assert.deepEqual(opened.structuredContent.capabilityFingerprint, {
+    version: packageJson.version,
+    toolMode: "full",
+    capabilities: [
+      "workspace.close",
+      "worktree.managed",
+      "filesystem.rename-move",
+      "filesystem.delete",
+      "process.write-stdin",
+      "hooks.lifecycle",
+      "capability-guides.read",
+      "inspection.search-tools",
+      "ui.mcp-app",
+    ],
+  });
+  const capabilityGuides = opened.structuredContent.capabilityGuides;
+  assert.deepEqual(capabilityGuides.map((guide) => guide.name), [
+    "lifecycle-hooks",
+    "managed-worktrees",
+    "host-integration",
+    "shell-processes",
+  ]);
+  const hooksGuide = callTool(oauth.accessToken, sessionId, 78, "read", {
+    workspaceId,
+    path: capabilityGuides[0].path,
+  });
+  assert.match(hooksGuide.structuredContent.result, /BeforeTool/);
+  assert.match(hooksGuide.structuredContent.result, /BeforeWorktreeClose/);
+  pass("open_workspace", `${workspaceId} -> fingerprint + ${capabilityGuides.length} capability guides`);
 
   const written = callTool(oauth.accessToken, sessionId, 4, "write", {
     workspaceId,

package/scripts/ensure-cli-executable.mjs

@@ -0,0 +1,12 @@
+import { chmodSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+if (process.platform !== "win32") {
+  const cliPath = fileURLToPath(new URL("../dist/cli.js", import.meta.url));
+  const currentMode = statSync(cliPath).mode;
+  chmodSync(cliPath, currentMode | 0o111);
+
+  if ((statSync(cliPath).mode & 0o111) === 0) {
+    throw new Error(`ForgeRelay CLI is not executable after build: ${cliPath}`);
+  }
+}