@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/conductor/supervisor-judgment.js

@@ -1,215 +0,0 @@
-/**
- * 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",
-    };
-}