@martinloop/mcp 0.3.8 → 0.5.0

package/dist/vendor/core/exits.js

@@ -0,0 +1,258 @@
+/**
+ * Eight-Exit Runtime — pure deterministic evaluator.
+ *
+ * EXIT_PRECEDENCE rationale (product decision — see contracts/exits.ts for rationale;
+ * any change to this array requires updating that paragraph in the same commit):
+ *   human_interrupt > external_event > wall_clock > budget_cap > turn_cap >
+ *   goal_met > error_threshold > no_progress
+ */
+import { createHash } from "node:crypto";
+// Precedence: human authority first, resource limits before goal success,
+// resource exits ranked by urgency (wall_clock > budget_cap > turn_cap).
+// Note: turn_cap is suppressed at signal-generation time when goalMet is true
+// so goal_met and turn_cap cannot co-occur in practice.
+const EXIT_PRECEDENCE = [
+    "human_interrupt",
+    "external_event",
+    "wall_clock",
+    "budget_cap",
+    "turn_cap",
+    "goal_met",
+    "error_threshold",
+    "no_progress"
+];
+export function createDefaultExitPolicy(budget, overrides = {}) {
+    const base = {
+        schemaVersion: "exit-policy/1",
+        goal: { verifierRequired: true, minimumScore: 1 },
+        turns: { max: budget.maxIterations },
+        budget: { maxUsd: budget.maxUsd, maxTokens: budget.maxTokens },
+        wallClock: { maxElapsedMs: 30 * 60 * 1000 },
+        progress: { windowSize: 3, unchangedStateLimit: 3 },
+        errors: { maxConsecutive: 3 },
+        humanInterrupt: { enabled: true },
+        externalEvent: { enabled: true }
+    };
+    return {
+        ...base,
+        ...overrides,
+        goal: { ...base.goal, ...overrides.goal },
+        turns: { ...base.turns, ...overrides.turns },
+        budget: { ...base.budget, ...overrides.budget },
+        wallClock: { ...base.wallClock, ...overrides.wallClock },
+        progress: { ...base.progress, ...overrides.progress },
+        errors: { ...base.errors, ...overrides.errors },
+        humanInterrupt: { ...base.humanInterrupt, ...overrides.humanInterrupt },
+        externalEvent: { ...base.externalEvent, ...overrides.externalEvent }
+    };
+}
+export function validateExitPolicy(policy) {
+    assertFinitePositive("turns.max", policy.turns.max);
+    assertFinitePositive("budget.maxUsd", policy.budget.maxUsd);
+    assertFinitePositive("budget.maxTokens", policy.budget.maxTokens);
+    assertFinitePositive("wallClock.maxElapsedMs", policy.wallClock.maxElapsedMs);
+    assertFinitePositive("progress.windowSize", policy.progress.windowSize);
+    assertFinitePositive("progress.unchangedStateLimit", policy.progress.unchangedStateLimit);
+    assertFinitePositive("errors.maxConsecutive", policy.errors.maxConsecutive);
+    if (policy.goal.minimumScore < 0 || policy.goal.minimumScore > 1) {
+        throw new RangeError("goal.minimumScore must be between 0 and 1");
+    }
+    if (policy.progress.unchangedStateLimit > policy.progress.windowSize) {
+        throw new RangeError("progress.unchangedStateLimit cannot exceed progress.windowSize");
+    }
+    if (policy.wallClock.deadlineAt !== undefined) {
+        const parsed = Date.parse(policy.wallClock.deadlineAt);
+        if (!Number.isFinite(parsed)) {
+            throw new RangeError("wallClock.deadlineAt must be an ISO timestamp");
+        }
+    }
+}
+export function evaluateExitPolicy(policy, snapshot) {
+    validateExitPolicy(policy);
+    const matches = [];
+    const push = (kind, reason, evidence) => {
+        matches.push({ kind, reason, evidence });
+    };
+    // 1. Human interrupt (highest authority — cannot be argued with)
+    if (policy.humanInterrupt.enabled && snapshot.humanInterrupt !== undefined) {
+        push("human_interrupt", snapshot.humanInterrupt.reason ?? "Human interrupt requested.", {
+            requestedAt: snapshot.humanInterrupt.requestedAt,
+            requestedBy: snapshot.humanInterrupt.requestedBy
+        });
+    }
+    // 2. External event
+    if (policy.externalEvent.enabled && snapshot.externalEvent !== undefined) {
+        push("external_event", snapshot.externalEvent.reason ?? "External terminal event observed.", {
+            source: snapshot.externalEvent.source,
+            event: snapshot.externalEvent.event,
+            disposition: snapshot.externalEvent.disposition,
+            subject: snapshot.externalEvent.subject,
+            evidenceUri: snapshot.externalEvent.evidenceUri
+        });
+    }
+    // 3. Goal met (verified success outranks resource exhaustion)
+    const result = snapshot.result;
+    const goalMet = result !== undefined &&
+        result.status === "completed" &&
+        (!policy.goal.verifierRequired || result.verificationPassed) &&
+        result.verifierScore >= policy.goal.minimumScore;
+    if (goalMet) {
+        push("goal_met", "Configured verification goal passed.", {
+            verifierScore: result.verifierScore,
+            minimumScore: policy.goal.minimumScore
+        });
+    }
+    // 4. Wall clock
+    const elapsedMs = Math.max(0, snapshot.nowMs - snapshot.runStartedAtMs);
+    const deadlineMs = policy.wallClock.deadlineAt === undefined
+        ? undefined
+        : Date.parse(policy.wallClock.deadlineAt);
+    if (elapsedMs >= policy.wallClock.maxElapsedMs ||
+        (deadlineMs !== undefined && snapshot.nowMs >= deadlineMs)) {
+        push("wall_clock", "Run wall-clock limit reached.", {
+            elapsedMs,
+            maxElapsedMs: policy.wallClock.maxElapsedMs,
+            deadlineAt: policy.wallClock.deadlineAt
+        });
+    }
+    // 5. Budget cap
+    const usdExceeded = snapshot.actualUsd >= policy.budget.maxUsd;
+    const tokensExceeded = snapshot.tokensUsed >= policy.budget.maxTokens;
+    if (usdExceeded || tokensExceeded) {
+        push("budget_cap", "Run token or dollar budget reached.", {
+            actualUsd: snapshot.actualUsd,
+            maxUsd: policy.budget.maxUsd,
+            tokensUsed: snapshot.tokensUsed,
+            maxTokens: policy.budget.maxTokens,
+            usdExceeded,
+            tokensExceeded
+        });
+    }
+    // 6. Turn cap — suppressed when goalMet: completing on the final allowed
+    // iteration is legitimate success, not an overrun. turn_cap fires only when
+    // iterations are exhausted without verified completion.
+    if (!goalMet && snapshot.turnsUsed >= policy.turns.max) {
+        push("turn_cap", "Run iteration limit reached.", {
+            turnsUsed: snapshot.turnsUsed,
+            maxTurns: policy.turns.max
+        });
+    }
+    // 7. Error threshold
+    if (snapshot.consecutiveErrors >= policy.errors.maxConsecutive) {
+        push("error_threshold", "Consecutive error threshold reached.", {
+            consecutiveErrors: snapshot.consecutiveErrors,
+            maxConsecutive: policy.errors.maxConsecutive
+        });
+    }
+    // 8. No progress — only fires when the window is FULL (A3 fix: sub-window must not fire)
+    const requiredHashes = policy.progress.unchangedStateLimit;
+    const recentHashes = snapshot.recentStateHashes.slice(-requiredHashes);
+    const hashStall = recentHashes.length === requiredHashes && new Set(recentHashes).size === 1;
+    if (hashStall || snapshot.trajectoryStop?.shouldStop === true) {
+        push("no_progress", snapshot.trajectoryStop?.reason ?? "Canonical run state stopped changing.", {
+            unchangedStateCount: hashStall ? recentHashes.length : 0,
+            stateHash: hashStall ? recentHashes[0] : undefined,
+            trajectoryStop: snapshot.trajectoryStop?.shouldStop ?? false
+        });
+    }
+    const matched = EXIT_PRECEDENCE.filter((kind) => matches.some((m) => m.kind === kind));
+    return {
+        schemaVersion: "exit-evaluation/1",
+        policyVersion: policy.schemaVersion,
+        shouldExit: matched.length > 0,
+        ...(matched[0] === undefined ? {} : { primary: matched[0] }),
+        matched,
+        phase: snapshot.phase,
+        evaluatedAt: snapshot.evaluatedAt,
+        matches
+    };
+}
+export function toLegacyExitDecision(evaluation, externalDisposition) {
+    const primary = evaluation.primary;
+    if (primary === undefined) {
+        return {
+            shouldExit: false,
+            lifecycleState: "running",
+            status: "running",
+            reason: "No exit condition matched.",
+            exitEvaluation: evaluation
+        };
+    }
+    const reason = evaluation.matches.find((m) => m.kind === primary)?.reason ??
+        `MartinLoop exited because ${primary} fired.`;
+    if (primary === "goal_met") {
+        return completed(reason, primary, evaluation);
+    }
+    if (primary === "external_event" && externalDisposition === "satisfied") {
+        return completed(reason, primary, evaluation);
+    }
+    if (primary === "human_interrupt") {
+        return exited("human_escalation", reason, primary, evaluation);
+    }
+    if (primary === "budget_cap" || primary === "turn_cap") {
+        return exited("budget_exit", reason, primary, evaluation);
+    }
+    if (primary === "no_progress") {
+        return exited("diminishing_returns", reason, primary, evaluation);
+    }
+    if (primary === "error_threshold") {
+        return exited("error_threshold", reason, primary, evaluation);
+    }
+    if (primary === "wall_clock") {
+        return exited("wall_clock", reason, primary, evaluation);
+    }
+    if (primary === "external_event") {
+        return exited("external_event", reason, primary, evaluation);
+    }
+    return exited("stuck_exit", reason, primary, evaluation);
+}
+/**
+ * Hash the meaningful workspace/verification state for no-progress detection.
+ * Excludes timestamps, cost counters, prose summaries — only structural changes count.
+ */
+export function hashProgressState(value) {
+    return createHash("sha256").update(stableJson(value)).digest("hex");
+}
+function stableJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? "null";
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableJson).join(",")}]`;
+    }
+    const obj = value;
+    return `{${Object.keys(obj)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${stableJson(obj[k])}`)
+        .join(",")}}`;
+}
+function completed(reason, primary, evaluation) {
+    return {
+        shouldExit: true,
+        lifecycleState: "completed",
+        status: "completed",
+        reason,
+        reasonCode: primary,
+        exitEvaluation: evaluation
+    };
+}
+function exited(lifecycleState, reason, primary, evaluation) {
+    return {
+        shouldExit: true,
+        lifecycleState,
+        status: "exited",
+        reason,
+        reasonCode: primary,
+        exitEvaluation: evaluation
+    };
+}
+function assertFinitePositive(name, value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`${name} must be a finite number greater than zero`);
+    }
+}
+/** @deprecated Use evaluateExitPolicy instead. Retained for downstream compatibility. */
+export { inferExitCompat as inferExitCompat };
+function inferExitCompat(_unused) {
+    throw new Error("inferExitCompat is a compatibility stub — call evaluateExitPolicy directly");
+}

package/dist/vendor/core/index.d.ts

@@ -1,9 +1,12 @@
-import { type ApprovalPolicy, type CostProvenance, type ExecutionProfile, type FailureClass, type InterventionType, type LoopArtifact, type LoopAttempt, type LoopBudget, type ProviderUsageSettlement, type MutationMode, type LoopRecord, type LoopTask, type ReceiptScope } from "../contracts/index.js";
+import { type ApprovalPolicy, type ContextHandoffReceipt, type CostProvenance, type ExecutionProfile, type FailureClass, type InterventionType, type LoopArtifact, type LoopAttempt, type LoopBudget, type ProviderUsageSettlement, type MutationMode, type LoopRecord, type LoopTask, type ReceiptScope } from "../contracts/index.js";
 import { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, type ExitDecision } from "./policy.js";
 import { evaluateChangeApprovalLeash, evaluateFilesystemLeash, evaluateSecretLeash, redactSecretsFromText, resolveExecutionProfile, evaluateVerificationLeash } from "./leash.js";
 import { buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations } from "./grounding.js";
 import { captureRollbackBoundary, listAttemptChangedFilesSinceBoundary, restoreRollbackBoundary } from "./rollback.js";
 import { type RunStore } from "./persistence/index.js";
+import { type ExitPolicyOverrides } from "./exits.js";
+import { type ExitSignalSource } from "./exit-signal.js";
+import { type VerifierExecutionBinding } from "./verified-handoff.js";
 export type { ApprovalPolicy, BudgetPreflightEstimate, BudgetSettlement, CostProvenance, EvidenceVector, ExecutionProfile, FailureClass, InterventionType, PatchDecision, PatchDecisionArtifact, PatchDecisionReasonCode, PatchScore, MutationMode, RollbackBoundaryArtifact, RollbackBoundaryStrategy, RollbackFileSnapshot, RollbackOutcomeArtifact, RollbackOutcomeStatus, PolicyPhase, CallStage, AgentRole, FirstDelta, RoutingEconomics } from "../contracts/index.js";
 export { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, evaluateVerificationLeash, evaluateFilesystemLeash, evaluateChangeApprovalLeash, evaluateSecretLeash, resolveExecutionProfile, redactSecretsFromText, buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations, captureRollbackBoundary, listAttemptChangedFilesSinceBoundary, restoreRollbackBoundary };
 export type { BudgetPreflightDecision, BudgetPreflightInput, CostGovernorState, EvidenceVectorInput, EvaluatedPatchDecision, ExitDecision, FailureAssessment, PatchDecisionInput, RecoveryDecision, RecoveryRecipe } from "./policy.js";
@@ -14,6 +17,8 @@ export { createLocalIdentityAuthority, hasIdentityScope, issueIdentityToken, ver
 export type { LocalIdentityAuthority } from "./identity.js";
 export { compileExecutionPolicy } from "./policy-compiler.js";
 export { assessTrajectory, decideCircuitBreak } from "./trajectory.js";
+export { calculateAvoidedUsd, calculateLoopAvoidedUsd } from "./savings.js";
+export type { AvoidedUsdInput } from "./savings.js";
 export { classifyRoute, evaluatePreworkBurnPolicy, resolveModelForTier, selectBestEngine } from "./routing.js";
 export type { RouteDecision, RouteClassificationInput, AvailableEngine } from "./routing.js";
 export { validateTestIntegrity, snapshotTestFiles, identifyNewTests, findTestFiles, isTestFile, extractImports, hasTrivialAssertionsOnly, importsPreExistingCode } from "./test-integrity.js";
@@ -24,16 +29,27 @@ export { runContextIntegrityPrecheck } from "./context-integrity.js";
 export type { ContextIntegrityPrecheck, ContextIntegrityVerdict } from "./context-integrity.js";
 export { compilePromptPacket } from "./compiler.js";
 export type { PromptPacket, CompilerAdapterRequest } from "./compiler.js";
+export { buildVerifiedHandoff, resolveVerifiedHandoffOutcome, toTestIntegrityVerdict, verifierActuallyPassed, } from "./verified-handoff.js";
+export type { BoundVerifierEvidence, BuildVerifiedHandoffInput, VerifierExecutionBinding, } from "./verified-handoff.js";
 export { createFileRunStore, makeLedgerEvent, readAllLoopRecords, readLatestLoopRecord, readLatestLoopRecordFromFile, readLoopRecordsFromFile, resolveRunsRoot, resolveReceiptIntegrityPath, verifyReceiptIntegrityFromFiles, writeReceiptIntegrityMaterial } from "./persistence/index.js";
 export type { AttemptArtifacts, LedgerEvent, LedgerEventKind, LoopAttemptRecord, LoopRunRecord, ReceiptIntegrityChainEntry, RunContract, RunStore, StoredReceiptIntegrityMaterial } from "./persistence/index.js";
 export { compileAndPersistContext } from "./persistence/index.js";
 export type { CompileResult } from "./persistence/index.js";
+export { compileContextShadow, estimateContextTokens } from "./context-shadow.js";
+export type { CompileContextShadowInput, CompileContextShadowResult, ContextShadowSegment } from "./context-shadow.js";
+export { compileContext, HEURISTIC_ADAPTER, MAX_RENDER_PASSES } from "./context-compiler.js";
+export type { CompileContextInput, CompileContextOutput, ContextAdapter } from "./context-compiler.js";
+export { verifyContextHandoff, decideContextCircuitBreak } from "./context-handoff.js";
+export type { VerifyContextHandoffInput } from "./context-handoff.js";
+export { evaluateChainGate, renderGatePrComment } from "./context-chain-gate.js";
+export type { ChainGateConfig, ChainGateCost, ChainGateConclusion, ChainGateInput, ChainGateResult, GatePrCommentOptions } from "./context-chain-gate.js";
 export { appendMemory, readMemoryEntries, getPreference, buildMemorySummary, recordPreference, recordConsent } from "./persistence/memory-store.js";
 export type { MemoryEntry, MemoryKind, MemorySummary } from "./persistence/memory-store.js";
 export { appendTraceEntry, readTraceEntries, aggregateTraces, getHistoricalDirectSuccessRate } from "./persistence/trace-store.js";
 export type { TraceEntry, TraceAggregation } from "./persistence/trace-store.js";
 export interface MartinAdapterRequest {
     loopId: string;
+    workspaceId: string;
     attemptId: string;
     context: {
         taskTitle: string;
@@ -41,6 +57,7 @@ export interface MartinAdapterRequest {
         verificationPlan: string[];
         verificationStack?: LoopTask["verificationStack"];
         mutationMode?: MutationMode;
+        definitionOfDonePreSatisfied?: boolean;
         /** Absolute path to the repository root. */
         repoRoot?: string;
         /** Glob patterns for files the agent may modify. Empty = no restriction. */
@@ -58,10 +75,14 @@ export interface MartinAdapterRequest {
         remainingTokens: number;
     };
     previousAttempts: LoopAttempt[];
+    /** Abort signal propagated from the harness — adapters should honour it. */
+    signal?: AbortSignal;
 }
 export interface MartinVerificationStep {
     command: string;
     launched: boolean;
+    completed?: boolean;
+    crashed?: boolean;
     exitCode?: number;
     timedOut: boolean;
     fastFail?: boolean;
@@ -72,6 +93,7 @@ export interface MartinVerificationOutcome {
     summary: string;
     steps?: MartinVerificationStep[];
     warnings?: string[];
+    binding?: VerifierExecutionBinding;
 }
 export interface MartinAdapterResult {
     status: "completed" | "failed";
@@ -91,6 +113,7 @@ export interface MartinAdapterResult {
         summary: string;
         steps?: MartinVerificationStep[];
         warnings?: string[];
+        binding?: VerifierExecutionBinding;
     };
     execution?: {
         changedFiles?: string[];
@@ -175,6 +198,20 @@ export interface RunMartinInput {
     receiptScope?: ReceiptScope;
     /** Optional persistence store. When provided, runMartin writes artifacts on each lifecycle event. */
     store?: RunStore;
+    /** Overrides for the default eight-exit policy derived from budget. */
+    exitPolicy?: ExitPolicyOverrides;
+    /** Source for durable cancellation/external-event signals. */
+    exitSignalSource?: ExitSignalSource;
+    /** Poll interval for the signal monitor in ms (default 250). */
+    exitSignalPollIntervalMs?: number;
+    /** Clock override for testing (default Date.now). */
+    nowMs?: () => number;
+    /** When provided, runMartin verifies the handoff before invoking the adapter. */
+    contextHandoff?: ContextHandoffReceipt;
+    /** true when the producer receipt file hash has been independently confirmed. */
+    producerReceiptVerified?: boolean;
+    /** Map of sha256 → true for every artifact available to the verifier. */
+    availableArtifacts?: ReadonlyMap<string, true>;
 }
 export interface RunMartinResult {
     loop: LoopRecord;
@@ -184,5 +221,9 @@ export declare function distillContext(loop: Pick<LoopRecord, "task" | "budget"
     maxRecentAttempts?: number;
 }): DistilledContext;
 export declare function runMartin(input: RunMartinInput): Promise<RunMartinResult>;
+export { createDefaultExitPolicy, evaluateExitPolicy, hashProgressState, toLegacyExitDecision, validateExitPolicy } from "./exits.js";
+export type { ExitPolicyOverrides, LegacyExitDecision } from "./exits.js";
+export { SignalDiagnosticError, createFileExitSignalSource, exitSignalPath, readAllExitSignals, readExitSignal, startExitSignalMonitor, writeExitSignal } from "./exit-signal.js";
+export type { ExitSignalSource, SignalDiagnostic, SignalReadResult } from "./exit-signal.js";
 export { cacheMessage, fetchSelectedMessage, getCliInstalledVersion, getMcpInstalledVersion, isCooldownExpired, isDismissed, isNewerVersion, loadDeliveryRecord, parseMessageSelectionResponse, recordDismissed, recordShown, resolveDefaultLedgerPath, saveDeliveryRecord, } from "./delivery/index.js";
 export type { MessageClientOptions, MessageSelectRequest, ParseFailure, ParseResult, ValidationError, } from "./delivery/index.js";