@akira-tl/forgerelay 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-08-10
+
+### Added
+
+- Added `review.changes` and `artifact.download` as registered Capability Gateway actions. Review preserves the existing Git-backed checkpoint and diff-card metadata; native artifact ingress preserves Host-native file transport, workspace-relative no-overwrite publication, size limits, and `AfterFileChange` lifecycle reporting.
+
+### Changed
+
+- The Capability catalog now advertises only capabilities that are actually available in the current runtime. Explicit calls to known-but-disabled capabilities still return stable `capability_unavailable` diagnostics.
+- `show_changes` and `download_artifact` remain compatibility aliases for the 0.3.3 migration window, but the artifacts/review guide now treats the Capability Gateway as the canonical Agent workflow.
+
 ## [0.3.2] - 2026-08-10
 
 ### Added

package/capabilities/artifacts-review/GUIDE.md

@@ -4,15 +4,17 @@
 
 ## Native artifact transfer
 
-Native artifact download 默认关闭。只有 `tools/list` 实际暴露 `download_artifact` 时才调用它；当前安全发布实现主要面向 Linux。
+Native artifact download 默认关闭，且当前安全发布实现主要面向 Linux。只有 `open_workspace` 的 Capability catalog 广告 `artifact.download` 时才执行它；不熟悉 contract 时先 `capability(action="describe")`，其中会明确 native file 通过 Gateway 顶层 `file` transport slot 传入。
 
 典型流程：
 
 1. 先用 `open_workspace` 打开目标项目；
-2. 调用 `download_artifact`，传入 Host 原样提供的 native `file` 值、现有 `workspaceId` 和 workspace-relative `path`；
+2. 调用 `capability`，`name="artifact.download"`、`action="run"`，把 Host 原样提供的 native `file` 值放在 Gateway 顶层 `file`，并在 `arguments.path` 传 workspace-relative 目标路径；
 3. 成功后使用返回的 normalized relative path 配合普通 `read` / `rename` / `delete` / shell 等工具继续处理。
 
-`download_artifact` 会创建缺失的父目录，但拒绝覆盖已有目标。不要把 native file 值改造成：
+0.3.3 仍保留 `download_artifact` 作为迁移期 compatibility alias，但新的 Agent workflow 不应把它视为长期 public surface。
+
+`artifact.download` 会创建缺失的父目录，但拒绝覆盖已有目标。不要把 native file 值改造成：
 
 - 任意 URL 字符串；
 - 猜测的本地主机路径；
@@ -28,15 +30,15 @@ Native artifact download 默认关闭。只有 `tools/list` 实际暴露 `downlo
 `FORGERELAY_WIDGETS`：
 
 - `full`：默认，为常用 workspace/file/edit/shell tools 附加 MCP App UI；
-- `changes`：聚焦 `open_workspace` + `show_changes` 聚合 review；
+- `changes`：聚焦 `open_workspace` + `review.changes` 聚合 review；
 - `off`：不附加 widget UI。
 
 Plain MCP Host 可以忽略这些 UI metadata；不要把 UI 是否显示当成文件操作是否成功的判据。
 
-当 `tools/list` 暴露 `show_changes` 时，它自己的 tool description 是调用契约：本轮成功修改文件后，在最后一个相关 file mutation 之后、final response 之前调用一次，让用户看到聚合 diff；不要每改一个文件就调用一次。
+当 Capability catalog 广告 `review.changes` 时，本轮成功修改文件后，在最后一个相关 file mutation 之后、final response 之前通过 `capability` 调用一次，让用户看到聚合 diff；不要每改一个文件就调用一次。0.3.3 仍保留 `show_changes` compatibility alias，但它和 `review.changes` 共用同一套 checkpoint，不是两套 review 状态。
 
-`show_changes` 使用 Git-backed review checkpoint。它按 workspace 跟踪 open/baseline 状态，展示自上次 review checkpoint 以来的 coherent diff，并在成功 review 后推进 baseline。当前版本要求可用的 Git workspace；checkpoint 缺失或 root 不匹配时会明确失败或使用受控 fallback，而不是凭空重建历史。
+`review.changes` 使用 Git-backed review checkpoint。它按 workspace 跟踪 open/baseline 状态，展示自上次 review checkpoint 以来的 coherent diff，并在成功 review 后推进 baseline。当前版本要求可用的 Git workspace；checkpoint 缺失或 root 不匹配时会明确失败或使用受控 fallback，而不是凭空重建历史。
 
 ## Capability ownership
 
-Artifact transfer 和 change review 都属于 ForgeRelay capability，而不是 Agent 自己的文件搬运协议。真实可调用工具仍以 `tools/list` 为准；本指南只提供低频流程和边界，不代表隐藏工具。
+Artifact transfer 和 change review 都属于 ForgeRelay registered capability，而不是 Agent 自己的文件搬运协议。`tools/list` 只负责暴露稳定 Gateway 与当前兼容 aliases；真正可用的低频能力以当前 workspace 的 Capability catalog 为准。本指南提供流程和边界，不额外创造隐藏执行入口。

package/dist/artifact-tools.js

@@ -32,8 +32,9 @@ const openAIFileReferenceInputSchema = z.strictObject({
 export function isArtifactDownloadSupportedPlatform(platform = process.platform) {
     return ARTIFACT_DOWNLOAD_PLATFORMS.has(platform);
 }
-export function registerArtifactTools(server, { config, workspaces, hooks, incomingArtifactAdapters = [], }) {
-    const incomingRegistry = new IncomingArtifactAdapterRegistry(incomingArtifactAdapters);
+export function registerArtifactTools(server, { config, workspaces, hooks, incomingArtifactAdapters = [], incomingArtifactRegistry, }) {
+    const incomingRegistry = incomingArtifactRegistry
+        ?? new IncomingArtifactAdapterRegistry(incomingArtifactAdapters);
     registerAppTool(server, "download_artifact", {
         title: "Download attached or generated file",
         description: "Stream one MCP-host-provided native file to a requested relative path inside an already-open workspace. Existing destinations, arbitrary URLs, absolute paths, traversal, symlinked parents, local source paths, and malformed file objects are rejected.",

package/dist/capability-registry.js

@@ -31,7 +31,7 @@ export class CapabilityRegistry {
                     readBeforeFirstUse: definition.readGuideBeforeFirstUse,
                 },
             };
-        });
+        }).filter((entry) => entry.available);
     }
     describe(name, context) {
         const definition = this.requireDefinition(name);
@@ -48,15 +48,29 @@ export class CapabilityRegistry {
                 whenToRead: guide.whenToRead,
             },
             inputSchema: z.toJSONSchema(definition.inputSchema, { target: "draft-7" }),
+            ...(definition.nativeFileArgument
+                ? {
+                    transport: {
+                        nativeFileArgument: definition.nativeFileArgument,
+                        gatewayParameter: "file",
+                    },
+                }
+                : {}),
         };
     }
-    async run(name, argumentsValue, context) {
+    async run(name, argumentsValue, context, options = {}) {
         const definition = this.requireDefinition(name);
         const catalogEntry = this.catalogEntry(definition, context);
         if (!catalogEntry.available) {
             throw new CapabilityError("capability_unavailable", `Capability ${name} is unavailable${catalogEntry.unavailableReason ? `: ${catalogEntry.unavailableReason}` : "."}`);
         }
-        const parsed = definition.inputSchema.safeParse(argumentsValue ?? {});
+        if (options.nativeFile !== undefined && !definition.nativeFileArgument) {
+            throw new CapabilityError("invalid_arguments", `Capability ${name} does not accept a Host-native file value.`);
+        }
+        const input = definition.nativeFileArgument && options.nativeFile !== undefined
+            ? { ...(isRecord(argumentsValue) ? argumentsValue : {}), [definition.nativeFileArgument]: options.nativeFile }
+            : argumentsValue ?? {};
+        const parsed = definition.inputSchema.safeParse(input);
         if (!parsed.success) {
             const details = parsed.error.issues
                 .map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "arguments"}: ${issue.message}`)
@@ -110,9 +124,53 @@ export function createCapabilityRegistry(dependencies) {
             inputSchema: hooksCheckInput,
             availability: () => ({ available: true }),
             run: async (_input, context) => ({
-                ok: true,
-                ...await dependencies.inspectHooks(context.workspaceRoot),
+                value: {
+                    ok: true,
+                    ...await dependencies.inspectHooks(context.workspaceRoot),
+                },
             }),
         },
+        ...(dependencies.reviewChanges
+            ? [{
+                    name: "review.changes",
+                    description: "Review accumulated workspace changes from the Git-backed review checkpoint.",
+                    guideName: "artifacts-review",
+                    readGuideBeforeFirstUse: true,
+                    inputSchema: z.object({}).strict(),
+                    availability: () => ({
+                        available: dependencies.reviewChanges?.available ?? false,
+                        reason: dependencies.reviewChanges?.unavailableReason,
+                    }),
+                    run: async (_input, context) => dependencies.reviewChanges.run(context),
+                }]
+            : []),
+        ...(dependencies.downloadArtifact
+            ? [{
+                    name: "artifact.download",
+                    description: "Save one Host-native file into a workspace-relative destination without overwriting.",
+                    guideName: "artifacts-review",
+                    readGuideBeforeFirstUse: true,
+                    inputSchema: z.object({
+                        file: z.strictObject({
+                            download_url: z.string(),
+                            file_id: z.string(),
+                            mime_type: z.string().nullable().optional(),
+                            file_name: z.string().nullable().optional(),
+                            name: z.string().nullable().optional(),
+                            size: z.number().int().nonnegative().nullable().optional(),
+                        }),
+                        path: z.string().min(1),
+                    }).strict(),
+                    nativeFileArgument: "file",
+                    availability: () => ({
+                        available: dependencies.downloadArtifact?.available ?? false,
+                        reason: dependencies.downloadArtifact?.unavailableReason,
+                    }),
+                    run: async (input, context) => dependencies.downloadArtifact.run(input, context),
+                }]
+            : []),
     ]);
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/server.js

@@ -17,12 +17,13 @@ import { applyPatch } from "./apply-patch.js";
 import { buildCapabilityFingerprint } from "./capabilities.js";
 import { CapabilityError, createCapabilityRegistry, } from "./capability-registry.js";
 import { deletePath, renamePath } from "./file-mutations.js";
-import { isArtifactDownloadSupportedPlatform, registerArtifactTools, } from "./artifact-tools.js";
+import { downloadIncomingArtifact, isArtifactDownloadSupportedPlatform, registerArtifactTools, } from "./artifact-tools.js";
+import { ArtifactError } from "./artifact-error.js";
 import { loadConfig } from "./config.js";
 import { attachHookReports, HookRunner, runToolWithHooks } from "./hooks.js";
 import { checkHookConfiguration } from "./hook-cli.js";
 import { buildServerInstructions, buildShellMutationPolicy, buildToolDescriptions, toolNames, } from "./mcp/server-instructions.js";
-import { createOpenAIIncomingArtifactAdapter, } from "./incoming-artifacts.js";
+import { createOpenAIIncomingArtifactAdapter, IncomingArtifactAdapterRegistry, } from "./incoming-artifacts.js";
 import { logEvent, requestIp, requestPath, commandPreview, transportSessionIdPrefix, workspaceLogLabel, } from "./logger.js";
 import { editFileTool, findFilesTool, grepFilesTool, listDirectoryTool, readFileTool, writeFileTool, } from "./pi-tools.js";
 import { SingleUserOAuthProvider } from "./oauth-provider.js";
@@ -66,7 +67,7 @@ function shouldAttachWidget(mode, kind) {
         case "off":
             return false;
         case "changes":
-            return kind === "workspace" || kind === "show_changes";
+            return kind === "workspace" || kind === "show_changes" || kind === "capability";
         case "full":
             return true;
     }
@@ -522,6 +523,13 @@ function capabilityContextFor(workspace) {
         })),
     };
 }
+async function reviewWorkspaceChanges(reviewCheckpoints, workspace) {
+    return reviewCheckpoints.reviewChanges({
+        workspaceId: workspace.id,
+        root: workspace.root,
+        markReviewed: true,
+    });
+}
 function toolResultIsError(result) {
     return typeof result === "object" && result !== null && result.isError === true;
 }
@@ -679,8 +687,66 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
 export function createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters) {
     const toolDescriptions = buildToolDescriptions(config);
     const hooks = new HookRunner(config.hooks, config.logging, process.env, (workspaceId, result) => attachCompletedProcessNotices(processSessions, workspaceId, result));
+    const incomingArtifactRegistry = new IncomingArtifactAdapterRegistry(incomingArtifactAdapters);
+    const artifactDownloadAvailable = config.artifactsEnabled && isArtifactDownloadSupportedPlatform();
+    const reviewChangesAvailable = config.widgets === "changes";
     const capabilityRegistry = createCapabilityRegistry({
         inspectHooks: (workspaceRoot) => checkHookConfiguration(workspaceRoot, config.hooks),
+        reviewChanges: {
+            available: reviewChangesAvailable,
+            unavailableReason: reviewChangesAvailable
+                ? undefined
+                : "Aggregate change review is disabled; start ForgeRelay with widgets=changes.",
+            run: async (context) => {
+                const review = await reviewWorkspaceChanges(reviewCheckpoints, {
+                    id: context.workspaceId,
+                    root: context.workspaceRoot,
+                });
+                return {
+                    value: {
+                        result: review.result,
+                        summary: review.summary,
+                        files: review.files,
+                    },
+                    card: {
+                        tool: "show_changes",
+                        summary: review.summary,
+                        files: review.files,
+                        payload: { patch: review.patch },
+                    },
+                };
+            },
+        },
+        downloadArtifact: {
+            available: artifactDownloadAvailable,
+            unavailableReason: !config.artifactsEnabled
+                ? "Native artifact ingress is disabled."
+                : !isArtifactDownloadSupportedPlatform()
+                    ? "Native artifact ingress is unsupported on this platform."
+                    : undefined,
+            run: async (input, context) => {
+                try {
+                    const downloaded = await downloadIncomingArtifact({
+                        registry: incomingArtifactRegistry,
+                        workspaceId: context.workspaceId,
+                        workspaceRoot: context.workspaceRoot,
+                        maxFileBytes: config.artifactMaxFileBytes,
+                        file: input.file,
+                        path: input.path,
+                    });
+                    return {
+                        value: { path: downloaded.path },
+                        changedPaths: [downloaded.path],
+                    };
+                }
+                catch (error) {
+                    if (error instanceof ArtifactError) {
+                        throw new CapabilityError(`artifact.${error.code}`, error.message);
+                    }
+                    throw error;
+                }
+            },
+        },
     });
     const server = new McpServer({
         name: "forgerelay",
@@ -987,7 +1053,11 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             arguments: z
                 .record(z.string(), z.unknown())
                 .optional()
-                .describe("Capability-specific arguments. Omit for describe and for capabilities with no arguments."),
+                .describe("Capability-specific JSON arguments. Omit for describe and for capabilities with no arguments."),
+            file: z
+                .unknown()
+                .optional()
+                .describe("Host-native file value. Only capabilities whose describe result advertises native-file transport may consume it."),
         },
         outputSchema: {
             name: z.string(),
@@ -996,20 +1066,25 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             result: z.unknown().optional(),
             error: capabilityErrorOutputSchema.optional(),
         },
-        _meta: {},
+        _meta: {
+            ...toolWidgetDescriptorMeta(config, "capability")._meta,
+            "openai/fileParams": ["file"],
+        },
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
-            openWorldHint: false,
+            openWorldHint: true,
         },
-    }, async ({ workspaceId, name, action, arguments: capabilityArguments }) => {
+    }, async ({ workspaceId, name, action, arguments: capabilityArguments, file }) => {
         const workspace = workspaces.getWorkspace(workspaceId);
+        let changedPaths = [];
         return runToolWithHooks(hooks, {
             tool: toolNames.capability,
             invocation: workspaceHookInvocation(workspace),
             payload: { name, action },
             isFailure: toolResultIsError,
+            changedPaths: () => changedPaths,
             operation: async () => {
                 const startedAt = performance.now();
                 try {
@@ -1036,10 +1111,24 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         });
                         return result;
                     }
-                    const capabilityResult = await capabilityRegistry.run(name, capabilityArguments ?? {}, capabilityContextFor(workspace));
+                    const execution = await capabilityRegistry.run(name, capabilityArguments ?? {}, capabilityContextFor(workspace), { nativeFile: file });
+                    changedPaths = execution.changedPaths ?? [];
                     const result = {
-                        content: [textBlock(`Capability ${name} completed.\n${JSON.stringify(capabilityResult, null, 2)}`)],
-                        structuredContent: { name, action, result: capabilityResult },
+                        content: [textBlock(`Capability ${name} completed.\n${JSON.stringify(execution.value, null, 2)}`)],
+                        ...(execution.card
+                            ? {
+                                _meta: {
+                                    tool: execution.card.tool ?? toolNames.capability,
+                                    card: {
+                                        workspaceId,
+                                        summary: execution.card.summary ?? {},
+                                        files: execution.card.files,
+                                        payload: execution.card.payload ?? {},
+                                    },
+                                },
+                            }
+                            : {}),
+                        structuredContent: { name, action, result: execution.value },
                     };
                     logToolCall(config, {
                         tool: toolNames.capability,
@@ -1651,11 +1740,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 invocation: workspaceHookInvocation(workspace),
                 operation: async () => {
                     const startedAt = performance.now();
-                    const review = await reviewCheckpoints.reviewChanges({
-                        workspaceId,
-                        root: workspace.root,
-                        markReviewed: true,
-                    });
+                    const review = await reviewWorkspaceChanges(reviewCheckpoints, workspace);
                     const content = [textBlock(review.result)];
                     logToolCall(config, {
                         tool: "show_changes",
@@ -1957,6 +2042,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             workspaces,
             hooks,
             incomingArtifactAdapters,
+            incomingArtifactRegistry,
         });
     }
     return server;

package/package.json

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