@akira-tl/forgerelay 0.5.2 → 0.5.5

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.5.5] - 2026-08-15
+
+### Added
+
+- Added native multi-target `read`, `edit`, and `delete` operations so Agents can read several files or apply one validated edit/delete intent across multiple paths in a single interaction; bulk mutations preflight every target before the first filesystem change and report mutation-phase partial failures without claiming transactional rollback.
+- Added the `batch.execute` capability for 1–100 heterogeneous Read/Write/Edit/Rename/Delete/Bash/Capability tasks with caller-controlled concurrency from 1–10, stable input-order results, continue-on-error execution, conflict-aware scheduling, conservative Bash/serial-Capability exclusivity, and Host cancellation that never invents Activities for queued work that did not start.
+- Added durable parent/child Activity relationships and aggregate summaries for native bulk and Batch execution, while preserving lazy child detail, compact Bash responses plus stable `outputId`, and restart-safe local audit/query behavior.
+
+### Changed
+
+- Capability definitions now declare and advertise an explicit Batch policy (`parallel`, `serial`, or `unsupported`); `hooks.check` and `code.intelligence` are parallel, `review.changes` is serial, while Host-native artifact download and recursive `batch.execute` use are unsupported inside a Batch.
+- Core work operations now share one internal execution seam so single MCP calls and Batch children use the same path validation, Hooks, Activity lifecycle, logging, cancellation, and result semantics instead of duplicating tool handlers.
+
+## [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

package/capabilities/batch-execution/GUIDE.md

@@ -0,0 +1,18 @@
+# Batch execution
+
+Use `capability` with `name="batch.execute"` when several independent ForgeRelay core operations can be completed in one Agent interaction.
+
+## Contract
+
+- Every batch belongs to one already-open `workspaceId`.
+- Supply 1–100 tasks. Every task requires a unique stable `id`.
+- Supported operations are `read`, `write`, `edit`, `rename`, `delete`, `bash.run`, and `capability.run`.
+- Core tasks are single-target operations. Use native `read(paths)`, `edit(paths)`, or `delete(paths)` for one homogeneous operation over multiple targets instead of nesting bulk groups inside a batch.
+- `concurrency` may be 1–10. When omitted, ForgeRelay uses `min(task count, 10)`.
+- Independent tasks may run concurrently. Conflicting filesystem mutations are serialized automatically. `bash.run` is treated conservatively as exclusive work because a shell command may modify arbitrary workspace state.
+- Capability definitions explicitly advertise a batch policy: `parallel`, `serial`, or `unsupported`. Parallel capabilities may run concurrently; serial capabilities run exclusively in v0.5.5; unsupported capabilities return a task-level error while preserving the failed child Activity.
+- One task failure does not stop independent tasks. Results are returned in the same order as the input task list.
+- Host cancellation stops launching queued tasks and is propagated to already-running tasks.
+- Batch execution does not support nested batches, Workspace lifecycle calls, Activity query/control calls, or Bash process-control actions.
+
+Each actual task retains its normal ForgeRelay Hooks, Activity audit, validation, and result semantics. The Batch parent is an aggregate Activity and does not execute Tool Hooks itself.

package/dist/activity/audit-store.js

@@ -14,6 +14,15 @@ export class ActivityAuditStore {
                 if (existing.length > 0) {
                     throw new Error(`Activity ${input.activityId} already has audit events.`);
                 }
+                if (input.parentActivityId) {
+                    const parent = this.getActivity(input.parentActivityId);
+                    if (!parent) {
+                        throw new Error(`Unknown parent Activity: ${input.parentActivityId}.`);
+                    }
+                    if (parent.turnId !== input.turnId) {
+                        throw new Error(`Parent Activity ${input.parentActivityId} belongs to Host Turn ${parent.turnId}, not ${input.turnId}.`);
+                    }
+                }
             }
             else if (existing.length === 0 || existing[0]?.event_type !== "started") {
                 throw new Error(`Activity ${input.activityId} must start before recording ${input.type}.`);
@@ -28,6 +37,7 @@ export class ActivityAuditStore {
           sequence,
           event_type,
           turn_id,
+          parent_activity_id,
           conversation_scope_id,
           tool,
           workspace_id,
@@ -40,13 +50,31 @@ export class ActivityAuditStore {
           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);
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.id, row.activity_id, row.sequence, row.event_type, row.turn_id, row.parent_activity_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);
     }
+    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];
@@ -86,6 +114,7 @@ export class ActivityAuditStore {
         return {
             activityId: started.activityId,
             turnId: started.turnId,
+            ...(started.parentActivityId ? { parentActivityId: started.parentActivityId } : {}),
             ...(started.conversationScopeId ? { conversationScopeId: started.conversationScopeId } : {}),
             tool: started.tool,
             workspace: started.workspace,
@@ -114,6 +143,7 @@ function eventInputToRow(input, identity) {
             sequence: identity.sequence,
             event_type: input.type,
             turn_id: input.turnId,
+            parent_activity_id: input.parentActivityId ?? null,
             conversation_scope_id: input.conversationScopeId ?? null,
             tool: input.tool,
             workspace_id: input.workspace.id ?? null,
@@ -134,6 +164,7 @@ function eventInputToRow(input, identity) {
         sequence: identity.sequence,
         event_type: input.type,
         turn_id: null,
+        parent_activity_id: null,
         conversation_scope_id: null,
         tool: null,
         workspace_id: null,
@@ -164,6 +195,7 @@ function rowToEvent(row) {
                 ...base,
                 type: "started",
                 turnId: row.turn_id,
+                ...(row.parent_activity_id ? { parentActivityId: row.parent_activity_id } : {}),
                 ...(row.conversation_scope_id ? { conversationScopeId: row.conversation_scope_id } : {}),
                 tool: row.tool,
                 workspace: {

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,10 +4,12 @@ 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);
@@ -43,12 +45,15 @@ export class ActivityLifecycle {
     }
     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",
             activityId,
             turnId,
+            ...(options.parentActivityId ? { parentActivityId: options.parentActivityId } : {}),
             ...(options.conversationScopeId ? { conversationScopeId: options.conversationScopeId } : {}),
             tool: options.tool,
             workspace: options.workspace,
@@ -57,6 +62,7 @@ export class ActivityLifecycle {
         return {
             activityId,
             turnId,
+            ...(options.parentActivityId ? { parentActivityId: options.parentActivityId } : {}),
             ...(options.conversationScopeId ? { conversationScopeId: options.conversationScopeId } : {}),
         };
     }

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/query-service.js

@@ -0,0 +1,289 @@
+export class ActivityQueryService {
+    turns;
+    audit;
+    outputs;
+    constructor(turns, audit, outputs) {
+        this.turns = turns;
+        this.audit = audit;
+        this.outputs = outputs;
+    }
+    beginTurn(conversationScopeId) {
+        const turn = this.turns.begin(conversationScopeId);
+        return this.snapshot(turn.turnId);
+    }
+    currentTurnId(conversationScopeId) {
+        return this.turns.current(conversationScopeId)?.turnId;
+    }
+    snapshot(turnId, knownRevision) {
+        this.requireTurn(turnId);
+        const revision = this.audit.turnRevision(turnId);
+        const activities = this.summaries(turnId);
+        const state = aggregateState(activities);
+        const changed = knownRevision === undefined || knownRevision !== revision;
+        return {
+            turnId,
+            revision,
+            changed,
+            state,
+            activities: changed ? activities : [],
+        };
+    }
+    detail(turnId, activityId) {
+        this.requireTurn(turnId);
+        const record = this.audit.getActivity(activityId);
+        if (!record || record.turnId !== turnId) {
+            throw new Error(`Unknown Activity ${activityId} in Host Turn ${turnId}.`);
+        }
+        const activity = this.summaries(turnId)
+            .find((summary) => summary.activityId === activityId) ?? toSummary(record);
+        if (!activity.detailAvailable) {
+            throw new Error(`Activity ${activityId} is summary-complete and has no lazy detail.`);
+        }
+        return {
+            activity,
+            ...(record.request !== undefined ? { request: record.request } : {}),
+            ...(record.result !== undefined ? { result: record.result } : {}),
+            ...(record.error !== undefined ? { error: record.error } : {}),
+        };
+    }
+    bashOutput(turnId, outputId) {
+        this.requireTurn(turnId);
+        const output = this.outputs.read(outputId);
+        if (!output)
+            throw new Error(`Unknown Bash output: ${outputId}.`);
+        const activities = this.audit.listActivitiesByTurn(turnId);
+        const visible = activities.some((activity) => activity.activityId === output.activityId || activityOutputId(activity) === outputId);
+        if (!visible) {
+            throw new Error(`Bash output ${outputId} is not part of Host Turn ${turnId}.`);
+        }
+        return {
+            outputId: output.outputId,
+            activityId: output.activityId,
+            processId: output.processId,
+            command: output.command,
+            output: output.output,
+            status: output.status,
+            ...(output.exitCode !== undefined ? { exitCode: output.exitCode } : {}),
+            ...(output.signal !== undefined ? { signal: output.signal } : {}),
+            timedOut: output.timedOut,
+            startedAt: output.startedAt,
+            ...(output.finishedAt !== undefined ? { finishedAt: output.finishedAt } : {}),
+        };
+    }
+    summaries(turnId) {
+        const records = this.audit.listActivitiesByTurn(turnId);
+        const summaries = records.map(toSummary);
+        const children = new Map();
+        for (const summary of summaries) {
+            if (!summary.parentActivityId)
+                continue;
+            const aggregate = children.get(summary.parentActivityId) ?? {
+                total: 0,
+                working: 0,
+                done: 0,
+                error: 0,
+            };
+            aggregate.total += 1;
+            aggregate[summary.status] += 1;
+            children.set(summary.parentActivityId, aggregate);
+        }
+        return summaries.map((summary) => {
+            const aggregate = children.get(summary.activityId);
+            return aggregate
+                ? { ...summary, detailAvailable: false, children: aggregate }
+                : summary;
+        });
+    }
+    requireTurn(turnId) {
+        if (!this.turns.get(turnId))
+            throw new Error(`Unknown Host Turn: ${turnId}.`);
+    }
+}
+function toSummary(record) {
+    const request = asRecord(record.request);
+    const result = asRecord(record.result);
+    const structured = asRecord(result?.structuredContent);
+    const directProcessId = numberField(result, "processId") ?? numberField(request, "processId");
+    const processId = numberField(structured, "processId") ?? directProcessId;
+    const outputId = stringField(structured, "outputId")
+        ?? stringField(result, "outputId")
+        ?? stringField(request, "outputId");
+    const command = stringField(request, "command") ?? stringField(request, "cmd");
+    const durationMs = numberField(structured, "wallTimeMs")
+        ?? numberField(result, "wallTimeMs")
+        ?? elapsedMs(record.startedAt, record.updatedAt, record.state);
+    const bashLike = record.tool === "bash" || record.tool === "exec_command" || record.tool === "bash_result";
+    const bulkGroup = arrayField(request, "paths") !== undefined &&
+        (record.tool === "read" || record.tool === "edit" || record.tool === "delete");
+    return {
+        activityId: record.activityId,
+        ...(record.parentActivityId ? { parentActivityId: record.parentActivityId } : {}),
+        tool: record.tool,
+        kind: activityKind(record.tool),
+        status: activityStatus(record.state),
+        state: record.state,
+        title: activityTitle(record.tool),
+        target: activityTarget(record, request, result, structured),
+        detailAvailable: !bulkGroup && record.tool !== "rename" && record.tool !== "delete" && record.tool !== "batch",
+        ...(record.workspace.id ? { workspaceId: record.workspace.id } : {}),
+        ...(processId !== undefined ? { processId } : {}),
+        ...(outputId !== undefined ? { outputId } : {}),
+        ...(bashLike && command !== undefined ? { commandLength: command.length } : {}),
+        ...(bashLike ? { bashPhase: bashPhase(record.state) } : {}),
+        startedAt: record.startedAt,
+        ...(record.state !== "executing" ? { finishedAt: record.updatedAt } : {}),
+        ...(durationMs !== undefined ? { durationMs } : {}),
+    };
+}
+function activityKind(tool) {
+    if (tool === "read")
+        return "read";
+    if (tool === "write")
+        return "write";
+    if (tool === "edit" || tool === "apply_patch")
+        return "edit";
+    if (tool === "rename")
+        return "rename";
+    if (tool === "delete")
+        return "delete";
+    if (tool === "bash_result")
+        return "shell-result";
+    if (tool === "bash" || tool === "exec_command")
+        return "shell";
+    if (tool === "capability")
+        return "capability";
+    if (tool === "batch")
+        return "batch";
+    return "tool";
+}
+function activityTitle(tool) {
+    const titles = {
+        read: "Read",
+        write: "Write",
+        edit: "Edit",
+        apply_patch: "Edit",
+        rename: "Rename",
+        delete: "Delete",
+        bash: "Bash",
+        exec_command: "Command",
+        bash_result: "Bash result",
+        capability: "Capability",
+        batch: "Batch",
+    };
+    return titles[tool] ?? tool;
+}
+function activityTarget(record, request, result, structured) {
+    if (record.tool === "bash" || record.tool === "exec_command")
+        return "Shell command";
+    if (record.tool === "batch") {
+        const tasks = arrayField(request, "tasks");
+        return `${tasks?.length ?? 0} tasks`;
+    }
+    const paths = arrayField(request, "paths");
+    if (paths && paths.length > 0) {
+        if (record.tool === "read" || record.tool === "edit")
+            return `${paths.length} files`;
+        if (record.tool === "delete")
+            return `${paths.length} paths`;
+    }
+    if (record.tool === "bash_result") {
+        const processId = numberField(result, "processId") ?? numberField(request, "processId");
+        const exitCode = numberField(result, "exitCode");
+        const signal = stringField(result, "signal");
+        const timedOut = booleanField(result, "timedOut");
+        const outcome = timedOut
+            ? "timed out"
+            : signal
+                ? `signal ${signal}`
+                : exitCode !== undefined
+                    ? `exit ${exitCode}`
+                    : record.state === "failed"
+                        ? "failed"
+                        : "completed";
+        return `Process ${processId ?? "?"} · ${outcome}`;
+    }
+    if (record.tool === "capability") {
+        const name = stringField(request, "name") ?? "capability";
+        const action = stringField(request, "action") ?? "run";
+        return `${name} · ${action}`;
+    }
+    if (record.tool === "rename") {
+        const from = stringField(request, "path")
+            ?? stringField(request, "from")
+            ?? stringField(request, "source");
+        const to = stringField(request, "newPath")
+            ?? stringField(request, "to")
+            ?? stringField(request, "destination");
+        return [from, to].filter((value) => Boolean(value)).join(" → ") || "path";
+    }
+    const path = stringField(request, "path");
+    if (path)
+        return path;
+    if (record.tool === "apply_patch") {
+        const files = arrayField(structured, "files");
+        const first = asRecord(files?.[0]);
+        const firstPath = stringField(first, "path");
+        if (firstPath)
+            return files && files.length > 1 ? `${firstPath} +${files.length - 1}` : firstPath;
+    }
+    return record.tool;
+}
+function activityStatus(state) {
+    if (state === "executing")
+        return "working";
+    if (state === "failed" || state === "blocked")
+        return "error";
+    return "done";
+}
+function bashPhase(state) {
+    if (state === "executing")
+        return "executing";
+    if (state === "returned")
+        return "returned";
+    if (state === "failed" || state === "blocked")
+        return "error";
+    return "done";
+}
+function aggregateState(activities) {
+    if (activities.length === 0)
+        return "working";
+    if (activities.some((activity) => activity.status === "working"))
+        return "working";
+    if (activities.some((activity) => activity.status === "error"))
+        return "error";
+    return "done";
+}
+function activityOutputId(activity) {
+    const request = asRecord(activity.request);
+    const result = asRecord(activity.result);
+    const structured = asRecord(result?.structuredContent);
+    return stringField(request, "outputId")
+        ?? stringField(result, "outputId")
+        ?? stringField(structured, "outputId");
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stringField(record, key) {
+    return typeof record?.[key] === "string" ? record[key] : undefined;
+}
+function numberField(record, key) {
+    return typeof record?.[key] === "number" ? record[key] : undefined;
+}
+function booleanField(record, key) {
+    return typeof record?.[key] === "boolean" ? record[key] : undefined;
+}
+function arrayField(record, key) {
+    return Array.isArray(record?.[key]) ? record[key] : undefined;
+}
+function elapsedMs(startedAt, updatedAt, state) {
+    if (state === "executing")
+        return undefined;
+    const start = Date.parse(startedAt);
+    const end = Date.parse(updatedAt);
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return undefined;
+    return Math.max(0, end - start);
+}

package/dist/capabilities.js

@@ -39,6 +39,12 @@ 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: "batch-execution",
+        description: "One-call execution of multiple independent ForgeRelay core operations.",
+        whenToRead: "Read before using batch.execute for heterogeneous multi-operation work.",
+        enabled: (config) => config.toolMode !== "codex",
+    },
 ];
 function capabilityGuidesDir() {
     return fileURLToPath(new URL("../capabilities", import.meta.url));
@@ -82,6 +88,9 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "capability-guides.read",
         "code.intelligence",
     ];
+    if (config.toolMode !== "codex") {
+        capabilities.push("batch.execute");
+    }
     if (config.subagents) {
         capabilities.push("subagent.profiles");
     }