@warlock.js/core 4.8.0 → 4.8.1

package/esm/ai/src/agent/json-stream-guard.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"json-stream-guard.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/agent/json-stream-guard.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { ModelToolCallRequest } from \"../contracts/model-tool-call-request.type\";\nimport type { ToolContract } from \"../tool/tool\";\n\n/**\n * Default cap on bytes accumulated in a single suspect buffer before\n * the guard gives up, flushes as text, and resets to pass-through.\n * Real envelope payloads observed in production leaks are well under\n * 1 KB; this is a safety valve against runaway / adversarial input.\n */\nconst DEFAULT_MAX_BUFFER_BYTES = 4096;\n\n/**\n * Fence opener the guard recognizes in pass-through mode. Targets the\n * lowercase form ```` ```json ```` only — that is the form models\n * actually emit in the wild when they fence-wrap a JSON tool envelope.\n * Other languages / casings flush as plain text.\n */\nconst FENCE_OPENER = \"```json\";\n\n/**\n * Closing fence sequence inside `bufferingFence` mode. Three backticks,\n * no language tag.\n */\nconst FENCE_CLOSER = \"```\";\n\n/**\n * Options passed when constructing a `JsonStreamGuard`.\n *\n * The guard is deliberately framework-agnostic of *how* deltas are\n * emitted or how recovered calls are dispatched — callers wire those\n * via `onSafeDelta` / `onRecoveredCall`. This keeps the unit-testable\n * surface tiny and lets the agent loop own all event-emission policy.\n */\nexport type JsonStreamGuardOptions = {\n  /** Tools the agent has registered for this trip. Envelope lookups use `.name`. */\n  tools: ReadonlyArray<ToolContract<unknown, unknown>>;\n  /**\n   * Hard cap on a single suspect buffer's size. When exceeded, the\n   * buffer is flushed verbatim as text and the guard returns to\n   * pass-through. Defaults to {@link DEFAULT_MAX_BUFFER_BYTES}.\n   */\n  maxBufferBytes?: number;\n  /**\n   * Called for every chunk of text that survived the guard — exactly\n   * what the consumer should treat as the visible delta. May be\n   * called many times per `feed()` call, possibly with a single\n   * character or with a multi-character flush.\n   */\n  onSafeDelta: (delta: string) => void;\n  /**\n   * Called once per envelope the guard successfully classifies as a\n   * tool-call recovery. The request carries `recoveredFrom:\n   * \"stream-text\"` so downstream consumers can distinguish synthesized\n   * calls from real ones.\n   */\n  onRecoveredCall: (request: ModelToolCallRequest) => void;\n};\n\n/**\n * Per-trip state machine that intercepts streamed text deltas, detects\n * JSON envelopes the model has emitted as plain text (the\n * tool-call-leakage symptom), and synthesizes real `ModelToolCallRequest`\n * entries for them while suppressing the JSON from visible output.\n *\n * **Role.** A `JsonStreamGuard` is the per-trip implementation of the\n * opt-in `streamingToolGuard` config. It sits between the model\n * adapter's `delta` chunks and the agent's `agent.trip.streaming`\n * emit + `content` accumulator — text that survives the guard is what\n * the consumer sees and what the trip records as `output`.\n *\n * **Responsibility.**\n * - Owns: a small character-level state machine (pass-through,\n *   brace-buffering, fence-buffering), string-literal-aware brace\n *   tracking, fence-opener / fence-closer detection, named-envelope\n *   matching against registered tool schemas, buffer-cap enforcement.\n * - Does NOT own: event emission (delegated via callbacks), tool\n *   dispatch, `finishReason` normalization, dedupe vs. real tool\n *   calls — the agent loop handles all four.\n *\n * **Matcher tier — named envelope only (v1).** A buffer matches when\n * it parses as a JSON object containing both:\n *   - a `name` or `tool` key resolving to a registered tool name, AND\n *   - an `arguments` or `input` key whose value validates against the\n *     resolved tool's `~standard` schema.\n * Bare-object matching (where any registered tool's schema is the\n * sole signal) is deferred until tool input schemas are tight enough\n * to distinguish — `v.record(v.any())` would match everything.\n *\n * **Per-trip lifecycle.** One instance per trip. The agent loop calls\n * `feed(chunk)` for every `delta` chunk and `finalize()` exactly once\n * after the stream's `done` chunk. Mid-stream cancellation: the loop\n * simply stops calling `feed`; any open buffer is discarded with the\n * guard instance.\n *\n * Modeled as a class (see §4.2 of code-style.md — per-call execution\n * state across phases): the machine has 3 states, accumulators for\n * brace depth, string-literal escape tracking, and a synthesized-call\n * counter for stable ids across the trip.\n *\n * @example\n * // Inside the agent's streaming trip body:\n * const guard = new JsonStreamGuard({\n *   tools: this.config.tools ?? [],\n *   maxBufferBytes: guardConfig.maxBufferBytes,\n *   onSafeDelta: (delta) => {\n *     content += delta;\n *     this.emit(\"agent.trip.streaming\", { delta, tripIndex });\n *   },\n *   onRecoveredCall: (request) => recoveredCalls.push(request),\n * });\n *\n * for await (const chunk of model.stream(messages, callOptions)) {\n *   if (chunk.type === \"delta\") await guard.feed(chunk.content);\n *   // ... other chunk types\n * }\n *\n * await guard.finalize();\n */\nexport class JsonStreamGuard {\n  private readonly tools: ReadonlyArray<ToolContract<unknown, unknown>>;\n  private readonly maxBufferBytes: number;\n  private readonly onSafeDelta: (delta: string) => void;\n  private readonly onRecoveredCall: (request: ModelToolCallRequest) => void;\n\n  private mode: \"passThrough\" | \"bufferingBrace\" | \"bufferingFence\" = \"passThrough\";\n\n  /**\n   * Characters held back in pass-through mode while we resolve whether\n   * a partial fence opener (`` ` ``, `` `` ``, `` ``` ``, `` ```j ``, …)\n   * will complete or break. Always a strict prefix of {@link FENCE_OPENER};\n   * emptied (and emitted verbatim) the moment a non-matching character\n   * arrives.\n   */\n  private holdback = \"\";\n\n  /**\n   * Accumulator while `mode === \"bufferingBrace\"` or `\"bufferingFence\"`.\n   * In brace mode it carries the JSON including the outermost `{`/`}`.\n   * In fence mode it carries everything between the opener and the\n   * closer (the opener and closer themselves are NOT in the buffer —\n   * they are reconstructed only on a flush-as-text fallback).\n   */\n  private buffer = \"\";\n\n  /**\n   * Brace-depth counter for `bufferingBrace` mode. Increments on `{`,\n   * decrements on `}` — but only when {@link inString} is false, so a\n   * `{` inside a JSON string literal does not skew the depth. Buffer\n   * closes when depth returns to zero.\n   */\n  private braceDepth = 0;\n\n  /** True while the scanner is inside a `\"...\"` JSON string literal. */\n  private inString = false;\n\n  /**\n   * True when the previous character inside a string literal was a\n   * backslash, so the current character is escaped (`\\\"` does not end\n   * the string; `\\\\` resets the flag without escaping anything else).\n   */\n  private escapeNext = false;\n\n  /**\n   * Trailing tail of the fence buffer used to detect the closing\n   * ```` ``` ```` sequence. Length capped at the closer length; rotated\n   * forward as new characters arrive.\n   */\n  private fenceCloseTail = \"\";\n\n  /**\n   * Count of envelopes the guard has successfully synthesized this\n   * trip. Used to assign deterministic, collision-free ids on\n   * recovered `ModelToolCallRequest` entries.\n   */\n  private recoveredCount = 0;\n\n  public constructor(options: JsonStreamGuardOptions) {\n    this.tools = options.tools;\n    this.maxBufferBytes = options.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;\n    this.onSafeDelta = options.onSafeDelta;\n    this.onRecoveredCall = options.onRecoveredCall;\n  }\n\n  /**\n   * Feed the next raw delta from the model. Splits the chunk into\n   * characters and runs each through the state machine, awaiting\n   * envelope classification whenever a buffer closes mid-chunk.\n   *\n   * The hot path (pass-through prose with no `{` / `` ` ``) is fully\n   * synchronous — `await` here only blocks at buffer-close points,\n   * which are rare in normal traffic.\n   */\n  public async feed(chunk: string): Promise<void> {\n    for (let i = 0; i < chunk.length; i++) {\n      await this.processChar(chunk[i]);\n    }\n  }\n\n  /**\n   * Stream ended. Anything still in the holdback was prose\n   * misclassified as a partial fence opener — emit it. Anything still\n   * in an open buffer never closed — emit it as text too (a leak\n   * truncated mid-flight is still text the user partially saw).\n   */\n  public async finalize(): Promise<void> {\n    if (this.holdback.length > 0) {\n      this.onSafeDelta(this.holdback);\n      this.holdback = \"\";\n    }\n\n    if (this.mode === \"bufferingBrace\") {\n      this.flushBraceBufferAsText();\n      return;\n    }\n\n    if (this.mode === \"bufferingFence\") {\n      this.flushFenceBufferAsText();\n    }\n  }\n\n  /**\n   * True when at least one envelope was recovered this trip. The\n   * agent loop reads this to override `finishReason` from `\"stop\"` to\n   * `\"tool_calls\"` when the model reported a natural stop but the\n   * guard found tool calls hiding in the text channel.\n   */\n  public hasRecoveredCalls(): boolean {\n    return this.recoveredCount > 0;\n  }\n\n  /**\n   * Route a single character based on the current mode. The\n   * `passThrough` branch handles holdback expansion / flushing\n   * iteratively (no recursion) so a character that \"breaks\" a fence\n   * opener can be re-evaluated as a fresh pass-through input in the\n   * same call.\n   */\n  private async processChar(char: string): Promise<void> {\n    if (this.mode === \"bufferingBrace\") {\n      await this.processBraceChar(char);\n      return;\n    }\n\n    if (this.mode === \"bufferingFence\") {\n      await this.processFenceChar(char);\n      return;\n    }\n\n    let current = char;\n\n    while (true) {\n      if (this.holdback.length === 0 && current === \"{\") {\n        this.openBraceBuffer(current);\n        return;\n      }\n\n      const extended = this.holdback + current;\n\n      if (this.isFenceOpenerPrefix(extended)) {\n        this.holdback = extended;\n\n        if (extended === FENCE_OPENER) {\n          this.openFenceBuffer();\n        }\n\n        return;\n      }\n\n      if (this.holdback.length === 0) {\n        this.onSafeDelta(current);\n        return;\n      }\n\n      this.onSafeDelta(this.holdback);\n      this.holdback = \"\";\n    }\n  }\n\n  /**\n   * Recognize any strict prefix of {@link FENCE_OPENER} including the\n   * full string. Used to decide whether to keep extending the holdback\n   * or flush it as plain text.\n   */\n  private isFenceOpenerPrefix(candidate: string): boolean {\n    return candidate.length <= FENCE_OPENER.length && FENCE_OPENER.startsWith(candidate);\n  }\n\n  /**\n   * Enter `bufferingBrace` mode with the seed `{` as the first buffer\n   * character and the initial brace depth set to one. Any holdback at\n   * this point was already a non-fence sequence so it stays empty.\n   */\n  private openBraceBuffer(seed: string): void {\n    this.mode = \"bufferingBrace\";\n    this.buffer = seed;\n    this.braceDepth = 1;\n    this.inString = false;\n    this.escapeNext = false;\n  }\n\n  /**\n   * Enter `bufferingFence` mode immediately after the opener\n   * ```` ```json ```` matched in the holdback. Holdback resets;\n   * subsequent characters accumulate into the buffer until the\n   * closing fence is seen.\n   */\n  private openFenceBuffer(): void {\n    this.mode = \"bufferingFence\";\n    this.buffer = \"\";\n    this.fenceCloseTail = \"\";\n    this.holdback = \"\";\n  }\n\n  /**\n   * Process one character while accumulating a brace-delimited JSON\n   * object. Tracks string-literal context so `{` / `}` inside `\"...\"`\n   * do not skew brace depth. Closes (and classifies) on balanced\n   * braces; flushes-as-text on cap overflow.\n   */\n  private async processBraceChar(char: string): Promise<void> {\n    this.buffer += char;\n\n    if (this.inString) {\n      if (this.escapeNext) {\n        this.escapeNext = false;\n        return;\n      }\n\n      if (char === \"\\\\\") {\n        this.escapeNext = true;\n        return;\n      }\n\n      if (char === '\"') {\n        this.inString = false;\n      }\n\n      this.guardBufferCap(\"brace\");\n      return;\n    }\n\n    if (char === '\"') {\n      this.inString = true;\n      this.guardBufferCap(\"brace\");\n      return;\n    }\n\n    if (char === \"{\") {\n      this.braceDepth++;\n      this.guardBufferCap(\"brace\");\n      return;\n    }\n\n    if (char === \"}\") {\n      this.braceDepth--;\n\n      if (this.braceDepth === 0) {\n        await this.closeBraceBuffer();\n        return;\n      }\n\n      this.guardBufferCap(\"brace\");\n      return;\n    }\n\n    this.guardBufferCap(\"brace\");\n  }\n\n  /**\n   * Process one character while accumulating a fence-delimited JSON\n   * block. The closing fence ```` ``` ```` ends the block; the closing\n   * characters are NOT included in the classified buffer (they are\n   * re-emitted only when the block flushes back to text).\n   */\n  private async processFenceChar(char: string): Promise<void> {\n    this.fenceCloseTail += char;\n\n    if (this.fenceCloseTail.length > FENCE_CLOSER.length) {\n      this.fenceCloseTail = this.fenceCloseTail.slice(-FENCE_CLOSER.length);\n    }\n\n    if (this.fenceCloseTail === FENCE_CLOSER) {\n      const innerLength = this.buffer.length - (FENCE_CLOSER.length - 1);\n      this.buffer = this.buffer.slice(0, Math.max(0, innerLength));\n\n      await this.closeFenceBuffer();\n      return;\n    }\n\n    this.buffer += char;\n    this.guardBufferCap(\"fence\");\n  }\n\n  /**\n   * Enforce the buffer-byte cap. When the current buffer exceeds the\n   * cap, flush it back to the consumer as plain text and reset to\n   * pass-through. Acts as a runaway / adversarial-input safety valve.\n   */\n  private guardBufferCap(source: \"brace\" | \"fence\"): void {\n    if (this.buffer.length <= this.maxBufferBytes) {\n      return;\n    }\n\n    if (source === \"brace\") {\n      this.flushBraceBufferAsText();\n      return;\n    }\n\n    this.flushFenceBufferAsText();\n  }\n\n  /**\n   * Run the envelope matcher against the closed brace buffer. On a\n   * match, synthesize a recovered `ModelToolCallRequest`; on no\n   * match, flush the buffer back as plain text. Resets state to\n   * pass-through either way.\n   */\n  private async closeBraceBuffer(): Promise<void> {\n    const closed = this.buffer;\n\n    this.resetToPassThrough();\n\n    const matched = await this.tryMatchEnvelope(closed);\n\n    if (matched) {\n      return;\n    }\n\n    this.onSafeDelta(closed);\n  }\n\n  /**\n   * Run the envelope matcher against the closed fence buffer. On a\n   * match, synthesize a recovered call; on no match, flush as text\n   * **with** the original opener and closer reconstructed so the\n   * customer sees exactly the markdown the model emitted.\n   */\n  private async closeFenceBuffer(): Promise<void> {\n    const closed = this.buffer;\n\n    this.resetToPassThrough();\n\n    const matched = await this.tryMatchEnvelope(closed);\n\n    if (matched) {\n      return;\n    }\n\n    this.onSafeDelta(`${FENCE_OPENER}${closed}${FENCE_CLOSER}`);\n  }\n\n  /**\n   * Emit the brace-buffer verbatim as text and reset to pass-through.\n   * Used on cap overflow and on `finalize()` for an unclosed buffer.\n   */\n  private flushBraceBufferAsText(): void {\n    const closed = this.buffer;\n    this.resetToPassThrough();\n    this.onSafeDelta(closed);\n  }\n\n  /**\n   * Emit the fence-buffer verbatim as text, reconstructing the\n   * opener and closer so the original markdown structure is\n   * preserved for the consumer.\n   */\n  private flushFenceBufferAsText(): void {\n    const closed = this.buffer;\n    this.resetToPassThrough();\n    this.onSafeDelta(`${FENCE_OPENER}${closed}`);\n  }\n\n  /**\n   * Reset all per-buffer state back to the pass-through baseline.\n   * Called whenever a buffer closes — by recovery, by flush, or by\n   * cap overflow — so the next character starts a fresh scan.\n   */\n  private resetToPassThrough(): void {\n    this.mode = \"passThrough\";\n    this.buffer = \"\";\n    this.braceDepth = 0;\n    this.inString = false;\n    this.escapeNext = false;\n    this.fenceCloseTail = \"\";\n  }\n\n  /**\n   * Attempt to classify a closed buffer as a tool-call envelope. On\n   * success, invoke `onRecoveredCall` with a synthesized request and\n   * return `true`; on failure return `false` so the caller can flush\n   * the buffer back as text.\n   */\n  private async tryMatchEnvelope(raw: string): Promise<boolean> {\n    const parsed = safeParseJson(raw);\n\n    if (parsed === undefined || typeof parsed !== \"object\" || parsed === null) {\n      return false;\n    }\n\n    const envelope = parsed as Record<string, unknown>;\n    const candidateName = readString(envelope, \"name\") ?? readString(envelope, \"tool\");\n    const candidateInput = readObject(envelope, \"arguments\") ?? readObject(envelope, \"input\");\n\n    if (!candidateName || !candidateInput) {\n      return false;\n    }\n\n    const tool = this.tools.find((entry) => entry.name === candidateName);\n\n    if (!tool || !tool.input) {\n      return false;\n    }\n\n    const schema = tool.input as StandardSchemaV1<unknown>;\n\n    let validationResult: StandardSchemaV1.Result<unknown>;\n\n    try {\n      validationResult = await schema[\"~standard\"].validate(candidateInput);\n    } catch {\n      return false;\n    }\n\n    if (validationResult.issues) {\n      return false;\n    }\n\n    this.recoveredCount++;\n\n    this.onRecoveredCall({\n      id: `synth_${candidateName}_${this.recoveredCount}`,\n      name: candidateName,\n      input: validationResult.value,\n      recoveredFrom: \"stream-text\",\n    });\n\n    return true;\n  }\n}\n\n/**\n * Parse a JSON string returning `undefined` on any failure. Local to\n * the guard so it can distinguish \"not JSON\" from a parsed `null`\n * value, which `safeJsonParse` cannot — a parsed `null` is a valid\n * JSON value but not a valid envelope, and we want the difference.\n */\nfunction safeParseJson(raw: string): unknown {\n  try {\n    return JSON.parse(raw);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Read a string-typed field from an envelope candidate. Returns\n * `undefined` when the key is missing or the value is non-string —\n * the matcher rejects either case.\n */\nfunction readString(envelope: Record<string, unknown>, key: string): string | undefined {\n  const value = envelope[key];\n\n  return typeof value === \"string\" && value.length > 0 ? value : undefined;\n}\n\n/**\n * Read an object-typed field from an envelope candidate. Returns\n * `undefined` when the key is missing or the value is not a\n * plain object (rejects arrays, primitives, null) — tool input\n * schemas always validate against an object root.\n */\nfunction readObject(\n  envelope: Record<string, unknown>,\n  key: string,\n): Record<string, unknown> | undefined {\n  const value = envelope[key];\n\n  if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n    return undefined;\n  }\n\n  return value as Record<string, unknown>;\n}\n"],"mappings":"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"}

package/esm/ai/src/agent/signature.mjs

@@ -1,57 +0,0 @@
-//#region ../@warlock.js/ai/src/agent/signature.ts
-/**
-* Deterministic structural fingerprint of an agent definition.
-* Persisted on every durable snapshot so `agent.resume()` can detect
-* drift between the saved run and the current definition. Covers the
-* fields whose change would make a mid-run resume unsafe — i.e. would
-* make the persisted `messages` / `toolCalls` array inconsistent with
-* what the resumed trip loop would produce:
-*
-* - Model name + provider — a different model invalidates the prior
-*   conversation's continuation.
-* - The sorted tool names — adding / removing / renaming a tool changes
-*   which dispatches the persisted `toolCalls` could have come from.
-* - `maxTrips` — the loop bound is a semantic shape change.
-* - Whether a default `output` schema is configured — flips the
-*   structured-output instruction baked into the system turn.
-* - `version` — dev-curated; a bump is an explicit "this changed" signal.
-*
-* Does NOT cover: system-prompt text, middleware, per-event handlers,
-* placeholders, modelOptions — runtime knobs that don't change the
-* shape of a resumable run. Mirrors `supervisor/signature.ts`'s coarse
-* structural philosophy and reuses its FNV-1a `hash`.
-*
-* `tools` here is read off the resolved config (post-normalization), so
-* raw executables dropped into `tools: []` are already adapted to
-* `ToolContract`s carrying a stable `name`.
-*/
-function computeAgentSignature(config) {
-	const toolNames = (config.tools ?? []).map((tool) => tool.name).sort((a, b) => a.localeCompare(b));
-	const fingerprint = {
-		n: config.name ?? null,
-		p: config.model?.provider ?? null,
-		m: config.model?.name ?? null,
-		t: toolNames,
-		x: config.maxTrips ?? null,
-		o: config.output ? 1 : 0,
-		v: config.version ?? null
-	};
-	return hash(JSON.stringify(fingerprint));
-}
-/**
-* FNV-1a 32-bit — the same hash `supervisor/signature.ts` and
-* `workflow/signature.ts` use. Deterministic, no crypto dependency,
-* cheap; signatures are 8-char hex.
-*/
-function hash(input) {
-	let h = 2166136261;
-	for (let i = 0; i < input.length; i++) {
-		h ^= input.charCodeAt(i);
-		h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
-	}
-	return h.toString(16).padStart(8, "0");
-}
-
-//#endregion
-export { computeAgentSignature };
-//# sourceMappingURL=signature.mjs.map

package/esm/ai/src/agent/signature.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"signature.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/agent/signature.ts"],"sourcesContent":["import type { AgentConfig } from \"./agent-config.type\";\n\n/**\n * Deterministic structural fingerprint of an agent definition.\n * Persisted on every durable snapshot so `agent.resume()` can detect\n * drift between the saved run and the current definition. Covers the\n * fields whose change would make a mid-run resume unsafe — i.e. would\n * make the persisted `messages` / `toolCalls` array inconsistent with\n * what the resumed trip loop would produce:\n *\n * - Model name + provider — a different model invalidates the prior\n *   conversation's continuation.\n * - The sorted tool names — adding / removing / renaming a tool changes\n *   which dispatches the persisted `toolCalls` could have come from.\n * - `maxTrips` — the loop bound is a semantic shape change.\n * - Whether a default `output` schema is configured — flips the\n *   structured-output instruction baked into the system turn.\n * - `version` — dev-curated; a bump is an explicit \"this changed\" signal.\n *\n * Does NOT cover: system-prompt text, middleware, per-event handlers,\n * placeholders, modelOptions — runtime knobs that don't change the\n * shape of a resumable run. Mirrors `supervisor/signature.ts`'s coarse\n * structural philosophy and reuses its FNV-1a `hash`.\n *\n * `tools` here is read off the resolved config (post-normalization), so\n * raw executables dropped into `tools: []` are already adapted to\n * `ToolContract`s carrying a stable `name`.\n */\nexport function computeAgentSignature(config: {\n  name?: string;\n  version?: AgentConfig[\"version\"];\n  model: { name?: string; provider?: string };\n  tools?: ReadonlyArray<{ name: string }>;\n  maxTrips?: number;\n  output?: unknown;\n}): string {\n  const toolNames = (config.tools ?? [])\n    .map((tool) => tool.name)\n    .sort((a, b) => a.localeCompare(b));\n\n  const fingerprint = {\n    n: config.name ?? null,\n    p: config.model?.provider ?? null,\n    m: config.model?.name ?? null,\n    t: toolNames,\n    x: config.maxTrips ?? null,\n    o: config.output ? 1 : 0,\n    v: config.version ?? null,\n  };\n\n  return hash(JSON.stringify(fingerprint));\n}\n\n/**\n * FNV-1a 32-bit — the same hash `supervisor/signature.ts` and\n * `workflow/signature.ts` use. Deterministic, no crypto dependency,\n * cheap; signatures are 8-char hex.\n */\nfunction hash(input: string): string {\n  let h = 0x811c9dc5;\n\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;\n  }\n\n  return h.toString(16).padStart(8, \"0\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,sBAAsB,QAO3B;CACT,MAAM,aAAa,OAAO,SAAS,CAAC,EAAC,CAClC,KAAK,SAAS,KAAK,IAAI,CAAC,CACxB,MAAM,GAAG,MAAM,EAAE,cAAc,CAAC,CAAC;CAEpC,MAAM,cAAc;EAClB,GAAG,OAAO,QAAQ;EAClB,GAAG,OAAO,OAAO,YAAY;EAC7B,GAAG,OAAO,OAAO,QAAQ;EACzB,GAAG;EACH,GAAG,OAAO,YAAY;EACtB,GAAG,OAAO,SAAS,IAAI;EACvB,GAAG,OAAO,WAAW;CACvB;CAEA,OAAO,KAAK,KAAK,UAAU,WAAW,CAAC;AACzC;;;;;;AAOA,SAAS,KAAK,OAAuB;CACnC,IAAI,IAAI;CAER,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,KAAK,MAAM,WAAW,CAAC;EACvB,IAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,SAAU;CACxE;CAEA,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;AACvC"}

package/esm/ai/src/agent/snapshot.mjs

@@ -1,101 +0,0 @@
-import { AgentExecutionError } from "../errors/agent-execution-error.mjs";
-import { AgentDriftError } from "../errors/agent-drift-error.mjs";
-import "../errors/index.mjs";
-import { resolveDefaultSnapshotStore } from "../config.mjs";
-
-//#region ../@warlock.js/ai/src/agent/snapshot.ts
-/**
-* Resolve the effective {@link SnapshotStore}: the agent's own
-* `durable.store` wins; absent that, fall back to the global default
-* set via `ai.config({ defaultSnapshotStore })`.
-*
-* The global default is typed for the supervisor snapshot shape, but
-* every store impl keys purely by `runId` and round-trips whatever
-* envelope it is handed — so it serves an `AgentSnapshot` just as well.
-* The cast re-tags the shape at this single boundary (Option B); the
-* agent only ever hands it an `AgentSnapshot`.
-*/
-function resolveSnapshotStore(durable) {
-	return durable?.store ?? resolveDefaultSnapshotStore();
-}
-/**
-* Write the current run state to the resolved snapshot store. No-op
-* (returns `{ ok: true }`) when neither `durable.store` nor the global
-* `defaultSnapshotStore` is configured — the common non-durable path.
-* Failures are returned as `{ ok: false }` rather than thrown so the
-* engine can surface them via logs without aborting the run — a failed
-* checkpoint loses resume-ability from that point but never breaks an
-* otherwise-healthy run.
-*/
-async function persistAgentSnapshot(params) {
-	const store = resolveSnapshotStore(params.durable);
-	if (!store) return { ok: true };
-	const snapshot = {
-		runId: params.runId,
-		agentName: params.agentName,
-		signature: params.signature,
-		version: params.version,
-		input: params.input,
-		systemPrompt: params.systemPrompt,
-		responseSchema: params.responseSchema,
-		promptName: params.promptName,
-		promptVersion: params.promptVersion,
-		messages: params.messages,
-		trips: params.trips,
-		toolCalls: params.toolCalls,
-		usage: params.usage,
-		status: params.status,
-		startedAt: params.startedAt,
-		savedAt: (/* @__PURE__ */ new Date()).toISOString()
-	};
-	try {
-		await store.save(snapshot);
-		return { ok: true };
-	} catch (error) {
-		return {
-			ok: false,
-			error
-		};
-	}
-}
-/**
-* Delete a persisted snapshot — used after a successful run when
-* `durable.deleteOnComplete` is set. Never throws: a failed delete is
-* surfaced as `{ ok: false }` and the engine logs it. No-op (ok) when no
-* store is configured.
-*/
-async function deleteAgentSnapshot(params) {
-	const store = resolveSnapshotStore(params.durable);
-	if (!store) return { ok: true };
-	try {
-		await store.delete(params.runId);
-		return { ok: true };
-	} catch (error) {
-		return {
-			ok: false,
-			error
-		};
-	}
-}
-/**
-* Load a persisted snapshot for `resume()` and run the drift check.
-* Throws `AgentExecutionError` when no store is configured or when the
-* run is missing; throws `AgentDriftError` when the stored signature
-* doesn't match the current definition (unless `force` is set).
-*/
-async function loadAgentSnapshotForResume(params) {
-	const store = resolveSnapshotStore(params.durable);
-	if (!store) throw new AgentExecutionError(`agent "${params.agentName}" has no durable store configured — set \`durable: { store }\` on the config or call \`ai.config({ defaultSnapshotStore })\` at boot before calling resume()`, { context: { runId: params.runId } });
-	const snapshot = await store.load(params.runId) ?? null;
-	if (!snapshot) throw new AgentExecutionError(`agent "${params.agentName}": no snapshot for runId "${params.runId}"`, { context: { runId: params.runId } });
-	if (!params.options?.force && snapshot.signature !== params.signature) throw new AgentDriftError(`agent "${params.agentName}" signature drift on resume`, {
-		savedSignature: snapshot.signature,
-		currentSignature: params.signature,
-		runId: params.runId
-	});
-	return snapshot;
-}
-
-//#endregion
-export { deleteAgentSnapshot, loadAgentSnapshotForResume, persistAgentSnapshot };
-//# sourceMappingURL=snapshot.mjs.map

package/esm/ai/src/agent/snapshot.mjs.map

@@ -1 +0,0 @@
-{"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/src/agent/spawn-sub-agent.mjs

@@ -1,68 +0,0 @@
-import { budget } from "../middleware/builtins/budget.mjs";
-import { agent } from "./agent.mjs";
-
-//#region ../@warlock.js/ai/src/agent/spawn-sub-agent.ts
-/**
-* Build a fresh agent, run a single subtask through it once, and return
-* the unified {@link AgentResult}. Equivalent to
-* `agent({ ...spec, middleware: spec.budget && [budget(spec.budget)] }).execute(spec.task, { output, signal, sessionId })`.
-*
-* **Role.** A general-purpose "build, run, discard" primitive: a caller
-* (an agent tool, a workflow step, a planner step, a route callback, or
-* hand-rolled orchestration) hands a self-contained subtask to a
-* single-use agent created just for it, instead of reusing a long-lived
-* agent. The spawned `report` slots under the caller's
-* `report.children[]` like any executable, so cost and traces roll up
-* uniformly. It is not tied to any one primitive — it depends only on
-* `agent()` and the optional `budget` middleware.
-*
-* **What it is NOT.** Not a sandbox or a separate runtime. Each spawn is
-* a plain new `agent()` — its fresh conversation, own tools, and own
-* middleware state are ordinary new-instance behavior, not special
-* isolation (every `agent()` already has them). It is also a *narrower*
-* surface than `agent.execute`: one-shot, with no `history`,
-* `placeholders`, per-call event handlers, or `repair`. Reach for it when
-* you want a named single-use delegation with a per-task budget cap;
-* otherwise just construct an `agent()` and call it.
-*
-* Never throws on runtime failure — the agent surfaces failures on
-* `result.error` and a `"failed"` / `"cancelled"` report status.
-*
-* @example
-* const result = await spawnSubAgent({
-*   name: "extract-entities",
-*   model,
-*   task: "Pull every company name from this article: ...",
-*   budget: { maxCostUSD: 0.05 },
-*   output: z.object({ companies: z.array(z.string()) }),
-* });
-*/
-async function spawnSubAgent(spec) {
-	const subAgent = buildSubAgent(spec);
-	const options = {};
-	if (spec.output !== void 0) options.output = spec.output;
-	if (spec.signal !== void 0) options.signal = spec.signal;
-	if (spec.sessionId !== void 0) options.sessionId = spec.sessionId;
-	return subAgent.execute(spec.task, options);
-}
-/**
-* Construct the fresh agent for one spawn. Attaches a `budget`
-* middleware only when a cap was requested, so the common no-budget case
-* is just a plain agent.
-*/
-function buildSubAgent(spec) {
-	const middleware = spec.budget !== void 0 ? [budget(spec.budget)] : void 0;
-	return agent({
-		name: spec.name,
-		model: spec.model,
-		systemPrompt: spec.systemPrompt,
-		tools: spec.tools,
-		maxTrips: spec.maxTrips,
-		output: spec.output,
-		middleware
-	});
-}
-
-//#endregion
-export { spawnSubAgent };
-//# sourceMappingURL=spawn-sub-agent.mjs.map

package/esm/ai/src/agent/spawn-sub-agent.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"spawn-sub-agent.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/agent/spawn-sub-agent.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { AgentExecuteOptions } from \"../contracts/agent/agent-options.type\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { AgentResult } from \"../contracts/result/agent-result.type\";\nimport type { ModelContract } from \"../contracts/model.contract\";\nimport type { SystemPromptContract } from \"../contracts/system-prompt.contract\";\nimport { budget, type BudgetOptions } from \"../middleware/builtins/budget\";\nimport type { AgentToolEntry } from \"../tool/executable-as-tool\";\nimport { agent } from \"./agent\";\n\n/**\n * Spec for `spawnSubAgent` — a one-shot agent invocation. `spawnSubAgent`\n * is a thin convenience wrapper: it builds a fresh `agent()` from this\n * spec, optionally attaches a `budget` middleware, runs the `task` once,\n * and returns the `AgentResult`. There is no separate \"sub-agent\" runtime\n * — a spawn is an ordinary new `agent()` instance, so it starts from an\n * empty conversation with its own tools/prompt exactly the way every\n * `agent()` does.\n *\n * `budget` is the one field that adds something a bare `agent()` config\n * doesn't already give you ergonomically: a first-class per-task\n * cost/token cap. When set, the spawn runs under a `budget` middleware\n * that aborts the moment a cap is crossed, so a delegated subtask cannot\n * overrun its allowance. (Equivalent to passing\n * `middleware: [budget(...)]` to a plain agent — this just promotes it to\n * a spec field.) Distinct from `maxTrips`, which caps round-trips, not spend.\n */\nexport type SpawnSubAgentSpec<TOutput = unknown> = {\n  /** Stable identifier for the spawned agent. */\n  name: string;\n  /** The model the sub-agent runs against. */\n  model: ModelContract;\n  /** The subtask instruction handed to the sub-agent's `execute()`. */\n  task: string;\n  /** Optional system prompt scoping the sub-agent's behavior. */\n  systemPrompt?: SystemPromptContract | string;\n  /** Tools the spawned agent may call inside its own loop (a fresh agent, so not shared with the caller). */\n  tools?: AgentToolEntry<unknown, unknown>[];\n  /** Per-spawn round-trip cap. Forwarded to the agent. Defaults to the agent default. */\n  maxTrips?: number;\n  /**\n   * Per-task budget. When set, the spawn runs under a `budget` middleware\n   * that aborts once a cap (`maxTokens` / `maxCostUSD`) is crossed — a\n   * spend ceiling scoped to this one subtask. Because each spawn is its\n   * own `agent()` instance, that ledger starts fresh per spawn.\n   */\n  budget?: BudgetOptions;\n  /** Structured-output schema validated into `result.data`. */\n  output?: StandardSchemaV1<TOutput>;\n  /** Cancellation handle threaded into the sub-agent run. */\n  signal?: AbortSignal;\n  /**\n   * Session identifier propagated onto the sub-agent's report tree so\n   * the spawned run groups under the parent's session in flat trace\n   * queries.\n   */\n  sessionId?: string;\n};\n\n/**\n * Build a fresh agent, run a single subtask through it once, and return\n * the unified {@link AgentResult}. Equivalent to\n * `agent({ ...spec, middleware: spec.budget && [budget(spec.budget)] }).execute(spec.task, { output, signal, sessionId })`.\n *\n * **Role.** A general-purpose \"build, run, discard\" primitive: a caller\n * (an agent tool, a workflow step, a planner step, a route callback, or\n * hand-rolled orchestration) hands a self-contained subtask to a\n * single-use agent created just for it, instead of reusing a long-lived\n * agent. The spawned `report` slots under the caller's\n * `report.children[]` like any executable, so cost and traces roll up\n * uniformly. It is not tied to any one primitive — it depends only on\n * `agent()` and the optional `budget` middleware.\n *\n * **What it is NOT.** Not a sandbox or a separate runtime. Each spawn is\n * a plain new `agent()` — its fresh conversation, own tools, and own\n * middleware state are ordinary new-instance behavior, not special\n * isolation (every `agent()` already has them). It is also a *narrower*\n * surface than `agent.execute`: one-shot, with no `history`,\n * `placeholders`, per-call event handlers, or `repair`. Reach for it when\n * you want a named single-use delegation with a per-task budget cap;\n * otherwise just construct an `agent()` and call it.\n *\n * Never throws on runtime failure — the agent surfaces failures on\n * `result.error` and a `\"failed\"` / `\"cancelled\"` report status.\n *\n * @example\n * const result = await spawnSubAgent({\n *   name: \"extract-entities\",\n *   model,\n *   task: \"Pull every company name from this article: ...\",\n *   budget: { maxCostUSD: 0.05 },\n *   output: z.object({ companies: z.array(z.string()) }),\n * });\n */\nexport async function spawnSubAgent<TOutput = unknown>(\n  spec: SpawnSubAgentSpec<TOutput>,\n): Promise<AgentResult<TOutput>> {\n  const subAgent = buildSubAgent<TOutput>(spec);\n\n  const options: AgentExecuteOptions<TOutput> = {};\n\n  if (spec.output !== undefined) {\n    options.output = spec.output;\n  }\n\n  if (spec.signal !== undefined) {\n    options.signal = spec.signal;\n  }\n\n  if (spec.sessionId !== undefined) {\n    options.sessionId = spec.sessionId;\n  }\n\n  return subAgent.execute(spec.task, options);\n}\n\n/**\n * Construct the fresh agent for one spawn. Attaches a `budget`\n * middleware only when a cap was requested, so the common no-budget case\n * is just a plain agent.\n */\nfunction buildSubAgent<TOutput>(spec: SpawnSubAgentSpec<TOutput>): AgentContract<TOutput> {\n  const middleware = spec.budget !== undefined ? [budget(spec.budget)] : undefined;\n\n  return agent<TOutput>({\n    name: spec.name,\n    model: spec.model,\n    systemPrompt: spec.systemPrompt,\n    tools: spec.tools,\n    maxTrips: spec.maxTrips,\n    output: spec.output,\n    middleware,\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,eAAsB,cACpB,MAC+B;CAC/B,MAAM,WAAW,cAAuB,IAAI;CAE5C,MAAM,UAAwC,CAAC;CAE/C,IAAI,KAAK,WAAW,QAClB,QAAQ,SAAS,KAAK;CAGxB,IAAI,KAAK,WAAW,QAClB,QAAQ,SAAS,KAAK;CAGxB,IAAI,KAAK,cAAc,QACrB,QAAQ,YAAY,KAAK;CAG3B,OAAO,SAAS,QAAQ,KAAK,MAAM,OAAO;AAC5C;;;;;;AAOA,SAAS,cAAuB,MAA0D;CACxF,MAAM,aAAa,KAAK,WAAW,SAAY,CAAC,OAAO,KAAK,MAAM,CAAC,IAAI;CAEvE,OAAO,MAAe;EACpB,MAAM,KAAK;EACX,OAAO,KAAK;EACZ,cAAc,KAAK;EACnB,OAAO,KAAK;EACZ,UAAU,KAAK;EACf,QAAQ,KAAK;EACb;CACF,CAAC;AACH"}

package/esm/ai/src/ai.mjs

@@ -1,191 +0,0 @@
-import { budget, readBudgetFallbackSignal } from "./middleware/builtins/budget.mjs";
-import { guardrail } from "./middleware/builtins/guardrail.mjs";
-import { 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 { tool } from "./tool/tool.mjs";
-import { skills } from "./skills/skills.mjs";
-import { memory } from "./memory/memory.mjs";
-import "./skills/index.mjs";
-import { agent } from "./agent/agent.mjs";
-import { spawnSubAgent } from "./agent/spawn-sub-agent.mjs";
-import { batch } from "./batch/batch.mjs";
-import "./batch/index.mjs";
-import { streamObject } from "./object-stream/stream-object.mjs";
-import "./object-stream/index.mjs";
-import { serve } from "./serve/serve.mjs";
-import { memory as memory$1 } from "./checkpoint/memory.mjs";
-import { pg } from "./checkpoint/pg.mjs";
-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";
-import { fallbackModel } from "./model/fallback-model.mjs";
-import "./model/index.mjs";
-import { supervisor } from "./supervisor/supervisor.mjs";
-import { orchestrator } from "./orchestrator/orchestrator.mjs";
-import "./orchestrator/index.mjs";
-import { planner } from "./planner/planner.mjs";
-import "./planner/index.mjs";
-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";
-import { vcr } from "./vcr/vcr.mjs";
-import "./vcr/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 { team } from "./team/team.mjs";
-import { step } from "./workflow/step.mjs";
-import { workflow } from "./workflow/workflow.mjs";
-
-//#region ../@warlock.js/ai/src/ai.ts
-/**
-* Top-level `ai` namespace — holds built-in factories and user-registered SDK adapters.
-*
-* Factories:
-* - `ai.tool(...)` — wrap an async function with a schema-validated input.
-* - `ai.agent(...)` — build an executable agent from model + tools + prompt.
-* - `ai.systemPrompt(...)` — compose a layered persona + instructions prompt.
-* - `ai.persona(text)` — reusable persona block (can be passed to `systemPrompt`).
-* - `ai.instruction(text)` — reusable instruction block (can be passed to `systemPrompt`).
-* - `ai.orchestrator(...)` — session-state manager wrapped around a supervisor (durable session, drift detection, resume, commands).
-* - `ai.memory(...)` — build an agent-memory store with WORKING (in-run scratch) and SEMANTIC (cache-driver `.similar()` recall) tiers.
-* - `ai.skills(...)` — build a runtime skills library (always-injected metadata catalog + on-demand loadSkill tool).
-* - `ai.planner(...)` — build an executable that generates an ordered plan over registered capabilities, then runs it step-by-step.
-* - `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).
-* - `ai.router(...)` — build a supervisor-compatible routing agent from named intents.
-* - `ai.fanOut(unit, count)` — spread one agent/workflow into N intent entries for voting / self-consistency.
-* - `ai.batch(executable, items, opts?)` — run any executable over a dataset with bounded concurrency + per-item retry.
-* - `ai.fallbackModel(models, opts?)` — wrap an ordered model list that fails over to the next on transient provider errors.
-* - `ai.eval.{exact,contains,predicate,judge}(...)` — built-in scorer factories for `agent.eval(...)`.
-* - `ai.mockRouter(decisions, opts?)` — deterministic supervisor `route` callback for tests.
-* - `ai.checkpoint.{memory,pg,redis}()` — durable orchestrator session checkpoint stores.
-* - `ai.snapshot.{memory,pg,redis}()` — supervisor-run snapshot stores for `iterate: true` resume.
-* - `ai.human.approval(...)` / `ai.human.resume(...)` / `ai.human.interrupt.{memory,pg,redis}()` — human-in-the-loop tool approval (interrupt / resume).
-* - `ai.guardrail(options)` + `ai.guardrail.{pii,topic,injection,moderation}(...)` — content-intelligence guardrails (moderation / PII / injection / topic).
-* - `ai.openai.model(...)` / `ai.anthropic.model(...)` / ... once the adapter SDK is registered.
-*
-* @example
-* const alex = ai.persona("You are Alex, a TypeScript expert.");
-* const replyIn = ai.instruction("Respond in {{language|English}}.");
-*
-* const prompt = ai.systemPrompt().persona(alex).instruction(replyIn);
-*
-* const myAgent = ai.agent({
-*   model: ai.openai.model({ name: "gpt-4o" }),
-*   systemPrompt: prompt,
-*   tools: [myTool],
-* });
-*
-* const result = await myAgent.execute("What is the weather in Cairo?", {
-*   placeholders: { language: "Arabic" },
-* });
-*/
-const ai = {
-	config: setAIConfig,
-	tool,
-	agent,
-	systemPrompt,
-	persona,
-	instruction,
-	workflow,
-	step,
-	supervisor,
-	team,
-	orchestrator,
-	memory,
-	skills,
-	planner,
-	rag: Object.assign(rag, {
-		keywordReranker,
-		llmReranker,
-		chunk,
-		cacheVectorStore,
-		pgVectorStore,
-		vectorLiteral,
-		loadText,
-		loadHtml,
-		loadWeb,
-		loadPdf,
-		bm25Rank,
-		reciprocalRankFusion,
-		hybridRank,
-		multiQuery
-	}),
-	spawnSubAgent,
-	router,
-	fanOut,
-	batch,
-	streamObject,
-	serve,
-	image,
-	speech,
-	transcribe,
-	audioFromFile,
-	audioFromBuffer,
-	audioMediaTypeForFilename,
-	fallbackModel,
-	eval: evalScorers,
-	dataset,
-	prompt,
-	prompts: defaultPromptsManager(),
-	vcr,
-	mockRouter,
-	middleware: {
-		budget,
-		guardrail,
-		semanticCache,
-		compose: composeMiddleware,
-		forTool,
-		readBudgetFallbackSignal
-	},
-	checkpoint: {
-		memory: memory$1,
-		pg,
-		redis
-	},
-	snapshot: {
-		memory: memory$2,
-		pg: pg$1,
-		redis: redis$1
-	},
-	human,
-	guardrail: guardrail$1
-};
-
-//#endregion
-export { ai };
-//# sourceMappingURL=ai.mjs.map

package/esm/ai/src/ai.mjs.map

@@ -1 +0,0 @@
-{"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"}