@akira-tl/forgerelay 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.8.5] - 2026-08-31
+
+### Added
+
+- Added source-controlled GitHub Wiki pages with validation and publishing tooling.
+
+### Changed
+
+- Relayed checkout and managed-worktree Workspaces now preserve stable Gateway identity and Execution-owned Task/lifecycle semantics across close, reopen, delete, inspection, and Composite member routing.
+
+### Fixed
+
+- Task reminders and relayed/Composite runtime state now survive independent MCP transport sessions instead of resetting or presenting stale session-local state.
+- Managed-worktree Relay acceptance now tolerates Git-native LF/CRLF checkout normalization, keeping the release matrix portable across Linux, macOS, and Windows.
+
+## [0.8.4] - 2026-08-31
+
+### Added
+
+- Added `open_workspace(action="inspect", workspaceId=...)` for bounded read-only Workspace metadata, including safe Task summaries without opening, rebinding, or exposing bootstrap/remote-auth details.
+
+### Changed
+
+- `workspace.tasks` now discloses Task state progressively from List summaries to headers and one Task detail, with configurable forgotten-update reminders after meaningful Workspace work.
+
 ## [0.8.3] - 2026-08-31
 
 ### Added

package/README.md

@@ -348,6 +348,7 @@ Trusted Publishing setup.
 
 ## Documentation
 
+- [GitHub Wiki](https://github.com/Akira-TL/forgerelay/wiki) — 面向用户的使用指南、概念说明与故障排查入口。
 - [Setup Guide](docs/setup.md)
 - [Local Debugging and 7677 Acceptance](docs/debugging.md)
 - [ChatGPT Coding Workflow](docs/chatgpt-coding-workflow.md)
@@ -358,6 +359,7 @@ Trusted Publishing setup.
 - [Troubleshooting](docs/gotchas.md)
 - [Roadmap](docs/roadmap.md)
 - [Versioning and Release Management](docs/versioning.md)
+- [GitHub Wiki Maintenance](docs/maintenance/wiki.md)
 - [Changelog](CHANGELOG.md)
 - [Attribution Notice](NOTICE.md)
 

package/capabilities/workspace-tasks/GUIDE.md

@@ -10,9 +10,19 @@
 - Task 状态只有 `pending`、`in_progress`、`completed`。`content` 保存继续工作真正需要的要求、阻塞点、结论或下一步，而不是日志或对话转录。
 - Task/List ID 创建后保持稳定。完成 Task 不会删除它；删除必须显式执行。
 
-## 操作
+## 渐进式读取
 
-先用 `operation="get"` 读取当前 Task state。
+Task 读取默认使用渐进式披露，不会一次返回所有 `content`：
+
+- `operation="get"` 或 `level="summary"`：返回 List identity、状态、revision、Task 数量和未完成数量，不返回 Task headers/body。
+- `operation="get", level="headers"`：返回 Task `id`、`status`、`subject`，不返回 `content`；可传 `listId` 只看一个 List。
+- `operation="get", level="detail", listId=..., taskId=...`：只返回指定 Task 的完整 `content`。
+
+先从 summary 定位 List，再按需读取 headers/detail；不要把所有 Task body 当作默认上下文。
+
+## 修改操作
+
+修改响应同样保持有界：List 修改返回 summary；Task 修改返回对应 List 的 headers，不会顺带回传所有 Task body。
 
 List 操作：
 
@@ -27,3 +37,14 @@ Task 操作：
 - `task.delete`：显式删除 Task。
 
 Task 修改使用独立的 revision/fingerprint 域；它不改变 Workspace bootstrap `contextFingerprint`。
+
+## 忘记更新提醒
+
+ForgeRelay 会按当前 Workspace 统计成功的语义工作调用。默认连续 30 次语义工作没有 Task mutation、且仍存在 active List 中的未完成 Task 时，在工作结果后追加一条简短提醒；提醒只提示检查 `workspace.tasks`，不会携带 Task `content`。
+
+- 任意 List/Task create/update/delete 都会重置计数。
+- `open_workspace` inventory/open/close、Activity/UI 查询、Capability describe、Task get，以及 `bash action="process"|"output"` / Codex `write_stdin` 等已有进程 follow-up 不单独计数。
+- `batch.execute` 作为一次顶层语义工作调用计数，而不是按 child operation 重复计数。
+- 只有 active List 中仍有 `pending` / `in_progress` Task 才会提醒；归档 List 或全部完成会 suppress 提醒。
+- 计数器只保存在当前 ForgeRelay 进程内，server restart 可以重置；Task durable state 本身不受影响。
+- `FORGERELAY_TASK_REMINDER_INTERVAL=0` 可禁用提醒；其他非负整数设置间隔。

package/dist/capability-registry.js

@@ -133,7 +133,21 @@ export function createCapabilityRegistry(dependencies) {
     const workspaceTaskStatus = z.enum(["pending", "in_progress", "completed"]);
     const workspaceTaskListState = z.enum(["active", "archived"]);
     const workspaceTasksInput = z.union([
-        z.object({ operation: z.literal("get") }).strict(),
+        z.object({
+            operation: z.literal("get"),
+            level: z.literal("summary").optional(),
+        }).strict(),
+        z.object({
+            operation: z.literal("get"),
+            level: z.literal("headers"),
+            listId: z.string().min(1).optional(),
+        }).strict(),
+        z.object({
+            operation: z.literal("get"),
+            level: z.literal("detail"),
+            listId: z.string().min(1),
+            taskId: z.string().min(1),
+        }).strict(),
         z.object({
             operation: z.literal("list.create"),
             name: z.string().trim().min(1),

package/dist/config.js

@@ -7,6 +7,7 @@ import { forgerelayAgentsDir, forgerelaySkillsDir, generateInstanceId, loadForge
 const DEFAULT_OAUTH_ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
 const DEFAULT_OAUTH_REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
 const DEFAULT_ARTIFACT_MAX_FILE_BYTES = 100 * 1024 * 1024;
+const DEFAULT_TASK_REMINDER_INTERVAL = 30;
 function parsePort(value) {
     if (value === undefined || value === "")
         return 7676;
@@ -109,6 +110,15 @@ function parsePositiveInteger(value, fallback, name, max = Number.MAX_SAFE_INTEG
     }
     return parsed;
 }
+function parseNonNegativeInteger(value, fallback, name) {
+    if (value === undefined || value === "")
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0 || parsed > Number.MAX_SAFE_INTEGER) {
+        throw new Error(`Invalid ${name}: ${value}`);
+    }
+    return parsed;
+}
 function parseLoggingConfig(env, trustProxyDefault) {
     const format = parseLogFormat(productEnv(env, "LOG_FORMAT"));
     const requests = productEnv(env, "LOG_REQUESTS");
@@ -247,6 +257,7 @@ export function loadConfig(env = process.env) {
             ? files.config.artifactsEnabled === true
             : parseBoolean(productEnv(env, "ARTIFACTS")),
         artifactMaxFileBytes: parsePositiveInteger(productEnv(env, "ARTIFACT_MAX_FILE_BYTES") ?? numberConfigValue(files.config.artifactMaxFileBytes), DEFAULT_ARTIFACT_MAX_FILE_BYTES, "FORGERELAY_ARTIFACT_MAX_FILE_BYTES"),
+        taskReminderInterval: parseNonNegativeInteger(productEnv(env, "TASK_REMINDER_INTERVAL") ?? numberConfigValue(files.config.taskReminderInterval), DEFAULT_TASK_REMINDER_INTERVAL, "FORGERELAY_TASK_REMINDER_INTERVAL"),
         skillsEnabled: productEnv(env, "SKILLS") === undefined ? true : parseBoolean(productEnv(env, "SKILLS")),
         skillPaths: parsePathList(productEnv(env, "SKILL_PATHS")),
         devspaceSkillsDir: forgerelaySkillsDir(env),

package/dist/remote-workspace-relay.js

@@ -27,6 +27,58 @@ export class RemoteWorkspaceRelay {
         this.loadRoutes();
         return this.routes.has(workspaceId);
     }
+    async inspectWorkspace(gatewayWorkspaceId) {
+        const route = this.requireRoute(gatewayWorkspaceId);
+        const resolved = this.remoteByInstance(route.remoteInstanceId);
+        let result;
+        try {
+            result = await this.callRemoteTool(resolved.alias, resolved.remote, "open_workspace", {
+                action: "inspect",
+                workspaceId: route.remoteWorkspaceId,
+            });
+            assertRemoteToolSucceeded(resolved.alias, "open_workspace", result);
+        }
+        catch (error) {
+            throw sanitizedRemoteError(error, route.remoteWorkspaceId, gatewayWorkspaceId);
+        }
+        const structured = result.structuredContent;
+        const remoteInspection = structured?.inspection;
+        if (!remoteInspection || remoteInspection.kind !== "workspace") {
+            throw new Error(`Remote ForgeRelay ${resolved.alias} inspection did not return a Workspace projection.`);
+        }
+        const root = stringField(remoteInspection, "root", "Remote Workspace inspection");
+        const mode = remoteInspection.mode;
+        if (mode !== "checkout" && mode !== "worktree") {
+            throw new Error(`Remote ForgeRelay ${resolved.alias} inspection did not return a valid Workspace mode.`);
+        }
+        const projection = {
+            workspaceId: route.gatewayWorkspaceId,
+            kind: "workspace",
+            location: "relay",
+            root,
+            routeState: "known",
+            mode,
+            relay: resolved.alias,
+            executionLocation: `remote:${resolved.alias}`,
+        };
+        copyStringField(remoteInspection, projection, "status");
+        const state = remoteInspection.state;
+        if (state === "active" || state === "stale" || state === "invalid" || state === "closed") {
+            projection.state = state;
+        }
+        copyStringField(remoteInspection, projection, "sourceRoot");
+        copyStringField(remoteInspection, projection, "branch");
+        copyStringField(remoteInspection, projection, "targetBranch");
+        copyBooleanField(remoteInspection, projection, "managed");
+        copyStringField(remoteInspection, projection, "createdAt");
+        copyStringField(remoteInspection, projection, "lastUsedAt");
+        copyNumberField(remoteInspection, projection, "idleMs");
+        copyBooleanField(remoteInspection, projection, "rootValid");
+        const taskSummary = safeTaskSummary(remoteInspection.taskSummary);
+        if (taskSummary)
+            projection.taskSummary = taskSummary;
+        return projection;
+    }
     async openWorkspace(alias, input, conversationScopeId) {
         const resolved = this.remoteByAlias(alias);
         let result;
@@ -51,18 +103,15 @@ export class RemoteWorkspaceRelay {
         if (mode !== "checkout" && mode !== "worktree") {
             throw new Error("Remote open_workspace response did not include a valid workspace mode.");
         }
-        const gatewayWorkspaceId = this.allocateGatewayWorkspaceId();
         const sourceRoot = typeof structured?.sourceRoot === "string" ? structured.sourceRoot : undefined;
-        const route = {
-            gatewayWorkspaceId,
+        const route = this.findOrCreateRoute({
             remoteInstanceId: resolved.remote.instanceId,
             remoteWorkspaceId,
             root,
             mode,
             ...(sourceRoot ? { sourceRoot } : {}),
-        };
-        this.routes.set(gatewayWorkspaceId, route);
-        this.persistRoute(route);
+        });
+        const gatewayWorkspaceId = route.gatewayWorkspaceId;
         const remapContext = (value) => replaceExactWorkspaceId(value, remoteWorkspaceId, gatewayWorkspaceId);
         const remoteInstruction = typeof structured?.instruction === "string"
             ? String(remapContext(structured.instruction))
@@ -102,10 +151,24 @@ export class RemoteWorkspaceRelay {
         };
     }
     async resumeWorkspace(gatewayWorkspaceId, context = "auto", conversationScopeId) {
+        const route = this.requireRoute(gatewayWorkspaceId);
         const result = await this.callWorkspaceTool(gatewayWorkspaceId, "open_workspace", { context }, conversationScopeId);
         if (result.isError === true) {
             throw new Error(`Remote open_workspace failed: ${toolResultText(result)}`);
         }
+        const structured = result.structuredContent;
+        const root = typeof structured?.root === "string" ? structured.root : route.root;
+        const mode = structured?.mode === "checkout" || structured?.mode === "worktree"
+            ? structured.mode
+            : route.mode;
+        const sourceRoot = typeof structured?.sourceRoot === "string" ? structured.sourceRoot : route.sourceRoot;
+        this.findOrCreateRoute({
+            remoteInstanceId: route.remoteInstanceId,
+            remoteWorkspaceId: route.remoteWorkspaceId,
+            root,
+            mode,
+            ...(sourceRoot ? { sourceRoot } : {}),
+        });
         return result;
     }
     async read(gatewayWorkspaceId, input, conversationScopeId) {
@@ -206,14 +269,16 @@ export class RemoteWorkspaceRelay {
             throw sanitizedRemoteError(error, route.remoteWorkspaceId, gatewayWorkspaceId);
         }
     }
-    async closeWorkspace(gatewayWorkspaceId, commitMessage, conversationScopeId) {
+    async closeWorkspace(gatewayWorkspaceId, input = {}, conversationScopeId) {
         const route = this.requireRoute(gatewayWorkspaceId);
         const resolved = this.remoteByInstance(route.remoteInstanceId);
+        const action = input.action ?? "close";
         let result;
         try {
             result = await this.callRemoteTool(resolved.alias, resolved.remote, "close_workspace", {
                 workspaceId: route.remoteWorkspaceId,
-                ...(commitMessage !== undefined ? { commitMessage } : {}),
+                action,
+                ...(input.commitMessage !== undefined ? { commitMessage: input.commitMessage } : {}),
             }, conversationScopeId);
             assertRemoteToolSucceeded(resolved.alias, "close_workspace", result);
         }
@@ -221,21 +286,26 @@ export class RemoteWorkspaceRelay {
             throw sanitizedRemoteError(error, route.remoteWorkspaceId, gatewayWorkspaceId);
         }
         const remoteStructured = result.structuredContent;
-        this.routes.delete(gatewayWorkspaceId);
-        this.deletePersistedRoute(gatewayWorkspaceId);
+        if (action === "delete") {
+            this.routes.delete(gatewayWorkspaceId);
+            this.deletePersistedRoute(gatewayWorkspaceId);
+        }
         for (const [turnId, routedWorkspaceId] of this.turnRoutes) {
             if (routedWorkspaceId === gatewayWorkspaceId)
                 this.turnRoutes.delete(turnId);
         }
+        const actionText = action === "delete" ? "Deleted" : "Closed";
         const text = route.mode === "worktree"
-            ? `Closed relayed worktree workspace ${gatewayWorkspaceId} on remote ${resolved.alias}.`
-            : `Closed relayed checkout workspace ${gatewayWorkspaceId} on remote ${resolved.alias}.`;
+            ? `${actionText} relayed worktree workspace ${gatewayWorkspaceId} on remote ${resolved.alias}.`
+            : `${actionText} relayed checkout workspace ${gatewayWorkspaceId} on remote ${resolved.alias}.`;
         const structuredContent = {
             result: text,
             workspaceId: gatewayWorkspaceId,
+            action,
             mode: route.mode,
         };
         for (const field of [
+            "status",
             "sourceRoot",
             "branch",
             "targetBranch",
@@ -255,6 +325,7 @@ export class RemoteWorkspaceRelay {
                 tool: "close_workspace",
                 card: {
                     workspaceId: gatewayWorkspaceId,
+                    action,
                     mode: route.mode,
                     payload: { content: [{ type: "text", text }] },
                 },
@@ -277,10 +348,26 @@ export class RemoteWorkspaceRelay {
             this.routes.set(workspaceId, route);
         }
     }
-    persistRoute(route) {
-        this.updatePersistedRoutes((routes) => {
-            routes.set(route.gatewayWorkspaceId, route);
+    findOrCreateRoute(input) {
+        let selected;
+        mkdirSync(this.routeStateDir, { recursive: true });
+        this.withRouteFileLock(() => {
+            const routes = this.readRoutesFromDisk();
+            const existing = [...routes.values()]
+                .filter((route) => route.remoteInstanceId === input.remoteInstanceId &&
+                route.remoteWorkspaceId === input.remoteWorkspaceId)
+                .sort((left, right) => left.gatewayWorkspaceId.localeCompare(right.gatewayWorkspaceId))[0];
+            selected = {
+                gatewayWorkspaceId: existing?.gatewayWorkspaceId ?? this.allocateGatewayWorkspaceId(routes),
+                ...input,
+            };
+            routes.set(selected.gatewayWorkspaceId, selected);
+            this.writeRoutesToDisk(routes);
         });
+        if (!selected)
+            throw new Error("Failed to persist relayed Workspace route.");
+        this.routes.set(selected.gatewayWorkspaceId, selected);
+        return selected;
     }
     deletePersistedRoute(workspaceId) {
         this.updatePersistedRoutes((routes) => {
@@ -408,11 +495,11 @@ export class RemoteWorkspaceRelay {
         writeForgeRelayRemote(alias, refreshed, this.authEnv);
         return refreshed;
     }
-    allocateGatewayWorkspaceId() {
+    allocateGatewayWorkspaceId(routes = this.routes) {
         let workspaceId;
         do {
             workspaceId = `rws_${randomBytes(5).toString("hex")}`;
-        } while (this.routes.has(workspaceId));
+        } while (routes.has(workspaceId));
         return workspaceId;
     }
 }
@@ -428,6 +515,62 @@ function stringField(structured, field, label) {
     }
     return value;
 }
+function copyStringField(source, target, field) {
+    const value = source[field];
+    if (typeof value === "string")
+        target[field] = value;
+}
+function copyBooleanField(source, target, field) {
+    const value = source[field];
+    if (typeof value === "boolean")
+        target[field] = value;
+}
+function copyNumberField(source, target, field) {
+    const value = source[field];
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+        target[field] = value;
+}
+function safeTaskSummary(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const summary = value;
+    if (summary.level !== "summary" ||
+        summary.version !== 1 ||
+        typeof summary.revision !== "number" ||
+        !Number.isInteger(summary.revision) ||
+        summary.revision < 0 ||
+        !Array.isArray(summary.lists)) {
+        return undefined;
+    }
+    const lists = [];
+    for (const value of summary.lists) {
+        if (!value || typeof value !== "object")
+            return undefined;
+        const list = value;
+        if (typeof list.id !== "string" ||
+            typeof list.name !== "string" ||
+            (list.state !== "active" && list.state !== "archived") ||
+            typeof list.revision !== "number" || !Number.isInteger(list.revision) || list.revision <= 0 ||
+            typeof list.taskCount !== "number" || !Number.isInteger(list.taskCount) || list.taskCount < 0 ||
+            typeof list.unfinishedTaskCount !== "number" || !Number.isInteger(list.unfinishedTaskCount) || list.unfinishedTaskCount < 0) {
+            return undefined;
+        }
+        lists.push({
+            id: list.id,
+            name: list.name,
+            state: list.state,
+            revision: list.revision,
+            taskCount: list.taskCount,
+            unfinishedTaskCount: list.unfinishedTaskCount,
+        });
+    }
+    return {
+        level: "summary",
+        version: 1,
+        revision: summary.revision,
+        lists,
+    };
+}
 function toolResultText(result) {
     return (result.content ?? [])
         .filter((entry) => entry.type === "text")