martin-loop 0.1.5 → 1.3.0

package/dist/vendor/cli/research/public-corpus.d.ts

@@ -0,0 +1,43 @@
+export type PublicResearchSource = "github" | "reddit" | "hackernews" | "docs" | "forum" | "blog" | "social";
+export type PublicResearchSeverity = "low" | "medium" | "high" | "critical";
+export type PublicResearchActionability = "low" | "medium" | "high";
+export type PublicResearchFrequencyBucket = "isolated" | "recurring" | "saturated";
+export interface PublicResearchItemInput {
+    source: PublicResearchSource;
+    url: string;
+    date: string;
+    ecosystem: string;
+    persona: string;
+    problem: string;
+    severity: PublicResearchSeverity;
+    excerpt: string;
+    actionability: PublicResearchActionability;
+    martinLoopFit: string[];
+}
+export interface PublicResearchItem extends PublicResearchItemInput {
+    canonicalUrl: string;
+    fingerprint: string;
+    normalizedProblem: string;
+}
+export interface PublicResearchProblemSummary {
+    problem: string;
+    normalizedProblem: string;
+    count: number;
+    ecosystems: string[];
+    recommendedFit: string[];
+    frequencyBucket: PublicResearchFrequencyBucket;
+}
+export interface PublicResearchCorpusSummary {
+    totalItems: number;
+    bySource: Record<PublicResearchSource, number>;
+    byProblem: PublicResearchProblemSummary[];
+    topFits: Array<{
+        fit: string;
+        count: number;
+    }>;
+}
+export declare function normalizePublicResearchItem(input: PublicResearchItemInput): PublicResearchItem;
+export declare function dedupePublicResearchItems(items: PublicResearchItemInput[]): PublicResearchItem[];
+export declare function summarizePublicResearchCorpus(items: PublicResearchItem[]): PublicResearchCorpusSummary;
+export declare function renderPublicResearchCorpusReport(summary: PublicResearchCorpusSummary): string;
+export declare function bucketFrequency(count: number): PublicResearchFrequencyBucket;

package/dist/vendor/cli/research/public-corpus.js

@@ -0,0 +1,151 @@
+import { createHash } from "node:crypto";
+export function normalizePublicResearchItem(input) {
+    const canonicalUrl = normalizeUrl(input.url);
+    const normalizedProblem = normalizeText(input.problem);
+    const normalizedExcerpt = normalizeText(input.excerpt);
+    return {
+        ...input,
+        ecosystem: input.ecosystem.trim(),
+        persona: input.persona.trim(),
+        problem: input.problem.trim(),
+        excerpt: input.excerpt.trim(),
+        martinLoopFit: uniqueStrings(input.martinLoopFit),
+        canonicalUrl,
+        normalizedProblem,
+        fingerprint: createFingerprint(canonicalUrl, normalizedProblem, normalizeText(input.ecosystem), normalizedExcerpt.slice(0, 140))
+    };
+}
+export function dedupePublicResearchItems(items) {
+    const deduped = new Map();
+    for (const item of items.map(normalizePublicResearchItem)) {
+        const duplicateKey = `${item.canonicalUrl}::${item.normalizedProblem}`;
+        const existing = deduped.get(duplicateKey);
+        if (!existing) {
+            deduped.set(duplicateKey, item);
+            continue;
+        }
+        deduped.set(duplicateKey, choosePreferredItem(existing, item));
+    }
+    return [...deduped.values()].sort((left, right) => right.date.localeCompare(left.date));
+}
+export function summarizePublicResearchCorpus(items) {
+    const bySource = {
+        github: 0,
+        reddit: 0,
+        hackernews: 0,
+        docs: 0,
+        forum: 0,
+        blog: 0,
+        social: 0
+    };
+    const problems = new Map();
+    const fits = new Map();
+    for (const item of items) {
+        bySource[item.source] += 1;
+        const existingProblem = problems.get(item.normalizedProblem);
+        if (!existingProblem) {
+            problems.set(item.normalizedProblem, {
+                problem: item.problem,
+                normalizedProblem: item.normalizedProblem,
+                count: 1,
+                ecosystems: [item.ecosystem],
+                recommendedFit: [...item.martinLoopFit],
+                frequencyBucket: "isolated"
+            });
+        }
+        else {
+            existingProblem.count += 1;
+            existingProblem.ecosystems = uniqueStrings([...existingProblem.ecosystems, item.ecosystem]);
+            existingProblem.recommendedFit = uniqueStrings([
+                ...existingProblem.recommendedFit,
+                ...item.martinLoopFit
+            ]);
+            existingProblem.frequencyBucket = bucketFrequency(existingProblem.count);
+        }
+        for (const fit of item.martinLoopFit) {
+            fits.set(fit, (fits.get(fit) ?? 0) + 1);
+        }
+    }
+    return {
+        totalItems: items.length,
+        bySource,
+        byProblem: [...problems.values()].sort((left, right) => right.count - left.count),
+        topFits: [...fits.entries()]
+            .map(([fit, count]) => ({ fit, count }))
+            .sort((left, right) => right.count - left.count)
+    };
+}
+export function renderPublicResearchCorpusReport(summary) {
+    const sourceLines = Object.entries(summary.bySource)
+        .filter(([, count]) => count > 0)
+        .map(([source, count]) => `- ${source}: ${String(count)}`);
+    const problemLines = summary.byProblem.slice(0, 10).map((problem) => `- ${problem.problem} — ${String(problem.count)} items (${problem.frequencyBucket})`);
+    const fitLines = summary.topFits.slice(0, 7).map((fit) => `- ${fit.fit}: ${String(fit.count)} linked sources`);
+    return [
+        "# Public Research Corpus Summary",
+        "",
+        `Total deduped items: ${String(summary.totalItems)}`,
+        "",
+        "## Sources",
+        ...(sourceLines.length > 0 ? sourceLines : ["- none"]),
+        "",
+        "## Top Problems",
+        ...(problemLines.length > 0 ? problemLines : ["- none"]),
+        "",
+        "## Martin Loop Fits",
+        ...(fitLines.length > 0 ? fitLines : ["- none"]),
+        ""
+    ].join("\n");
+}
+export function bucketFrequency(count) {
+    if (count >= 10)
+        return "saturated";
+    if (count >= 3)
+        return "recurring";
+    return "isolated";
+}
+function choosePreferredItem(left, right) {
+    const leftScore = scoreItem(left);
+    const rightScore = scoreItem(right);
+    return rightScore > leftScore ? right : left;
+}
+function scoreItem(item) {
+    const severityScore = {
+        low: 1,
+        medium: 2,
+        high: 3,
+        critical: 4
+    };
+    const actionabilityScore = {
+        low: 1,
+        medium: 2,
+        high: 3
+    };
+    return (severityScore[item.severity] * 10 +
+        actionabilityScore[item.actionability] * 5 +
+        item.martinLoopFit.length);
+}
+function normalizeUrl(url) {
+    const trimmed = url.trim();
+    const parsed = new URL(trimmed);
+    parsed.hash = "";
+    parsed.searchParams.sort();
+    if ((parsed.hostname === "www.reddit.com" || parsed.hostname === "reddit.com") &&
+        parsed.pathname.endsWith("/")) {
+        parsed.pathname = parsed.pathname.slice(0, -1);
+    }
+    return parsed.toString();
+}
+function normalizeText(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, " ")
+        .trim();
+}
+function uniqueStrings(values) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+function createFingerprint(...parts) {
+    return createHash("sha256").update(parts.join("::"), "utf8").digest("hex");
+}
+//# sourceMappingURL=public-corpus.js.map

package/dist/vendor/cli/ui/error-card.d.ts

@@ -0,0 +1,38 @@
+/**
+ * error-card.ts
+ *
+ * Renders a structured error card to stderr after a fatal CLI failure.
+ * Mirrors the visual language of summary-card.ts (CARD_WIDTH=56, box-drawing).
+ * Respects MARTIN_NO_SUMMARY env var and --json flag.
+ */
+export interface ErrorCardInput {
+    /** Short all-caps machine code, e.g. "BUDGET_EXCEEDED", "CONFIG_NOT_FOUND" */
+    code: string;
+    /** Human-readable one-liner describing what went wrong */
+    message: string;
+    /** Optional recovery suggestion shown below the message */
+    hint?: string;
+    /** Optional key-value detail rows (e.g. { file: "martin.config.yaml", limit: "$0.05" }) */
+    context?: Record<string, string>;
+}
+/**
+ * Returns true when the error card should be rendered.
+ * Mirrors shouldRenderSummaryCard — checks TTY, MARTIN_NO_SUMMARY, --json.
+ */
+export declare function shouldRenderErrorCard(): boolean;
+/**
+ * Renders a box-drawing error card string ready to write to stderr.
+ *
+ * Example output:
+ *   ╔══════════════════════════════════════════════════════╗
+ *   ║  MARTIN ERROR                      [BUDGET_EXCEEDED] ║
+ *   ╠══════════════════════════════════════════════════════╣
+ *   ║  Task cost exceeded configured budget limit.         ║
+ *   ║                                                      ║
+ *   ║  hint: increase budget_limit in martin.config.yaml   ║
+ *   ╠══════════════════════════════════════════════════════╣
+ *   ║  limit          $0.05                                ║
+ *   ║  spent          $0.08                                ║
+ *   ╚══════════════════════════════════════════════════════╝
+ */
+export declare function renderErrorCard(input: ErrorCardInput): string;

package/dist/vendor/cli/ui/error-card.js

@@ -0,0 +1,103 @@
+/**
+ * error-card.ts
+ *
+ * Renders a structured error card to stderr after a fatal CLI failure.
+ * Mirrors the visual language of summary-card.ts (CARD_WIDTH=56, box-drawing).
+ * Respects MARTIN_NO_SUMMARY env var and --json flag.
+ */
+const CARD_WIDTH = 56;
+const INNER_WIDTH = CARD_WIDTH - 4; // 2 border chars + 2 padding spaces
+/**
+ * Returns true when the error card should be rendered.
+ * Mirrors shouldRenderSummaryCard — checks TTY, MARTIN_NO_SUMMARY, --json.
+ */
+export function shouldRenderErrorCard() {
+    if (process.env.MARTIN_NO_SUMMARY === "1")
+        return false;
+    if (!process.stderr.isTTY && process.env.MARTIN_FORCE_SUMMARY !== "1")
+        return false;
+    return true;
+}
+/**
+ * Renders a box-drawing error card string ready to write to stderr.
+ *
+ * Example output:
+ *   ╔══════════════════════════════════════════════════════╗
+ *   ║  MARTIN ERROR                      [BUDGET_EXCEEDED] ║
+ *   ╠══════════════════════════════════════════════════════╣
+ *   ║  Task cost exceeded configured budget limit.         ║
+ *   ║                                                      ║
+ *   ║  hint: increase budget_limit in martin.config.yaml   ║
+ *   ╠══════════════════════════════════════════════════════╣
+ *   ║  limit          $0.05                                ║
+ *   ║  spent          $0.08                                ║
+ *   ╚══════════════════════════════════════════════════════╝
+ */
+export function renderErrorCard(input) {
+    const lines = [];
+    const top = `╔${"═".repeat(CARD_WIDTH - 2)}╗`;
+    const bottom = `╚${"═".repeat(CARD_WIDTH - 2)}╝`;
+    const divider = `╠${"═".repeat(CARD_WIDTH - 2)}╣`;
+    // Header row: "MARTIN ERROR" left, "[CODE]" right
+    const codeTag = `[${truncate(input.code, 20)}]`;
+    const headerLabel = "MARTIN ERROR";
+    const headerGap = INNER_WIDTH - headerLabel.length - codeTag.length;
+    const headerPad = headerGap > 0 ? " ".repeat(headerGap) : " ";
+    lines.push(top);
+    lines.push(`║ ${headerLabel}${headerPad}${codeTag} ║`);
+    lines.push(divider);
+    // Message (word-wrapped to INNER_WIDTH)
+    for (const segment of wrapText(input.message, INNER_WIDTH)) {
+        lines.push(row(segment));
+    }
+    // Hint row
+    if (input.hint !== undefined) {
+        lines.push(row(""));
+        lines.push(row(truncate(`hint: ${input.hint}`, INNER_WIDTH)));
+    }
+    // Context key-value rows
+    const entries = Object.entries(input.context ?? {});
+    if (entries.length > 0) {
+        lines.push(divider);
+        const keyWidth = Math.min(16, Math.max(...entries.map(([k]) => k.length)) + 2);
+        for (const [key, value] of entries) {
+            const paddedKey = key.padEnd(keyWidth);
+            lines.push(row(truncate(`${paddedKey}${value}`, INNER_WIDTH)));
+        }
+    }
+    lines.push(bottom);
+    return lines.join("\n") + "\n";
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function row(content) {
+    const remaining = INNER_WIDTH - content.length;
+    const padding = remaining > 0 ? " ".repeat(remaining) : "";
+    return `║ ${content}${padding} ║`;
+}
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return `${str.slice(0, maxLen - 3)}...`;
+}
+function wrapText(text, maxWidth) {
+    if (text.length <= maxWidth)
+        return [text];
+    const words = text.split(" ");
+    const wrapped = [];
+    let current = "";
+    for (const word of words) {
+        const candidate = current.length === 0 ? word : `${current} ${word}`;
+        if (candidate.length <= maxWidth) {
+            current = candidate;
+        }
+        else {
+            if (current.length > 0)
+                wrapped.push(current);
+            current = truncate(word, maxWidth);
+        }
+    }
+    if (current.length > 0)
+        wrapped.push(current);
+    return wrapped.length > 0 ? wrapped : [""];
+}
+//# sourceMappingURL=error-card.js.map

package/dist/vendor/cli/ui/mission-brief.d.ts

@@ -0,0 +1,41 @@
+/**
+ * mission-brief.ts
+ *
+ * Pre-run gate rendered before any attempt loop starts.
+ *
+ * Displays blast radius, trust calibration, and budget so the user can
+ * abort before spending a single token. High-risk runs require explicit
+ * confirmation ("proceed") to prevent accidental expensive jobs.
+ *
+ * Skip conditions:
+ *   MARTIN_NO_BRIEF=1  env var — always skip (CI/automation)
+ *   --yes / -y flag    — skip interactive prompt, still print the brief
+ *   --json flag        — suppress entirely (piped usage)
+ *   non-TTY stdin      — suppress unless MARTIN_FORCE_BRIEF=1; prompt never waits
+ *
+ * The brief is written to stderr so stdout stays JSON-clean. Interactivity is
+ * based on stdin for input safety and stderr for display capability.
+ */
+import type { BlastRadiusResult } from "../../core/index.js";
+import type { ModelTrustProfile } from "../../core/index.js";
+import type { LoopBudget } from "../../contracts/index.js";
+export interface MissionBriefInput {
+    objective: string;
+    budget: LoopBudget;
+    blast: BlastRadiusResult;
+    /** Best trust profile for the likely model, if calibration has enough data */
+    trustProfile?: ModelTrustProfile | null;
+    /** Model selected by the router (may differ from trust profile) */
+    selectedModel?: string;
+}
+export declare function shouldRenderMissionBrief(args: string[]): boolean;
+export declare function renderMissionBrief(input: MissionBriefInput): string;
+/**
+ * Awaits user confirmation before a run starts.
+ *
+ * - High-risk runs require typing "proceed" exactly.
+ * - Normal runs accept any input (Enter key).
+ * - Returns false if the user aborts or times out (30s).
+ * - In non-TTY or when skip=true, returns true immediately.
+ */
+export declare function awaitMissionBriefConfirmation(blast: BlastRadiusResult, skip: boolean): Promise<boolean>;

package/dist/vendor/cli/ui/mission-brief.js

@@ -0,0 +1,173 @@
+/**
+ * mission-brief.ts
+ *
+ * Pre-run gate rendered before any attempt loop starts.
+ *
+ * Displays blast radius, trust calibration, and budget so the user can
+ * abort before spending a single token. High-risk runs require explicit
+ * confirmation ("proceed") to prevent accidental expensive jobs.
+ *
+ * Skip conditions:
+ *   MARTIN_NO_BRIEF=1  env var — always skip (CI/automation)
+ *   --yes / -y flag    — skip interactive prompt, still print the brief
+ *   --json flag        — suppress entirely (piped usage)
+ *   non-TTY stdin      — suppress unless MARTIN_FORCE_BRIEF=1; prompt never waits
+ *
+ * The brief is written to stderr so stdout stays JSON-clean. Interactivity is
+ * based on stdin for input safety and stderr for display capability.
+ */
+const CARD_WIDTH = 58;
+const INNER_WIDTH = CARD_WIDTH - 4;
+export function shouldRenderMissionBrief(args) {
+    if (process.env.MARTIN_NO_BRIEF === "1")
+        return false;
+    if (args.includes("--json"))
+        return false;
+    if (process.env.MARTIN_FORCE_BRIEF === "1")
+        return true;
+    if (!process.stdin.isTTY)
+        return false;
+    if (!process.stderr.isTTY)
+        return false;
+    return true;
+}
+export function renderMissionBrief(input) {
+    const { objective, budget, blast, trustProfile, selectedModel } = input;
+    const top = `╔${"═".repeat(CARD_WIDTH - 2)}╗`;
+    const bottom = `╚${"═".repeat(CARD_WIDTH - 2)}╝`;
+    const divider = `╠${"═".repeat(CARD_WIDTH - 2)}╣`;
+    const riskLabel = blast.regressionRisk === "high"
+        ? "HIGH RISK"
+        : blast.regressionRisk === "medium"
+            ? "Medium risk"
+            : "Low risk";
+    const blastStr = `${blast.score}/100 · ${riskLabel}`;
+    const budgetStr = `$${budget.maxUsd.toFixed(2)} · ${budget.maxIterations ?? 5} iterations max`;
+    const lines = [];
+    lines.push(top);
+    lines.push(row("Martin Loop — Mission Brief"));
+    lines.push(divider);
+    lines.push(row(`Task      ${truncate(objective, INNER_WIDTH - 10)}`));
+    const modelLabel = selectedModel ?? trustProfile?.model ?? "auto-selected";
+    const modelSuffix = trustProfile
+        ? ` (${Math.round(trustProfile.efficiencyScore * 100)}% efficiency · ${trustProfile.runsObserved} runs)`
+        : "";
+    lines.push(row(`Engine    ${truncate(modelLabel + modelSuffix, INNER_WIDTH - 10)}`));
+    lines.push(row(`Budget    ${budgetStr}`));
+    lines.push(row(`Blast     ${blastStr}`));
+    if (blast.regressionRisk === "high" && blast.hotspotsInPath.length > 0) {
+        lines.push(divider);
+        for (const file of blast.hotspotsInPath.slice(0, 3)) {
+            lines.push(row(`  Hotspot: ${truncate(file, INNER_WIDTH - 12)}`));
+        }
+        if (blast.hotspotsInPath.length > 3) {
+            lines.push(row(`  + ${blast.hotspotsInPath.length - 3} more hotspot files`));
+        }
+    }
+    if (blast.rationale) {
+        lines.push(divider);
+        const parts = blast.rationale.split("; ");
+        for (const part of parts.slice(0, 2)) {
+            lines.push(row(`  ${truncate(part, INNER_WIDTH - 2)}`));
+        }
+    }
+    lines.push(divider);
+    if (blast.regressionRisk === "high") {
+        lines.push(row(`  Blast score ${blast.score}/100. Type "proceed" to continue.`));
+    }
+    else {
+        lines.push(row(`  Press Enter to proceed or Ctrl+C to abort.`));
+    }
+    lines.push(bottom);
+    return lines.join("\n");
+}
+/**
+ * Awaits user confirmation before a run starts.
+ *
+ * - High-risk runs require typing "proceed" exactly.
+ * - Normal runs accept any input (Enter key).
+ * - Returns false if the user aborts or times out (30s).
+ * - In non-TTY or when skip=true, returns true immediately.
+ */
+export async function awaitMissionBriefConfirmation(blast, skip) {
+    if (skip || !process.stdin.isTTY)
+        return true;
+    const isHighRisk = blast.regressionRisk === "high";
+    return new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            process.stderr.write("\nNo response — aborting run to protect budget.\n");
+            resolve(false);
+        }, 30_000);
+        function cleanup() {
+            clearTimeout(timeout);
+            process.stdin.setRawMode?.(false);
+            process.stdin.pause();
+            process.stdin.removeListener("data", onData);
+        }
+        let buffer = "";
+        function onData(chunk) {
+            const text = chunk.toString();
+            // Ctrl+C — abort
+            if (text === "\x03") {
+                process.stderr.write("\nAborted.\n");
+                cleanup();
+                resolve(false);
+                return;
+            }
+            if (isHighRisk) {
+                // Accumulate typed characters, echo them, check for Enter
+                for (const ch of text) {
+                    if (ch === "\r" || ch === "\n") {
+                        process.stderr.write("\n");
+                        const confirmed = buffer.trim().toLowerCase() === "proceed";
+                        if (!confirmed) {
+                            process.stderr.write(`Type "proceed" to confirm, or Ctrl+C to abort.\n`);
+                            buffer = "";
+                        }
+                        else {
+                            cleanup();
+                            resolve(true);
+                        }
+                    }
+                    else if (ch === "\x7f" && buffer.length > 0) {
+                        buffer = buffer.slice(0, -1);
+                        process.stderr.write("\b \b");
+                    }
+                    else {
+                        buffer += ch;
+                        process.stderr.write(ch);
+                    }
+                }
+            }
+            else {
+                // Any key (Enter) proceeds
+                cleanup();
+                resolve(true);
+            }
+        }
+        try {
+            process.stdin.setRawMode?.(true);
+        }
+        catch {
+            // setRawMode not available (e.g. Windows without a pty)
+        }
+        process.stdin.resume();
+        process.stdin.on("data", onData);
+        if (isHighRisk) {
+            process.stderr.write('\n> ');
+        }
+    });
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function row(content) {
+    const remaining = CARD_WIDTH - 4 - content.length;
+    const padding = remaining > 0 ? " ".repeat(remaining) : "";
+    return `║ ${content}${padding} ║`;
+}
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return `${str.slice(0, maxLen - 3)}...`;
+}
+//# sourceMappingURL=mission-brief.js.map

package/dist/vendor/cli/ui/summary-card.d.ts

@@ -0,0 +1,34 @@
+/**
+ * summary-card.ts
+ *
+ * Renders a human-readable run summary card to stdout after every martin run.
+ * Respects --json flag and MARTIN_NO_SUMMARY env var.
+ * Width: 56 chars to fit any terminal >= 60 cols.
+ */
+export interface RunSummaryInput {
+    succeeded: boolean;
+    loopId: string;
+    objective: string;
+    attemptCount: number;
+    maxAttempts: number;
+    grade?: string;
+    groundingScore?: number;
+    modelName?: string;
+    probeTier?: string;
+    costUsd: number;
+    probeCostUsd?: number;
+    durationMs: number;
+    lastBlockReason?: string;
+    rollbackComplete?: boolean;
+    /** Router cost telemetry — populated when MartinRouter is active */
+    routerSelectedModel?: string;
+    routerCostPer1kTcs?: number;
+    routerTrustTier?: "high" | "medium" | "low";
+    /**
+     * Estimated blast radius of the executed action on a 0–100 scale.
+     * Display + telemetry only in Phase 32 — no gate enforcement until Phase 33.
+     */
+    blastRadius?: number;
+}
+export declare function shouldRenderSummaryCard(args: string[]): boolean;
+export declare function renderSummaryCard(input: RunSummaryInput): string;