@bridge_gpt/mcp-server 0.2.10 → 0.2.12

package/build/conductor/store.js

@@ -18,11 +18,66 @@
  */
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import Database from "better-sqlite3";
 import { SEMANTIC_EVENT_TYPES, assertSemanticEventType, } from "./taxonomy.js";
 import { ConductorValidationError } from "./errors.js";
 import { prepareDataJsonForStorage } from "./data-normalization.js";
 import { ensureConductorDatabaseFile, getConductorLedgerPath, getConductorPathHealth, detectNetworkMountedHome, } from "./paths.js";
+// ---------------------------------------------------------------------------
+// Optional native binding loader (BAPI-451)
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when the optional native `better-sqlite3` binding cannot be loaded
+ * (the optional dependency was skipped at install, or no prebuilt binary exists
+ * for this platform×Node and the source build failed). In this degraded state
+ * Conductor persistence is unavailable; callers degrade gracefully rather than
+ * crashing the MCP server, whose core (non-Conductor) tools are unaffected.
+ */
+export class ConductorPersistenceUnavailableError extends Error {
+    constructor(message = "Conductor persistence is unavailable: the optional 'better-sqlite3' native module could not be loaded.") {
+        super(message);
+        this.name = "ConductorPersistenceUnavailableError";
+    }
+}
+/**
+ * Cached, concurrency-safe async loader for the optional `better-sqlite3` module.
+ *
+ * The static `import Database from "better-sqlite3"` was removed (BAPI-451) so the
+ * native binding is never pulled into the eager boot graph. The first call performs
+ * a dynamic `import("better-sqlite3")`; the in-flight promise is stored module-scoped
+ * and synchronously, so concurrent first callers from the read and write open paths
+ * share a single load and the ESM-resolution + native-binding cost is paid exactly
+ * once. On failure the degraded state is cached in `dbLoadDegraded`: the stderr
+ * warning is emitted exactly once and every subsequent call throws
+ * {@link ConductorPersistenceUnavailableError} immediately, without re-attempting the
+ * failing import on every Conductor operation.
+ */
+let databaseModulePromise = null;
+let dbLoadDegraded = false;
+async function getDatabaseModule() {
+    // Cached degraded state: never re-attempt a known-failing native import.
+    if (dbLoadDegraded) {
+        throw new ConductorPersistenceUnavailableError();
+    }
+    if (databaseModulePromise)
+        return databaseModulePromise;
+    databaseModulePromise = (async () => {
+        try {
+            const mod = await import("better-sqlite3");
+            // CommonJS interop: the better-sqlite3 default export is the constructor.
+            const ctor = (mod.default ?? mod);
+            return ctor;
+        }
+        catch {
+            if (!dbLoadDegraded) {
+                dbLoadDegraded = true;
+                console.error("[conductor] Conductor persistence is unavailable: the optional 'better-sqlite3' native module could not be loaded. " +
+                    "Conductor coordination features are disabled for this session; core MCP tools are unaffected.");
+            }
+            throw new ConductorPersistenceUnavailableError();
+        }
+    })();
+    return databaseModulePromise;
+}
 const BUSY_TIMEOUT_DEFAULT = 10_000;
 const BUSY_TIMEOUT_MIN = 250;
 const BUSY_TIMEOUT_MAX = 120_000;
@@ -122,11 +177,14 @@ export function resolveConductorStoreConfig(env = process.env) {
  * `merge.attempted`, `merge.succeeded`, and `merge.failed` lifecycle event types
  * to the same `events.type` CHECK vocabulary. Bumped to 5 in BAPI-413 because
  * the per-merge human approval feature adds the `merge.pending_approval` lifecycle
- * event type to the same CHECK vocabulary. Older ledgers stamped at a lower
- * version are rebuilt by {@link migrateConductorSchemaIfNeeded} so their CHECK
- * clause accepts the current taxonomy.
+ * event type to the same CHECK vocabulary. Bumped to 6 in BAPI-445 because the
+ * pre-implementation spec re-review verdict feature adds the `spec_review.passed`
+ * and `spec_review.changes_requested` event types to the same `events.type`
+ * CHECK vocabulary. Older ledgers stamped at a lower version are rebuilt by
+ * {@link migrateConductorSchemaIfNeeded} so their CHECK clause accepts the
+ * current taxonomy.
  */
-export const CURRENT_CONDUCTOR_SCHEMA_VERSION = 5;
+export const CURRENT_CONDUCTOR_SCHEMA_VERSION = 6;
 /** Render the taxonomy `CHECK (type IN (...))` clause from the single source of truth. */
 function buildTypeCheckClause() {
     const list = SEMANTIC_EVENT_TYPES.map((t) => `'${t}'`).join(", ");
@@ -292,7 +350,11 @@ export function migrateConductorSchemaIfNeeded(db) {
  * permissions, open SQLite, apply WAL/concurrency pragmas, and initialize the
  * schema before returning the live connection.
  */
-export function openWritableConductorDatabase(config = resolveConductorStoreConfig()) {
+export async function openWritableConductorDatabase(config = resolveConductorStoreConfig()) {
+    // Resolve the native binding lazily (BAPI-451). Throws
+    // ConductorPersistenceUnavailableError when the optional module is absent so
+    // write paths fail-soft into a structured "persistence unavailable" envelope.
+    const Database = await getDatabaseModule();
     ensureConductorDatabaseFile();
     const db = new Database(getConductorLedgerPath());
     // busy_timeout MUST be set first: `journal_mode = WAL` and the schema writes
@@ -333,7 +395,17 @@ export function openWritableConductorDatabase(config = resolveConductorStoreConf
  * Open the ledger read-only when it already exists; otherwise return `null`.
  * Never creates files and never runs schema migrations.
  */
-export function openReadonlyConductorDatabaseIfExists(config = resolveConductorStoreConfig()) {
+export async function openReadonlyConductorDatabaseIfExists(config = resolveConductorStoreConfig()) {
+    // Read paths degrade silently: when the optional native binding is absent the
+    // loader throws, and callers (poll/snapshot/doctor) treat a null connection as
+    // "no ledger yet" — returning empty results instead of crashing.
+    let Database;
+    try {
+        Database = await getDatabaseModule();
+    }
+    catch {
+        return null;
+    }
     const dbPath = getConductorLedgerPath();
     let db;
     try {
@@ -426,7 +498,7 @@ function projectRow(row, dataMode) {
  * prepares/redacts the data JSON BEFORE opening the write transaction. Defaults
  * `id`, `time`, and `schema_version`. Closes the connection in a `finally`.
  */
-export function emitConductorEvent(input, config = resolveConductorStoreConfig()) {
+export async function emitConductorEvent(input, config = resolveConductorStoreConfig()) {
     // --- Validation & preparation OUTSIDE any SQLite transaction. ---
     const type = assertSemanticEventType(input.type);
     if (typeof input.source !== "string" || input.source.trim().length === 0) {
@@ -450,7 +522,7 @@ export function emitConductorEvent(input, config = resolveConductorStoreConfig()
     const schemaVersion = typeof input.schema_version === "number" && Number.isFinite(input.schema_version)
         ? input.schema_version
         : 1;
-    const db = openWritableConductorDatabase(config);
+    const db = await openWritableConductorDatabase(config);
     try {
         const insert = db.prepare(`INSERT INTO events
          (id, source, type, subject, run_id, worker_id, producer, schema_version, time, data_json, confidence, observed_via)
@@ -581,13 +653,13 @@ function buildFilterClause(filter) {
  * applying allowlisted filters and a bounded limit. Returns compact summaries
  * unless `data_mode="full"`. `next_seq` is the cursor to pass on the next call.
  */
-export function pollConductorEvents(options = {}, config = resolveConductorStoreConfig()) {
+export async function pollConductorEvents(options = {}, config = resolveConductorStoreConfig()) {
     const sinceSeq = typeof options.since_seq === "number" && options.since_seq >= 0
         ? Math.floor(options.since_seq)
         : 1;
     const dataMode = options.data_mode === "full" ? "full" : "summary";
     const limit = Math.min(POLL_LIMIT_MAX, Math.max(1, Math.floor(options.limit ?? POLL_LIMIT_DEFAULT)));
-    const db = openReadonlyConductorDatabaseIfExists(config);
+    const db = await openReadonlyConductorDatabaseIfExists(config);
     if (!db) {
         return { events: [], next_seq: sinceSeq, count: 0 };
     }
@@ -617,11 +689,11 @@ export async function waitForConductorEvent(options = {}, config = resolveConduc
     const timeoutMs = Math.min(WAIT_TIMEOUT_MAX_MS, Math.max(0, Math.floor(options.timeout_ms ?? WAIT_TIMEOUT_MAX_MS)));
     const deadline = Date.now() + timeoutMs;
     // Poll immediately at least once.
-    let result = pollConductorEvents(options, config);
+    let result = await pollConductorEvents(options, config);
     while (result.count === 0 && Date.now() < deadline) {
         const remaining = deadline - Date.now();
         await sleep(Math.min(WAIT_POLL_INTERVAL_MS, Math.max(1, remaining)));
-        result = pollConductorEvents(options, config);
+        result = await pollConductorEvents(options, config);
     }
     return { ...result, timed_out: result.count === 0 };
 }
@@ -663,8 +735,8 @@ export function rowToSupervisorProjection(row) {
  * The projection is maintained by the conductor supervisor runtime
  * (`conductor supervise`); this read never derives state from raw events.
  */
-export function getSupervisorSnapshot(runId, config = resolveConductorStoreConfig()) {
-    const db = openReadonlyConductorDatabaseIfExists(config);
+export async function getSupervisorSnapshot(runId, config = resolveConductorStoreConfig()) {
+    const db = await openReadonlyConductorDatabaseIfExists(config);
     if (!db) {
         return { run_id: runId, status: "unknown", projection: null };
     }
@@ -689,7 +761,7 @@ export function getSupervisorSnapshot(runId, config = resolveConductorStoreConfi
  * connection is always closed in a `finally`. The statement is fully
  * parameterized — run-supplied values never enter the SQL string.
  */
-export function upsertSupervisorProjection(input, config = resolveConductorStoreConfig()) {
+export async function upsertSupervisorProjection(input, config = resolveConductorStoreConfig()) {
     if (typeof input.run_id !== "string" || input.run_id.trim().length === 0) {
         throw new ConductorValidationError("Supervisor projection 'run_id' is required.");
     }
@@ -697,7 +769,7 @@ export function upsertSupervisorProjection(input, config = resolveConductorStore
     const gatesJson = JSON.stringify(input.gates ?? {});
     const assessmentJson = input.assessment == null ? null : JSON.stringify(input.assessment);
     const summaryJson = input.summary == null ? null : JSON.stringify(input.summary);
-    const db = openWritableConductorDatabase(config);
+    const db = await openWritableConductorDatabase(config);
     try {
         const upsert = db.prepare(`INSERT INTO supervisor_projection
          (run_id, status, last_seq, last_event_time, active_workers_json, gates_json, assessment_json, summary_json, updated_at)
@@ -743,7 +815,7 @@ export function upsertSupervisorProjection(input, config = resolveConductorStore
  * and network-home degradation. Never creates the DB, inserts a diagnostic
  * event, or mutates WAL/schema state.
  */
-export function doctorConductorLedger(config = resolveConductorStoreConfig()) {
+export async function doctorConductorLedger(config = resolveConductorStoreConfig()) {
     const health = getConductorPathHealth();
     const network = detectNetworkMountedHome();
     const warnings = [...health.warnings];
@@ -755,7 +827,7 @@ export function doctorConductorLedger(config = resolveConductorStoreConfig()) {
     let eventCount = null;
     let maxSeq = null;
     let userVersion = null;
-    const db = openReadonlyConductorDatabaseIfExists(config);
+    const db = await openReadonlyConductorDatabaseIfExists(config);
     if (db) {
         try {
             const tableRow = db
@@ -810,7 +882,7 @@ export function doctorConductorLedger(config = resolveConductorStoreConfig()) {
  * `supervisor_projection`. If the DB does not exist, returns a successful empty
  * purge. Runs `wal_checkpoint(TRUNCATE)` after deletion when possible.
  */
-export function purgeConductorLedger(config = resolveConductorStoreConfig()) {
+export async function purgeConductorLedger(config = resolveConductorStoreConfig()) {
     if (!existsSync(getConductorLedgerPath())) {
         return {
             ok: true,
@@ -818,7 +890,7 @@ export function purgeConductorLedger(config = resolveConductorStoreConfig()) {
             deleted: { events: 0, messages: 0, supervisor_projection: 0 },
         };
     }
-    const db = openWritableConductorDatabase(config);
+    const db = await openWritableConductorDatabase(config);
     try {
         const purge = db.transaction(() => {
             const events = db.prepare("DELETE FROM events").run().changes;
@@ -963,7 +1035,7 @@ function insertRelayAuditEvent(db, audit) {
  * are NEVER logged; unexpected storage errors are re-thrown after the connection
  * is closed in `finally`.
  */
-export function sendWorkerMessage(input, config = resolveConductorStoreConfig()) {
+export async function sendWorkerMessage(input, config = resolveConductorStoreConfig()) {
     validateWorkerMessageIdentity(input);
     const runId = input.run_id.trim();
     const workerId = input.worker_id.trim();
@@ -997,7 +1069,7 @@ export function sendWorkerMessage(input, config = resolveConductorStoreConfig())
     const producer = typeof input.producer === "string" && input.producer.trim().length > 0
         ? input.producer.trim()
         : "worker-message-relay";
-    const db = openWritableConductorDatabase(config);
+    const db = await openWritableConductorDatabase(config);
     try {
         // (1) Exact idempotency-key hit: never insert or audit a second time.
         const existing = db
@@ -1084,7 +1156,7 @@ export function sendWorkerMessage(input, config = resolveConductorStoreConfig())
  * always reads each pending message exactly once. Returned payloads are NEVER
  * logged; the connection is closed in `finally`.
  */
-export function checkWorkerMessages(input, config = resolveConductorStoreConfig()) {
+export async function checkWorkerMessages(input, config = resolveConductorStoreConfig()) {
     if (typeof input.run_id !== "string" || input.run_id.trim().length === 0) {
         throw new ConductorValidationError("Message poll 'run_id' is required and must be a non-empty string.");
     }
@@ -1096,7 +1168,7 @@ export function checkWorkerMessages(input, config = resolveConductorStoreConfig(
     const limit = typeof input.limit === "number" && Number.isFinite(input.limit) && input.limit > 0
         ? Math.min(CHECK_MESSAGES_LIMIT_MAX, Math.floor(input.limit))
         : CHECK_MESSAGES_LIMIT_DEFAULT;
-    const db = openWritableConductorDatabase(config);
+    const db = await openWritableConductorDatabase(config);
     try {
         const selectPending = db.prepare(`SELECT * FROM messages
          WHERE run_id = @run_id AND worker_id = @worker_id AND state = 'pending'

package/build/conductor/supervisor-ledger.js

@@ -71,7 +71,7 @@ function isDuplicateConstraintError(error) {
  * reason: "duplicate" }` rather than surfaced as a failure. This function writes
  * ONLY an audit event — it performs no privileged action.
  */
-export function emitSupervisorAssessmentIfNew(input, deps = {}) {
+export async function emitSupervisorAssessmentIfNew(input, deps = {}) {
     const emitEvent = deps.emitEvent ?? emitConductorEvent;
     const idempotencyKey = makeSupervisorIdempotencyKey(input.idempotency);
     const eventId = makeSupervisorAssessmentEventId(idempotencyKey);
@@ -107,7 +107,7 @@ export function emitSupervisorAssessmentIfNew(input, deps = {}) {
         },
     };
     try {
-        const result = emitEvent(event);
+        const result = await emitEvent(event);
         return { emitted: true, event_id: eventId, event: result.event };
     }
     catch (error) {

package/build/conductor/supervisor-merge.js

@@ -69,7 +69,7 @@ export async function processGateMetMerge(access, event, deps = {}) {
     }
     const actionKey = identity.action_key;
     // Terminal-success short-circuit BEFORE any API call (idempotent across restart).
-    if (checkTerminal(actionKey)) {
+    if (await checkTerminal(actionKey)) {
         return { processed: false, reason: "already_succeeded" };
     }
     const baseDetails = {
@@ -85,7 +85,7 @@ export async function processGateMetMerge(access, event, deps = {}) {
     }
     catch (error) {
         const reason = mapApiErrorReason(error);
-        emitMergeLedgerEventIfNew({
+        await emitMergeLedgerEventIfNew({
             type: "merge.failed",
             action_key: actionKey,
             status: "failed",
@@ -101,18 +101,18 @@ export async function processGateMetMerge(access, event, deps = {}) {
     for (const ledgerEvent of response.ledger_events ?? []) {
         // Dry-run dedup: skip if one already exists locally, but NEVER treat it as
         // terminal — a later enabled merge for the same PR/head/gate can still run.
-        if (ledgerEvent.type === "merge.dry_run" && checkDryRun(actionKey)) {
+        if (ledgerEvent.type === "merge.dry_run" && (await checkDryRun(actionKey))) {
             emitted.push({ type: ledgerEvent.type, emitted: false });
             continue;
         }
         // Pending-approval dedup: skip re-emission if a pending_approval event was
         // already recorded for this action key. NEVER terminal — the worker must
         // remain active until the backend reports the merge is approved and complete.
-        if (ledgerEvent.type === "merge.pending_approval" && checkPendingApproval(actionKey)) {
+        if (ledgerEvent.type === "merge.pending_approval" && (await checkPendingApproval(actionKey))) {
             emitted.push({ type: ledgerEvent.type, emitted: false });
             continue;
         }
-        const result = emitMergeLedgerEventIfNew({
+        const result = await emitMergeLedgerEventIfNew({
             type: ledgerEvent.type,
             action_key: actionKey,
             status: ledgerEvent.status,

package/build/conductor/supervisor-message-relay.js

@@ -85,7 +85,7 @@ export function buildSupervisorRemediationWorkerMessage(input) {
  * rather than treating as failures. Unexpected storage errors are NOT swallowed
  * — they propagate to the caller's best-effort wrapper.
  */
-export function sendSupervisorEscalationWorkerMessageIfNew(candidate, assessment, state, deps = {}) {
+export async function sendSupervisorEscalationWorkerMessageIfNew(candidate, assessment, state, deps = {}) {
     const sendMessage = deps.sendMessage ?? sendWorkerMessage;
     const input = buildSupervisorEscalationWorkerMessage(candidate, assessment, state);
     return sendMessage(input);

package/build/conductor/supervisor-runtime.js

@@ -110,7 +110,7 @@ async function processEscalations(state, config, client, deps) {
         }
         let outcome = "skipped";
         try {
-            const result = deps.emitAssessment({
+            const result = await deps.emitAssessment({
                 run_id: state.run_id,
                 worker_id: candidate.worker_id,
                 assessment,
@@ -134,7 +134,7 @@ async function processEscalations(state, config, client, deps) {
         // text are never logged on failure.
         if ((outcome === "emitted" || outcome === "duplicate") && candidate.worker_id) {
             try {
-                sendSupervisorEscalationWorkerMessageIfNew(candidate, assessment, state, {
+                await sendSupervisorEscalationWorkerMessageIfNew(candidate, assessment, state, {
                     sendMessage: deps.sendWorkerMessage,
                 });
             }
@@ -216,9 +216,9 @@ export async function runSupervisor(options, deps = {}) {
             }
         }
     };
-    const persist = (state) => {
+    const persist = async (state) => {
         try {
-            upsertProjection(toSupervisorProjectionInput(state));
+            await upsertProjection(toSupervisorProjectionInput(state));
         }
         catch {
             // Persistence is best-effort within an iteration; the next iteration retries.
@@ -226,7 +226,7 @@ export async function runSupervisor(options, deps = {}) {
     };
     let state;
     try {
-        const snapshot = getSnapshot(runId);
+        const snapshot = await getSnapshot(runId);
         state = hydrateSupervisorRunStateFromSnapshot(snapshot, runId, config, now());
     }
     catch {
@@ -258,7 +258,7 @@ export async function runSupervisor(options, deps = {}) {
             // still in progress.
             if (isSupervisorRunTerminal(state)) {
                 state.status = terminalStatus(state);
-                persist(state);
+                await persist(state);
                 log(`[supervisor] run=${runId} complete status=${state.status} workers=${Object.keys(state.workers).length}`);
                 return {
                     run_id: runId,
@@ -271,7 +271,7 @@ export async function runSupervisor(options, deps = {}) {
             }
             if (hasSupervisorGlobalTimeoutElapsed(state, now())) {
                 state.status = "timed_out";
-                persist(state);
+                await persist(state);
                 errorLog(`[supervisor] run=${runId} global timeout elapsed`);
                 return {
                     run_id: runId,
@@ -314,12 +314,12 @@ export async function runSupervisor(options, deps = {}) {
             // Persist after the batch AND after housekeeping/escalation, because state
             // can change even when no events arrived. The terminal/timeout exit is
             // re-evaluated at the top of the next iteration (no extra blocking wait).
-            persist(state);
+            await persist(state);
         }
         // Iteration cap reached without a terminal/global-timeout exit (frozen clock):
         // treat as a timeout rather than spinning.
         state.status = "timed_out";
-        persist(state);
+        await persist(state);
         return {
             run_id: runId,
             status: "timed_out",
@@ -333,7 +333,7 @@ export async function runSupervisor(options, deps = {}) {
         // Unexpected boundary exception — sanitize, attempt to persist failed status.
         state.status = "failed";
         try {
-            upsertProjection(toSupervisorProjectionInput(state));
+            await upsertProjection(toSupervisorProjectionInput(state));
         }
         catch {
             /* best-effort */

package/build/conductor/taxonomy.js

@@ -38,6 +38,11 @@ export const SEMANTIC_EVENT_TYPES = [
     // BAPI-440 PR review-state telemetry event types.
     "review.passed",
     "review.changes_requested",
+    // BAPI-445 pre-implementation SPEC re-review verdict event types. Kept
+    // distinct from the review.* PR-review verdicts above so the conductor never
+    // mis-folds a spec-review outcome as the implementation PR's review state.
+    "spec_review.passed",
+    "spec_review.changes_requested",
 ];
 /**
  * Type guard: returns `true` only when `value` is one of the exact taxonomy

package/build/conductor/tools.js

@@ -79,7 +79,7 @@ function registerEmitEventTool(registerTool) {
             observed_via: z.string().optional().describe("Optional channel the event was observed through."),
         },
     }, withConductorToolErrorHandling(async (args) => {
-        const result = emitConductorEvent({
+        const result = await emitConductorEvent({
             source: args.source,
             type: args.type,
             subject: args.subject,
@@ -113,7 +113,7 @@ function registerPollEventsTool(registerTool) {
             limit: z.number().int().positive().optional().describe("Max events to return (default 100, max 1000)."),
         },
     }, withConductorToolErrorHandling(async (args) => {
-        const result = pollConductorEvents({
+        const result = await pollConductorEvents({
             since_seq: args.since_seq ?? 1,
             filter: args.filter,
             data_mode: args.data_mode ?? "summary",
@@ -167,7 +167,7 @@ function registerGetSupervisorSnapshotTool(registerTool) {
             run_id: z.string().describe("The run/session identifier to read the supervisor projection for."),
         },
     }, withConductorToolErrorHandling(async (args) => {
-        const result = getSupervisorSnapshot(args.run_id);
+        const result = await getSupervisorSnapshot(args.run_id);
         return jsonResult(result);
     }));
 }
@@ -299,7 +299,7 @@ function registerSendMessageTool(registerTool) {
                 .describe("Optional per-call cooldown override in ms (falls back to the configured cooldown)."),
         },
     }, withConductorToolErrorHandling(async (args) => {
-        const result = sendWorkerMessage({
+        const result = await sendWorkerMessage({
             run_id: args.run_id,
             worker_id: args.worker_id,
             type: args.type,
@@ -338,7 +338,7 @@ function registerCheckMessagesTool(registerTool) {
         if (runId.trim().length === 0 || workerId.trim().length === 0) {
             throw new ConductorValidationError("Conductor worker identity is unavailable: provide run_id + worker_id, or set BAPI_CONDUCTOR_RUN_ID and BAPI_CONDUCTOR_WORKER_ID.");
         }
-        const result = checkWorkerMessages({
+        const result = await checkWorkerMessages({
             run_id: runId,
             worker_id: workerId,
             limit: args.limit,