@warlock.js/ai 4.5.0 → 4.6.0

package/esm/agent/snapshot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/agent/snapshot.ts"],"sourcesContent":["import { resolveDefaultSnapshotStore } from \"../config\";\nimport type {\n  AgentResumeOptions,\n} from \"../contracts/agent/agent-options.type\";\nimport type {\n  AgentSnapshot,\n  AgentSnapshotStatus,\n} from \"../contracts/agent/agent-snapshot.type\";\nimport type { SnapshotStore } from \"../contracts/orchestrator/snapshot-store.contract\";\nimport type { Message } from \"../contracts/conversation-message.type\";\nimport type { LLMTrip } from \"../contracts/result/llm-trip.type\";\nimport type { ToolCall } from \"../contracts/result/tool-call.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AgentDriftError, AgentExecutionError } from \"../errors\";\n\n/**\n * The agent's `durable` config, narrowed to the fields the snapshot\n * helpers read. Kept minimal so this module doesn't depend on the full\n * resolved-config shape.\n */\nexport type AgentDurableConfig = {\n  store?: SnapshotStore<AgentSnapshot>;\n  deleteOnComplete?: boolean;\n};\n\n/**\n * Resolve the effective {@link SnapshotStore}: the agent's own\n * `durable.store` wins; absent that, fall back to the global default\n * set via `ai.config({ defaultSnapshotStore })`.\n *\n * The global default is typed for the supervisor snapshot shape, but\n * every store impl keys purely by `runId` and round-trips whatever\n * envelope it is handed — so it serves an `AgentSnapshot` just as well.\n * The cast re-tags the shape at this single boundary (Option B); the\n * agent only ever hands it an `AgentSnapshot`.\n */\nfunction resolveSnapshotStore(\n  durable: AgentDurableConfig | undefined,\n): SnapshotStore<AgentSnapshot> | undefined {\n  return (\n    durable?.store ??\n    (resolveDefaultSnapshotStore() as SnapshotStore<AgentSnapshot> | undefined)\n  );\n}\n\nexport type PersistAgentParams = {\n  durable: AgentDurableConfig | undefined;\n  runId: string;\n  agentName: string;\n  signature: string;\n  version?: string;\n  input: string;\n  systemPrompt?: string;\n  responseSchema?: Record<string, unknown>;\n  promptName?: string;\n  promptVersion?: string;\n  messages: Message[];\n  trips: LLMTrip[];\n  toolCalls: ToolCall[];\n  usage: Usage;\n  status: AgentSnapshotStatus;\n  startedAt: string;\n};\n\nexport type PersistOutcome = { ok: true } | { ok: false; error: unknown };\n\n/**\n * Write the current run state to the resolved snapshot store. No-op\n * (returns `{ ok: true }`) when neither `durable.store` nor the global\n * `defaultSnapshotStore` is configured — the common non-durable path.\n * Failures are returned as `{ ok: false }` rather than thrown so the\n * engine can surface them via logs without aborting the run — a failed\n * checkpoint loses resume-ability from that point but never breaks an\n * otherwise-healthy run.\n */\nexport async function persistAgentSnapshot(\n  params: PersistAgentParams,\n): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  const snapshot: AgentSnapshot = {\n    runId: params.runId,\n    agentName: params.agentName,\n    signature: params.signature,\n    version: params.version,\n    input: params.input,\n    systemPrompt: params.systemPrompt,\n    responseSchema: params.responseSchema,\n    promptName: params.promptName,\n    promptVersion: params.promptVersion,\n    messages: params.messages,\n    trips: params.trips,\n    toolCalls: params.toolCalls,\n    usage: params.usage,\n    status: params.status,\n    startedAt: params.startedAt,\n    savedAt: new Date().toISOString(),\n  };\n\n  try {\n    await store.save(snapshot);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Delete a persisted snapshot — used after a successful run when\n * `durable.deleteOnComplete` is set. Never throws: a failed delete is\n * surfaced as `{ ok: false }` and the engine logs it. No-op (ok) when no\n * store is configured.\n */\nexport async function deleteAgentSnapshot(params: {\n  durable: AgentDurableConfig | undefined;\n  runId: string;\n}): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  try {\n    await store.delete(params.runId);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Load a persisted snapshot for `resume()` and run the drift check.\n * Throws `AgentExecutionError` when no store is configured or when the\n * run is missing; throws `AgentDriftError` when the stored signature\n * doesn't match the current definition (unless `force` is set).\n */\nexport async function loadAgentSnapshotForResume(params: {\n  durable: AgentDurableConfig | undefined;\n  agentName: string;\n  signature: string;\n  runId: string;\n  options?: AgentResumeOptions<unknown>;\n}): Promise<AgentSnapshot> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    throw new AgentExecutionError(\n      `agent \"${params.agentName}\" has no durable store configured — set \\`durable: { store }\\` on the config or call \\`ai.config({ defaultSnapshotStore })\\` at boot before calling resume()`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  const snapshot = (await store.load(params.runId)) ?? null;\n\n  if (!snapshot) {\n    throw new AgentExecutionError(\n      `agent \"${params.agentName}\": no snapshot for runId \"${params.runId}\"`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  if (!params.options?.force && snapshot.signature !== params.signature) {\n    throw new AgentDriftError(\n      `agent \"${params.agentName}\" signature drift on resume`,\n      {\n        savedSignature: snapshot.signature,\n        currentSignature: params.signature,\n        runId: params.runId,\n      },\n    );\n  }\n\n  return snapshot;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAoCA,SAAS,qBACP,SAC0C;CAC1C,OACE,SAAS,SACR,4BAA4B;AAEjC;;;;;;;;;;AAgCA,eAAsB,qBACpB,QACyB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,MAAM,WAA0B;EAC9B,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,OAAO,OAAO;EACd,cAAc,OAAO;EACrB,gBAAgB,OAAO;EACvB,YAAY,OAAO;EACnB,eAAe,OAAO;EACtB,UAAU,OAAO;EACjB,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,OAAO,OAAO;EACd,QAAQ,OAAO;EACf,WAAW,OAAO;EAClB,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;CAClC;CAEA,IAAI;EACF,MAAM,MAAM,KAAK,QAAQ;EAEzB,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;;AAQA,eAAsB,oBAAoB,QAGd;CAC1B,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,IAAI;EACF,MAAM,MAAM,OAAO,OAAO,KAAK;EAE/B,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;;AAQA,eAAsB,2BAA2B,QAMtB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,MAAM,IAAI,oBACR,UAAU,OAAO,UAAU,+JAC3B,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,MAAM,WAAY,MAAM,MAAM,KAAK,OAAO,KAAK,KAAM;CAErD,IAAI,CAAC,UACH,MAAM,IAAI,oBACR,UAAU,OAAO,UAAU,4BAA4B,OAAO,MAAM,IACpE,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,IAAI,CAAC,OAAO,SAAS,SAAS,SAAS,cAAc,OAAO,WAC1D,MAAM,IAAI,gBACR,UAAU,OAAO,UAAU,8BAC3B;EACE,gBAAgB,SAAS;EACzB,kBAAkB,OAAO;EACzB,OAAO,OAAO;CAChB,CACF;CAGF,OAAO;AACT"}

package/esm/ai-openai/src/image.mjs

@@ -0,0 +1,5 @@
+import "../../index.mjs";
+import "./utils/index.mjs";
+import { log } from "@warlock.js/logger";
+
+export {  };

package/esm/ai-openai/src/index.mjs

@@ -1,4 +1,7 @@
 import "./embedder.mjs";
+import "./image.mjs";
+import "./speech.mjs";
+import "./transcription.mjs";
 import "./sdk.mjs";
 
 export {  };

package/esm/ai-openai/src/sdk.mjs

@@ -1,6 +1,9 @@
 import "../../index.mjs";
 import "./embedder.mjs";
+import "./image.mjs";
 import "./model.mjs";
+import "./speech.mjs";
+import "./transcription.mjs";
 import "openai";
 
 export {  };

package/esm/ai-openai/src/speech.mjs

@@ -0,0 +1,5 @@
+import "../../index.mjs";
+import "./utils/index.mjs";
+import { log } from "@warlock.js/logger";
+
+export {  };

package/esm/ai-openai/src/transcription.mjs

@@ -0,0 +1,6 @@
+import "../../index.mjs";
+import "./utils/index.mjs";
+import { log } from "@warlock.js/logger";
+import "openai";
+
+export {  };

package/esm/ai-openai/src/utils/index.mjs

@@ -1,3 +1,4 @@
+import "./to-openai-messages.mjs";
 import "./to-openai-tools.mjs";
 import "./wrap-openai-error.mjs";
 

package/esm/ai-openai/src/utils/to-openai-messages.mjs

@@ -0,0 +1,3 @@
+import "../../../index.mjs";
+
+export {  };

package/esm/ai.d.mts

@@ -12,6 +12,10 @@ import { setAIConfig } from "./config.mjs";
 import { dataset } from "./eval/dataset.mjs";
 import { evalScorers } from "./eval/index.mjs";
 import { humanApproval } from "./human/human-approval.mjs";
+import { image } from "./image/image.mjs";
+import { speech } from "./speech/speech.mjs";
+import { audioFromBuffer, audioFromFile, audioMediaTypeForFilename } from "./transcribe/audio-input.mjs";
+import { transcribe } from "./transcribe/transcribe.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";
@@ -28,8 +32,19 @@ import { orchestrator } from "./orchestrator/orchestrator.mjs";
 import { planner } from "./planner/planner.mjs";
 import { defaultPromptsManager } from "./prompts/prompts-manager.mjs";
 import { rag } from "./rag/rag.mjs";
+import { chunk } from "./rag/chunk/chunk.mjs";
+import { cacheVectorStore } from "./rag/store/cache-vector-store.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 { 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 { skills } from "./skills/skills.mjs";
 import { systemPrompt } from "./system-prompt/system-prompt.mjs";
 import { prompt } from "./prompt/prompt.mjs";
@@ -72,6 +87,18 @@ interface Ai {
   rag: typeof rag & {
     keywordReranker: typeof keywordReranker;
     llmReranker: typeof llmReranker;
+    chunk: typeof chunk;
+    cacheVectorStore: typeof cacheVectorStore;
+    pgVectorStore: typeof pgVectorStore;
+    vectorLiteral: typeof vectorLiteral;
+    loadText: typeof loadText;
+    loadHtml: typeof loadHtml;
+    loadWeb: typeof loadWeb;
+    loadPdf: typeof loadPdf;
+    bm25Rank: typeof bm25Rank;
+    reciprocalRankFusion: typeof reciprocalRankFusion;
+    hybridRank: typeof hybridRank;
+    multiQuery: typeof multiQuery;
   };
   spawnSubAgent: typeof spawnSubAgent;
   router: typeof router;
@@ -81,6 +108,24 @@ interface Ai {
   streamObject: typeof streamObject;
   /** Serve an executable as an SSE HTTP endpoint — production serving primitive (A3). */
   serve: typeof serve;
+  /**
+   * Generate images from a text prompt — the image-output verb of the
+   * output-modality track (Theme I). Wraps an `ImageModelContract` (from
+   * `openai.image(...)` / `google.image(...)`) in the uniform
+   * never-throws `{ data, error, usage, report }` envelope with cost-truth
+   * and observability.
+   */
+  image: typeof image;
+  /** Text-to-speech (TTS) — the audio-output verb of the modality track (Theme I). */
+  speech: typeof speech;
+  /** Speech-to-text (STT / transcription) — the audio-input verb of the modality track (Theme I). */
+  transcribe: typeof transcribe;
+  /** Read an audio file from disk → `AudioInput` for `ai.transcribe` (non-AI file plumbing). */
+  audioFromFile: typeof audioFromFile;
+  /** Package raw audio bytes → `AudioInput` for `ai.transcribe`. */
+  audioFromBuffer: typeof audioFromBuffer;
+  /** Resolve the audio media type from a filename's extension. */
+  audioMediaTypeForFilename: typeof audioMediaTypeForFilename;
   fallbackModel: typeof fallbackModel;
   eval: typeof evalScorers;
   dataset: typeof dataset;

package/esm/ai.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ai.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAuDiB,EAAA;EACf,MAAA,SAAe,WAAA;EACf,IAAA,SAAa,IAAA;EACb,KAAA,SAAc,KAAA;EACd,YAAA,SAAqB,YAAA;EACrB,OAAA,SAAgB,OAAA;EAChB,WAAA,SAAoB,WAAA;EACpB,QAAA,SAAiB,QAAA;EACjB,IAAA,SAAa,IAAA;EACb,UAAA,SAAmB,UAAA;EACnB,IAAA,SAAa,IAAA;EACb,YAAA,SAAqB,YAAA;EACrB,MAAA,SAAe,QAAA;EACf,MAAA,SAAe,MAAA;EACf,OAAA,SAAgB,OAAA;EAChB,GAAA,SAAY,GAAA;IACV,eAAA,SAAwB,eAAA;IACxB,WAAA,SAAoB,WAAA;EAAA;EAEtB,aAAA,SAAsB,aAAA;EACtB,MAAA,SAAe,MAAA;EACf,MAAA,SAAe,MAAA;EACf,KAAA,SAAc,KAAA;EAnBA;EAqBd,YAAA,SAAqB,YAAA;EAnBL;EAqBhB,KAAA,SAAc,KAAA;EACd,aAAA,SAAsB,aAAA;EACtB,IAAA,SAAa,WAAA;EACb,OAAA,SAAgB,OAAA;EAChB,MAAA,SAAe,MAAA;EAnBM;;;;;;;EA2BrB,OAAA,EAAS,UAAA,QAAkB,qBAAA;EAC3B,GAAA,SAAY,GAAA;EACZ,UAAA,SAAmB,UAAA;EACnB,UAAA;IACE,MAAA,SAAe,MAAA;IACf,SAAA,SAAkB,WAAA;IAClB,aAAA,SAAsB,aAAA;IACtB,OAAA,SAAgB,iBAAA;IAChB,OAAA,SAAgB,OAAA;IAChB,wBAAA,SAAiC,wBAAA;EAAA;EAEnC,UAAA;IACE,MAAA,SAAe,MAAA;IACf,EAAA,SAAW,EAAA;IACX,KAAA,SAAc,KAAA;EAAA;EAEhB,QAAA;IACE,MAAA,SAAe,QAAA;IACf,EAAA,SAAW,IAAA;IACX,KAAA,SAAc,OAAA;EAAA;EANH;;;;;;;;EAgBb,KAAA;IACE,QAAA,SAAiB,aAAA;IACjB,MAAA,SAAe,MAAA;IACf,SAAA;MACE,MAAA,SAAe,QAAA;MACf,EAAA,SAAW,IAAA;MACX,KAAA,SAAc,OAAA;IAAA;EAAA;EAtElB;;;;;EA8EA,SAAA,SAAkB,SAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6CP,EAAA,EAmDR,EAAE"}
+{"version":3,"file":"ai.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA6EiB,EAAA;EACf,MAAA,SAAe,WAAA;EACf,IAAA,SAAa,IAAA;EACb,KAAA,SAAc,KAAA;EACd,YAAA,SAAqB,YAAA;EACrB,OAAA,SAAgB,OAAA;EAChB,WAAA,SAAoB,WAAA;EACpB,QAAA,SAAiB,QAAA;EACjB,IAAA,SAAa,IAAA;EACb,UAAA,SAAmB,UAAA;EACnB,IAAA,SAAa,IAAA;EACb,YAAA,SAAqB,YAAA;EACrB,MAAA,SAAe,QAAA;EACf,MAAA,SAAe,MAAA;EACf,OAAA,SAAgB,OAAA;EAChB,GAAA,SAAY,GAAA;IACV,eAAA,SAAwB,eAAA;IACxB,WAAA,SAAoB,WAAA;IACpB,KAAA,SAAc,KAAA;IACd,gBAAA,SAAyB,gBAAA;IACzB,aAAA,SAAsB,aAAA;IACtB,aAAA,SAAsB,aAAA;IACtB,QAAA,SAAiB,QAAA;IACjB,QAAA,SAAiB,QAAA;IACjB,OAAA,SAAgB,OAAA;IAChB,OAAA,SAAgB,OAAA;IAChB,QAAA,SAAiB,QAAA;IACjB,oBAAA,SAA6B,oBAAA;IAC7B,UAAA,SAAmB,UAAA;IACnB,UAAA,SAAmB,UAAA;EAAA;EAErB,aAAA,SAAsB,aAAA;EACtB,MAAA,SAAe,MAAA;EACf,MAAA,SAAe,MAAA;EACf,KAAA,SAAc,KAAA;EAjCC;EAmCf,YAAA,SAAqB,YAAA;EAjCP;EAmCd,KAAA,SAAc,KAAA;EAjCE;;;;;;;EAyChB,KAAA,SAAc,KAAA;EAjCC;EAmCf,MAAA,SAAe,MAAA;EAjCH;EAmCZ,UAAA,SAAmB,UAAA;EAjCG;EAmCtB,aAAA,SAAsB,aAAA;EAjCK;EAmC3B,eAAA,SAAwB,eAAA;EAjCA;EAmCxB,yBAAA,SAAkC,yBAAA;EAClC,aAAA,SAAsB,aAAA;EACtB,IAAA,SAAa,WAAA;EACb,OAAA,SAAgB,OAAA;EAChB,MAAA,SAAe,MAAA;EAjCgB;;;;;;;EAyC/B,OAAA,EAAS,UAAA,QAAkB,qBAAA;EAC3B,GAAA,SAAY,GAAA;EACZ,UAAA,SAAmB,UAAA;EACnB,UAAA;IACE,MAAA,SAAe,MAAA;IACf,SAAA,SAAkB,WAAA;IAClB,aAAA,SAAsB,aAAA;IACtB,OAAA,SAAgB,iBAAA;IAChB,OAAA,SAAgB,OAAA;IAChB,wBAAA,SAAiC,wBAAA;EAAA;EAEnC,UAAA;IACE,MAAA,SAAe,MAAA;IACf,EAAA,SAAW,EAAA;IACX,KAAA,SAAc,KAAA;EAAA;EAEhB,QAAA;IACE,MAAA,SAAe,QAAA;IACf,EAAA,SAAW,IAAA;IACX,KAAA,SAAc,OAAA;EAAA;EAVmB;;;;;;;;EAoBnC,KAAA;IACE,QAAA,SAAiB,aAAA;IACjB,MAAA,SAAe,MAAA;IACf,SAAA;MACE,MAAA,SAAe,QAAA;MACf,EAAA,SAAW,IAAA;MACX,KAAA,SAAc,OAAA;IAAA;EAAA;EArGlB;;;;;EA6GA,SAAA,SAAkB,SAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6CP,EAAA,EAwER,EAAE"}

package/esm/ai.mjs

@@ -21,6 +21,13 @@ import { redis } from "./checkpoint/redis.mjs";
 import { dataset } from "./eval/dataset.mjs";
 import { evalScorers } from "./eval/index.mjs";
 import { human } from "./human/register.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 { guardrail as guardrail$1 } from "./guard/guardrail.mjs";
 import { mockRouter } from "./mock/mock-router.mjs";
 import "./mock/index.mjs";
@@ -35,9 +42,20 @@ import { instruction } from "./system-prompt/instruction.mjs";
 import { persona } from "./system-prompt/persona.mjs";
 import { systemPrompt } from "./system-prompt/system-prompt.mjs";
 import { defaultPromptsManager } 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 { 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 { prompt } from "./prompt/prompt.mjs";
 import "./prompt/index.mjs";
@@ -113,7 +131,19 @@ const ai = {
 	planner,
 	rag: Object.assign(rag, {
 		keywordReranker,
-		llmReranker
+		llmReranker,
+		chunk,
+		cacheVectorStore,
+		pgVectorStore,
+		vectorLiteral,
+		loadText,
+		loadHtml,
+		loadWeb,
+		loadPdf,
+		bm25Rank,
+		reciprocalRankFusion,
+		hybridRank,
+		multiQuery
 	}),
 	spawnSubAgent,
 	router,
@@ -121,6 +151,12 @@ const ai = {
 	batch,
 	streamObject,
 	serve,
+	image,
+	speech,
+	transcribe,
+	audioFromFile,
+	audioFromBuffer,
+	audioMediaTypeForFilename,
 	fallbackModel,
 	eval: evalScorers,
 	dataset,

package/esm/ai.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ai.mjs","names":["checkpointMemory","checkpointPg","checkpointRedis","snapshotMemory","snapshotPg","snapshotRedis","guardrailSuite"],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"sourcesContent":["import { agent } from \"./agent/agent\";\nimport { batch } from \"./batch\";\nimport { streamObject } from \"./object-stream\";\nimport { serve } from \"./serve\";\nimport {\n  checkpointMemory,\n  checkpointPg,\n  checkpointRedis,\n} from \"./checkpoint\";\nimport { setAIConfig } from \"./config\";\nimport { dataset, evalScorers } from \"./eval\";\nimport { humanApproval } from \"./human/human-approval\";\nimport { human } from \"./human/register\";\nimport { resume } from \"./human/resume\";\nimport {\n  interruptMemory,\n  interruptPg,\n  interruptRedis,\n} from \"./human/stores\";\nimport { guardrail as guardrailSuite } from \"./guard/guardrail\";\nimport { budget, readBudgetFallbackSignal } from \"./middleware/builtins/budget\";\nimport { memory } from \"./memory\";\nimport { guardrail } from \"./middleware/builtins/guardrail\";\nimport { semanticCache } from \"./middleware/builtins/semantic-cache\";\nimport { composeMiddleware, forTool } from \"./middleware/helpers\";\nimport { mockRouter } from \"./mock\";\nimport { fallbackModel } from \"./model\";\nimport { orchestrator } from \"./orchestrator\";\nimport { planner } from \"./planner\";\nimport { defaultPromptsManager } from \"./prompts/prompts-manager\";\nimport { rag } from \"./rag\";\nimport { keywordReranker } from \"./rag/rerank/keyword-reranker\";\nimport { llmReranker } from \"./rag/rerank/llm-reranker\";\nimport { spawnSubAgent } from \"./agent/spawn-sub-agent\";\nimport { skills } from \"./skills\";\nimport { prompt } from \"./prompt\";\nimport { vcr } from \"./vcr\";\nimport { snapshotMemory, snapshotPg, snapshotRedis } from \"./snapshot\";\nimport { fanOut, router } from \"./supervisor\";\nimport { supervisor } from \"./supervisor/supervisor\";\nimport { team } from \"./team/team\";\nimport { instruction } from \"./system-prompt/instruction\";\nimport { persona } from \"./system-prompt/persona\";\nimport { systemPrompt } from \"./system-prompt/system-prompt\";\nimport { tool } from \"./tool/tool\";\nimport { step } from \"./workflow/step\";\nimport { workflow } from \"./workflow/workflow\";\n\n/**\n * The shape of the top-level `ai` namespace. Declared as an `interface` (not an\n * inferred `const` type) so satellite packages can attach their verb via\n * `declare module \"@warlock.js/ai\" { interface Ai { … } }` — e.g. `ai.workspace`,\n * `ai.tools`, `ai.mcp`, `ai.human`. The runtime object below is asserted to this\n * type; a satellite assigns its member on import.\n */\nexport interface Ai {\n  config: typeof setAIConfig;\n  tool: typeof tool;\n  agent: typeof agent;\n  systemPrompt: typeof systemPrompt;\n  persona: typeof persona;\n  instruction: typeof instruction;\n  workflow: typeof workflow;\n  step: typeof step;\n  supervisor: typeof supervisor;\n  team: typeof team;\n  orchestrator: typeof orchestrator;\n  memory: typeof memory;\n  skills: typeof skills;\n  planner: typeof planner;\n  rag: typeof rag & {\n    keywordReranker: typeof keywordReranker;\n    llmReranker: typeof llmReranker;\n  };\n  spawnSubAgent: typeof spawnSubAgent;\n  router: typeof router;\n  fanOut: typeof fanOut;\n  batch: typeof batch;\n  /** Structured-output streaming — partial-object snapshots + a strict final parse (A1). */\n  streamObject: typeof streamObject;\n  /** Serve an executable as an SSE HTTP endpoint — production serving primitive (A3). */\n  serve: typeof serve;\n  fallbackModel: typeof fallbackModel;\n  eval: typeof evalScorers;\n  dataset: typeof dataset;\n  prompt: typeof prompt;\n  /**\n   * Process-wide registry of named, versioned `systemPrompt(...)` builders,\n   * keyed by `name@version`. A `systemPrompt(input, { name })` (or any\n   * `.meta({ name })` rename) auto-registers here; `ai.prompts.get(name)` /\n   * `.resolve(name)` reads them back, and `systemPrompt().merge(name)` folds a\n   * registered prompt into a new one.\n   */\n  prompts: ReturnType<typeof defaultPromptsManager>;\n  vcr: typeof vcr;\n  mockRouter: typeof mockRouter;\n  middleware: {\n    budget: typeof budget;\n    guardrail: typeof guardrail;\n    semanticCache: typeof semanticCache;\n    compose: typeof composeMiddleware;\n    forTool: typeof forTool;\n    readBudgetFallbackSignal: typeof readBudgetFallbackSignal;\n  };\n  checkpoint: {\n    memory: typeof checkpointMemory;\n    pg: typeof checkpointPg;\n    redis: typeof checkpointRedis;\n  };\n  snapshot: {\n    memory: typeof snapshotMemory;\n    pg: typeof snapshotPg;\n    redis: typeof snapshotRedis;\n  };\n  /**\n   * Human-in-the-loop tool approval (interrupt / resume).\n   *\n   * - `human.approval(options)` — the `tool.before` approval-gate middleware.\n   * - `human.resume(id, decision, options)` — out-of-process durable resume.\n   * - `human.interrupt.{memory,pg,redis}()` — durable {@link InterruptStore}\n   *   factories (memory ships real; pg/redis are lazy optional peers).\n   */\n  human: {\n    approval: typeof humanApproval;\n    resume: typeof resume;\n    interrupt: {\n      memory: typeof interruptMemory;\n      pg: typeof interruptPg;\n      redis: typeof interruptRedis;\n    };\n  };\n  /**\n   * Content-intelligence guardrail. `ai.guardrail(options)` builds a composed\n   * input / output / tool middleware; `ai.guardrail.{pii,topic,injection,moderation}`\n   * are the built-in detector factories.\n   */\n  guardrail: typeof guardrailSuite;\n}\n\n/**\n * Top-level `ai` namespace — holds built-in factories and user-registered SDK adapters.\n *\n * Factories:\n * - `ai.tool(...)` — wrap an async function with a schema-validated input.\n * - `ai.agent(...)` — build an executable agent from model + tools + prompt.\n * - `ai.systemPrompt(...)` — compose a layered persona + instructions prompt.\n * - `ai.persona(text)` — reusable persona block (can be passed to `systemPrompt`).\n * - `ai.instruction(text)` — reusable instruction block (can be passed to `systemPrompt`).\n * - `ai.orchestrator(...)` — session-state manager wrapped around a supervisor (durable session, drift detection, resume, commands).\n * - `ai.memory(...)` — build an agent-memory store with WORKING (in-run scratch) and SEMANTIC (cache-driver `.similar()` recall) tiers.\n * - `ai.skills(...)` — build a runtime skills library (always-injected metadata catalog + on-demand loadSkill tool).\n * - `ai.planner(...)` — build an executable that generates an ordered plan over registered capabilities, then runs it step-by-step.\n * - `ai.spawnSubAgent(spec)` — thin wrapper that builds a fresh one-shot `agent()` with an optional per-task `budget` and runs the task once. A general primitive (not planner-specific).\n * - `ai.router(...)` — build a supervisor-compatible routing agent from named intents.\n * - `ai.fanOut(unit, count)` — spread one agent/workflow into N intent entries for voting / self-consistency.\n * - `ai.batch(executable, items, opts?)` — run any executable over a dataset with bounded concurrency + per-item retry.\n * - `ai.fallbackModel(models, opts?)` — wrap an ordered model list that fails over to the next on transient provider errors.\n * - `ai.eval.{exact,contains,predicate,judge}(...)` — built-in scorer factories for `agent.eval(...)`.\n * - `ai.mockRouter(decisions, opts?)` — deterministic supervisor `route` callback for tests.\n * - `ai.checkpoint.{memory,pg,redis}()` — durable orchestrator session checkpoint stores.\n * - `ai.snapshot.{memory,pg,redis}()` — supervisor-run snapshot stores for `iterate: true` resume.\n * - `ai.human.approval(...)` / `ai.human.resume(...)` / `ai.human.interrupt.{memory,pg,redis}()` — human-in-the-loop tool approval (interrupt / resume).\n * - `ai.guardrail(options)` + `ai.guardrail.{pii,topic,injection,moderation}(...)` — content-intelligence guardrails (moderation / PII / injection / topic).\n * - `ai.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.\n *\n * @example\n * const alex = ai.persona(\"You are Alex, a TypeScript expert.\");\n * const replyIn = ai.instruction(\"Respond in {{language|English}}.\");\n *\n * const prompt = ai.systemPrompt().persona(alex).instruction(replyIn);\n *\n * const myAgent = ai.agent({\n *   model: ai.openai.model({ name: \"gpt-4o\" }),\n *   systemPrompt: prompt,\n *   tools: [myTool],\n * });\n *\n * const result = await myAgent.execute(\"What is the weather in Cairo?\", {\n *   placeholders: { language: \"Arabic\" },\n * });\n */\nexport const ai = {\n  config: setAIConfig,\n  tool,\n  agent,\n  systemPrompt,\n  persona,\n  instruction,\n  workflow,\n  step,\n  supervisor,\n  team,\n  orchestrator,\n  memory,\n  skills,\n  planner,\n  rag: Object.assign(rag, { keywordReranker, llmReranker }),\n  spawnSubAgent,\n  router,\n  fanOut,\n  batch,\n  streamObject,\n  serve,\n  fallbackModel,\n  eval: evalScorers,\n  dataset,\n  prompt,\n  prompts: defaultPromptsManager(),\n  vcr,\n  mockRouter,\n  middleware: {\n    budget,\n    guardrail,\n    semanticCache,\n    compose: composeMiddleware,\n    forTool,\n    readBudgetFallbackSignal,\n  },\n  checkpoint: {\n    memory: checkpointMemory,\n    pg: checkpointPg,\n    redis: checkpointRedis,\n  },\n  snapshot: {\n    memory: snapshotMemory,\n    pg: snapshotPg,\n    redis: snapshotRedis,\n  },\n  human,\n  guardrail: guardrailSuite,\n  // Asserted (not `: Ai`) so a consumer build that augments `Ai` with a\n  // satellite verb (e.g. `workspace`) doesn't flag this literal as missing it.\n} as Ai;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqLA,MAAa,KAAK;CAChB,QAAQ;CACR;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,KAAK,OAAO,OAAO,KAAK;EAAE;EAAiB;CAAY,CAAC;CACxD;CACA;CACA;CACA;CACA;CACA;CACA;CACA,MAAM;CACN;CACA;CACA,SAAS,sBAAsB;CAC/B;CACA;CACA,YAAY;EACV;EACA;EACA;EACA,SAAS;EACT;EACA;CACF;CACA,YAAY;EACV,QAAQA;EACJC;EACGC;CACT;CACA,UAAU;EACR,QAAQC;EACR,IAAIC;EACJ,OAAOC;CACT;CACA;CACA,WAAWC;AAGb"}
+{"version":3,"file":"ai.mjs","names":["checkpointMemory","checkpointPg","checkpointRedis","snapshotMemory","snapshotPg","snapshotRedis","guardrailSuite"],"sources":["../../../../../../@warlock.js/ai/src/ai.ts"],"sourcesContent":["import { agent } from \"./agent/agent\";\nimport { batch } from \"./batch\";\nimport { streamObject } from \"./object-stream\";\nimport { serve } from \"./serve\";\nimport {\n  checkpointMemory,\n  checkpointPg,\n  checkpointRedis,\n} from \"./checkpoint\";\nimport { setAIConfig } from \"./config\";\nimport { dataset, evalScorers } from \"./eval\";\nimport { humanApproval } from \"./human/human-approval\";\nimport { human } from \"./human/register\";\nimport { image } from \"./image\";\nimport { speech } from \"./speech\";\nimport {\n  audioFromBuffer,\n  audioFromFile,\n  audioMediaTypeForFilename,\n  transcribe,\n} from \"./transcribe\";\nimport { resume } from \"./human/resume\";\nimport {\n  interruptMemory,\n  interruptPg,\n  interruptRedis,\n} from \"./human/stores\";\nimport { guardrail as guardrailSuite } from \"./guard/guardrail\";\nimport { budget, readBudgetFallbackSignal } from \"./middleware/builtins/budget\";\nimport { memory } from \"./memory\";\nimport { guardrail } from \"./middleware/builtins/guardrail\";\nimport { semanticCache } from \"./middleware/builtins/semantic-cache\";\nimport { composeMiddleware, forTool } from \"./middleware/helpers\";\nimport { mockRouter } from \"./mock\";\nimport { fallbackModel } from \"./model\";\nimport { orchestrator } from \"./orchestrator\";\nimport { planner } from \"./planner\";\nimport { defaultPromptsManager } from \"./prompts/prompts-manager\";\nimport {\n  bm25Rank,\n  cacheVectorStore,\n  chunk,\n  hybridRank,\n  keywordReranker,\n  llmReranker,\n  loadHtml,\n  loadPdf,\n  loadText,\n  loadWeb,\n  multiQuery,\n  pgVectorStore,\n  rag,\n  reciprocalRankFusion,\n  vectorLiteral,\n} from \"./rag\";\nimport { spawnSubAgent } from \"./agent/spawn-sub-agent\";\nimport { skills } from \"./skills\";\nimport { prompt } from \"./prompt\";\nimport { vcr } from \"./vcr\";\nimport { snapshotMemory, snapshotPg, snapshotRedis } from \"./snapshot\";\nimport { fanOut, router } from \"./supervisor\";\nimport { supervisor } from \"./supervisor/supervisor\";\nimport { team } from \"./team/team\";\nimport { instruction } from \"./system-prompt/instruction\";\nimport { persona } from \"./system-prompt/persona\";\nimport { systemPrompt } from \"./system-prompt/system-prompt\";\nimport { tool } from \"./tool/tool\";\nimport { step } from \"./workflow/step\";\nimport { workflow } from \"./workflow/workflow\";\n\n/**\n * The shape of the top-level `ai` namespace. Declared as an `interface` (not an\n * inferred `const` type) so satellite packages can attach their verb via\n * `declare module \"@warlock.js/ai\" { interface Ai { … } }` — e.g. `ai.workspace`,\n * `ai.tools`, `ai.mcp`, `ai.human`. The runtime object below is asserted to this\n * type; a satellite assigns its member on import.\n */\nexport interface Ai {\n  config: typeof setAIConfig;\n  tool: typeof tool;\n  agent: typeof agent;\n  systemPrompt: typeof systemPrompt;\n  persona: typeof persona;\n  instruction: typeof instruction;\n  workflow: typeof workflow;\n  step: typeof step;\n  supervisor: typeof supervisor;\n  team: typeof team;\n  orchestrator: typeof orchestrator;\n  memory: typeof memory;\n  skills: typeof skills;\n  planner: typeof planner;\n  rag: typeof rag & {\n    keywordReranker: typeof keywordReranker;\n    llmReranker: typeof llmReranker;\n    chunk: typeof chunk;\n    cacheVectorStore: typeof cacheVectorStore;\n    pgVectorStore: typeof pgVectorStore;\n    vectorLiteral: typeof vectorLiteral;\n    loadText: typeof loadText;\n    loadHtml: typeof loadHtml;\n    loadWeb: typeof loadWeb;\n    loadPdf: typeof loadPdf;\n    bm25Rank: typeof bm25Rank;\n    reciprocalRankFusion: typeof reciprocalRankFusion;\n    hybridRank: typeof hybridRank;\n    multiQuery: typeof multiQuery;\n  };\n  spawnSubAgent: typeof spawnSubAgent;\n  router: typeof router;\n  fanOut: typeof fanOut;\n  batch: typeof batch;\n  /** Structured-output streaming — partial-object snapshots + a strict final parse (A1). */\n  streamObject: typeof streamObject;\n  /** Serve an executable as an SSE HTTP endpoint — production serving primitive (A3). */\n  serve: typeof serve;\n  /**\n   * Generate images from a text prompt — the image-output verb of the\n   * output-modality track (Theme I). Wraps an `ImageModelContract` (from\n   * `openai.image(...)` / `google.image(...)`) in the uniform\n   * never-throws `{ data, error, usage, report }` envelope with cost-truth\n   * and observability.\n   */\n  image: typeof image;\n  /** Text-to-speech (TTS) — the audio-output verb of the modality track (Theme I). */\n  speech: typeof speech;\n  /** Speech-to-text (STT / transcription) — the audio-input verb of the modality track (Theme I). */\n  transcribe: typeof transcribe;\n  /** Read an audio file from disk → `AudioInput` for `ai.transcribe` (non-AI file plumbing). */\n  audioFromFile: typeof audioFromFile;\n  /** Package raw audio bytes → `AudioInput` for `ai.transcribe`. */\n  audioFromBuffer: typeof audioFromBuffer;\n  /** Resolve the audio media type from a filename's extension. */\n  audioMediaTypeForFilename: typeof audioMediaTypeForFilename;\n  fallbackModel: typeof fallbackModel;\n  eval: typeof evalScorers;\n  dataset: typeof dataset;\n  prompt: typeof prompt;\n  /**\n   * Process-wide registry of named, versioned `systemPrompt(...)` builders,\n   * keyed by `name@version`. A `systemPrompt(input, { name })` (or any\n   * `.meta({ name })` rename) auto-registers here; `ai.prompts.get(name)` /\n   * `.resolve(name)` reads them back, and `systemPrompt().merge(name)` folds a\n   * registered prompt into a new one.\n   */\n  prompts: ReturnType<typeof defaultPromptsManager>;\n  vcr: typeof vcr;\n  mockRouter: typeof mockRouter;\n  middleware: {\n    budget: typeof budget;\n    guardrail: typeof guardrail;\n    semanticCache: typeof semanticCache;\n    compose: typeof composeMiddleware;\n    forTool: typeof forTool;\n    readBudgetFallbackSignal: typeof readBudgetFallbackSignal;\n  };\n  checkpoint: {\n    memory: typeof checkpointMemory;\n    pg: typeof checkpointPg;\n    redis: typeof checkpointRedis;\n  };\n  snapshot: {\n    memory: typeof snapshotMemory;\n    pg: typeof snapshotPg;\n    redis: typeof snapshotRedis;\n  };\n  /**\n   * Human-in-the-loop tool approval (interrupt / resume).\n   *\n   * - `human.approval(options)` — the `tool.before` approval-gate middleware.\n   * - `human.resume(id, decision, options)` — out-of-process durable resume.\n   * - `human.interrupt.{memory,pg,redis}()` — durable {@link InterruptStore}\n   *   factories (memory ships real; pg/redis are lazy optional peers).\n   */\n  human: {\n    approval: typeof humanApproval;\n    resume: typeof resume;\n    interrupt: {\n      memory: typeof interruptMemory;\n      pg: typeof interruptPg;\n      redis: typeof interruptRedis;\n    };\n  };\n  /**\n   * Content-intelligence guardrail. `ai.guardrail(options)` builds a composed\n   * input / output / tool middleware; `ai.guardrail.{pii,topic,injection,moderation}`\n   * are the built-in detector factories.\n   */\n  guardrail: typeof guardrailSuite;\n}\n\n/**\n * Top-level `ai` namespace — holds built-in factories and user-registered SDK adapters.\n *\n * Factories:\n * - `ai.tool(...)` — wrap an async function with a schema-validated input.\n * - `ai.agent(...)` — build an executable agent from model + tools + prompt.\n * - `ai.systemPrompt(...)` — compose a layered persona + instructions prompt.\n * - `ai.persona(text)` — reusable persona block (can be passed to `systemPrompt`).\n * - `ai.instruction(text)` — reusable instruction block (can be passed to `systemPrompt`).\n * - `ai.orchestrator(...)` — session-state manager wrapped around a supervisor (durable session, drift detection, resume, commands).\n * - `ai.memory(...)` — build an agent-memory store with WORKING (in-run scratch) and SEMANTIC (cache-driver `.similar()` recall) tiers.\n * - `ai.skills(...)` — build a runtime skills library (always-injected metadata catalog + on-demand loadSkill tool).\n * - `ai.planner(...)` — build an executable that generates an ordered plan over registered capabilities, then runs it step-by-step.\n * - `ai.spawnSubAgent(spec)` — thin wrapper that builds a fresh one-shot `agent()` with an optional per-task `budget` and runs the task once. A general primitive (not planner-specific).\n * - `ai.router(...)` — build a supervisor-compatible routing agent from named intents.\n * - `ai.fanOut(unit, count)` — spread one agent/workflow into N intent entries for voting / self-consistency.\n * - `ai.batch(executable, items, opts?)` — run any executable over a dataset with bounded concurrency + per-item retry.\n * - `ai.fallbackModel(models, opts?)` — wrap an ordered model list that fails over to the next on transient provider errors.\n * - `ai.eval.{exact,contains,predicate,judge}(...)` — built-in scorer factories for `agent.eval(...)`.\n * - `ai.mockRouter(decisions, opts?)` — deterministic supervisor `route` callback for tests.\n * - `ai.checkpoint.{memory,pg,redis}()` — durable orchestrator session checkpoint stores.\n * - `ai.snapshot.{memory,pg,redis}()` — supervisor-run snapshot stores for `iterate: true` resume.\n * - `ai.human.approval(...)` / `ai.human.resume(...)` / `ai.human.interrupt.{memory,pg,redis}()` — human-in-the-loop tool approval (interrupt / resume).\n * - `ai.guardrail(options)` + `ai.guardrail.{pii,topic,injection,moderation}(...)` — content-intelligence guardrails (moderation / PII / injection / topic).\n * - `ai.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.\n *\n * @example\n * const alex = ai.persona(\"You are Alex, a TypeScript expert.\");\n * const replyIn = ai.instruction(\"Respond in {{language|English}}.\");\n *\n * const prompt = ai.systemPrompt().persona(alex).instruction(replyIn);\n *\n * const myAgent = ai.agent({\n *   model: ai.openai.model({ name: \"gpt-4o\" }),\n *   systemPrompt: prompt,\n *   tools: [myTool],\n * });\n *\n * const result = await myAgent.execute(\"What is the weather in Cairo?\", {\n *   placeholders: { language: \"Arabic\" },\n * });\n */\nexport const ai = {\n  config: setAIConfig,\n  tool,\n  agent,\n  systemPrompt,\n  persona,\n  instruction,\n  workflow,\n  step,\n  supervisor,\n  team,\n  orchestrator,\n  memory,\n  skills,\n  planner,\n  rag: Object.assign(rag, {\n    keywordReranker,\n    llmReranker,\n    chunk,\n    cacheVectorStore,\n    pgVectorStore,\n    vectorLiteral,\n    loadText,\n    loadHtml,\n    loadWeb,\n    loadPdf,\n    bm25Rank,\n    reciprocalRankFusion,\n    hybridRank,\n    multiQuery,\n  }),\n  spawnSubAgent,\n  router,\n  fanOut,\n  batch,\n  streamObject,\n  serve,\n  image,\n  speech,\n  transcribe,\n  audioFromFile,\n  audioFromBuffer,\n  audioMediaTypeForFilename,\n  fallbackModel,\n  eval: evalScorers,\n  dataset,\n  prompt,\n  prompts: defaultPromptsManager(),\n  vcr,\n  mockRouter,\n  middleware: {\n    budget,\n    guardrail,\n    semanticCache,\n    compose: composeMiddleware,\n    forTool,\n    readBudgetFallbackSignal,\n  },\n  checkpoint: {\n    memory: checkpointMemory,\n    pg: checkpointPg,\n    redis: checkpointRedis,\n  },\n  snapshot: {\n    memory: snapshotMemory,\n    pg: snapshotPg,\n    redis: snapshotRedis,\n  },\n  human,\n  guardrail: guardrailSuite,\n  // Asserted (not `: Ai`) so a consumer build that augments `Ai` with a\n  // satellite verb (e.g. `workspace`) doesn't flag this literal as missing it.\n} as Ai;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyOA,MAAa,KAAK;CAChB,QAAQ;CACR;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,KAAK,OAAO,OAAO,KAAK;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CACD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,MAAM;CACN;CACA;CACA,SAAS,sBAAsB;CAC/B;CACA;CACA,YAAY;EACV;EACA;EACA;EACA,SAAS;EACT;EACA;CACF;CACA,YAAY;EACV,QAAQA;EACJC;EACGC;CACT;CACA,UAAU;EACR,QAAQC;EACR,IAAIC;EACJ,OAAOC;CACT;CACA;CACA,WAAWC;AAGb"}

package/esm/contracts/agent/agent-options.type.d.mts

@@ -25,7 +25,15 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  * });
  */
 type AgentExecuteOptions<TOutput = unknown> = {
-  /** Prior conversation messages to prepend as context */history?: Message[]; /** Files or URLs to attach to the message */
+  /**
+   * Caller-chosen stable run identifier. Auto-generated (`agent_<rand>`)
+   * when omitted. Load-bearing for durable resume: when `durable` is on,
+   * pass a stable `runId` here (or read the generated one off
+   * `result.report.runId`) so a later `agent.resume(runId)` can find the
+   * snapshot. Mirrors `SupervisorExecuteOptions.runId`.
+   */
+  runId?: string; /** Prior conversation messages to prepend as context */
+  history?: Message[]; /** Files or URLs to attach to the message */
   attachments?: Attachment[];
   /**
    * Trust-boundary policy for {@link attachments} (S1) — overrides
@@ -135,6 +143,18 @@ type AgentExecuteOptions<TOutput = unknown> = {
    */
   sessionId?: string;
 };
+/**
+ * Options accepted by `agent.resume(runId, options?)`.
+ *
+ * `force: true` bypasses the signature drift check — use only when you
+ * have verified the definition change is safe for the in-flight
+ * snapshot. `AgentDriftError` is otherwise thrown without executing
+ * anything. Everything else mirrors {@link AgentExecuteOptions} (e.g.
+ * re-supply a `signal` to keep the resumed run cancellable).
+ */
+type AgentResumeOptions<TOutput = unknown> = AgentExecuteOptions<TOutput> & {
+  /** Bypass the drift check and resume against the changed definition. */force?: boolean;
+};
 //#endregion
-export { AgentExecuteOptions };
+export { AgentExecuteOptions, AgentResumeOptions };
 //# sourceMappingURL=agent-options.type.d.mts.map

package/esm/contracts/agent/agent-options.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent-options.type.ts"],"mappings":";;;;;;;;;;;;;AAyBA;;;;;;;;;;;;;KAAY,mBAAA;EAmF4C,wDAjFtD,OAAA,GAAU,OAAA,IA8FA;EA5FV,WAAA,GAAc,UAAA;EAoG+B;;;;;;EA7F7C,gBAAA,GAAmB,gBAAA,EAAnB;EAEA,YAAA,GAAe,YAAA;EAAf;;;;EAKA,MAAA,GAAS,gBAAA,CAAiB,OAAA;EAyB1B;;;;;;;;;;;;;;;;;;;;;AA0ES;;;EA1ET,cAAA,GAAiB,MAAA;;;;;;;;;;;;;;;;;;;;;EAqBjB,MAAA;8EAEE,WAAA;EAAA;EAGF,YAAA,GAAe,oBAAA;;;;;;;;;;;EAWf,MAAA,GAAS,WAAA;EAET,EAAA,GAAK,OAAA,eACS,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;EAatD,OAAA,GAAU,WAAA;;;;;;;;EAQV,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;EAarB,SAAA;AAAA"}
+{"version":3,"file":"agent-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent-options.type.ts"],"mappings":";;;;;;;;;;;;;AAyBA;;;;;;;;;;;;;KAAY,mBAAA;EA2F4C;;;;;;;EAnFtD,KAAA,WAEA;EAAA,OAAA,GAAU,OAAA,IAEV;EAAA,WAAA,GAAc,UAAA;EAOd;;;;;;EAAA,gBAAA,GAAmB,gBAAA,EAgCnB;EA9BA,YAAA,GAAe,YAAA;EAmDf;;;;EA9CA,MAAA,GAAS,gBAAA,CAAiB,OAAA;EA8DjB;;;;;;;;;;;;;;AAqCA;AAYX;;;;;;;;;EAtFE,cAAA,GAAiB,MAAA;;;;;;;;;;;;;;;;;;;;;EAqBjB,MAAA;8EAEE,WAAA;EAAA;EAGF,YAAA,GAAe,oBAAA;;;;;;;;;;;EAWf,MAAA,GAAS,WAAA;EAET,EAAA,GAAK,OAAA,eACS,aAAA,IAAiB,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;EAatD,OAAA,GAAU,WAAA;;;;;;;;EAQV,kBAAA,GAAqB,wBAAA;;;;;;;;;;;;;EAarB,SAAA;AAAA;;;;;;;;;;KAYU,kBAAA,sBAAwC,mBAAmB,CAAC,OAAA;0EAEtE,KAAA;AAAA"}

package/esm/contracts/agent/agent-snapshot.type.d.mts

@@ -0,0 +1,90 @@
+import { Message } from "../conversation-message.type.mjs";
+import { Usage } from "../result/usage.type.mjs";
+import { ToolCall } from "../result/tool-call.type.mjs";
+import { LLMTrip } from "../result/llm-trip.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/agent/agent-snapshot.type.d.ts
+/**
+ * Lifecycle status of a durable agent run, recorded on the persisted
+ * snapshot so `resume()` can decide whether a run is still in flight.
+ *
+ * - `"running"` — the trip loop is active; a resume is legitimate if
+ *   the process crashed between trip boundaries.
+ * - `"completed"` — the agent terminated successfully; resume is a
+ *   no-op and re-returns the final result rebuilt from the snapshot.
+ * - `"cancelled"` — aborted via `AbortSignal`; resume is allowed (the
+ *   caller decides whether to retry).
+ * - `"failed"` — terminated with an error; resume after the fix.
+ */
+type AgentSnapshotStatus = "running" | "completed" | "cancelled" | "failed";
+/**
+ * Persisted shape written to the configured {@link
+ * import("../orchestrator/snapshot-store.contract").SnapshotStore} after
+ * every trip settles. Exists so `agent.resume(runId)` can re-hydrate the
+ * assembled conversation + completed trips + tool calls + running usage
+ * and continue the trip loop from the next `tripIndex`.
+ *
+ * **Checkpoint granularity is per-trip.** The snapshot is written at the
+ * end of `runTrip`, after every tool the trip requested has been
+ * dispatched and its result message appended — the only point in the
+ * loop where `messages`, `trips`, `toolCalls`, and `usage` are mutually
+ * consistent. A crash mid-trip loses only that in-flight trip (never
+ * checkpointed), which the resumed run re-issues cleanly.
+ *
+ * `signature` is a structural fingerprint covering model + provider +
+ * sorted tool names + maxTrips + output presence + version (see
+ * {@link import("../../agent/signature").computeAgentSignature}).
+ * `resume()` compares it against the current agent's signature; a
+ * mismatch throws `AgentDriftError` (bypassable with `{ force: true }`).
+ *
+ * Every field is JSON-serializable — `Message`, `LLMTrip`, `ToolCall`,
+ * and `Usage` are the same plain-data shapes already persisted on
+ * reports, so the snapshot round-trips through any `SnapshotStore`
+ * backend (`memory`, `pg`, `redis`) verbatim.
+ *
+ * @example
+ * const snapshot: AgentSnapshot | undefined = await store.load(runId);
+ * if (snapshot?.status === "running") {
+ *   await agent.resume(runId);
+ * }
+ */
+type AgentSnapshot = {
+  /** The store key — stable across the whole run. */runId: string; /** Resolved agent name, for the resume error message + attribution. */
+  agentName: string; /** Structural drift fingerprint (see `computeAgentSignature`). */
+  signature: string; /** `AgentConfig.version` — metadata only, never compared. */
+  version?: string; /** The original `execute(input)` value — needed to rebuild context. */
+  input: string;
+  /**
+   * The resolved system-prompt text captured once on the first run, so
+   * a resume skips `buildInitialMessages` (the messages array already
+   * holds the system turn). Absent when the agent had no prompt.
+   */
+  systemPrompt?: string;
+  /**
+   * The wire-level JSON Schema sent to the model for structured output,
+   * captured so resume re-issues continuation trips with the identical
+   * response contract. Absent when the agent produced untyped output.
+   */
+  responseSchema?: Record<string, unknown>; /** Registry name of the resolved named prompt, when one was used. */
+  promptName?: string; /** Registry version label paired with {@link AgentSnapshot.promptName}. */
+  promptVersion?: string;
+  /**
+   * The live conversation array — assistant turns (with `toolCalls`)
+   * plus tool-result turns — assembled across the persisted trips.
+   * Re-hydrated verbatim so the next trip sees the full history.
+   */
+  messages: Message[];
+  /**
+   * Every settled trip so far. `trips.length` is the next `tripIndex`
+   * the resumed loop starts at, so completed trips never re-run.
+   */
+  trips: LLMTrip[]; /** Every settled tool dispatch (flat, each carrying its `tripIndex`). */
+  toolCalls: ToolCall[]; /** Running usage total across the persisted trips — never double-counted. */
+  usage: Usage;
+  status: AgentSnapshotStatus;
+  startedAt: string;
+  savedAt: string;
+};
+//#endregion
+export { AgentSnapshot, AgentSnapshotStatus };
+//# sourceMappingURL=agent-snapshot.type.d.mts.map

package/esm/contracts/agent/agent-snapshot.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-snapshot.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent-snapshot.type.ts"],"mappings":";;;;;;;;AAiBA;;;;AAA+B;AAqC/B;;;;;KArCY,mBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiFH;;;KA5CG,aAAA;qDAEV,KAAA;EAEA,SAAA;EAEA,SAAA;EAEA,OAAA;EAEA,KAAA;;;;;;EAMA,YAAA;;;;;;EAMA,cAAA,GAAiB,MAAA;EAEjB,UAAA;EAEA,aAAA;;;;;;EAMA,QAAA,EAAU,OAAA;;;;;EAKV,KAAA,EAAO,OAAA;EAEP,SAAA,EAAW,QAAA;EAEX,KAAA,EAAO,KAAA;EACP,MAAA,EAAQ,mBAAA;EACR,SAAA;EACA,OAAA;AAAA"}

package/esm/contracts/agent/agent.contract.d.mts

@@ -3,7 +3,7 @@ import { ExecutableContract } from "../executable.contract.mjs";
 import { StreamContract } from "../stream/stream.contract.mjs";
 import { EvalOptions, EvalReport } from "./eval.type.mjs";
 import { AgentEventMap } from "../events/event-map.type.mjs";
-import { AgentExecuteOptions } from "./agent-options.type.mjs";
+import { AgentExecuteOptions, AgentResumeOptions } from "./agent-options.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/agent/agent.contract.d.ts
 /**
@@ -71,11 +71,39 @@ interface AgentContract<TOutput = unknown> extends ExecutableContract<string, Ag
    * `AgentConfig.description` at factory time.
    */
   readonly description?: string;
+  /**
+   * Structural drift fingerprint of the agent definition — model +
+   * provider + sorted tool names + maxTrips + output presence + version.
+   * Stamped on every durable snapshot and compared on `resume()`; a
+   * mismatch throws `AgentDriftError`. Always populated (computed at
+   * factory time), independent of whether `durable` is configured.
+   */
+  readonly signature: string;
   /**
    * Stream execution events in real time.
    * Yields typed StreamEvent values and resolves result when done.
    */
   stream(input: string, options?: AgentExecuteOptions<TOutput>): StreamContract<AgentResult<TOutput>>;
+  /**
+   * Resume a durable run after a crash. Loads the snapshot persisted
+   * under `runId` (requires `durable` on the config, or a global
+   * `defaultSnapshotStore`), re-hydrates the completed trips + tool
+   * calls + usage, and continues the trip loop from the next trip —
+   * never re-issuing a completed trip's model call or re-invoking its
+   * tools. A resume of an already-settled run re-returns the stored
+   * result without running anything.
+   *
+   * Refuses to continue when the current definition has structurally
+   * drifted from the snapshot (`AgentDriftError`), unless
+   * `{ force: true }` is passed. Throws `AgentExecutionError` when no
+   * store is configured or no snapshot exists for `runId`.
+   *
+   * @example
+   * const result = await writer.execute("research X", { runId: "run-42" });
+   * // ...process crashes mid-run...
+   * const recovered = await writer.resume("run-42");
+   */
+  resume(runId: string, options?: AgentResumeOptions<TOutput>): Promise<AgentResult<TOutput>>;
   /**
    * Subscribe a handler to a single event name for the lifetime of
    * this agent instance. Returns an unsubscribe function; calling it

package/esm/contracts/agent/agent.contract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent.contract.ts"],"mappings":";;;;;;;;;;AAWA;;KAAY,iBAAA,iBAAkC,aAAA,KAC5C,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AAyC3B;;;;;;;;;;;;;;;;;;;;;;;;;;UAAiB,aAAA,4BAAyC,kBAAA,SAExD,mBAAA,CAAoB,OAAA,GACpB,WAAA,CAAY,OAAA;EAH8D;;;;;;;;EAAA,SAajE,IAAA;EAMA;;;;;EAAA,SAAA,WAAA;EAaP;;;;;EAAA,SAPO,WAAA;EAeU;;;;EAVnB,MAAA,CACE,KAAA,UACA,OAAA,GAAU,mBAAA,CAAoB,OAAA,IAC7B,cAAA,CAAe,WAAA,CAAY,OAAA;EAS5B;;;;;EAFF,EAAA,iBAAmB,aAAA,EACjB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;EASlB;;;;EAFX,GAAA,iBAAoB,aAAA,EAClB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;EA4ChB;;;;;;;;AAA+D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA5E,IAAA,SAAa,OAAA,EAAS,OAAA,EAAS,WAAA,CAAY,KAAA,IAAS,OAAA,CAAQ,UAAA,CAAW,KAAA;AAAA"}
+{"version":3,"file":"agent.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/agent/agent.contract.ts"],"mappings":";;;;;;;;;;AAWA;;KAAY,iBAAA,iBAAkC,aAAA,KAC5C,OAAA,EAAS,aAAA,CAAc,CAAA;;;;;;;;;;;;AAAE;AAyC3B;;;;;;;;;;;;;;;;;;;;;;;;;;UAAiB,aAAA,4BAAyC,kBAAA,SAExD,mBAAA,CAAoB,OAAA,GACpB,WAAA,CAAY,OAAA;EA4HmB;;;;;;;;EAAA,SAlHtB,IAAA;EAXT;;;;;EAAA,SAiBS,WAAA;EAMA;;;;;EAAA,SAAA,WAAA;EAeP;;;;;;;EAAA,SAPO,SAAA;EA+BP;;;;EA1BF,MAAA,CACE,KAAA,UACA,OAAA,GAAU,mBAAA,CAAoB,OAAA,IAC7B,cAAA,CAAe,WAAA,CAAY,OAAA;EA+B3B;;;;;;;;;;;;;;;;;;;EAVH,MAAA,CACE,KAAA,UACA,OAAA,GAAU,kBAAA,CAAmB,OAAA,IAC5B,OAAA,CAAQ,WAAA,CAAY,OAAA;EA8DD;;;;;EAvDtB,EAAA,iBAAmB,aAAA,EACjB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;;;;;EAO7B,GAAA,iBAAoB,aAAA,EAClB,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,iBAAA,CAAkB,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4C7B,IAAA,SAAa,OAAA,EAAS,OAAA,EAAS,WAAA,CAAY,KAAA,IAAS,OAAA,CAAQ,UAAA,CAAW,KAAA;AAAA"}

package/esm/contracts/agent/index.d.mts

@@ -1,3 +1,4 @@
 import { EvalCase, EvalCaseResult, EvalJudge, EvalOptions, EvalReport, EvalScore, EvalScorer, EvalScorerContext } from "./eval.type.mjs";
 import { AgentContract, AgentEventHandler } from "./agent.contract.mjs";
-import { AgentExecuteOptions } from "./agent-options.type.mjs";
+import { AgentExecuteOptions, AgentResumeOptions } from "./agent-options.type.mjs";
+import { AgentSnapshot, AgentSnapshotStatus } from "./agent-snapshot.type.mjs";