@bridge_gpt/mcp-server 0.2.62 → 0.2.66

package/build/executor/completion-contract.js

@@ -0,0 +1,423 @@
+/**
+ * The required-work completion-evidence contract (BAPI-1301, D4a) — executor
+ * mirror of `src/python/llms/executor_completion_contract.py`.
+ *
+ * A covered child attempt (`implement`, `resume`, `remediate`, `ci_fix`) that
+ * was claimed under the `completion_evidence.v1` requirement reports its
+ * terminal outcome with one bounded, versioned envelope built from facts the
+ * EXECUTOR observed: the stream-json lifecycle it read to EOF, the processes it
+ * swept, and the finalization facts it verified. The server re-validates the
+ * envelope against the claimed row and refuses success unless the envelope
+ * proves the attempt finished its required work and cleaned up after itself.
+ *
+ * What the envelope proves, and what it does not:
+ *  - A task that ended `succeeded` proves its LIFECYCLE ended. It does not prove
+ *    the check it ran is correct or that an effect it attempted was authorized.
+ *    Declared checks are run by the executor itself (D4c) and reported through
+ *    `verification`.
+ *  - `cleanup.verdict: "confirmed"` covers processes that kept the inherited
+ *    environment. Every covered verdict names `residual_not_covered`: a daemon
+ *    that detaches AND clears its environment carries no tag and is invisible to
+ *    the sweep on macOS. The controlled workload excludes it.
+ *
+ * Nothing in the envelope is a prompt, a raw tool argument, a provider payload,
+ * a process argument, an environment value, a path, or a URL. Inputs and targets
+ * cross the wire only as SHA-256 digests.
+ */
+import { createHash } from "node:crypto";
+/** The capability string declared on `POST /claim` and required by covered jobs. */
+export const COMPLETION_EVIDENCE_CAPABILITY = "completion_evidence.v1";
+export const COMPLETION_CONTRACT_VERSION = 1;
+/**
+ * BAPI-1302 (D4c) — the envelope version that carries executor-run check facts
+ * in `verification_facts`. Sent for every job whose payload carries a
+ * required-verification declaration; version 1 otherwise.
+ */
+export const COMPLETION_CONTRACT_VERSION_V2 = 2;
+/**
+ * BAPI-1302 (D4c) — declared on `POST /claim` when this executor runs declared
+ * checks itself. A job carrying a declaration requires it, so an executor
+ * without the runner never claims one.
+ */
+export const REQUIRED_VERIFICATION_CAPABILITY = "required_verification.v1";
+export const COMPLETION_CONTRACT_MARKER_VALUES = ["completion_evidence.v1", "legacy"];
+export const COVERED_JOB_TYPES = ["implement", "resume", "remediate", "ci_fix"];
+/**
+ * The measured runtime identity (BAPI-1292 probe): Claude Code 2.1.282 on macOS
+ * arm64. A measured baseline, not a certification — any other CLI version or
+ * platform is unsupported until measured.
+ */
+export const SUPPORTED_COMPLETION_RUNTIME = {
+    adapter: "claude",
+    cli_version: "2.1.282",
+    platform: "darwin-arm64",
+    event_schema: "claude-stream-json.lifecycle.v1",
+};
+export const EVIDENCE_VALUES = ["sufficient", "insufficient"];
+export const INSUFFICIENT_REASON_VALUES = [
+    "no_init_event",
+    "no_result_turn",
+    "active_turn_at_close",
+    "live_required_work",
+    "stale_task_snapshot",
+    "late_activity_after_close",
+    "stdout_not_read_to_eof",
+    "stream_parse_error",
+    "stream_lost",
+    "stream_oversize",
+    "stream_truncated",
+    "event_conflict",
+    "event_unknown",
+    "ledger_capacity_exhausted",
+    "denial_capacity_exhausted",
+    "forced_kill_no_cli_teardown",
+    "no_process_exit",
+    "transport_failed_before_work",
+    "transport_failed_after_progress",
+    "allowance_exhausted",
+    "unsupported_runtime",
+    "binding_mismatch",
+    // Failed before any worker was launched: nothing to be incomplete, nothing to
+    // clean up. Alone, it is not a completion cause (see isNotLaunchedEnvelope).
+    "worker_not_launched",
+    // BAPI-1302: the job's required-verification declaration was unusable, so no
+    // worker was launched against a partial set of checks.
+    "declaration_refused",
+];
+export const EXECUTION_VALUES = ["complete", "incomplete", "unknown"];
+/**
+ * `not_declared` is "no declared local verification" — NOT a pass. `unavailable`
+ * means checks were declared but no runner is installed (D4c absent): a park.
+ */
+export const VERIFICATION_VALUES = [
+    "not_declared",
+    "passed",
+    "failed",
+    "unavailable",
+    "incomplete",
+];
+export const FINALIZATION_VALUES = ["ok", "unmet", "not_required", "unknown"];
+export const CLEANUP_VERDICT_VALUES = ["confirmed", "failed", "unconfirmed"];
+export const CLEANUP_RESIDUAL_ENV_SCRUBBING_DAEMON = "environment_scrubbing_daemon";
+/**
+ * The second accepted residual (BAPI-1301). macOS hides a platform (Apple-signed)
+ * binary's environment from `ps -E`, so `/bin/bash`, `/bin/zsh` or `/bin/sleep`
+ * shows no tag. Tracked descendants cover the common case; a platform-binary
+ * process that detaches from the tracked tree between samples (reparented to
+ * launchd) is not attributable. Named on every verdict; the server still
+ * requires only the scrubbing-daemon token.
+ */
+export const CLEANUP_RESIDUAL_PLATFORM_BINARY_ENV_HIDDEN = "platform_binary_environment_hidden";
+export const CLEANUP_REASON_VALUES = [
+    "survivors_detected",
+    "enumeration_failed",
+    "ownership_unverifiable",
+    "executor_interrupted",
+    "sweep_deadline_exhausted",
+    "not_run",
+];
+export const TASK_KIND_VALUES = [
+    "delegate",
+    "delegate_bg",
+    "bash_bg",
+    "monitor",
+    "bash_task",
+    "subagent_bash",
+    "task",
+];
+export const TASK_STATE_VALUES = [
+    "pending",
+    "succeeded",
+    "failed",
+    "stopped",
+    "withdrawn",
+    "replaced",
+    "unknown",
+    "conflict",
+];
+/** The only states that resolve a REQUIRED task. */
+export const TASK_RESOLVING_STATES = new Set([
+    "succeeded",
+    "replaced",
+]);
+export const DENIAL_OPERATION_VALUES = [
+    "push",
+    "pr_create",
+    "external_mutation",
+    "delegate",
+    "other",
+    "unknown",
+];
+export const DENIAL_STATE_VALUES = ["blocking", "historical", "unlinked", "ambiguous"];
+export const MISSING_CAPABILITY_VALUES = [
+    "declared_check_runner",
+    "permission_enforcement",
+    "focused_ci_repair",
+    "repaired_head_convergence",
+    "continuation",
+];
+/** BAPI-1302 — where a job's declaration came from. Neither `absent` nor `declared_empty` is a pass. */
+export const DECLARATION_PROVENANCE_VALUES = ["declared", "declared_empty", "absent", "refused"];
+/** BAPI-1302 — how one declared command ended, as the executor observed it. */
+export const CHECK_OUTCOME_VALUES = [
+    "exited_zero",
+    "exited_nonzero",
+    "timed_out",
+    "launch_error",
+    "cancelled",
+    "not_run",
+];
+/** BAPI-1302 — bounded reason for a non-zero outcome. Never exit text or output. */
+export const CHECK_REASON_VALUES = [
+    "declared_timeout",
+    "reservation_exhausted",
+    "stopped_after_interruption",
+    "ownership_lost",
+    "executor_cancelled",
+    "spawn_failed",
+];
+/**
+ * BAPI-1302 — what the executor saw of the final local artifact (full HEAD plus
+ * the TRACKED tree and index) around the checks. Only `stable` lets a result
+ * count. Untracked files are outside the guarantee.
+ */
+export const ARTIFACT_VALUES = [
+    "stable",
+    "not_observed",
+    "head_unreadable",
+    "dirty_before",
+    "head_moved",
+    "tracked_changed",
+    "unobservable_after",
+];
+export const MAX_CHECKS = 16;
+export const MAX_CHECK_DURATION_MS = 2 * 60 * 60 * 1000;
+export const COMPLETION_CAUSE_VALUES = [
+    "required_work_incomplete",
+    "required_check_failed",
+    "permission_stop",
+    "unsupported_completion_evidence",
+    "cleanup_unconfirmed",
+    "verification_runner_unavailable",
+];
+export const MAX_TASKS = 64;
+export const MAX_DENIALS = 32;
+export const MAX_IDENTIFIER_CHARS = 128;
+export const MAX_SERIALIZED_BYTES = 32 * 1024;
+/** One stream-json event larger than this is `stream_oversize`, never parsed. */
+export const MAX_EVENT_BYTES = 1024 * 1024;
+const IDENTIFIER_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
+export function sha256Hex(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+/** A stable digest of a structured value (sorted keys). Never the value itself. */
+export function digestStructured(value) {
+    return sha256Hex(stableStringify(value));
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value ?? null);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+/** An opaque identifier, or null when the value cannot be carried safely. */
+export function boundedIdentifier(value) {
+    if (typeof value !== "string")
+        return null;
+    if (value.length === 0 || value.length > MAX_IDENTIFIER_CHARS)
+        return null;
+    return IDENTIFIER_RE.test(value) ? value : null;
+}
+export function isCoveredJobType(jobType) {
+    return COVERED_JOB_TYPES.includes(jobType);
+}
+/** Whether a claimed job carries the covered completion contract. */
+export function claimRequiresCompletionEvidence(requiredCapabilities) {
+    return Array.isArray(requiredCapabilities) && requiredCapabilities.includes(COMPLETION_EVIDENCE_CAPABILITY);
+}
+export function runtimeMatchesSupported(runtime) {
+    if (!runtime)
+        return false;
+    return (runtime.adapter === SUPPORTED_COMPLETION_RUNTIME.adapter &&
+        runtime.cli_version === SUPPORTED_COMPLETION_RUNTIME.cli_version &&
+        runtime.platform === SUPPORTED_COMPLETION_RUNTIME.platform &&
+        runtime.event_schema === SUPPORTED_COMPLETION_RUNTIME.event_schema);
+}
+export function unresolvedRequiredTasks(envelope) {
+    return envelope.tasks.filter((t) => t.required && !TASK_RESOLVING_STATES.has(t.state));
+}
+const FULL_SHA_RE = /^[0-9a-f]{40}$/;
+/**
+ * The verification verdict version-2 facts support. Mirrors the server's
+ * `verification_verdict_from_facts` clause for clause; the envelope's
+ * `verification` token must equal it or the server refuses the envelope.
+ *
+ * `declaredCount` is the number of commands the job's declaration names; a
+ * declared command with no fact is not-run, so the verdict is `incomplete`.
+ */
+export function verificationVerdictFromFacts(facts, declaredCount) {
+    if (facts.provenance === "absent" || facts.provenance === "declared_empty")
+        return "not_declared";
+    if (facts.provenance !== "declared")
+        return "incomplete";
+    const expected = declaredCount ?? facts.commands.length;
+    if (expected === 0 || facts.commands.length !== expected)
+        return "incomplete";
+    if (facts.artifact !== "stable" || facts.tested_head_sha === null || !FULL_SHA_RE.test(facts.tested_head_sha)) {
+        return "incomplete";
+    }
+    if (facts.commands.some((c) => c.outcome !== "exited_zero" && c.outcome !== "exited_nonzero"))
+        return "incomplete";
+    if (facts.commands.some((c) => c.outcome === "exited_nonzero"))
+        return "failed";
+    return "passed";
+}
+/**
+ * Closed reason the envelope cannot support a covered success, or null.
+ * Mirrors the server's `success_refusal_reason` clause for clause, so the
+ * executor never sends `/complete` for an envelope the server would refuse.
+ */
+export function successRefusalReason(envelope) {
+    if (envelope.evidence !== "sufficient")
+        return "evidence_insufficient";
+    if (envelope.execution !== "complete")
+        return "execution_not_complete";
+    if (unresolvedRequiredTasks(envelope).length > 0)
+        return "required_task_unresolved";
+    if (envelope.verification !== "passed" && envelope.verification !== "not_declared") {
+        return "verification_not_acceptable";
+    }
+    if (envelope.finalization !== "ok" && envelope.finalization !== "not_required") {
+        return "finalization_not_met";
+    }
+    if (envelope.cleanup.verdict !== "confirmed" || envelope.cleanup.survivors !== 0) {
+        return "cleanup_not_confirmed";
+    }
+    if (envelope.denials.some((d) => d.state === "blocking"))
+        return "blocking_denial";
+    if (envelope.cause !== null)
+        return "cause_present";
+    return null;
+}
+/**
+ * The executor-proposed cause for an envelope that cannot be a success. Same
+ * order as the server's `derive_park_cause`; the server re-derives it and never
+ * lets this value widen what the rest of the envelope proves.
+ */
+export function deriveCompletionCause(envelope) {
+    const reasons = new Set(envelope.insufficient_reasons);
+    if (reasons.has("unsupported_runtime"))
+        return "unsupported_completion_evidence";
+    if (isNotLaunchedEnvelope(envelope))
+        return null;
+    const blocking = envelope.denials.filter((d) => d.state === "blocking");
+    if (blocking.length > 0 && envelope.evidence === "sufficient" && blocking.some((d) => d.result_after_denial)) {
+        return "permission_stop";
+    }
+    if (envelope.cleanup.verdict !== "confirmed" || envelope.cleanup.survivors !== 0)
+        return "cleanup_unconfirmed";
+    const unresolved = envelope.tasks.some((t) => t.required && !TASK_RESOLVING_STATES.has(t.state));
+    if (blocking.length > 0 ||
+        envelope.evidence !== "sufficient" ||
+        envelope.execution !== "complete" ||
+        unresolved ||
+        envelope.verification === "incomplete") {
+        return "required_work_incomplete";
+    }
+    if (envelope.verification === "unavailable")
+        return "verification_runner_unavailable";
+    if (envelope.verification === "failed")
+        return "required_check_failed";
+    // Nothing completion-specific is wrong: an unmet finalization (or success)
+    // keeps its existing executor/server classification.
+    return null;
+}
+/**
+ * Whether an envelope reports a failure before any worker was launched: exactly
+ * the `worker_not_launched` reason, no task/denial/result, confirmed cleanup with
+ * zero survivors. Mirrors the server's `is_not_launched_envelope`.
+ */
+export function isNotLaunchedEnvelope(envelope) {
+    return (envelope.insufficient_reasons.length === 1 &&
+        envelope.insufficient_reasons[0] === "worker_not_launched" &&
+        envelope.tasks.length === 0 &&
+        envelope.denials.length === 0 &&
+        envelope.results_seen === 0 &&
+        envelope.cleanup.verdict === "confirmed" &&
+        envelope.cleanup.survivors === 0);
+}
+/**
+ * The envelope for a covered attempt that failed before any worker existed.
+ *
+ * Every covered terminal report must carry an envelope; without one the server
+ * refuses the report and the row eventually dead-letters as cleanup
+ * unconfirmed — parking a transient pre-spawn problem for a human with a
+ * misleading cause. Nothing was spawned, so cleanup is truthfully confirmed with
+ * zero survivors, and the report's own error kind keeps deciding.
+ */
+export function buildNotLaunchedEnvelope(input) {
+    return {
+        evidence_version: input.verificationFacts ? COMPLETION_CONTRACT_VERSION_V2 : COMPLETION_CONTRACT_VERSION,
+        runtime: { ...input.runtime },
+        binding: { ...input.binding },
+        session_id: null,
+        evidence: "insufficient",
+        insufficient_reasons: ["worker_not_launched"],
+        execution: "unknown",
+        verification: input.verification,
+        finalization: "unknown",
+        cleanup: {
+            verdict: "confirmed",
+            method: "env_tag_sweep",
+            survivors: 0,
+            reasons: [],
+            residual_not_covered: [...input.residuals],
+        },
+        tasks: [],
+        denials: [],
+        missing_capabilities: [],
+        results_seen: 0,
+        cause: null,
+        ...(input.verificationFacts ? { verification_facts: input.verificationFacts } : {}),
+    };
+}
+/**
+ * Enforce the serialized bound. An envelope that would exceed it drops its
+ * lowest-value detail (resolved tasks, then historical/unlinked denials) and
+ * becomes `insufficient` — it never silently loses an unresolved obligation.
+ */
+export function boundEnvelope(envelope) {
+    const size = (e) => Buffer.byteLength(JSON.stringify(e), "utf8");
+    if (size(envelope) <= MAX_SERIALIZED_BYTES)
+        return envelope;
+    const markOversize = (e) => {
+        const reasons = new Set(e.insufficient_reasons);
+        reasons.add("ledger_capacity_exhausted");
+        const next = {
+            ...e,
+            evidence: "insufficient",
+            insufficient_reasons: [...reasons],
+            execution: e.execution === "complete" ? "unknown" : e.execution,
+            cause: null,
+        };
+        return { ...next, cause: deriveCompletionCause(next) };
+    };
+    let next = markOversize({
+        ...envelope,
+        tasks: envelope.tasks.filter((t) => t.required && !TASK_RESOLVING_STATES.has(t.state)),
+    });
+    if (size(next) <= MAX_SERIALIZED_BYTES)
+        return next;
+    next = markOversize({
+        ...next,
+        denials: next.denials.filter((d) => d.state === "blocking" || d.state === "ambiguous"),
+    });
+    if (size(next) <= MAX_SERIALIZED_BYTES)
+        return next;
+    // Last resort: identities cannot fit. Keep the count-free verdict only.
+    return markOversize({ ...next, tasks: next.tasks.slice(0, 8), denials: next.denials.slice(0, 8) });
+}