@martinloop/mcp 0.2.7 → 0.3.1

package/dist/tools/tool-errors.js

@@ -92,7 +92,7 @@ export function toToolFailure(error) {
             code: "engine_unavailable",
             category: "environment",
             message,
-            suggestion: "Install the requested CLI or set MARTIN_LIVE=false for stub execution.",
+            suggestion: "Install the requested CLI or set MARTIN_LIVE=false for a no-spend proof run.",
             retryable: false
         };
     }

package/dist/tools/tool-support.d.ts

@@ -1,6 +1,6 @@
-import type { LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask } from "../vendor/contracts/index.js";
+import type { LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask, ReceiptIntegritySummary, ReceiptScope } from "../vendor/contracts/index.js";
 import { type LedgerEvent, type LoopAttemptRecord, type LoopRunRecord } from "../vendor/core/index.js";
-export type MartinEngine = "claude" | "codex";
+export type MartinEngine = "claude" | "codex" | "gemini";
 export interface InspectableLoopAttempt extends LoopAttemptRecord {
     attemptId?: string;
     summary?: string;
@@ -11,6 +11,8 @@ export interface InspectableLoopRecord extends Omit<LoopRunRecord, "attempts" |
     artifacts?: LoopArtifact[];
     events?: LoopEvent[];
     metadata?: Record<string, string>;
+    receiptIntegrity?: ReceiptIntegritySummary;
+    receiptScope?: ReceiptScope;
 }
 export interface LoopPreview {
     loopId: string;
@@ -87,10 +89,11 @@ export interface CliAvailability {
     locator: string;
     detail: string;
     resolvedPath?: string;
+    candidatePaths?: string[];
 }
 export interface ExecutionMode {
     liveMode: boolean;
-    mode: "live" | "stub";
+    mode: "live" | "proof";
     detail: string;
 }
 export interface RunStoreInspection extends LoopCollectionSummary {
@@ -108,11 +111,13 @@ export interface CanonicalRunPaths {
 export declare function resolveExecutionMode(): ExecutionMode;
 export declare function detectCliAvailability(command: string): CliAvailability;
 export declare function getEngineAvailability(engine: MartinEngine): CliAvailability;
+export declare function createSkippedCliAvailability(command: string, detail?: string): CliAvailability;
 export declare function formatUsd(value: number): string;
 export declare function buildLoopPreview(loop: InspectableLoopRecord): LoopPreview;
 export declare function buildAttemptSummary(attempt: InspectableLoopAttempt, artifacts?: AttemptArtifactFiles): AttemptSummary;
 export declare function buildArtifactSummary(loop: InspectableLoopRecord): ArtifactSummary;
 export declare function buildVerificationSummary(loop: InspectableLoopRecord, ledgerEvents?: LedgerEvent[]): VerificationSummary;
+export declare function resolveReceiptIntegrity(loop: InspectableLoopRecord): ReceiptIntegritySummary;
 export declare function buildEventSummaries(loop: InspectableLoopRecord, limit?: number): EventSummary[];
 export declare function buildLoopCollectionSummary(loops: Array<LoopRunRecord | InspectableLoopRecord>): LoopCollectionSummary;
 export declare function inspectRunsRoot(runsRoot?: string): Promise<RunStoreInspection>;

package/dist/tools/tool-support.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { evaluateCostGovernor, resolveRunsRoot } from "../vendor/core/index.js";
@@ -11,10 +11,10 @@ export function resolveExecutionMode() {
     const liveMode = process.env.MARTIN_LIVE !== "false";
     return {
         liveMode,
-        mode: liveMode ? "live" : "stub",
+        mode: liveMode ? "live" : "proof",
         detail: liveMode
             ? "Live CLI execution is enabled."
-            : "Stub mode is active because MARTIN_LIVE=false."
+            : "Proof mode is active because MARTIN_LIVE=false."
     };
 }
 export function detectCliAvailability(command) {
@@ -23,18 +23,9 @@ export function detectCliAvailability(command) {
     if (cached && cached.expiresAt > Date.now()) {
         return cached.value;
     }
-    const locator = process.platform === "win32" ? "where.exe" : "which";
-    const result = spawnSync(locator, [command], {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"]
-    });
-    const resolvedPath = result.status === 0
-        ? (result.stdout ?? "")
-            .split(/\r?\n/u)
-            .map((line) => line.trim())
-            .find(Boolean)
-        : undefined;
-    const value = result.status === 0
+    const locator = process.platform === "win32" ? "path-scan(win32)" : "path-scan(posix)";
+    const resolvedPath = findCommandOnPath(command);
+    const value = resolvedPath
         ? {
             command,
             available: true,
@@ -54,9 +45,54 @@ export function detectCliAvailability(command) {
     });
     return value;
 }
+function findCommandOnPath(command) {
+    const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path");
+    const rawPath = pathKey ? process.env[pathKey] : undefined;
+    if (!rawPath) {
+        return undefined;
+    }
+    const pathEntries = rawPath
+        .split(process.platform === "win32" ? ";" : ":")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    const hasExtension = /\.[A-Za-z0-9]+$/u.test(command);
+    const candidateNames = process.platform === "win32" && !hasExtension
+        ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+            .split(";")
+            .map((extension) => extension.trim())
+            .filter(Boolean)
+            .map((extension) => `${command}${extension.toLowerCase()}`)
+        : [command];
+    for (const directory of pathEntries) {
+        for (const candidateName of candidateNames) {
+            const candidatePath = join(directory, candidateName);
+            if (isExecutablePath(candidatePath)) {
+                return candidatePath;
+            }
+        }
+    }
+    return undefined;
+}
+function isExecutablePath(candidatePath) {
+    try {
+        accessSync(candidatePath, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export function getEngineAvailability(engine) {
     return detectCliAvailability(engine);
 }
+export function createSkippedCliAvailability(command, detail = "Proof mode skipped live CLI availability detection.") {
+    return {
+        command,
+        available: false,
+        locator: "skipped",
+        detail
+    };
+}
 export function formatUsd(value) {
     return `$${value.toFixed(2)}`;
 }
@@ -126,7 +162,11 @@ export function buildVerificationSummary(loop, ledgerEvents = []) {
     const verificationEvents = (loop.events ?? []).filter((event) => event.type === "verification.completed");
     const verificationLedgerEvents = ledgerEvents.filter((event) => event.kind === "verification.completed");
     const warnings = [];
+    const integrity = resolveReceiptIntegrity(loop);
     const ledgerWarnings = getLedgerWarnings(ledgerEvents);
+    if (integrity.state !== "verified") {
+        warnings.push(`Receipt integrity is ${integrity.state}; persisted verifier evidence is not trustworthy yet.`);
+    }
     warnings.push(...ledgerWarnings);
     if (verificationEvents.length === 0) {
         warnings.push(verificationLedgerEvents.length > 0
@@ -163,6 +203,12 @@ export function buildVerificationSummary(loop, ledgerEvents = []) {
         warnings
     };
 }
+export function resolveReceiptIntegrity(loop) {
+    return (loop.receiptIntegrity ?? {
+        state: "unsigned",
+        reason: "Receipt integrity metadata was not available on the loop record."
+    });
+}
 export function buildEventSummaries(loop, limit = 5) {
     return (loop.events ?? [])
         .slice(-limit)
@@ -287,9 +333,6 @@ export function buildSuggestedResourceUris(loopId) {
         `martin://runs/${loopId}/verification`,
         "martin://guides/mcp-usage",
         "martin://guides/agent-start",
-        "martin://guides/command-map",
-        "martin://guides/ide-onboarding",
-        "martin://guides/operating-rules",
         "martin://guides/publish-readiness"
     ];
 }

package/dist/tools/workflow-governance.d.ts

@@ -1,3 +1,4 @@
+import { type LoopBudget } from "../vendor/contracts/index.js";
 import { type RunStoreInspection } from "./tool-support.js";
 export type MartinPolicyPack = "solo-founder" | "startup-team" | "enterprise-strict" | "oss-maintainer" | "security-sensitive";
 export interface RepoGitState {
@@ -23,6 +24,7 @@ export interface RepoSignals {
     packageScripts: Record<string, string>;
     git: RepoGitState;
     sensitivePaths: string[];
+    hostAvailabilityChecked: boolean;
     availableHosts: Record<"claude" | "codex" | "cursor" | "gemini", {
         available: boolean;
         detail: string;
@@ -110,11 +112,25 @@ interface ContractOverrides {
     maxFilesChanged?: number;
     maxCommands?: number;
 }
-export declare function inspectRepoSignals(workingDirectory: string): RepoSignals;
+interface LoopBudgetOverrides {
+    maxUsd?: number;
+    softLimitUsd?: number;
+    maxIterations?: number;
+    maxTokens?: number;
+}
+export declare function inspectRepoSignals(workingDirectory: string, options?: {
+    includeHostAvailability?: boolean;
+}): RepoSignals;
 export declare function buildReadinessReport(signals: RepoSignals, runStore: RunStoreInspection): MartinReadinessReport;
 export declare function buildPolicyPackDefinition(policyPack: MartinPolicyPack | undefined, signals: RepoSignals): MartinPolicyPackDefinition;
-export declare function buildPlanProposal(workingDirectory: string, overrides: ContractOverrides): MartinPlanProposal;
-export declare function buildRunContract(workingDirectory: string, overrides: ContractOverrides): MartinRunContract;
+export declare function buildPlanProposal(workingDirectory: string, overrides: ContractOverrides, options?: {
+    signals?: RepoSignals;
+}): MartinPlanProposal;
+export declare function buildRunContract(workingDirectory: string, overrides: ContractOverrides, options?: {
+    signals?: RepoSignals;
+    plan?: MartinPlanProposal;
+}): MartinRunContract;
+export declare function normalizeLoopBudget(overrides?: LoopBudgetOverrides): LoopBudget;
 export declare function assessRunRisk(input: {
     objective: string;
     context?: string;

package/dist/tools/workflow-governance.js

@@ -2,13 +2,17 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { DEFAULT_BUDGET } from "../vendor/contracts/index.js";
-import { detectCliAvailability } from "./tool-support.js";
+import { createSkippedCliAvailability, detectCliAvailability } from "./tool-support.js";
 const HOST_COMMANDS = {
     claude: "claude",
     codex: "codex",
     cursor: "cursor",
     gemini: "gemini"
 };
+const REPO_SIGNALS_CACHE_TTL_MS = 5_000;
+const repoSignalsCache = new Map();
+const GIT_STATE_CACHE_TTL_MS = 60_000;
+const repoGitStateCache = new Map();
 const POLICY_PACKS = {
     "solo-founder": {
         name: "solo-founder",
@@ -110,13 +114,19 @@ const POLICY_PACKS = {
         requireApprovalAtOrAbove: "medium"
     }
 };
-export function inspectRepoSignals(workingDirectory) {
+export function inspectRepoSignals(workingDirectory, options = {}) {
+    const includeHostAvailability = options.includeHostAvailability ?? true;
+    const cacheKey = `${workingDirectory}::hosts=${includeHostAvailability ? "live" : "skipped"}`;
+    const cached = repoSignalsCache.get(cacheKey);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.value;
+    }
     const packageScripts = readPackageScripts(workingDirectory);
     const packageManager = detectPackageManager(workingDirectory);
     const frameworks = detectFrameworks(workingDirectory, packageScripts);
     const languages = detectLanguages(workingDirectory, frameworks);
     const verifiers = detectVerifierCommands(packageScripts, packageManager);
-    return {
+    const signals = {
         workingDirectory,
         packageManager,
         languages,
@@ -125,13 +135,27 @@ export function inspectRepoSignals(workingDirectory) {
         packageScripts,
         git: detectGitState(workingDirectory),
         sensitivePaths: detectSensitivePaths(workingDirectory),
+        hostAvailabilityChecked: includeHostAvailability,
         availableHosts: {
-            claude: detectCliAvailability(HOST_COMMANDS.claude),
-            codex: detectCliAvailability(HOST_COMMANDS.codex),
-            cursor: detectCliAvailability(HOST_COMMANDS.cursor),
-            gemini: detectCliAvailability(HOST_COMMANDS.gemini)
+            claude: includeHostAvailability
+                ? detectCliAvailability(HOST_COMMANDS.claude)
+                : createSkippedCliAvailability(HOST_COMMANDS.claude),
+            codex: includeHostAvailability
+                ? detectCliAvailability(HOST_COMMANDS.codex)
+                : createSkippedCliAvailability(HOST_COMMANDS.codex),
+            cursor: includeHostAvailability
+                ? detectCliAvailability(HOST_COMMANDS.cursor)
+                : createSkippedCliAvailability(HOST_COMMANDS.cursor),
+            gemini: includeHostAvailability
+                ? detectCliAvailability(HOST_COMMANDS.gemini)
+                : createSkippedCliAvailability(HOST_COMMANDS.gemini)
         }
     };
+    repoSignalsCache.set(cacheKey, {
+        expiresAt: Date.now() + REPO_SIGNALS_CACHE_TTL_MS,
+        value: signals
+    });
+    return signals;
 }
 export function buildReadinessReport(signals, runStore) {
     const missingSafeguards = [];
@@ -155,7 +179,9 @@ export function buildReadinessReport(signals, runStore) {
     if (signals.frameworks.length === 0) {
         score -= 8;
     }
-    if (!signals.availableHosts.claude.available && !signals.availableHosts.codex.available) {
+    if (signals.hostAvailabilityChecked &&
+        !signals.availableHosts.claude.available &&
+        !signals.availableHosts.codex.available) {
         score -= 18;
     }
     score = Math.max(0, Math.min(100, score));
@@ -189,8 +215,8 @@ export function buildPolicyPackDefinition(policyPack, signals) {
             : fallbackVerifierPlan(signals.packageManager)
     };
 }
-export function buildPlanProposal(workingDirectory, overrides) {
-    const signals = inspectRepoSignals(workingDirectory);
+export function buildPlanProposal(workingDirectory, overrides, options = {}) {
+    const signals = options.signals ?? inspectRepoSignals(workingDirectory);
     const policy = buildPolicyPackDefinition(overrides.policyPack, signals);
     const scope = inferScopeFromObjective(overrides.objective, policy, overrides);
     const estimatedBudget = buildBudget(overrides, signals);
@@ -223,8 +249,8 @@ export function buildPlanProposal(workingDirectory, overrides) {
         ]
     };
 }
-export function buildRunContract(workingDirectory, overrides) {
-    const plan = buildPlanProposal(workingDirectory, overrides);
+export function buildRunContract(workingDirectory, overrides, options = {}) {
+    const plan = options.plan ?? buildPlanProposal(workingDirectory, overrides, options);
     return {
         objective: overrides.objective,
         ...(overrides.context ? { context: overrides.context } : {}),
@@ -238,6 +264,16 @@ export function buildRunContract(workingDirectory, overrides) {
             shouldRequireApproval(plan.policyPack.requireApprovalAtOrAbove, plan.risk.level)
     };
 }
+export function normalizeLoopBudget(overrides = {}) {
+    const maxUsd = overrides.maxUsd ?? DEFAULT_BUDGET.maxUsd;
+    const softLimitUsd = Math.min(overrides.softLimitUsd ?? DEFAULT_BUDGET.softLimitUsd, maxUsd);
+    return {
+        maxUsd,
+        softLimitUsd,
+        maxIterations: overrides.maxIterations ?? DEFAULT_BUDGET.maxIterations,
+        maxTokens: overrides.maxTokens ?? DEFAULT_BUDGET.maxTokens
+    };
+}
 export function assessRunRisk(input) {
     const reasons = [];
     let score = 12;
@@ -406,17 +442,10 @@ function detectVerifierCommands(scripts, packageManager) {
     return { test, lint, build, defaultPlan };
 }
 function detectGitState(workingDirectory) {
-    const availability = spawnSync("git", ["--version"], {
-        cwd: workingDirectory,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"]
-    });
-    if (availability.status !== 0) {
-        return {
-            available: false,
-            isRepo: false,
-            clean: false
-        };
+    const cacheKey = workingDirectory;
+    const cached = repoGitStateCache.get(cacheKey);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.value;
     }
     const isRepo = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
         cwd: workingDirectory,
@@ -424,18 +453,29 @@ function detectGitState(workingDirectory) {
         stdio: ["ignore", "pipe", "pipe"]
     });
     if (isRepo.status !== 0 || !/true/u.test(isRepo.stdout ?? "")) {
-        return {
-            available: true,
-            isRepo: false,
-            clean: false
-        };
+        const availability = spawnSync("git", ["--version"], {
+            cwd: workingDirectory,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        const value = availability.status !== 0
+            ? {
+                available: false,
+                isRepo: false,
+                clean: false
+            }
+            : {
+                available: true,
+                isRepo: false,
+                clean: false
+            };
+        repoGitStateCache.set(cacheKey, {
+            expiresAt: Date.now() + GIT_STATE_CACHE_TTL_MS,
+            value
+        });
+        return value;
     }
-    const branch = spawnSync("git", ["branch", "--show-current"], {
-        cwd: workingDirectory,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"]
-    }).stdout.trim();
-    const status = spawnSync("git", ["status", "--porcelain", "--branch"], {
+    const status = spawnSync("git", ["status", "--porcelain=v2", "--branch", "--untracked-files=normal", "--ignored=no", "--", "."], {
         cwd: workingDirectory,
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"]
@@ -444,20 +484,42 @@ function detectGitState(workingDirectory) {
         .split(/\r?\n/u)
         .map((line) => line.trim())
         .filter(Boolean);
-    const dirty = statusLines.some((line) => !line.startsWith("##"));
-    const header = statusLines.find((line) => line.startsWith("##"));
-    const upstream = header?.match(/\.\.\.([^\s[]+)/u)?.[1];
-    const ahead = parseCount(header, /ahead (\d+)/u);
-    const behind = parseCount(header, /behind (\d+)/u);
-    return {
+    const dirty = statusLines.some((line) => !line.startsWith("#"));
+    const branch = statusLines
+        .find((line) => line.startsWith("# branch.head "))
+        ?.replace("# branch.head ", "")
+        .trim();
+    const upstream = statusLines
+        .find((line) => line.startsWith("# branch.upstream "))
+        ?.replace("# branch.upstream ", "")
+        .trim();
+    const aheadBehind = statusLines
+        .find((line) => line.startsWith("# branch.ab "))
+        ?.replace("# branch.ab ", "")
+        .trim()
+        .split(/\s+/u);
+    const aheadToken = aheadBehind?.find((token) => token.startsWith("+"));
+    const behindToken = aheadBehind?.find((token) => token.startsWith("-"));
+    const ahead = aheadToken && aheadToken.length > 1
+        ? Number.parseInt(aheadToken.slice(1), 10)
+        : undefined;
+    const behind = behindToken && behindToken.length > 1
+        ? Number.parseInt(behindToken.slice(1), 10)
+        : undefined;
+    const value = {
         available: true,
         isRepo: true,
         clean: !dirty,
-        ...(branch ? { branch } : {}),
+        ...(branch && branch !== "(detached)" ? { branch } : {}),
         ...(upstream ? { upstream } : {}),
-        ...(ahead !== undefined ? { ahead } : {}),
-        ...(behind !== undefined ? { behind } : {})
+        ...(Number.isFinite(ahead) ? { ahead } : {}),
+        ...(Number.isFinite(behind) ? { behind } : {})
     };
+    repoGitStateCache.set(cacheKey, {
+        expiresAt: Date.now() + GIT_STATE_CACHE_TTL_MS,
+        value
+    });
+    return value;
 }
 function detectSensitivePaths(workingDirectory) {
     const candidates = [
@@ -520,11 +582,9 @@ function inferScopeFromObjective(objective, policy, overrides) {
 }
 function buildBudget(overrides, signals) {
     const defaultCommands = signals.verifiers.defaultPlan.length > 0 ? 12 : 8;
+    const normalizedBudget = normalizeLoopBudget(overrides);
     return {
-        maxUsd: overrides.maxUsd ?? DEFAULT_BUDGET.maxUsd,
-        softLimitUsd: Math.min(overrides.maxUsd ?? DEFAULT_BUDGET.maxUsd, DEFAULT_BUDGET.softLimitUsd),
-        maxIterations: overrides.maxIterations ?? DEFAULT_BUDGET.maxIterations,
-        maxTokens: overrides.maxTokens ?? DEFAULT_BUDGET.maxTokens,
+        ...normalizedBudget,
         maxMinutes: overrides.maxMinutes ?? 20,
         maxFilesChanged: overrides.maxFilesChanged ?? 8,
         maxCommands: overrides.maxCommands ?? defaultCommands
@@ -571,11 +631,3 @@ function shouldRequireApproval(threshold, level) {
     const ordering = ["low", "medium", "high"];
     return ordering.indexOf(level) >= ordering.indexOf(threshold);
 }
-function parseCount(value, pattern) {
-    const match = value?.match(pattern)?.[1];
-    if (!match) {
-        return undefined;
-    }
-    const parsed = Number.parseInt(match, 10);
-    return Number.isFinite(parsed) ? parsed : undefined;
-}

package/dist/vendor/adapters/claude-cli.d.ts

@@ -45,6 +45,15 @@ export interface AgentCliAdapterOptions {
      * Defaults to true for Claude.
      */
     supportsJsonOutput?: boolean;
+    /**
+     * Set when `argsBuilder` requests `--output-format stream-json` (newline-
+     * delimited JSON events) rather than single-blob `json`. Enables (a)
+     * incremental result parsing that scans for the final `result` event, and
+     * (b) a live cumulative-cost circuit breaker that terminates the subprocess
+     * the moment projected spend crosses the remaining per-attempt budget,
+     * rather than only learning about an overspend after the process exits.
+     */
+    streamingUsageCap?: boolean;
     /** Test-only override for subprocess spawning. */
     spawnImpl?: SpawnLike;
 }
@@ -60,6 +69,8 @@ export interface ClaudeCliAdapterOptions {
     spawnImpl?: SpawnLike;
 }
 export interface CodexCliAdapterOptions {
+    /** Override the executable or absolute command path used to launch Codex. */
+    command?: string;
     workingDirectory?: string;
     timeoutMs?: number;
     verifyTimeoutMs?: number;
@@ -80,12 +91,33 @@ export interface CodexCliAdapterOptions {
     extraArgs?: string[];
     spawnImpl?: SpawnLike;
 }
+export interface GeminiCliAdapterOptions {
+    workingDirectory?: string;
+    timeoutMs?: number;
+    verifyTimeoutMs?: number;
+    label?: string;
+    /** Override the model passed via --model flag. Defaults to the Gemini `flash` alias. */
+    model?: string;
+    /** Approval mode for headless Gemini runs. Defaults to yolo for autonomous execution. */
+    approvalMode?: "default" | "auto_edit" | "yolo" | "plan";
+    /** Enable Gemini sandbox mode when the host is configured for it. Disabled by default. */
+    sandbox?: boolean;
+    /** Extra args appended after core args. */
+    extraArgs?: string[];
+    spawnImpl?: SpawnLike;
+}
 export declare function createAgentCliAdapter(options: AgentCliAdapterOptions): MartinAdapter;
 /**
- * Spawns `claude --output-format json --print "<prompt>" --dangerously-skip-permissions [extraArgs]`.
+ * Spawns `claude --output-format stream-json --verbose --print "<prompt>" [extraArgs]`.
  *
- * The --output-format json flag causes Claude CLI to return structured JSON
- * including real token usage counts, enabling accurate cost tracking.
+ * `stream-json` emits one JSON event per line — including per-turn usage on
+ * each `assistant` message and a final `result` event carrying the same
+ * `result`/`usage`/`total_cost_usd` fields as single-blob `json` output — so
+ * MartinLoop can both (a) recover real token usage/cost as before, and
+ * (b) watch cumulative spend live and self-terminate the subprocess the
+ * moment it crosses the remaining per-attempt budget (see
+ * `streamingUsageCap` / `createStreamingUsageInspector`), instead of only
+ * discovering an overspend after the whole process has already exited.
  *
  * Requires the Claude Code CLI to be installed and authenticated:
  *   https://docs.anthropic.com/claude-code
@@ -102,3 +134,13 @@ export declare function createClaudeCliAdapter(options?: ClaudeCliAdapterOptions
  *   npm install -g @openai/codex
  */
 export declare function createCodexCliAdapter(options?: CodexCliAdapterOptions): MartinAdapter;
+/**
+ * Spawns `gemini --model <model> --prompt "" --approval-mode <mode> --output-format json [...]`.
+ *
+ * The prompt is delivered via stdin while forcing headless mode with `--prompt ""`,
+ * which keeps large MartinLoop prompts off the command line on Windows.
+ *
+ * Requires the Gemini CLI to be installed and authenticated:
+ *   npm install -g @google/gemini-cli
+ */
+export declare function createGeminiCliAdapter(options?: GeminiCliAdapterOptions): MartinAdapter;