@akira-tl/forgerelay 0.4.6 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-14
+
+### Added
+
+- Added the production local Activity audit foundation: append-only Audit Events persist in ForgeRelay's existing SQLite state, queryable Activity Records survive server restarts and Workspace cleanup, and success, failure, and Hook-blocked outcomes retain immutable Workspace/Host Turn execution context for later lifecycle and UI releases.
+
+## [0.4.7] - 2026-08-11
+
+### Added
+
+- Added independent `bash` execution deadlines with optional `timeoutMs`; `yieldTimeMs` now remains purely a feedback window, including `yieldTimeMs: 0` for immediate background handoff to a canonical `processId`.
+
+### Changed
+
+- Regular `bash` now defaults to a 10-second feedback window instead of occupying a full 300-second Host request; Agent-selected waits can still be up to 300 seconds, while execution can continue without a ForgeRelay deadline when `timeoutMs` is omitted.
+- Completed background processes keep full buffered output for five minutes, then compact to a bounded completion record deliverable for up to 24 hours. Completed results no longer block workspace close and are delivered with the close response when available.
+- Local `release:verify` now records a proof for the committed release HEAD, while the stable-tag `BeforeTool` Hook performs only a fast proof/HEAD/version/tag check before the push instead of rerunning the multi-minute release gate inside one MCP request.
+
+### Fixed
+
+- Propagated Host request cancellation through lifecycle Hooks and shell process waits. If a Host cancels while a blocking `BeforeTool` Hook is still running, ForgeRelay terminates the Hook and does not execute the original tool side effect; cancellation of an initial shell run also terminates a process whose `processId` has not yet been delivered.
+- Corrected `ProcessManager` yield bounding so a configured maximum also caps the default feedback window rather than only explicit `yieldTimeMs` values.
+- Made the new release-proof and Hook-cancellation test harnesses use cross-platform Node path and shell invocation forms, covering Windows drive-letter paths and `cmd.exe` Hook execution as well as POSIX hosts.
+
 ## [0.4.6] - 2026-08-11
 
 ### Added

package/README.md

@@ -163,13 +163,13 @@ Hook 是 ForgeRelay 的自动生命周期规则。首选方式是一个 Hook 一
     "tool": "bash",
     "commandRegex": "git\\s+push\\s+origin\\s+v\\d+\\.\\d+\\.\\d+"
   },
-  "command": "npm run release:verify",
-  "timeoutSeconds": 300,
+  "command": "node scripts/release-proof.mjs check-hook",
+  "timeoutSeconds": 30,
   "report": true
 }
 ```
 
-命中 `BeforeTool` 后，Hook 先执行；成功才继续原始 `git push`，失败则直接阻断。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
+耗时的 `npm run release:verify` 应先在已提交的 release-ready HEAD 上运行，它会写入绑定 HEAD/package version 的本地 release proof。命中 `BeforeTool` 后，Hook 只快速验证该 proof、clean working tree（含 untracked）与 tag 指向；成功才继续原始 `git push`，失败则直接阻断。这样发布 gate 不依赖一个持续数分钟的 MCP 请求。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
 
 旧的 inline `hooks` 和聚合 `hooks.json` 仍兼容；新配置建议都用独立 `hooks/*.json` 文件。
 
@@ -292,10 +292,11 @@ npm run release:major
 npm run release:verify
 ```
 
-Daily branch pushes do not run cloud CI. When preparing a release, run the full
-local release verification first. `release:verify` includes a focused parity pass
-in an isolated Node 22.19.0 environment with its own `npm ci`, matching the cloud
-CI runtime for native addons and high-risk LSP lifecycle tests. Pushing a matching
+Daily branch pushes do not run cloud CI. When preparing a release, commit the
+release-ready tree and run the full local release verification on that clean HEAD.
+`release:verify` includes a focused parity pass in an isolated Node 22.19.0 environment
+with its own `npm ci`, matching the cloud CI runtime for native addons and high-risk
+LSP lifecycle tests, then writes the local proof consumed by the tag-push Hook. Pushing a matching
 `vX.Y.Z` tag to `Akira-TL/forgerelay` is the only cloud CI and publish trigger:
 GitHub Actions runs the reusable multi-platform CI, then publishes
 `@akira-tl/forgerelay` and creates the matching GitHub Release only after CI

package/dist/activity/audit-store.js

@@ -0,0 +1,209 @@
+import { randomUUID } from "node:crypto";
+import { openDatabase } from "../db/client.js";
+export class ActivityAuditStore {
+    database;
+    now;
+    constructor(stateDir, options = {}) {
+        this.database = openDatabase(stateDir);
+        this.now = options.now ?? (() => new Date());
+    }
+    append(input) {
+        return this.database.sqlite.transaction(() => {
+            const existing = this.readRows(input.activityId);
+            if (input.type === "started") {
+                if (existing.length > 0) {
+                    throw new Error(`Activity ${input.activityId} already has audit events.`);
+                }
+            }
+            else if (existing.length === 0 || existing[0]?.event_type !== "started") {
+                throw new Error(`Activity ${input.activityId} must start before recording ${input.type}.`);
+            }
+            const sequence = existing.length + 1;
+            const id = `evt_${randomUUID().replaceAll("-", "")}`;
+            const createdAt = this.now().toISOString();
+            const row = eventInputToRow(input, { id, sequence, createdAt });
+            this.database.sqlite.prepare(`insert into activity_audit_events (
+          id,
+          activity_id,
+          sequence,
+          event_type,
+          turn_id,
+          conversation_scope_id,
+          tool,
+          workspace_id,
+          workspace_root,
+          workspace_mode,
+          workspace_source_root,
+          workspace_branch,
+          workspace_target_branch,
+          request_json,
+          result_json,
+          error,
+          created_at
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.id, row.activity_id, row.sequence, row.event_type, row.turn_id, row.conversation_scope_id, row.tool, row.workspace_id, row.workspace_root, row.workspace_mode, row.workspace_source_root, row.workspace_branch, row.workspace_target_branch, row.request_json, row.result_json, row.error, row.created_at);
+            return rowToEvent(row);
+        })();
+    }
+    listEvents(activityId) {
+        return this.readRows(activityId).map(rowToEvent);
+    }
+    getActivity(activityId) {
+        const events = this.listEvents(activityId);
+        const started = events[0];
+        if (!started || started.type !== "started")
+            return undefined;
+        let state = "executing";
+        let result;
+        let error;
+        let updatedAt = started.createdAt;
+        for (const event of events.slice(1)) {
+            updatedAt = event.createdAt;
+            switch (event.type) {
+                case "started":
+                    break;
+                case "succeeded":
+                    state = "done";
+                    result = event.result;
+                    error = undefined;
+                    break;
+                case "failed":
+                    state = "failed";
+                    result = event.result;
+                    error = event.error;
+                    break;
+                case "blocked":
+                    state = "blocked";
+                    result = undefined;
+                    error = event.error;
+                    break;
+            }
+        }
+        return {
+            activityId: started.activityId,
+            turnId: started.turnId,
+            ...(started.conversationScopeId ? { conversationScopeId: started.conversationScopeId } : {}),
+            tool: started.tool,
+            workspace: started.workspace,
+            state,
+            ...(started.request !== undefined ? { request: started.request } : {}),
+            ...(result !== undefined ? { result } : {}),
+            ...(error !== undefined ? { error } : {}),
+            startedAt: started.createdAt,
+            updatedAt,
+        };
+    }
+    close() {
+        this.database.close();
+    }
+    readRows(activityId) {
+        return this.database.sqlite.prepare(`select * from activity_audit_events
+       where activity_id = ?
+       order by sequence asc`).all(activityId);
+    }
+}
+function eventInputToRow(input, identity) {
+    if (input.type === "started") {
+        return {
+            id: identity.id,
+            activity_id: input.activityId,
+            sequence: identity.sequence,
+            event_type: input.type,
+            turn_id: input.turnId,
+            conversation_scope_id: input.conversationScopeId ?? null,
+            tool: input.tool,
+            workspace_id: input.workspace.id ?? null,
+            workspace_root: input.workspace.root,
+            workspace_mode: input.workspace.mode,
+            workspace_source_root: input.workspace.sourceRoot ?? null,
+            workspace_branch: input.workspace.branch ?? null,
+            workspace_target_branch: input.workspace.targetBranch ?? null,
+            request_json: serializeJson(input.request),
+            result_json: null,
+            error: null,
+            created_at: identity.createdAt,
+        };
+    }
+    return {
+        id: identity.id,
+        activity_id: input.activityId,
+        sequence: identity.sequence,
+        event_type: input.type,
+        turn_id: null,
+        conversation_scope_id: null,
+        tool: null,
+        workspace_id: null,
+        workspace_root: null,
+        workspace_mode: null,
+        workspace_source_root: null,
+        workspace_branch: null,
+        workspace_target_branch: null,
+        request_json: null,
+        result_json: "result" in input ? serializeJson(input.result) : null,
+        error: "error" in input ? input.error : null,
+        created_at: identity.createdAt,
+    };
+}
+function rowToEvent(row) {
+    const base = {
+        id: row.id,
+        activityId: row.activity_id,
+        sequence: row.sequence,
+        createdAt: row.created_at,
+    };
+    switch (row.event_type) {
+        case "started":
+            if (!row.turn_id || !row.tool || !row.workspace_root || !isWorkspaceMode(row.workspace_mode)) {
+                throw new Error(`Activity audit start event ${row.id} is missing required context.`);
+            }
+            return {
+                ...base,
+                type: "started",
+                turnId: row.turn_id,
+                ...(row.conversation_scope_id ? { conversationScopeId: row.conversation_scope_id } : {}),
+                tool: row.tool,
+                workspace: {
+                    ...(row.workspace_id ? { id: row.workspace_id } : {}),
+                    root: row.workspace_root,
+                    mode: row.workspace_mode,
+                    ...(row.workspace_source_root ? { sourceRoot: row.workspace_source_root } : {}),
+                    ...(row.workspace_branch ? { branch: row.workspace_branch } : {}),
+                    ...(row.workspace_target_branch ? { targetBranch: row.workspace_target_branch } : {}),
+                },
+                ...(row.request_json !== null ? { request: parseJson(row.request_json) } : {}),
+            };
+        case "succeeded":
+            return {
+                ...base,
+                type: "succeeded",
+                result: parseJson(row.result_json),
+            };
+        case "failed":
+            if (!row.error)
+                throw new Error(`Activity audit failed event ${row.id} is missing an error.`);
+            return {
+                ...base,
+                type: "failed",
+                result: parseJson(row.result_json),
+                error: row.error,
+            };
+        case "blocked":
+            if (!row.error)
+                throw new Error(`Activity audit blocked event ${row.id} is missing an error.`);
+            return {
+                ...base,
+                type: "blocked",
+                error: row.error,
+            };
+        default:
+            throw new Error(`Unknown Activity audit event type: ${row.event_type}`);
+    }
+}
+function isWorkspaceMode(value) {
+    return value === "checkout" || value === "worktree";
+}
+function serializeJson(value) {
+    return value === undefined ? null : JSON.stringify(value);
+}
+function parseJson(value) {
+    return value === null ? undefined : JSON.parse(value);
+}

package/dist/db/migrations.js

@@ -34,6 +34,11 @@ const migrations = [
         name: "workspace-context-deliveries",
         up: migrateWorkspaceContextDeliveries,
     },
+    {
+        version: 8,
+        name: "activity-audit",
+        up: migrateActivityAudit,
+    },
 ];
 export function migrateDatabase(sqlite) {
     const migrate = sqlite.transaction(() => {
@@ -208,6 +213,41 @@ function migrateWorkspaceContextDeliveries(sqlite) {
       on workspace_context_deliveries(delivered_at desc);
   `);
 }
+function migrateActivityAudit(sqlite) {
+    sqlite.exec(`
+    create table if not exists activity_audit_events (
+      id text primary key,
+      activity_id text not null,
+      sequence integer not null,
+      event_type text not null,
+      turn_id text,
+      conversation_scope_id text,
+      tool text,
+      workspace_id text,
+      workspace_root text,
+      workspace_mode text,
+      workspace_source_root text,
+      workspace_branch text,
+      workspace_target_branch text,
+      request_json text,
+      result_json text,
+      error text,
+      created_at text not null
+    );
+
+    create unique index if not exists activity_audit_events_activity_sequence_unique_idx
+      on activity_audit_events(activity_id, sequence);
+
+    create index if not exists activity_audit_events_activity_idx
+      on activity_audit_events(activity_id, sequence);
+
+    create index if not exists activity_audit_events_turn_idx
+      on activity_audit_events(turn_id, created_at);
+
+    create index if not exists activity_audit_events_created_idx
+      on activity_audit_events(created_at);
+  `);
+}
 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

@@ -1,4 +1,4 @@
-import { index, integer, primaryKey, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { index, integer, primaryKey, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
 export const workspaceSessions = sqliteTable("workspace_sessions", {
     id: text("id").primaryKey(),
     root: text("root").notNull(),
@@ -73,6 +73,30 @@ export const oauthRefreshTokens = sqliteTable("oauth_refresh_tokens", {
     expiresAt: integer("expires_at").notNull(),
     resource: text("resource"),
 });
+export const activityAuditEvents = sqliteTable("activity_audit_events", {
+    id: text("id").primaryKey(),
+    activityId: text("activity_id").notNull(),
+    sequence: integer("sequence").notNull(),
+    eventType: text("event_type").notNull(),
+    turnId: text("turn_id"),
+    conversationScopeId: text("conversation_scope_id"),
+    tool: text("tool"),
+    workspaceId: text("workspace_id"),
+    workspaceRoot: text("workspace_root"),
+    workspaceMode: text("workspace_mode"),
+    workspaceSourceRoot: text("workspace_source_root"),
+    workspaceBranch: text("workspace_branch"),
+    workspaceTargetBranch: text("workspace_target_branch"),
+    requestJson: text("request_json"),
+    resultJson: text("result_json"),
+    error: text("error"),
+    createdAt: text("created_at").notNull(),
+}, (table) => [
+    uniqueIndex("activity_audit_events_activity_sequence_unique_idx").on(table.activityId, table.sequence),
+    index("activity_audit_events_activity_idx").on(table.activityId, table.sequence),
+    index("activity_audit_events_turn_idx").on(table.turnId, table.createdAt),
+    index("activity_audit_events_created_idx").on(table.createdAt),
+]);
 export const localAgentSessions = sqliteTable("local_agent_sessions", {
     id: text("id").primaryKey(),
     workspaceId: text("workspace_id"),

package/dist/hooks.js

@@ -105,7 +105,8 @@ export async function runToolWithHooks(runner, options) {
         executions.push(...await runner.run("BeforeTool", {
             ...options.invocation,
             payload: basePayload,
-        }));
+        }, options.signal));
+        options.signal?.throwIfAborted();
         const result = await options.operation();
         const afterCwd = options.afterCwd?.(result);
         if (options.isFailure?.(result)) {
@@ -113,7 +114,7 @@ export async function runToolWithHooks(runner, options) {
                 ...options.invocation,
                 cwd: afterCwd,
                 payload: basePayload,
-            }));
+            }, options.signal));
             const reported = attachHookReports(result, executions);
             return decorateToolResult(runner, options.invocation.workspaceId, reported);
         }
@@ -121,14 +122,14 @@ export async function runToolWithHooks(runner, options) {
             ...options.invocation,
             cwd: afterCwd,
             payload: basePayload,
-        }));
+        }, options.signal));
         const changedPaths = options.changedPaths?.(result) ?? [];
         if (changedPaths.length > 0) {
             executions.push(...await runner.run("AfterFileChange", {
                 ...options.invocation,
                 cwd: afterCwd,
                 payload: { ...basePayload, paths: changedPaths },
-            }));
+            }, options.signal));
         }
         const reported = attachHookReports(result, executions);
         return decorateToolResult(runner, options.invocation.workspaceId, reported);
@@ -137,13 +138,15 @@ export async function runToolWithHooks(runner, options) {
         if (error instanceof HookExecutionError) {
             executions.push(...error.executions);
         }
-        executions.push(...await runner.run("AfterToolFailure", {
-            ...options.invocation,
-            payload: {
-                ...basePayload,
-                errorType: error instanceof Error ? error.name : "Error",
-            },
-        }));
+        if (!options.signal?.aborted) {
+            executions.push(...await runner.run("AfterToolFailure", {
+                ...options.invocation,
+                payload: {
+                    ...basePayload,
+                    errorType: error instanceof Error ? error.name : "Error",
+                },
+            }, options.signal));
+        }
         const reportedError = appendHookReportsToError(error, executions);
         throw decorateToolResult(runner, options.invocation.workspaceId, reportedError);
     }
@@ -219,7 +222,8 @@ export class HookRunner {
     decorateResult(workspaceId, result) {
         return (this.resultDecorator?.(workspaceId, result) ?? result);
     }
-    async run(event, invocation) {
+    async run(event, invocation, signal) {
+        signal?.throwIfAborted();
         const projectRoot = event === "AfterWorktreeClose" && invocation.sourceRoot
             ? invocation.sourceRoot
             : invocation.workspaceRoot;
@@ -246,7 +250,8 @@ export class HookRunner {
                 }]
             : [];
         for (const [index, { scope, handler, invocation: matchedInvocation }] of handlers.entries()) {
-            const execution = await this.runHandler(event, handler, index, matchedInvocation, scope);
+            signal?.throwIfAborted();
+            const execution = await this.runHandler(event, handler, index, matchedInvocation, scope, signal);
             executions.push(execution);
             logEvent(this.logging, execution.status === "passed" ? "info" : "warn", "hook_call", {
                 hookEvent: event,
@@ -267,7 +272,7 @@ export class HookRunner {
         }
         return executions;
     }
-    async runHandler(event, handler, index, invocation, scope) {
+    async runHandler(event, handler, index, invocation, scope, signal) {
         const startedAt = performance.now();
         const name = handler.name ?? `${event} handler ${index + 1}`;
         const shell = resolveShellCommand(handler.command, process.platform, this.baseEnv);
@@ -282,6 +287,7 @@ export class HookRunner {
                 env,
                 timeoutMs: handler.timeoutSeconds * 1_000,
                 detached,
+                signal,
             });
             const durationMs = Math.round(performance.now() - startedAt);
             if (result.exitCode === 0 && !result.timedOut) {
@@ -311,6 +317,8 @@ export class HookRunner {
             };
         }
         catch (error) {
+            if (signal?.aborted)
+                throw error;
             return {
                 event,
                 name,
@@ -522,6 +530,7 @@ function hookEnvironment(baseEnv, event, invocation) {
     };
 }
 function executeHookCommand(input) {
+    input.signal?.throwIfAborted();
     return new Promise((resolve, reject) => {
         const child = spawn(input.executable, input.args, {
             cwd: input.cwd,
@@ -535,6 +544,18 @@ function executeHookCommand(input) {
         let stderr = "";
         let timedOut = false;
         let forceKillTimer;
+        let aborted = false;
+        const abort = () => {
+            if (aborted)
+                return;
+            aborted = true;
+            terminateProcessTree(child, "SIGTERM", input.detached);
+            forceKillTimer = setTimeout(() => {
+                terminateProcessTree(child, "SIGKILL", input.detached);
+            }, 500);
+            forceKillTimer.unref();
+        };
+        input.signal?.addEventListener("abort", abort, { once: true });
         child.stdout?.on("data", (chunk) => {
             stdout = appendCaptured(stdout, chunk);
         });
@@ -554,12 +575,20 @@ function executeHookCommand(input) {
             clearTimeout(timeout);
             if (forceKillTimer)
                 clearTimeout(forceKillTimer);
+            input.signal?.removeEventListener("abort", abort);
             reject(error);
         });
         child.once("close", (exitCode, signal) => {
             clearTimeout(timeout);
             if (forceKillTimer)
                 clearTimeout(forceKillTimer);
+            input.signal?.removeEventListener("abort", abort);
+            if (aborted) {
+                reject(input.signal?.reason instanceof Error
+                    ? input.signal.reason
+                    : Object.assign(new Error("Hook execution cancelled by Host."), { name: "AbortError" }));
+                return;
+            }
             resolve({ exitCode, signal, stdout, stderr, timedOut });
         });
     });

package/dist/mcp/server-instructions.js

@@ -30,7 +30,7 @@ export function buildToolDescriptions(config) {
         rename: `Rename or move one file or directory inside an open workspace or the OS temp directory without overwriting an existing destination. Source and destination must both remain inside the permitted file roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         delete: `Delete one file or directory inside an open workspace or the OS temp directory. Non-empty directories require recursive=true. An allowed root itself cannot be deleted. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         applyPatch: `Apply one Codex-style patch inside an open workspace or the OS temp directory. Supports adding, overwriting, updating, deleting, and moving files. Workspace paths must remain relative; absolute paths are accepted only inside the OS temp directory. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        shell: `Run or manage a shell process inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. action=run (default) starts a command and waits up to 300 seconds; action=process uses its processId to poll, wait, write input, resize a PTY, or interrupt it. Completed background commands may also be reported later for the same workspaceId. Call ${toolNames.openWorkspace} first and pass workspaceId. Expose this capability only behind strong authentication.`,
+        shell: `Run or manage a shell process inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace containment does not make shell execution a sandbox. For action=run, yieldTimeMs is only the feedback wait (default 10000ms; 0 returns a processId immediately) and optional timeoutMs is the independent total execution limit. action=process polls/waits for incremental output, writes input, resizes a PTY, or interrupts by processId. Keep explicit waits below the Host request deadline; use 60000ms only when supported. Completed background results may be attached to a later result for the same workspaceId. Call ${toolNames.openWorkspace} first and pass workspaceId. Expose this capability only behind strong authentication.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };
 }