@akira-tl/forgerelay 0.5.1 → 0.5.4

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.5.4] - 2026-08-15
+
+### Fixed
+
+- Closed all Activity query SQLite handles before temporary-state cleanup so the backend acceptance suite also passes on Windows, where open database files cannot be unlinked.
+
+## [0.5.3] - 2026-08-15
+
+### Added
+
+- Added durable Host Turn records and a stable Activity query projection backed by ForgeRelay's local SQLite audit history, with revision-based lightweight snapshots that remain queryable after ForgeRelay restarts.
+- Added the production backend query contract for future MCP App UI: model-visible `activity_panel` establishes a Host Turn, while app-only `activity_snapshot`, `activity_detail`, and `activity_output` data sources expose summaries, selected lazy detail, and complete Bash output separately.
+
+### Changed
+
+- Activity snapshots now use an explicit summary whitelist: read bodies, write/edit patches, full Bash commands/output, and capability-heavy payloads stay out of normal snapshots; rename/delete include complete path targets and are summary-complete without detail requests.
+- Late Bash completion records use the current Host Turn for delivery while preserving the original Bash Activity's immutable returned history and Workspace audit snapshot.
+
+## [0.5.2] - 2026-08-15
+
+### Added
+
+- Added durable Bash output audit streams in ForgeRelay's local SQLite state: complete commands and original stdout/stderr/PTY output are retained under a stable `outputId`, can be retrieved after restart through regular Bash or Codex-compatible process tooling, and remain independent of the bounded in-memory process buffer.
+- Background commands that were previously returned to the Host now produce a separate durable `bash_result` Activity exactly once when their completion is delivered, while the original Bash Activity remains historical `returned` state.
+
+### Changed
+
+- Normal Bash, `exec_command`, and process-control responses now keep Agent context compact by returning only the final 10 output lines plus the stable full-output identifier; explicit output lookup returns the complete persisted process output.
+
 ## [0.5.1] - 2026-08-14
 
 ### Added

package/dist/activity/audit-store.js

@@ -47,6 +47,24 @@ export class ActivityAuditStore {
     listEvents(activityId) {
         return this.readRows(activityId).map(rowToEvent);
     }
+    listActivitiesByTurn(turnId) {
+        const rows = this.database.sqlite.prepare(`select activity_id from activity_audit_events
+       where event_type = 'started' and turn_id = ?
+       order by rowid asc`).all(turnId);
+        return rows.flatMap(({ activity_id }) => {
+            const activity = this.getActivity(activity_id);
+            return activity ? [activity] : [];
+        });
+    }
+    turnRevision(turnId) {
+        const row = this.database.sqlite.prepare(`select count(*) as revision
+       from activity_audit_events
+       where activity_id in (
+         select activity_id from activity_audit_events
+         where event_type = 'started' and turn_id = ?
+       )`).get(turnId);
+        return row.revision;
+    }
     getActivity(activityId) {
         const events = this.listEvents(activityId);
         const started = events[0];

package/dist/activity/bash-output-store.js

@@ -0,0 +1,127 @@
+import { randomUUID } from "node:crypto";
+import { StringDecoder } from "node:string_decoder";
+import { openDatabase } from "../db/client.js";
+export class BashOutputStore {
+    database;
+    now;
+    nextOutputId;
+    nextSequences = new Map();
+    constructor(stateDir, options = {}) {
+        this.database = openDatabase(stateDir);
+        this.now = options.now ?? (() => new Date());
+        this.nextOutputId = options.outputId ?? (() => `out_${randomUUID().replaceAll("-", "")}`);
+    }
+    begin(input) {
+        const outputId = this.nextOutputId();
+        const startedAt = this.now().toISOString();
+        this.database.sqlite.prepare(`insert into bash_output_streams (
+        id, activity_id, turn_id, conversation_scope_id, process_id,
+        workspace_id, workspace_root, command, tty, status, timed_out, started_at
+      ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', 0, ?)`).run(outputId, input.activityId, input.turnId, input.conversationScopeId ?? null, input.processId, input.workspaceId, input.workspaceRoot, input.command, input.tty ? 1 : 0, startedAt);
+        this.nextSequences.set(outputId, 1);
+        return outputId;
+    }
+    append(outputId, channel, data) {
+        const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+        if (bytes.length === 0)
+            return;
+        const sequence = this.nextSequence(outputId);
+        this.database.sqlite.prepare(`insert into bash_output_chunks (output_id, sequence, channel, data, created_at)
+       values (?, ?, ?, ?, ?)`).run(outputId, sequence, channel, bytes, this.now().toISOString());
+    }
+    markReturned(outputId) {
+        this.database.sqlite.prepare("update bash_output_streams set returned = 1 where id = ?").run(outputId);
+    }
+    claimCompletion(outputId) {
+        const claimedAt = this.now().toISOString();
+        const claimed = this.database.sqlite.prepare(`update bash_output_streams
+       set completion_claimed_at = ?
+       where id = ? and returned = 1 and status != 'running' and completion_claimed_at is null`).run(claimedAt, outputId);
+        return claimed.changes === 1 ? this.read(outputId) : undefined;
+    }
+    finish(outputId, input) {
+        const status = input.error || input.timedOut || input.signal || (input.exitCode !== undefined && input.exitCode !== 0)
+            ? "failed"
+            : "done";
+        this.database.sqlite.prepare(`update bash_output_streams
+       set status = ?, exit_code = ?, signal = ?, timed_out = ?, error = ?, finished_at = ?
+       where id = ?`).run(status, input.exitCode ?? null, input.signal ?? null, input.timedOut ? 1 : 0, input.error ?? null, this.now().toISOString(), outputId);
+    }
+    read(outputId) {
+        const stream = this.database.sqlite.prepare("select * from bash_output_streams where id = ?").get(outputId);
+        if (!stream)
+            return undefined;
+        const rows = this.database.sqlite.prepare(`select * from bash_output_chunks
+       where output_id = ?
+       order by sequence asc`).all(outputId);
+        const decoded = decodeChunks(rows);
+        return {
+            outputId: stream.id,
+            activityId: stream.activity_id,
+            turnId: stream.turn_id,
+            ...(stream.conversation_scope_id ? { conversationScopeId: stream.conversation_scope_id } : {}),
+            processId: stream.process_id,
+            workspaceId: stream.workspace_id,
+            workspaceRoot: stream.workspace_root,
+            command: stream.command,
+            tty: stream.tty === 1,
+            output: decoded.map((chunk) => chunk.data).join(""),
+            chunks: decoded,
+            status: isBashOutputStatus(stream.status) ? stream.status : "failed",
+            ...(stream.exit_code !== null ? { exitCode: stream.exit_code } : {}),
+            ...(stream.signal ? { signal: stream.signal } : {}),
+            timedOut: stream.timed_out === 1,
+            ...(stream.error ? { error: stream.error } : {}),
+            returned: stream.returned === 1,
+            startedAt: stream.started_at,
+            ...(stream.finished_at ? { finishedAt: stream.finished_at } : {}),
+        };
+    }
+    close() {
+        this.database.close();
+    }
+    nextSequence(outputId) {
+        const known = this.nextSequences.get(outputId);
+        if (known !== undefined) {
+            this.nextSequences.set(outputId, known + 1);
+            return known;
+        }
+        const row = this.database.sqlite.prepare("select coalesce(max(sequence), 0) as sequence from bash_output_chunks where output_id = ?").get(outputId);
+        const sequence = row.sequence + 1;
+        this.nextSequences.set(outputId, sequence + 1);
+        return sequence;
+    }
+}
+function decodeChunks(rows) {
+    const decoders = new Map();
+    const chunks = [];
+    const lastChunkIndex = new Map();
+    for (const row of rows) {
+        if (!isBashOutputChannel(row.channel)) {
+            throw new Error(`Unknown Bash output channel: ${row.channel}`);
+        }
+        const decoder = decoders.get(row.channel) ?? new StringDecoder("utf8");
+        decoders.set(row.channel, decoder);
+        const data = decoder.write(row.data);
+        chunks.push({ sequence: row.sequence, channel: row.channel, data });
+        lastChunkIndex.set(row.channel, chunks.length - 1);
+    }
+    for (const [channel, decoder] of decoders) {
+        const tail = decoder.end();
+        if (!tail)
+            continue;
+        const index = lastChunkIndex.get(channel);
+        if (index === undefined)
+            continue;
+        const chunk = chunks[index];
+        if (chunk)
+            chunk.data += tail;
+    }
+    return chunks;
+}
+function isBashOutputChannel(value) {
+    return value === "stdout" || value === "stderr" || value === "pty" || value === "process";
+}
+function isBashOutputStatus(value) {
+    return value === "running" || value === "done" || value === "failed";
+}

package/dist/activity/host-turn-store.js

@@ -0,0 +1,46 @@
+import { randomUUID } from "node:crypto";
+import { openDatabase } from "../db/client.js";
+export class HostTurnStore {
+    database;
+    now;
+    nextTurnId;
+    constructor(stateDir, options = {}) {
+        this.database = openDatabase(stateDir);
+        this.now = options.now ?? (() => new Date());
+        this.nextTurnId = options.turnId ?? (() => `turn_${randomUUID().replaceAll("-", "")}`);
+    }
+    begin(conversationScopeId) {
+        const turnId = this.nextTurnId();
+        const createdAt = this.now().toISOString();
+        this.database.sqlite.prepare(`insert into activity_host_turns (turn_id, conversation_scope_id, created_at)
+       values (?, ?, ?)`).run(turnId, conversationScopeId ?? null, createdAt);
+        return {
+            turnId,
+            ...(conversationScopeId ? { conversationScopeId } : {}),
+            createdAt,
+        };
+    }
+    get(turnId) {
+        const row = this.database.sqlite.prepare("select * from activity_host_turns where turn_id = ?").get(turnId);
+        return row ? rowToTurn(row) : undefined;
+    }
+    current(conversationScopeId) {
+        if (!conversationScopeId)
+            return undefined;
+        const row = this.database.sqlite.prepare(`select * from activity_host_turns
+       where conversation_scope_id = ?
+       order by rowid desc
+       limit 1`).get(conversationScopeId);
+        return row ? rowToTurn(row) : undefined;
+    }
+    close() {
+        this.database.close();
+    }
+}
+function rowToTurn(row) {
+    return {
+        turnId: row.turn_id,
+        ...(row.conversation_scope_id ? { conversationScopeId: row.conversation_scope_id } : {}),
+        createdAt: row.created_at,
+    };
+}

package/dist/activity/lifecycle.js

@@ -4,14 +4,50 @@ export class ActivityLifecycle {
     auditStore;
     activityId;
     turnId;
+    turnIdForConversation;
     constructor(auditStore, options = {}) {
         this.auditStore = auditStore;
         this.activityId = options.activityId ?? newActivityId;
         this.turnId = options.turnId ?? newTurnId;
+        this.turnIdForConversation = options.turnIdForConversation;
+    }
+    record(options) {
+        const context = this.start(options);
+        this.finish(context.activityId, options.result, options.outcome);
+        return context;
+    }
+    recordLinked(options) {
+        const source = this.auditStore.getActivity(options.sourceActivityId);
+        if (!source)
+            throw new Error(`Unknown source Activity: ${options.sourceActivityId}`);
+        const { sourceActivityId: _sourceActivityId, ...record } = options;
+        return this.record({
+            ...record,
+            ...(source.conversationScopeId ? { conversationScopeId: source.conversationScopeId } : {}),
+            workspace: source.workspace,
+        });
     }
     async run(options) {
+        const executionContext = this.start(options);
+        const activityId = executionContext.activityId;
+        try {
+            const result = await options.operation(executionContext);
+            this.finish(activityId, result, options.outcome?.(result) ?? { type: "succeeded" });
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.auditStore.append(error instanceof HookExecutionError && error.event === "BeforeTool"
+                ? { type: "blocked", activityId, error: message }
+                : { type: "failed", activityId, error: message });
+            throw error;
+        }
+    }
+    start(options) {
         const activityId = options.activityId ?? this.activityId();
-        const turnId = options.turnId ?? this.turnId();
+        const turnId = options.turnId
+            ?? this.turnIdForConversation?.(options.conversationScopeId)
+            ?? this.turnId();
         const request = normalizeAuditValue(options.request);
         this.auditStore.append({
             type: "started",
@@ -22,36 +58,31 @@ export class ActivityLifecycle {
             workspace: options.workspace,
             ...(request !== undefined ? { request } : {}),
         });
-        try {
-            const result = await options.operation();
-            const normalizedResult = normalizeAuditValue(result);
-            const outcome = options.outcome?.(result) ?? { type: "succeeded" };
-            switch (outcome.type) {
-                case "succeeded":
-                case "returned":
-                    this.auditStore.append({
-                        type: outcome.type,
-                        activityId,
-                        ...(normalizedResult !== undefined ? { result: normalizedResult } : {}),
-                    });
-                    break;
-                case "failed":
-                    this.auditStore.append({
-                        type: "failed",
-                        activityId,
-                        ...(normalizedResult !== undefined ? { result: normalizedResult } : {}),
-                        error: outcome.error,
-                    });
-                    break;
-            }
-            return result;
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            this.auditStore.append(error instanceof HookExecutionError && error.event === "BeforeTool"
-                ? { type: "blocked", activityId, error: message }
-                : { type: "failed", activityId, error: message });
-            throw error;
+        return {
+            activityId,
+            turnId,
+            ...(options.conversationScopeId ? { conversationScopeId: options.conversationScopeId } : {}),
+        };
+    }
+    finish(activityId, result, outcome) {
+        const normalizedResult = normalizeAuditValue(result);
+        switch (outcome.type) {
+            case "succeeded":
+            case "returned":
+                this.auditStore.append({
+                    type: outcome.type,
+                    activityId,
+                    ...(normalizedResult !== undefined ? { result: normalizedResult } : {}),
+                });
+                break;
+            case "failed":
+                this.auditStore.append({
+                    type: "failed",
+                    activityId,
+                    ...(normalizedResult !== undefined ? { result: normalizedResult } : {}),
+                    error: outcome.error,
+                });
+                break;
         }
     }
 }

package/dist/activity/mcp-query-tools.js

@@ -0,0 +1,129 @@
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import * as z from "zod/v4";
+import { openAiConversationScopeId } from "../request-meta.js";
+const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+const activitySummarySchema = z.object({
+    activityId: z.string(),
+    tool: z.string(),
+    kind: z.string(),
+    status: z.enum(["working", "done", "error"]),
+    state: z.enum(["executing", "returned", "done", "failed", "blocked"]),
+    title: z.string(),
+    target: z.string(),
+    detailAvailable: z.boolean(),
+    workspaceId: z.string().optional(),
+    processId: z.number().int().positive().optional(),
+    outputId: z.string().optional(),
+    commandLength: z.number().int().nonnegative().optional(),
+    bashPhase: z.enum(["executing", "returned", "done", "error"]).optional(),
+    startedAt: z.string(),
+    finishedAt: z.string().optional(),
+    durationMs: z.number().nonnegative().optional(),
+});
+const snapshotOutputSchema = {
+    turnId: z.string(),
+    revision: z.number().int().nonnegative(),
+    changed: z.boolean(),
+    state: z.enum(["working", "done", "error"]),
+    activities: z.array(activitySummarySchema),
+};
+export function registerActivityQueryTools(server, queries) {
+    registerAppTool(server, "activity_panel", {
+        title: "Begin Activity Panel",
+        description: "Begin one ForgeRelay Host Turn lifecycle for subsequent project work. This orchestration call does not read or modify project files. Call it once before the first ForgeRelay work operation in a Host Turn that performs project work.",
+        inputSchema: {},
+        outputSchema: snapshotOutputSchema,
+        _meta: { ui: { visibility: ["model", "app"] } },
+        annotations: {
+            ...READ_ONLY_ANNOTATIONS,
+            idempotentHint: false,
+        },
+    }, async (_input, extra) => {
+        const snapshot = queries.beginTurn(openAiConversationScopeId(extra._meta));
+        return {
+            content: [{
+                    type: "text",
+                    text: `Started ForgeRelay Activity Panel Host Turn ${snapshot.turnId}.`,
+                }],
+            structuredContent: { ...snapshot },
+        };
+    });
+    registerAppTool(server, "activity_snapshot", {
+        title: "Read Activity snapshot",
+        description: "App-only data source for lightweight Activity summaries in one durable Host Turn.",
+        inputSchema: {
+            turnId: z.string(),
+            knownRevision: z.number().int().nonnegative().optional(),
+        },
+        outputSchema: snapshotOutputSchema,
+        _meta: { ui: { visibility: ["app"] } },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async ({ turnId, knownRevision }) => {
+        const snapshot = queries.snapshot(turnId, knownRevision);
+        return {
+            content: [{
+                    type: "text",
+                    text: snapshot.changed
+                        ? `Activity snapshot ${turnId} revision ${snapshot.revision}.`
+                        : `Activity snapshot ${turnId} unchanged at revision ${snapshot.revision}.`,
+                }],
+            structuredContent: { ...snapshot },
+        };
+    });
+    registerAppTool(server, "activity_detail", {
+        title: "Read Activity detail",
+        description: "App-only lazy data source for one selected expandable Activity.",
+        inputSchema: {
+            turnId: z.string(),
+            activityId: z.string(),
+        },
+        outputSchema: {
+            activity: activitySummarySchema,
+            request: z.unknown().optional(),
+            result: z.unknown().optional(),
+            error: z.string().optional(),
+        },
+        _meta: { ui: { visibility: ["app"] } },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async ({ turnId, activityId }) => {
+        const detail = queries.detail(turnId, activityId);
+        return {
+            content: [{ type: "text", text: `Activity detail ${activityId}.` }],
+            structuredContent: { ...detail },
+        };
+    });
+    registerAppTool(server, "activity_output", {
+        title: "Read Bash output",
+        description: "App-only lazy data source for complete durable Bash command/output by stable outputId.",
+        inputSchema: {
+            turnId: z.string(),
+            outputId: z.string(),
+        },
+        outputSchema: {
+            outputId: z.string(),
+            activityId: z.string(),
+            processId: z.number().int().positive(),
+            command: z.string(),
+            output: z.string(),
+            status: z.enum(["running", "done", "failed"]),
+            exitCode: z.number().int().optional(),
+            signal: z.string().optional(),
+            timedOut: z.boolean(),
+            startedAt: z.string(),
+            finishedAt: z.string().optional(),
+        },
+        _meta: { ui: { visibility: ["app"] } },
+        annotations: READ_ONLY_ANNOTATIONS,
+    }, async ({ turnId, outputId }) => {
+        const output = queries.bashOutput(turnId, outputId);
+        return {
+            content: [{ type: "text", text: `Bash output ${outputId}.` }],
+            structuredContent: { ...output },
+        };
+    });
+}

package/dist/activity/process-output-audit.js

@@ -0,0 +1 @@
+export {};