cloving 1.3.0 → 1.4.0

package/dist/src/broker/actor/stop-turn.js

@@ -11,23 +11,36 @@ function attemptOf(row) {
 const closed = "NOT EXISTS (SELECT 1 FROM deliveries x WHERE x.operation_id = o.operation_id AND x.outcome IS NULL)";
 const reported = "EXISTS (SELECT 1 FROM stopped_operations s WHERE s.operation_id = o.operation_id)";
 const finalStatuses = "'refused', 'completed', 'failed', 'stopped', 'cancelled'";
+const waitStopSequence = "(SELECT min(e.sequence) FROM command_waits w JOIN events e ON e.run_id = w.run_id WHERE w.check_operation = o.operation_id AND w.state != 'waiting' AND (e.type IN ('run.completed', 'run.failed', 'run.cancelled') OR (json_extract(e.payload, '$.waitName') = w.name AND (e.type = 'command-wait.expired' OR (e.type = 'command-wait.opened' AND round(unixepoch(e.recorded_at, 'subsec') * 1000) >= w.deadline)))))";
 export async function stopping(connection, runId) {
-    const rows = await connection.all(`SELECT o.operation_id, o.kind, d.effect_id, coalesce(a.purpose, 'dispatch') AS purpose, d.outcome, d.staged_sequence, p.status, p.receipt, ${reported} AS stopped FROM outbox o JOIN deliveries d ON d.operation_id = o.operation_id LEFT JOIN dispatch_attempts a ON a.effect_id = d.effect_id LEFT JOIN operations p ON p.operation_id = o.operation_id WHERE o.run_id = ? AND ((coalesce(p.status, '') NOT IN (${finalStatuses}) AND NOT ${reported}) OR NOT ${closed}) ORDER BY d.staged_sequence, d.rowid`, [runId]);
+    const rows = await connection.all(`SELECT o.operation_id, o.kind, d.effect_id, coalesce(a.purpose, 'dispatch') AS purpose, d.outcome, d.staged_sequence, p.status, p.receipt, ${reported} AS stopped, ${waitStopSequence} AS stop_sequence FROM outbox o JOIN deliveries d ON d.operation_id = o.operation_id LEFT JOIN dispatch_attempts a ON a.effect_id = d.effect_id LEFT JOIN operations p ON p.operation_id = o.operation_id WHERE o.run_id = ? AND ((coalesce(p.status, '') NOT IN (${finalStatuses}) AND NOT ${reported}) OR NOT ${closed}) ORDER BY d.staged_sequence, d.rowid`, [runId]);
     const grouped = Map.groupBy(rows, (row) => text(row, "operation_id"));
     return {
-        subjects: [...grouped].map(([operationId, attempts]) => ({
-            operationId,
-            kind: text(attempts[0], "kind"),
-            attempts: attempts.map(attemptOf),
-            status: optionalText(attempts[0], "status"),
-            receipt: optionalText(attempts[0], "receipt"),
-            stopped: integer(attempts[0], "stopped") === 1,
-        })),
+        subjects: [...grouped].map(([operationId, attempts]) => {
+            const stopSequence = optionalInteger(attempts[0], "stop_sequence");
+            return {
+                operationId,
+                kind: text(attempts[0], "kind"),
+                attempts: attempts.map(attemptOf),
+                status: optionalText(attempts[0], "status"),
+                receipt: optionalText(attempts[0], "receipt"),
+                stopped: integer(attempts[0], "stopped") === 1,
+                ...(stopSequence === null ? {} : { stopSequence }),
+            };
+        }),
         cancelledSequence: optionalInteger(await connection.get("SELECT max(sequence) AS sequence FROM events WHERE run_id = ? AND type = 'run.cancelled'", [runId]), "sequence"),
     };
 }
 export function turnStopping(connection, scope) {
-    const dropping = scope.status === "cancelled" || scope.kind === "cancel-run";
+    const endingWait = Object.values(scope.commandWaits ?? {}).some((wait) => wait.checkOperation !== null &&
+        (wait.state !== "waiting" ||
+            [
+                "expire-command-wait",
+                "open-command-wait",
+                "complete-run",
+                "fail-run",
+            ].includes(scope.kind)));
+    const dropping = scope.status === "cancelled" || scope.kind === "cancel-run" || endingWait;
     return dropping
         ? stopping(connection, scope.runId)
         : Promise.resolve(noStopping);
@@ -37,6 +50,6 @@ const last = "(SELECT d.outcome FROM deliveries d WHERE d.operation_id = o.opera
 const effectDue = `o.kind = 'protected-effect' AND p.status NOT IN (${finalStatuses}) AND (p.receipt IS NULL OR ?1 = 1 OR p.status IN ('recovering', 'blocked'))`;
 const runDue = `o.kind != 'protected-effect' AND NOT ${reported} AND ((${sent} AND ?1 = 1) OR (NOT ${sent} AND ${last} NOT IN ('withheld', 'blocked', 'absent')))`;
 export async function droppedRuns(connection, rule) {
-    const rows = await connection.all(`SELECT r.run_id FROM runs r WHERE r.status = 'cancelled' AND EXISTS (SELECT 1 FROM outbox o LEFT JOIN operations p ON p.operation_id = o.operation_id WHERE o.run_id = r.run_id AND ${closed} AND ((${effectDue}) OR (${runDue}))) ORDER BY r.run_id LIMIT ?2`, [rule.stopSupported ? 1 : 0, rule.limit]);
+    const rows = await connection.all(`SELECT r.run_id FROM runs r WHERE EXISTS (SELECT 1 FROM outbox o LEFT JOIN operations p ON p.operation_id = o.operation_id WHERE o.run_id = r.run_id AND (r.status = 'cancelled' OR EXISTS (SELECT 1 FROM command_waits w WHERE w.run_id = r.run_id AND w.check_operation = o.operation_id AND w.state != 'waiting')) AND ${closed} AND ((${effectDue}) OR (${runDue}))) ORDER BY r.run_id LIMIT ?2`, [rule.stopSupported ? 1 : 0, rule.limit]);
     return rows.map((row) => text(row, "run_id"));
 }

package/dist/src/broker/actor/turn-draft.d.ts

@@ -11,6 +11,7 @@ export interface ChangeDraft {
     readonly released: readonly Row[];
     readonly closed: readonly Row[];
     readonly gates: readonly Row[];
+    readonly waits: readonly Row[];
     readonly details: readonly Row[];
     readonly documents: readonly Row[];
     readonly budgets: readonly Row[];

package/dist/src/broker/actor/turn-draft.js

@@ -1,3 +1,4 @@
+import { commandWaitRows } from "../command-wait-restore.js";
 import { evidenceOf } from "../../authority/operations.js";
 import { detailRecord, gateRecord } from "../decision-restore.js";
 import { effectRows } from "../effect-restore.js";
@@ -23,6 +24,7 @@ export function unchangedAt(sequence, closed) {
         released: [],
         closed,
         gates: [],
+        waits: [],
         details: [],
         documents: [],
         ...unchangedEffects,
@@ -78,6 +80,7 @@ export function draft(result, extra) {
         closed,
         documents,
         ...effectDraft(result, before),
+        waits: commandWaitRows(changedEntries(state.commandWaits ?? {}, before.commandWaits ?? {})).map(columns),
         gates: changed(state.gates, before.gates).map((gate) => columns(gateRecord(gate))),
         details: changed(state.details, before.details).map((details) => columns(detailRecord(details))),
         previous: before.sequence,
@@ -127,6 +130,7 @@ export function merged(first, later) {
         released: joined("released"),
         closed: joined("closed"),
         gates: joined("gates"),
+        waits: joined("waits"),
         details: joined("details"),
         documents: joined("documents"),
         budgets: joined("budgets"),

package/dist/src/broker/actor/turn-state.js

@@ -1,3 +1,4 @@
+import { readCommandWaits } from "../command-wait-restore.js";
 import { parseCommand } from "../../authority/commands.js";
 import { readExecutionManifest } from "../../execution-pin.js";
 import { operationScope } from "../../operation-identity.js";
@@ -92,7 +93,7 @@ export async function recoverableIntents(connection) {
     return [...intents, ...(await uncertainEffects(connection))];
 }
 async function uncertainEffects(connection) {
-    const rows = await connection.all("SELECT p.operation_id, p.run_id, r.workflow FROM operations p JOIN runs r ON r.run_id = p.run_id WHERE p.status IN ('recovering', 'blocked') AND r.status != 'cancelled' AND NOT EXISTS (SELECT 1 FROM deliveries d WHERE d.operation_id = p.operation_id AND d.outcome IS NULL) ORDER BY p.requested_sequence LIMIT ?", [recoveryBatch]);
+    const rows = await connection.all("SELECT p.operation_id, p.run_id, r.workflow FROM operations p JOIN runs r ON r.run_id = p.run_id WHERE p.status IN ('recovering', 'blocked') AND r.status != 'cancelled' AND NOT EXISTS (SELECT 1 FROM command_waits w WHERE w.check_operation = p.operation_id AND w.state != 'waiting') AND NOT EXISTS (SELECT 1 FROM deliveries d WHERE d.operation_id = p.operation_id AND d.outcome IS NULL) ORDER BY p.requested_sequence LIMIT ?", [recoveryBatch]);
     const intents = [];
     for (const row of rows)
         intents.push(await pendingEffect(connection, {
@@ -161,8 +162,10 @@ async function turnState(connection, scope) {
         sql: "SELECT operation_id, kind, run_id, created_sequence, released_sequence FROM outbox WHERE run_id = ? AND released_sequence IS NULL ORDER BY created_sequence, rowid",
         parameters: [runId],
     });
+    const waits = await readCommandWaits(connection, runId);
     return {
         state: {
+            ...waits,
             sequence,
             runs: { ...near.runs, ...(stored ? { [runId]: stored } : {}) },
             commands: recorded ? { [commandId]: recorded } : {},
@@ -178,6 +181,7 @@ async function turnState(connection, scope) {
             runId,
             status: stored?.status,
             kind: scope.kind,
+            ...waits,
         }),
         runId,
         created: recorded

package/dist/src/broker/authority-admission.js

@@ -1,3 +1,5 @@
+import { commandWaitKey } from "../authority/command-waits.js";
+import { documentDigest } from "./decision-restore.js";
 import { parseCommand } from "../authority/commands.js";
 import { executionCapabilities, readExecutionManifest, resumePinned, } from "../execution-pin.js";
 import { effectInputDigest } from "./effect-restore.js";
@@ -41,6 +43,61 @@ const commandEffect = (command, context) => {
         return { kind: "rejected", reason: "command-not-declared" };
     return unpinned(command, context);
 };
+function waitMatches(command, wait) {
+    return (command.target === wait.command &&
+        command.maximumWaitSeconds === wait.maximumWaitSeconds &&
+        command.pollEverySeconds === wait.pollEverySeconds);
+}
+const commandWait = (command, context) => {
+    const pin = context.state.runs[command.runId]?.workflow ?? "";
+    const declaration = context.definitions.get(pin);
+    const name = String(command.waitName);
+    const waits = declaration?.commandWaits ?? {};
+    const wait = Object.hasOwn(waits, name) ? waits[name] : undefined;
+    if (wait === undefined || !waitMatches(command, wait))
+        return { kind: "rejected", reason: "command-wait-not-declared" };
+    return unpinned(command, context);
+};
+function declaredWaitCheck(command, context) {
+    const pin = context.state.runs[command.runId]?.workflow ?? "";
+    const declarations = context.definitions.get(pin)?.commandWaits ?? {};
+    const name = String(command.waitName);
+    const declaration = Object.hasOwn(declarations, name)
+        ? declarations[name]
+        : undefined;
+    const wait = context.state.commandWaits?.[commandWaitKey(command.runId, name)];
+    if (declaration === undefined || wait === undefined)
+        return undefined;
+    return waitMatches({
+        ...command,
+        target: wait.command,
+        maximumWaitSeconds: wait.maximumWaitSeconds,
+        pollEverySeconds: wait.pollEverySeconds,
+    }, declaration)
+        ? wait
+        : undefined;
+}
+const commandWaitCheck = (command, context) => {
+    const wait = declaredWaitCheck(command, context);
+    if (wait === undefined)
+        return { kind: "rejected", reason: "command-wait-not-declared" };
+    const computed = effectInputDigest({
+        capability: "command",
+        method: `run:${wait.command}`,
+        target: wait.command,
+        payload: wait.inputDigest,
+    });
+    return command.inputDigest === computed
+        ? unpinned(command, context)
+        : { kind: "rejected", reason: "input-digest-mismatch" };
+};
+const commandReport = (command, context) => {
+    const output = command.commandOutput;
+    if (output !== undefined &&
+        (command.worker !== "command" || documentDigest(output) !== command.result))
+        return { kind: "rejected", reason: "command-output-mismatch" };
+    return unpinned(command, context);
+};
 const handoffEffect = (command, context) => {
     if (command.capability !== "handoff")
         return unpinned(command, context);
@@ -67,6 +124,9 @@ const effectRequest = (command, context) => {
 };
 const rules = {
     "request-effect": effectRequest,
+    "check-command-wait": commandWaitCheck,
+    "report-effect": commandReport,
+    "open-command-wait": commandWait,
     "admit-run": admission,
     "decide-gate": resumption,
     "resume-run": resumption,

package/dist/src/broker/authority-restore.d.ts

@@ -1,3 +1,4 @@
+import type { CommandWaitRow } from "../storage/command-wait-rows.ts";
 import type { AuthorityEvent, AuthorityState, EffectIntent, RunState } from "../authority/reducer.ts";
 import type { DecisionRows, DocumentRow } from "../storage/decision-rows.ts";
 import type { EffectRows } from "../storage/effect-rows.ts";
@@ -7,6 +8,7 @@ import type { ExecutionManifest } from "../workflow-admission.ts";
 export type RestoredSnapshot = AuthoritySnapshot & Partial<DecisionRows> & {
     readonly documents?: readonly DocumentRow[];
     readonly effects?: EffectRows;
+    readonly waits?: readonly CommandWaitRow[];
 };
 export type Restoration = {
     readonly kind: "restored";

package/dist/src/broker/authority-restore.js

@@ -1,3 +1,4 @@
+import { commandWaitState, commandWaitRows, commandOutputsIntact, } from "./command-wait-restore.js";
 import { isDeepStrictEqual } from "node:util";
 import { parseEvent } from "../authority/events.js";
 import { rebuildHistory } from "../authority/history.js";
@@ -51,6 +52,7 @@ export function restore(snapshot) {
             isDeepStrictEqual(Object.fromEntries(snapshot.runs.map((row) => [row.runId, row.sequence])), history.runSequences),
         ],
         ["definitions", definitionsIntact(definitions, state)],
+        ...waitChecks(snapshot, { state, definitions, events }),
         ...decisionChecks(snapshot, state),
         ...(snapshot.effects === undefined
             ? []
@@ -68,6 +70,21 @@ export function restore(snapshot) {
         };
     return { kind: "restored", state, events, definitions };
 }
+function waitChecks(snapshot, context) {
+    const { state, definitions } = context;
+    return [
+        ["command-outputs", commandOutputsIntact(context.events)],
+        ["command-waits", commandWaitsIntact(definitions, state)],
+        ...(snapshot.waits === undefined
+            ? []
+            : [
+                [
+                    "waits",
+                    isDeepStrictEqual(snapshot.waits, commandWaitRows(state.commandWaits ?? {})),
+                ],
+            ]),
+    ];
+}
 function decisionChecks(snapshot, state) {
     const { gates, details, documents } = snapshot;
     if (gates === undefined || details === undefined || documents === undefined)
@@ -95,12 +112,29 @@ function definitionsIntact(definitions, state) {
     const used = new Set(Object.values(state.runs).map((run) => run.workflow));
     return ([...definitions].every(([pin, manifest]) => workflowPin(manifest) === pin && used.has(pin)) && [...used].every((pin) => definitions.has(pin)));
 }
+function commandWaitsIntact(definitions, state) {
+    return Object.values(state.commandWaits ?? {}).every((wait) => {
+        const pin = state.runs[wait.runId]?.workflow ?? "";
+        const waits = definitions.get(pin)?.commandWaits ?? {};
+        const permission = Object.hasOwn(waits, wait.name)
+            ? waits[wait.name]
+            : undefined;
+        return (permission !== undefined &&
+            permission.command === wait.command &&
+            permission.maximumWaitSeconds === wait.maximumWaitSeconds &&
+            permission.pollEverySeconds === wait.pollEverySeconds);
+    });
+}
 const projectionParts = ["sequence", "runs", "commands", "intents"];
 function text(error) {
     return String(Reflect.get(Object(error), "message"));
 }
 export function currentState(snapshot) {
-    return { ...projectedState(snapshot), ...decisionState(snapshot) };
+    return {
+        ...projectedState(snapshot),
+        ...decisionState(snapshot),
+        ...commandWaitState(snapshot.waits ?? []),
+    };
 }
 export function projectedState(snapshot) {
     return {

package/dist/src/broker/command-wait-restore.d.ts

@@ -0,0 +1,31 @@
+import type { Database } from "solid-objects";
+import { type CommandWaitsState } from "../authority/command-waits.ts";
+import type { AuthorityEvent } from "../authority/transitions.ts";
+import type { DispatchRead } from "../authority/dispatch-decision.ts";
+import type { AuthorityState } from "../authority/transitions.ts";
+import { type CommandWaitRow } from "../storage/command-wait-rows.ts";
+import type { SqlConnection } from "../storage/domain-rows.ts";
+export declare function commandWaitRows(waits: CommandWaitsState): readonly CommandWaitRow[];
+export declare function commandWaitState(rows: readonly CommandWaitRow[]): {
+    readonly commandWaits?: CommandWaitsState;
+};
+export declare function readCommandWaits(connection: SqlConnection, runId: string): Promise<{
+    readonly commandWaits?: CommandWaitsState;
+}>;
+export declare function upgradeCommandWaits(database: Database, state: AuthorityState): Promise<void>;
+export declare function upgradeCommandWaitChecks(database: Database): Promise<void>;
+export declare function commandWaitDeadline(waits: CommandWaitsState, operationId: string): {
+    readonly commandDeadline?: string;
+};
+export declare function dispatchCommandWait(connection: SqlConnection, check: {
+    readonly runId: string;
+    readonly workflow: string;
+    readonly operationId: string;
+}): Promise<Pick<DispatchRead, "commandWait">>;
+export declare function commandOutputsIntact(events: readonly AuthorityEvent[]): boolean;
+export declare function readCommandWaitDeadline(connection: SqlConnection, scope: {
+    readonly runId: string;
+    readonly operationId: string;
+}): Promise<{
+    readonly commandDeadline?: string;
+}>;

package/dist/src/broker/command-wait-restore.js

@@ -0,0 +1,86 @@
+import { commandWaitKey, } from "../authority/command-waits.js";
+import { operationPhase } from "../operation-identity.js";
+import { documentDigest } from "./decision-restore.js";
+import { readExecutionManifest } from "../execution-pin.js";
+import { text } from "../storage/domain-rows.js";
+import { commandWaitStatements, loadCommandWaits, } from "../storage/command-wait-rows.js";
+import { checkedVersion, waitingVersion, upgradeSchema, } from "../storage/domain-schema.js";
+export function commandWaitRows(waits) {
+    return Object.values(waits).sort((left, right) => {
+        if (left.runId !== right.runId)
+            return left.runId < right.runId ? -1 : 1;
+        return left.name < right.name ? -1 : 1;
+    });
+}
+export function commandWaitState(rows) {
+    const waits = {};
+    for (const row of rows) {
+        const state = [
+            "waiting",
+            "timed-out",
+            "cancelled",
+            "completed",
+            "failed",
+        ];
+        const kind = state.find((candidate) => candidate === row.state);
+        if (kind === undefined)
+            throw new Error("invalid-command-wait-state");
+        waits[commandWaitKey(row.runId, row.name)] = { ...row, state: kind };
+    }
+    return rows.length === 0 ? {} : { commandWaits: waits };
+}
+export async function readCommandWaits(connection, runId) {
+    return commandWaitState(await loadCommandWaits(connection, { runId }));
+}
+export async function upgradeCommandWaits(database, state) {
+    await database.transaction(async (connection) => {
+        await upgradeSchema(connection, waitingVersion);
+        for (const statement of commandWaitStatements(commandWaitRows(state.commandWaits ?? {}), { version: "opened" }))
+            await connection.run(statement.sql, statement.parameters);
+    });
+}
+export async function upgradeCommandWaitChecks(database) {
+    await database.transaction(async (connection) => {
+        await upgradeSchema(connection, checkedVersion);
+    });
+}
+export function commandWaitDeadline(waits, operationId) {
+    const wait = Object.values(waits).find((wait) => wait.checkOperation === operationId);
+    return wait === undefined
+        ? {}
+        : { commandDeadline: new Date(wait.deadline).toISOString() };
+}
+export async function dispatchCommandWait(connection, check) {
+    if (operationPhase(check.operationId) !== "command-wait")
+        return {};
+    const state = await readCommandWaits(connection, check.runId);
+    const wait = Object.values(state.commandWaits ?? {}).find((wait) => wait.checkOperation === check.operationId);
+    if (wait === undefined)
+        return {};
+    const row = await connection.get("SELECT manifest FROM definitions WHERE pin = ?", [check.workflow]);
+    const declarations = readExecutionManifest(JSON.parse(text(row, "manifest"))).commandWaits ?? {};
+    const permission = Object.hasOwn(declarations, wait.name)
+        ? declarations[wait.name]
+        : undefined;
+    return { commandWait: { wait, declared: declaredWait(wait, permission) } };
+}
+function declaredWait(wait, permission) {
+    return (permission !== undefined &&
+        permission.command === wait.command &&
+        permission.maximumWaitSeconds === wait.maximumWaitSeconds &&
+        permission.pollEverySeconds === wait.pollEverySeconds);
+}
+export function commandOutputsIntact(events) {
+    return events.every((event) => {
+        const output = event.payload["commandOutput"];
+        return (output === undefined ||
+            (event.payload["worker"] === "command" &&
+                documentDigest(output) === event.payload["result"]));
+    });
+}
+export async function readCommandWaitDeadline(connection, scope) {
+    if (operationPhase(scope.operationId) !== "command-wait")
+        return {};
+    const state = await readCommandWaits(connection, scope.runId);
+    return commandWaitDeadline(state.commandWaits ?? {}, scope.operationId);
+}

package/dist/src/broker/decision-restore.d.ts

@@ -2,7 +2,7 @@ import type { RunDetails } from "../authority/details.ts";
 import { type GateState } from "../authority/gates.ts";
 import type { AuthorityState } from "../authority/reducer.ts";
 import type { DecisionRows, DetailRow, DocumentRow, GateRow } from "../storage/decision-rows.ts";
-export type DecisionState = Pick<AuthorityState, "gates" | "details" | "questions">;
+export type DecisionState = Pick<AuthorityState, "gates" | "details" | "questions" | "commandWaits">;
 export declare function documentDigest(body: string): string;
 export declare function gateRecord(gate: GateState): GateRow;
 export declare function detailRecord(details: RunDetails): DetailRow;

package/dist/src/broker/decision-restore.js

@@ -141,6 +141,7 @@ export function decisionRows(state) {
 }
 export function referencedDigests(state) {
     return [
+        ...Object.values(state.commandWaits ?? {}).map((wait) => wait.inputDigest),
         ...Object.values(state.gates).flatMap((gate) => [
             gate.prompt,
             gate.outcome?.answer ?? null,

package/dist/src/broker/effect-upgrade.d.ts

@@ -1,3 +1,5 @@
 import type { Database } from "solid-objects";
 import type { AuthorityState } from "../authority/reducer.ts";
 export declare function upgradeEffects(database: Database, state: AuthorityState): Promise<void>;
+export declare function upgradeSpendingIndexes(database: Database): Promise<void>;
+export declare function upgradeEventIndexes(database: Database): Promise<void>;

package/dist/src/broker/effect-upgrade.js

@@ -1,9 +1,15 @@
-import { currentVersion, upgradeSchema } from "../storage/domain-schema.js";
+import { currentVersion, effectedVersion, spendingVersion, upgradeSchema, } from "../storage/domain-schema.js";
 import { persistEffects } from "../storage/effect-changes.js";
 import { effectRows } from "./effect-restore.js";
 export async function upgradeEffects(database, state) {
     await database.transaction(async (connection) => {
-        await upgradeSchema(connection, currentVersion);
+        await upgradeSchema(connection, effectedVersion);
         await persistEffects(connection, effectRows(state.effects, []));
     });
 }
+export async function upgradeSpendingIndexes(database) {
+    await database.transaction((connection) => upgradeSchema(connection, spendingVersion));
+}
+export async function upgradeEventIndexes(database) {
+    await database.transaction((connection) => upgradeSchema(connection, currentVersion));
+}

package/dist/src/cli/arguments.d.ts

@@ -9,6 +9,19 @@ export type Invocation = {
     readonly kind: "help";
 } | {
     readonly kind: "version";
+} | {
+    readonly kind: "mcp";
+} | {
+    readonly kind: "mcp-help";
+} | {
+    readonly kind: "init-prompt";
+} | {
+    readonly kind: "init";
+    readonly harness: string | undefined;
+} | {
+    readonly kind: "init-prompt-help";
+} | {
+    readonly kind: "init-help";
 } | {
     readonly kind: "doctor-help";
 } | {

package/dist/src/cli/arguments.js

@@ -26,6 +26,7 @@ const options = {
     follow: { type: "boolean" },
     since: { type: "string" },
     repository: { type: "string" },
+    harness: { type: "string" },
 };
 const textOptions = ["--prompt", "--text"];
 function knownFlag(token) {
@@ -83,8 +84,9 @@ function selectedInvocation(given) {
     const [command, ...remaining] = positionals;
     if (command === undefined)
         return topLevel(values);
-    if (command === "doctor")
-        return doctorInvocation(values, remaining);
+    const inspection = inspectionInvocation(command, { values, remaining });
+    if (inspection !== undefined)
+        return inspection;
     if (command === "workflows" && remaining[0] === "validate")
         return validation(values, remaining.slice(1));
     const outcome = runtimeInvocation({
@@ -96,6 +98,43 @@ function selectedInvocation(given) {
         return { kind: "usage-error", code: outcome, json };
     return outcome;
 }
+function inspectionInvocation(command, input) {
+    const { values, remaining } = input;
+    if (command === "init") {
+        if (unexpected(values, ["harness", "help"]))
+            return { kind: "usage-error", code: "unexpected-option", json: false };
+        if (remaining.length > 0)
+            return { kind: "usage-error", code: "unexpected-argument", json: false };
+        return values.help
+            ? { kind: "init-help" }
+            : { kind: "init", harness: values.harness };
+    }
+    if (command === "doctor")
+        return doctorInvocation(values, remaining);
+    if (command === "mcp")
+        return mcpInvocation(values, remaining);
+    if (command === "init-prompt")
+        return promptInvocation(values, remaining);
+    return undefined;
+}
+function mcpInvocation(values, remaining) {
+    if (unexpected(values, ["help"]))
+        return { kind: "usage-error", code: "unexpected-option", json: false };
+    if (remaining.length > 0)
+        return { kind: "usage-error", code: "unexpected-argument", json: false };
+    return { kind: values.help ? "mcp-help" : "mcp" };
+}
+function promptInvocation(values, remaining) {
+    if (unexpected(values, ["help"]))
+        return {
+            kind: "usage-error",
+            code: "unexpected-option",
+            json: values.json === true,
+        };
+    if (remaining.length > 0)
+        return { kind: "usage-error", code: "unexpected-argument", json: false };
+    return { kind: values.help ? "init-prompt-help" : "init-prompt" };
+}
 function doctorInvocation(values, remaining) {
     const json = values.json === true;
     if (unexpected(values, ["help", "json"]))
@@ -134,7 +173,7 @@ function knownCommand(positionals) {
         return true;
     if (command === "workflows")
         return subcommand === "validate";
-    if (command === "doctor")
+    if (["doctor", "init-prompt", "init", "mcp"].includes(command))
         return true;
     return isRuntimeCommand(command);
 }

package/dist/src/cli/chat-stores.d.ts

@@ -0,0 +1,2 @@
+import type { ChatStore } from "./init-prompt.ts";
+export declare function chatStores(home: string | undefined): Promise<readonly ChatStore[]>;

package/dist/src/cli/chat-stores.js

@@ -0,0 +1,113 @@
+import { lstat, opendir } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+const knownStores = [
+    {
+        name: "Claude Code",
+        folder: ".claude/projects",
+        format: "JSONL",
+        documentation: "https://code.claude.com/docs/en/claude-directory",
+    },
+    {
+        name: "Codex",
+        folder: ".codex/sessions",
+        format: "JSONL, including zstd-compressed .jsonl.zst (read with zstd -dc)",
+        documentation: "https://learn.chatgpt.com/docs/security/sdk",
+    },
+    {
+        name: "Gemini CLI",
+        folder: ".gemini",
+        format: "JSON conversation history and checkpoints under tmp/<project>/",
+        documentation: "https://geminicli.com/docs/cli/checkpointing/",
+    },
+    {
+        name: "opencode",
+        folder: ".local/share/opencode",
+        format: "SQLite (opencode.db); older versions use JSON files under storage/",
+        documentation: "https://docs.opencode.ai/docs/troubleshooting/",
+    },
+    {
+        name: "grok",
+        folder: ".grok",
+        format: "JSONL ACP events in sessions/<encoded-cwd>/<session-id>/updates.jsonl; raw messages in chat_history.jsonl; JSON metadata",
+        documentation: "https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/17-sessions.md",
+    },
+    {
+        name: "Cursor Agent",
+        folder: ".cursor",
+        format: "JSONL under projects/<project>/agent-transcripts/ (older transcripts may be text)",
+        documentation: "https://forum.cursor.com/t/accessing-the-full-agent-transcript-in-cursor/157311/5",
+    },
+];
+async function metadata(path) {
+    return lstat(path).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+}
+async function* storeFiles(path) {
+    const pending = [path];
+    for (let folder = pending.pop(); folder !== undefined; folder = pending.pop()) {
+        const directory = await opendir(folder);
+        for await (const entry of directory) {
+            const file = join(folder, entry.name);
+            if (entry.isDirectory())
+                pending.push(file);
+            if (!entry.isFile())
+                continue;
+            const info = await metadata(file);
+            if (info?.isFile())
+                yield info;
+        }
+    }
+}
+async function measure(path) {
+    let fileCount = 0;
+    let totalBytes = 0;
+    let oldest = null;
+    let newest = null;
+    for await (const info of storeFiles(path)) {
+        fileCount += 1;
+        totalBytes += info.size;
+        oldest = Math.min(oldest ?? info.mtimeMs, info.mtimeMs);
+        newest = Math.max(newest ?? info.mtimeMs, info.mtimeMs);
+    }
+    return {
+        fileCount,
+        totalBytes,
+        oldestFileDate: oldest === null ? null : new Date(oldest).toISOString(),
+        newestFileDate: newest === null ? null : new Date(newest).toISOString(),
+    };
+}
+async function inspectStore(path) {
+    try {
+        if (!(await metadata(path))?.isDirectory())
+            return null;
+        return await measure(path);
+    }
+    catch (error) {
+        return {
+            unavailable: error instanceof Error &&
+                "code" in error &&
+                typeof error.code === "string"
+                ? error.code
+                : "scan-failed",
+            fileCount: null,
+            totalBytes: null,
+            oldestFileDate: null,
+            newestFileDate: null,
+        };
+    }
+}
+export async function chatStores(home) {
+    if (!home || !isAbsolute(home))
+        return [];
+    const stores = [];
+    for (const { folder, ...store } of knownStores) {
+        const path = join(home, folder);
+        const facts = await inspectStore(path);
+        if (facts)
+            stores.push({ ...store, path, ...facts });
+    }
+    return stores;
+}