@warlock.js/ai 4.4.0 → 4.6.0

package/esm/index.mjs

@@ -1,6 +1,7 @@
 import { AIError } from "./errors/ai-error.mjs";
 import { AgentExecutionError } from "./errors/agent-execution-error.mjs";
 import { AgentCancelledError } from "./errors/agent-cancelled-error.mjs";
+import { AgentDriftError } from "./errors/agent-drift-error.mjs";
 import { AgentMaxTripsError } from "./errors/agent-max-trips-error.mjs";
 import { BudgetExceededError } from "./errors/budget-exceeded-error.mjs";
 import { ProviderError } from "./errors/provider-error.mjs";
@@ -16,8 +17,10 @@ import { OrchestratorFailedError } from "./errors/orchestrator-failed-error.mjs"
 import { OrchestratorCancelledError } from "./errors/orchestrator-cancelled-error.mjs";
 import { OrchestratorConfigError } from "./errors/orchestrator-config-error.mjs";
 import { OrchestratorDriftError } from "./errors/orchestrator-drift-error.mjs";
+import { OutboundPolicyError } from "./errors/outbound-policy-error.mjs";
 import { PlannerFailedError } from "./errors/planner-failed-error.mjs";
 import { PlannerCancelledError } from "./errors/planner-cancelled-error.mjs";
+import { PlannerDriftError } from "./errors/planner-drift-error.mjs";
 import { PlannerPlanInvalidError } from "./errors/planner-plan-invalid-error.mjs";
 import { ProviderAuthError } from "./errors/provider-auth-error.mjs";
 import { ProviderRateLimitError } from "./errors/provider-rate-limit-error.mjs";
@@ -33,44 +36,100 @@ import { ToolExecutionError } from "./errors/tool-execution-error.mjs";
 import { WorkflowCancelledError } from "./errors/workflow-cancelled-error.mjs";
 import { WorkflowDriftError } from "./errors/workflow-drift-error.mjs";
 import "./errors/index.mjs";
-import { accumulateCost, computeCost } from "./utils/compute-cost.mjs";
+import { accumulateCost, computeCost, mergeUsage } from "./utils/compute-cost.mjs";
 import { extractJsonPayload } from "./utils/extract-json-payload.mjs";
+import { extractJsonLenient } from "./utils/extract-json-lenient.mjs";
 import { generateRunId } from "./utils/generate-run-id.mjs";
 import { extractJsonSchema } from "./utils/json-schema.mjs";
+import { isPrivateOrReservedIp } from "./security/private-ip.mjs";
+import { assertUrlAllowed, fetchTextWithPolicy, guardedFetch, readTextCapped, resolveOutboundPolicy } from "./security/outbound-policy.mjs";
 import { resolveAttachment } from "./utils/resolve-attachment.mjs";
 import { prepareAttachmentPart } from "./utils/prepare-attachment-part.mjs";
+import { captureChildReport, currentRunFrame, withRunFrame, withoutRunFrame } from "./utils/run-context.mjs";
 import { safeJsonParse } from "./utils/safe-json-parse.mjs";
 import { REPORT_SCHEMA_VERSION } from "./contracts/result/base-report.type.mjs";
 import { stampReportLineage } from "./utils/stamp-report-lineage.mjs";
 import { approximateTokenCount } from "./utils/token-count.mjs";
 import "./utils/index.mjs";
 import { judge } from "./eval/judge-scorer.mjs";
+import { diff } from "./eval/regression.mjs";
 import { runEval } from "./eval/eval-runner.mjs";
 import { extractUserText } from "./middleware/utils/extract-user-text.mjs";
 import { namespacedState } from "./middleware/utils/namespaced-state.mjs";
 import { budget, readBudgetFallbackSignal } from "./middleware/builtins/budget.mjs";
-import { guardrail } from "./middleware/builtins/guardrail.mjs";
-import { getAIConfig, resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, setAIConfig } from "./config.mjs";
+import { getAIConfig, onConfigApplied, resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, setAIConfig } from "./config.mjs";
 import { semanticCache } from "./middleware/builtins/semantic-cache.mjs";
 import { composeMiddleware } from "./middleware/helpers/compose.mjs";
 import { forTool } from "./middleware/helpers/for-tool.mjs";
 import { runPipeline } from "./middleware/pipeline.mjs";
 import "./middleware/index.mjs";
+import { getObservers, isObserveAll, registerObserver, setObserveAll } from "./observe/observer-registry.mjs";
+import { resolveObservers } from "./observe/resolve-observers.mjs";
+import { buildCatalog, loadRecord, renderCatalogPrompt, semanticPreselect } from "./skills/catalog.mjs";
 import { tool } from "./tool/tool.mjs";
+import { loadSkillTool } from "./skills/load-skill-tool.mjs";
+import { saveSkillTool } from "./skills/save-skill-tool.mjs";
+import { parseFrontmatter, parseTags } from "./skills/sources/parse-frontmatter.mjs";
+import { directorySource } from "./skills/sources/directory-source.mjs";
+import { storeSource } from "./skills/sources/store-source.mjs";
+import { urlSource } from "./skills/sources/url-source.mjs";
+import { resolveSource } from "./skills/sources/index.mjs";
+import { skills } from "./skills/skills.mjs";
+import { MockSkillsStore } from "./skills/store/mock-skills-store.mjs";
+import { memory as memory$2 } from "./memory/memory.mjs";
+import { proceduralSkillStore } from "./skills/store/procedural-skill-store.mjs";
+import { runReviewGate } from "./skills/review-gate.mjs";
+import "./skills/index.mjs";
 import { executableToTool, isExecutableTool, normalizeAgentTools } from "./tool/executable-as-tool.mjs";
+import { JUDGE_DEFAULT_REPAIR_ATTEMPTS } from "./agent/judge-config.type.mjs";
 import { createAgentStream } from "./agent/agent-stream.mjs";
 import { agent } from "./agent/agent.mjs";
 import { spawnSubAgent } from "./agent/spawn-sub-agent.mjs";
 import "./agent/index.mjs";
 import { batch } from "./batch/batch.mjs";
 import "./batch/index.mjs";
+import { parsePartialJson } from "./object-stream/parse-partial-json.mjs";
+import { collectStreamObject, streamObject } from "./object-stream/stream-object.mjs";
+import "./object-stream/index.mjs";
+import { SSE_DONE, encodeSSE } from "./serve/sse.mjs";
+import { streamToSSE } from "./serve/stream-to-sse.mjs";
+import { serve } from "./serve/serve.mjs";
 import { memory } from "./checkpoint/memory.mjs";
 import { pg } from "./checkpoint/pg.mjs";
 import { redis } from "./checkpoint/redis.mjs";
+import { fromJSON, toJSON } from "./eval/report-json.mjs";
+import { toJUnit } from "./eval/report-junit.mjs";
 import { contains, exact, predicate } from "./eval/scorers.mjs";
+import { dataset } from "./eval/dataset.mjs";
 import { evalScorers } from "./eval/index.mjs";
-import { memory as memory$1 } from "./memory/memory.mjs";
+import { ApprovalRejectedError, InterruptSuspendedError } from "./human/errors.mjs";
+import { evaluatePolicy } from "./human/policy.mjs";
+import { humanApproval } from "./human/human-approval.mjs";
+import { resume } from "./human/resume.mjs";
+import { memory as memory$1 } from "./human/stores/memory.mjs";
+import { pg as pg$1 } from "./human/stores/pg.mjs";
+import { redis as redis$1 } from "./human/stores/redis.mjs";
+import "./human/stores/index.mjs";
+import { computeImageCost } from "./image/image-cost.mjs";
+import { image } from "./image/image.mjs";
+import "./image/index.mjs";
+import { speech } from "./speech/speech.mjs";
+import "./speech/index.mjs";
+import { audioFromBuffer, audioFromFile, audioMediaTypeForFilename } from "./transcribe/audio-input.mjs";
+import { transcribe } from "./transcribe/transcribe.mjs";
+import "./transcribe/index.mjs";
+import { injection } from "./guard/detectors/injection.mjs";
+import { pii } from "./guard/detectors/pii.mjs";
+import { topic } from "./guard/detectors/topic.mjs";
+import { OPENAI_INSTALL_INSTRUCTIONS } from "./guard/errors.mjs";
+import { moderation } from "./guard/detectors/moderation.mjs";
+import "./guard/detectors/index.mjs";
+import { guard } from "./guard/guard.mjs";
+import { guardrail } from "./guard/guardrail.mjs";
+import { MockImageModel } from "./mock/mock-image-model.mjs";
 import { MockModel } from "./mock/mock-model.mjs";
+import { MockSpeechModel } from "./mock/mock-speech-model.mjs";
+import { MockTranscriptionModel } from "./mock/mock-transcription-model.mjs";
 import { MockSDK } from "./mock/mock-sdk.mjs";
 import { mockAgent } from "./mock/mock-agent.mjs";
 import { END } from "./contracts/end.type.mjs";
@@ -94,6 +153,7 @@ import { createSupervisorStream } from "./supervisor/supervisor-stream.mjs";
 import { supervisor } from "./supervisor/supervisor.mjs";
 import { OrchestratorExecution, runResume, runTurn, streamTurn } from "./orchestrator/execution.mjs";
 import { createOrchestratorStream } from "./orchestrator/orchestrator-stream.mjs";
+import { inProcessSessionLock, noopSessionLock } from "./orchestrator/session-lock.mjs";
 import { computeOrchestratorSignature } from "./orchestrator/signature.mjs";
 import { orchestrator } from "./orchestrator/orchestrator.mjs";
 import "./orchestrator/index.mjs";
@@ -102,24 +162,54 @@ import { planSchema } from "./planner/plan-schema.mjs";
 import { computeSignature } from "./planner/signature.mjs";
 import { planner } from "./planner/planner.mjs";
 import "./planner/index.mjs";
-import { memory as memory$2 } from "./snapshot/memory.mjs";
-import { pg as pg$1 } from "./snapshot/pg.mjs";
-import { redis as redis$1 } from "./snapshot/redis.mjs";
-import { fanOut } from "./supervisor/fan-out.mjs";
-import { router } from "./supervisor/router-factory.mjs";
-import "./supervisor/index.mjs";
 import { renderPlaceholders } from "./system-prompt/render-placeholders.mjs";
 import { Instruction, instruction } from "./system-prompt/instruction.mjs";
 import { Persona, persona } from "./system-prompt/persona.mjs";
 import { SystemPrompt, systemPrompt } from "./system-prompt/system-prompt.mjs";
+import { defaultPromptsManager, promptKey, prompts } from "./prompts/prompts-manager.mjs";
+import { chunk } from "./rag/chunk/chunk.mjs";
+import { cacheVectorStore } from "./rag/store/cache-vector-store.mjs";
+import { rag } from "./rag/rag.mjs";
+import { pgVectorStore, vectorLiteral } from "./rag/store/pg-vector-store.mjs";
+import { loadText } from "./rag/loaders/load-text.mjs";
+import { loadHtml } from "./rag/loaders/load-html.mjs";
+import { loadWeb } from "./rag/loaders/load-web.mjs";
+import { PDF_PARSE_INSTALL_INSTRUCTIONS } from "./rag/loaders/errors.mjs";
+import { loadPdf } from "./rag/loaders/load-pdf.mjs";
+import { keywordReranker } from "./rag/rerank/keyword-reranker.mjs";
+import { llmReranker } from "./rag/rerank/llm-reranker.mjs";
+import { reciprocalRankFusion } from "./rag/hybrid/rrf.mjs";
+import { bm25Rank } from "./rag/hybrid/bm25.mjs";
+import { hybridRank } from "./rag/hybrid/hybrid-rank.mjs";
+import { multiQuery } from "./rag/transforms/multi-query.mjs";
+import "./rag/index.mjs";
+import { PromptNotFoundError, PromptValidationError } from "./prompt/errors.mjs";
+import { prompt } from "./prompt/prompt.mjs";
+import "./prompt/index.mjs";
+import { DEFAULT_SENSITIVE_KEYS, SENSITIVE_HEADERS, redact, redactError, redactHeaders, scrubSecrets } from "./security/redact.mjs";
+import { VcrCassetteMissError } from "./vcr/errors.mjs";
+import { DEFAULT_HASH_OPTIONS, hashRequest } from "./vcr/hash-request.mjs";
+import { vcr } from "./vcr/vcr.mjs";
+import "./vcr/index.mjs";
+import { memory as memory$3 } from "./snapshot/memory.mjs";
+import { pg as pg$2 } from "./snapshot/pg.mjs";
+import { redis as redis$2 } from "./snapshot/redis.mjs";
+import { fanOut } from "./supervisor/fan-out.mjs";
+import { router } from "./supervisor/router-factory.mjs";
+import "./supervisor/index.mjs";
+import { team } from "./team/team.mjs";
 import { step } from "./workflow/step.mjs";
 import { computeSignature as computeSignature$1 } from "./workflow/signature.mjs";
 import { workflow } from "./workflow/workflow.mjs";
 import { ai } from "./ai.mjs";
+import "./observe/index.mjs";
+import "./prompts/index.mjs";
+import "./security/index.mjs";
+import "./team/index.mjs";
 import "./system-prompt/index.mjs";
 import "./tool/index.mjs";
 import "./workflow/index.mjs";
 import { matchConverge, matchOutputShape, matchPassStep, matchRouteTo } from "./testing/matcher-logic.mjs";
 import { registerAiMatchers } from "./testing/register-lazy.mjs";
 
-export { AIError, AgentCancelledError, AgentExecutionError, AgentMaxTripsError, BudgetExceededError, ContentFilterError, ContextLengthExceededError, END, GuardrailViolationError, Instruction, InvalidRequestError, MaxIterationsError, MaxStepsExceededError, MockModel, MockSDK, OrchestratorCancelledError, OrchestratorConfigError, OrchestratorDriftError, OrchestratorEmitter, OrchestratorExecution, OrchestratorFailedError, Persona, PlannerCancelledError, PlannerFailedError, PlannerPlanInvalidError, ProviderAuthError, ProviderError, ProviderRateLimitError, ProviderTimeoutError, QuotaExceededError, REPORT_SCHEMA_VERSION, RoutingError, SchemaValidationError, StepFailedError, SupervisorCancelledError, SupervisorDriftError, SupervisorEmitter, SupervisorExecution, SupervisorFailedError, SupervisorRoutingError, SystemPrompt, ToolExecutionError, WorkflowCancelledError, WorkflowDriftError, WorkflowError, accumulateCost, agent, ai, approximateTokenCount, batch, budget, buildPlanSystemPrompt, buildRouterContextMessage, memory as checkpointMemory, pg as checkpointPg, redis as checkpointRedis, composeMiddleware, computeCost, computeOrchestratorSignature, computeSignature as computePlannerSignature, computeSignature$1 as computeSignature, computeSignature$2 as computeSupervisorSignature, contains, createAgentStream, createCommandDispatcher as createOrchestratorCommandDispatcher, createOrchestratorStream, createCancelledError as createSupervisorCancelledError, createSupervisorStream, evalScorers, exact, executableToTool, extractJsonPayload, extractJsonSchema, extractUserText, fallbackModel, fanOut, forTool, generateRunId, getAIConfig, guardrail, injectMemories as injectOrchestratorMemories, instruction, isExecutableTool, judge, loadSnapshotForResume as loadSupervisorSnapshotForResume, matchConverge, matchOutputShape, matchPassStep, matchRouteTo, memory$1 as memory, mockAgent, mockRouter, namespacedState, normalizeAgentTools, orchestrator, asTool as orchestratorAsTool, memoryQueryFromInput as orchestratorMemoryQueryFromInput, outcomeTextFromTurn as orchestratorOutcomeTextFromTurn, persistSupervisorSnapshot, persona, planSchema, planner, predicate, prepareAttachmentPart, readBudgetFallbackSignal, recallForTurn as recallOrchestratorMemory, registerAiMatchers, rememberTurnOutcome as rememberOrchestratorTurnOutcome, renderPlaceholders, resolveAttachment, resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, resolveIntentEntries, resolveOrchestratorMemory, router, runEval, runResume as runOrchestratorResume, runTurn as runOrchestratorTurn, runPipeline, safeJsonParse, semanticCache, setAIConfig, memory$2 as snapshotMemory, pg$1 as snapshotPg, redis$1 as snapshotRedis, spawnSubAgent, stampReportLineage, step, streamTurn as streamOrchestratorTurn, supervisor, asTool$1 as supervisorAsTool, systemPrompt, tool, workflow };
+export { AIError, AgentCancelledError, AgentDriftError, AgentExecutionError, AgentMaxTripsError, ApprovalRejectedError, BudgetExceededError, ContentFilterError, ContextLengthExceededError, DEFAULT_HASH_OPTIONS, DEFAULT_SENSITIVE_KEYS, END, GuardrailViolationError, Instruction, InterruptSuspendedError, InvalidRequestError, JUDGE_DEFAULT_REPAIR_ATTEMPTS, MaxIterationsError, MaxStepsExceededError, MockImageModel, MockModel, MockSDK, MockSkillsStore, MockSpeechModel, MockTranscriptionModel, OPENAI_INSTALL_INSTRUCTIONS, OrchestratorCancelledError, OrchestratorConfigError, OrchestratorDriftError, OrchestratorEmitter, OrchestratorExecution, OrchestratorFailedError, OutboundPolicyError, PDF_PARSE_INSTALL_INSTRUCTIONS, Persona, PlannerCancelledError, PlannerDriftError, PlannerFailedError, PlannerPlanInvalidError, PromptNotFoundError, PromptValidationError, ProviderAuthError, ProviderError, ProviderRateLimitError, ProviderTimeoutError, QuotaExceededError, REPORT_SCHEMA_VERSION, RoutingError, SENSITIVE_HEADERS, SSE_DONE, SchemaValidationError, StepFailedError, SupervisorCancelledError, SupervisorDriftError, SupervisorEmitter, SupervisorExecution, SupervisorFailedError, SupervisorRoutingError, SystemPrompt, ToolExecutionError, VcrCassetteMissError, WorkflowCancelledError, WorkflowDriftError, WorkflowError, accumulateCost, agent, ai, approximateTokenCount, assertUrlAllowed, audioFromBuffer, audioFromFile, audioMediaTypeForFilename, batch, bm25Rank, budget, buildCatalog, buildPlanSystemPrompt, buildRouterContextMessage, cacheVectorStore, captureChildReport, memory as checkpointMemory, pg as checkpointPg, redis as checkpointRedis, chunk, collectStreamObject, composeMiddleware, computeCost, computeImageCost, computeOrchestratorSignature, computeSignature as computePlannerSignature, computeSignature$1 as computeSignature, computeSignature$2 as computeSupervisorSignature, contains, createAgentStream, createCommandDispatcher as createOrchestratorCommandDispatcher, createOrchestratorStream, createCancelledError as createSupervisorCancelledError, createSupervisorStream, currentRunFrame, dataset, defaultPromptsManager, diff, directorySource, encodeSSE, evalScorers, evaluatePolicy, exact, executableToTool, extractJsonLenient, extractJsonPayload, extractJsonSchema, extractUserText, fallbackModel, fanOut, fetchTextWithPolicy, forTool, fromJSON, generateRunId, getAIConfig, getObservers, guard, guardedFetch, guardrail, hashRequest, humanApproval, hybridRank, image, inProcessSessionLock, injectMemories as injectOrchestratorMemories, injection, instruction, memory$1 as interruptMemory, pg$1 as interruptPg, redis$1 as interruptRedis, isExecutableTool, isObserveAll, isPrivateOrReservedIp, judge, keywordReranker, llmReranker, loadHtml, loadPdf, loadRecord, loadSkillTool, loadSnapshotForResume as loadSupervisorSnapshotForResume, loadText, loadWeb, matchConverge, matchOutputShape, matchPassStep, matchRouteTo, memory$2 as memory, mergeUsage, mockAgent, mockRouter, moderation, multiQuery, namespacedState, noopSessionLock, normalizeAgentTools, onConfigApplied, orchestrator, asTool as orchestratorAsTool, memoryQueryFromInput as orchestratorMemoryQueryFromInput, outcomeTextFromTurn as orchestratorOutcomeTextFromTurn, parseFrontmatter, parsePartialJson, parseTags, persistSupervisorSnapshot, persona, pgVectorStore, pii, planSchema, planner, predicate, prepareAttachmentPart, proceduralSkillStore, prompt, promptKey, prompts, rag, readBudgetFallbackSignal, readTextCapped, recallForTurn as recallOrchestratorMemory, reciprocalRankFusion, redact, redactError, redactHeaders, registerAiMatchers, registerObserver, rememberTurnOutcome as rememberOrchestratorTurnOutcome, renderCatalogPrompt, renderPlaceholders, resolveAttachment, resolveDefaultCheckpointStore, resolveDefaultSnapshotStore, resolveDefaultStore, resolveIntentEntries, resolveObservers, resolveOrchestratorMemory, resolveOutboundPolicy, resolveSource, resume, router, runEval, runResume as runOrchestratorResume, runTurn as runOrchestratorTurn, runPipeline, runReviewGate, safeJsonParse, saveSkillTool, scrubSecrets, semanticCache, semanticPreselect, serve, setAIConfig, setObserveAll, skills, memory$3 as snapshotMemory, pg$2 as snapshotPg, redis$2 as snapshotRedis, spawnSubAgent, speech, stampReportLineage, step, storeSource, streamObject, streamTurn as streamOrchestratorTurn, streamToSSE, supervisor, asTool$1 as supervisorAsTool, systemPrompt, team, toJSON, toJUnit, tool, topic, transcribe, urlSource, vcr, vectorLiteral, withRunFrame, withoutRunFrame, workflow };

package/esm/middleware/builtins/budget.mjs

@@ -144,6 +144,7 @@ function budget(options) {
 	const hasContractCostCap = typeof contract?.maxCostUSD === "number";
 	const hasContractLatencyCap = typeof contract?.maxLatencyMs === "number";
 	const contractNeedsCost = hasCostCap || hasContractCostCap;
+	const warnedUnpricedModels = /* @__PURE__ */ new Set();
 	return {
 		name,
 		execute: { before(context) {
@@ -159,11 +160,14 @@ function budget(options) {
 			const counters = namespacedState(context, name).get();
 			if (!counters) return;
 			counters.tokens += response.usage.total;
-			if (contractNeedsCost && options.pricing) {
-				const pricing = options.pricing[context.model.name];
+			if (contractNeedsCost) {
+				const pricing = options.pricing?.[context.model.name];
 				if (pricing) {
 					const tripCost = response.usage.input / 1e3 * pricing.inputPer1K + response.usage.output / 1e3 * pricing.outputPer1K;
 					counters.costUSD += tripCost;
+				} else if (!warnedUnpricedModels.has(context.model.name)) {
+					warnedUnpricedModels.add(context.model.name);
+					console.warn(`ai.middleware.budget("${name}"): a USD cost cap is set but no pricing entry matches the running model "${context.model.name}" — the cap cannot be enforced for it. Add a pricing entry for "${context.model.name}" to options.pricing.`);
 				}
 			}
 			if (hasTokenCap && counters.tokens > options.maxTokens) {

package/esm/middleware/builtins/budget.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"budget.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget.ts"],"sourcesContent":["import type {\n  AgentMiddleware,\n  MiddlewareExecuteContext,\n} from \"../../contracts/middleware\";\nimport { BudgetExceededError, type BudgetUnit } from \"../../errors\";\nimport { namespacedState } from \"../utils\";\nimport type {\n  BudgetContract,\n  BudgetContractDimension,\n  BudgetContractViolation,\n} from \"./budget-contract.type\";\n\nexport type {\n  BudgetContract,\n  BudgetContractDimension,\n  BudgetContractFallback,\n  BudgetContractViolation,\n  BudgetContractViolationMode,\n} from \"./budget-contract.type\";\n\n/**\n * Per-model pricing used to compute USD cost from token counts.\n * Caller-supplied — no bundled table. Keys are model names (the\n * `ModelContract.name` value); values are input / output token\n * prices expressed as **USD per 1K tokens** to match every major\n * provider's published pricing sheet.\n */\nexport type BudgetPricing = Record<\n  string,\n  {\n    /** USD per 1,000 input tokens. */\n    inputPer1K: number;\n    /** USD per 1,000 output tokens. */\n    outputPer1K: number;\n  }\n>;\n\n/**\n * Configuration for `budget()`. At least one of `maxTokens` or\n * `maxCostUSD` must be supplied — a budget with no cap is a no-op.\n */\nexport type BudgetOptions = {\n  /**\n   * Hard cap on cumulative total tokens (input + output, summed\n   * across every trip of the run). Inclusive — exceeding triggers\n   * the configured `onExceeded`.\n   */\n  maxTokens?: number;\n  /**\n   * Hard cap on cumulative USD cost. Requires `pricing` for the\n   * agent's configured model — without a pricing entry the USD check\n   * silently skips (tokens-only enforcement still applies).\n   */\n  maxCostUSD?: number;\n  /**\n   * Per-model pricing table used to compute USD cost. Only consulted\n   * when `maxCostUSD` is set. Model names must match the running\n   * agent's `ModelContract.name` exactly.\n   */\n  pricing?: BudgetPricing;\n  /**\n   * Behavior when a cap is breached. `\"abort\"` throws\n   * `BudgetExceededError` — surfaces on `result.error`, stops the\n   * run at the next trip boundary. `\"warn\"` logs a warning and\n   * lets the run continue (useful for observability-first rollouts\n   * before flipping the switch to abort). Default `\"abort\"`.\n   */\n  onExceeded?: \"abort\" | \"warn\";\n  /**\n   * Override the middleware name. Useful when two budgets coexist\n   * (e.g. a per-request cap plus a session-wide cap via different\n   * instances). Default `\"budget\"`.\n   */\n  name?: string;\n  /**\n   * Declarative SLO / cost contract enforced on top of (and\n   * independently of) the legacy `maxTokens` / `maxCostUSD` caps.\n   * Adds a wall-clock `maxLatencyMs` dimension and a per-contract\n   * `onViolation` reaction (`\"abort\"` hard-stops, `\"fallback\"` records\n   * a signal + fires `fallback` and lets the run continue). Omit to\n   * keep the classic budget behavior unchanged.\n   *\n   * Read a recorded fallback signal back with\n   * {@link readBudgetFallbackSignal}.\n   */\n  contract?: BudgetContract;\n};\n\ntype BudgetCounters = {\n  tokens: number;\n  costUSD: number;\n  warned: boolean;\n  /**\n   * Wall-clock epoch ms captured at `execute.before`. Used to derive\n   * cumulative run latency for the contract's `maxLatencyMs` clause.\n   */\n  startedAt: number;\n  /**\n   * Set once a `\"fallback\"` contract clause has fired, so the signal +\n   * callback are emitted at most once per run even if later trips keep\n   * breaching.\n   */\n  fallbackFired: boolean;\n};\n\n/**\n * Recorded contract fallback signal, stashed under the `<name>.fallback`\n * state key when a `\"fallback\"` clause trips. A fallback orchestrator\n * reads it via {@link readBudgetFallbackSignal} to decide how to degrade.\n */\nexport type BudgetFallbackSignal = BudgetContractViolation;\n\n/**\n * The `BudgetUnit` to stamp on the thrown error per contract dimension.\n * Latency has no native unit — it borrows `\"requests\"` as the least-wrong\n * operational measure, while the authoritative detail rides on the\n * error's `context.dimension`.\n */\nconst DIMENSION_UNIT: Record<BudgetContractDimension, BudgetUnit> = {\n  tokens: \"tokens\",\n  cost: \"usd\",\n  latency: \"requests\",\n};\n\nfunction breach(\n  limit: number,\n  actual: number,\n  unit: BudgetUnit,\n  name: string,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" exceeded — ${actual} ${unit} (cap: ${limit})`,\n    { limit, actual, unit },\n  );\n}\n\nfunction breachContract(\n  name: string,\n  dimension: BudgetContractDimension,\n  limit: number,\n  actual: number,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" contract exceeded — ${dimension} ${actual} (cap: ${limit})`,\n    {\n      limit,\n      actual,\n      unit: DIMENSION_UNIT[dimension],\n      context: { dimension, limit, actual, source: \"contract\" },\n    },\n  );\n}\n\n/**\n * Read the contract fallback signal recorded by a `budget()` middleware\n * running under `contract.onViolation: \"fallback\"`. Returns `undefined`\n * when no clause was breached.\n *\n * **Role.** The middleware cannot itself switch models on a soft breach,\n * so it records a typed {@link BudgetFallbackSignal} in the shared state\n * bag and lets the run continue. A fallback orchestrator (or the\n * `execute.after` hook of an outer middleware) reads it back here and\n * decides how to degrade the next run — cheaper model, cached answer,\n * truncated context.\n *\n * @param state - The middleware state bag (`ctx.state`).\n * @param name - The budget middleware's name. Default `\"budget\"`,\n *   matching `BudgetOptions.name`'s default.\n *\n * @example\n * const guard = budget({ contract: { maxCostUSD: 0.05, onViolation: \"fallback\" } });\n *\n * // In an outer middleware's execute.after, after the run:\n * const signal = readBudgetFallbackSignal(ctx.state);\n * if (signal?.dimension === \"cost\") {\n *   await rerunOnCheaperModel();\n * }\n */\nexport function readBudgetFallbackSignal(\n  state: MiddlewareExecuteContext[\"state\"],\n  name = \"budget\",\n): BudgetFallbackSignal | undefined {\n  return namespacedState<BudgetFallbackSignal>(\n    { state },\n    `${name}.fallback`,\n  ).get();\n}\n\n/**\n * Enforced token and / or USD budget for an agent run.\n *\n * **Role.** Guards against runaway tool loops, misconfigured\n * prompts, and unexpected provider price swings by capping\n * cumulative usage across every LLM trip of a single execution.\n * Aborts the run with a typed `BudgetExceededError` the moment a cap\n * is breached, rather than letting the damage grow trip by trip.\n *\n * **Scope.** Per-execution. A fresh counter is created at\n * `execute.before` and lives in the middleware state bag until the\n * run ends. Two concurrent `agent.execute()` calls on the same\n * agent therefore enforce the cap independently.\n *\n * **Token accounting.** After each successful trip, the middleware\n * adds `response.usage.total` to its running total and checks\n * against `maxTokens`. Synthetic trips (cache hits) contribute\n * `usage.total` as returned by the cache — cache middleware is\n * expected to surface zero usage on a hit, which naturally excludes\n * those trips from the budget.\n *\n * **USD accounting.** When `maxCostUSD` + `pricing[modelName]` are\n * both present, the middleware converts per-trip input / output\n * tokens to USD and accumulates. Missing pricing silently degrades\n * to tokens-only — explicit rather than guessing.\n *\n * **Warn mode.** `onExceeded: \"warn\"` logs a single warning the first\n * time a cap is breached and lets the run continue. Useful for\n * measuring real-world traffic against a proposed cap before flipping\n * to `\"abort\"` in production.\n *\n * **Contract / SLO mode.** Pass `contract` to enforce a declarative\n * service-level objective — `maxCostUSD`, `maxLatencyMs`, `maxTokens` —\n * on top of the legacy caps, with a single `onViolation` reaction:\n * `\"abort\"` hard-stops with `BudgetExceededError`; `\"fallback\"` records\n * a typed signal (read it via {@link readBudgetFallbackSignal}), fires\n * the optional `fallback` callback, and lets the run continue so an\n * outer layer can degrade gracefully. The contract's clauses are\n * evaluated independently of — and after — the top-level caps; the\n * top-level caps stay fully functional with or without a contract.\n *\n * @example\n * const budgetMiddleware = budget({ maxTokens: 50_000 });\n *\n * const myAgent = agent({\n *   model,\n *   middleware: [budgetMiddleware],\n * });\n *\n * @example\n * // With USD cap and custom pricing\n * const guard = budget({\n *   maxCostUSD: 0.5,\n *   pricing: {\n *     \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 },\n *   },\n * });\n *\n * @example\n * // SLO contract — soft-fallback on any breach\n * const sloGuard = budget({\n *   pricing: { \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 } },\n *   contract: {\n *     maxCostUSD: 0.05,\n *     maxLatencyMs: 8_000,\n *     maxTokens: 40_000,\n *     onViolation: \"fallback\",\n *     fallback: (violation) => routeToCheaperModel(violation.dimension),\n *   },\n * });\n */\nexport function budget(options: BudgetOptions): AgentMiddleware {\n  const name = options.name ?? \"budget\";\n  const onExceeded = options.onExceeded ?? \"abort\";\n  const hasTokenCap = typeof options.maxTokens === \"number\";\n  const hasCostCap = typeof options.maxCostUSD === \"number\";\n\n  const contract = options.contract;\n  const contractMode = contract?.onViolation ?? \"abort\";\n  const hasContractTokenCap = typeof contract?.maxTokens === \"number\";\n  const hasContractCostCap = typeof contract?.maxCostUSD === \"number\";\n  const hasContractLatencyCap = typeof contract?.maxLatencyMs === \"number\";\n  const contractNeedsCost = hasCostCap || hasContractCostCap;\n\n  return {\n    name,\n    execute: {\n      before(context) {\n        const counters = namespacedState<BudgetCounters>(context, name);\n        counters.set({\n          tokens: 0,\n          costUSD: 0,\n          warned: false,\n          startedAt: Date.now(),\n          fallbackFired: false,\n        });\n      },\n    },\n    trip: {\n      async after(context, response) {\n        const counters = namespacedState<BudgetCounters>(context, name).get();\n\n        if (!counters) {\n          return;\n        }\n\n        counters.tokens += response.usage.total;\n\n        if (contractNeedsCost && options.pricing) {\n          const pricing = options.pricing[context.model.name];\n\n          if (pricing) {\n            const tripCost =\n              (response.usage.input / 1000) * pricing.inputPer1K +\n              (response.usage.output / 1000) * pricing.outputPer1K;\n            counters.costUSD += tripCost;\n          }\n        }\n\n        if (hasTokenCap && counters.tokens > options.maxTokens!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxTokens!, counters.tokens, \"tokens\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (hasCostCap && counters.costUSD > options.maxCostUSD!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxCostUSD!, counters.costUSD, \"usd\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (!contract) {\n          return;\n        }\n\n        if (hasContractTokenCap && counters.tokens > contract.maxTokens!) {\n          await enforceContract(\n            context,\n            counters,\n            name,\n            contractMode,\n            contract,\n            \"tokens\",\n            contract.maxTokens!,\n            counters.tokens,\n          );\n        }\n\n        if (hasContractCostCap && counters.costUSD > contract.maxCostUSD!) {\n          await enforceContract(\n            context,\n            counters,\n            name,\n            contractMode,\n            contract,\n            \"cost\",\n            contract.maxCostUSD!,\n            counters.costUSD,\n          );\n        }\n\n        if (hasContractLatencyCap) {\n          const elapsedMs = Date.now() - counters.startedAt;\n\n          if (elapsedMs > contract.maxLatencyMs!) {\n            await enforceContract(\n              context,\n              counters,\n              name,\n              contractMode,\n              contract,\n              \"latency\",\n              contract.maxLatencyMs!,\n              elapsedMs,\n            );\n          }\n        }\n      },\n    },\n  };\n}\n\n/**\n * Apply the contract's reaction to a single breached clause. `\"abort\"`\n * throws `BudgetExceededError` (stops the run); `\"fallback\"` records the\n * signal once, fires the callback, and returns so the run continues.\n *\n * The callback is invoked at most once per run (guarded by\n * `counters.fallbackFired`) and its rejections are swallowed — a buggy\n * fallback hook must never crash the agent.\n */\nasync function enforceContract(\n  context: MiddlewareExecuteContext,\n  counters: BudgetCounters,\n  name: string,\n  mode: NonNullable<BudgetContract[\"onViolation\"]>,\n  contract: BudgetContract,\n  dimension: BudgetContractDimension,\n  limit: number,\n  actual: number,\n): Promise<void> {\n  if (mode === \"abort\") {\n    breachContract(name, dimension, limit, actual);\n  }\n\n  if (counters.fallbackFired) {\n    return;\n  }\n\n  counters.fallbackFired = true;\n\n  const violation: BudgetContractViolation = {\n    dimension,\n    limit,\n    actual,\n    mode,\n  };\n\n  namespacedState<BudgetContractViolation>(context, `${name}.fallback`).set(\n    violation,\n  );\n\n  if (!contract.fallback) {\n    return;\n  }\n\n  try {\n    await contract.fallback(violation, context);\n  } catch {\n    // A fallback callback is a notification hook — its failure must\n    // never crash the run. Swallow deliberately.\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"budget.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget.ts"],"sourcesContent":["import type {\n  AgentMiddleware,\n  MiddlewareExecuteContext,\n} from \"../../contracts/middleware\";\nimport { BudgetExceededError, type BudgetUnit } from \"../../errors\";\nimport { namespacedState } from \"../utils\";\nimport type {\n  BudgetContract,\n  BudgetContractDimension,\n  BudgetContractViolation,\n} from \"./budget-contract.type\";\n\nexport type {\n  BudgetContract,\n  BudgetContractDimension,\n  BudgetContractFallback,\n  BudgetContractViolation,\n  BudgetContractViolationMode,\n} from \"./budget-contract.type\";\n\n/**\n * Per-model pricing used to compute USD cost from token counts.\n * Caller-supplied — no bundled table. Keys are model names (the\n * `ModelContract.name` value); values are input / output token\n * prices expressed as **USD per 1K tokens** to match every major\n * provider's published pricing sheet.\n */\nexport type BudgetPricing = Record<\n  string,\n  {\n    /** USD per 1,000 input tokens. */\n    inputPer1K: number;\n    /** USD per 1,000 output tokens. */\n    outputPer1K: number;\n  }\n>;\n\n/**\n * Configuration for `budget()`. At least one of `maxTokens` or\n * `maxCostUSD` must be supplied — a budget with no cap is a no-op.\n */\nexport type BudgetOptions = {\n  /**\n   * Hard cap on cumulative total tokens (input + output, summed\n   * across every trip of the run). Inclusive — exceeding triggers\n   * the configured `onExceeded`.\n   */\n  maxTokens?: number;\n  /**\n   * Hard cap on cumulative USD cost. Requires `pricing` for the\n   * agent's configured model — without a pricing entry the USD check\n   * silently skips (tokens-only enforcement still applies).\n   */\n  maxCostUSD?: number;\n  /**\n   * Per-model pricing table used to compute USD cost. Only consulted\n   * when `maxCostUSD` is set. Model names must match the running\n   * agent's `ModelContract.name` exactly.\n   */\n  pricing?: BudgetPricing;\n  /**\n   * Behavior when a cap is breached. `\"abort\"` throws\n   * `BudgetExceededError` — surfaces on `result.error`, stops the\n   * run at the next trip boundary. `\"warn\"` logs a warning and\n   * lets the run continue (useful for observability-first rollouts\n   * before flipping the switch to abort). Default `\"abort\"`.\n   */\n  onExceeded?: \"abort\" | \"warn\";\n  /**\n   * Override the middleware name. Useful when two budgets coexist\n   * (e.g. a per-request cap plus a session-wide cap via different\n   * instances). Default `\"budget\"`.\n   */\n  name?: string;\n  /**\n   * Declarative SLO / cost contract enforced on top of (and\n   * independently of) the legacy `maxTokens` / `maxCostUSD` caps.\n   * Adds a wall-clock `maxLatencyMs` dimension and a per-contract\n   * `onViolation` reaction (`\"abort\"` hard-stops, `\"fallback\"` records\n   * a signal + fires `fallback` and lets the run continue). Omit to\n   * keep the classic budget behavior unchanged.\n   *\n   * Read a recorded fallback signal back with\n   * {@link readBudgetFallbackSignal}.\n   */\n  contract?: BudgetContract;\n};\n\ntype BudgetCounters = {\n  tokens: number;\n  costUSD: number;\n  warned: boolean;\n  /**\n   * Wall-clock epoch ms captured at `execute.before`. Used to derive\n   * cumulative run latency for the contract's `maxLatencyMs` clause.\n   */\n  startedAt: number;\n  /**\n   * Set once a `\"fallback\"` contract clause has fired, so the signal +\n   * callback are emitted at most once per run even if later trips keep\n   * breaching.\n   */\n  fallbackFired: boolean;\n};\n\n/**\n * Recorded contract fallback signal, stashed under the `<name>.fallback`\n * state key when a `\"fallback\"` clause trips. A fallback orchestrator\n * reads it via {@link readBudgetFallbackSignal} to decide how to degrade.\n */\nexport type BudgetFallbackSignal = BudgetContractViolation;\n\n/**\n * The `BudgetUnit` to stamp on the thrown error per contract dimension.\n * Latency has no native unit — it borrows `\"requests\"` as the least-wrong\n * operational measure, while the authoritative detail rides on the\n * error's `context.dimension`.\n */\nconst DIMENSION_UNIT: Record<BudgetContractDimension, BudgetUnit> = {\n  tokens: \"tokens\",\n  cost: \"usd\",\n  latency: \"requests\",\n};\n\nfunction breach(\n  limit: number,\n  actual: number,\n  unit: BudgetUnit,\n  name: string,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" exceeded — ${actual} ${unit} (cap: ${limit})`,\n    { limit, actual, unit },\n  );\n}\n\nfunction breachContract(\n  name: string,\n  dimension: BudgetContractDimension,\n  limit: number,\n  actual: number,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" contract exceeded — ${dimension} ${actual} (cap: ${limit})`,\n    {\n      limit,\n      actual,\n      unit: DIMENSION_UNIT[dimension],\n      context: { dimension, limit, actual, source: \"contract\" },\n    },\n  );\n}\n\n/**\n * Read the contract fallback signal recorded by a `budget()` middleware\n * running under `contract.onViolation: \"fallback\"`. Returns `undefined`\n * when no clause was breached.\n *\n * **Role.** The middleware cannot itself switch models on a soft breach,\n * so it records a typed {@link BudgetFallbackSignal} in the shared state\n * bag and lets the run continue. A fallback orchestrator (or the\n * `execute.after` hook of an outer middleware) reads it back here and\n * decides how to degrade the next run — cheaper model, cached answer,\n * truncated context.\n *\n * @param state - The middleware state bag (`ctx.state`).\n * @param name - The budget middleware's name. Default `\"budget\"`,\n *   matching `BudgetOptions.name`'s default.\n *\n * @example\n * const guard = budget({ contract: { maxCostUSD: 0.05, onViolation: \"fallback\" } });\n *\n * // In an outer middleware's execute.after, after the run:\n * const signal = readBudgetFallbackSignal(ctx.state);\n * if (signal?.dimension === \"cost\") {\n *   await rerunOnCheaperModel();\n * }\n */\nexport function readBudgetFallbackSignal(\n  state: MiddlewareExecuteContext[\"state\"],\n  name = \"budget\",\n): BudgetFallbackSignal | undefined {\n  return namespacedState<BudgetFallbackSignal>(\n    { state },\n    `${name}.fallback`,\n  ).get();\n}\n\n/**\n * Enforced token and / or USD budget for an agent run.\n *\n * **Role.** Guards against runaway tool loops, misconfigured\n * prompts, and unexpected provider price swings by capping\n * cumulative usage across every LLM trip of a single execution.\n * Aborts the run with a typed `BudgetExceededError` the moment a cap\n * is breached, rather than letting the damage grow trip by trip.\n *\n * **Scope.** Per-execution. A fresh counter is created at\n * `execute.before` and lives in the middleware state bag until the\n * run ends. Two concurrent `agent.execute()` calls on the same\n * agent therefore enforce the cap independently.\n *\n * **Token accounting.** After each successful trip, the middleware\n * adds `response.usage.total` to its running total and checks\n * against `maxTokens`. Synthetic trips (cache hits) contribute\n * `usage.total` as returned by the cache — cache middleware is\n * expected to surface zero usage on a hit, which naturally excludes\n * those trips from the budget.\n *\n * **USD accounting.** When `maxCostUSD` + `pricing[modelName]` are\n * both present, the middleware converts per-trip input / output\n * tokens to USD and accumulates. Missing pricing silently degrades\n * to tokens-only — explicit rather than guessing.\n *\n * **Warn mode.** `onExceeded: \"warn\"` logs a single warning the first\n * time a cap is breached and lets the run continue. Useful for\n * measuring real-world traffic against a proposed cap before flipping\n * to `\"abort\"` in production.\n *\n * **Contract / SLO mode.** Pass `contract` to enforce a declarative\n * service-level objective — `maxCostUSD`, `maxLatencyMs`, `maxTokens` —\n * on top of the legacy caps, with a single `onViolation` reaction:\n * `\"abort\"` hard-stops with `BudgetExceededError`; `\"fallback\"` records\n * a typed signal (read it via {@link readBudgetFallbackSignal}), fires\n * the optional `fallback` callback, and lets the run continue so an\n * outer layer can degrade gracefully. The contract's clauses are\n * evaluated independently of — and after — the top-level caps; the\n * top-level caps stay fully functional with or without a contract.\n *\n * @example\n * const budgetMiddleware = budget({ maxTokens: 50_000 });\n *\n * const myAgent = agent({\n *   model,\n *   middleware: [budgetMiddleware],\n * });\n *\n * @example\n * // With USD cap and custom pricing\n * const guard = budget({\n *   maxCostUSD: 0.5,\n *   pricing: {\n *     \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 },\n *   },\n * });\n *\n * @example\n * // SLO contract — soft-fallback on any breach\n * const sloGuard = budget({\n *   pricing: { \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 } },\n *   contract: {\n *     maxCostUSD: 0.05,\n *     maxLatencyMs: 8_000,\n *     maxTokens: 40_000,\n *     onViolation: \"fallback\",\n *     fallback: (violation) => routeToCheaperModel(violation.dimension),\n *   },\n * });\n */\nexport function budget(options: BudgetOptions): AgentMiddleware {\n  const name = options.name ?? \"budget\";\n  const onExceeded = options.onExceeded ?? \"abort\";\n  const hasTokenCap = typeof options.maxTokens === \"number\";\n  const hasCostCap = typeof options.maxCostUSD === \"number\";\n\n  const contract = options.contract;\n  const contractMode = contract?.onViolation ?? \"abort\";\n  const hasContractTokenCap = typeof contract?.maxTokens === \"number\";\n  const hasContractCostCap = typeof contract?.maxCostUSD === \"number\";\n  const hasContractLatencyCap = typeof contract?.maxLatencyMs === \"number\";\n  const contractNeedsCost = hasCostCap || hasContractCostCap;\n  // Warn once per model when a cost cap is configured but the running model\n  // has no pricing entry — without this the USD cap silently never enforces\n  // (costUSD stays 0), a fail-open the JSDoc on `maxCostUSD` documents.\n  const warnedUnpricedModels = new Set<string>();\n\n  return {\n    name,\n    execute: {\n      before(context) {\n        const counters = namespacedState<BudgetCounters>(context, name);\n        counters.set({\n          tokens: 0,\n          costUSD: 0,\n          warned: false,\n          startedAt: Date.now(),\n          fallbackFired: false,\n        });\n      },\n    },\n    trip: {\n      async after(context, response) {\n        const counters = namespacedState<BudgetCounters>(context, name).get();\n\n        if (!counters) {\n          return;\n        }\n\n        counters.tokens += response.usage.total;\n\n        if (contractNeedsCost) {\n          const pricing = options.pricing?.[context.model.name];\n\n          if (pricing) {\n            const tripCost =\n              (response.usage.input / 1000) * pricing.inputPer1K +\n              (response.usage.output / 1000) * pricing.outputPer1K;\n            counters.costUSD += tripCost;\n          } else if (!warnedUnpricedModels.has(context.model.name)) {\n            // A cost cap is set but no pricing matched the running model, so\n            // costUSD can never grow and the USD cap silently never fires.\n            // Surface the fail-open once per model instead of swallowing it.\n            warnedUnpricedModels.add(context.model.name);\n            console.warn(\n              `ai.middleware.budget(\"${name}\"): a USD cost cap is set but no pricing entry ` +\n                `matches the running model \"${context.model.name}\" — the cap cannot be enforced ` +\n                `for it. Add a pricing entry for \"${context.model.name}\" to options.pricing.`,\n            );\n          }\n        }\n\n        if (hasTokenCap && counters.tokens > options.maxTokens!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxTokens!, counters.tokens, \"tokens\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (hasCostCap && counters.costUSD > options.maxCostUSD!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxCostUSD!, counters.costUSD, \"usd\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (!contract) {\n          return;\n        }\n\n        if (hasContractTokenCap && counters.tokens > contract.maxTokens!) {\n          await enforceContract(\n            context,\n            counters,\n            name,\n            contractMode,\n            contract,\n            \"tokens\",\n            contract.maxTokens!,\n            counters.tokens,\n          );\n        }\n\n        if (hasContractCostCap && counters.costUSD > contract.maxCostUSD!) {\n          await enforceContract(\n            context,\n            counters,\n            name,\n            contractMode,\n            contract,\n            \"cost\",\n            contract.maxCostUSD!,\n            counters.costUSD,\n          );\n        }\n\n        if (hasContractLatencyCap) {\n          const elapsedMs = Date.now() - counters.startedAt;\n\n          if (elapsedMs > contract.maxLatencyMs!) {\n            await enforceContract(\n              context,\n              counters,\n              name,\n              contractMode,\n              contract,\n              \"latency\",\n              contract.maxLatencyMs!,\n              elapsedMs,\n            );\n          }\n        }\n      },\n    },\n  };\n}\n\n/**\n * Apply the contract's reaction to a single breached clause. `\"abort\"`\n * throws `BudgetExceededError` (stops the run); `\"fallback\"` records the\n * signal once, fires the callback, and returns so the run continues.\n *\n * The callback is invoked at most once per run (guarded by\n * `counters.fallbackFired`) and its rejections are swallowed — a buggy\n * fallback hook must never crash the agent.\n */\nasync function enforceContract(\n  context: MiddlewareExecuteContext,\n  counters: BudgetCounters,\n  name: string,\n  mode: NonNullable<BudgetContract[\"onViolation\"]>,\n  contract: BudgetContract,\n  dimension: BudgetContractDimension,\n  limit: number,\n  actual: number,\n): Promise<void> {\n  if (mode === \"abort\") {\n    breachContract(name, dimension, limit, actual);\n  }\n\n  if (counters.fallbackFired) {\n    return;\n  }\n\n  counters.fallbackFired = true;\n\n  const violation: BudgetContractViolation = {\n    dimension,\n    limit,\n    actual,\n    mode,\n  };\n\n  namespacedState<BudgetContractViolation>(context, `${name}.fallback`).set(\n    violation,\n  );\n\n  if (!contract.fallback) {\n    return;\n  }\n\n  try {\n    await contract.fallback(violation, context);\n  } catch {\n    // A fallback callback is a notification hook — its failure must\n    // never crash the run. Swallow deliberately.\n  }\n}\n"],"mappings":"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"}

package/esm/middleware/utils/extract-user-text.d.mts

@@ -16,12 +16,19 @@ import { Message } from "../../contracts/conversation-message.type.mjs";
  *   wins (correct when the agent has history + a fresh prompt).
  * - Returns a plain string directly when `content` is a string.
  * - Joins `text` parts with `"\n"` when `content` is a multipart
- *   `ContentPart[]`. Non-text parts (images, audio) are skipped —
+ *   `ContentPart[]`. Non-text parts (images, audio, pdf) are skipped —
  *   callers concerned with multimodal content inspect `request`
  *   / attachments separately.
  * - Returns `""` when there is no user message at all (e.g. a trip
  *   composed entirely of tool results).
  *
+ * **Coverage limit (D3).** Because only `text` parts are extracted, any
+ * guardrail / PII detector built on this helper inspects **text only** —
+ * image / PDF / audio attachment content is NOT scanned. A guardrail is
+ * therefore not a multimodal safety control: for non-text inputs add an
+ * attachment-level policy (e.g. an OCR / moderation pass before the call)
+ * rather than relying on input detectors.
+ *
  * @example
  * const prompt = extractUserText(context.messages);
  * if (!prompt) return;

package/esm/middleware/utils/extract-user-text.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-user-text.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/utils/extract-user-text.ts"],"mappings":";;;;;AA4BA;;;;;;;;AAAgE;;;;;;;;;;;;;;;;iBAAhD,eAAA,CAAgB,QAAA,EAAU,aAAa,CAAC,OAAA"}
+{"version":3,"file":"extract-user-text.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/utils/extract-user-text.ts"],"mappings":";;;;;AAmCA;;;;;;;;AAAgE;;;;;;;;;;;;;;;;;;;;;;;iBAAhD,eAAA,CAAgB,QAAA,EAAU,aAAa,CAAC,OAAA"}

package/esm/middleware/utils/extract-user-text.mjs

@@ -14,12 +14,19 @@
 *   wins (correct when the agent has history + a fresh prompt).
 * - Returns a plain string directly when `content` is a string.
 * - Joins `text` parts with `"\n"` when `content` is a multipart
-*   `ContentPart[]`. Non-text parts (images, audio) are skipped —
+*   `ContentPart[]`. Non-text parts (images, audio, pdf) are skipped —
 *   callers concerned with multimodal content inspect `request`
 *   / attachments separately.
 * - Returns `""` when there is no user message at all (e.g. a trip
 *   composed entirely of tool results).
 *
+* **Coverage limit (D3).** Because only `text` parts are extracted, any
+* guardrail / PII detector built on this helper inspects **text only** —
+* image / PDF / audio attachment content is NOT scanned. A guardrail is
+* therefore not a multimodal safety control: for non-text inputs add an
+* attachment-level policy (e.g. an OCR / moderation pass before the call)
+* rather than relying on input detectors.
+*
 * @example
 * const prompt = extractUserText(context.messages);
 * if (!prompt) return;

package/esm/middleware/utils/extract-user-text.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"extract-user-text.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/utils/extract-user-text.ts"],"sourcesContent":["import type { Message } from \"../../contracts/conversation-message.type\";\n\n/**\n * Pull the text a content-inspection middleware should care about\n * from the outbound message list.\n *\n * **Role.** Built-ins that inspect \"what the user just said\" — the\n * guardrail on `trip.before`, the semantic cache on `trip.before`,\n * future consumers like PII redactors — all need the same string:\n * the most recent `user`-role message's text content. This helper\n * is the single authority on how that string is resolved.\n *\n * **Behavior.**\n * - Walks `messages` from the end backwards so the LAST user turn\n *   wins (correct when the agent has history + a fresh prompt).\n * - Returns a plain string directly when `content` is a string.\n * - Joins `text` parts with `\"\\n\"` when `content` is a multipart\n *   `ContentPart[]`. Non-text parts (images, audio) are skipped —\n *   callers concerned with multimodal content inspect `request`\n *   / attachments separately.\n * - Returns `\"\"` when there is no user message at all (e.g. a trip\n *   composed entirely of tool results).\n *\n * @example\n * const prompt = extractUserText(context.messages);\n * if (!prompt) return;\n * const verdict = await inputCheck(prompt);\n */\nexport function extractUserText(messages: ReadonlyArray<Message>): string {\n  for (let index = messages.length - 1; index >= 0; index--) {\n    const message = messages[index];\n\n    if (message.role !== \"user\") {\n      continue;\n    }\n\n    if (typeof message.content === \"string\") {\n      return message.content;\n    }\n\n    if (Array.isArray(message.content)) {\n      return message.content\n        .filter((part) => part.type === \"text\")\n        .map((part) => (part as { text: string }).text)\n        .join(\"\\n\");\n    }\n  }\n\n  return \"\";\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,gBAAgB,UAA0C;CACxE,KAAK,IAAI,QAAQ,SAAS,SAAS,GAAG,SAAS,GAAG,SAAS;EACzD,MAAM,UAAU,SAAS;EAEzB,IAAI,QAAQ,SAAS,QACnB;EAGF,IAAI,OAAO,QAAQ,YAAY,UAC7B,OAAO,QAAQ;EAGjB,IAAI,MAAM,QAAQ,QAAQ,OAAO,GAC/B,OAAO,QAAQ,QACZ,QAAQ,SAAS,KAAK,SAAS,MAAM,CAAC,CACtC,KAAK,SAAU,KAA0B,IAAI,CAAC,CAC9C,KAAK,IAAI;CAEhB;CAEA,OAAO;AACT"}
+{"version":3,"file":"extract-user-text.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/utils/extract-user-text.ts"],"sourcesContent":["import type { Message } from \"../../contracts/conversation-message.type\";\n\n/**\n * Pull the text a content-inspection middleware should care about\n * from the outbound message list.\n *\n * **Role.** Built-ins that inspect \"what the user just said\" — the\n * guardrail on `trip.before`, the semantic cache on `trip.before`,\n * future consumers like PII redactors — all need the same string:\n * the most recent `user`-role message's text content. This helper\n * is the single authority on how that string is resolved.\n *\n * **Behavior.**\n * - Walks `messages` from the end backwards so the LAST user turn\n *   wins (correct when the agent has history + a fresh prompt).\n * - Returns a plain string directly when `content` is a string.\n * - Joins `text` parts with `\"\\n\"` when `content` is a multipart\n *   `ContentPart[]`. Non-text parts (images, audio, pdf) are skipped —\n *   callers concerned with multimodal content inspect `request`\n *   / attachments separately.\n * - Returns `\"\"` when there is no user message at all (e.g. a trip\n *   composed entirely of tool results).\n *\n * **Coverage limit (D3).** Because only `text` parts are extracted, any\n * guardrail / PII detector built on this helper inspects **text only** —\n * image / PDF / audio attachment content is NOT scanned. A guardrail is\n * therefore not a multimodal safety control: for non-text inputs add an\n * attachment-level policy (e.g. an OCR / moderation pass before the call)\n * rather than relying on input detectors.\n *\n * @example\n * const prompt = extractUserText(context.messages);\n * if (!prompt) return;\n * const verdict = await inputCheck(prompt);\n */\nexport function extractUserText(messages: ReadonlyArray<Message>): string {\n  for (let index = messages.length - 1; index >= 0; index--) {\n    const message = messages[index];\n\n    if (message.role !== \"user\") {\n      continue;\n    }\n\n    if (typeof message.content === \"string\") {\n      return message.content;\n    }\n\n    if (Array.isArray(message.content)) {\n      return message.content\n        .filter((part) => part.type === \"text\")\n        .map((part) => (part as { text: string }).text)\n        .join(\"\\n\");\n    }\n  }\n\n  return \"\";\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,gBAAgB,UAA0C;CACxE,KAAK,IAAI,QAAQ,SAAS,SAAS,GAAG,SAAS,GAAG,SAAS;EACzD,MAAM,UAAU,SAAS;EAEzB,IAAI,QAAQ,SAAS,QACnB;EAGF,IAAI,OAAO,QAAQ,YAAY,UAC7B,OAAO,QAAQ;EAGjB,IAAI,MAAM,QAAQ,QAAQ,OAAO,GAC/B,OAAO,QAAQ,QACZ,QAAQ,SAAS,KAAK,SAAS,MAAM,CAAC,CACtC,KAAK,SAAU,KAA0B,IAAI,CAAC,CAC9C,KAAK,IAAI;CAEhB;CAEA,OAAO;AACT"}

package/esm/mock/index.d.mts

@@ -1,3 +1,6 @@
+import { MockImageCall, MockImageModel, MockImageResponse } from "./mock-image-model.mjs";
+import { MockSpeechCall, MockSpeechModel, MockSpeechResponse } from "./mock-speech-model.mjs";
+import { MockTranscriptionCall, MockTranscriptionModel, MockTranscriptionResponse } from "./mock-transcription-model.mjs";
 import { MockModelResponse, MockSDKConfig } from "./mock-config.type.mjs";
 import { mockAgent } from "./mock-agent.mjs";
 import { MockModel } from "./mock-model.mjs";

package/esm/mock/index.mjs

@@ -1,4 +1,7 @@
+import { MockImageModel } from "./mock-image-model.mjs";
 import { MockModel } from "./mock-model.mjs";
+import { MockSpeechModel } from "./mock-speech-model.mjs";
+import { MockTranscriptionModel } from "./mock-transcription-model.mjs";
 import { MockSDK } from "./mock-sdk.mjs";
 import { mockAgent } from "./mock-agent.mjs";
 import { mockRouter } from "./mock-router.mjs";

package/esm/mock/mock-config.type.d.mts

@@ -2,6 +2,13 @@ import { ModelToolCallRequest } from "../contracts/model-tool-call-request.type.
 import { Usage } from "../contracts/result/usage.type.mjs";
 import { FinishReason } from "../contracts/finish-reason.type.mjs";
 import { ModelCapabilities } from "../contracts/model.contract.mjs";
+import { ImageModelPricing } from "../contracts/image-model.contract.mjs";
+import { SpeechModelPricing } from "../contracts/speech-model.contract.mjs";
+import { TranscriptionModelPricing } from "../contracts/transcription-model.contract.mjs";
+import { MockImageResponse } from "./mock-image-model.mjs";
+import { MockSpeechResponse } from "./mock-speech-model.mjs";
+import { MockTranscriptionResponse } from "./mock-transcription-model.mjs";
+
 //#region ../@warlock.js/ai/src/mock/mock-config.type.d.ts
 /**
  * Configuration for a single mock model response.
@@ -25,6 +32,21 @@ type MockSDKConfig = {
    * a real provider.
    */
   capabilities?: ModelCapabilities;
+  /**
+   * Scripted responses for `image()` models this mock SDK creates,
+   * consumed in sequence (last repeats when exhausted). Omitted = a
+   * single default 1×1 PNG.
+   */
+  imageResponses?: MockImageResponse[];
+  /**
+   * Pricing stamped on every `image()` model this mock SDK creates, so
+   * tests can exercise the per-image / per-token cost rollup.
+   */
+  imagePricing?: ImageModelPricing; /** Scripted responses for `speech()` (TTS) models. Omitted = a default audio blob. */
+  speechResponses?: MockSpeechResponse[]; /** Pricing stamped on every `speech()` model — exercise the per-character / per-token rollup. */
+  speechPricing?: SpeechModelPricing; /** Scripted responses for `transcribe()` (STT) models. Omitted = a default transcript. */
+  transcriptionResponses?: MockTranscriptionResponse[]; /** Pricing stamped on every `transcribe()` model — exercise the per-minute / per-token rollup. */
+  transcriptionPricing?: TranscriptionModelPricing;
 };
 //#endregion
 export { MockModelResponse, MockSDKConfig };

package/esm/mock/mock-config.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-config.type.ts"],"mappings":";;;;;;;;AASA;KAAY,iBAAA;EACV,OAAA;EACA,YAAA,GAAe,YAAA;EACf,KAAA,GAAQ,KAAA;EACR,SAAA,GAAY,oBAAA,IAIJ;EAFR,KAAA,WAEa;EAAb,KAAA,GAAQ,KAAA;AAAA;AAAA,KAGE,aAAA;EARV,wEAUA,SAAA,GAAY,iBAAA,IATZ;EAWA,gBAAA;EATA;;;;AAEa;AAGf;EAWE,YAAA,GAAe,iBAAiB;AAAA"}
+{"version":3,"file":"mock-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-config.type.ts"],"mappings":";;;;;;;;;;;;;;;AAeA;KAAY,iBAAA;EACV,OAAA;EACA,YAAA,GAAe,YAAA;EACf,KAAA,GAAQ,KAAA;EACR,SAAA,GAAY,oBAAA,IAIJ;EAFR,KAAA,WAEa;EAAb,KAAA,GAAQ,KAAA;AAAA;AAAA,KAGE,aAAA;EARV,wEAUA,SAAA,GAAY,iBAAA,IATZ;EAWA,gBAAA;EATA;;;;AAEa;AAGf;EAWE,YAAA,GAAe,iBAAA;;;;;;EAMf,cAAA,GAAiB,iBAAA;EASD;;;;EAJhB,YAAA,GAAe,iBAAA,EApBf;EAsBA,eAAA,GAAkB,kBAAA,IApBlB;EAsBA,aAAA,GAAgB,kBAAA,EAfD;EAiBf,sBAAA,GAAyB,yBAAA,IAXR;EAajB,oBAAA,GAAuB,yBAAA;AAAA"}

package/esm/mock/mock-image-model.d.mts

@@ -0,0 +1,41 @@
+import { Usage } from "../contracts/result/usage.type.mjs";
+import { GeneratedImage, ImageGenerationOptions, ImageGenerationResponse, ImageModelContract, ImageModelPricing } from "../contracts/image-model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/mock/mock-image-model.d.ts
+/** One scripted response for a {@link MockImageModel}. */
+type MockImageResponse = {
+  /** Images to return; defaults to a single 1×1 transparent PNG. */images?: GeneratedImage[]; /** Token usage to report; defaults to all-zero (per-image-metered). */
+  usage?: Usage; /** Throw this instead of returning — drives the never-throws/error path. */
+  error?: Error; /** Simulate latency before resolving/rejecting (ms). */
+  delay?: number;
+};
+/** One recorded `generate()` invocation, for test assertions. */
+type MockImageCall = {
+  prompt: string;
+  options: ImageGenerationOptions | undefined;
+};
+/**
+ * Deterministic {@link ImageModelContract} double for tests — no HTTP.
+ * Scripts responses in sequence (the last repeats once exhausted),
+ * records every call, and can be primed with pricing to exercise the
+ * cost rollup. Mirrors {@link MockModel} for the image path.
+ *
+ * @example
+ * const model = new MockImageModel("mock-image", [{ usage: { input: 0, output: 0, total: 0 } }], {
+ *   perImage: 0.04,
+ * });
+ * const { data, usage } = await ai.image({ model, prompt: "a cat" });
+ */
+declare class MockImageModel implements ImageModelContract {
+  readonly name: string;
+  private readonly responses;
+  readonly pricing?: ImageModelPricing | undefined;
+  readonly provider = "mock";
+  readonly calls: MockImageCall[];
+  private callIndex;
+  constructor(name: string, responses: MockImageResponse[], pricing?: ImageModelPricing | undefined);
+  generate(prompt: string, options?: ImageGenerationOptions): Promise<ImageGenerationResponse>;
+}
+//#endregion
+export { MockImageCall, MockImageModel, MockImageResponse };
+//# sourceMappingURL=mock-image-model.d.mts.map

package/esm/mock/mock-image-model.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-image-model.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-image-model.ts"],"mappings":";;;;;KAUY,iBAAA;EAAA,kEAEV,MAAA,GAAS,cAAA;EAET,KAAA,GAAQ,KAAA,EAAA;EAER,KAAA,GAAQ,KAAA,EAAK;EAEb,KAAA;AAAA;;KAIU,aAAA;EACV,MAAA;EACA,OAAA,EAAS,sBAAsB;AAAA;;;AAN1B;AAIP;;;;;;;;AAEiC;cAmBpB,cAAA,YAA0B,kBAAA;EAAA,SAOnB,IAAA;EAAA,iBACC,SAAA;EAAA,SACD,OAAA,GAAU,iBAAA;EAAA,SARZ,QAAA;EAAA,SACA,KAAA,EAAO,aAAA;EAAA,QAEf,SAAA;cAGU,IAAA,UACC,SAAA,EAAW,iBAAA,IACZ,OAAA,GAAU,iBAAA;EAGf,QAAA,CACX,MAAA,UACA,OAAA,GAAU,sBAAA,GACT,OAAA,CAAQ,uBAAA;AAAA"}

package/esm/mock/mock-image-model.mjs

@@ -0,0 +1,52 @@
+//#region ../@warlock.js/ai/src/mock/mock-image-model.ts
+/** A 1×1 transparent PNG — the default mock image payload. */
+const TRANSPARENT_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+/**
+* Deterministic {@link ImageModelContract} double for tests — no HTTP.
+* Scripts responses in sequence (the last repeats once exhausted),
+* records every call, and can be primed with pricing to exercise the
+* cost rollup. Mirrors {@link MockModel} for the image path.
+*
+* @example
+* const model = new MockImageModel("mock-image", [{ usage: { input: 0, output: 0, total: 0 } }], {
+*   perImage: 0.04,
+* });
+* const { data, usage } = await ai.image({ model, prompt: "a cat" });
+*/
+var MockImageModel = class {
+	constructor(name, responses, pricing) {
+		this.name = name;
+		this.responses = responses;
+		this.pricing = pricing;
+		this.provider = "mock";
+		this.calls = [];
+		this.callIndex = 0;
+	}
+	async generate(prompt, options) {
+		this.calls.push({
+			prompt,
+			options
+		});
+		const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};
+		this.callIndex += 1;
+		if (response.delay) await new Promise((resolve) => setTimeout(resolve, response.delay));
+		if (response.error) throw response.error;
+		const count = options?.count ?? 1;
+		return {
+			images: response.images ?? Array.from({ length: count }, () => ({
+				type: "base64",
+				base64: TRANSPARENT_PNG_BASE64,
+				mediaType: "image/png"
+			})),
+			usage: response.usage ?? {
+				input: 0,
+				output: 0,
+				total: 0
+			}
+		};
+	}
+};
+
+//#endregion
+export { MockImageModel };
+//# sourceMappingURL=mock-image-model.mjs.map

package/esm/mock/mock-image-model.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-image-model.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-image-model.ts"],"sourcesContent":["import type {\n  GeneratedImage,\n  ImageGenerationOptions,\n  ImageGenerationResponse,\n  ImageModelContract,\n  ImageModelPricing,\n} from \"../contracts/image-model.contract\";\nimport type { Usage } from \"../contracts/result/usage.type\";\n\n/** One scripted response for a {@link MockImageModel}. */\nexport type MockImageResponse = {\n  /** Images to return; defaults to a single 1×1 transparent PNG. */\n  images?: GeneratedImage[];\n  /** Token usage to report; defaults to all-zero (per-image-metered). */\n  usage?: Usage;\n  /** Throw this instead of returning — drives the never-throws/error path. */\n  error?: Error;\n  /** Simulate latency before resolving/rejecting (ms). */\n  delay?: number;\n};\n\n/** One recorded `generate()` invocation, for test assertions. */\nexport type MockImageCall = {\n  prompt: string;\n  options: ImageGenerationOptions | undefined;\n};\n\n/** A 1×1 transparent PNG — the default mock image payload. */\nconst TRANSPARENT_PNG_BASE64 =\n  \"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==\";\n\n/**\n * Deterministic {@link ImageModelContract} double for tests — no HTTP.\n * Scripts responses in sequence (the last repeats once exhausted),\n * records every call, and can be primed with pricing to exercise the\n * cost rollup. Mirrors {@link MockModel} for the image path.\n *\n * @example\n * const model = new MockImageModel(\"mock-image\", [{ usage: { input: 0, output: 0, total: 0 } }], {\n *   perImage: 0.04,\n * });\n * const { data, usage } = await ai.image({ model, prompt: \"a cat\" });\n */\nexport class MockImageModel implements ImageModelContract {\n  public readonly provider = \"mock\";\n  public readonly calls: MockImageCall[] = [];\n\n  private callIndex = 0;\n\n  public constructor(\n    public readonly name: string,\n    private readonly responses: MockImageResponse[],\n    public readonly pricing?: ImageModelPricing,\n  ) {}\n\n  public async generate(\n    prompt: string,\n    options?: ImageGenerationOptions,\n  ): Promise<ImageGenerationResponse> {\n    this.calls.push({ prompt, options });\n\n    const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};\n    this.callIndex += 1;\n\n    if (response.delay) {\n      await new Promise((resolve) => setTimeout(resolve, response.delay));\n    }\n\n    if (response.error) {\n      throw response.error;\n    }\n\n    const count = options?.count ?? 1;\n    const images: GeneratedImage[] =\n      response.images ??\n      Array.from({ length: count }, () => ({\n        type: \"base64\" as const,\n        base64: TRANSPARENT_PNG_BASE64,\n        mediaType: \"image/png\",\n      }));\n\n    return {\n      images,\n      usage: response.usage ?? { input: 0, output: 0, total: 0 },\n    };\n  }\n}\n"],"mappings":";;AA4BA,MAAM,yBACJ;;;;;;;;;;;;;AAcF,IAAa,iBAAb,MAA0D;CAMxD,AAAO,YACL,AAAgB,MAChB,AAAiB,WACjB,AAAgB,SAChB;EAHgB;EACC;EACD;kBARS;eACc,CAAC;mBAEtB;CAMjB;CAEH,MAAa,SACX,QACA,SACkC;EAClC,KAAK,MAAM,KAAK;GAAE;GAAQ;EAAQ,CAAC;EAEnC,MAAM,WAAW,KAAK,UAAU,KAAK,IAAI,KAAK,WAAW,KAAK,UAAU,SAAS,CAAC,MAAM,CAAC;EACzF,KAAK,aAAa;EAElB,IAAI,SAAS,OACX,MAAM,IAAI,SAAS,YAAY,WAAW,SAAS,SAAS,KAAK,CAAC;EAGpE,IAAI,SAAS,OACX,MAAM,SAAS;EAGjB,MAAM,QAAQ,SAAS,SAAS;EAShC,OAAO;GACL,QARA,SAAS,UACT,MAAM,KAAK,EAAE,QAAQ,MAAM,UAAU;IACnC,MAAM;IACN,QAAQ;IACR,WAAW;GACb,EAAE;GAIF,OAAO,SAAS,SAAS;IAAE,OAAO;IAAG,QAAQ;IAAG,OAAO;GAAE;EAC3D;CACF;AACF"}

package/esm/mock/mock-sdk.d.mts

@@ -1,4 +1,7 @@
 import { SDKAdapterContract } from "../contracts/sdk-adapter.contract.mjs";
+import { MockImageModel } from "./mock-image-model.mjs";
+import { MockSpeechModel } from "./mock-speech-model.mjs";
+import { MockTranscriptionModel } from "./mock-transcription-model.mjs";
 import { MockSDKConfig } from "./mock-config.type.mjs";
 import { MockModel } from "./mock-model.mjs";
 
@@ -18,7 +21,10 @@ import { MockModel } from "./mock-model.mjs";
  * console.log(result.content); // "Hello from mock!"
  */
 declare function MockSDK(config?: MockSDKConfig): SDKAdapterContract & {
-  /** All model instances created by this SDK — for inspecting calls in tests */models: MockModel[];
+  /** All model instances created by this SDK — for inspecting calls in tests */models: MockModel[]; /** All image-model instances created by this SDK — for inspecting calls in tests */
+  imageModels: MockImageModel[]; /** All speech-model instances created by this SDK — for inspecting calls in tests */
+  speechModels: MockSpeechModel[]; /** All transcription-model instances created by this SDK — for inspecting calls in tests */
+  transcriptionModels: MockTranscriptionModel[];
 };
 //#endregion
 export { MockSDK };

package/esm/mock/mock-sdk.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-sdk.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-sdk.ts"],"mappings":";;;;;;;AAsBA;;;;;;;;;;;;iBAAgB,OAAA,CAAQ,MAAA,GAAQ,aAAA,GAAqB,kBAAA;EAElC,8EAAjB,MAAA,EAAQ,SAAA;AAAA"}
+{"version":3,"file":"mock-sdk.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-sdk.ts"],"mappings":";;;;;;;;;;AA4BA;;;;;;;;;;;;iBAAgB,OAAA,CAAQ,MAAA,GAAQ,aAAA,GAAqB,kBAAA;EAAA,8EAEnD,MAAA,EAAQ,SAAA,IAAA;EAER,WAAA,EAAa,cAAA,IAAA;EAEb,YAAA,EAAc,eAAA,IAAA;EAEd,mBAAA,EAAqB,sBAAA;AAAA"}