martin-loop 0.1.5 → 1.3.0

package/dist/vendor/core/context-flow/sync-preview.js

@@ -0,0 +1,22 @@
+export function buildSyncPreview(input) {
+    const destination = input.destination ?? "martinloop";
+    const mode = input.mode ?? "upsert_account_brief";
+    const contextProfile = destination.toLowerCase().startsWith("martin") ? "martin360_agent_stage" : "generic_agent_small";
+    return {
+        destination,
+        mode,
+        payload: {
+            record_id: input.canonicalRecord.recordId,
+            record_type: input.canonicalRecord.recordType,
+            summary: input.canonicalRecord.summary,
+            fields: input.canonicalRecord.fields,
+            entities: input.canonicalRecord.entities,
+            context_profile: contextProfile
+        },
+        notes: [
+            `Preview builder only: live ${destination} execution depends on a host-wired adapter.`,
+            "This payload is the canonical contract consumed by the Martin360 writeback adapter."
+        ]
+    };
+}
+//# sourceMappingURL=sync-preview.js.map

package/dist/vendor/core/context-flow/token-estimator.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_COST_PER_1K_TOKENS = 0.003;
+export declare function estimateTokens(text: string): number;
+export declare function estimateCostUsd(text: string, costPer1kTokens?: number): number;

package/dist/vendor/core/context-flow/token-estimator.js

@@ -0,0 +1,13 @@
+export const DEFAULT_COST_PER_1K_TOKENS = 0.003;
+export function estimateTokens(text) {
+    const normalized = text.trim();
+    if (!normalized) {
+        return 1;
+    }
+    return Math.max(1, normalized.split(/\s+/).length);
+}
+export function estimateCostUsd(text, costPer1kTokens = DEFAULT_COST_PER_1K_TOKENS) {
+    const tokens = estimateTokens(text);
+    return Number(((tokens / 1000) * costPer1kTokens).toFixed(6));
+}
+//# sourceMappingURL=token-estimator.js.map

package/dist/vendor/core/context-flow/types.d.ts

@@ -0,0 +1,91 @@
+import type { HeadlessProfileName } from "./profiles.js";
+export interface Tenant {
+    tenantId: string;
+    slug: string;
+    name: string;
+    createdAt: string;
+    metadata: Record<string, unknown>;
+}
+export type ApiKeyScope = "ingest" | "compile" | "policy" | "writeback" | "admin";
+export interface ApiKey {
+    apiKeyId: string;
+    tenantId: string;
+    label: string;
+    scopes: ApiKeyScope[];
+    createdAt: string;
+    expiresAt?: string;
+    rotatedAt?: string;
+    revokedAt?: string;
+}
+export interface ProvenanceItem {
+    sourceName: string;
+    evidence: string;
+    charStart?: number;
+    charEnd?: number;
+}
+export interface Entity {
+    type: string;
+    value: string;
+    confidence: number;
+}
+export interface CanonicalRecord {
+    recordId: string;
+    recordType: string;
+    summary: string;
+    fields: Record<string, string>;
+    entities: Entity[];
+    provenance: ProvenanceItem[];
+    metadata: Record<string, unknown>;
+}
+export interface CompileOptions {
+    redactPii: boolean;
+    includeProvenanceSnippets: boolean;
+    deltaMode: boolean;
+    maxTokensOverride?: number;
+}
+export interface QcReport {
+    completenessScore: number;
+    tokenEstimateBefore: number;
+    tokenEstimateAfter: number;
+    tokenReductionPct: number;
+    warnings: string[];
+    keptFields: string[];
+}
+export type PolicySeverity = "low" | "medium" | "high";
+export type PolicyMode = "auto" | "human_review" | "approval_required";
+export interface PolicyDecision {
+    profile: HeadlessProfileName;
+    allowAutonomy: boolean;
+    severity: PolicySeverity;
+    reasons: string[];
+    recommendedMode: PolicyMode;
+    requiresApproval: boolean;
+}
+export interface CompileTrace {
+    compileId: string;
+    policyDecision: PolicyDecision;
+}
+export interface ContextPack {
+    profile: HeadlessProfileName;
+    compiledContext: string;
+    qcReport: QcReport;
+    canonicalRecord: CanonicalRecord;
+    trace: CompileTrace;
+}
+export type SensitivityLevel = "low" | "moderate" | "high";
+export interface SensitivityClassification {
+    level: SensitivityLevel;
+    reasons: string[];
+    matchedEntityTypes: string[];
+}
+export interface SyncPreviewInput {
+    destination?: string;
+    canonicalRecord: CanonicalRecord;
+    mode?: string;
+}
+export interface SyncPreviewResponse {
+    destination: string;
+    mode: string;
+    payload: Record<string, unknown>;
+    notes: string[];
+}

package/dist/vendor/core/context-flow/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/vendor/core/context-utility.d.ts

@@ -0,0 +1,47 @@
+import type { PromptPacket } from "./compiler.js";
+export type ContextUtilityBand = "low" | "medium" | "high";
+export type ContextUtilityActionType = "compress_context" | "retain_memory" | "evict_memory" | "refresh_verification" | "investigate_anomalies" | "narrow_surfaces";
+export interface ContextUtilityAction {
+    type: ContextUtilityActionType;
+    priority: "high" | "medium" | "low";
+    message: string;
+    drawerIds?: string[];
+}
+export interface ContextUtilitySectionScores {
+    contract: number;
+    guidance: number;
+    memory: number;
+    verification: number;
+    anomalyGuards: number;
+    surfaceFocus: number;
+}
+export interface ContextUtilityEvidenceCounts {
+    memoryEntryCount: number;
+    retainedMemoryCount: number;
+    evictableMemoryCount: number;
+    priorFailurePatternCount: number;
+    anomalyCount: number;
+    requiredCheckCount: number;
+    optionalCheckCount: number;
+    touchedSurfaceCount: number;
+    changedFileCount: number;
+    acceptanceCriteriaCount: number;
+}
+export interface ContextUtilityScoreArtifact {
+    schemaVersion: "martin.context-utility-score.v1";
+    attemptIndex: number;
+    utilityScore: number;
+    utilityBand: ContextUtilityBand;
+    summary: string;
+    sectionScores: ContextUtilitySectionScores;
+    actions: ContextUtilityAction[];
+    evidenceCounts: ContextUtilityEvidenceCounts;
+}
+export interface ComputeContextUtilityScoreInput {
+    attemptIndex: number;
+    compiledContext: PromptPacket;
+    verificationPlan?: unknown;
+    patterns?: unknown;
+    scopeSurface?: unknown;
+}
+export declare function computeContextUtilityScore(input: ComputeContextUtilityScoreInput): ContextUtilityScoreArtifact;

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