@martinloop/mcp 0.3.7 → 0.3.8

package/dist/vendor/adapters/claude-cli.js

@@ -17,22 +17,18 @@ import { createAdapterCapabilities, normalizeStructuredErrors, normalizeUsage }
 // ---------------------------------------------------------------------------
 // Cost estimation
 //
-// Token costs are estimated using a blended average across top models:
-// Anthropic Sonnet, OpenAI GPT-4o Mini, Gemini Flash, Meta Llama 3.
-// Override at runtime with --input-cost-per-1k / --output-cost-per-1k CLI
-// flags or martin.config.yaml pricing section.
+// Streaming enforcement needs a model-specific estimate until Claude emits
+// authoritative total_cost_usd on the final result event. Unknown Claude
+// models are never assigned another model's price.
 // ---------------------------------------------------------------------------
 const BLENDED_INPUT_COST_PER_1K = 0.003; // $/1K input tokens
 const BLENDED_OUTPUT_COST_PER_1K = 0.012; // $/1K output tokens
-// Per-model overrides for common Claude models (fallback: blended average)
+// USD per 1K tokens. Claude cache creation uses the documented default
+// five-minute rate; cache reads are priced independently from fresh input.
 const MODEL_PRICING = {
-    "claude-opus-4-6": { inputPer1K: 0.015, outputPer1K: 0.075 },
-    "claude-sonnet-4-6": { inputPer1K: 0.003, outputPer1K: 0.015 },
-    "claude-haiku-4-5": { inputPer1K: 0.00025, outputPer1K: 0.00125 },
-    // Keep legacy names working
-    "claude-opus": { inputPer1K: 0.015, outputPer1K: 0.075 },
-    "claude-sonnet": { inputPer1K: 0.003, outputPer1K: 0.015 },
-    "claude-haiku": { inputPer1K: 0.00025, outputPer1K: 0.00125 },
+    "claude-opus-4-6": { inputPer1K: 0.005, cachedInputPer1K: 0.0005, cacheCreationInputPer1K: 0.00625, outputPer1K: 0.025 },
+    "claude-sonnet-4-6": { inputPer1K: 0.003, cachedInputPer1K: 0.0003, cacheCreationInputPer1K: 0.00375, outputPer1K: 0.015 },
+    "claude-haiku-4-5": { inputPer1K: 0.001, cachedInputPer1K: 0.0001, cacheCreationInputPer1K: 0.00125, outputPer1K: 0.005 },
     // OpenAI coding models
     "codex": { inputPer1K: 0.00125, cachedInputPer1K: 0.000125, outputPer1K: 0.01 },
     "gpt-5-codex": { inputPer1K: 0.00125, cachedInputPer1K: 0.000125, outputPer1K: 0.01 },
@@ -41,6 +37,37 @@ const MODEL_PRICING = {
     "gpt-5.2-codex": { inputPer1K: 0.00175, cachedInputPer1K: 0.000175, outputPer1K: 0.014 },
     "codex-mini-latest": { inputPer1K: 0.0015, cachedInputPer1K: 0.000375, outputPer1K: 0.006 }
 };
+const CLAUDE_MODEL_ALIASES = [
+    { canonicalModelId: "claude-opus-4-6", aliases: [/^claude-opus-4-6-\d{8}$/u, /^claude-opus$/u] },
+    { canonicalModelId: "claude-sonnet-4-6", aliases: [/^claude-sonnet-4-6-\d{8}$/u, /^claude-sonnet$/u] },
+    { canonicalModelId: "claude-haiku-4-5", aliases: [/^claude-haiku-4-5-\d{8}$/u, /^claude-haiku$/u] }
+];
+function resolveModelPricing(modelLabel) {
+    const normalized = modelLabel?.trim().toLowerCase();
+    if (!normalized) {
+        return { status: "unknown" };
+    }
+    const exact = MODEL_PRICING[normalized];
+    if (exact) {
+        return { status: "exact", canonicalModelId: normalized, pricing: exact };
+    }
+    for (const family of CLAUDE_MODEL_ALIASES) {
+        if (family.aliases.some((alias) => alias.test(normalized))) {
+            return {
+                status: "alias",
+                canonicalModelId: family.canonicalModelId,
+                pricing: MODEL_PRICING[family.canonicalModelId]
+            };
+        }
+    }
+    return { status: "unknown" };
+}
+function calculateUsageCost(usage, pricing) {
+    return ((usage.inputTokens / 1000) * pricing.inputPer1K +
+        (usage.cachedInputTokens / 1000) * (pricing.cachedInputPer1K ?? pricing.inputPer1K) +
+        (usage.cacheCreationInputTokens / 1000) * (pricing.cacheCreationInputPer1K ?? pricing.inputPer1K) +
+        (usage.outputTokens / 1000) * pricing.outputPer1K);
+}
 function extractUsage(parsed, modelLabel) {
     if (!parsed?.usage) {
         return normalizeUsage({
@@ -50,34 +77,38 @@ function extractUsage(parsed, modelLabel) {
             provenance: "unavailable"
         });
     }
-    const promptTokens = (parsed.usage.inputTokens ?? parsed.usage.input_tokens ?? 0) +
-        (parsed.usage.cacheCreationInputTokens ?? parsed.usage.cache_creation_input_tokens ?? 0);
+    const promptTokens = parsed.usage.inputTokens ?? parsed.usage.input_tokens ?? 0;
+    const cacheCreationInputTokens = parsed.usage.cacheCreationInputTokens ?? parsed.usage.cache_creation_input_tokens ?? 0;
     const cachedInputTokens = parsed.usage.cacheReadInputTokens ?? parsed.usage.cache_read_input_tokens ?? 0;
-    const tokensIn = promptTokens + cachedInputTokens;
+    const tokensIn = promptTokens + cachedInputTokens + cacheCreationInputTokens;
     const tokensOut = parsed.usage.outputTokens ?? parsed.usage.output_tokens ?? 0;
-    const pricing = (modelLabel ? MODEL_PRICING[modelLabel] : undefined) ??
-        { inputPer1K: BLENDED_INPUT_COST_PER_1K, outputPer1K: BLENDED_OUTPUT_COST_PER_1K };
+    const pricingResolution = resolveModelPricing(modelLabel);
     // Prefer Claude's own authoritative total_cost_usd (present on the final
     // `result` event in json/stream-json output) over our pricing-table estimate,
     // which can drift from real billed cost (cache discounts, surcharges, etc).
     const hasAuthoritativeCost = typeof parsed.total_cost_usd === "number";
     const actualUsd = hasAuthoritativeCost
         ? parsed.total_cost_usd
-        : (promptTokens / 1000) * pricing.inputPer1K +
-            (cachedInputTokens / 1000) * (pricing.cachedInputPer1K ?? pricing.inputPer1K) +
-            (tokensOut / 1000) * pricing.outputPer1K;
+        : pricingResolution.pricing
+            ? calculateUsageCost({
+                inputTokens: promptTokens,
+                cachedInputTokens,
+                cacheCreationInputTokens,
+                outputTokens: tokensOut
+            }, pricingResolution.pricing)
+            : 0;
     return normalizeUsage({
         actualUsd: Number(actualUsd.toFixed(6)),
         tokensIn,
         tokensOut,
         cachedInputTokens,
-        provenance: hasAuthoritativeCost ? "actual" : "estimated",
+        provenance: hasAuthoritativeCost ? "actual" : pricingResolution.pricing ? "estimated" : "unavailable",
         providerSettlement: {
             providerId: "claude",
             model: modelLabel ?? "claude",
             transport: "cli",
             source: "claude_json",
-            inputTokens: promptTokens,
+            inputTokens: promptTokens + cacheCreationInputTokens,
             cachedInputTokens,
             outputTokens: tokensOut,
             rawUsageAvailable: true,
@@ -239,20 +270,23 @@ function extractGeminiJsonResult(stdout, modelLabel) {
         })
     };
 }
-function createStreamingUsageInspector(capUsd, modelLabel) {
-    const pricing = (modelLabel ? MODEL_PRICING[modelLabel] : undefined) ??
-        { inputPer1K: BLENDED_INPUT_COST_PER_1K, outputPer1K: BLENDED_OUTPUT_COST_PER_1K };
+function createStreamingUsageInspector(capUsd, modelLabel, promptTokenEstimate) {
+    let pricingResolution = resolveModelPricing(modelLabel);
     // Safety margin: terminate at 80% of cap to bound one-turn overshoot.
     // Without this, a single expensive turn can blow past the cap before the
     // next check fires (proven live: $1.50 cap → $28.42 actual).
-    const effectiveCapUsd = capUsd * 0.8;
+    const largeContext = promptTokenEstimate > 10_000;
+    const effectiveCapRatio = largeContext ? 0.7 : 0.8;
+    const effectiveCapUsd = capUsd * effectiveCapRatio;
     // Token-count ceiling fallback: if no usage events are ever parsed (e.g.
     // Claude changes its stream-json event format), use raw byte volume as a
     // last-resort circuit breaker. Derived from budget / blended cost per char.
-    const blendedCostPerChar = (pricing.inputPer1K / 1000 / 4) + (pricing.outputPer1K / 1000 / 4);
-    const bytesCeiling = blendedCostPerChar > 0
-        ? Math.ceil((capUsd / blendedCostPerChar) * 2)
-        : 100_000_000;
+    const resolveBlendedCostPerChar = () => {
+        const pricing = pricingResolution.pricing;
+        return pricing
+            ? (pricing.inputPer1K / 1000 / 4) + (pricing.outputPer1K / 1000 / 4)
+            : undefined;
+    };
     // Time-based fallback: if we receive data but no usage events for this long,
     // estimate spend from byte volume and enforce the cap. Prevents the inspector
     // from going blind when Claude changes its stream-json event format.
@@ -269,11 +303,14 @@ function createStreamingUsageInspector(capUsd, modelLabel) {
     const checkBudgetExceeded = (terminate) => {
         if (capUsd > 0 && cumulativeUsd > effectiveCapUsd) {
             terminate(`Streaming usage cap exceeded after ${String(turns)} turn(s): cumulative cost ~$${cumulativeUsd.toFixed(4)} ` +
-                `surpassed the per-attempt cap $${capUsd.toFixed(4)} (80% threshold: $${effectiveCapUsd.toFixed(4)}). ` +
+                `surpassed the per-attempt cap $${capUsd.toFixed(4)} (${String(Math.round(effectiveCapRatio * 100))}% threshold: $${effectiveCapUsd.toFixed(4)}). ` +
                 `Subprocess terminated to bound runaway overspend.`);
         }
     };
     const extractUsageFromEvent = (event, terminate) => {
+        if (event.type === "system" && event.subtype === "init" && typeof event.model === "string") {
+            pricingResolution = resolveModelPricing(event.model);
+        }
         // Check for authoritative total_cost_usd on ANY event — if Claude reports
         // cost exceeding cap, terminate immediately regardless of event type.
         if (typeof event.total_cost_usd === "number" && event.total_cost_usd > 0) {
@@ -293,18 +330,43 @@ function createStreamingUsageInspector(capUsd, modelLabel) {
             return;
         }
         const usageRecord = usage;
-        const turnTokensIn = (usageRecord.input_tokens ?? usageRecord.inputTokens ?? 0) +
-            (usageRecord.cache_read_input_tokens ?? usageRecord.cacheReadInputTokens ?? 0) +
-            (usageRecord.cache_creation_input_tokens ?? usageRecord.cacheCreationInputTokens ?? 0);
+        const turnInputTokens = usageRecord.input_tokens ?? usageRecord.inputTokens ?? 0;
+        const turnCachedInputTokens = usageRecord.cache_read_input_tokens ?? usageRecord.cacheReadInputTokens ?? 0;
+        const turnCacheCreationInputTokens = usageRecord.cache_creation_input_tokens ?? usageRecord.cacheCreationInputTokens ?? 0;
+        const turnTokensIn = turnInputTokens + turnCachedInputTokens + turnCacheCreationInputTokens;
         const turnTokensOut = usageRecord.output_tokens ?? usageRecord.outputTokens ?? 0;
         if (turnTokensIn === 0 && turnTokensOut === 0) {
             return;
         }
+        const turnUsd = pricingResolution.pricing
+            ? calculateUsageCost({
+                inputTokens: turnInputTokens,
+                cachedInputTokens: turnCachedInputTokens,
+                cacheCreationInputTokens: turnCacheCreationInputTokens,
+                outputTokens: turnTokensOut
+            }, pricingResolution.pricing)
+            : undefined;
+        const remainingBudgetBeforeTurn = Math.max(capUsd - cumulativeUsd, 0);
+        if (turnUsd !== undefined &&
+            capUsd > 0 &&
+            remainingBudgetBeforeTurn > 0 &&
+            turnUsd > remainingBudgetBeforeTurn * 0.5) {
+            cumulativeUsd += turnUsd;
+            tokensIn += turnTokensIn;
+            tokensOut += turnTokensOut;
+            turns += 1;
+            usageEventSeen = true;
+            terminate(`Single turn spend ~$${turnUsd.toFixed(4)} consumed more than 50% of the remaining per-attempt budget ` +
+                `($${remainingBudgetBeforeTurn.toFixed(4)} before the turn). Subprocess terminated to prevent a one-turn overshoot.`);
+            return;
+        }
         tokensIn += turnTokensIn;
         tokensOut += turnTokensOut;
         turns += 1;
         usageEventSeen = true;
-        cumulativeUsd += (turnTokensIn / 1000) * pricing.inputPer1K + (turnTokensOut / 1000) * pricing.outputPer1K;
+        if (turnUsd !== undefined) {
+            cumulativeUsd += turnUsd;
+        }
         checkBudgetExceeded(terminate);
     };
     const ingestLine = (line, terminate) => {
@@ -319,10 +381,14 @@ function createStreamingUsageInspector(capUsd, modelLabel) {
         catch {
             return;
         }
-        extractUsageFromEvent(event, terminate);
+        // result events contain aggregate usage that duplicates previously streamed
+        // assistant-message usage events — skip to avoid double-counting.
         if (event.type === "result") {
             finalResult = event;
         }
+        else {
+            extractUsageFromEvent(event, terminate);
+        }
     };
     return {
         onChunk: (chunk, terminate) => {
@@ -333,7 +399,11 @@ function createStreamingUsageInspector(capUsd, modelLabel) {
             // Token-count ceiling fallback: if we've ingested a lot of bytes but
             // never seen a single usage event, the event format may have changed
             // and the inspector is silently blind. Terminate as a last resort.
-            if (!usageEventSeen && capUsd > 0 && totalBytes > bytesCeiling) {
+            const blendedCostPerChar = resolveBlendedCostPerChar();
+            const bytesCeiling = blendedCostPerChar && blendedCostPerChar > 0
+                ? Math.ceil((capUsd / blendedCostPerChar) * 2)
+                : undefined;
+            if (!usageEventSeen && capUsd > 0 && bytesCeiling !== undefined && totalBytes > bytesCeiling) {
                 terminate(`Streaming byte ceiling exceeded (${String(totalBytes)} bytes > ${String(bytesCeiling)} ceiling) ` +
                     `without any usage events parsed. The Claude stream-json event format may have changed. ` +
                     `Subprocess terminated as a fallback budget guard for cap $${capUsd.toFixed(4)}.`);
@@ -348,8 +418,8 @@ function createStreamingUsageInspector(capUsd, modelLabel) {
                 firstChunkAt !== undefined &&
                 Date.now() - firstChunkAt > USAGE_BLIND_TIMEOUT_MS &&
                 totalBytes > 10_000) {
-                const estimatedUsd = totalBytes * blendedCostPerChar;
-                if (estimatedUsd > effectiveCapUsd) {
+                const estimatedUsd = blendedCostPerChar === undefined ? undefined : totalBytes * blendedCostPerChar;
+                if (estimatedUsd !== undefined && estimatedUsd > effectiveCapUsd) {
                     terminate(`No usage events received after ${String(Math.round((Date.now() - firstChunkAt) / 1000))}s ` +
                         `(${String(totalBytes)} bytes). Estimated cost ~$${estimatedUsd.toFixed(4)} exceeds cap ` +
                         `$${capUsd.toFixed(4)}. Subprocess terminated to prevent unmetered spend.`);
@@ -443,11 +513,11 @@ export function createAgentCliAdapter(options) {
         },
         async execute(request) {
             const prompt = buildPrompt(request);
-            const estimatedUsage = estimateUsage(prompt, options.model ?? options.command);
+            const estimatedUsage = estimateUsage(prompt, options.model ?? options.command, options.command);
             // Preflight: bail if projected cost exceeds remaining budget
             if (request.context.remainingBudgetUsd > 0) {
-                const projected = estimatePromptCost(prompt, options.model ?? "");
-                if (projected > request.context.remainingBudgetUsd * 0.95) {
+                const projected = estimatePromptCost(prompt, options.model ?? "", options.command);
+                if (projected !== undefined && projected > request.context.remainingBudgetUsd * 0.95) {
                     return {
                         status: "failed",
                         summary: `Preflight: projected cost $${projected.toFixed(4)} exceeds remaining budget $${request.context.remainingBudgetUsd.toFixed(4)}.`,
@@ -463,7 +533,7 @@ export function createAgentCliAdapter(options) {
                     };
                 }
             }
-            const args = options.argsBuilder(prompt);
+            const args = options.argsBuilder(prompt, request);
             const stdinData = options.stdinBuilder?.(prompt);
             // Live cumulative-cost circuit breaker: a single attempt should never be
             // allowed to spend more than the loop has left. `--output-format json`
@@ -472,7 +542,7 @@ export function createAgentCliAdapter(options) {
             // instant projected spend crosses what remains — bounding the worst case
             // to roughly one turn's overshoot rather than the entire runaway session.
             const streamingUsage = options.streamingUsageCap && request.context.remainingBudgetUsd > 0
-                ? createStreamingUsageInspector(request.context.remainingBudgetUsd, options.model ?? options.command)
+                ? createStreamingUsageInspector(request.context.remainingBudgetUsd, options.model ?? options.command, estimatedUsage.tokensIn)
                 : undefined;
             const agentResult = await runSubprocess(options.command, args, {
                 cwd: workingDirectory,
@@ -797,7 +867,7 @@ export function createClaudeCliAdapter(options = {}) {
         supportsJsonOutput: true,
         streamingUsageCap: true,
         spawnImpl: options.spawnImpl,
-        argsBuilder: (_prompt) => [
+        argsBuilder: (_prompt, request) => [
             "--output-format",
             "stream-json",
             "--verbose",
@@ -1026,21 +1096,27 @@ function sanitizeForPrompt(input) {
     }
     return redactSecretsForPrompt(out);
 }
-function estimatePromptCost(promptText, model) {
+function estimatePromptCost(promptText, model, providerCommand) {
     const inputTokens = Math.ceil(promptText.length / 3.5);
     const outputTokens = 2000;
-    const pricing = MODEL_PRICING[model] ?? { inputPer1K: BLENDED_INPUT_COST_PER_1K, outputPer1K: BLENDED_OUTPUT_COST_PER_1K };
+    const pricing = resolveModelPricing(model).pricing ?? (providerCommand === "claude"
+        ? undefined
+        : { inputPer1K: BLENDED_INPUT_COST_PER_1K, outputPer1K: BLENDED_OUTPUT_COST_PER_1K });
+    if (!pricing) {
+        return undefined;
+    }
     return (inputTokens / 1000) * pricing.inputPer1K + (outputTokens / 1000) * pricing.outputPer1K;
 }
-function estimateUsage(promptText, model) {
+function estimateUsage(promptText, model, providerCommand) {
     const inputTokens = Math.ceil(promptText.length / 3.5);
     const outputTokens = 2_000;
+    const estimatedUsd = estimatePromptCost(promptText, model, providerCommand);
     return normalizeUsage({
-        actualUsd: estimatePromptCost(promptText, model),
-        estimatedUsd: estimatePromptCost(promptText, model),
+        actualUsd: estimatedUsd ?? 0,
+        ...(estimatedUsd === undefined ? {} : { estimatedUsd }),
         tokensIn: inputTokens,
         tokensOut: outputTokens,
-        provenance: "estimated"
+        provenance: estimatedUsd === undefined ? "unavailable" : "estimated"
     });
 }
 function redactSecretsForPrompt(input) {

package/dist/vendor/adapters/codex-launcher.js

@@ -357,6 +357,10 @@ function discoverCommandOffPath(command, platform, env) {
         const localAppData = env.LOCALAPPDATA;
         if (localAppData)
             dirs.push(join(localAppData, "OpenAI", "Codex", "bin"));
+        // Claude Code native installer places binary at %USERPROFILE%\.local\bin
+        const userProfile = env.USERPROFILE ?? env.HOMEPATH;
+        if (userProfile)
+            dirs.push(join(userProfile, ".local", "bin"));
         if (home)
             dirs.push(join(home, "scoop", "shims"));
     }
@@ -383,8 +387,13 @@ function discoverCommandOffPath(command, platform, env) {
     return undefined;
 }
 function suggestInstall(command) {
+    if (command === "claude") {
+        const installCmd = process.platform === "win32"
+            ? "irm https://claude.ai/install.ps1 | iex"
+            : "curl -fsSL https://claude.ai/install.sh | bash";
+        return `Install with: ${installCmd}`;
+    }
     const installs = {
-        claude: "Install with: npm install -g @anthropic-ai/claude-code",
         codex: "Install with: npm install -g @openai/codex",
         gemini: "Install with: npm install -g @google/gemini-cli"
     };

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;
+}

package/dist/vendor/contracts/delivery.js

@@ -0,0 +1,18 @@
+/**
+ * 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 const DELIVERY_MESSAGE_SCHEMA_VERSION = "delivery-message/1";
+export const DELIVERY_RECORD_SCHEMA_VERSION = "delivery-record/1";
+export const MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION = "martin-message-selection/1";
+export const ALLOWED_ACTION_TYPES = [
+    "upgrade_cli",
+    "upgrade_mcp",
+    "submit_feedback",
+    "open_release_notes",
+    "dismiss",
+    "view_spend_report",
+    "view_run_explain",
+];

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

@@ -410,3 +410,5 @@ export { cloneIdentityAttestation, cloneIdentityClaims, cloneIdentityToken } fro
 export type { IdentityAttestation, IdentityClaims, IdentityToken } from "./identity.js";
 export { cloneCircuitBreakDecision, cloneTrajectoryAssessment } from "./trajectory.js";
 export type { CircuitBreakDecision, TrajectoryAssessment, TrajectorySignal } from "./trajectory.js";
+export { ALLOWED_ACTION_TYPES, DELIVERY_MESSAGE_SCHEMA_VERSION, DELIVERY_RECORD_SCHEMA_VERSION, MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION } from "./delivery.js";
+export type { ActionType, DeliveryMessage, DeliveryRecord, MessageKind, MessageSelectionResponse, UpdateAvailableField } from "./delivery.js";

package/dist/vendor/contracts/index.js

@@ -223,3 +223,5 @@ export { DEFAULT_ROUTING_POLICY } from "./execution-policy.js";
 export { cloneContextGraphSnapshot } from "./context-graph.js";
 export { cloneIdentityAttestation, cloneIdentityClaims, cloneIdentityToken } from "./identity.js";
 export { cloneCircuitBreakDecision, cloneTrajectoryAssessment } from "./trajectory.js";
+// ─── R4 Delivery — M1 Contract ──────────────────────────────────────────────
+export { ALLOWED_ACTION_TYPES, DELIVERY_MESSAGE_SCHEMA_VERSION, DELIVERY_RECORD_SCHEMA_VERSION, MESSAGE_SELECTION_RESPONSE_SCHEMA_VERSION } from "./delivery.js";

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

@@ -0,0 +1,6 @@
+export { fetchSelectedMessage } from "./message-client.js";
+export type { MessageClientOptions, MessageSelectRequest } from "./message-client.js";
+export { cacheMessage, isCooldownExpired, isDismissed, loadDeliveryRecord, recordDismissed, recordShown, resolveDefaultLedgerPath, saveDeliveryRecord, } from "./message-ledger.js";
+export { parseMessageSelectionResponse } from "./message-schema.js";
+export type { ParseFailure, ParseResult, ValidationError } from "./message-schema.js";
+export { getCliInstalledVersion, getMcpInstalledVersion, isNewerVersion } from "./update-check.js";

package/dist/vendor/core/delivery/index.js

@@ -0,0 +1,4 @@
+export { fetchSelectedMessage } from "./message-client.js";
+export { cacheMessage, isCooldownExpired, isDismissed, loadDeliveryRecord, recordDismissed, recordShown, resolveDefaultLedgerPath, saveDeliveryRecord, } from "./message-ledger.js";
+export { parseMessageSelectionResponse } from "./message-schema.js";
+export { getCliInstalledVersion, getMcpInstalledVersion, isNewerVersion } from "./update-check.js";

package/dist/vendor/core/delivery/message-client.d.ts

@@ -0,0 +1,18 @@
+import { type DeliveryMessage } from "../../contracts/index.js";
+export interface MessageSelectRequest {
+    installId?: string;
+    clientVersion: string;
+    clientKind: "cli" | "mcp";
+    /** Enum signal — never a transcript or raw content */
+    trigger?: "first_verified_run" | "milestone_reached" | "version_check";
+}
+export interface MessageClientOptions {
+    endpoint?: string;
+    timeoutMs?: number;
+}
+/**
+ * Fetch a server-selected message from the Control Plane.
+ * Returns null on any network failure, timeout, or validation error.
+ * Never throws — the primary command must never be affected.
+ */
+export declare function fetchSelectedMessage(request: MessageSelectRequest, options?: MessageClientOptions): Promise<DeliveryMessage | null>;

package/dist/vendor/core/delivery/message-client.js

@@ -0,0 +1,38 @@
+import { parseMessageSelectionResponse } from "./message-schema.js";
+const DEFAULT_ENDPOINT = "https://api.martinloop.com/v1/messages/select";
+const REQUEST_TIMEOUT_MS = 4_000;
+/**
+ * Fetch a server-selected message from the Control Plane.
+ * Returns null on any network failure, timeout, or validation error.
+ * Never throws — the primary command must never be affected.
+ */
+export async function fetchSelectedMessage(request, options = {}) {
+    const endpoint = options.endpoint ?? process.env["MARTIN_MESSAGE_ENDPOINT"] ?? DEFAULT_ENDPOINT;
+    const timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
+    let controller;
+    let timeoutId;
+    try {
+        controller = new AbortController();
+        timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Accept": "application/json" },
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return null;
+        const raw = await response.text();
+        const result = parseMessageSelectionResponse(raw);
+        if (!result.ok)
+            return null;
+        return result.message ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+    }
+}

package/dist/vendor/core/delivery/message-ledger.d.ts

@@ -0,0 +1,35 @@
+import { type DeliveryMessage, type DeliveryRecord } from "../../contracts/index.js";
+/**
+ * Load DeliveryRecord from disk. Returns empty record on any read/parse failure — never throws.
+ */
+export declare function loadDeliveryRecord(ledgerPath: string): DeliveryRecord;
+/**
+ * Persist DeliveryRecord atomically via temp-file + rename.
+ */
+export declare function saveDeliveryRecord(ledgerPath: string, record: DeliveryRecord): void;
+/**
+ * Returns true when the cooldown period has elapsed and the message should be shown.
+ * Clock-skew safe: if now < lastShownAtEpochMs (clock jumped back), treat cooldown as expired.
+ */
+export declare function isCooldownExpired(record: DeliveryRecord, nowMs: number): boolean;
+/**
+ * Returns true if this message id was permanently dismissed.
+ */
+export declare function isDismissed(record: DeliveryRecord, messageId: string): boolean;
+/**
+ * Record that a message was shown. Updates cooldown window.
+ */
+export declare function recordShown(record: DeliveryRecord, message: DeliveryMessage, nowMs: number): DeliveryRecord;
+/**
+ * Record that a message was permanently dismissed.
+ */
+export declare function recordDismissed(record: DeliveryRecord, messageId: string): DeliveryRecord;
+/**
+ * Cache a fetched message for offline use.
+ */
+export declare function cacheMessage(record: DeliveryRecord, message: DeliveryMessage, nowMs: number): DeliveryRecord;
+/**
+ * Resolve the default ledger path: $MARTIN_STATE_DIR/delivery-record.json
+ * or ~/.martin/delivery-record.json.
+ */
+export declare function resolveDefaultLedgerPath(): string;

package/dist/vendor/core/delivery/message-ledger.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DELIVERY_RECORD_SCHEMA_VERSION } from "../../contracts/index.js";
+const EMPTY_RECORD = {
+    schemaVersion: DELIVERY_RECORD_SCHEMA_VERSION,
+    dismissedIds: [],
+};
+/**
+ * Load DeliveryRecord from disk. Returns empty record on any read/parse failure — never throws.
+ */
+export function loadDeliveryRecord(ledgerPath) {
+    try {
+        const raw = fs.readFileSync(ledgerPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            !Array.isArray(parsed) &&
+            parsed["schemaVersion"] === DELIVERY_RECORD_SCHEMA_VERSION) {
+            return parsed;
+        }
+    }
+    catch {
+        // file missing or corrupt — start fresh
+    }
+    return { ...EMPTY_RECORD, dismissedIds: [] };
+}
+/**
+ * Persist DeliveryRecord atomically via temp-file + rename.
+ */
+export function saveDeliveryRecord(ledgerPath, record) {
+    const dir = path.dirname(ledgerPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(os.tmpdir(), `martin-dlv-${process.pid}-${Date.now()}.json`);
+    fs.writeFileSync(tmp, JSON.stringify(record, null, 2), "utf8");
+    fs.renameSync(tmp, ledgerPath);
+}
+/**
+ * Returns true when the cooldown period has elapsed and the message should be shown.
+ * Clock-skew safe: if now < lastShownAtEpochMs (clock jumped back), treat cooldown as expired.
+ */
+export function isCooldownExpired(record, nowMs) {
+    const until = record.cooldownUntilEpochMs;
+    if (until === undefined)
+        return true;
+    const last = record.lastShownAtEpochMs ?? 0;
+    // If clock appears to have gone backwards past last-shown, treat as expired
+    if (nowMs < last)
+        return true;
+    return nowMs >= until;
+}
+/**
+ * Returns true if this message id was permanently dismissed.
+ */
+export function isDismissed(record, messageId) {
+    return record.dismissedIds.includes(messageId);
+}
+/**
+ * Record that a message was shown. Updates cooldown window.
+ */
+export function recordShown(record, message, nowMs) {
+    return {
+        ...record,
+        lastMessageId: message.id,
+        lastShownAtEpochMs: nowMs,
+        cooldownUntilEpochMs: nowMs + message.cooldownHours * 60 * 60 * 1000,
+    };
+}
+/**
+ * Record that a message was permanently dismissed.
+ */
+export function recordDismissed(record, messageId) {
+    if (record.dismissedIds.includes(messageId))
+        return record;
+    return {
+        ...record,
+        dismissedIds: [...record.dismissedIds, messageId],
+    };
+}
+/**
+ * Cache a fetched message for offline use.
+ */
+export function cacheMessage(record, message, nowMs) {
+    return {
+        ...record,
+        cachedMessage: message,
+        cachedAtEpochMs: nowMs,
+    };
+}
+/**
+ * Resolve the default ledger path: $MARTIN_STATE_DIR/delivery-record.json
+ * or ~/.martin/delivery-record.json.
+ */
+export function resolveDefaultLedgerPath() {
+    const stateDir = process.env["MARTIN_STATE_DIR"] ?? path.join(os.homedir(), ".martin");
+    return path.join(stateDir, "delivery-record.json");
+}