@martinloop/mcp 0.3.9 → 0.5.1

package/dist/vendor/adapters/openai-compatible.js

@@ -14,7 +14,7 @@
  * Usage:
  *   # Defaults to OpenAI's hosted endpoint when MARTIN_OPENAI_BASE_URL is unset.
  *   MARTIN_OPENAI_API_KEY=sk-...
- *   MARTIN_OPENAI_MODEL=gpt-4.1-mini
+ *   MARTIN_OPENAI_MODEL=<provider-model-id>
  *   martin-loop run "fix the bug" --engine openai
  *
  *   # Or route to a third-party / self-hosted OpenAI-compatible endpoint:
@@ -69,6 +69,37 @@ function estimateCost(model, inputChars, outputChars) {
     const actualUsd = (tokensIn / 1000) * pricing.inputPer1K + (tokensOut / 1000) * pricing.outputPer1K;
     return { tokensIn, tokensOut, actualUsd };
 }
+function normalizeOpenAiCompatibleUsage(input) {
+    const hasKnownPricing = KNOWN_MODEL_PRICING[input.model] !== undefined;
+    const pricing = KNOWN_MODEL_PRICING[input.model] ?? {
+        inputPer1K: FALLBACK_INPUT_PER_1K,
+        outputPer1K: FALLBACK_OUTPUT_PER_1K
+    };
+    const actualUsd = (input.tokensIn / 1000) * pricing.inputPer1K +
+        (input.tokensOut / 1000) * pricing.outputPer1K;
+    const provenance = input.usageWasFullyProviderReported && hasKnownPricing ? "calculated" : "estimated";
+    return normalizeUsage({
+        actualUsd,
+        ...(provenance === "estimated" ? { estimatedUsd: actualUsd } : {}),
+        tokensIn: input.tokensIn,
+        tokensOut: input.tokensOut,
+        provenance,
+        providerSettlement: {
+            providerId: "openai-compatible",
+            model: input.model,
+            transport: "http",
+            source: input.usageWasFullyProviderReported ? "openai_compatible_json" : "estimated_fallback",
+            inputTokens: input.tokensIn,
+            outputTokens: input.tokensOut,
+            billingMode: input.billingMode,
+            modelSource: input.modelSource,
+            pricingSource: hasKnownPricing ? "static_catalog" : "blended_fallback",
+            pricingVersion: "embedded-v1",
+            rawUsageAvailable: input.usageWasFullyProviderReported,
+            settledAt: new Date().toISOString()
+        }
+    });
+}
 // ---------------------------------------------------------------------------
 // Prompt builder
 // ---------------------------------------------------------------------------
@@ -80,12 +111,11 @@ Follow these rules exactly:
 - Be precise, minimal, and test-backed in all changes.
 - State what you changed and why at the end of your response.`;
 export const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com";
-export const DEFAULT_OPENAI_MODEL = "gpt-4.1-mini";
 export function resolveOpenAiCompatibleRuntimeConfig(env = process.env) {
     const apiKey = env["MARTIN_OPENAI_API_KEY"] ?? "";
     return {
         baseUrl: env["MARTIN_OPENAI_BASE_URL"] ?? DEFAULT_OPENAI_BASE_URL,
-        model: env["MARTIN_OPENAI_MODEL"] ?? DEFAULT_OPENAI_MODEL,
+        ...(env["MARTIN_OPENAI_MODEL"] ? { model: env["MARTIN_OPENAI_MODEL"] } : {}),
         apiKey,
         apiKeyConfigured: apiKey.length > 0,
         authPosture: apiKey.length > 0 ? "api_key" : "anonymous_or_local"
@@ -126,7 +156,16 @@ export function createOpenAiCompatibleAdapter(options) {
     const runtimeConfig = resolveOpenAiCompatibleRuntimeConfig();
     const baseUrl = (options.baseUrl ?? runtimeConfig.baseUrl).replace(/\/$/, "");
     const model = options.model ?? runtimeConfig.model;
+    if (!model) {
+        throw new Error("MODEL_CONFIGURATION_REQUIRED: set --model or MARTIN_OPENAI_MODEL for direct OpenAI-compatible execution.");
+    }
     const apiKey = options.apiKey ?? runtimeConfig.apiKey;
+    const modelSource = options.model ? "explicit_override" : "provider_configured";
+    const billingMode = /^(?:https?:\/\/)?(?:localhost|127\.0\.0\.1|\[::1\])/iu.test(baseUrl)
+        ? "local_unmetered"
+        : apiKey
+            ? "metered_api"
+            : "unknown";
     return {
         adapterId: `openai-compatible:${model}`,
         kind: "direct-provider",
@@ -172,10 +211,12 @@ export function createOpenAiCompatibleAdapter(options) {
             // indicate a permanent configuration problem.
             const MAX_RETRIES = 3;
             const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+            const NON_RETRYABLE_STATUS = new Set([400, 401, 403]);
             const endpoint = `${baseUrl}/v1/chat/completions`;
             let responseText = "";
             let tokensIn = estimated.tokensIn;
             let tokensOut = 0;
+            let usageWasFullyProviderReported = false;
             const headers = { "Content-Type": "application/json" };
             if (apiKey)
                 headers["Authorization"] = `Bearer ${apiKey}`;
@@ -207,6 +248,17 @@ export function createOpenAiCompatibleAdapter(options) {
                     const body = (await res.json());
                     if (!res.ok || body.error) {
                         const errMsg = body.error?.message ?? `HTTP ${res.status}`;
+                        // Fail immediately on non-retryable errors (auth, bad request)
+                        if (NON_RETRYABLE_STATUS.has(res.status)) {
+                            return {
+                                status: "failed",
+                                summary: `${model} API error: ${errMsg}`,
+                                usage: normalizeUsage({ actualUsd: 0, tokensIn: 0, tokensOut: 0, provenance: "unavailable" }),
+                                verification: { passed: false, summary: "API call failed before verifier." },
+                                failure: { message: errMsg, classHint: "infrastructure_error" }
+                            };
+                        }
+                        // Retry on transient errors
                         if (RETRYABLE_STATUS.has(res.status) && attempt < MAX_RETRIES - 1) {
                             lastError = errMsg;
                             // Exponential backoff: 1s, 2s, 4s
@@ -223,8 +275,13 @@ export function createOpenAiCompatibleAdapter(options) {
                     }
                     responseText = body.choices?.[0]?.message?.content ?? "";
                     if (body.usage) {
-                        tokensIn = body.usage.prompt_tokens ?? tokensIn;
-                        tokensOut = body.usage.completion_tokens ?? 0;
+                        const providerPromptTokens = body.usage.prompt_tokens;
+                        const providerCompletionTokens = body.usage.completion_tokens;
+                        usageWasFullyProviderReported =
+                            typeof providerPromptTokens === "number" &&
+                                typeof providerCompletionTokens === "number";
+                        tokensIn = providerPromptTokens ?? tokensIn;
+                        tokensOut = providerCompletionTokens ?? Math.ceil(responseText.length / CHARS_PER_TOKEN);
                     }
                     else {
                         tokensOut = Math.ceil(responseText.length / CHARS_PER_TOKEN);
@@ -267,33 +324,41 @@ export function createOpenAiCompatibleAdapter(options) {
                 return {
                     status: "failed",
                     summary: `${model} returned an empty response.`,
-                    usage: normalizeUsage({ actualUsd: 0, tokensIn, tokensOut: 0, provenance: "actual" }),
+                    usage: normalizeOpenAiCompatibleUsage({
+                        model,
+                        tokensIn,
+                        tokensOut: 0,
+                        usageWasFullyProviderReported,
+                        modelSource,
+                        billingMode
+                    }),
                     verification: { passed: false, summary: "Empty response — nothing to verify." },
                     failure: { message: "empty_response" }
                 };
             }
             // Run verification
-            const verification = await runVerification(request.context.verificationPlan, workingDirectory, verifyTimeoutMs, request.context.verificationStack);
+            const verification = await runVerification(request.context.verificationPlan, workingDirectory, verifyTimeoutMs, request.context.verificationStack, undefined, {
+                runId: request.loopId,
+                workspaceId: request.workspaceId,
+                cwd: workingDirectory,
+            });
             const execution = {
                 changedFiles: hasVerificationSteps
                     ? (await readGitChangedFiles(workingDirectory, 5_000)).filter((file) => !baselineChangedFiles.has(file))
                     : []
             };
-            const pricing = KNOWN_MODEL_PRICING[model] ?? {
-                inputPer1K: FALLBACK_INPUT_PER_1K,
-                outputPer1K: FALLBACK_OUTPUT_PER_1K
-            };
-            const actualUsd = (tokensIn / 1000) * pricing.inputPer1K + (tokensOut / 1000) * pricing.outputPer1K;
             return {
                 status: verification.passed ? "completed" : "failed",
                 summary: verification.passed
                     ? `${model} completed the task. Verifier passed.`
                     : `${model} completed but verifier failed: ${verification.summary}`,
-                usage: normalizeUsage({
-                    actualUsd,
+                usage: normalizeOpenAiCompatibleUsage({
+                    model,
                     tokensIn,
                     tokensOut,
-                    provenance: "actual"
+                    usageWasFullyProviderReported,
+                    modelSource,
+                    billingMode
                 }),
                 verification,
                 execution,

package/dist/vendor/adapters/verifier-only.js

@@ -13,18 +13,23 @@ export function createVerifierOnlyAdapter(options = {}) {
             transport: "cli",
             capabilities: createAdapterCapabilities({
                 usageSettlement: true,
-                diffArtifacts: true
+                diffArtifacts: true,
+                workspaceMutations: false
             })
         },
         async execute(request) {
             const shouldTrackVerifierWrites = request.context.verificationPlan.length > 0 ||
                 (request.context.verificationStack?.length ?? 0) > 0;
             const baselineChangedFiles = shouldTrackVerifierWrites
-                ? new Set(await readGitChangedFiles(workingDirectory, 5_000, options.spawnImpl))
+                ? new Set(await readGitChangedFiles(workingDirectory, 5_000))
                 : new Set();
-            const verification = await runVerification(request.context.verificationPlan, workingDirectory, verifyTimeoutMs, request.context.verificationStack, options.spawnImpl);
+            const verification = await runVerification(request.context.verificationPlan, workingDirectory, verifyTimeoutMs, request.context.verificationStack, options.spawnImpl, {
+                runId: request.loopId,
+                workspaceId: request.workspaceId,
+                cwd: workingDirectory
+            });
             const changedFiles = shouldTrackVerifierWrites
-                ? (await readGitChangedFiles(workingDirectory, 5_000, options.spawnImpl)).filter((file) => !baselineChangedFiles.has(file))
+                ? (await readGitChangedFiles(workingDirectory, 5_000)).filter((file) => !baselineChangedFiles.has(file))
                 : [];
             const execution = { changedFiles };
             if (verification.passed) {

package/dist/vendor/contracts/adapter-capabilities.d.ts

@@ -1,5 +1,5 @@
 export type DiffVisibilityLevel = "none" | "git" | "adapter_reported";
-export type VerifierCompatibility = "full" | "verify_only" | "unsupported";
+export type VerifierCompatibility = "full" | "proof" | "unsupported";
 export type SandboxExpectation = "host_process" | "workspace_write" | "provider_managed" | "not_applicable";
 export type LaunchReadiness = "path_lookup" | "configured_endpoint" | "built_in";
 export type AdapterUsageSettlement = "actual" | "estimated" | "unavailable";

package/dist/vendor/contracts/context-handoff.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Context Handoff — A-CTX-2 contracts.
+ *
+ * Chain verification circuit breaker for upstream-to-downstream context handoff.
+ *
+ * Rule: a downstream agent MUST NOT execute before verifyContextHandoff returns ok=true.
+ * Healthy handoffs are silent. Broken handoffs stop execution and return one reason code
+ * plus one recovery instruction. Never silently discard excluded or unverifiable context.
+ */
+/**
+ * Overall integrity state of the upstream chain.
+ * "verified"          — all upstream receipts and artifacts check out
+ * "evidence_boundary" — upstream integrity could not be established (no receipt)
+ * "tamper_detected"   — receipt hash or artifact hash does not match
+ * "incomplete"        — required fields or artifacts are absent
+ * "unsupported_schema"— handoff schemaVersion is not recognised
+ */
+export type ChainIntegrityState = "verified" | "evidence_boundary" | "tamper_detected" | "incomplete" | "unsupported_schema";
+export type HandoffClaimState = "verified" | "unverified" | "rejected" | "unknown";
+/** A single verifiable statement carried across the handoff boundary. */
+export interface ContextHandoffClaim {
+    claimId: string;
+    statement: string;
+    evidenceRefs: string[];
+    verificationState: HandoffClaimState;
+}
+/** A content-addressed artifact that must be present and hash-stable across the boundary. */
+export interface ContextHandoffArtifact {
+    path?: string;
+    sha256: string;
+    required: boolean;
+    label?: string;
+}
+export declare const HANDOFF_SCHEMA_VERSION: "martin.handoff.v1";
+/**
+ * Immutable record produced by the upstream agent and verified before the
+ * downstream agent executes.
+ *
+ * upstreamIntegrity propagates from the parent handoff — it can never be
+ * upgraded by downstream success. A "tamper_detected" upstream remains
+ * "tamper_detected" regardless of what the current agent does.
+ */
+export interface ContextHandoffReceipt {
+    schemaVersion: typeof HANDOFF_SCHEMA_VERSION;
+    handoffId: string;
+    chainId: string;
+    missionId?: string;
+    producerRunId: string;
+    /** SHA-256 of the upstream run's canonical receipt file. */
+    producerReceiptHash: string;
+    /** Parent handoff IDs for multi-hop chain lineage. */
+    parentHandoffIds?: string[];
+    claims: ContextHandoffClaim[];
+    artifacts: ContextHandoffArtifact[];
+    /** Free-text assumptions that have not yet been verified at handoff time. */
+    unresolvedAssumptions: string[];
+    upstreamIntegrity: "verified" | "evidence_boundary" | "tamper_detected" | "incomplete";
+    createdAt: string;
+}
+/**
+ * Safe ledger record for a context object that was denied before reaching
+ * executable context.
+ *
+ * MUST NOT contain the secret value or raw denied content — only safe
+ * identity, hashes, and reason codes.
+ */
+export interface ContextExclusionDecision {
+    decision: "excluded";
+    objectId: string;
+    reasonCode: "secret_detected" | "policy_denied" | "authority_boundary" | "integrity_unverified";
+    reason: string;
+    /** SHA-256 of the denied content — never the content itself. */
+    sourceHash?: string;
+    excludedAt: string;
+}
+export interface ContextHandoffVerification {
+    ok: boolean;
+    integrity: ChainIntegrityState;
+    reasons: Array<{
+        code: string;
+        message: string;
+        claimId?: string;
+        artifactSha256?: string;
+    }>;
+}
+/**
+ * Decision produced by decideContextCircuitBreak.
+ *
+ * Healthy:  { shouldStop: false, silent: true }
+ * Broken:   { shouldStop: true, silent: false, reasonCode, message, nextAction }
+ */
+export interface ContextCircuitBreakResult {
+    shouldStop: boolean;
+    /** true = healthy, no human-visible output; false = must surface to caller */
+    silent: boolean;
+    verification: ContextHandoffVerification;
+    reasonCode?: string;
+    message?: string;
+    nextAction?: string;
+}

package/dist/vendor/contracts/context-handoff.js

@@ -0,0 +1,11 @@
+/**
+ * Context Handoff — A-CTX-2 contracts.
+ *
+ * Chain verification circuit breaker for upstream-to-downstream context handoff.
+ *
+ * Rule: a downstream agent MUST NOT execute before verifyContextHandoff returns ok=true.
+ * Healthy handoffs are silent. Broken handoffs stop execution and return one reason code
+ * plus one recovery instruction. Never silently discard excluded or unverifiable context.
+ */
+// ─── Receipt ──────────────────────────────────────────────────────────────────
+export const HANDOFF_SCHEMA_VERSION = "martin.handoff.v1";

package/dist/vendor/contracts/context-manifest.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Context Runtime — A-CTX-1 contracts.
+ *
+ * Defines the governed context layer: objects, budgets, manifests, ledger
+ * entries, fault protocol, and continuation checkpoints.
+ *
+ * Non-negotiable invariants (enforced in implementation, not type system):
+ *   - No `confidence` float anywhere — use UsageEvidence enums only
+ *   - No `outcome_delta` field anywhere — permanently banned
+ *   - `nowMs` is always a captured input; never Date.now() inside a compiler
+ *   - Secret scan hit → deny persistence entirely; reason-coded ledger entry only
+ *   - Fault budget accumulates by taskId, NOT by runId
+ */
+/**
+ * Evidence quality for a metric or measurement.
+ *
+ * "observed"  = distinctive substring from the object appears verbatim in model output
+ * "inferred"  = weak kind correlation, narrow and documented per kind
+ * "unknown"   = default; metrics MUST be withheld, never reported as zero
+ */
+export type UsageEvidence = "observed" | "inferred" | "unknown";
+export type ContextKind = "mission" | "policy" | "security" | "task" | "continuation" | "working_diff" | "diagnostic" | "source" | "test" | "decision" | "todo" | "receipt_summary" | "tool_result";
+export type ContextPriority = "required" | "high" | "normal" | "low";
+export type ContextTrust = "authoritative" | "workspace" | "external" | "untrusted";
+export type ContextSensitivity = "public" | "workspace" | "restricted" | "secret";
+/** A typed, hashed, provenance-tracked object eligible for working-set inclusion. */
+export interface ContextObject {
+    /** Stable identifier across revisions. */
+    id: string;
+    kind: ContextKind;
+    priority: ContextPriority;
+    trust: ContextTrust;
+    sensitivity: ContextSensitivity;
+    /** File path, receipt hash, or MCP URI — where the object originates. */
+    sourceRef: string;
+    /** SHA-256 of raw content. */
+    contentHash: string;
+    /** Git SHA or equivalent revision of the source file, if known. */
+    sourceRevisionHash?: string;
+    /** Pre-render token estimate used during selection. */
+    estimatedTokens: number;
+    /** Set iff the object was manually pinned; counts against pinnedTokensMax. */
+    pinnedBy?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Token budget for one context compilation pass.
+ *
+ * pinnedTokensMax REQUIRED: caps manual-pin tokens to prevent deterministic
+ * selector starvation. Any pin that would exceed this cap must be rejected.
+ */
+export interface ContextBudget {
+    modelWindowTokens: number;
+    systemReserveTokens: number;
+    outputReserveTokens: number;
+    toolReserveTokens: number;
+    overflowReserveTokens: number;
+    maxWorkingSetTokens: number;
+    /** Hard cap on manually-pinned token allocation. */
+    pinnedTokensMax: number;
+}
+/**
+ * The compiler's per-object inclusion/exclusion record.
+ *
+ * "included_truncated" is DISTINCT from "included" — truncation must be
+ * explicit in every receipt. Never use "included" for a truncated object.
+ */
+export interface ContextCandidateDecision {
+    objectId: string;
+    decision: "included" | "included_truncated" | "excluded" | "deferred" | "fault_loaded";
+    /**
+     * Only present when decision === "included_truncated".
+     * Records the pre-truncation token count for receipts.
+     */
+    truncatedFromTokens?: number;
+    /** Machine-readable reason code for this decision. */
+    reason: string;
+    /** Actual post-render token count after adapter recount. Omitted pre-render. */
+    renderedTokens?: number;
+}
+export declare const CONTEXT_MANIFEST_VERSION: "context-manifest/1";
+/**
+ * Immutable record of one context compilation pass.
+ *
+ * Determinism invariant:
+ *   same inputs + policyHash + adapterVersion + nowMs → same manifestHash
+ *
+ * nowMs MUST be an explicit captured input — never Date.now() inside the
+ * compiler or rankContextObject.
+ */
+export interface ContextManifest {
+    schemaVersion: typeof CONTEXT_MANIFEST_VERSION;
+    /** SHA-256 of (decisions + budget + policyHash + adapterVersion + nowMs). */
+    manifestHash: string;
+    taskId: string;
+    runId: string;
+    /** Explicit input — never Date.now() inside the compiler. */
+    nowMs: number;
+    adapterVersion: string;
+    policyHash: string;
+    budget: ContextBudget;
+    decisions: ContextCandidateDecision[];
+    totalRenderedTokens: number;
+    /** Render pass count; must be ≤ MAX_RENDER_PASSES (5). */
+    renderPasses: number;
+    compilationDurationMs: number;
+}
+export declare const CONTEXT_LEDGER_VERSION: "context-ledger/1";
+/**
+ * Fourth ledger entry type — on the SAME receipt chain as cost and verification.
+ *
+ * FORBIDDEN: confidence field, outcome_delta field — both permanently banned.
+ * overflowCount and faultBudgetUsed accumulate by taskId, NOT by runId.
+ */
+export interface ContextLedgerEntry {
+    schemaVersion: typeof CONTEXT_LEDGER_VERSION;
+    entryType: "context";
+    taskId: string;
+    runId: string;
+    manifestHash: string;
+    totalIncluded: number;
+    totalExcluded: number;
+    totalFaultLoaded: number;
+    /** Cumulative overflow count — resets per task, never per run. */
+    overflowCount: number;
+    /** Cumulative fault budget consumed — resets per task, never per run. */
+    faultBudgetUsed: number;
+    adapterVersion: string;
+}
+/** Request to demand-load a missing context object on fault. */
+export interface ContextFaultRequest {
+    objectId: string;
+    taskId: string;
+    runId: string;
+    reason: string;
+}
+/** Result of a context fault resolution attempt. */
+export interface ContextFaultResult {
+    objectId: string;
+    status: "loaded" | "unavailable" | "secret_blocked" | "budget_exceeded";
+    /** Post-render token count when status === "loaded". */
+    renderedTokens?: number;
+    ledgerEventEmitted: boolean;
+}
+/** Minimal task item tracked within a ContinuationCheckpoint. */
+export interface TaskItem {
+    id: string;
+    description: string;
+    status: "pending" | "in_progress" | "completed" | "failed";
+    createdAtMs: number;
+    completedAtMs?: number;
+}
+/**
+ * Durable task state preserved outside the provider transcript.
+ *
+ * Write discipline (all enforced in CheckpointStore):
+ *   - All writes MUST go through CheckpointStore.withTaskLock (CAS-locked).
+ *   - Reject if store.read(taskId).sequenceNumber !== checkpoint.sequenceNumber - 1.
+ *   - All array fields MUST be bounded before persistence.
+ *   - Old completed entries MUST be compacted into completedSummaryHash.
+ *
+ * Testing requirement: two real concurrent Node processes, not jest mocks.
+ */
+export interface ContinuationCheckpoint {
+    schemaVersion: "checkpoint/1";
+    taskId: string;
+    /** CAS lock key: reject write if stored sequenceNumber !== this - 1. */
+    sequenceNumber: number;
+    /** SHA-256 of the previous checkpoint — integrity chain. */
+    parentHash: string;
+    /** Old completed[] compacted into a hash-referenced summary to bound size. */
+    completedSummaryHash?: string;
+    pending: TaskItem[];
+    inProgress: TaskItem[];
+    decisions: ContextCandidateDecision[];
+    createdAtMs: number;
+}
+/**
+ * Governs what may enter the working set, how much, and why.
+ * policyHash must be included in every manifestHash computation.
+ */
+export interface ContextPolicy {
+    policyHash: string;
+    /** Sensitivity levels that are unconditionally excluded. */
+    deniedSensitivities: ContextSensitivity[];
+    /** Trust levels that are unconditionally excluded. */
+    deniedTrustLevels: ContextTrust[];
+    /** Behaviour when required objects alone exceed budget. */
+    requiredOverBudgetAction: "explicit_escalation" | "fail_closed";
+    /** Maximum allowed compiler wall-clock duration in ms. */
+    maxCompilerDurationMs: number;
+    /** Maximum overhead ratio: compilationDurationMs / totalRenderedTokens. */
+    maxOverheadRatio: number;
+}

package/dist/vendor/contracts/context-manifest.js

@@ -0,0 +1,17 @@
+/**
+ * Context Runtime — A-CTX-1 contracts.
+ *
+ * Defines the governed context layer: objects, budgets, manifests, ledger
+ * entries, fault protocol, and continuation checkpoints.
+ *
+ * Non-negotiable invariants (enforced in implementation, not type system):
+ *   - No `confidence` float anywhere — use UsageEvidence enums only
+ *   - No `outcome_delta` field anywhere — permanently banned
+ *   - `nowMs` is always a captured input; never Date.now() inside a compiler
+ *   - Secret scan hit → deny persistence entirely; reason-coded ledger entry only
+ *   - Fault budget accumulates by taskId, NOT by runId
+ */
+// ─── ContextManifest ─────────────────────────────────────────────────────────
+export const CONTEXT_MANIFEST_VERSION = "context-manifest/1";
+// ─── ContextLedgerEntry ───────────────────────────────────────────────────────
+export const CONTEXT_LEDGER_VERSION = "context-ledger/1";

package/dist/vendor/contracts/context-shadow.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Context Shadow — A-CTX-0 schema contracts.
+ *
+ * Shadow mode observes the existing prompt without altering it.
+ * No source text is retained in manifests or receipts — only hashes and counts.
+ */
+export declare const CONTEXT_SHADOW_MANIFEST_VERSION: "context-shadow-manifest/1";
+export declare const CONTEXT_C5_VERSION: "context-c5/1";
+export type ContextEvidence = "observed" | "configured" | "inferred" | "unknown";
+export type ContextShadowSegmentKind = "system" | "mission" | "task" | "workspace" | "diagnostic" | "tool" | "other";
+export interface ContextShadowSegmentInput {
+    segmentId: string;
+    kind: ContextShadowSegmentKind;
+    required: boolean;
+    text: string;
+}
+export interface ContextShadowDecisionV1 {
+    segmentId: string;
+    kind: string;
+    /** SHA-256 of segment.text — never the source text itself. */
+    contentHash: string;
+    estimatedTokens: number;
+    /** Always true in shadow mode — actual prompt is never altered. */
+    actuallyIncluded: true;
+    /** What the shadow compiler would have decided if it controlled selection. */
+    proposedDecision: "included" | "excluded";
+    reason: "required" | "within_shadow_budget" | "shadow_budget_exhausted" | "required_over_budget";
+}
+export interface ContextShadowManifestV1 {
+    schemaVersion: typeof CONTEXT_SHADOW_MANIFEST_VERSION;
+    manifestId: string;
+    /** SHA-256 of the canonical JSON of the manifest (excluding manifestId and manifestHash). */
+    manifestHash: string;
+    /** SHA-256 of the canonical compiler input, for cross-run determinism checks. */
+    compilerInputHash: string;
+    runId: string;
+    taskId?: string;
+    adapter: string;
+    model?: string;
+    capturedAt: string;
+    mode: "shadow";
+    modelWindowTokens: number | null;
+    modelWindowEvidence: ContextEvidence;
+    shadowBudgetTokens: number;
+    /** SHA-256 of framed source segments — confirms prompt identity without storing content. */
+    actualPromptHash: string;
+    /** Estimated token count of all segments (actual prompt). */
+    actualEstimatedTokens: number;
+    /** Estimated token count of shadow-selected segments only. */
+    proposedEstimatedTokens: number;
+    /** True if required segments alone exceed shadowBudgetTokens. */
+    requiredOverBudget: boolean;
+    decisions: ContextShadowDecisionV1[];
+}
+export interface ContextC5EnvelopeV1 {
+    schemaVersion: typeof CONTEXT_C5_VERSION;
+    resource: "context";
+    event: "shadow_compiled";
+    runId: string;
+    taskId?: string;
+    manifestId: string;
+    manifestHash: string;
+    adapter: string;
+    model?: string;
+    mode: "shadow";
+    actualEstimatedTokens: number;
+    proposedEstimatedTokens: number;
+    candidateCount: number;
+    includedCount: number;
+    excludedCount: number;
+    requiredOverBudget: boolean;
+    modelWindowTokens: number | null;
+    modelWindowEvidence: ContextEvidence;
+    createdAt: string;
+}

package/dist/vendor/contracts/context-shadow.js

@@ -0,0 +1,8 @@
+/**
+ * Context Shadow — A-CTX-0 schema contracts.
+ *
+ * Shadow mode observes the existing prompt without altering it.
+ * No source text is retained in manifests or receipts — only hashes and counts.
+ */
+export const CONTEXT_SHADOW_MANIFEST_VERSION = "context-shadow-manifest/1";
+export const CONTEXT_C5_VERSION = "context-c5/1";

package/dist/vendor/contracts/delivery.d.ts

@@ -0,0 +1,47 @@
+/**
+ * R4 Delivery — M1 Contract
+ *
+ * Shared with Lane B (Control Plane). Do not modify unilaterally.
+ * The server selects one message; the client never downloads the catalog.
+ */
+export declare const DELIVERY_MESSAGE_SCHEMA_VERSION: "delivery-message/1";
+export declare const DELIVERY_RECORD_SCHEMA_VERSION: "delivery-record/1";
+export declare const MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION: "martin-message-selection/1";
+export declare const ALLOWED_ACTION_TYPES: readonly ["upgrade_cli", "upgrade_mcp", "submit_feedback", "open_release_notes", "dismiss", "view_spend_report", "view_run_explain"];
+export type ActionType = (typeof ALLOWED_ACTION_TYPES)[number];
+export type MessageKind = "update" | "feedback_request" | "milestone";
+export interface DeliveryMessage {
+    schemaVersion: typeof DELIVERY_MESSAGE_SCHEMA_VERSION;
+    id: string;
+    revision: number;
+    kind: MessageKind;
+    title: string;
+    body: string;
+    action: {
+        type: ActionType;
+        url?: string;
+        targetVersion?: string;
+    };
+    expiresAt: string;
+    cooldownHours: number;
+}
+export interface MessageSelectionResponse {
+    schemaVersion: typeof MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION;
+    message?: DeliveryMessage;
+}
+/** Local cooldown/dismissal state — persisted in .martin/delivery-record.json */
+export interface DeliveryRecord {
+    schemaVersion: typeof DELIVERY_RECORD_SCHEMA_VERSION;
+    lastMessageId?: string;
+    lastShownAtEpochMs?: number;
+    dismissedIds: string[];
+    cooldownUntilEpochMs?: number;
+    cachedMessage?: DeliveryMessage;
+    cachedAtEpochMs?: number;
+}
+/** Structured update field for --json and MCP responses */
+export interface UpdateAvailableField {
+    targetVersion: string;
+    kind: "cli" | "mcp";
+    message?: string;
+}