@akira-tl/forgerelay 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [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
+
+- Added `workspace.tasks` with private file-backed Task Lists per persistent Workspace, preserving Task state across restart, close/reopen, managed-worktree backing replacement, and Composite close while keeping Task data out of project Git contents.
+
 ## [0.8.2] - 2026-08-31
 
 ### Changed

package/capabilities/workspace-tasks/GUIDE.md

@@ -0,0 +1,50 @@
+# Workspace Tasks
+
+`workspace.tasks` 维护当前 Workspace 自己的持久 Task Lists。它是轻量工作续接状态，不是执行队列、Subagent Session、Activity 或依赖图。
+
+## 使用边界
+
+- 只操作当前调用上下文中的 Workspace；参数中没有目标 `workspaceId`。
+- Task state 由 ForgeRelay 保存在私有 state directory，不写入 checkout 或 managed worktree。
+- 一个 Workspace 可以有多个 Task List；List 可为 `active` 或 `archived`。
+- Task 状态只有 `pending`、`in_progress`、`completed`。`content` 保存继续工作真正需要的要求、阻塞点、结论或下一步，而不是日志或对话转录。
+- Task/List ID 创建后保持稳定。完成 Task 不会删除它；删除必须显式执行。
+
+## 渐进式读取
+
+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 操作：
+
+- `list.create`：创建具名 List，可指定 `position`。
+- `list.update`：修改 `name`、`state` 或 `position`；`state="archived"` 用于归档，改回 `active` 即重新激活。
+- `list.delete`：显式删除 List 及其 Tasks。
+
+Task 操作：
+
+- `task.create`：在一个 List 中创建 Task；需要 `subject`，可提供 `content`、`status`、`position`。
+- `task.update`：修改 `subject`、`content`、`status` 或 `position`；至少提供一个变更字段。
+- `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/capabilities.js

@@ -39,6 +39,11 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
         description: "Read-only semantic code navigation backed by external Language servers.",
         whenToRead: "Read before using code.intelligence or configuring Language servers.",
     },
+    {
+        name: "workspace-tasks",
+        description: "Persistent Task Lists owned by the current Workspace.",
+        whenToRead: "Read before creating or maintaining Workspace Tasks.",
+    },
     {
         name: "batch-execution",
         description: "One-call execution of multiple independent ForgeRelay core operations.",
@@ -87,6 +92,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "hooks.lifecycle",
         "capability-guides.read",
         "code.intelligence",
+        "workspace.tasks",
     ];
     if (config.toolMode !== "codex") {
         capabilities.push("batch.execute");

package/dist/capability-registry.js

@@ -130,6 +130,66 @@ export function createCapabilityRegistry(dependencies) {
         line: z.number().int(),
         column: z.number().int(),
     };
+    const workspaceTaskStatus = z.enum(["pending", "in_progress", "completed"]);
+    const workspaceTaskListState = z.enum(["active", "archived"]);
+    const workspaceTasksInput = z.union([
+        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),
+            position: z.number().int().min(0).optional(),
+        }).strict(),
+        z.object({
+            operation: z.literal("list.update"),
+            listId: z.string().min(1),
+            name: z.string().trim().min(1).optional(),
+            state: workspaceTaskListState.optional(),
+            position: z.number().int().min(0).optional(),
+        }).strict().refine((input) => input.name !== undefined || input.state !== undefined || input.position !== undefined, { message: "list.update requires at least one field to change" }),
+        z.object({
+            operation: z.literal("list.delete"),
+            listId: z.string().min(1),
+        }).strict(),
+        z.object({
+            operation: z.literal("task.create"),
+            listId: z.string().min(1),
+            subject: z.string().trim().min(1),
+            content: z.string().optional(),
+            status: workspaceTaskStatus.optional(),
+            position: z.number().int().min(0).optional(),
+        }).strict(),
+        z.object({
+            operation: z.literal("task.update"),
+            listId: z.string().min(1),
+            taskId: z.string().min(1),
+            subject: z.string().trim().min(1).optional(),
+            content: z.string().optional(),
+            status: workspaceTaskStatus.optional(),
+            position: z.number().int().min(0).optional(),
+        }).strict().refine((input) => input.subject !== undefined
+            || input.content !== undefined
+            || input.status !== undefined
+            || input.position !== undefined, { message: "task.update requires at least one field to change" }),
+        z.object({
+            operation: z.literal("task.delete"),
+            listId: z.string().min(1),
+            taskId: z.string().min(1),
+        }).strict(),
+    ]);
     const subagentSessionInput = z.discriminatedUnion("operation", [
         z.object({
             operation: z.literal("start"),
@@ -190,11 +250,11 @@ export function createCapabilityRegistry(dependencies) {
             readGuideBeforeFirstUse: true,
             batchPolicy: "parallel",
             inputSchema: hooksCheckInput,
-            availability: () => ({ available: true }),
+            availability: (context) => filesystemWorkspaceAvailability(context),
             run: async (_input, context) => ({
                 value: {
                     ok: true,
-                    ...await dependencies.inspectHooks(context.workspaceRoot),
+                    ...await dependencies.inspectHooks(requireWorkspaceRoot(context)),
                 },
             }),
         },
@@ -206,10 +266,7 @@ export function createCapabilityRegistry(dependencies) {
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "serial",
                     inputSchema: z.object({}).strict(),
-                    availability: () => ({
-                        available: dependencies.reviewChanges?.available ?? false,
-                        reason: dependencies.reviewChanges?.unavailableReason,
-                    }),
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.reviewChanges?.available ?? false, dependencies.reviewChanges?.unavailableReason),
                     run: async (_input, context) => dependencies.reviewChanges.run(context),
                 }]
             : []),
@@ -221,11 +278,23 @@ export function createCapabilityRegistry(dependencies) {
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "parallel",
                     inputSchema: codeIntelligenceInput,
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.codeIntelligence?.available ?? false, dependencies.codeIntelligence?.unavailableReason),
+                    run: async (input, context, options) => dependencies.codeIntelligence.run(input, context, options),
+                }]
+            : []),
+        ...(dependencies.workspaceTasks
+            ? [{
+                    name: "workspace.tasks",
+                    description: "Maintain persistent Task Lists owned by the current Workspace.",
+                    guideName: "workspace-tasks",
+                    readGuideBeforeFirstUse: true,
+                    batchPolicy: "serial",
+                    inputSchema: workspaceTasksInput,
                     availability: () => ({
-                        available: dependencies.codeIntelligence?.available ?? false,
-                        reason: dependencies.codeIntelligence?.unavailableReason,
+                        available: dependencies.workspaceTasks?.available ?? false,
+                        reason: dependencies.workspaceTasks?.unavailableReason,
                     }),
-                    run: async (input, context, options) => dependencies.codeIntelligence.run(input, context, options),
+                    run: async (input, context, options) => dependencies.workspaceTasks.run(input, context, options),
                 }]
             : []),
         ...(dependencies.subagentSession
@@ -236,10 +305,7 @@ export function createCapabilityRegistry(dependencies) {
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "unsupported",
                     inputSchema: subagentSessionInput,
-                    availability: () => ({
-                        available: dependencies.subagentSession?.available ?? false,
-                        reason: dependencies.subagentSession?.unavailableReason,
-                    }),
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.subagentSession?.available ?? false, dependencies.subagentSession?.unavailableReason),
                     run: async (input, context, options) => dependencies.subagentSession.run(input, context, options),
                 }]
             : []),
@@ -251,10 +317,7 @@ export function createCapabilityRegistry(dependencies) {
                     readGuideBeforeFirstUse: true,
                     batchPolicy: "unsupported",
                     inputSchema: batchExecuteInputSchema,
-                    availability: () => ({
-                        available: dependencies.batchExecute?.available ?? false,
-                        reason: dependencies.batchExecute?.unavailableReason,
-                    }),
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.batchExecute?.available ?? false, dependencies.batchExecute?.unavailableReason),
                     run: async (input, context, options) => dependencies.batchExecute.run(input, context, options),
                 }]
             : []),
@@ -277,15 +340,27 @@ export function createCapabilityRegistry(dependencies) {
                         path: z.string().min(1),
                     }).strict(),
                     nativeFileArgument: "file",
-                    availability: () => ({
-                        available: dependencies.downloadArtifact?.available ?? false,
-                        reason: dependencies.downloadArtifact?.unavailableReason,
-                    }),
+                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.downloadArtifact?.available ?? false, dependencies.downloadArtifact?.unavailableReason),
                     run: async (input, context) => dependencies.downloadArtifact.run(input, context),
                 }]
             : []),
     ]);
 }
+function filesystemWorkspaceAvailability(context, available = true, reason) {
+    if (context.workspaceKind !== "workspace" || !context.workspaceRoot) {
+        return {
+            available: false,
+            reason: "This capability requires a filesystem-backed Workspace.",
+        };
+    }
+    return { available, ...(reason ? { reason } : {}) };
+}
+function requireWorkspaceRoot(context) {
+    if (context.workspaceKind !== "workspace" || !context.workspaceRoot) {
+        throw new CapabilityError("capability_unavailable", "This capability requires a filesystem-backed Workspace.");
+    }
+    return context.workspaceRoot;
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

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,21 @@ export class RemoteWorkspaceRelay {
         this.loadRoutes();
         return this.routes.has(workspaceId);
     }
+    inspectWorkspace(gatewayWorkspaceId) {
+        const route = this.requireRoute(gatewayWorkspaceId);
+        const resolved = this.remoteByInstance(route.remoteInstanceId);
+        return {
+            workspaceId: route.gatewayWorkspaceId,
+            kind: "workspace",
+            location: "relay",
+            root: route.root,
+            routeState: "known",
+            mode: route.mode,
+            ...(route.sourceRoot ? { sourceRoot: route.sourceRoot } : {}),
+            relay: resolved.alias,
+            executionLocation: `remote:${resolved.alias}`,
+        };
+    }
     async openWorkspace(alias, input, conversationScopeId) {
         const resolved = this.remoteByAlias(alias);
         let result;