@bridge_gpt/mcp-server 0.2.16 → 0.2.19

package/build/conductor/worker-ledger-cli.js

@@ -0,0 +1,244 @@
+/**
+ * Worker-side conductor-ledger subprocess boundary (BAPI-527, durable execution).
+ *
+ * CORE INVARIANT: only the CAPTURED CONDUCTOR NODE touches the `better-sqlite3`
+ * native binary. A dispatched worker's Node process must NEVER import or load it.
+ * Every worker-facing ledger operation (`check_messages`, and the
+ * `wait_for_done_gate` event emit) therefore runs through this module, which
+ * shells out to the packaged `conductor-bin.js` CLI executed by the conductor
+ * Node runtime captured at dispatch time in `CONDUCTOR_NODE_PATH`. Conductor-OWNED
+ * processes (the CLI itself, the supervisor/epic runtimes) keep calling
+ * `store.ts` directly — they legitimately own the native load.
+ *
+ * Hard-fail contract: when `CONDUCTOR_NODE_PATH` is missing/invalid or
+ * `BAPI_CONDUCTOR_CLI_FILE` is absent, this boundary throws a typed
+ * {@link ConductorLedgerSubprocessRuntimeError} rather than silently falling back
+ * to the worker's own `process.execPath`. Falling back would re-introduce the
+ * native load into the worker Node — the exact failure mode this slice removes.
+ *
+ * Security: argv is always a fixed LIST (`execFile`, never `shell: true`, never a
+ * command string). Event JSON payloads cross via STDIN (`--data-json-stdin`), so
+ * raw payloads/secrets never enter the process argument list. Every failure is
+ * converted to a sanitized typed error — no raw caught error, path, argv, stdout,
+ * stderr, or credential value is ever attached.
+ */
+import * as nodeChildProcess from "node:child_process";
+import { isAbsolute as pathIsAbsolute } from "node:path";
+import { ConductorLedgerSubprocessRuntimeError, } from "./errors.js";
+import { makeProducerDedupeKey, makeStableProducerEventId, } from "./producer-ledger.js";
+/** The env key that carries the captured conductor Node executable path. */
+export const CONDUCTOR_NODE_PATH_ENV = "CONDUCTOR_NODE_PATH";
+/** The (pre-existing) env key that carries the packaged `conductor-bin.js` path. */
+export const BAPI_CONDUCTOR_CLI_FILE_ENV = "BAPI_CONDUCTOR_CLI_FILE";
+/**
+ * Bounded stdout buffer for a conductor CLI response. Conductor JSON responses
+ * (message batches / emit summaries) are small; 8 MiB is generous headroom while
+ * still capping a runaway subprocess.
+ */
+export const WORKER_LEDGER_CLI_MAX_BUFFER = 8 * 1024 * 1024;
+/**
+ * Hard wall-clock cap for a single conductor CLI subprocess. A hung
+ * `conductor-bin.js` must never hang `check_messages` / `wait_for_done_gate`
+ * indefinitely; `execFile`'s `timeout` kills the child and surfaces the callback
+ * error (mapped to a sanitized `spawn_failed`). Generous relative to a fast local
+ * ledger read/write, but bounded.
+ */
+export const WORKER_LEDGER_CLI_TIMEOUT_MS = 30_000;
+const defaultExecFile = (file, args, options, callback) => 
+// The narrowed signature (utf-8 string stdout/stderr + list argv, no shell) is a
+// safe structural subset of Node's execFile overloads.
+nodeChildProcess.execFile(file, args, options, callback);
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Validate and resolve the worker-ledger subprocess runtime from the environment.
+ *
+ * `CONDUCTOR_NODE_PATH` must be set, non-empty, and an ABSOLUTE path (a relative
+ * value like `node` / `./node` is rejected as `invalid` — it must never resolve
+ * against `PATH` or the worker cwd). `BAPI_CONDUCTOR_CLI_FILE` must be set and
+ * non-empty. On any failure this throws a typed
+ * {@link ConductorLedgerSubprocessRuntimeError}; it NEVER falls back to
+ * `process.execPath`.
+ */
+export function resolveWorkerLedgerCliRuntime(deps = {}) {
+    const env = deps.env ?? process.env;
+    const isAbsolute = deps.isAbsolute ?? pathIsAbsolute;
+    const nodePathRaw = env[CONDUCTOR_NODE_PATH_ENV];
+    if (!nonEmpty(nodePathRaw)) {
+        throw new ConductorLedgerSubprocessRuntimeError("missing", CONDUCTOR_NODE_PATH_ENV);
+    }
+    const nodePath = nodePathRaw.trim();
+    if (!isAbsolute(nodePath)) {
+        throw new ConductorLedgerSubprocessRuntimeError("invalid", CONDUCTOR_NODE_PATH_ENV);
+    }
+    const cliFileRaw = env[BAPI_CONDUCTOR_CLI_FILE_ENV];
+    if (!nonEmpty(cliFileRaw)) {
+        throw new ConductorLedgerSubprocessRuntimeError("cli_missing", BAPI_CONDUCTOR_CLI_FILE_ENV);
+    }
+    return { nodePath, cliFile: cliFileRaw.trim() };
+}
+/**
+ * Execute one conductor CLI subcommand under the captured conductor Node and
+ * resolve its raw stdout. argv is a fixed LIST — `[cliFile, ...subcommandArgs]` —
+ * spawned via `execFile` with `shell` disabled. An optional `stdin` payload is
+ * written to the child's stdin (used for `--data-json-stdin`) so raw payloads
+ * never enter argv. Any spawn error or abnormal exit is converted to a sanitized
+ * {@link ConductorLedgerSubprocessRuntimeError} — the raw error, stderr, and
+ * stdout are discarded so no path/secret leaks.
+ */
+export function execConductorCli(subcommandArgs, stdin, deps = {}) {
+    const runtime = resolveWorkerLedgerCliRuntime(deps);
+    const execFile = deps.execFile ?? defaultExecFile;
+    const maxBuffer = deps.maxBuffer ?? WORKER_LEDGER_CLI_MAX_BUFFER;
+    const timeout = deps.timeout ?? WORKER_LEDGER_CLI_TIMEOUT_MS;
+    const argv = [runtime.cliFile, ...subcommandArgs];
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = execFile(runtime.nodePath, argv, 
+            // A `timeout` bounds a hung child; the kill surfaces as the callback error
+            // (mapped below to a sanitized spawn_failed) rather than an infinite hang.
+            { maxBuffer, encoding: "utf8", timeout }, (error, stdout) => {
+                if (error) {
+                    // A non-zero exit, spawn failure, or timeout kill — never surface the
+                    // raw error text (it can carry paths/secrets). Fixed reason only.
+                    reject(new ConductorLedgerSubprocessRuntimeError("spawn_failed", CONDUCTOR_NODE_PATH_ENV));
+                    return;
+                }
+                resolve(stdout);
+            });
+        }
+        catch {
+            reject(new ConductorLedgerSubprocessRuntimeError("spawn_failed", CONDUCTOR_NODE_PATH_ENV));
+            return;
+        }
+        if (stdin !== undefined) {
+            // A writable-stream 'error' (e.g. EPIPE when the child exits early) is emitted
+            // ASYNCHRONOUSLY and, without a listener, becomes an uncaught exception that
+            // crashes the whole worker process. Attach a no-op handler so the failure is
+            // absorbed here; the exec callback still surfaces the underlying failure as a
+            // sanitized spawn_failed. Never echo the raw error.
+            child.stdin?.on("error", () => {
+                /* swallowed: the exec callback owns the failure signal */
+            });
+            try {
+                child.stdin?.write(stdin);
+                child.stdin?.end();
+            }
+            catch {
+                // A synchronous write failure surfaces through the exec callback as a spawn
+                // error; do not throw here (and do not echo the raw failure).
+            }
+        }
+    });
+}
+/**
+ * Parse compact CLI JSON from stdout. Malformed output becomes a sanitized typed
+ * {@link ConductorLedgerSubprocessRuntimeError} (`malformed_stdout`) — the raw
+ * stdout is never attached to the thrown error.
+ */
+export function parseCliJsonStdout(stdout) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        throw new ConductorLedgerSubprocessRuntimeError("malformed_stdout", CONDUCTOR_NODE_PATH_ENV);
+    }
+}
+/**
+ * Read + ACK a worker's pending relay messages through the conductor CLI, i.e.
+ * `conductor-bin.js check-messages --run-id <id> --worker-id <id> [--limit <n>] --json`.
+ * Returns the parsed {@link CheckWorkerMessagesResult}. Never touches the local
+ * SQLite store from the worker Node.
+ */
+export async function checkWorkerMessagesViaCli(input, deps = {}) {
+    const args = ["check-messages", "--run-id", input.runId, "--worker-id", input.workerId];
+    if (input.limit !== undefined) {
+        args.push("--limit", String(input.limit));
+    }
+    args.push("--json");
+    const stdout = await execConductorCli(args, undefined, deps);
+    return parseCliJsonStdout(stdout);
+}
+/**
+ * Build the `emit-event` envelope argv (everything EXCEPT the normalized `data`
+ * object, which crosses via stdin through `--data-json-stdin`). Mirrors the
+ * claude-hook emit contract so raw payloads/secrets never reach the argument list.
+ */
+export function buildEmitEventArgs(event) {
+    const args = ["emit-event", "--type", event.type, "--source", event.source];
+    // Forward the deterministic event id so the conductor process dedups server-side
+    // on the `events.id` UNIQUE constraint — this is what lets the worker skip the
+    // in-process `eventAlreadyExists` poll (which would load better-sqlite3).
+    if (nonEmpty(event.id ?? undefined))
+        args.push("--id", event.id);
+    if (nonEmpty(event.subject ?? undefined))
+        args.push("--subject", event.subject);
+    if (nonEmpty(event.run_id ?? undefined))
+        args.push("--run-id", event.run_id);
+    if (nonEmpty(event.worker_id ?? undefined))
+        args.push("--worker-id", event.worker_id);
+    if (nonEmpty(event.producer ?? undefined))
+        args.push("--producer", event.producer);
+    if (nonEmpty(event.observed_via ?? undefined)) {
+        args.push("--observed-via", event.observed_via);
+    }
+    if (event.schema_version !== undefined) {
+        args.push("--schema-version", String(event.schema_version));
+    }
+    if (nonEmpty(event.time ?? undefined))
+        args.push("--time", event.time);
+    if (typeof event.confidence === "number") {
+        args.push("--confidence", String(event.confidence));
+    }
+    args.push("--data-json-stdin", "--json");
+    return args;
+}
+/**
+ * Emit one conductor event through the CLI, i.e.
+ * `conductor-bin.js emit-event ... --data-json-stdin --json`, passing the
+ * normalized `data` object over STDIN rather than argv. Returns the parsed CLI
+ * JSON result. Never touches the local SQLite store from the worker Node.
+ */
+export async function emitConductorEventViaCli(event, deps = {}) {
+    const args = buildEmitEventArgs(event);
+    const stdinPayload = JSON.stringify(event.data ?? {});
+    const stdout = await execConductorCli(args, stdinPayload, deps);
+    return parseCliJsonStdout(stdout);
+}
+/**
+ * Dedup-aware event emit through the CLI, with NO in-process ledger access.
+ *
+ * This is the worker gate path's replacement for the in-process
+ * {@link emitConductorEventIfNew}: the dedupe key + deterministic event id are
+ * derived PURELY (hashing only — no store read), the id is forwarded to the CLI
+ * (`emit-event --id`), and the conductor process performs the dedup server-side on
+ * the `events.id` UNIQUE constraint. Because the pre-check `eventAlreadyExists`
+ * poll is gone, a dispatched worker calling `wait_for_done_gate` never loads
+ * `better-sqlite3` — closing the exact gap BAPI-527 targets. A conductor-side
+ * duplicate is reported back as `{ ok: false, reason: "duplicate" }`.
+ */
+export async function emitConductorEventIfNewViaCli(input, dimensions, deps = {}) {
+    const dedupeKey = makeProducerDedupeKey(dimensions);
+    const eventId = makeStableProducerEventId(dedupeKey);
+    // Embed the dedupe key under data.details (mirrors emitConductorEventIfNew) so a
+    // later ledger scan can still recognize the event, without disturbing other
+    // normalized details the caller supplied.
+    const existingData = input.data ?? {};
+    const existingDetails = existingData.details && typeof existingData.details === "object" && !Array.isArray(existingData.details)
+        ? existingData.details
+        : {};
+    const data = {
+        ...existingData,
+        details: { ...existingDetails, dedupe_key: dedupeKey },
+    };
+    const result = (await emitConductorEventViaCli({ ...input, id: eventId, data }, deps));
+    // The conductor CLI reports a UNIQUE-constraint collision as a structured
+    // duplicate rather than an error — treat that as a no-op dedup, everything else
+    // as a successful emit of the deterministic id.
+    if (result && result.ok === false && result.reason === "duplicate") {
+        return { emitted: false, reason: "duplicate" };
+    }
+    return { emitted: true, event_id: eventId };
+}