@warlock.js/core 4.3.0 → 4.5.0

package/esm/ai/src/model/fallback-model.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-model.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/model/fallback-model.ts"],"sourcesContent":["import type {\n  FallbackAttempt,\n  FallbackModelContract,\n  FallbackModelOptions,\n  FallbackRetryPredicate,\n} from \"../contracts/fallback-model.contract\";\nimport type { Message } from \"../contracts/conversation-message.type\";\nimport type {\n  ModelCallOptions,\n  ModelCapabilities,\n  ModelContract,\n  ModelResponse,\n  ModelStreamChunk,\n} from \"../contracts/model.contract\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AIError } from \"../errors/ai-error\";\nimport type { AIErrorCode } from \"../errors/error-code.type\";\nimport { accumulateCost } from \"../utils/compute-cost\";\n\n/**\n * Error codes treated as transient — and therefore worth falling over\n * to the next model — when the caller does not supply an explicit\n * `retryOn`. Covers provider rate-limits, timeouts, and the generic\n * `PROVIDER_ERROR` catch-all that adapters throw for 5xx / unknown\n * network failures. Deliberately omits auth, invalid-request,\n * context-length, and content-filter: those fail identically on every\n * downstream model, so retrying only burns budget.\n */\nconst DEFAULT_RETRYABLE_CODES: readonly AIErrorCode[] = [\n  \"PROVIDER_RATE_LIMIT\",\n  \"PROVIDER_TIMEOUT\",\n  \"PROVIDER_ERROR\",\n];\n\n/**\n * A `ModelContract` that wraps an ordered list of models and tries each\n * in turn, advancing to the next only when the current one fails with a\n * matching (transient) provider error.\n *\n * **Role.** A drop-in `ModelContract` for resilience: hand it to any\n * agent / workflow / supervisor in place of a single model and provider\n * outages, rate-limits, and timeouts transparently fail over to a\n * backup. Non-transient failures (bad key, oversized prompt, blocked\n * content) re-throw immediately rather than wastefully retrying.\n *\n * **What it owns / doesn't own.** Owns the ordered model list, the\n * retry decision, and per-call usage aggregation across attempted\n * models. Does NOT own retry/backoff timing (it advances instantly to\n * the next model — pair it with a backoff middleware if you want delay)\n * nor any provider I/O of its own; every call is delegated to a wrapped\n * model.\n *\n * **Streaming fall-over caveat.** `stream()` can only fail over while no\n * chunk has been emitted yet. Once the first `delta` / `tool-call`\n * reaches the consumer, the partial output cannot be un-sent, so a\n * mid-stream failure propagates instead of restarting on the next\n * model.\n *\n * @example\n * const model = fallbackModel([\n *   ai.openai.model({ name: \"gpt-4o\" }),\n *   ai.anthropic.model({ name: \"claude-3-5-sonnet\" }),\n * ]);\n * const agent = ai.agent({ model });\n *\n * @example\n * // custom retry predicate\n * const model = fallbackModel([primary, backup], {\n *   retryOn: (error) => error instanceof ProviderError,\n * });\n */\nexport function fallbackModel(\n  models: ModelContract[],\n  options?: FallbackModelOptions,\n): FallbackModelContract {\n  if (models.length === 0) {\n    throw new AIError(\n      \"PROVIDER_INVALID_REQUEST\",\n      \"fallbackModel() requires at least one model in the chain.\",\n      undefined,\n      \"validation\",\n    );\n  }\n\n  return new FallbackModel(models, resolveShouldRetry(options?.retryOn));\n}\n\n/**\n * Build the chain-advancement predicate from the caller's `retryOn`.\n * An array becomes a code membership test against an `AIError.code`; a\n * function is used verbatim; absence falls back to the transient\n * default set.\n */\nfunction resolveShouldRetry(\n  retryOn: FallbackModelOptions[\"retryOn\"],\n): FallbackRetryPredicate {\n  if (typeof retryOn === \"function\") {\n    return retryOn;\n  }\n\n  const codes: readonly AIErrorCode[] = retryOn ?? DEFAULT_RETRYABLE_CODES;\n\n  return (error: unknown): boolean => {\n    return error instanceof AIError && codes.includes(error.code);\n  };\n}\n\n/**\n * Add a successful call's usage into a running aggregate, mirroring the\n * agent's trip accumulation: scalar token counts sum, optional channels\n * sum only when present, and cost merges via `accumulateCost` so an\n * unpriced model never erases a priced sibling's cost.\n */\nfunction aggregateUsage(total: Usage, next: Usage): void {\n  total.input += next.input;\n  total.output += next.output;\n  total.total += next.total;\n\n  if (next.cachedTokens !== undefined) {\n    total.cachedTokens = (total.cachedTokens ?? 0) + next.cachedTokens;\n  }\n\n  if (next.reasoningTokens !== undefined) {\n    total.reasoningTokens = (total.reasoningTokens ?? 0) + next.reasoningTokens;\n  }\n\n  if (next.cacheWriteTokens !== undefined) {\n    total.cacheWriteTokens = (total.cacheWriteTokens ?? 0) + next.cacheWriteTokens;\n  }\n\n  total.cost = accumulateCost(total.cost, next.cost);\n}\n\n/**\n * Internal `ModelContract` implementation backing {@link fallbackModel}.\n *\n * Long-lived (its identity, capabilities, and pricing front the primary\n * model for the wrapper's whole lifetime) so it is a class rather than a\n * closure. Per-call mutable state (the usage aggregate, the attempt log)\n * lives in {@link FallbackRun}, instantiated fresh on every\n * `complete()` / `stream()` so concurrent calls never share bookkeeping.\n */\nclass FallbackModel implements FallbackModelContract {\n  public readonly name: string;\n  public readonly provider: string;\n  public readonly capabilities?: ModelCapabilities;\n  public readonly pricing?: ModelContract[\"pricing\"];\n\n  private latestAttempts: FallbackAttempt[] = [];\n\n  public constructor(\n    private readonly models: ModelContract[],\n    private readonly shouldRetry: FallbackRetryPredicate,\n  ) {\n    const primary = models[0]!;\n\n    this.name = primary.name;\n    this.provider = primary.provider;\n    this.capabilities = primary.capabilities;\n    this.pricing = primary.pricing;\n  }\n\n  /**\n   * Models that failed with a chain-advancing error during the most\n   * recent `complete()` / `stream()` call, in attempt order. Empty when\n   * the primary model succeeded outright. Overwritten on each call.\n   */\n  public get lastAttempts(): FallbackAttempt[] {\n    return this.latestAttempts;\n  }\n\n  public async complete(\n    messages: Message[],\n    options?: ModelCallOptions,\n  ): Promise<ModelResponse> {\n    const run = new FallbackRun(this.models, this.shouldRetry);\n    const response = await run.complete(messages, options);\n\n    this.latestAttempts = run.attempts;\n\n    return response;\n  }\n\n  public stream(\n    messages: Message[],\n    options?: ModelCallOptions,\n  ): AsyncIterable<ModelStreamChunk> {\n    const run = new FallbackRun(this.models, this.shouldRetry);\n\n    return run.stream(messages, options, (attempts) => {\n      this.latestAttempts = attempts;\n    });\n  }\n}\n\n/**\n * Per-call execution of the fallback chain. Holds the usage aggregate\n * and the attempt log for a single `complete()` / `stream()` invocation\n * so the long-lived {@link FallbackModel} stays free of shared mutable\n * state across concurrent calls.\n */\nclass FallbackRun {\n  public readonly attempts: FallbackAttempt[] = [];\n\n  private readonly usage: Usage = { input: 0, output: 0, total: 0 };\n\n  public constructor(\n    private readonly models: ModelContract[],\n    private readonly shouldRetry: FallbackRetryPredicate,\n  ) {}\n\n  /**\n   * Try each model's `complete()` in order. On a chain-advancing error,\n   * record the attempt and move to the next; on the last model (or a\n   * non-retryable error) re-throw the underlying error verbatim so the\n   * caller still sees a typed `AIError` with its original code.\n   */\n  public async complete(\n    messages: Message[],\n    options?: ModelCallOptions,\n  ): Promise<ModelResponse> {\n    for (let index = 0; index < this.models.length; index++) {\n      const model = this.models[index]!;\n      const isLast = index === this.models.length - 1;\n\n      try {\n        const response = await model.complete(messages, options);\n\n        aggregateUsage(this.usage, response.usage);\n\n        return { ...response, usage: this.usage };\n      } catch (error) {\n        if (isLast || !this.shouldRetry(error)) {\n          throw error;\n        }\n\n        this.recordAttempt(model, error);\n      }\n    }\n\n    throw new AIError(\n      \"PROVIDER_ERROR\",\n      \"fallbackModel() exhausted its chain without producing a response.\",\n      undefined,\n      \"provider\",\n    );\n  }\n\n  /**\n   * Try each model's `stream()` in order. Fall-over is only attempted\n   * while no chunk has been emitted yet for the current model — once the\n   * consumer has seen a `delta` / `tool-call`, a mid-stream failure\n   * propagates instead of restarting (partial output cannot be un-sent).\n   * The aggregated usage replaces the `done` chunk's usage so the caller\n   * sees the chain total.\n   */\n  public async *stream(\n    messages: Message[],\n    options: ModelCallOptions | undefined,\n    onSettle: (attempts: FallbackAttempt[]) => void,\n  ): AsyncIterable<ModelStreamChunk> {\n    try {\n      for (let index = 0; index < this.models.length; index++) {\n        const model = this.models[index]!;\n        const isLast = index === this.models.length - 1;\n        let emitted = false;\n\n        try {\n          for await (const chunk of model.stream(messages, options)) {\n            if (chunk.type === \"done\") {\n              aggregateUsage(this.usage, chunk.usage);\n\n              yield { ...chunk, usage: this.usage };\n              return;\n            }\n\n            emitted = true;\n\n            yield chunk;\n          }\n\n          return;\n        } catch (error) {\n          if (emitted || isLast || !this.shouldRetry(error)) {\n            throw error;\n          }\n\n          this.recordAttempt(model, error);\n        }\n      }\n\n      throw new AIError(\n        \"PROVIDER_ERROR\",\n        \"fallbackModel() exhausted its chain without producing a response.\",\n        undefined,\n        \"provider\",\n      );\n    } finally {\n      onSettle(this.attempts);\n    }\n  }\n\n  private recordAttempt(model: ModelContract, error: unknown): void {\n    this.attempts.push({\n      modelName: model.name,\n      provider: model.provider,\n      error,\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AA4BA,MAAM,0BAAkD;CACtD;CACA;CACA;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,cACd,QACA,SACuB;CACvB,IAAI,OAAO,WAAW,GACpB,MAAM,IAAI,QACR,4BACA,6DACA,QACA,YACF;CAGF,OAAO,IAAI,cAAc,QAAQ,mBAAmB,SAAS,OAAO,CAAC;AACvE;;;;;;;AAQA,SAAS,mBACP,SACwB;CACxB,IAAI,OAAO,YAAY,YACrB,OAAO;CAGT,MAAM,QAAgC,WAAW;CAEjD,QAAQ,UAA4B;EAClC,OAAO,iBAAiB,WAAW,MAAM,SAAS,MAAM,IAAI;CAC9D;AACF;;;;;;;AAQA,SAAS,eAAe,OAAc,MAAmB;CACvD,MAAM,SAAS,KAAK;CACpB,MAAM,UAAU,KAAK;CACrB,MAAM,SAAS,KAAK;CAEpB,IAAI,KAAK,iBAAiB,QACxB,MAAM,gBAAgB,MAAM,gBAAgB,KAAK,KAAK;CAGxD,IAAI,KAAK,oBAAoB,QAC3B,MAAM,mBAAmB,MAAM,mBAAmB,KAAK,KAAK;CAG9D,IAAI,KAAK,qBAAqB,QAC5B,MAAM,oBAAoB,MAAM,oBAAoB,KAAK,KAAK;CAGhE,MAAM,OAAO,eAAe,MAAM,MAAM,KAAK,IAAI;AACnD;;;;;;;;;;AAWA,IAAM,gBAAN,MAAqD;CAQnD,AAAO,YACL,AAAiB,QACjB,AAAiB,aACjB;EAFiB;EACA;wBAJyB,CAAC;EAM3C,MAAM,UAAU,OAAO;EAEvB,KAAK,OAAO,QAAQ;EACpB,KAAK,WAAW,QAAQ;EACxB,KAAK,eAAe,QAAQ;EAC5B,KAAK,UAAU,QAAQ;CACzB;;;;;;CAOA,IAAW,eAAkC;EAC3C,OAAO,KAAK;CACd;CAEA,MAAa,SACX,UACA,SACwB;EACxB,MAAM,MAAM,IAAI,YAAY,KAAK,QAAQ,KAAK,WAAW;EACzD,MAAM,WAAW,MAAM,IAAI,SAAS,UAAU,OAAO;EAErD,KAAK,iBAAiB,IAAI;EAE1B,OAAO;CACT;CAEA,AAAO,OACL,UACA,SACiC;EAGjC,OAAO,IAFS,YAAY,KAAK,QAAQ,KAAK,WAErC,CAAC,CAAC,OAAO,UAAU,UAAU,aAAa;GACjD,KAAK,iBAAiB;EACxB,CAAC;CACH;AACF;;;;;;;AAQA,IAAM,cAAN,MAAkB;CAKhB,AAAO,YACL,AAAiB,QACjB,AAAiB,aACjB;EAFiB;EACA;kBAN2B,CAAC;eAEf;GAAE,OAAO;GAAG,QAAQ;GAAG,OAAO;EAAE;CAK7D;;;;;;;CAQH,MAAa,SACX,UACA,SACwB;EACxB,KAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,OAAO,QAAQ,SAAS;GACvD,MAAM,QAAQ,KAAK,OAAO;GAC1B,MAAM,SAAS,UAAU,KAAK,OAAO,SAAS;GAE9C,IAAI;IACF,MAAM,WAAW,MAAM,MAAM,SAAS,UAAU,OAAO;IAEvD,eAAe,KAAK,OAAO,SAAS,KAAK;IAEzC,OAAO;KAAE,GAAG;KAAU,OAAO,KAAK;IAAM;GAC1C,SAAS,OAAO;IACd,IAAI,UAAU,CAAC,KAAK,YAAY,KAAK,GACnC,MAAM;IAGR,KAAK,cAAc,OAAO,KAAK;GACjC;EACF;EAEA,MAAM,IAAI,QACR,kBACA,qEACA,QACA,UACF;CACF;;;;;;;;;CAUA,OAAc,OACZ,UACA,SACA,UACiC;EACjC,IAAI;GACF,KAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,OAAO,QAAQ,SAAS;IACvD,MAAM,QAAQ,KAAK,OAAO;IAC1B,MAAM,SAAS,UAAU,KAAK,OAAO,SAAS;IAC9C,IAAI,UAAU;IAEd,IAAI;KACF,WAAW,MAAM,SAAS,MAAM,OAAO,UAAU,OAAO,GAAG;MACzD,IAAI,MAAM,SAAS,QAAQ;OACzB,eAAe,KAAK,OAAO,MAAM,KAAK;OAEtC,MAAM;QAAE,GAAG;QAAO,OAAO,KAAK;OAAM;OACpC;MACF;MAEA,UAAU;MAEV,MAAM;KACR;KAEA;IACF,SAAS,OAAO;KACd,IAAI,WAAW,UAAU,CAAC,KAAK,YAAY,KAAK,GAC9C,MAAM;KAGR,KAAK,cAAc,OAAO,KAAK;IACjC;GACF;GAEA,MAAM,IAAI,QACR,kBACA,qEACA,QACA,UACF;EACF,UAAU;GACR,SAAS,KAAK,QAAQ;EACxB;CACF;CAEA,AAAQ,cAAc,OAAsB,OAAsB;EAChE,KAAK,SAAS,KAAK;GACjB,WAAW,MAAM;GACjB,UAAU,MAAM;GAChB;EACF,CAAC;CACH;AACF"}

package/esm/ai/src/model/index.mjs

@@ -0,0 +1,3 @@
+import { fallbackModel } from "./fallback-model.mjs";
+
+export {  };

package/esm/ai/src/object-stream/index.mjs

@@ -0,0 +1,4 @@
+import { parsePartialJson } from "./parse-partial-json.mjs";
+import { streamObject } from "./stream-object.mjs";
+
+export {  };

package/esm/ai/src/object-stream/parse-partial-json.mjs

@@ -0,0 +1,78 @@
+//#region ../@warlock.js/ai/src/object-stream/parse-partial-json.ts
+/**
+* Best-effort parse of a possibly-truncated JSON string into the value it
+* is "on its way to" becoming. Used by {@link streamObject} to emit a
+* partial object snapshot from each streamed delta before the full reply
+* has arrived.
+*
+* Returns `undefined` when the prefix can't yet be coerced into a value
+* (so the caller simply waits for more text). The FINAL parse in
+* `streamObject` is always strict `JSON.parse` — this tolerant parser only
+* powers the in-flight snapshots, so a too-clever completion never affects
+* the authoritative result.
+*
+* @example
+* parsePartialJson('{"name":"Al');      // → { name: "Al" }
+* parsePartialJson('{"items":[1,2,');   // → { items: [1, 2] }
+* parsePartialJson('{"a":1,"b"');       // → { a: 1 } (drops the dangling key)
+*/
+function parsePartialJson(text) {
+	const trimmed = text.trim();
+	if (!trimmed) return void 0;
+	const direct = tryParse(trimmed);
+	if (direct.ok) return direct.value;
+	const completed = completePartialJson(trimmed);
+	if (completed === void 0) return void 0;
+	const parsed = tryParse(completed);
+	return parsed.ok ? parsed.value : void 0;
+}
+function tryParse(text) {
+	try {
+		return {
+			ok: true,
+			value: JSON.parse(text)
+		};
+	} catch {
+		return { ok: false };
+	}
+}
+/**
+* Reconstruct a parseable JSON string from a truncated prefix by closing
+* open strings/containers and trimming dangling separators, keys, and
+* partial literals. Tries the most faithful completion first, then falls
+* back to dropping the unfinished tail.
+*/
+function completePartialJson(text) {
+	const stack = [];
+	let inString = false;
+	let escaped = false;
+	for (const ch of text) {
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === "\"") inString = false;
+			continue;
+		}
+		if (ch === "\"") inString = true;
+		else if (ch === "{" || ch === "[") stack.push(ch);
+		else if (ch === "}" || ch === "]") stack.pop();
+	}
+	const closers = () => stack.map((c) => c === "{" ? "}" : "]").reverse().join("");
+	let core = text;
+	if (inString) core += "\"";
+	core = core.replace(/\s+$/, "");
+	if (core.endsWith(",")) core = core.slice(0, -1);
+	if (core.endsWith(":")) core += "null";
+	const attempts = [core + closers()];
+	if (stack[stack.length - 1] === "{") {
+		const droppedKey = core.replace(/,?\s*"(?:[^"\\]|\\.)*"\s*$/, "");
+		attempts.push(droppedKey.replace(/,\s*$/, "") + closers());
+	}
+	const droppedLiteral = core.replace(/[:,]?\s*[A-Za-z0-9.+\-eE]+$/, (match) => match.trimStart().startsWith(":") ? ":null" : "");
+	attempts.push(droppedLiteral.replace(/,\s*$/, "") + closers());
+	for (const candidate of attempts) if (tryParse(candidate).ok) return candidate;
+}
+
+//#endregion
+export { parsePartialJson };
+//# sourceMappingURL=parse-partial-json.mjs.map

package/esm/ai/src/object-stream/parse-partial-json.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-partial-json.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/object-stream/parse-partial-json.ts"],"sourcesContent":["/**\n * Best-effort parse of a possibly-truncated JSON string into the value it\n * is \"on its way to\" becoming. Used by {@link streamObject} to emit a\n * partial object snapshot from each streamed delta before the full reply\n * has arrived.\n *\n * Returns `undefined` when the prefix can't yet be coerced into a value\n * (so the caller simply waits for more text). The FINAL parse in\n * `streamObject` is always strict `JSON.parse` — this tolerant parser only\n * powers the in-flight snapshots, so a too-clever completion never affects\n * the authoritative result.\n *\n * @example\n * parsePartialJson('{\"name\":\"Al');      // → { name: \"Al\" }\n * parsePartialJson('{\"items\":[1,2,');   // → { items: [1, 2] }\n * parsePartialJson('{\"a\":1,\"b\"');       // → { a: 1 } (drops the dangling key)\n */\nexport function parsePartialJson(text: string): unknown | undefined {\n  const trimmed = text.trim();\n  if (!trimmed) return undefined;\n\n  // Fast path: already-valid JSON.\n  const direct = tryParse(trimmed);\n  if (direct.ok) return direct.value;\n\n  const completed = completePartialJson(trimmed);\n  if (completed === undefined) return undefined;\n\n  const parsed = tryParse(completed);\n  return parsed.ok ? parsed.value : undefined;\n}\n\nfunction tryParse(text: string): { ok: true; value: unknown } | { ok: false } {\n  try {\n    return { ok: true, value: JSON.parse(text) };\n  } catch {\n    return { ok: false };\n  }\n}\n\n/**\n * Reconstruct a parseable JSON string from a truncated prefix by closing\n * open strings/containers and trimming dangling separators, keys, and\n * partial literals. Tries the most faithful completion first, then falls\n * back to dropping the unfinished tail.\n */\nfunction completePartialJson(text: string): string | undefined {\n  const stack: Array<\"{\" | \"[\"> = [];\n  let inString = false;\n  let escaped = false;\n\n  for (const ch of text) {\n    if (inString) {\n      if (escaped) escaped = false;\n      else if (ch === \"\\\\\") escaped = true;\n      else if (ch === '\"') inString = false;\n      continue;\n    }\n    if (ch === '\"') inString = true;\n    else if (ch === \"{\" || ch === \"[\") stack.push(ch);\n    else if (ch === \"}\" || ch === \"]\") stack.pop();\n  }\n\n  const closers = () =>\n    stack\n      .map(c => (c === \"{\" ? \"}\" : \"]\"))\n      .reverse()\n      .join(\"\");\n\n  // Faithful completion: close an open string, drop a trailing comma,\n  // fill a dangling `key:` with null, then close containers.\n  let core = text;\n  if (inString) core += '\"';\n  core = core.replace(/\\s+$/, \"\");\n  if (core.endsWith(\",\")) core = core.slice(0, -1);\n  if (core.endsWith(\":\")) core += \"null\";\n\n  const attempts: string[] = [core + closers()];\n\n  // Fallback 1: drop a dangling object key (a `\"...\"` with no value yet).\n  if (stack[stack.length - 1] === \"{\") {\n    const droppedKey = core.replace(/,?\\s*\"(?:[^\"\\\\]|\\\\.)*\"\\s*$/, \"\");\n    attempts.push(droppedKey.replace(/,\\s*$/, \"\") + closers());\n  }\n\n  // Fallback 2: drop a partial trailing literal / number (e.g. `tr`, `12.`).\n  const droppedLiteral = core.replace(/[:,]?\\s*[A-Za-z0-9.+\\-eE]+$/, match =>\n    match.trimStart().startsWith(\":\") ? \":null\" : \"\",\n  );\n  attempts.push(droppedLiteral.replace(/,\\s*$/, \"\") + closers());\n\n  for (const candidate of attempts) {\n    if (tryParse(candidate).ok) return candidate;\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiBA,SAAgB,iBAAiB,MAAmC;CAClE,MAAM,UAAU,KAAK,KAAK;CAC1B,IAAI,CAAC,SAAS,OAAO;CAGrB,MAAM,SAAS,SAAS,OAAO;CAC/B,IAAI,OAAO,IAAI,OAAO,OAAO;CAE7B,MAAM,YAAY,oBAAoB,OAAO;CAC7C,IAAI,cAAc,QAAW,OAAO;CAEpC,MAAM,SAAS,SAAS,SAAS;CACjC,OAAO,OAAO,KAAK,OAAO,QAAQ;AACpC;AAEA,SAAS,SAAS,MAA4D;CAC5E,IAAI;EACF,OAAO;GAAE,IAAI;GAAM,OAAO,KAAK,MAAM,IAAI;EAAE;CAC7C,QAAQ;EACN,OAAO,EAAE,IAAI,MAAM;CACrB;AACF;;;;;;;AAQA,SAAS,oBAAoB,MAAkC;CAC7D,MAAM,QAA0B,CAAC;CACjC,IAAI,WAAW;CACf,IAAI,UAAU;CAEd,KAAK,MAAM,MAAM,MAAM;EACrB,IAAI,UAAU;GACZ,IAAI,SAAS,UAAU;QAClB,IAAI,OAAO,MAAM,UAAU;QAC3B,IAAI,OAAO,MAAK,WAAW;GAChC;EACF;EACA,IAAI,OAAO,MAAK,WAAW;OACtB,IAAI,OAAO,OAAO,OAAO,KAAK,MAAM,KAAK,EAAE;OAC3C,IAAI,OAAO,OAAO,OAAO,KAAK,MAAM,IAAI;CAC/C;CAEA,MAAM,gBACJ,MACG,KAAI,MAAM,MAAM,MAAM,MAAM,GAAI,CAAC,CACjC,QAAQ,CAAC,CACT,KAAK,EAAE;CAIZ,IAAI,OAAO;CACX,IAAI,UAAU,QAAQ;CACtB,OAAO,KAAK,QAAQ,QAAQ,EAAE;CAC9B,IAAI,KAAK,SAAS,GAAG,GAAG,OAAO,KAAK,MAAM,GAAG,EAAE;CAC/C,IAAI,KAAK,SAAS,GAAG,GAAG,QAAQ;CAEhC,MAAM,WAAqB,CAAC,OAAO,QAAQ,CAAC;CAG5C,IAAI,MAAM,MAAM,SAAS,OAAO,KAAK;EACnC,MAAM,aAAa,KAAK,QAAQ,8BAA8B,EAAE;EAChE,SAAS,KAAK,WAAW,QAAQ,SAAS,EAAE,IAAI,QAAQ,CAAC;CAC3D;CAGA,MAAM,iBAAiB,KAAK,QAAQ,gCAA+B,UACjE,MAAM,UAAU,CAAC,CAAC,WAAW,GAAG,IAAI,UAAU,EAChD;CACA,SAAS,KAAK,eAAe,QAAQ,SAAS,EAAE,IAAI,QAAQ,CAAC;CAE7D,KAAK,MAAM,aAAa,UACtB,IAAI,SAAS,SAAS,CAAC,CAAC,IAAI,OAAO;AAIvC"}

package/esm/ai/src/object-stream/stream-object.mjs

@@ -0,0 +1,97 @@
+import { SchemaValidationError } from "../errors/schema-validation-error.mjs";
+import "../errors/index.mjs";
+import { parsePartialJson } from "./parse-partial-json.mjs";
+
+//#region ../@warlock.js/ai/src/object-stream/stream-object.ts
+/**
+* Stream a structured object: emit raw token deltas, progressively-parsed
+* partial-object snapshots, and a final strictly-validated object — the
+* first-class structured-output streaming primitive (A1). Reuses the
+* model's existing `stream()` seam; the partial snapshots come from a
+* tolerant {@link parsePartialJson}, while the terminal `done` event is a
+* strict `JSON.parse` + schema validation, so an over-eager partial parse
+* never affects the authoritative result.
+*
+* Pair it with a `structuredOutput`-capable model and a `responseSchema`
+* (via `options`) for the cleanest JSON; otherwise prompt the model to
+* reply with JSON only.
+*
+* @example
+* for await (const event of streamObject({ model, messages, schema })) {
+*   if (event.type === "partial") render(event.value);          // live UI
+*   if (event.type === "done" && event.valid) save(event.value); // final
+* }
+*/
+async function* streamObject(params) {
+	const { model, messages, schema, options } = params;
+	let accumulated = "";
+	let lastPartialKey;
+	let usage = {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+	for await (const chunk of model.stream(messages, options)) if (chunk.type === "delta") {
+		accumulated += chunk.content;
+		yield {
+			type: "text-delta",
+			delta: chunk.content
+		};
+		const partial = parsePartialJson(accumulated);
+		if (partial !== void 0) {
+			const key = safeStringify(partial);
+			if (key !== lastPartialKey) {
+				lastPartialKey = key;
+				yield {
+					type: "partial",
+					value: partial
+				};
+			}
+		}
+	} else if (chunk.type === "done") usage = chunk.usage;
+	yield await finalize(accumulated, schema, usage);
+}
+/** Strict parse + schema validation of the complete streamed text. */
+async function finalize(text, schema, usage) {
+	const cleaned = stripJsonFences(text).trim();
+	let parsed;
+	try {
+		parsed = JSON.parse(cleaned);
+	} catch (cause) {
+		return {
+			type: "done",
+			valid: false,
+			error: new SchemaValidationError("streamObject: the final streamed output was not valid JSON", { cause }),
+			usage
+		};
+	}
+	const result = await schema["~standard"].validate(parsed);
+	if ("issues" in result && result.issues) return {
+		type: "done",
+		valid: false,
+		error: new SchemaValidationError("streamObject: the streamed object failed schema validation", { issues: result.issues }),
+		usage
+	};
+	return {
+		type: "done",
+		valid: true,
+		value: result.value,
+		usage
+	};
+}
+/** Strip a leading/trailing ```json fence the model may wrap output in. */
+function stripJsonFences(text) {
+	const fenced = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+	return fenced ? fenced[1] : text;
+}
+function safeStringify(value) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+
+//#endregion
+export { streamObject };
+//# sourceMappingURL=stream-object.mjs.map

package/esm/ai/src/object-stream/stream-object.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-object.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/object-stream/stream-object.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { Message } from \"../contracts/conversation-message.type\";\nimport type { ModelCallOptions, ModelContract } from \"../contracts/model.contract\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AIError, SchemaValidationError } from \"../errors\";\nimport { parsePartialJson } from \"./parse-partial-json\";\n\n/**\n * One event in a {@link streamObject} run.\n *\n * - `text-delta` — the raw token text as it streams (for a \"typing\" view).\n * - `partial` — a best-effort snapshot of the object so far, re-parsed\n *   from the accumulated text on each delta (only emitted when it changed).\n * - `done` — terminal: the final text is strictly parsed and validated\n *   against the schema. `valid` + `value` on success; `valid: false` +\n *   `error` when the output wasn't valid JSON or failed the schema.\n */\nexport type ObjectStreamEvent<T> =\n  | { type: \"text-delta\"; delta: string }\n  | { type: \"partial\"; value: unknown }\n  | { type: \"done\"; valid: true; value: T; usage: Usage }\n  | { type: \"done\"; valid: false; error: AIError; usage: Usage };\n\n/** Parameters for {@link streamObject}. */\nexport type StreamObjectParams<T> = {\n  /** The model to stream from (e.g. `sdk.model({ name })`). */\n  model: ModelContract;\n  /** The prompt messages. */\n  messages: Message[];\n  /** Standard Schema the final object is validated against. */\n  schema: StandardSchemaV1<T>;\n  /** Extra model call options (e.g. `responseSchema`, `temperature`). */\n  options?: ModelCallOptions;\n};\n\n/**\n * Stream a structured object: emit raw token deltas, progressively-parsed\n * partial-object snapshots, and a final strictly-validated object — the\n * first-class structured-output streaming primitive (A1). Reuses the\n * model's existing `stream()` seam; the partial snapshots come from a\n * tolerant {@link parsePartialJson}, while the terminal `done` event is a\n * strict `JSON.parse` + schema validation, so an over-eager partial parse\n * never affects the authoritative result.\n *\n * Pair it with a `structuredOutput`-capable model and a `responseSchema`\n * (via `options`) for the cleanest JSON; otherwise prompt the model to\n * reply with JSON only.\n *\n * @example\n * for await (const event of streamObject({ model, messages, schema })) {\n *   if (event.type === \"partial\") render(event.value);          // live UI\n *   if (event.type === \"done\" && event.valid) save(event.value); // final\n * }\n */\nexport async function* streamObject<T>(\n  params: StreamObjectParams<T>,\n): AsyncIterable<ObjectStreamEvent<T>> {\n  const { model, messages, schema, options } = params;\n\n  let accumulated = \"\";\n  let lastPartialKey: string | undefined;\n  let usage: Usage = { input: 0, output: 0, total: 0 };\n\n  for await (const chunk of model.stream(messages, options)) {\n    if (chunk.type === \"delta\") {\n      accumulated += chunk.content;\n      yield { type: \"text-delta\", delta: chunk.content };\n\n      const partial = parsePartialJson(accumulated);\n      if (partial !== undefined) {\n        const key = safeStringify(partial);\n        if (key !== lastPartialKey) {\n          lastPartialKey = key;\n          yield { type: \"partial\", value: partial };\n        }\n      }\n    } else if (chunk.type === \"done\") {\n      usage = chunk.usage;\n    }\n  }\n\n  yield await finalize(accumulated, schema, usage);\n}\n\n/** Strict parse + schema validation of the complete streamed text. */\nasync function finalize<T>(\n  text: string,\n  schema: StandardSchemaV1<T>,\n  usage: Usage,\n): Promise<ObjectStreamEvent<T>> {\n  const cleaned = stripJsonFences(text).trim();\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(cleaned);\n  } catch (cause) {\n    return {\n      type: \"done\",\n      valid: false,\n      error: new SchemaValidationError(\n        \"streamObject: the final streamed output was not valid JSON\",\n        { cause },\n      ),\n      usage,\n    };\n  }\n\n  const result = await schema[\"~standard\"].validate(parsed);\n  if (\"issues\" in result && result.issues) {\n    return {\n      type: \"done\",\n      valid: false,\n      error: new SchemaValidationError(\n        \"streamObject: the streamed object failed schema validation\",\n        { issues: result.issues },\n      ),\n      usage,\n    };\n  }\n\n  return { type: \"done\", valid: true, value: (result as { value: T }).value, usage };\n}\n\n/** Collect a {@link streamObject} run down to just its terminal event. */\nexport async function collectStreamObject<T>(\n  stream: AsyncIterable<ObjectStreamEvent<T>>,\n): Promise<Extract<ObjectStreamEvent<T>, { type: \"done\" }>> {\n  let done: Extract<ObjectStreamEvent<T>, { type: \"done\" }> | undefined;\n  for await (const event of stream) {\n    if (event.type === \"done\") done = event;\n  }\n  if (!done) {\n    throw new SchemaValidationError(\"streamObject: stream ended without a terminal event\");\n  }\n  return done;\n}\n\n/** Strip a leading/trailing ```json fence the model may wrap output in. */\nfunction stripJsonFences(text: string): string {\n  const fenced = text.match(/```(?:json)?\\s*([\\s\\S]*?)\\s*```/i);\n  return fenced ? fenced[1] : text;\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAsDA,gBAAuB,aACrB,QACqC;CACrC,MAAM,EAAE,OAAO,UAAU,QAAQ,YAAY;CAE7C,IAAI,cAAc;CAClB,IAAI;CACJ,IAAI,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CAEnD,WAAW,MAAM,SAAS,MAAM,OAAO,UAAU,OAAO,GACtD,IAAI,MAAM,SAAS,SAAS;EAC1B,eAAe,MAAM;EACrB,MAAM;GAAE,MAAM;GAAc,OAAO,MAAM;EAAQ;EAEjD,MAAM,UAAU,iBAAiB,WAAW;EAC5C,IAAI,YAAY,QAAW;GACzB,MAAM,MAAM,cAAc,OAAO;GACjC,IAAI,QAAQ,gBAAgB;IAC1B,iBAAiB;IACjB,MAAM;KAAE,MAAM;KAAW,OAAO;IAAQ;GAC1C;EACF;CACF,OAAO,IAAI,MAAM,SAAS,QACxB,QAAQ,MAAM;CAIlB,MAAM,MAAM,SAAS,aAAa,QAAQ,KAAK;AACjD;;AAGA,eAAe,SACb,MACA,QACA,OAC+B;CAC/B,MAAM,UAAU,gBAAgB,IAAI,CAAC,CAAC,KAAK;CAE3C,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,OAAO;CAC7B,SAAS,OAAO;EACd,OAAO;GACL,MAAM;GACN,OAAO;GACP,OAAO,IAAI,sBACT,8DACA,EAAE,MAAM,CACV;GACA;EACF;CACF;CAEA,MAAM,SAAS,MAAM,OAAO,YAAY,CAAC,SAAS,MAAM;CACxD,IAAI,YAAY,UAAU,OAAO,QAC/B,OAAO;EACL,MAAM;EACN,OAAO;EACP,OAAO,IAAI,sBACT,8DACA,EAAE,QAAQ,OAAO,OAAO,CAC1B;EACA;CACF;CAGF,OAAO;EAAE,MAAM;EAAQ,OAAO;EAAM,OAAQ,OAAwB;EAAO;CAAM;AACnF;;AAiBA,SAAS,gBAAgB,MAAsB;CAC7C,MAAM,SAAS,KAAK,MAAM,kCAAkC;CAC5D,OAAO,SAAS,OAAO,KAAK;AAC9B;AAEA,SAAS,cAAc,OAAwB;CAC7C,IAAI;EACF,OAAO,KAAK,UAAU,KAAK;CAC7B,QAAQ;EACN,OAAO,OAAO,KAAK;CACrB;AACF"}

package/esm/ai/src/observe/index.mjs

@@ -0,0 +1,4 @@
+import { getObservers, isObserveAll } from "./observer-registry.mjs";
+import { notifyObservers, resolveObservers } from "./resolve-observers.mjs";
+
+export {  };

package/esm/ai/src/observe/observer-registry.mjs

@@ -0,0 +1,35 @@
+//#region ../@warlock.js/ai/src/observe/observer-registry.ts
+/**
+* Module-level list of globally registered {@link Observer}s. A flow
+* that resolves to "observed" hands its finished report to every entry
+* here. An observability tool (panoptic, …) registers exactly one
+* collector when its config is applied.
+*/
+const observers = [];
+/**
+* Global "observe every flow by default" flag. When `true`, a flow that
+* did not set its own `observe` option is observed (routed to the
+* globally registered observers). Individual flows opt out with
+* `observe: false`. Default `false` — opt-in observability.
+*/
+let observeAll = false;
+/**
+* The currently registered global observers. Returned as a read-only
+* snapshot reference — callers must not mutate it; use
+* {@link registerObserver} to add and {@link clearObservers} (test-only)
+* to reset.
+*/
+function getObservers() {
+	return observers;
+}
+/**
+* Read the global "observe every flow by default" flag. Consulted by the
+* observe-resolution helper when a flow left `observe` undefined.
+*/
+function isObserveAll() {
+	return observeAll;
+}
+
+//#endregion
+export { getObservers, isObserveAll };
+//# sourceMappingURL=observer-registry.mjs.map

package/esm/ai/src/observe/observer-registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-registry.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/observe/observer-registry.ts"],"sourcesContent":["import type { Observer } from \"./observer.contract\";\n\n/**\n * Module-level list of globally registered {@link Observer}s. A flow\n * that resolves to \"observed\" hands its finished report to every entry\n * here. An observability tool (panoptic, …) registers exactly one\n * collector when its config is applied.\n */\nconst observers: Observer[] = [];\n\n/**\n * Global \"observe every flow by default\" flag. When `true`, a flow that\n * did not set its own `observe` option is observed (routed to the\n * globally registered observers). Individual flows opt out with\n * `observe: false`. Default `false` — opt-in observability.\n */\nlet observeAll = false;\n\n/**\n * Register a global {@link Observer}. Every flow that resolves to\n * \"observed\" (via `observeAll` or `observe: true`) routes its completed\n * report to it. An observability tool registers its collector here once,\n * when its config is applied.\n */\nexport function registerObserver(observer: Observer): void {\n  observers.push(observer);\n}\n\n/**\n * The currently registered global observers. Returned as a read-only\n * snapshot reference — callers must not mutate it; use\n * {@link registerObserver} to add and {@link clearObservers} (test-only)\n * to reset.\n */\nexport function getObservers(): readonly Observer[] {\n  return observers;\n}\n\n/**\n * Set the global \"observe every flow by default\" flag. An observability\n * tool flips this on when configured with its own observe-all option.\n */\nexport function setObserveAll(value: boolean): void {\n  observeAll = value;\n}\n\n/**\n * Read the global \"observe every flow by default\" flag. Consulted by the\n * observe-resolution helper when a flow left `observe` undefined.\n */\nexport function isObserveAll(): boolean {\n  return observeAll;\n}\n\n/**\n * Reset the registry to its initial empty state — clears all registered\n * observers and turns off the observe-all flag. Internal: intended for\n * test isolation so one spec's registrations don't leak into the next.\n * Not part of the public surface.\n */\nexport function clearObservers(): void {\n  observers.length = 0;\n  observeAll = false;\n}\n"],"mappings":";;;;;;;AAQA,MAAM,YAAwB,CAAC;;;;;;;AAQ/B,IAAI,aAAa;;;;;;;AAkBjB,SAAgB,eAAoC;CAClD,OAAO;AACT;;;;;AAcA,SAAgB,eAAwB;CACtC,OAAO;AACT"}

package/esm/ai/src/observe/resolve-observers.mjs

@@ -0,0 +1,73 @@
+import { isNestedRun } from "../utils/run-context.mjs";
+import { getObservers, isObserveAll } from "./observer-registry.mjs";
+
+//#region ../@warlock.js/ai/src/observe/resolve-observers.ts
+/**
+* Resolve a flow's `observe` option into the concrete list of
+* {@link Observer}s to notify with that flow's completed report:
+*
+* - `false` → `[]` (opted out).
+* - `true` → the globally registered observers.
+* - an `Observer` object → just that one (flow-local).
+* - `undefined` → the globally registered observers when observe-all is
+*   on AND this is a ROOT run, otherwise `[]`.
+*
+* Reads the ambient {@link currentRunFrame} for the observe-all path:
+* flows call it at completion, so a present frame means the run is nested
+* inside an orchestration callback and is already attached to its parent's
+* report tree — self-routing it again would double-count it as a separate
+* top-level trace (and double its tokens/cost in the aggregate). Explicit
+* `observe: true` / an `Observer` still route regardless of nesting.
+*/
+function resolveObservers(observe) {
+	if (observe === false) return [];
+	if (observe === true) return getObservers();
+	if (observe !== void 0) return [observe];
+	return isObserveAll() && !isNestedRun() ? getObservers() : [];
+}
+/**
+* Observers whose `collect()` already threw once — so the isolate-but-
+* surface warning fires at most once per observer object, never spamming
+* the log when every flow report hits the same broken exporter. Keyed by
+* object identity via a {@link WeakSet} so a discarded observer is GC'd
+* without leaking. Mirrors panoptic's per-exporter `warnedExporters`.
+*/
+const warnedObservers = /* @__PURE__ */ new WeakSet();
+/**
+* Route a completed flow report to every observer the flow's `observe`
+* option resolves to. Each `collect` is awaited so async exporters
+* finish before the flow returns; a throw is **isolated** (never breaks
+* the run) but no longer **silent** — it is surfaced via `onError` when
+* supplied, otherwise a `console.warn` once per observer. A broken
+* observer/exporter must not disappear from production with no signal
+* (C5). Adopts the isolate-but-surface pattern panoptic's collector
+* already uses for exporters.
+*/
+async function notifyObservers(observe, report, onError) {
+	for (const observer of resolveObservers(observe)) try {
+		await observer.collect(report);
+	} catch (error) {
+		surfaceObserverError(observer, error, onError);
+	}
+}
+/**
+* Surface an isolated observer failure without ever rethrowing into the
+* flow. Prefers the caller-supplied `onError` (itself guarded so a
+* throwing handler can't escape); otherwise warns once per observer.
+*/
+function surfaceObserverError(observer, error, onError) {
+	if (onError) {
+		try {
+			onError(error, observer);
+		} catch {}
+		return;
+	}
+	if (warnedObservers.has(observer)) return;
+	warnedObservers.add(observer);
+	const message = error instanceof Error ? error.message : String(error);
+	console.warn(`[warlock-ai] an observer's collect() threw and was isolated: ${message}`);
+}
+
+//#endregion
+export { notifyObservers, resolveObservers };
+//# sourceMappingURL=resolve-observers.mjs.map

package/esm/ai/src/observe/resolve-observers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-observers.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/observe/resolve-observers.ts"],"sourcesContent":["import { isNestedRun } from \"../utils/run-context\";\nimport { getObservers, isObserveAll } from \"./observer-registry\";\nimport type { Observer } from \"./observer.contract\";\n\n/**\n * The value a flow's `observe` config option may take. Additive and\n * gated — when `undefined` (the default), behavior follows the global\n * observe-all flag, so a flow that never sets `observe` behaves exactly\n * as before unless an observability tool turned observe-all on.\n *\n * - `true`  → route this flow to the globally registered observers,\n *   even when observe-all is off.\n * - `false` → opt this flow out entirely, even when observe-all is on.\n * - an {@link Observer} object → a flow-local collector; only this flow's\n *   report is routed, and only to it (the global observers are skipped).\n *   A panoptic flow-local collector implements `Observer`, so it can be\n *   passed here directly — core stays panoptic-agnostic.\n * - `undefined` → follow the global observe-all flag.\n */\nexport type FlowObserveOption = boolean | Observer;\n\n/**\n * Resolve a flow's `observe` option into the concrete list of\n * {@link Observer}s to notify with that flow's completed report:\n *\n * - `false` → `[]` (opted out).\n * - `true` → the globally registered observers.\n * - an `Observer` object → just that one (flow-local).\n * - `undefined` → the globally registered observers when observe-all is\n *   on AND this is a ROOT run, otherwise `[]`.\n *\n * Reads the ambient {@link currentRunFrame} for the observe-all path:\n * flows call it at completion, so a present frame means the run is nested\n * inside an orchestration callback and is already attached to its parent's\n * report tree — self-routing it again would double-count it as a separate\n * top-level trace (and double its tokens/cost in the aggregate). Explicit\n * `observe: true` / an `Observer` still route regardless of nesting.\n */\nexport function resolveObservers(observe: FlowObserveOption | undefined): readonly Observer[] {\n  if (observe === false) {\n    return [];\n  }\n\n  if (observe === true) {\n    return getObservers();\n  }\n\n  if (observe !== undefined) {\n    return [observe];\n  }\n\n  // Observe-all captures ROOT runs only. A run nested inside any parent\n  // capture (orchestration callback, supervisor member dispatch, workflow\n  // step) already nests in its parent's report, so routing it here too would\n  // duplicate it as a standalone top-level trace.\n  return isObserveAll() && !isNestedRun() ? getObservers() : [];\n}\n\n/**\n * Observers whose `collect()` already threw once — so the isolate-but-\n * surface warning fires at most once per observer object, never spamming\n * the log when every flow report hits the same broken exporter. Keyed by\n * object identity via a {@link WeakSet} so a discarded observer is GC'd\n * without leaking. Mirrors panoptic's per-exporter `warnedExporters`.\n */\nconst warnedObservers = new WeakSet<Observer>();\n\n/**\n * Route a completed flow report to every observer the flow's `observe`\n * option resolves to. Each `collect` is awaited so async exporters\n * finish before the flow returns; a throw is **isolated** (never breaks\n * the run) but no longer **silent** — it is surfaced via `onError` when\n * supplied, otherwise a `console.warn` once per observer. A broken\n * observer/exporter must not disappear from production with no signal\n * (C5). Adopts the isolate-but-surface pattern panoptic's collector\n * already uses for exporters.\n */\nexport async function notifyObservers(\n  observe: FlowObserveOption | undefined,\n  report: Parameters<Observer[\"collect\"]>[0],\n  onError?: (error: unknown, observer: Observer) => void,\n): Promise<void> {\n  for (const observer of resolveObservers(observe)) {\n    try {\n      await observer.collect(report);\n    } catch (error) {\n      surfaceObserverError(observer, error, onError);\n    }\n  }\n}\n\n/**\n * Surface an isolated observer failure without ever rethrowing into the\n * flow. Prefers the caller-supplied `onError` (itself guarded so a\n * throwing handler can't escape); otherwise warns once per observer.\n */\nfunction surfaceObserverError(\n  observer: Observer,\n  error: unknown,\n  onError?: (error: unknown, observer: Observer) => void,\n): void {\n  if (onError) {\n    try {\n      onError(error, observer);\n    } catch {\n      // Never let the error handler itself escape into the flow.\n    }\n    return;\n  }\n\n  if (warnedObservers.has(observer)) return;\n  warnedObservers.add(observer);\n\n  const message = error instanceof Error ? error.message : String(error);\n  console.warn(`[warlock-ai] an observer's collect() threw and was isolated: ${message}`);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,iBAAiB,SAA6D;CAC5F,IAAI,YAAY,OACd,OAAO,CAAC;CAGV,IAAI,YAAY,MACd,OAAO,aAAa;CAGtB,IAAI,YAAY,QACd,OAAO,CAAC,OAAO;CAOjB,OAAO,aAAa,KAAK,CAAC,YAAY,IAAI,aAAa,IAAI,CAAC;AAC9D;;;;;;;;AASA,MAAM,kCAAkB,IAAI,QAAkB;;;;;;;;;;;AAY9C,eAAsB,gBACpB,SACA,QACA,SACe;CACf,KAAK,MAAM,YAAY,iBAAiB,OAAO,GAC7C,IAAI;EACF,MAAM,SAAS,QAAQ,MAAM;CAC/B,SAAS,OAAO;EACd,qBAAqB,UAAU,OAAO,OAAO;CAC/C;AAEJ;;;;;;AAOA,SAAS,qBACP,UACA,OACA,SACM;CACN,IAAI,SAAS;EACX,IAAI;GACF,QAAQ,OAAO,QAAQ;EACzB,QAAQ,CAER;EACA;CACF;CAEA,IAAI,gBAAgB,IAAI,QAAQ,GAAG;CACnC,gBAAgB,IAAI,QAAQ;CAE5B,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CACrE,QAAQ,KAAK,gEAAgE,SAAS;AACxF"}

package/esm/ai/src/orchestrator/as-tool.mjs

@@ -0,0 +1,98 @@
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import "../errors/index.mjs";
+import { generateRunId } from "../utils/generate-run-id.mjs";
+import { compositeAsTool } from "../tool/tool.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/as-tool.ts
+/**
+* Wrap an {@link OrchestratorContract} as a {@link ToolContract} so an
+* outer agent can invoke it from its tool-call loop (design §13).
+* Mirrors `supervisor.asTool()` — same `compositeAsTool` composition and
+* error normalization — and adds `sessionScope`.
+*
+* The boundary is OPAQUE (§13, §18.6): the parent's `signal` / `context`
+* / events do NOT auto-forward. Anything the wrapped orchestrator needs
+* per call must ride on the tool's `inputSchema` payload.
+*
+* Session continuity:
+* - `"fresh"` (default) — each invocation gets a brand-new `sessionId`
+*   (a generated id) and empty history; the session lives only for this
+*   tool call. The whole validated payload is forwarded as the
+*   orchestrator's `execute(input)` argument.
+* - `"shared"` — the parent supplies `sessionId` (and optionally
+*   `history`) inside the validated payload; the orchestrator
+*   participates in that session. The remaining payload fields are
+*   forwarded as `execute(input)`. A missing/blank `sessionId` throws
+*   {@link SupervisorFailedError}.
+*
+* On `result.error`, the typed orchestrator error is thrown so the tool
+* wrapper produces a `ToolExecutionError` with `cause` preserved — the
+* outer agent sees one uniform error class.
+*
+* @example
+* const support = ai.orchestrator({ name: "refund-support", intents });
+* const supportTool = support.asTool({
+*   name: "handle_refund",
+*   description: "Handle a refund conversation end-to-end.",
+*   inputSchema: v.object({ message: v.string() }),
+* });
+* const concierge = ai.agent({ model, tools: [supportTool] });
+*/
+function asTool(orchestrator, options) {
+	if (!orchestrator.name || typeof orchestrator.name !== "string") throw new SupervisorFailedError("orchestrator.asTool(): orchestrator must have a `name` to be wrapped as a tool");
+	const sessionScope = options.sessionScope ?? "fresh";
+	return compositeAsTool({
+		name: options.name ?? orchestrator.name,
+		description: options.description ?? `Invoke orchestrator "${orchestrator.name}" as a tool.`,
+		input: options.inputSchema,
+		execute: async (input) => {
+			const { sessionId, history, executeInput } = resolveSession(sessionScope, input);
+			const result = await orchestrator.execute(executeInput, {
+				sessionId,
+				history
+			});
+			if (result.error) throw result.error;
+			return {
+				data: result.data,
+				usage: result.usage,
+				report: result.report
+			};
+		}
+	});
+}
+/**
+* Resolve the per-call `sessionId`, `history`, and the `execute(input)`
+* argument from the validated tool payload, according to `sessionScope`.
+*/
+function resolveSession(sessionScope, input) {
+	if (sessionScope === "fresh") return {
+		sessionId: generateRunId("session"),
+		history: [],
+		executeInput: coerceInput(input)
+	};
+	const payload = typeof input === "object" && input !== null ? input : {};
+	if (typeof payload.sessionId !== "string" || payload.sessionId.length === 0) throw new SupervisorFailedError("orchestrator.asTool(): sessionScope \"shared\" requires a `sessionId` string in the tool input payload");
+	const { sessionId, history, ...rest } = payload;
+	return {
+		sessionId,
+		history: Array.isArray(history) ? history : [],
+		executeInput: coerceInput(rest)
+	};
+}
+/**
+* Coerce a tool-input value into the `SupervisorInput` shape the
+* orchestrator's `execute()` accepts (`string | Record<string,
+* unknown>`). Strings and plain objects pass through; everything else
+* is JSON-stringified so the orchestrator receives a predictable input
+* regardless of how the outer agent shaped its call.
+*/
+function coerceInput(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "object" && value !== null) return value;
+	if (value === void 0 || value === null) return "";
+	return String(value);
+}
+
+//#endregion
+export { asTool };
+//# sourceMappingURL=as-tool.mjs.map

package/esm/ai/src/orchestrator/as-tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"as-tool.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/as-tool.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type {\n  OrchestratorAsToolOptions,\n  OrchestratorContract,\n} from \"../contracts/orchestrator/orchestrator.contract\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport { SupervisorFailedError } from \"../errors\";\nimport { compositeAsTool, type ToolContract } from \"../tool/tool\";\nimport { generateRunId } from \"../utils/generate-run-id\";\n\n/**\n * Shape the orchestrator looks for inside the validated tool input when\n * `sessionScope: \"shared\"` — the parent must thread the session id (and\n * optionally the prior history) through the tool's `inputSchema`\n * payload, since the boundary is opaque (§13). Everything else on the\n * payload becomes the orchestrator's `execute(input)` argument.\n */\ntype SharedScopePayload = {\n  sessionId?: unknown;\n  history?: unknown;\n  [key: string]: unknown;\n};\n\n/**\n * Wrap an {@link OrchestratorContract} as a {@link ToolContract} so an\n * outer agent can invoke it from its tool-call loop (design §13).\n * Mirrors `supervisor.asTool()` — same `compositeAsTool` composition and\n * error normalization — and adds `sessionScope`.\n *\n * The boundary is OPAQUE (§13, §18.6): the parent's `signal` / `context`\n * / events do NOT auto-forward. Anything the wrapped orchestrator needs\n * per call must ride on the tool's `inputSchema` payload.\n *\n * Session continuity:\n * - `\"fresh\"` (default) — each invocation gets a brand-new `sessionId`\n *   (a generated id) and empty history; the session lives only for this\n *   tool call. The whole validated payload is forwarded as the\n *   orchestrator's `execute(input)` argument.\n * - `\"shared\"` — the parent supplies `sessionId` (and optionally\n *   `history`) inside the validated payload; the orchestrator\n *   participates in that session. The remaining payload fields are\n *   forwarded as `execute(input)`. A missing/blank `sessionId` throws\n *   {@link SupervisorFailedError}.\n *\n * On `result.error`, the typed orchestrator error is thrown so the tool\n * wrapper produces a `ToolExecutionError` with `cause` preserved — the\n * outer agent sees one uniform error class.\n *\n * @example\n * const support = ai.orchestrator({ name: \"refund-support\", intents });\n * const supportTool = support.asTool({\n *   name: \"handle_refund\",\n *   description: \"Handle a refund conversation end-to-end.\",\n *   inputSchema: v.object({ message: v.string() }),\n * });\n * const concierge = ai.agent({ model, tools: [supportTool] });\n */\nexport function asTool<TOutput, TState, TToolInput>(\n  orchestrator: OrchestratorContract<TOutput, TState>,\n  options: OrchestratorAsToolOptions<TToolInput>,\n): ToolContract<TToolInput, TOutput> {\n  if (!orchestrator.name || typeof orchestrator.name !== \"string\") {\n    throw new SupervisorFailedError(\n      \"orchestrator.asTool(): orchestrator must have a `name` to be wrapped as a tool\",\n    );\n  }\n\n  const sessionScope = options.sessionScope ?? \"fresh\";\n\n  return compositeAsTool<TToolInput, TOutput>({\n    name: options.name ?? orchestrator.name,\n    description:\n      options.description ??\n      `Invoke orchestrator \"${orchestrator.name}\" as a tool.`,\n    input: options.inputSchema,\n    execute: async (input) => {\n      const { sessionId, history, executeInput } = resolveSession(\n        sessionScope,\n        input,\n      );\n\n      const result = await orchestrator.execute(executeInput, {\n        sessionId,\n        history,\n      });\n\n      if (result.error) {\n        // Surface the typed orchestrator error — the outer ToolContract\n        // wraps it as a ToolExecutionError with `cause` preserved.\n        throw result.error;\n      }\n\n      return {\n        data: result.data as TOutput,\n        usage: result.usage,\n        report: result.report,\n      };\n    },\n  });\n}\n\n/**\n * Resolve the per-call `sessionId`, `history`, and the `execute(input)`\n * argument from the validated tool payload, according to `sessionScope`.\n */\nfunction resolveSession(\n  sessionScope: \"fresh\" | \"shared\",\n  input: unknown,\n): { sessionId: string; history: Message[]; executeInput: SupervisorInput } {\n  if (sessionScope === \"fresh\") {\n    return {\n      sessionId: generateRunId(\"session\"),\n      history: [],\n      executeInput: coerceInput(input),\n    };\n  }\n\n  const payload = (\n    typeof input === \"object\" && input !== null ? input : {}\n  ) as SharedScopePayload;\n\n  if (typeof payload.sessionId !== \"string\" || payload.sessionId.length === 0) {\n    throw new SupervisorFailedError(\n      'orchestrator.asTool(): sessionScope \"shared\" requires a `sessionId` string in the tool input payload',\n    );\n  }\n\n  const { sessionId, history, ...rest } = payload;\n\n  return {\n    sessionId,\n    history: Array.isArray(history) ? (history as Message[]) : [],\n    executeInput: coerceInput(rest),\n  };\n}\n\n/**\n * Coerce a tool-input value into the `SupervisorInput` shape the\n * orchestrator's `execute()` accepts (`string | Record<string,\n * unknown>`). Strings and plain objects pass through; everything else\n * is JSON-stringified so the orchestrator receives a predictable input\n * regardless of how the outer agent shaped its call.\n */\nfunction coerceInput(value: unknown): SupervisorInput {\n  if (typeof value === \"string\") {\n    return value;\n  }\n\n  if (typeof value === \"object\" && value !== null) {\n    return value as Record<string, unknown>;\n  }\n\n  if (value === undefined || value === null) {\n    return \"\";\n  }\n\n  return String(value);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,OACd,cACA,SACmC;CACnC,IAAI,CAAC,aAAa,QAAQ,OAAO,aAAa,SAAS,UACrD,MAAM,IAAI,sBACR,gFACF;CAGF,MAAM,eAAe,QAAQ,gBAAgB;CAE7C,OAAO,gBAAqC;EAC1C,MAAM,QAAQ,QAAQ,aAAa;EACnC,aACE,QAAQ,eACR,wBAAwB,aAAa,KAAK;EAC5C,OAAO,QAAQ;EACf,SAAS,OAAO,UAAU;GACxB,MAAM,EAAE,WAAW,SAAS,iBAAiB,eAC3C,cACA,KACF;GAEA,MAAM,SAAS,MAAM,aAAa,QAAQ,cAAc;IACtD;IACA;GACF,CAAC;GAED,IAAI,OAAO,OAGT,MAAM,OAAO;GAGf,OAAO;IACL,MAAM,OAAO;IACb,OAAO,OAAO;IACd,QAAQ,OAAO;GACjB;EACF;CACF,CAAC;AACH;;;;;AAMA,SAAS,eACP,cACA,OAC0E;CAC1E,IAAI,iBAAiB,SACnB,OAAO;EACL,WAAW,cAAc,SAAS;EAClC,SAAS,CAAC;EACV,cAAc,YAAY,KAAK;CACjC;CAGF,MAAM,UACJ,OAAO,UAAU,YAAY,UAAU,OAAO,QAAQ,CAAC;CAGzD,IAAI,OAAO,QAAQ,cAAc,YAAY,QAAQ,UAAU,WAAW,GACxE,MAAM,IAAI,sBACR,wGACF;CAGF,MAAM,EAAE,WAAW,SAAS,GAAG,SAAS;CAExC,OAAO;EACL;EACA,SAAS,MAAM,QAAQ,OAAO,IAAK,UAAwB,CAAC;EAC5D,cAAc,YAAY,IAAI;CAChC;AACF;;;;;;;;AASA,SAAS,YAAY,OAAiC;CACpD,IAAI,OAAO,UAAU,UACnB,OAAO;CAGT,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,OAAO;CAGT,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO;CAGT,OAAO,OAAO,KAAK;AACrB"}

package/esm/ai/src/orchestrator/checkpoint.mjs

@@ -0,0 +1,75 @@
+//#region ../@warlock.js/ai/src/orchestrator/checkpoint.ts
+/** Framework default for snapshot retention per session (§4 Phase 6). */
+const DEFAULT_KEEP_SNAPSHOTS = 100;
+/**
+* Summarize a supervisor dispatch decision into the `last_route`
+* checkpoint column (§4 Phase 6). A bare string passes through; a
+* fan-out array passes through; the `END` sentinel and anything else
+* collapse to `null` (the turn routed nowhere worth recording).
+*/
+function summarizeRoute(next) {
+	if (typeof next === "string") return next === "__warlock:end__" ? null : next;
+	if (Array.isArray(next)) return next;
+	return null;
+}
+/**
+* Phase 6 — persist checkpoint (orchestrator.md §3 / §4 Phase 6).
+* Writes a fresh append-only row at `turn_index = N` carrying the
+* post-merge `state`, the current `signature` (read by the next call's
+* Phase 2), the informational `version`, the dispatch `last_route`, and
+* the carried-forward `summarized_through`. Lock columns are written
+* `null` here — they are populated only by an in-flight Phase 7
+* compaction.
+*
+* Emits `orchestrator.checkpoint.persisted` after the row lands, then
+* prunes to `keepSnapshots` (default 100; `"all"` opts out) — §4 Phase
+* 6 pruning (Q20). Pruning runs only when the store exposes the
+* optional `prune` hook (memory/pg/redis own their own pruning); when
+* absent the write still succeeds.
+*
+* Returns the persisted record so the engine can fold it into the
+* turn's report.
+*/
+async function persistCheckpoint(params) {
+	const { ctx, sessionId, turnIndex, state, lastRoute, summarizedThrough } = params;
+	const record = {
+		orchestrator_name: ctx.config.name,
+		session_id: sessionId,
+		turn_index: turnIndex,
+		state,
+		last_route: lastRoute,
+		signature: ctx.signature,
+		version: ctx.config.version ?? null,
+		summarized_through: summarizedThrough,
+		lock_acquired_at: null,
+		lock_expires_at: null,
+		saved_at: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await ctx.checkpointStore.save(record);
+	ctx.emitter.emit("orchestrator.checkpoint.persisted", {
+		sessionId,
+		turnIndex
+	});
+	await prune(ctx, sessionId, turnIndex);
+	return record;
+}
+/**
+* Prune session rows older than `max_turn_index - keepSnapshots` (§4
+* Phase 6). Synchronous-after-save; opted out with
+* `keepSnapshots: "all"`. Delegated to an optional store-side `prune`
+* hook so each driver implements deletion in its own dialect — the
+* engine never reaches into store internals.
+*/
+async function prune(ctx, sessionId, latestTurnIndex) {
+	const keep = ctx.config.keepSnapshots ?? 100;
+	if (keep === "all") return;
+	const store = ctx.checkpointStore;
+	if (typeof store.prune !== "function") return;
+	const keepBeforeTurnIndex = latestTurnIndex - keep + 1;
+	if (keepBeforeTurnIndex <= 0) return;
+	await store.prune(ctx.config.name, sessionId, keepBeforeTurnIndex);
+}
+
+//#endregion
+export { persistCheckpoint, summarizeRoute };
+//# sourceMappingURL=checkpoint.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/checkpoint.ts"],"sourcesContent":["import type { CheckpointRecord } from \"../contracts/orchestrator/checkpoint-store.contract\";\nimport type { Next } from \"../contracts/supervisor/next.type\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\n\n/** Framework default for snapshot retention per session (§4 Phase 6). */\nexport const DEFAULT_KEEP_SNAPSHOTS = 100;\n\n/** Fields the engine supplies to build a fresh checkpoint row. */\nexport type PersistParams<TState> = {\n  ctx: OrchestratorEngineContext<unknown, TState>;\n  sessionId: string;\n  turnIndex: number;\n  state: unknown;\n  /** Dispatch decision summary — a single intent, fan-out list, or null. */\n  lastRoute: string | string[] | null;\n  /** Carried forward from the loaded checkpoint (compaction progress). */\n  summarizedThrough: number | null;\n};\n\n/**\n * Summarize a supervisor dispatch decision into the `last_route`\n * checkpoint column (§4 Phase 6). A bare string passes through; a\n * fan-out array passes through; the `END` sentinel and anything else\n * collapse to `null` (the turn routed nowhere worth recording).\n */\nexport function summarizeRoute(next: Next | undefined): string | string[] | null {\n  if (typeof next === \"string\") {\n    return next === \"__warlock:end__\" ? null : next;\n  }\n\n  if (Array.isArray(next)) {\n    return next;\n  }\n\n  return null;\n}\n\n/**\n * Phase 6 — persist checkpoint (orchestrator.md §3 / §4 Phase 6).\n * Writes a fresh append-only row at `turn_index = N` carrying the\n * post-merge `state`, the current `signature` (read by the next call's\n * Phase 2), the informational `version`, the dispatch `last_route`, and\n * the carried-forward `summarized_through`. Lock columns are written\n * `null` here — they are populated only by an in-flight Phase 7\n * compaction.\n *\n * Emits `orchestrator.checkpoint.persisted` after the row lands, then\n * prunes to `keepSnapshots` (default 100; `\"all\"` opts out) — §4 Phase\n * 6 pruning (Q20). Pruning runs only when the store exposes the\n * optional `prune` hook (memory/pg/redis own their own pruning); when\n * absent the write still succeeds.\n *\n * Returns the persisted record so the engine can fold it into the\n * turn's report.\n */\nexport async function persistCheckpoint<TState>(\n  params: PersistParams<TState>,\n): Promise<CheckpointRecord> {\n  const { ctx, sessionId, turnIndex, state, lastRoute, summarizedThrough } = params;\n\n  const record: CheckpointRecord = {\n    orchestrator_name: ctx.config.name,\n    session_id: sessionId,\n    turn_index: turnIndex,\n    state,\n    last_route: lastRoute,\n    signature: ctx.signature,\n    version: ctx.config.version ?? null,\n    summarized_through: summarizedThrough,\n    lock_acquired_at: null,\n    lock_expires_at: null,\n    saved_at: new Date().toISOString(),\n  };\n\n  await ctx.checkpointStore.save(record);\n\n  ctx.emitter.emit(\"orchestrator.checkpoint.persisted\", {\n    sessionId,\n    turnIndex,\n  });\n\n  await prune(ctx, sessionId, turnIndex);\n\n  return record;\n}\n\n/**\n * Prune session rows older than `max_turn_index - keepSnapshots` (§4\n * Phase 6). Synchronous-after-save; opted out with\n * `keepSnapshots: \"all\"`. Delegated to an optional store-side `prune`\n * hook so each driver implements deletion in its own dialect — the\n * engine never reaches into store internals.\n */\nasync function prune<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n  latestTurnIndex: number,\n): Promise<void> {\n  const keep = ctx.config.keepSnapshots ?? DEFAULT_KEEP_SNAPSHOTS;\n\n  if (keep === \"all\") {\n    return;\n  }\n\n  const store = ctx.checkpointStore as {\n    prune?: (\n      orchestratorName: string,\n      sessionId: string,\n      keepBeforeTurnIndex: number,\n    ) => Promise<void>;\n  };\n\n  if (typeof store.prune !== \"function\") {\n    return;\n  }\n\n  const keepBeforeTurnIndex = latestTurnIndex - keep + 1;\n\n  if (keepBeforeTurnIndex <= 0) {\n    return;\n  }\n\n  await store.prune(ctx.config.name, sessionId, keepBeforeTurnIndex);\n}\n"],"mappings":";;AAKA,MAAa,yBAAyB;;;;;;;AAoBtC,SAAgB,eAAe,MAAkD;CAC/E,IAAI,OAAO,SAAS,UAClB,OAAO,SAAS,oBAAoB,OAAO;CAG7C,IAAI,MAAM,QAAQ,IAAI,GACpB,OAAO;CAGT,OAAO;AACT;;;;;;;;;;;;;;;;;;;AAoBA,eAAsB,kBACpB,QAC2B;CAC3B,MAAM,EAAE,KAAK,WAAW,WAAW,OAAO,WAAW,sBAAsB;CAE3E,MAAM,SAA2B;EAC/B,mBAAmB,IAAI,OAAO;EAC9B,YAAY;EACZ,YAAY;EACZ;EACA,YAAY;EACZ,WAAW,IAAI;EACf,SAAS,IAAI,OAAO,WAAW;EAC/B,oBAAoB;EACpB,kBAAkB;EAClB,iBAAiB;EACjB,2BAAU,IAAI,KAAK,EAAC,CAAC,YAAY;CACnC;CAEA,MAAM,IAAI,gBAAgB,KAAK,MAAM;CAErC,IAAI,QAAQ,KAAK,qCAAqC;EACpD;EACA;CACF,CAAC;CAED,MAAM,MAAM,KAAK,WAAW,SAAS;CAErC,OAAO;AACT;;;;;;;;AASA,eAAe,MACb,KACA,WACA,iBACe;CACf,MAAM,OAAO,IAAI,OAAO;CAExB,IAAI,SAAS,OACX;CAGF,MAAM,QAAQ,IAAI;CAQlB,IAAI,OAAO,MAAM,UAAU,YACzB;CAGF,MAAM,sBAAsB,kBAAkB,OAAO;CAErD,IAAI,uBAAuB,GACzB;CAGF,MAAM,MAAM,MAAM,IAAI,OAAO,MAAM,WAAW,mBAAmB;AACnE"}

package/esm/ai/src/orchestrator/commands.mjs

@@ -0,0 +1,34 @@
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import "../errors/index.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/commands.ts
+/**
+* Build the typed `command(name, args)` dispatcher backing
+* {@link import("../contracts/orchestrator/orchestrator.contract").OrchestratorContract.command}
+* (design §11). Looks the command up in the supplied handler bag and
+* forwards `args`, preserving the discriminated `OrchestratorCommands`
+* typing end to end.
+*
+* v1 ships exactly one built-in command, `compact`. v2 user commands
+* attach via module augmentation of `OrchestratorCommands`; the
+* dispatcher widens with the map automatically, and an unregistered
+* command throws {@link SupervisorFailedError} rather than silently
+* resolving `undefined`.
+*
+* @example
+* const command = createCommandDispatcher({
+*   compact: (args) => runCompaction(args),
+* });
+* const result = await command("compact", { sessionId, history });
+*/
+function createCommandDispatcher(handlers) {
+	return function command(name, args) {
+		const handler = handlers[name];
+		if (typeof handler !== "function") throw new SupervisorFailedError(`orchestrator.command(): unknown command "${String(name)}"`);
+		return handler(args);
+	};
+}
+
+//#endregion
+export { createCommandDispatcher };
+//# sourceMappingURL=commands.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commands.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/commands.ts"],"sourcesContent":["import type { OrchestratorCommands } from \"../contracts/orchestrator/orchestrator-commands.type\";\nimport { SupervisorFailedError } from \"../errors\";\n\n/**\n * Per-command handler bag — one async runner per key of\n * {@link OrchestratorCommands}. The orchestrator factory supplies the\n * `compact` runner (which delegates to the shared compaction code path,\n * §11) so this module owns command ROUTING only, never the compaction\n * logic itself.\n *\n * Typed against the same discriminated map the public `command<K>`\n * method uses, so a registered handler's `args` / result line up with\n * the contract with no casting at the call site.\n */\nexport type OrchestratorCommandHandlers = {\n  [K in keyof OrchestratorCommands]: (\n    args: OrchestratorCommands[K][\"args\"],\n  ) => Promise<OrchestratorCommands[K][\"result\"]>;\n};\n\n/**\n * Build the typed `command(name, args)` dispatcher backing\n * {@link import(\"../contracts/orchestrator/orchestrator.contract\").OrchestratorContract.command}\n * (design §11). Looks the command up in the supplied handler bag and\n * forwards `args`, preserving the discriminated `OrchestratorCommands`\n * typing end to end.\n *\n * v1 ships exactly one built-in command, `compact`. v2 user commands\n * attach via module augmentation of `OrchestratorCommands`; the\n * dispatcher widens with the map automatically, and an unregistered\n * command throws {@link SupervisorFailedError} rather than silently\n * resolving `undefined`.\n *\n * @example\n * const command = createCommandDispatcher({\n *   compact: (args) => runCompaction(args),\n * });\n * const result = await command(\"compact\", { sessionId, history });\n */\nexport function createCommandDispatcher(handlers: OrchestratorCommandHandlers) {\n  return function command<K extends keyof OrchestratorCommands>(\n    name: K,\n    args: OrchestratorCommands[K][\"args\"],\n  ): Promise<OrchestratorCommands[K][\"result\"]> {\n    const handler = handlers[name];\n\n    if (typeof handler !== \"function\") {\n      throw new SupervisorFailedError(\n        `orchestrator.command(): unknown command \"${String(name)}\"`,\n      );\n    }\n\n    return handler(args);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,wBAAwB,UAAuC;CAC7E,OAAO,SAAS,QACd,MACA,MAC4C;EAC5C,MAAM,UAAU,SAAS;EAEzB,IAAI,OAAO,YAAY,YACrB,MAAM,IAAI,sBACR,4CAA4C,OAAO,IAAI,EAAE,EAC3D;EAGF,OAAO,QAAQ,IAAI;CACrB;AACF"}