@akira-tl/forgerelay 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.3.6] - 2026-08-10
+
+### Added
+
+- `open_workspace(action="list")` now provides paginated logical-workspace inventory without adding a tenth Core tool. Inventory entries include a compact `project/workspaceId` label, persisted status, derived lifecycle state, checkout/worktree backing metadata, creation/last-used timestamps, idle duration, root validity, current-conversation selection, and filters for workspace ID, status, state, mode, root, and stale-only views.
+
+### Changed
+
+- Workspace bootstrap context is now deduplicated by conversation scope, canonical workspace target, and a content fingerprint instead of by logical `workspaceId`. `context="auto"` remains the default, `context="full"` forces a refresh, and `context="none"` opens or resumes a workspace without returning the full AGENTS/Skills/guide/profile bootstrap.
+- Context-delivery state is persisted independently from logical-workspace selection, so switching or closing one logical handle does not make the same conversation forget already-delivered project context. Changes to loaded instruction contents or relevant Skill, guide, profile, diagnostic, or nested-instruction metadata change the fingerprint and cause `auto` to deliver the refreshed context again.
+- Workspace inventory is read-only with respect to workspace activity timestamps and runs the existing idle-session GC before listing. Persisted `status="active"` continues to mean the session has not been explicitly closed, while the derived `state` distinguishes currently active, stale-but-valid, invalid/missing-root, and closed records.
+
+## [0.3.5] - 2026-08-10
+
+### Changed
+
+- Regular `minimal` and `full` MCP modes now expose the same canonical 9-tool surface: `open_workspace`, `capability`, `close_workspace`, `read`, `write`, `edit`, `rename`, `delete`, and `bash`. Search and directory inspection use shell commands through `bash`; `full` remains only as a configuration-compatibility value.
+- `review.changes` and `artifact.download` are now Capability Gateway-only workflows. Their dedicated top-level compatibility aliases have been removed, while review cards identify themselves as `capability` results with `capabilityName="review.changes"`.
+- Capability fingerprints now report semantic runtime capabilities such as `review.changes` instead of implementation-shaped search/review tool names, and current Guides/docs/bootstrap instructions use the final Core Surface + Capability Gateway model.
+
+### Removed
+
+- Removed the regular dedicated `grep`, `glob`, `ls`, aggregate-review, and native-artifact MCP adapters after their canonical workflows moved to `bash` or the Capability Gateway.
+
+### Fixed
+
+- Successful `report: true` lifecycle Hook reports are now mirrored into the model-readable structured result as well as MCP text content, so Hosts that surface only structured tool results still expose the Hook outcome to the Agent.
+
 ## [0.3.4] - 2026-08-10
 
 ### Changed

package/capabilities/artifacts-review/GUIDE.md

@@ -12,8 +12,6 @@ Native artifact download 默认关闭，且当前安全发布实现主要面向
 2. 调用 `capability`，`name="artifact.download"`、`action="run"`，把 Host 原样提供的 native `file` 值放在 Gateway 顶层 `file`，并在 `arguments.path` 传 workspace-relative 目标路径；
 3. 成功后使用返回的 normalized relative path 配合普通 `read` / `rename` / `delete` / shell 等工具继续处理。
 
-0.3.3 仍保留 `download_artifact` 作为迁移期 compatibility alias，但新的 Agent workflow 不应把它视为长期 public surface。
-
 `artifact.download` 会创建缺失的父目录，但拒绝覆盖已有目标。不要把 native file 值改造成：
 
 - 任意 URL 字符串；
@@ -35,10 +33,10 @@ Native artifact download 默认关闭，且当前安全发布实现主要面向
 
 Plain MCP Host 可以忽略这些 UI metadata；不要把 UI 是否显示当成文件操作是否成功的判据。
 
-当 Capability catalog 广告 `review.changes` 时，本轮成功修改文件后，在最后一个相关 file mutation 之后、final response 之前通过 `capability` 调用一次，让用户看到聚合 diff；不要每改一个文件就调用一次。0.3.3 仍保留 `show_changes` compatibility alias，但它和 `review.changes` 共用同一套 checkpoint，不是两套 review 状态。
+当 Capability catalog 广告 `review.changes` 时，本轮成功修改文件后，在最后一个相关 file mutation 之后、final response 之前通过 `capability` 调用一次，让用户看到聚合 diff；不要每改一个文件就调用一次。
 
 `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 registered capability，而不是 Agent 自己的文件搬运协议。`tools/list` 只负责暴露稳定 Gateway 与当前兼容 aliases；真正可用的低频能力以当前 workspace 的 Capability catalog 为准。本指南提供流程和边界，不额外创造隐藏执行入口。
+Artifact transfer 和 change review 都属于 ForgeRelay registered capability，而不是 Agent 自己的文件搬运协议。`tools/list` 只暴露稳定 `capability` Gateway；真正可用的低频能力以当前 workspace 的 Capability catalog 为准。本指南提供流程和边界，不额外创造隐藏执行入口。

package/dist/artifact-tools.js

@@ -2,18 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import { link, lstat, mkdir, open, readdir, unlink, } from "node:fs/promises";
 import { isAbsolute, join, normalize, sep } from "node:path";
-import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
-import * as z from "zod/v4";
 import { ArtifactError } from "./artifact-error.js";
-import { runToolWithHooks } from "./hooks.js";
-import { describeIncomingArtifactValue, IncomingArtifactAdapterRegistry, } from "./incoming-artifacts.js";
-import { logEvent, workspaceLogLabel } from "./logger.js";
-const ARTIFACT_WRITE_ANNOTATIONS = {
-    readOnlyHint: false,
-    destructiveHint: false,
-    idempotentHint: false,
-    openWorldHint: true,
-};
 const NO_FOLLOW = fsConstants.O_NOFOLLOW ?? 0;
 const DIRECTORY_FLAGS = fsConstants.O_RDONLY | (fsConstants.O_DIRECTORY ?? 0) | NO_FOLLOW;
 const PARTIAL_PREFIX = ".forgerelay-download-";
@@ -21,64 +10,9 @@ const PARTIAL_SUFFIX = ".partial";
 const STALE_PARTIAL_AGE_MS = 24 * 60 * 60 * 1_000;
 const MAX_STALE_PARTIAL_CLEANUP = 32;
 const ARTIFACT_DOWNLOAD_PLATFORMS = new Set(["linux"]);
-const openAIFileReferenceInputSchema = 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(),
-});
 export function isArtifactDownloadSupportedPlatform(platform = process.platform) {
     return ARTIFACT_DOWNLOAD_PLATFORMS.has(platform);
 }
-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.",
-        inputSchema: {
-            file: openAIFileReferenceInputSchema.describe("Native file value authorized and supplied by the MCP host."),
-            workspaceId: z.string().min(1).describe("Workspace identifier returned by open_workspace."),
-            path: z.string().min(1).describe("Relative destination path inside the selected workspace. The destination must not already exist."),
-        },
-        outputSchema: {
-            path: z.string(),
-        },
-        _meta: { "openai/fileParams": ["file"] },
-        annotations: ARTIFACT_WRITE_ANNOTATIONS,
-    }, async (input) => {
-        const workspace = workspaces.getWorkspace(input.workspaceId);
-        return runToolWithHooks(hooks, {
-            tool: "download_artifact",
-            invocation: {
-                workspaceId: workspace.id,
-                workspaceRoot: workspace.root,
-                workspaceMode: workspace.mode,
-                sourceRoot: workspace.sourceRoot,
-            },
-            payload: { path: input.path },
-            changedPaths: (result) => [result.structuredContent.path],
-            operation: () => executeArtifactTool(config, input, {
-                workspace: workspaceLogLabel(workspace.root, workspace.id),
-            }, async () => {
-                const downloaded = await downloadIncomingArtifact({
-                    registry: incomingRegistry,
-                    workspaceId: workspace.id,
-                    workspaceRoot: workspace.root,
-                    maxFileBytes: config.artifactMaxFileBytes,
-                    file: input.file,
-                    path: input.path,
-                });
-                return {
-                    publicResult: { path: downloaded.path },
-                    logResult: downloaded,
-                };
-            }),
-        });
-    });
-}
 /**
  * Stream a trusted native file directly into one already-open workspace.
  *
@@ -159,53 +93,6 @@ export async function downloadIncomingArtifact({ registry, workspaceId, workspac
         await workspaceHandle?.close().catch(() => undefined);
     }
 }
-export function artifactToolLogFields(input) {
-    return {
-        fileProvided: input.file !== undefined,
-        fileReferenceShape: describeIncomingArtifactValue(input.file),
-        downloadUrlHostname: incomingFileDownloadHostname(input.file),
-        workspaceId: input.workspaceId,
-        path: input.path,
-    };
-}
-async function executeArtifactTool(config, input, logContext, operation) {
-    const startedAt = performance.now();
-    try {
-        const { publicResult, logResult } = await operation();
-        if (config.logging.toolCalls) {
-            logEvent(config.logging, "info", "artifact_tool_call", {
-                tool: "download_artifact",
-                ...artifactToolLogFields(input),
-                ...logContext,
-                path: logResult.path,
-                size: logResult.size,
-                sha256: logResult.sha256,
-                success: true,
-                durationMs: Math.round(performance.now() - startedAt),
-            });
-        }
-        return artifactToolResponse(publicResult);
-    }
-    catch (error) {
-        if (config.logging.toolCalls) {
-            logEvent(config.logging, "warn", "artifact_tool_call", {
-                tool: "download_artifact",
-                ...artifactToolLogFields(input),
-                ...logContext,
-                success: false,
-                errorCode: error instanceof ArtifactError ? error.code : "internal_error",
-                durationMs: Math.round(performance.now() - startedAt),
-            });
-        }
-        throw error;
-    }
-}
-function artifactToolResponse(result) {
-    return {
-        content: [{ type: "text", text: JSON.stringify(result) }],
-        structuredContent: result,
-    };
-}
 async function openDirectoryNoFollow(path, code, message) {
     let handle;
     try {
@@ -356,21 +243,6 @@ async function writeAll(handle, buffer, position) {
         offset += bytesWritten;
     }
 }
-function incomingFileDownloadHostname(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return undefined;
-    }
-    const rawUrl = value.download_url;
-    if (typeof rawUrl !== "string")
-        return undefined;
-    try {
-        const hostname = new URL(rawUrl).hostname.toLowerCase();
-        return hostname.length > 0 && hostname.length <= 253 ? hostname : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 function incomingStreamChunk(value) {
     if (Buffer.isBuffer(value))
         return value;

package/dist/capabilities.js

@@ -21,7 +21,7 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
     {
         name: "artifacts-review",
         description: "Native artifact transfer and aggregate change review.",
-        whenToRead: "Read for host-provided files or show_changes.",
+        whenToRead: "Read for host-provided files or aggregate change review.",
         enabled: (config) => config.artifactsEnabled || config.widgets === "changes",
     },
     {
@@ -76,9 +76,6 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "hooks.lifecycle",
         "capability-guides.read",
     ];
-    if (config.toolMode === "full") {
-        capabilities.push("inspection.search-tools");
-    }
     if (config.subagents) {
         capabilities.push("subagent.profiles");
     }
@@ -89,7 +86,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         capabilities.push("ui.mcp-app");
     }
     if (config.widgets === "changes") {
-        capabilities.push("review.show-changes");
+        capabilities.push("review.changes");
     }
     return {
         version,

package/dist/db/migrations.js

@@ -29,6 +29,11 @@ const migrations = [
         name: "local-agent-hook-reports",
         up: migrateLocalAgentHookReports,
     },
+    {
+        version: 7,
+        name: "workspace-context-deliveries",
+        up: migrateWorkspaceContextDeliveries,
+    },
 ];
 export function migrateDatabase(sqlite) {
     const migrate = sqlite.transaction(() => {
@@ -189,6 +194,20 @@ function migrateWorkspaceWorktreeBranches(sqlite) {
 function migrateLocalAgentHookReports(sqlite) {
     addColumnIfMissing(sqlite, "local_agent_sessions", "hook_reports_json", "text");
 }
+function migrateWorkspaceContextDeliveries(sqlite) {
+    sqlite.exec(`
+    create table if not exists workspace_context_deliveries (
+      conversation_scope_id text not null,
+      target_key text not null,
+      context_fingerprint text not null,
+      delivered_at text not null,
+      primary key (conversation_scope_id, target_key)
+    );
+
+    create index if not exists workspace_context_deliveries_delivered_idx
+      on workspace_context_deliveries(delivered_at desc);
+  `);
+}
 function addColumnIfMissing(sqlite, table, column, definition) {
     const columns = sqlite.prepare(`pragma table_info(${table})`).all();
     if (columns.some((existingColumn) => existingColumn.name === column))

package/dist/db/schema.js

@@ -41,6 +41,15 @@ export const workspaceConversationBindings = sqliteTable("workspace_conversation
     primaryKey({ columns: [table.conversationScopeId, table.targetKey] }),
     index("workspace_conversation_bindings_workspace_idx").on(table.workspaceSessionId),
 ]);
+export const workspaceContextDeliveries = sqliteTable("workspace_context_deliveries", {
+    conversationScopeId: text("conversation_scope_id").notNull(),
+    targetKey: text("target_key").notNull(),
+    contextFingerprint: text("context_fingerprint").notNull(),
+    deliveredAt: text("delivered_at").notNull(),
+}, (table) => [
+    primaryKey({ columns: [table.conversationScopeId, table.targetKey] }),
+    index("workspace_context_deliveries_delivered_idx").on(table.deliveredAt),
+]);
 export const oauthClients = sqliteTable("oauth_clients", {
     clientId: text("client_id").primaryKey(),
     clientJson: text("client_json").notNull(),

package/dist/hooks.js

@@ -152,6 +152,10 @@ export function attachHookReports(result, executions) {
     const summary = formatVisibleHookReports(executions);
     if (!summary || !isRecord(result) || !Array.isArray(result.content))
         return result;
+    const structuredContent = isRecord(result.structuredContent) ? result.structuredContent : undefined;
+    const structuredResult = typeof structuredContent?.result === "string"
+        ? structuredContent.result
+        : undefined;
     return {
         ...result,
         content: [
@@ -161,6 +165,14 @@ export function attachHookReports(result, executions) {
                 text: summary,
             },
         ],
+        ...(structuredContent && structuredResult !== undefined
+            ? {
+                structuredContent: {
+                    ...structuredContent,
+                    result: `${structuredResult}\n\n${summary}`,
+                },
+            }
+            : {}),
     };
 }
 function appendHookReportsToError(error, executions) {

package/dist/mcp/server-instructions.js

@@ -6,9 +6,6 @@ export const toolNames = {
     edit: "edit",
     rename: "rename",
     delete: "delete",
-    grep: "grep",
-    glob: "glob",
-    ls: "ls",
     shell: "bash",
     writeStdin: "write_stdin",
     capability: "capability",
@@ -23,9 +20,9 @@ export function buildToolDescriptions(config) {
     const skillCapability = config.skillsEnabled
         ? " Advertised skill paths may also be outside the workspace."
         : "";
-    const shellSurface = config.toolMode === "minimal"
-        ? ` In minimal tool mode, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} are disabled, so shell commands may be used for equivalent search and directory inspection.`
-        : "";
+    const shellSurface = config.toolMode === "codex"
+        ? ""
+        : " Use shell commands for search and directory inspection instead of dedicated MCP search tools.";
     return {
         read: `Read a file inside an open workspace or the OS temp directory. Instruction files and advertised capability guides returned by ${toolNames.openWorkspace} are also readable when applicable.${skillCapability} Only advertised entry files and files under already-loaded advertised directories are readable outside the normal roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         write: `Create or completely overwrite a file inside an open workspace or the OS temp directory. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
@@ -62,9 +59,7 @@ function defaultWorkflowInstructions(config) {
     if (config.toolMode === "codex") {
         return `Use ${toolNames.read} for direct file reads, ${toolNames.rename} and ${toolNames.delete} for direct path moves or removals, apply_patch for content modifications, exec_command for inspection, tests, builds, and other commands, and ${toolNames.writeStdin} to poll or interact with running processes.`;
     }
-    const inspection = config.toolMode === "full"
-        ? `Prefer ${toolNames.read}, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} for file inspection.`
-        : `Use ${toolNames.shell} with command-line tools such as grep, rg, find, ls, and tree for search and directory inspection.`;
+    const inspection = `Use ${toolNames.shell} with command-line tools such as grep, rg, find, ls, and tree for search and directory inspection.`;
     return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted content modifications, ${toolNames.write} only for new files or complete rewrites, ${toolNames.rename} for path moves, ${toolNames.delete} for removals, and ${toolNames.shell} for tests, builds, git inspection, package scripts, generators, formatters, and commands that are better executed by the shell. If ${toolNames.shell} returns a running process with a processId, call ${toolNames.shell} again with action=\"process\" when you need to poll, wait, interact, resize, or interrupt it; otherwise you may continue other work and consume its completion notice from a later tool result.`);
 }
 function joinInstructions(...parts) {

package/dist/review-checkpoints.js

@@ -39,19 +39,19 @@ export function createReviewCheckpointManager() {
             }
             assertWorkspaceRoot(state, workspaceId, root);
             if (!state?.gitRoot) {
-                throw new Error(state?.diagnostic ?? "show_changes requires a Git workspace in this version.");
+                throw new Error(state?.diagnostic ?? "review.changes requires a Git workspace in this version.");
             }
             let effectiveSince = since;
             let usedWorkspaceOpenFallback = false;
             if (since === "last_shown" && !state.baselineRefAvailable) {
                 if (!state.openRefAvailable) {
-                    throw new Error("Review checkpoints are missing; show_changes cannot reconstruct that history safely.");
+                    throw new Error("Review checkpoints are missing; review.changes cannot reconstruct that history safely.");
                 }
                 effectiveSince = "workspace_open";
                 usedWorkspaceOpenFallback = true;
             }
             else if (since === "workspace_open" && !state.openRefAvailable) {
-                throw new Error("The workspace-open review checkpoint is missing; show_changes cannot reconstruct that history safely.");
+                throw new Error("The workspace-open review checkpoint is missing; review.changes cannot reconstruct that history safely.");
             }
             const baselineRef = effectiveSince === "workspace_open" ? state.openRef : state.baselineRef;
             const baseline = (await git(state.gitRoot, ["rev-parse", "--verify", `${baselineRef}^{commit}`])).stdout.trim();
@@ -98,7 +98,7 @@ async function initializeWorkspaceState(states, workspaceId, root) {
     try {
         const eligibility = await getGitEligibility(root);
         if (!eligibility.ok || !eligibility.gitRoot) {
-            state.diagnostic = eligibility.message ?? "show_changes requires a Git workspace in this version.";
+            state.diagnostic = eligibility.message ?? "review.changes requires a Git workspace in this version.";
             return;
         }
         const [openCommit, baselineCommit] = await Promise.all([