@bridge_gpt/mcp-server 0.2.2 → 0.2.3

package/build/conductor/supervisor-judgment.js

@@ -0,0 +1,215 @@
+/**
+ * LLM judgment boundary for the conductor supervisor (BAPI-396, conductor C4).
+ *
+ * The LLM is JUDGMENT-ONLY. It is consulted solely to classify ambiguous stalls
+ * and to draft short escalation text — compact snapshot in, strict JSON out. It
+ * NEVER executes privileged actions and is NEVER the source of truth: a
+ * malformed, disabled, exhausted, or timed-out model call degrades to a
+ * deterministic assessment. This module is pure prompt/parse/budget logic with
+ * an injectable client and emits NO events.
+ */
+/** Raised when a model response cannot be trusted as a valid judgment. */
+export class SupervisorJudgmentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SupervisorJudgmentError";
+    }
+}
+/** Classifications the supervisor accepts from the judgment model. */
+export const ALLOWED_JUDGMENT_CLASSIFICATIONS = new Set([
+    "progressing",
+    "ambiguous",
+    "stuck",
+    "blocked",
+    "unknown",
+]);
+/**
+ * Build the judgment-only system prompt. Uses `## HEADERS ##` sections, states
+ * the model only classifies stalls / drafts escalation text, prohibits claiming
+ * to execute actions, and requires strict JSON output.
+ */
+export function buildSupervisorAssessmentSystemPrompt() {
+    return [
+        "## ROLE ##",
+        "You are a read-only watchdog assistant for a multi-agent coding supervisor.",
+        "You classify whether a worker appears stuck and optionally draft a short, human-readable escalation note.",
+        "",
+        "## HARD CONSTRAINTS ##",
+        "- You ONLY classify ambiguous stalls and draft escalation text.",
+        "- You have NO ability to take actions. Never claim to have executed, killed, merged, retried, or fixed anything.",
+        "- You are NEVER the source of truth; deterministic signals override your judgment.",
+        "- Do not request or reveal secrets, tokens, or raw payloads.",
+        "",
+        "## OUTPUT FORMAT ##",
+        "Return STRICT JSON only — no prose, no markdown fences. The object must have exactly these keys:",
+        '  "classification": one of "progressing" | "ambiguous" | "stuck" | "blocked" | "unknown"',
+        '  "confidence": a number between 0 and 1',
+        '  "should_escalate": a boolean',
+        '  "reason": a short machine reason string',
+        '  "draft_escalation_text": a short human-readable string, or null',
+    ].join("\n");
+}
+/**
+ * Build the user prompt from a compact judgment request. The dynamic JSON
+ * context is wrapped in triple quotes; only compact, secret-free fields are
+ * included (the request itself must already be secret-free).
+ */
+export function buildSupervisorAssessmentUserPrompt(request) {
+    const compact = {
+        run_id: request.run_id,
+        candidate: {
+            reason: request.candidate.reason,
+            state: request.candidate.state,
+            liveness: request.candidate.liveness,
+            elapsed_ms: request.candidate.elapsed_ms,
+            context: request.candidate.context,
+        },
+        worker: request.worker,
+    };
+    return [
+        "## SUPERVISOR SNAPSHOT ##",
+        "Classify the worker situation below and decide whether it warrants escalation.",
+        "",
+        '"""',
+        JSON.stringify(compact, null, 2),
+        '"""',
+    ].join("\n");
+}
+/** Top-level keys that, if present, mark a response as action-like (rejected). */
+const ACTION_LIKE_KEYS = new Set([
+    "executed",
+    "action",
+    "actions",
+    "command",
+    "commands",
+    "kill",
+    "killed",
+    "merge",
+    "merged",
+    "transition",
+    "deleted",
+    "wrote",
+    "mutated",
+    "ran",
+]);
+/** Phrases in drafted text that assert a privileged action was performed. */
+const ACTION_LIKE_PHRASES = [
+    /\bi (?:have )?(?:killed|merged|executed|ran|deleted|restarted|retried|fixed|committed|pushed)\b/i,
+    /\bhas been (?:killed|merged|executed|restarted|deleted)\b/i,
+    /\bworker (?:killed|terminated|restarted)\b/i,
+];
+/** Parse a JSON value (string or already-parsed object). */
+function asObject(raw) {
+    let value = raw;
+    if (typeof raw === "string") {
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            throw new SupervisorJudgmentError("judgment response is not valid JSON");
+        }
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new SupervisorJudgmentError("judgment response must be a JSON object");
+    }
+    return value;
+}
+/**
+ * Parse + validate a strict-JSON judgment response. Rejects non-objects,
+ * malformed JSON, unknown classifications, missing/typed-wrong fields, and any
+ * action-like output (forbidden keys or draft text claiming privileged work).
+ * Throws {@link SupervisorJudgmentError} on any violation.
+ */
+export function parseSupervisorJudgmentResponse(raw) {
+    const obj = asObject(raw);
+    // Reject action-like keys outright.
+    for (const key of Object.keys(obj)) {
+        if (ACTION_LIKE_KEYS.has(key.toLowerCase())) {
+            throw new SupervisorJudgmentError(`judgment response contains forbidden action key "${key}"`);
+        }
+    }
+    const classification = obj.classification;
+    if (typeof classification !== "string" || !ALLOWED_JUDGMENT_CLASSIFICATIONS.has(classification)) {
+        throw new SupervisorJudgmentError("judgment response has an invalid 'classification'");
+    }
+    const confidence = obj.confidence;
+    if (typeof confidence !== "number" || !Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+        throw new SupervisorJudgmentError("judgment response 'confidence' must be a number in [0,1]");
+    }
+    const shouldEscalate = obj.should_escalate;
+    if (typeof shouldEscalate !== "boolean") {
+        throw new SupervisorJudgmentError("judgment response 'should_escalate' must be a boolean");
+    }
+    const reason = obj.reason;
+    if (typeof reason !== "string" || reason.trim().length === 0) {
+        throw new SupervisorJudgmentError("judgment response 'reason' must be a non-empty string");
+    }
+    let draft = null;
+    const draftRaw = obj.draft_escalation_text;
+    if (draftRaw !== null && draftRaw !== undefined) {
+        if (typeof draftRaw !== "string") {
+            throw new SupervisorJudgmentError("judgment response 'draft_escalation_text' must be a string or null");
+        }
+        for (const pattern of ACTION_LIKE_PHRASES) {
+            if (pattern.test(draftRaw)) {
+                throw new SupervisorJudgmentError("judgment draft text claims a privileged action");
+            }
+        }
+        draft = draftRaw;
+    }
+    return {
+        classification,
+        confidence,
+        should_escalate: shouldEscalate,
+        reason,
+        draft_escalation_text: draft,
+    };
+}
+/** Build the deterministic, degraded-mode assessment for a candidate. */
+function degradedAssessment(candidate, reason) {
+    return {
+        classification: "unknown",
+        confidence: 0,
+        // Degraded mode never SUPPRESSES a surfaced stall: a candidate the
+        // deterministic layer already flagged stays escalated.
+        should_escalate: true,
+        reason: `${candidate.reason}:${reason}`,
+        draft_escalation_text: null,
+        source: "degraded",
+    };
+}
+/**
+ * Assess one escalation candidate. Enforces the LLM budget BEFORE calling the
+ * injectable client: when the LLM is disabled, the budget is exhausted, or the
+ * client times out / errors / returns malformed output, a deterministic
+ * degraded-mode assessment is returned. On a successful call `budget.used_calls`
+ * is incremented. This function emits NO events.
+ */
+export async function assessSupervisorCandidate(request, config, budget, client) {
+    const candidate = request.candidate;
+    if (!config.llm_enabled || !budget.enabled || budget.max_calls <= 0) {
+        return degradedAssessment(candidate, "llm_disabled");
+    }
+    if (budget.used_calls >= budget.max_calls) {
+        return degradedAssessment(candidate, "budget_exhausted");
+    }
+    // Count the attempt against the budget regardless of outcome so a flaky model
+    // cannot be retried unboundedly within a single run.
+    budget.used_calls += 1;
+    let response;
+    try {
+        const raw = await client(request);
+        response = parseSupervisorJudgmentResponse(raw);
+    }
+    catch {
+        return degradedAssessment(candidate, "llm_failed");
+    }
+    return {
+        classification: response.classification,
+        confidence: response.confidence,
+        should_escalate: response.should_escalate,
+        reason: response.reason,
+        draft_escalation_text: response.draft_escalation_text,
+        source: "llm",
+    };
+}

package/build/conductor/supervisor-ledger.js

@@ -0,0 +1,119 @@
+/**
+ * Idempotent supervisor assessment emission (BAPI-396, conductor C4).
+ *
+ * The supervisor records its escalation decisions as `supervisor.assessment`
+ * ledger events. To guarantee no duplicate escalation across crash/restart or
+ * concurrent retries, each event carries a deterministic id derived from a
+ * STABLE idempotency key. The key is built only from normalized dimensions
+ * (run id, optional worker id, reason, kind, cooldown window) — it deliberately
+ * EXCLUDES raw event payloads and any LLM free text, so two assessments with
+ * different draft text but the same decision collide on the `events.id` UNIQUE
+ * constraint instead of double-emitting.
+ *
+ * This module performs NO privileged action: it only writes an audit event to
+ * the local ledger.
+ */
+import { createHash } from "node:crypto";
+import { emitConductorEvent } from "./store.js";
+/** Normalize a dimension to a stable, case-folded, trimmed token. */
+function normalizeDimension(value) {
+    return (value ?? "").trim().toLowerCase();
+}
+/**
+ * Build a stable idempotency key from normalized dimensions. Whitespace and
+ * case are normalized; empty/undefined `worker_id` collapses to a fixed
+ * run-level token. NO raw payload or LLM free text ever enters the key.
+ */
+export function makeSupervisorIdempotencyKey(meta) {
+    const parts = [
+        normalizeDimension(meta.run_id),
+        normalizeDimension(meta.worker_id) || "(run)",
+        normalizeDimension(meta.reason),
+        normalizeDimension(meta.kind),
+        normalizeDimension(meta.cooldown_window),
+    ];
+    return parts.join("|");
+}
+/**
+ * Derive a deterministic, UUID-shaped event id from an idempotency key. Repeated
+ * calls with the same key always return the same id, so a retrying/restarting
+ * supervisor collides on the `events.id` UNIQUE constraint instead of appending
+ * a duplicate assessment. Mirrors `makeStableProducerEventId` in
+ * `producer-ledger.ts`.
+ */
+export function makeSupervisorAssessmentEventId(idempotencyKey) {
+    const h = createHash("sha256")
+        .update(`supervisor.assessment:${idempotencyKey}`)
+        .digest("hex");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+/** Heuristically detect a SQLite duplicate-id / UNIQUE constraint failure. */
+function isDuplicateConstraintError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    if (typeof code === "string" && code.startsWith("SQLITE_CONSTRAINT"))
+        return true;
+    const message = error.message;
+    if (typeof message === "string") {
+        const lowered = message.toLowerCase();
+        if (lowered.includes("unique constraint") || lowered.includes("constraint failed"))
+            return true;
+    }
+    return false;
+}
+/**
+ * Emit a `supervisor.assessment` event under a deterministic, idempotency-keyed
+ * id. The idempotency key is embedded under `data.details.idempotency_key` so a
+ * later ledger scan can find it, and the event id is derived from that key so a
+ * duplicate emit collides on the UNIQUE constraint. A duplicate constraint (from
+ * a racing or restarted supervisor) is classified as `{ emitted: false,
+ * 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 = {}) {
+    const emitEvent = deps.emitEvent ?? emitConductorEvent;
+    const idempotencyKey = makeSupervisorIdempotencyKey(input.idempotency);
+    const eventId = makeSupervisorAssessmentEventId(idempotencyKey);
+    // Build secret-free assessment details. The assessment carries only the
+    // classification/decision and optional short drafted text — never raw payload.
+    const details = {
+        ...(input.details ?? {}),
+        idempotency_key: idempotencyKey,
+        reason: input.idempotency.reason,
+        kind: input.idempotency.kind,
+        cooldown_window: input.idempotency.cooldown_window,
+        classification: input.assessment.classification,
+        confidence: input.assessment.confidence,
+        should_escalate: input.assessment.should_escalate,
+        assessment_source: input.assessment.source,
+    };
+    if (input.assessment.draft_escalation_text) {
+        details.draft_escalation_text = input.assessment.draft_escalation_text;
+    }
+    const event = {
+        id: eventId,
+        source: "conductor-supervisor",
+        type: "supervisor.assessment",
+        run_id: input.run_id,
+        worker_id: input.idempotency.worker_id ?? input.worker_id ?? null,
+        producer: "conductor-supervisor",
+        observed_via: "supervisor",
+        data: {
+            summary: `supervisor assessment: ${input.idempotency.reason}`,
+            status: input.assessment.should_escalate ? "escalated" : "noted",
+            reason: input.idempotency.reason,
+            details,
+        },
+    };
+    try {
+        const result = emitEvent(event);
+        return { emitted: true, event_id: eventId, event: result.event };
+    }
+    catch (error) {
+        if (isDuplicateConstraintError(error)) {
+            return { emitted: false, reason: "duplicate" };
+        }
+        throw error;
+    }
+}

package/build/conductor/supervisor-merge.js

@@ -0,0 +1,127 @@
+/**
+ * Supervisor merge pipeline wrapper (Conductor C6, BAPI-398).
+ *
+ * Processes an eligible worker-scoped `gate.met` event by calling the API-owned
+ * merge decision/execution endpoint and recording the returned `merge.*` ledger
+ * events into the LOCAL conductor ledger. This module:
+ *
+ *   - never performs a provider merge locally and never handles VCS write
+ *     credentials (no `gh`, no GITHUB_TOKEN, no installation token, no shell-out),
+ *   - skips the API call when a terminal `merge.succeeded` already exists locally,
+ *   - de-duplicates `merge.dry_run` without ever treating it as terminal,
+ *   - maps sanitized Bridge API errors to `merge.failed` reason codes instead of
+ *     crashing the supervisor loop.
+ */
+import { ConductorBridgeApiError, mergePullRequestForGate, } from "./bridge-api-client.js";
+import { emitMergeLedgerEventIfNew, extractMergeActionIdentityFromGateEvent, hasMergeDryRun, hasMergePendingApproval, hasTerminalMergeSucceeded, } from "./merge-ledger.js";
+/**
+ * Convert an eligible merge identity into the protected endpoint request shape.
+ * Includes the gate event reference (id/seq/time) and the deterministic action
+ * key; never includes a branch name or raw provider payload.
+ */
+export function buildMergeRequestFromGateEvent(identity) {
+    return {
+        repo_name: identity.repo,
+        pr_number: identity.pr_number,
+        expected_head_sha: identity.head_sha,
+        gate: {
+            name: identity.gate_name,
+            config_hash: identity.config_hash,
+            required_checks: identity.required_checks,
+        },
+        action_key: identity.action_key,
+        gate_event: identity.gate_event,
+    };
+}
+/** Map a sanitized Bridge API error kind to a `merge.failed` reason code. */
+function mapApiErrorReason(error) {
+    if (error instanceof ConductorBridgeApiError) {
+        switch (error.kind) {
+            case "timeout":
+                return "api_timeout";
+            case "network":
+                return "api_network";
+            case "unauthorized":
+                return "api_unauthorized";
+            case "server":
+            case "http":
+                return "api_unavailable";
+            case "invalid-input":
+                return "api_invalid";
+        }
+    }
+    return "api_network";
+}
+/**
+ * Process an eligible `gate.met` event end-to-end: terminal-success short-circuit,
+ * API merge call, ordered ledger recording, and sanitized error handling. Never
+ * throws into the supervisor loop and never logs secrets or raw HTTP responses.
+ */
+export async function processGateMetMerge(access, event, deps = {}) {
+    const extract = deps.extractIdentity ?? extractMergeActionIdentityFromGateEvent;
+    const checkTerminal = deps.hasTerminal ?? hasTerminalMergeSucceeded;
+    const checkDryRun = deps.hasDryRun ?? hasMergeDryRun;
+    const checkPendingApproval = deps.hasPendingApproval ?? hasMergePendingApproval;
+    const mergeFn = deps.merge ?? mergePullRequestForGate;
+    const identity = extract(event);
+    if (!identity) {
+        return { processed: false, reason: "ineligible" };
+    }
+    const actionKey = identity.action_key;
+    // Terminal-success short-circuit BEFORE any API call (idempotent across restart).
+    if (checkTerminal(actionKey)) {
+        return { processed: false, reason: "already_succeeded" };
+    }
+    const baseDetails = {
+        action_key: actionKey,
+        repo: identity.repo,
+        pr_number: identity.pr_number,
+        expected_head_sha: identity.head_sha,
+        gate: identity.gate_identity,
+    };
+    let response;
+    try {
+        response = await mergeFn(access, buildMergeRequestFromGateEvent(identity));
+    }
+    catch (error) {
+        const reason = mapApiErrorReason(error);
+        emitMergeLedgerEventIfNew({
+            type: "merge.failed",
+            action_key: actionKey,
+            status: "failed",
+            reason,
+            details: baseDetails,
+            run_id: event.run_id ?? null,
+            worker_id: event.worker_id ?? null,
+            summary: `merge.failed ${reason}`,
+        }, { emitEvent: deps.emitEvent });
+        return { processed: true, outcome: "api_error", reason };
+    }
+    const emitted = [];
+    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)) {
+            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)) {
+            emitted.push({ type: ledgerEvent.type, emitted: false });
+            continue;
+        }
+        const result = emitMergeLedgerEventIfNew({
+            type: ledgerEvent.type,
+            action_key: actionKey,
+            status: ledgerEvent.status,
+            reason: ledgerEvent.reason ?? null,
+            details: ledgerEvent.details ?? baseDetails,
+            run_id: event.run_id ?? null,
+            worker_id: event.worker_id ?? null,
+        }, { emitEvent: deps.emitEvent });
+        emitted.push({ type: ledgerEvent.type, emitted: result.emitted });
+    }
+    return { processed: true, outcome: response.status, emitted };
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Supervisor → worker escalation message relay (BAPI-397, conductor C5).
+ *
+ * Bridges the deterministic supervisor escalation pipeline (BAPI-396) to the
+ * cooperative message relay: an escalation candidate + assessment is converted
+ * into a typed, compact, secret-free {@link SendWorkerMessageInput} and enqueued
+ * through {@link sendWorkerMessage}. Delivery is cooperative — the worker polls
+ * `check_messages`; this module NEVER injects into a live session.
+ *
+ * Idempotency/cooldown are owned by the store: the `cause_seq` is the
+ * supervisor's `last_seq` at decision time, so a restarted supervisor that
+ * re-assesses the same window enqueues the same idempotency key and the store
+ * dedupes it. This module is best-effort by design and copies only allowlisted,
+ * bounded fields — never raw logs, secrets, or unbounded text.
+ */
+import { sendWorkerMessage } from "./store.js";
+/**
+ * Convert an escalation candidate + assessment + run state into a relay message
+ * input. The message `type` encodes the supervisor reason
+ * (`supervisor.<reason>`, e.g. `supervisor.worker_stalled`). `cause_seq` is the
+ * run's `last_seq` so a re-assessment of the same window is idempotent. The
+ * payload uses only allowlisted top-level keys (`summary`, `status`, `details`);
+ * every escalation detail is nested under `details` and is compact + secret-free.
+ */
+export function buildSupervisorEscalationWorkerMessage(candidate, assessment, state) {
+    const details = {
+        reason: candidate.reason,
+        state: candidate.state,
+        liveness: candidate.liveness,
+        elapsed_ms: candidate.elapsed_ms,
+        assessment_source: assessment.source,
+    };
+    if (assessment.draft_escalation_text) {
+        details.draft_escalation_text = assessment.draft_escalation_text;
+    }
+    return {
+        run_id: state.run_id,
+        worker_id: candidate.worker_id,
+        type: `supervisor.${candidate.reason}`,
+        cause_seq: state.last_seq,
+        payload: {
+            summary: `supervisor escalation: ${candidate.reason}`,
+            status: assessment.should_escalate ? "escalated" : "noted",
+            details,
+        },
+        source: "conductor-supervisor",
+        producer: "worker-message-relay",
+    };
+}
+/**
+ * Build the escalation message and enqueue it through {@link sendWorkerMessage}.
+ * The store result already encodes the expected idempotency/cooldown outcomes
+ * (`duplicate` / `cooldown_suppressed`), which this wrapper returns verbatim
+ * 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 = {}) {
+    const sendMessage = deps.sendMessage ?? sendWorkerMessage;
+    const input = buildSupervisorEscalationWorkerMessage(candidate, assessment, state);
+    return sendMessage(input);
+}

package/build/conductor/supervisor-notification.js

@@ -0,0 +1,39 @@
+/**
+ * Out-of-band human notification dispatch for the Epic Supervisor (BAPI-411, S7).
+ *
+ * Builds a minimal, secret-free escalation payload and delivers it via the
+ * protected `/jira/epic-runs/{epicRunId}/notifications` endpoint. The function
+ * is fail-open: a missing credential, a network error, or any thrown exception
+ * is swallowed so the supervisor loop is never interrupted by a notification
+ * failure.
+ */
+import { resolveConductorBridgeApiAccess, buildConductorJiraUrl, fetchConductorJsonPostWithTimeout, CONDUCTOR_FETCH_TIMEOUT_MS, } from "./bridge-api-client.js";
+export async function dispatchSupervisorNotification(epicRunId, candidate, assessment, idempotencyKey) {
+    const result = await resolveConductorBridgeApiAccess();
+    if (!result.ok)
+        return; // fail open — credential gaps must never crash the supervisor
+    const { access } = result;
+    const url = buildConductorJiraUrl(access.baseUrl, `/epic-runs/${encodeURIComponent(epicRunId)}/notifications`);
+    const payload = {
+        repo_name: access.repoName,
+        idempotency_key: idempotencyKey,
+        summary: {
+            reason: candidate.reason,
+            kind: candidate.kind,
+            worker_id: candidate.worker_id ?? null,
+            elapsed_ms: candidate.elapsed_ms,
+            ticket_key: (candidate.context?.ticket_key ?? null),
+            draft_text: assessment.draft_escalation_text ?? null,
+        },
+    };
+    const headers = {
+        "X-API-Key": access.apiKey,
+        "Content-Type": "application/json",
+    };
+    try {
+        await fetchConductorJsonPostWithTimeout(url, headers, JSON.stringify(payload), CONDUCTOR_FETCH_TIMEOUT_MS, fetch);
+    }
+    catch {
+        // Best-effort delivery — a notification failure must never abort processEscalations.
+    }
+}