martin-loop 0.1.4 → 1.3.0

package/dist/vendor/core/context-utility.js

@@ -0,0 +1,405 @@
+const CONTRACT_WEIGHT = 0.22;
+const GUIDANCE_WEIGHT = 0.18;
+const MEMORY_WEIGHT = 0.16;
+const VERIFICATION_WEIGHT = 0.20;
+const ANOMALY_WEIGHT = 0.14;
+const SURFACE_WEIGHT = 0.10;
+export function computeContextUtilityScore(input) {
+    const compiledContext = normalizePromptPacket(input.compiledContext);
+    const verification = resolveVerificationCounts(compiledContext, input.verificationPlan);
+    const anomalies = resolvePatterns(input.patterns);
+    const scopeSurface = resolveScopeSurface(input.scopeSurface);
+    const memoryEntries = compiledContext.memoryBrief?.entries ?? [];
+    const memoryDecisions = scoreMemoryEntries(compiledContext, memoryEntries);
+    const retainedMemory = memoryDecisions.filter((decision) => decision.utility >= 55);
+    const evictableMemory = memoryDecisions.filter((decision) => decision.utility < 40);
+    const sectionScores = {
+        contract: scoreContract(compiledContext),
+        guidance: scoreGuidance(compiledContext),
+        memory: scoreMemory(memoryDecisions),
+        verification: scoreVerification(verification),
+        anomalyGuards: scoreAnomalyGuards(anomalies.length),
+        surfaceFocus: scoreSurfaceFocus(scopeSurface.touchedSurfaces.length)
+    };
+    const utilityScore = Math.round(sectionScores.contract * CONTRACT_WEIGHT +
+        sectionScores.guidance * GUIDANCE_WEIGHT +
+        sectionScores.memory * MEMORY_WEIGHT +
+        sectionScores.verification * VERIFICATION_WEIGHT +
+        sectionScores.anomalyGuards * ANOMALY_WEIGHT +
+        sectionScores.surfaceFocus * SURFACE_WEIGHT);
+    const utilityBand = classifyUtilityBand(utilityScore);
+    const evidenceCounts = {
+        memoryEntryCount: memoryEntries.length,
+        retainedMemoryCount: retainedMemory.length,
+        evictableMemoryCount: evictableMemory.length,
+        priorFailurePatternCount: compiledContext.priorFailurePatterns.length,
+        anomalyCount: anomalies.length,
+        requiredCheckCount: verification.requiredCheckCount,
+        optionalCheckCount: verification.optionalCheckCount,
+        touchedSurfaceCount: scopeSurface.touchedSurfaces.length,
+        changedFileCount: scopeSurface.changedFileCount,
+        acceptanceCriteriaCount: compiledContext.contract.acceptanceCriteria?.length ?? 0
+    };
+    const actions = buildContextUtilityActions({
+        utilityScore,
+        utilityBand,
+        verification,
+        anomalyCount: anomalies.length,
+        touchedSurfaceCount: scopeSurface.touchedSurfaces.length,
+        retainedMemory,
+        evictableMemory
+    });
+    return {
+        schemaVersion: "martin.context-utility-score.v1",
+        attemptIndex: input.attemptIndex,
+        utilityScore,
+        utilityBand,
+        summary: buildSummary({
+            utilityScore,
+            utilityBand,
+            anomalyCount: anomalies.length,
+            evictableMemoryCount: evictableMemory.length,
+            shouldCompress: actions.some((action) => action.type === "compress_context")
+        }),
+        sectionScores,
+        actions,
+        evidenceCounts
+    };
+}
+function classifyUtilityBand(score) {
+    if (score >= 75) {
+        return "high";
+    }
+    if (score >= 50) {
+        return "medium";
+    }
+    return "low";
+}
+function normalizePromptPacket(compiledContext) {
+    const packet = isRecord(compiledContext) ? compiledContext : {};
+    const contract = isRecord(packet["contract"]) ? packet["contract"] : {};
+    const memoryBrief = isRecord(packet["memoryBrief"])
+        ? packet["memoryBrief"]
+        : undefined;
+    const budgetEnvelope = isRecord(packet["budgetEnvelope"])
+        ? packet["budgetEnvelope"]
+        : {};
+    const allowedPaths = readStringArray(contract["allowedPaths"]);
+    const deniedPaths = readStringArray(contract["deniedPaths"]);
+    const acceptanceCriteria = readStringArray(contract["acceptanceCriteria"]);
+    const entries = normalizeMemoryRecallEntries(memoryBrief?.["entries"]);
+    return {
+        loopId: readString(packet["loopId"]) ?? "unknown-loop",
+        attemptNumber: readFiniteNumber(packet["attemptNumber"]),
+        contract: {
+            objective: readString(contract["objective"]) ?? "",
+            verificationPlan: readStringArray(contract["verificationPlan"]),
+            ...(allowedPaths.length > 0 ? { allowedPaths } : {}),
+            ...(deniedPaths.length > 0 ? { deniedPaths } : {}),
+            ...(acceptanceCriteria.length > 0 ? { acceptanceCriteria } : {})
+        },
+        priorFailurePatterns: readStringArray(packet["priorFailurePatterns"]),
+        ...(memoryBrief
+            ? {
+                memoryBrief: {
+                    wingKey: readString(memoryBrief["wingKey"]) ?? "",
+                    recalledAt: readString(memoryBrief["recalledAt"]) ?? "",
+                    entries
+                }
+            }
+            : {}),
+        guidance: readString(packet["guidance"]) ?? "",
+        budgetEnvelope: {
+            remainingBudgetUsd: readFiniteNumber(budgetEnvelope["remainingBudgetUsd"]),
+            remainingIterations: readFiniteNumber(budgetEnvelope["remainingIterations"]),
+            remainingTokens: readFiniteNumber(budgetEnvelope["remainingTokens"])
+        }
+    };
+}
+function normalizeMemoryRecallEntries(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((entry, index) => {
+        const normalizedEntry = isRecord(entry) ? entry : {};
+        const sourceAttemptIndex = normalizedEntry["sourceAttemptIndex"];
+        return {
+            drawerId: readString(normalizedEntry["drawerId"]) ?? `memory-${String(index + 1)}`,
+            roomKey: readString(normalizedEntry["roomKey"]) ?? "",
+            lesson: readString(normalizedEntry["lesson"]) ?? "",
+            content: readString(normalizedEntry["content"]) ?? "",
+            sourceRunId: readString(normalizedEntry["sourceRunId"]) ?? "",
+            ...(typeof sourceAttemptIndex === "number" && Number.isFinite(sourceAttemptIndex)
+                ? { sourceAttemptIndex }
+                : {}),
+            score: readFiniteNumber(normalizedEntry["score"]),
+            reason: readString(normalizedEntry["reason"]) ?? ""
+        };
+    });
+}
+function scoreContract(compiledContext) {
+    const boundaryCount = [
+        compiledContext.contract.allowedPaths?.length ? 1 : 0,
+        compiledContext.contract.deniedPaths?.length ? 1 : 0,
+        compiledContext.contract.acceptanceCriteria?.length ? 1 : 0
+    ].reduce((sum, value) => sum + value, 0);
+    return clampScore((compiledContext.contract.objective.trim().length > 0 ? 40 : 0) +
+        Math.min(compiledContext.contract.verificationPlan.length, 3) * 15 +
+        boundaryCount * 5);
+}
+function scoreGuidance(compiledContext) {
+    const guidance = compiledContext.guidance.toLowerCase();
+    let score = guidance.trim().length > 0 ? 25 : 0;
+    if (guidance.includes("allowed paths")) {
+        score += 15;
+    }
+    if (guidance.includes("denied paths")) {
+        score += 10;
+    }
+    if (guidance.includes("prior failure patterns")) {
+        score += 10;
+    }
+    if (guidance.includes("current focus")) {
+        score += 15;
+    }
+    if (compiledContext.guidance.length >= 180) {
+        score += 15;
+    }
+    return clampScore(score);
+}
+function scoreMemory(memoryDecisions) {
+    if (memoryDecisions.length === 0) {
+        return 0;
+    }
+    const total = memoryDecisions.reduce((sum, decision) => sum + decision.utility, 0);
+    return clampScore(Math.round(total / memoryDecisions.length));
+}
+function scoreVerification(counts) {
+    return clampScore(counts.requiredCheckCount * 25 +
+        counts.optionalCheckCount * 8 +
+        (counts.mustPassAll ? 9 : 0) +
+        (counts.hasTieredPlan ? 8 : 0));
+}
+function scoreAnomalyGuards(anomalyCount) {
+    return clampScore(100 - anomalyCount * 30);
+}
+function scoreSurfaceFocus(touchedSurfaceCount) {
+    if (touchedSurfaceCount === 0) {
+        return 40;
+    }
+    if (touchedSurfaceCount <= 4) {
+        return 100;
+    }
+    if (touchedSurfaceCount <= 8) {
+        return 70;
+    }
+    if (touchedSurfaceCount <= 12) {
+        return 45;
+    }
+    return 20;
+}
+function buildContextUtilityActions(input) {
+    const actions = [];
+    if (input.retainedMemory.length > 0) {
+        actions.push({
+            type: "retain_memory",
+            priority: "medium",
+            message: "Retain only the highest-signal memory drawers in the active brief.",
+            drawerIds: input.retainedMemory.map((decision) => decision.entry.drawerId)
+        });
+    }
+    if (input.evictableMemory.length > 0) {
+        actions.push({
+            type: "evict_memory",
+            priority: input.utilityBand === "low" ? "high" : "medium",
+            message: "Evict low-value memory drawers from the active context before the next retry.",
+            drawerIds: input.evictableMemory.map((decision) => decision.entry.drawerId)
+        });
+    }
+    if (input.utilityBand === "low" ||
+        input.anomalyCount >= 3 ||
+        input.touchedSurfaceCount >= 9) {
+        actions.push({
+            type: "compress_context",
+            priority: "high",
+            message: "Compress the active context to the contract, retained memory drawers, latest verifier evidence, and touched surfaces only."
+        });
+    }
+    if (input.verification.requiredCheckCount === 0 || input.verification.optionalCheckCount === 0) {
+        actions.push({
+            type: "refresh_verification",
+            priority: input.verification.requiredCheckCount === 0 ? "high" : "medium",
+            message: "Refresh the verification plan so the next attempt has explicit required checks before any completion claim."
+        });
+    }
+    if (input.anomalyCount > 0) {
+        actions.push({
+            type: "investigate_anomalies",
+            priority: input.anomalyCount >= 2 ? "high" : "medium",
+            message: "Inspect the latest anomaly evidence before retrying so the loop does not reuse a drifting or contradictory context frame."
+        });
+    }
+    if (input.touchedSurfaceCount >= 9) {
+        actions.push({
+            type: "narrow_surfaces",
+            priority: "medium",
+            message: "Narrow the next patch to the minimum changed surfaces because the current context spans too many files."
+        });
+    }
+    return actions;
+}
+function buildSummary(input) {
+    if (input.utilityBand === "low") {
+        return `Low context utility (${String(input.utilityScore)}/100). Compress the active context, refresh verification focus, and evict ${String(input.evictableMemoryCount)} stale memory drawer(s) before retrying.`;
+    }
+    if (input.utilityBand === "medium") {
+        return `Medium context utility (${String(input.utilityScore)}/100). Keep the contract and verification cues, prune ${String(input.evictableMemoryCount)} stale memory drawer(s), and review ${String(input.anomalyCount)} anomaly guard(s).`;
+    }
+    const anomalyNote = input.anomalyCount > 0
+        ? `review ${String(input.anomalyCount)} anomaly guard(s)`
+        : "keep the current anomaly guard state";
+    return `High context utility (${String(input.utilityScore)}/100). Contract and verification signals are strong; retain the best memory cues, evict ${String(input.evictableMemoryCount)} stale drawer(s), and ${anomalyNote}.`;
+}
+function resolveVerificationCounts(compiledContext, verificationPlan) {
+    const requiredFromArtifact = collectCheckCount(verificationPlan, [
+        "requiredVerifiers",
+        "requiredChecks",
+        "required",
+        "mustRun",
+        "verificationPlan"
+    ]);
+    const optionalFromArtifact = collectCheckCount(verificationPlan, [
+        "optionalChecks",
+        "optionalVerifiers",
+        "optional",
+        "recommendedVerifiers",
+        "fallbackVerifiers"
+    ]);
+    const requiredCheckCount = requiredFromArtifact > 0
+        ? requiredFromArtifact
+        : compiledContext.contract.verificationPlan.length;
+    const optionalCheckCount = optionalFromArtifact;
+    return {
+        requiredCheckCount,
+        optionalCheckCount,
+        hasTieredPlan: isRecord(verificationPlan) &&
+            typeof verificationPlan["tier"] === "string",
+        mustPassAll: isRecord(verificationPlan) &&
+            verificationPlan["mustPassAll"] === true
+    };
+}
+function resolvePatterns(patterns) {
+    if (Array.isArray(patterns)) {
+        return patterns.filter(isPatternDetection);
+    }
+    if (isRecord(patterns) && Array.isArray(patterns["patterns"])) {
+        return patterns["patterns"].filter(isPatternDetection);
+    }
+    return [];
+}
+function resolveScopeSurface(scopeSurface) {
+    if (!isRecord(scopeSurface)) {
+        return {
+            touchedSurfaces: [],
+            changedFileCount: 0
+        };
+    }
+    const touchedSurfaces = uniqueNormalizedPaths([
+        ...readStringArray(scopeSurface["allChangedPaths"]),
+        ...readStringArray(scopeSurface["trackedChangedPaths"]),
+        ...readStringArray(scopeSurface["deletedPaths"]),
+        ...readStringArray(scopeSurface["newUntrackedPaths"])
+    ]);
+    const diffStats = isRecord(scopeSurface["diffStats"]) ? scopeSurface["diffStats"] : undefined;
+    const changedFileCount = typeof diffStats?.["filesChanged"] === "number"
+        ? diffStats["filesChanged"]
+        : touchedSurfaces.length;
+    return {
+        touchedSurfaces,
+        changedFileCount
+    };
+}
+function scoreMemoryEntries(compiledContext, entries) {
+    const promptTokens = buildPromptTokens(compiledContext);
+    return entries.map((entry) => {
+        let utility = Math.min(Math.max(entry.score, 0), 60);
+        const reason = entry.reason.toLowerCase();
+        if (reason.includes("matched failure class")) {
+            utility += 20;
+        }
+        if (reason.includes("matched intervention")) {
+            utility += 10;
+        }
+        const overlap = countIntersection(promptTokens, buildEntryTokens(entry));
+        utility += overlap * 6;
+        return {
+            entry,
+            utility: clampScore(utility)
+        };
+    });
+}
+function buildPromptTokens(compiledContext) {
+    return uniqueTokens([
+        ...tokenize(compiledContext.contract.objective),
+        ...compiledContext.contract.verificationPlan.flatMap((command) => tokenize(command)),
+        ...tokenize(compiledContext.guidance),
+        ...compiledContext.priorFailurePatterns.flatMap((pattern) => tokenize(pattern))
+    ]);
+}
+function buildEntryTokens(entry) {
+    return uniqueTokens([
+        ...tokenize(entry.roomKey),
+        ...tokenize(entry.lesson),
+        ...tokenize(entry.content),
+        ...tokenize(entry.reason)
+    ]);
+}
+function collectCheckCount(value, keys) {
+    if (Array.isArray(value)) {
+        return value.length;
+    }
+    if (!isRecord(value)) {
+        return 0;
+    }
+    return keys.reduce((sum, key) => {
+        const next = value[key];
+        return sum + (Array.isArray(next) ? next.length : 0);
+    }, 0);
+}
+function isPatternDetection(value) {
+    return (isRecord(value) &&
+        typeof value["attemptId"] === "string" &&
+        typeof value["patternId"] === "string" &&
+        typeof value["message"] === "string");
+}
+function readStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+        : [];
+}
+function readString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function readFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function tokenize(value) {
+    return (value.toLowerCase().match(/[a-z0-9_/-]{3,}/g) ?? []).filter((token) => token.trim().length > 0);
+}
+function uniqueTokens(values) {
+    return [...new Set(values)];
+}
+function uniqueNormalizedPaths(paths) {
+    return [...new Set(paths.map((path) => path.replace(/\\/g, "/").replace(/^\.\//u, "")))].sort();
+}
+function countIntersection(left, right) {
+    const rightSet = new Set(right);
+    return left.filter((token) => rightSet.has(token)).length;
+}
+function clampScore(value) {
+    return Math.max(0, Math.min(100, Math.round(value)));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=context-utility.js.map

package/dist/vendor/core/cost/pipeline.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Composable cost-aware LLM pipeline.
+ *
+ * Combines four patterns into one composable function:
+ *   1. Model routing by task complexity (Haiku vs Sonnet)
+ *   2. Immutable cost tracking with budget enforcement
+ *   3. Narrow retry logic (transient errors only, exponential backoff)
+ *   4. Prompt caching via Anthropic cache_control messages
+ *
+ * Does NOT import @anthropic-ai/sdk — uses an injected LlmClient interface
+ * so it works with the claude-cli adapter or any HTTP client.
+ */
+export declare const MODEL_HAIKU: "claude-haiku-4-5-20251001";
+export declare const MODEL_SONNET: "claude-sonnet-4-6";
+export type SupportedModel = typeof MODEL_HAIKU | typeof MODEL_SONNET;
+/**
+ * Select the cheapest model that can handle the task complexity.
+ * Returns forceModel unchanged when provided.
+ */
+export declare function selectModel(textLength: number, itemCount: number, forceModel?: string): string;
+export interface CostRecord {
+    readonly model: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly costUsd: number;
+    readonly timestamp: string;
+}
+export interface CostTracker {
+    readonly budgetLimitUsd: number;
+    readonly records: readonly CostRecord[];
+    readonly totalCost: number;
+    readonly overBudget: boolean;
+}
+export declare function createCostTracker(budgetLimitUsd: number): CostTracker;
+export declare function addCostRecord(tracker: CostTracker, record: Omit<CostRecord, "timestamp">): CostTracker;
+export interface RetryOptions {
+    readonly maxRetries?: number;
+    readonly baseDelayMs?: number;
+}
+export declare function callWithRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+export interface CacheControlEphemeral {
+    readonly type: "ephemeral";
+}
+export interface TextBlockWithCache {
+    readonly type: "text";
+    readonly text: string;
+    readonly cache_control: CacheControlEphemeral;
+}
+export interface SystemMessage {
+    readonly role: "system";
+    readonly content: readonly [TextBlockWithCache];
+}
+export interface UserMessage {
+    readonly role: "user";
+    readonly content: string;
+}
+export type CachedMessageArray = readonly [SystemMessage, UserMessage];
+export declare function buildCachedMessages(systemPrompt: string, userInput: string): CachedMessageArray;
+export interface LlmCallResult {
+    readonly content: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly costUsd: number;
+}
+export interface LlmClient {
+    call(model: string, messages: CachedMessageArray, options?: {
+        maxTokens?: number;
+    }): Promise<LlmCallResult>;
+}
+export interface PipelineConfig {
+    readonly forceModel?: string;
+    readonly maxRetries?: number;
+    readonly baseDelayMs?: number;
+    readonly maxTokens?: number;
+}
+export interface PipelineInput {
+    readonly text: string;
+    readonly config?: PipelineConfig;
+    readonly tracker: CostTracker;
+    readonly client: LlmClient;
+    readonly systemPrompt: string;
+}
+export interface PipelineOutput {
+    readonly result: LlmCallResult;
+    readonly tracker: CostTracker;
+}
+export declare class BudgetExceededError extends Error {
+    readonly totalCost: number;
+    readonly budgetLimit: number;
+    constructor(totalCost: number, budgetLimit: number);
+}
+export declare function runCostAwarePipeline(input: PipelineInput): Promise<PipelineOutput>;

package/dist/vendor/core/cost/pipeline.js

@@ -0,0 +1,141 @@
+/**
+ * Composable cost-aware LLM pipeline.
+ *
+ * Combines four patterns into one composable function:
+ *   1. Model routing by task complexity (Haiku vs Sonnet)
+ *   2. Immutable cost tracking with budget enforcement
+ *   3. Narrow retry logic (transient errors only, exponential backoff)
+ *   4. Prompt caching via Anthropic cache_control messages
+ *
+ * Does NOT import @anthropic-ai/sdk — uses an injected LlmClient interface
+ * so it works with the claude-cli adapter or any HTTP client.
+ */
+// ---------------------------------------------------------------------------
+// Model constants
+// ---------------------------------------------------------------------------
+export const MODEL_HAIKU = "claude-haiku-4-5-20251001";
+export const MODEL_SONNET = "claude-sonnet-4-6";
+const COMPLEXITY_CHAR_THRESHOLD = 10_000;
+const COMPLEXITY_ITEM_THRESHOLD = 30;
+// Private pricing for budget preflight estimation only.
+// Canonical pricing lives in packages/adapters/src/usage.ts.
+const PIPELINE_PRICING = {
+    [MODEL_HAIKU]: { inputPer1K: 0.00025, outputPer1K: 0.00125 },
+    [MODEL_SONNET]: { inputPer1K: 0.003, outputPer1K: 0.015 }
+};
+const FALLBACK_PRICING = { inputPer1K: 0.003, outputPer1K: 0.015 };
+// ---------------------------------------------------------------------------
+// 1. Model routing
+// ---------------------------------------------------------------------------
+/**
+ * Select the cheapest model that can handle the task complexity.
+ * Returns forceModel unchanged when provided.
+ */
+export function selectModel(textLength, itemCount, forceModel) {
+    if (forceModel !== undefined)
+        return forceModel;
+    if (textLength >= COMPLEXITY_CHAR_THRESHOLD || itemCount >= COMPLEXITY_ITEM_THRESHOLD) {
+        return MODEL_SONNET;
+    }
+    return MODEL_HAIKU;
+}
+export function createCostTracker(budgetLimitUsd) {
+    return makeFrozenTracker(budgetLimitUsd, []);
+}
+export function addCostRecord(tracker, record) {
+    const full = Object.freeze({
+        ...record,
+        timestamp: new Date().toISOString()
+    });
+    return makeFrozenTracker(tracker.budgetLimitUsd, [...tracker.records, full]);
+}
+function makeFrozenTracker(budgetLimitUsd, records) {
+    const totalCost = records.reduce((sum, r) => sum + r.costUsd, 0);
+    return Object.freeze({
+        budgetLimitUsd,
+        records: Object.freeze(records),
+        totalCost,
+        overBudget: totalCost > budgetLimitUsd
+    });
+}
+function classifyError(err) {
+    const msg = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase();
+    if (/econnreset|etimedout|enotfound|econnrefused|socket hang up/.test(msg))
+        return "retryable";
+    if (/429|rate.limit|too.many.requests/.test(msg))
+        return "retryable";
+    if (/5\d{2}|internal.server.error|overloaded/.test(msg))
+        return "retryable";
+    return "fatal";
+}
+export async function callWithRetry(fn, options = {}) {
+    const maxRetries = options.maxRetries ?? 3;
+    const baseDelayMs = options.baseDelayMs ?? 1_000;
+    let lastErr;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (classifyError(err) === "fatal")
+                throw err;
+            lastErr = err;
+            if (attempt < maxRetries - 1) {
+                const delay = Math.min(baseDelayMs * Math.pow(2, attempt), 32_000);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+    }
+    throw lastErr;
+}
+export function buildCachedMessages(systemPrompt, userInput) {
+    const systemMsg = Object.freeze({
+        role: "system",
+        content: Object.freeze([
+            Object.freeze({
+                type: "text",
+                text: systemPrompt,
+                cache_control: Object.freeze({ type: "ephemeral" })
+            })
+        ])
+    });
+    const userMsg = Object.freeze({
+        role: "user",
+        content: userInput
+    });
+    return Object.freeze([systemMsg, userMsg]);
+}
+export class BudgetExceededError extends Error {
+    totalCost;
+    budgetLimit;
+    constructor(totalCost, budgetLimit) {
+        super(`Budget exceeded: spent $${totalCost.toFixed(4)} of $${budgetLimit.toFixed(4)}`);
+        this.totalCost = totalCost;
+        this.budgetLimit = budgetLimit;
+        this.name = "BudgetExceededError";
+    }
+}
+export async function runCostAwarePipeline(input) {
+    const { text, config, tracker, client, systemPrompt } = input;
+    const itemCount = text.split("\n").length;
+    const model = selectModel(text.length, itemCount, config?.forceModel);
+    // Preflight budget check: estimate cost before spending
+    const estimatedInputTokens = Math.ceil(text.length / 3.5);
+    const estimatedOutputTokens = 500;
+    const pricing = PIPELINE_PRICING[model] ?? FALLBACK_PRICING;
+    const estimatedCost = (estimatedInputTokens / 1000) * pricing.inputPer1K +
+        (estimatedOutputTokens / 1000) * pricing.outputPer1K;
+    if (tracker.totalCost + estimatedCost > tracker.budgetLimitUsd) {
+        throw new BudgetExceededError(tracker.totalCost, tracker.budgetLimitUsd);
+    }
+    const messages = buildCachedMessages(systemPrompt, text);
+    const result = await callWithRetry(() => client.call(model, messages, { maxTokens: config?.maxTokens }), { maxRetries: config?.maxRetries, baseDelayMs: config?.baseDelayMs });
+    const updatedTracker = addCostRecord(tracker, {
+        model,
+        inputTokens: result.inputTokens,
+        outputTokens: result.outputTokens,
+        costUsd: result.costUsd
+    });
+    return { result, tracker: updatedTracker };
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/vendor/core/cost/tagged-cost.d.ts

@@ -0,0 +1,27 @@
+export interface TaggedCostEntry {
+    runId: string;
+    tags: Record<string, string>;
+    totalUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    timestamp: string;
+}
+export interface TaggedCostSummary {
+    tag: string;
+    value: string;
+    totalUsd: number;
+    runCount: number;
+    entries: TaggedCostEntry[];
+}
+/**
+ * Groups cost entries by the value of a specific tag key.
+ * Entries missing the tag key are grouped under "(untagged)".
+ * Results are sorted descending by totalUsd.
+ */
+export declare function aggregateCostsByTag(entries: TaggedCostEntry[], tagKey: string): TaggedCostSummary[];
+/**
+ * Formats a list of TaggedCostSummary objects as a plain-text table.
+ * Columns: tag value | runs | total USD
+ * Sorted descending by totalUsd (aggregateCostsByTag already sorts).
+ */
+export declare function formatCostReport(summaries: TaggedCostSummary[]): string;