@smithers-orchestrator/db 0.24.2 → 0.25.0

package/src/docWatcher.js

@@ -0,0 +1,162 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, watch } from "node:fs";
+import { join } from "node:path";
+import { sha256Hex } from "./sha256Hex.js";
+
+/**
+ * Durability file-watcher seam for `_smithers_docs`.
+ *
+ * Watches a directory of `*.md` docs and upserts each into `_smithers_docs`
+ * (via a {@link import("./adapter.js").SmithersDb}), so a doc edited on disk —
+ * by a human, an agent, or a `git` checkout — surfaces through the gateway's
+ * `listTickets` RPC without a separate import step. The doc identity (`path` PK)
+ * is the filename WITHOUT its `.md` extension, matching the id a `createTicket`
+ * caller supplies, so a file and an RPC-created row for the same id reconcile to
+ * one row.
+ *
+ * Reconciliation is ONE-DIRECTIONAL (file → DB) and last-write-wins on a
+ * content-hash mismatch: a file is upserted only when `sha256(content)` differs
+ * from the stored `content_hash` (a no-op otherwise, so a noisy `fs.watch` does
+ * not churn the DB or bump `updated_at_ms`). The watcher NEVER writes the DB
+ * back out to disk and NEVER materializes a tombstone as a file.
+ *
+ * Soft-deletes (tombstones) are RESPECTED: a row with `deleted_at_ms` set is NOT
+ * resurrected merely because its `*.md` file still lingers on disk. The watcher
+ * compares the file's `sha256(content)` against the tombstoned row's stored
+ * `content_hash` — only a genuine post-deletion change (a real re-create / edit,
+ * i.e. a hash MISMATCH) revives the doc (file wins). An identical leftover file
+ * leaves the tombstone intact, so a deleted ticket stays deleted across re-syncs
+ * and gateway restarts. This prevents tombstone resurrection while preserving
+ * last-write-wins for live docs and legitimate re-creates.
+ *
+ * @param {import("./adapter.js").SmithersDb} adapter
+ * @param {{
+ *   dir: string,
+ *   kind?: string,
+ *   defaultStatus?: string | null,
+ *   nowMs?: () => number,
+ *   onError?: (error: unknown) => void,
+ * }} options
+ * @returns {{ dir: string, sync: () => Promise<void>, syncFile: (file: string) => Promise<void>, close: () => void }}
+ */
+export function watchDocsDirectory(adapter, options) {
+    const dir = options.dir;
+    const kind = options.kind ?? "ticket";
+    const defaultStatus = options.defaultStatus ?? null;
+    const now = options.nowMs ?? (() => Date.now());
+    const onError = options.onError ?? ((error) => {
+        console.warn(`[docWatcher] ${dir}: ${error instanceof Error ? error.message : String(error)}`);
+    });
+
+    // The watched directory must exist before `fs.watch`; create it so wiring the
+    // seam against a not-yet-populated docs dir is safe (idempotent).
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+
+    /** Map a `*.md` filename to its doc `path` (id) — drop the extension. */
+    function pathForFile(file) {
+        return file.endsWith(".md") ? file.slice(0, -3) : file;
+    }
+
+    /**
+     * Reconcile ONE `*.md` file into `_smithers_docs`. Reads the file, hashes it,
+     * and upserts only when the hash differs from the stored row (last-write-wins).
+     * A vanished/non-`.md`/unreadable file is ignored — the watcher never deletes
+     * a row from a missing file (soft-deletes are the gateway's job, not the
+     * filesystem's), so a transient editor swap can't tombstone a doc.
+     * @param {string} file
+     */
+    async function syncFile(file) {
+        if (!file.endsWith(".md")) {
+            return;
+        }
+        const full = join(dir, file);
+        let content;
+        try {
+            if (!existsSync(full) || !statSync(full).isFile()) {
+                return;
+            }
+            content = readFileSync(full, "utf8");
+        }
+        catch (error) {
+            onError(error);
+            return;
+        }
+        const path = pathForFile(file);
+        const contentHash = sha256Hex(content);
+        try {
+            const existing = await adapter.getDoc(path);
+            if (existing && existing.contentHash === contentHash) {
+                // Identical content to the stored row:
+                //  - live row  → no-op (a duplicate `fs.watch` event never bumps
+                //    updated_at_ms or churns the DB);
+                //  - tombstone → RESPECT the soft-delete. A lingering, unchanged
+                //    file is NOT a recreation, so we leave `deleted_at_ms` intact
+                //    instead of resurrecting the deleted doc. Only a genuine
+                //    post-deletion edit (hash MISMATCH, handled below) revives it.
+                return;
+            }
+            await adapter.upsertDoc({
+                path,
+                kind,
+                content,
+                contentHash,
+                // Preserve an existing row's status; a brand-new file gets the default.
+                status: existing && existing.status != null ? existing.status : defaultStatus,
+                updatedAtMs: now(),
+                deletedAtMs: null,
+            });
+        }
+        catch (error) {
+            onError(error);
+        }
+    }
+
+    /** Reconcile every `*.md` currently in the directory. */
+    async function sync() {
+        let files;
+        try {
+            files = readdirSync(dir);
+        }
+        catch (error) {
+            onError(error);
+            return;
+        }
+        for (const file of files) {
+            await syncFile(file);
+        }
+    }
+
+    // Initial reconcile, then watch for changes. Each event re-syncs just the
+    // touched file; errors are reported, never thrown, so a watcher hiccup never
+    // takes down the gateway that wired it.
+    void sync();
+
+    let watcher = null;
+    try {
+        watcher = watch(dir, { persistent: false }, (_event, filename) => {
+            if (typeof filename === "string" && filename.length > 0) {
+                void syncFile(filename);
+            }
+            else {
+                void sync();
+            }
+        });
+        watcher.on("error", onError);
+    }
+    catch (error) {
+        onError(error);
+    }
+
+    return {
+        dir,
+        sync,
+        syncFile,
+        close: () => {
+            if (watcher) {
+                watcher.close();
+                watcher = null;
+            }
+        },
+    };
+}

package/src/frame-codec.js

@@ -240,7 +240,11 @@ function applyOps(root, ops) {
             current = insertAtPath(current, op.path, op.value);
             continue;
         }
-        current = removeAtPath(current, op.path);
+        if (op.op === "remove") {
+            current = removeAtPath(current, op.path);
+            continue;
+        }
+        throw new Error(`Invalid frame delta op: ${String(op.op)}`);
     }
     return current;
 }

package/src/getSmithersSchemaSignature.js

@@ -0,0 +1,70 @@
+import { getTableName } from "drizzle-orm";
+import { createHash } from "node:crypto";
+import * as internalSchema from "./internal-schema.js";
+import { schemaSignature } from "./schema-signature.js";
+
+/**
+ * @param {unknown} value
+ * @returns {value is { queryAll: (statement: string, params?: readonly unknown[]) => Promise<readonly Record<string, unknown>[]> }}
+ */
+function isStorageLike(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        typeof /** @type {any} */ (value).queryAll === "function");
+}
+
+/**
+ * @param {unknown} value
+ */
+function resolveStorage(value) {
+    if (isStorageLike(value)) {
+        return value;
+    }
+    const storage = /** @type {{ internalStorage?: unknown } | null | undefined} */ (value)?.internalStorage;
+    if (isStorageLike(storage)) {
+        return storage;
+    }
+    throw new Error("getSmithersSchemaSignature requires a SmithersDb or SqlMessageStorage instance");
+}
+
+/**
+ * @returns {Array<import("drizzle-orm").Table>}
+ */
+function internalTables() {
+    return Object.values(internalSchema)
+        .filter((table) => {
+            try {
+                return typeof getTableName(/** @type {any} */ (table)) === "string";
+            }
+            catch {
+                return false;
+            }
+        })
+        .sort((left, right) => getTableName(/** @type {any} */ (left)).localeCompare(getTableName(/** @type {any} */ (right))));
+}
+
+/**
+ * Return the durable Smithers schema head and a stable hash of the internal
+ * table catalog. The migration head is the client persistence schemaVersion;
+ * the signature lets clients or operators detect a same-head table-shape drift.
+ *
+ * @param {unknown} adapterOrStorage
+ * @returns {Promise<{ schemaVersion: string; signature: string; components: Record<string, string> }>}
+ */
+export async function getSmithersSchemaSignature(adapterOrStorage) {
+    const storage = resolveStorage(adapterOrStorage);
+    const rows = await storage.queryAll("SELECT id FROM _smithers_schema_migrations ORDER BY id");
+    const headId = rows
+        .map((row) => row.id)
+        .filter((id) => typeof id === "string")
+        .at(-1) ?? "0000";
+    const schemaVersion = headId.match(/^\d+/)?.[0] ?? headId;
+    const components = Object.fromEntries(internalTables().map((table) => [
+        getTableName(table),
+        schemaSignature(table),
+    ]));
+    const signature = createHash("sha256")
+        .update(JSON.stringify({ headId, schemaVersion, components }))
+        .digest("hex");
+    return { schemaVersion, signature, components };
+}

package/src/index.d.ts

@@ -15,6 +15,21 @@ type SchemaRegistryEntry$1 = {
     zodSchema: zod.ZodObject;
 };
 
+type Dialect = "sqlite" | "postgres";
+declare const SQLITE: "sqlite";
+declare const POSTGRES: "postgres";
+declare function isDialect(value: unknown): value is Dialect;
+declare function quoteIdentifier(identifier: string): string;
+declare function translatePlaceholders(dialect: Dialect, sql: string): string;
+declare function columnType(dialect: Dialect, sqliteType: string): string;
+declare function translateDdl(dialect: Dialect, ddl: string): string;
+declare function tableColumnsSql(dialect: Dialect, table: string): {
+    sql: string;
+    params: ReadonlyArray<string>;
+};
+declare function beginTransactionSql(dialect: Dialect): string;
+declare function jsonExtractText(dialect: Dialect, columnSql: string, jsonPath: string): string;
+
 type SignalQuery$1 = {
     signalName?: string;
     correlationId?: string | null;
@@ -385,6 +400,9 @@ type SqliteParam = string | number | bigint | boolean | Uint8Array | null | unde
 /**
  * @typedef {{ cacheKey: string; createdAtMs?: number; nodeId: string; outputTable: string }} CacheRowLike
  */
+/**
+ * @typedef {{ path: string; kind: string; content: string; contentHash: string; updatedAtMs: number; deletedAtMs?: number | null }} DocRow
+ */
 declare const DB_ALERT_ID_MAX_LENGTH: 256;
 declare const DB_ALERT_POLICY_NAME_MAX_LENGTH: 256;
 declare const DB_ALERT_MESSAGE_MAX_LENGTH: 4096;
@@ -432,10 +450,11 @@ declare class SmithersDb {
    */
     clearFrameCacheForRun(runId: string): void;
     /**
-   * @param {string} queryString
+     * @param {string} queryString
+     * @param {unknown[]} [params]
    * @returns {RunnableEffect<unknown[], SmithersError>}
    */
-    rawQuery(queryString: string): RunnableEffect<unknown[], SmithersError$1>;
+    rawQuery(queryString: string, params?: unknown[]): RunnableEffect<unknown[], SmithersError$1>;
     /**
    * @param {string} currentFiberThread
    * @returns {boolean}
@@ -890,6 +909,29 @@ declare class SmithersDb {
    */
     listToolCalls(runId: string, nodeId: string, iteration: number): RunnableEffect<Array<Record<string, unknown>>, SmithersError$1>;
     /**
+   * @param {DocRow} row
+   * @returns {RunnableEffect<void, SmithersError>}
+   */
+    upsertDocRow(row: DocRow): RunnableEffect<void, SmithersError$1>;
+    /**
+   * @param {string} path
+   * @param {{ includeDeleted?: boolean }} [options]
+   * @returns {RunnableEffect<DocRow | undefined, SmithersError>}
+   */
+    getDoc(path: string, options?: {
+        includeDeleted?: boolean;
+    }): RunnableEffect<DocRow | undefined, SmithersError$1>;
+    /**
+   * @param {{ kind?: string; includeDeleted?: boolean; updatedAfterMs?: number; limit?: number }} [options]
+   * @returns {RunnableEffect<DocRow[], SmithersError>}
+   */
+    listDocs(options?: {
+        kind?: string;
+        includeDeleted?: boolean;
+        updatedAfterMs?: number;
+        limit?: number;
+    }): RunnableEffect<DocRow[], SmithersError$1>;
+    /**
    * @param {Record<string, unknown>} row
    * @returns {RunnableEffect<void, SmithersError>}
    */
@@ -912,15 +954,6 @@ declare class SmithersDb {
     /**
    * @param {string} runId
    * @param {EventHistoryQuery} [query]
-   * @returns {{ whereSql: string; params: Array<string | number> }}
-   */
-    buildEventHistoryWhere(runId: string, query?: EventHistoryQuery): {
-        whereSql: string;
-        params: Array<string | number>;
-    };
-    /**
-   * @param {string} runId
-   * @param {EventHistoryQuery} [query]
    * @returns {RunnableEffect<Array<Record<string, unknown>>, SmithersError>}
    */
     listEventHistory(runId: string, query?: EventHistoryQuery): RunnableEffect<Array<Record<string, unknown>>, SmithersError$1>;
@@ -1281,6 +1314,14 @@ type CacheRowLike = {
     nodeId: string;
     outputTable: string;
 };
+type DocRow = {
+    path: string;
+    kind: string;
+    content: string;
+    contentHash: string;
+    updatedAtMs: number;
+    deletedAtMs?: number | null;
+};
 
 /** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase} _BunSQLiteDatabase */
 /** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} _SmithersError */
@@ -4899,6 +4940,7 @@ declare const smithersCron: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
     };
     dialect: "sqlite";
 }>;
+declare const smithersDocs: any;
 
 /** @typedef {import("drizzle-orm").AnyColumn} AnyColumn */
 /** @typedef {import("./output/OutputKey.ts").OutputKey} _OutputKey */
@@ -5009,6 +5051,12 @@ type BunSQLiteDatabase$1 = drizzle_orm_bun_sqlite.BunSQLiteDatabase;
 declare function schemaSignature(table: _Table$1): string;
 type _Table$1 = drizzle_orm.Table;
 
+declare function getSmithersSchemaSignature(adapterOrStorage: unknown): Promise<{
+    schemaVersion: string;
+    signature: string;
+    components: Record<string, string>;
+}>;
+
 /**
  * @param {BunSQLiteDatabase<Record<string, unknown>>} db
  * @param {_Table} inputTable
@@ -5226,4 +5274,4 @@ declare function camelToSnake(str: any): any;
 
 type SchemaRegistryEntry = SchemaRegistryEntry$1;
 
-export { type AlertRow, type AlertSeverity, type AlertStatus, type AnyColumn, type ApprovalRow, type AttemptRow, type CacheRow, type CacheRowLike, type CountRow, DB_ALERT_ALLOWED_SEVERITIES, DB_ALERT_ALLOWED_STATUSES, DB_ALERT_ID_MAX_LENGTH, DB_ALERT_MESSAGE_MAX_LENGTH, DB_ALERT_POLICY_NAME_MAX_LENGTH, DB_RUN_ALLOWED_STATUSES, DB_RUN_ID_MAX_LENGTH, DB_RUN_WORKFLOW_NAME_MAX_LENGTH, type EventHistoryQuery, FRAME_KEYFRAME_INTERVAL, type FrameDelta, type FrameDeltaOp, type FrameEncoding, type FrameRow, type HumanRequestRow, type JsonBounds, type JsonPath, type JsonPathSegment, NODE_DIFF_MAX_BYTES, NodeDiffCache, type NodeDiffCacheResult, type NodeDiffCacheRow$1 as NodeDiffCacheRow, NodeDiffTooLargeError, type NodeRow, type OutputKey, type OutputSnapshot, type PendingHumanRequestRow, type RalphRow, type RunAncestryRow, type RunRow, type RunnableEffect, type SchemaRegistryEntry, type SignalQuery, type SignalRow, SmithersDb, type SmithersError$1 as SmithersError, SqlMessageStorage, type SqlMessageStorageEventHistoryQuery, type SqliteParam, type SqliteWriteRetryOptions, type StaleRunRecord, type _BunSQLiteDatabase, type _NodeDiffCacheRow, type _OutputKey, type _SmithersDb, type _SmithersError, applyFrameDelta, applyFrameDeltaJson, assertJsonPayloadWithinBounds, assertMaxBytes, assertMaxJsonDepth, assertMaxStringLength, assertOptionalArrayMaxLength, assertOptionalStringMaxLength, assertPositiveFiniteInteger, assertPositiveFiniteNumber, buildKeyWhere, buildOutputRow, camelToSnake, describeSchemaShape, encodeFrameDelta, ensureSmithersTables, ensureSmithersTablesEffect, ensureSqlMessageStorage, ensureSqlMessageStorageEffect, getAgentOutputSchema, getKeyColumns, getSqlMessageStorage, isRetryableSqliteWriteError, loadInput, loadInputEffect, loadOutputs, loadOutputsEffect, normalizeFrameEncoding, parseFrameDelta, schemaSignature, selectOutputRow, selectOutputRowEffect, serializeFrameDelta, smithersAlerts, smithersApprovals, smithersAttempts, smithersCache, smithersCron, smithersEvents, smithersFrames, smithersHumanRequests, smithersNodeDiffs, smithersNodes, smithersRalph, smithersRuns, smithersSandboxes, smithersSignals, smithersTimeTravelAudit, smithersToolCalls, smithersVectors, stripAutoColumns, syncZodTableSchema, unwrapZodType, upsertOutputRow, upsertOutputRowEffect, validateExistingOutput, validateInput, validateOutput, withSqliteWriteRetry, withSqliteWriteRetryEffect, zodSchemaColumns, zodToCreateTableSQL, zodToTable };
+export { type AlertRow, type AlertSeverity, type AlertStatus, type AnyColumn, type ApprovalRow, type AttemptRow, type CacheRow, type CacheRowLike, type CountRow, DB_ALERT_ALLOWED_SEVERITIES, DB_ALERT_ALLOWED_STATUSES, DB_ALERT_ID_MAX_LENGTH, DB_ALERT_MESSAGE_MAX_LENGTH, DB_ALERT_POLICY_NAME_MAX_LENGTH, DB_RUN_ALLOWED_STATUSES, DB_RUN_ID_MAX_LENGTH, DB_RUN_WORKFLOW_NAME_MAX_LENGTH, type Dialect, type DocRow, type EventHistoryQuery, FRAME_KEYFRAME_INTERVAL, type FrameDelta, type FrameDeltaOp, type FrameEncoding, type FrameRow, type HumanRequestRow, type JsonBounds, type JsonPath, type JsonPathSegment, NODE_DIFF_MAX_BYTES, NodeDiffCache, type NodeDiffCacheResult, type NodeDiffCacheRow$1 as NodeDiffCacheRow, NodeDiffTooLargeError, type NodeRow, type OutputKey, type OutputSnapshot, POSTGRES, type PendingHumanRequestRow, type RalphRow, type RunAncestryRow, type RunRow, type RunnableEffect, SQLITE, type SchemaRegistryEntry, type SignalQuery, type SignalRow, SmithersDb, type SmithersError$1 as SmithersError, SqlMessageStorage, type SqlMessageStorageEventHistoryQuery, type SqliteParam, type SqliteWriteRetryOptions, type StaleRunRecord, type _BunSQLiteDatabase, type _NodeDiffCacheRow, type _OutputKey, type _SmithersDb, type _SmithersError, applyFrameDelta, applyFrameDeltaJson, assertJsonPayloadWithinBounds, assertMaxBytes, assertMaxJsonDepth, assertMaxStringLength, assertOptionalArrayMaxLength, assertOptionalStringMaxLength, assertPositiveFiniteInteger, assertPositiveFiniteNumber, beginTransactionSql, buildKeyWhere, buildOutputRow, camelToSnake, columnType, describeSchemaShape, encodeFrameDelta, ensureSmithersTables, ensureSmithersTablesEffect, ensureSqlMessageStorage, ensureSqlMessageStorageEffect, getAgentOutputSchema, getKeyColumns, getSmithersSchemaSignature, getSqlMessageStorage, isDialect, isRetryableSqliteWriteError, jsonExtractText, loadInput, loadInputEffect, loadOutputs, loadOutputsEffect, normalizeFrameEncoding, parseFrameDelta, quoteIdentifier, schemaSignature, selectOutputRow, selectOutputRowEffect, serializeFrameDelta, smithersAlerts, smithersApprovals, smithersAttempts, smithersCache, smithersCron, smithersDocs, smithersEvents, smithersFrames, smithersHumanRequests, smithersNodeDiffs, smithersNodes, smithersRalph, smithersRuns, smithersSandboxes, smithersSignals, smithersTimeTravelAudit, smithersToolCalls, smithersVectors, stripAutoColumns, syncZodTableSchema, tableColumnsSql, translateDdl, translatePlaceholders, unwrapZodType, upsertOutputRow, upsertOutputRowEffect, validateExistingOutput, validateInput, validateOutput, withSqliteWriteRetry, withSqliteWriteRetryEffect, zodSchemaColumns, zodToCreateTableSQL, zodToTable };

package/src/index.js

@@ -3,9 +3,12 @@
 // @smithers-type-exports-end
 
 export * from "./adapter.js";
+export * from "./assertNoReservedColumns.js";
+export * from "./dialect.js";
 export * from "./ensure.js";
 export * from "./input-bounds.js";
 export * from "./frame-codec.js";
+export * from "./getSmithersSchemaSignature.js";
 export * from "./input.js";
 export * from "./internal-schema.js";
 export * from "./output.js";

package/src/internal-schema/index.js

@@ -19,6 +19,7 @@ export { smithersMemoryThreads } from "./smithersMemoryThreads.js";
 export { smithersMemoryMessages } from "./smithersMemoryMessages.js";
 export { smithersVectors } from "./smithersVectors.js";
 export { smithersCron } from "./smithersCron.js";
+export { smithersDocs } from "./smithersDocs.js";
 export { smithersSchemaMigrations } from "./smithersSchemaMigrations.js";
 export { smithersWorkspaceStates } from "./smithersWorkspaceStates.js";
 export { smithersWorkspaceCheckpoints } from "./smithersWorkspaceCheckpoints.js";

package/src/internal-schema/smithersDocs.js

@@ -0,0 +1,27 @@
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+/**
+ * `_smithers_docs` — durable markdown work-docs (tickets, plans, specs,
+ * proposals) the gateway lists/creates/updates/soft-deletes via the
+ * `listTickets`/`createTicket`/`updateTicket`/`deleteTicket` RPCs and that the
+ * file-watcher seam (`watchDocsDirectory`) upserts from a `.md` directory.
+ *
+ *  - `path`          PK; the doc identity (a file path or stable id).
+ *  - `kind`          one of `ticket | plan | spec | proposal` (default `ticket`).
+ *  - `content`       the full markdown body.
+ *  - `contentHash`   `sha256(content)` — the watcher's last-write-wins compare key.
+ *  - `status`        rides the sync row so a ticket's status survives reload
+ *                    (LOCKED Path A); free-form text (e.g. `todo`/`in-progress`/`done`).
+ *  - `updatedAtMs`   last write (Unix epoch ms).
+ *  - `deletedAtMs`   soft-delete tombstone; NULL means live. `listTickets`
+ *                    filters tombstones and the watcher never materializes them.
+ */
+export const smithersDocs = sqliteTable("_smithers_docs", {
+    path: text("path").primaryKey(),
+    kind: text("kind").notNull().default("ticket"),
+    content: text("content").notNull(),
+    contentHash: text("content_hash").notNull(),
+    status: text("status"),
+    updatedAtMs: integer("updated_at_ms").notNull(),
+    deletedAtMs: integer("deleted_at_ms"),
+});

package/src/internal-schema/smithersScorers.js

@@ -14,6 +14,8 @@ export const smithersScorers = sqliteTable("_smithers_scorers", {
     metaJson: text("meta_json"),
     inputJson: text("input_json"),
     outputJson: text("output_json"),
+    groundTruthJson: text("ground_truth_json"),
+    contextJson: text("context_json"),
     latencyMs: real("latency_ms"),
     scoredAtMs: integer("scored_at_ms").notNull(),
     durationMs: real("duration_ms"),

package/src/internal-schema.js

@@ -270,3 +270,4 @@ export const smithersSchemaMigrations = sqliteTable("_smithers_schema_migrations
 });
 export { smithersWorkspaceStates } from "./internal-schema/smithersWorkspaceStates.js";
 export { smithersWorkspaceCheckpoints } from "./internal-schema/smithersWorkspaceCheckpoints.js";
+export { smithersDocs } from "./internal-schema/smithersDocs.js";

package/src/react-output.js

@@ -1,10 +1,3 @@
-/**
- * @param {unknown} payload
- */
-export function stripAutoColumns(payload) {
-    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
-        return payload;
-    }
-    const { runId: _runId, nodeId: _nodeId, iteration: _iteration, ...rest } = payload;
-    return rest;
-}
+// Re-export the canonical stripAutoColumns from the output barrel so this
+// React-facing subpath does not carry a third, drifting copy of the helper.
+export { stripAutoColumns } from "./output.js";

package/src/runState/DeriveRunStateInput.ts

@@ -5,6 +5,10 @@ export type DeriveRunStateInput = {
   pendingApproval?: { nodeId: string; requestedAtMs: number } | null;
   pendingTimer?: { nodeId: string; firesAtMs: number } | null;
   pendingEvent?: { nodeId: string; correlationKey: string } | null;
+  parkedEventBlock?:
+    | { kind: "approval-decided-resume-required"; nodeId: string }
+    | { kind: "external-trigger" }
+    | null;
   now?: number;
   staleThresholdMs?: number;
 };

package/src/runState/ReasonBlocked.ts

@@ -2,9 +2,12 @@ export type ReasonBlocked =
   | { kind: "approval"; nodeId: string; requestedAt: string }
   | { kind: "event"; nodeId: string; correlationKey: string }
   | { kind: "timer"; nodeId: string; wakeAt: string }
+  | { kind: "approval-decided-resume-required"; nodeId: string }
+  | { kind: "external-trigger" }
   | {
       kind: "provider";
       nodeId: string;
       code: "rate-limit" | "auth" | "timeout";
     }
-  | { kind: "tool"; nodeId: string; toolName: string; code: string };
+  | { kind: "tool"; nodeId: string; toolName: string; code: string }
+  | { kind: "quota"; quotaBlockedCount: number; resetAtMs?: number };

package/src/runState/RunState.ts

@@ -3,6 +3,7 @@ export type RunState =
   | "waiting-approval"
   | "waiting-event"
   | "waiting-timer"
+  | "waiting-quota"
   | "recovering"
   | "stale"
   | "orphaned"

package/src/runState/computeRunStateFromRow.js

@@ -17,6 +17,7 @@ export async function computeRunStateFromRow(adapter, run, options = {}) {
     let pendingApproval = null;
     let pendingTimer = null;
     let pendingEvent = null;
+    let parkedEventBlock = null;
 
     if (run.status === "waiting-approval") {
         pendingApproval = await loadPendingApproval(adapter, run.runId);
@@ -24,6 +25,9 @@ export async function computeRunStateFromRow(adapter, run, options = {}) {
         pendingTimer = await loadPendingTimer(adapter, run.runId);
     } else if (run.status === "waiting-event") {
         pendingEvent = await loadPendingEvent(adapter, run.runId);
+        if (pendingEvent == null) {
+            parkedEventBlock = await loadParkedEventBlock(adapter, run.runId);
+        }
     }
 
     return deriveRunState({
@@ -31,6 +35,7 @@ export async function computeRunStateFromRow(adapter, run, options = {}) {
         pendingApproval,
         pendingTimer,
         pendingEvent,
+        parkedEventBlock,
         now: options.now,
         staleThresholdMs: options.staleThresholdMs,
     });
@@ -100,3 +105,19 @@ async function loadPendingEvent(adapter, runId) {
     }
     return null;
 }
+
+/**
+ * @param {SmithersDb} adapter
+ * @param {string} runId
+ */
+async function loadParkedEventBlock(adapter, runId) {
+    const nodes = await adapter.listNodes(runId);
+    const pending = nodes.find((node) => node.state === "pending");
+    if (pending) {
+        return {
+            kind: "approval-decided-resume-required",
+            nodeId: pending.nodeId,
+        };
+    }
+    return { kind: "external-trigger" };
+}

package/src/runState/deriveRunState.js

@@ -13,6 +13,7 @@ export function deriveRunState(input) {
         pendingApproval = null,
         pendingTimer = null,
         pendingEvent = null,
+        parkedEventBlock = null,
         now = Date.now(),
         staleThresholdMs = RUN_STATE_HEARTBEAT_STALE_MS,
     } = input;
@@ -55,17 +56,45 @@ export function deriveRunState(input) {
                   }
                 : { ...base, state: "waiting-timer" };
         case "waiting-event":
-            return pendingEvent
-                ? {
-                      ...base,
-                      state: "waiting-event",
-                      blocked: {
-                          kind: "event",
-                          nodeId: pendingEvent.nodeId,
-                          correlationKey: pendingEvent.correlationKey,
-                      },
-                  }
+            if (pendingEvent) {
+                return {
+                    ...base,
+                    state: "waiting-event",
+                    blocked: {
+                        kind: "event",
+                        nodeId: pendingEvent.nodeId,
+                        correlationKey: pendingEvent.correlationKey,
+                    },
+                };
+            }
+            return parkedEventBlock
+                ? { ...base, state: "waiting-event", blocked: parkedEventBlock }
                 : { ...base, state: "waiting-event" };
+        case "waiting-quota": {
+            let quotaMeta;
+            if (run.errorJson) {
+                try { quotaMeta = JSON.parse(run.errorJson); } catch { /* ignore */ }
+            }
+            const quotaBlockedCount = typeof quotaMeta?.quotaBlockedCount === "number"
+                ? quotaMeta.quotaBlockedCount
+                : undefined;
+            const resetAtMs = typeof quotaMeta?.resetAtMs === "number"
+                ? quotaMeta.resetAtMs
+                : undefined;
+            return {
+                ...base,
+                state: "waiting-quota",
+                ...(quotaBlockedCount != null
+                    ? {
+                          blocked: {
+                              kind: "quota",
+                              quotaBlockedCount,
+                              ...(resetAtMs != null ? { resetAtMs } : {}),
+                          },
+                      }
+                    : {}),
+            };
+        }
         case "running":
             return classifyRunning(run, now, staleThresholdMs, base);
         default: