@warlock.js/ai 4.2.11 → 4.3.0

package/esm/orchestrator/memory.d.mts

@@ -0,0 +1,84 @@
+import { SupervisorInput } from "../contracts/supervisor/supervisor-input.type.mjs";
+import { TurnSnapshot } from "../contracts/result/orchestrator-result.type.mjs";
+import { RecalledMemory } from "../contracts/memory/memory-item.type.mjs";
+import { MemoryContract } from "../contracts/memory/memory.contract.mjs";
+import { OrchestratorMemoryConfig } from "../contracts/orchestrator/orchestrator-config.type.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/memory.d.ts
+/**
+ * Memory wiring resolved once per turn from `OrchestratorConfig.memory`
+ * (memory core M2). Normalizes the two accepted config shapes — a bare
+ * {@link MemoryContract} or the richer {@link OrchestratorMemoryConfig} —
+ * into a single flat record the lifecycle phase reads, so `runTurn` never
+ * branches on which form the dev supplied.
+ */
+type ResolvedOrchestratorMemory = {
+  /** The store recalled-from before dispatch and remembered-into after. */store: MemoryContract; /** Recall count cap; `0` disables recall (write-only memory). */
+  k?: number; /** Semantic-similarity floor for recall. */
+  threshold?: number; /** Single-tier recall restriction. */
+  tier?: ResolvedTier; /** Whether a clean turn writes its outcome back. Default `true`. */
+  remember: boolean; /** Tier the remembered outcome lands in. Omit for the memory's `defaultTier`. */
+  rememberTier?: ResolvedTier; /** Context-bag key the recalled memories are injected under. */
+  injectKey: string;
+};
+type ResolvedTier = NonNullable<OrchestratorMemoryConfig["recall"]>["tier"];
+/**
+ * Normalize `OrchestratorConfig.memory` into {@link ResolvedOrchestratorMemory},
+ * or `undefined` when no memory is configured. Centralizes the
+ * bare-store-vs-config distinction so the engine context carries one
+ * shape and the lifecycle phase stays branch-free.
+ */
+declare function resolveOrchestratorMemory(memory: MemoryContract | OrchestratorMemoryConfig | undefined): ResolvedOrchestratorMemory | undefined;
+/**
+ * Coerce a turn's {@link SupervisorInput} (string or structured object)
+ * into the natural-language query the memory store recalls / embeds
+ * against. Strings pass through; objects are JSON-serialized — the same
+ * coercion the supervisor applies when forwarding an object input to a
+ * child agent without an explicit `input(ctx)` override.
+ */
+declare function memoryQueryFromInput(input: SupervisorInput): string;
+/**
+ * Recall the memories relevant to a turn's input (memory core M2 — the
+ * pre-dispatch half). Returns the scored {@link RecalledMemory}[] the
+ * lifecycle injects into the turn's `context` bag under
+ * `memory.injectKey`. Returns an empty array — never throws on "no hits"
+ * — and short-circuits when `k === 0` (recall disabled / write-only
+ * memory) so a write-only config never round-trips the embedder.
+ */
+declare function recallForTurn(memory: ResolvedOrchestratorMemory, input: SupervisorInput): Promise<RecalledMemory[]>;
+/**
+ * Merge the recalled memories into a fresh per-turn context bag under
+ * `memory.injectKey` (memory core M2 — the injection half). Never
+ * mutates the caller's `context` object — returns a new bag (or the
+ * original when there is nothing to inject) so the request-scoped input
+ * stays immutable, and the supervisor's intake (which freezes a
+ * shallow copy) sees the recalled set on every `ctx.context[injectKey]`.
+ *
+ * A pre-existing value at `injectKey` is preserved when recall produced
+ * nothing, and overwritten with the recalled set otherwise — the
+ * orchestrator owns that key once memory is configured.
+ */
+declare function injectMemories(context: Record<string, unknown> | undefined, memory: ResolvedOrchestratorMemory, recalled: RecalledMemory[]): Record<string, unknown> | undefined;
+/**
+ * Remember a settled turn's outcome (memory core M2 — the post-dispatch
+ * half). Called only after a clean turn (cancelled / failed turns revert
+ * and never remember — §17). No-ops when `remember` is `false`
+ * (read-only memory) or when the produced text is empty.
+ *
+ * The remembered text is the turn input followed by the model's textual
+ * outcome when one is available, so a later `recall` keyed on a similar
+ * input surfaces both the prior question and its answer.
+ */
+declare function rememberTurnOutcome(memory: ResolvedOrchestratorMemory, input: SupervisorInput, outcomeText: string | undefined): Promise<void>;
+/**
+ * Derive a turn's textual outcome for remembering (memory core M2).
+ * Prefers the validated `result.data` (an `output` schema reshaped it);
+ * otherwise stringifies the dispatched intents' branch outputs from the
+ * turn snapshot, joined newline-wise so a multi-branch fan-out
+ * contributes every output. Returns `undefined` when the turn produced
+ * no usable text — the caller then remembers the input alone.
+ */
+declare function outcomeTextFromTurn(data: unknown, turnSnapshot: TurnSnapshot): string | undefined;
+//#endregion
+export { ResolvedOrchestratorMemory, injectMemories, memoryQueryFromInput, outcomeTextFromTurn, recallForTurn, rememberTurnOutcome, resolveOrchestratorMemory };
+//# sourceMappingURL=memory.d.mts.map

package/esm/orchestrator/memory.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/memory.ts"],"mappings":";;;;;;;;;AAmBA;;;;;KAAY,0BAAA;EAYiB,yEAV3B,KAAA,EAAO,cAAA,EAAP;EAEA,CAAA;EAEA,SAAA,WAEA;EAAA,IAAA,GAAO,YAAA,EAEP;EAAA,QAAA,WAEe;EAAf,YAAA,GAAe,YAAA,EAEN;EAAT,SAAA;AAAA;AAAA,KAGG,YAAA,GAAe,WAAW,CAAC,wBAAA;;;AAAwB;AAoBxD;;;iBAAgB,yBAAA,CACd,MAAA,EAAQ,cAAA,GAAiB,wBAAA,eACxB,0BAAA;;;;;;;;iBA+Ba,oBAAA,CAAqB,KAAsB,EAAf,eAAe;;AA/B9B;AA+B7B;;;;AAA2D;AAY3D;iBAAsB,aAAA,CACpB,MAAA,EAAQ,0BAAA,EACR,KAAA,EAAO,eAAA,GACN,OAAA,CAAQ,cAAA;;;;;;;;;;;;;iBAwBK,cAAA,CACd,OAAA,EAAS,MAAA,+BACT,MAAA,EAAQ,0BAAA,EACR,QAAA,EAAU,cAAA,KACT,MAAA;;AA5BsB;AAwBzB;;;;;;;;iBAsBsB,mBAAA,CACpB,MAAA,EAAQ,0BAAA,EACR,KAAA,EAAO,eAAA,EACP,WAAA,uBACC,OAAA;;;;;;;;;iBA4Ca,mBAAA,CACd,IAAA,WACA,YAAA,EAAc,YAAY"}

package/esm/orchestrator/memory.mjs

@@ -0,0 +1,141 @@
+//#region ../@warlock.js/ai/src/orchestrator/memory.ts
+/** Default key the recalled memories are injected under in the context bag. */
+const DEFAULT_INJECT_KEY = "memories";
+/**
+* A `MemoryContract` is the bare-store form; anything carrying a `store`
+* is the {@link OrchestratorMemoryConfig} wrapper. Distinguished by the
+* presence of `recall` — a method on the contract, absent on the config
+* (whose own `recall` is a plain options object, never a function).
+*/
+function isBareMemory(value) {
+	return typeof value.recall === "function";
+}
+/**
+* Normalize `OrchestratorConfig.memory` into {@link ResolvedOrchestratorMemory},
+* or `undefined` when no memory is configured. Centralizes the
+* bare-store-vs-config distinction so the engine context carries one
+* shape and the lifecycle phase stays branch-free.
+*/
+function resolveOrchestratorMemory(memory) {
+	if (!memory) return;
+	if (isBareMemory(memory)) return {
+		store: memory,
+		remember: true,
+		injectKey: DEFAULT_INJECT_KEY
+	};
+	return {
+		store: memory.store,
+		k: memory.recall?.k,
+		threshold: memory.recall?.threshold,
+		tier: memory.recall?.tier,
+		remember: memory.remember ?? true,
+		rememberTier: memory.rememberTier,
+		injectKey: memory.injectKey ?? DEFAULT_INJECT_KEY
+	};
+}
+/**
+* Coerce a turn's {@link SupervisorInput} (string or structured object)
+* into the natural-language query the memory store recalls / embeds
+* against. Strings pass through; objects are JSON-serialized — the same
+* coercion the supervisor applies when forwarding an object input to a
+* child agent without an explicit `input(ctx)` override.
+*/
+function memoryQueryFromInput(input) {
+	return typeof input === "string" ? input : JSON.stringify(input);
+}
+/**
+* Recall the memories relevant to a turn's input (memory core M2 — the
+* pre-dispatch half). Returns the scored {@link RecalledMemory}[] the
+* lifecycle injects into the turn's `context` bag under
+* `memory.injectKey`. Returns an empty array — never throws on "no hits"
+* — and short-circuits when `k === 0` (recall disabled / write-only
+* memory) so a write-only config never round-trips the embedder.
+*/
+async function recallForTurn(memory, input) {
+	if (memory.k === 0) return [];
+	return memory.store.recall(memoryQueryFromInput(input), {
+		k: memory.k,
+		threshold: memory.threshold,
+		tier: memory.tier
+	});
+}
+/**
+* Merge the recalled memories into a fresh per-turn context bag under
+* `memory.injectKey` (memory core M2 — the injection half). Never
+* mutates the caller's `context` object — returns a new bag (or the
+* original when there is nothing to inject) so the request-scoped input
+* stays immutable, and the supervisor's intake (which freezes a
+* shallow copy) sees the recalled set on every `ctx.context[injectKey]`.
+*
+* A pre-existing value at `injectKey` is preserved when recall produced
+* nothing, and overwritten with the recalled set otherwise — the
+* orchestrator owns that key once memory is configured.
+*/
+function injectMemories(context, memory, recalled) {
+	if (recalled.length === 0) return context;
+	return {
+		...context ?? {},
+		[memory.injectKey]: recalled
+	};
+}
+/**
+* Remember a settled turn's outcome (memory core M2 — the post-dispatch
+* half). Called only after a clean turn (cancelled / failed turns revert
+* and never remember — §17). No-ops when `remember` is `false`
+* (read-only memory) or when the produced text is empty.
+*
+* The remembered text is the turn input followed by the model's textual
+* outcome when one is available, so a later `recall` keyed on a similar
+* input surfaces both the prior question and its answer.
+*/
+async function rememberTurnOutcome(memory, input, outcomeText) {
+	if (!memory.remember) return;
+	const text = buildOutcomeText(input, outcomeText);
+	if (!text) return;
+	const item = {
+		text,
+		tier: memory.rememberTier
+	};
+	await memory.store.remember(item);
+}
+/**
+* Compose the text written to memory for a turn: the input query, plus
+* the outcome text on a following line when the dispatch produced one.
+* Returns `undefined` when neither side carries content so an empty turn
+* never pollutes the store.
+*/
+function buildOutcomeText(input, outcomeText) {
+	const query = memoryQueryFromInput(input).trim();
+	const outcome = outcomeText?.trim();
+	if (query && outcome) return `${query}\n${outcome}`;
+	return query || outcome || void 0;
+}
+/**
+* Derive a turn's textual outcome for remembering (memory core M2).
+* Prefers the validated `result.data` (an `output` schema reshaped it);
+* otherwise stringifies the dispatched intents' branch outputs from the
+* turn snapshot, joined newline-wise so a multi-branch fan-out
+* contributes every output. Returns `undefined` when the turn produced
+* no usable text — the caller then remembers the input alone.
+*/
+function outcomeTextFromTurn(data, turnSnapshot) {
+	const fromData = stringifyOutcome(data);
+	if (fromData) return fromData;
+	const outputs = Object.values(turnSnapshot.result).map((branch) => stringifyOutcome(branch.output)).filter((text) => Boolean(text));
+	return outputs.length > 0 ? outputs.join("\n") : void 0;
+}
+/**
+* Coerce one outcome value to text: strings pass through; everything
+* else (objects, numbers) is JSON-serialized. `undefined` / `null` and
+* empty strings collapse to `undefined` so they don't masquerade as
+* content.
+*/
+function stringifyOutcome(value) {
+	if (value === void 0 || value === null) return;
+	const text = typeof value === "string" ? value : JSON.stringify(value);
+	return text.trim() ? text : void 0;
+}
+
+//#endregion
+export { injectMemories, memoryQueryFromInput, outcomeTextFromTurn, recallForTurn, rememberTurnOutcome, resolveOrchestratorMemory };
+//# sourceMappingURL=memory.mjs.map

package/esm/orchestrator/memory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/memory.ts"],"sourcesContent":["import type { MemoryContract } from \"../contracts/memory/memory.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport type { OrchestratorMemoryConfig } from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type { TurnSnapshot } from \"../contracts/result/orchestrator-result.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\n\n/** Default key the recalled memories are injected under in the context bag. */\nconst DEFAULT_INJECT_KEY = \"memories\";\n\n/**\n * Memory wiring resolved once per turn from `OrchestratorConfig.memory`\n * (memory core M2). Normalizes the two accepted config shapes — a bare\n * {@link MemoryContract} or the richer {@link OrchestratorMemoryConfig} —\n * into a single flat record the lifecycle phase reads, so `runTurn` never\n * branches on which form the dev supplied.\n */\nexport type ResolvedOrchestratorMemory = {\n  /** The store recalled-from before dispatch and remembered-into after. */\n  store: MemoryContract;\n  /** Recall count cap; `0` disables recall (write-only memory). */\n  k?: number;\n  /** Semantic-similarity floor for recall. */\n  threshold?: number;\n  /** Single-tier recall restriction. */\n  tier?: ResolvedTier;\n  /** Whether a clean turn writes its outcome back. Default `true`. */\n  remember: boolean;\n  /** Tier the remembered outcome lands in. Omit for the memory's `defaultTier`. */\n  rememberTier?: ResolvedTier;\n  /** Context-bag key the recalled memories are injected under. */\n  injectKey: string;\n};\n\ntype ResolvedTier = NonNullable<OrchestratorMemoryConfig[\"recall\"]>[\"tier\"];\n\n/**\n * A `MemoryContract` is the bare-store form; anything carrying a `store`\n * is the {@link OrchestratorMemoryConfig} wrapper. Distinguished by the\n * presence of `recall` — a method on the contract, absent on the config\n * (whose own `recall` is a plain options object, never a function).\n */\nfunction isBareMemory(\n  value: MemoryContract | OrchestratorMemoryConfig,\n): value is MemoryContract {\n  return typeof (value as MemoryContract).recall === \"function\";\n}\n\n/**\n * Normalize `OrchestratorConfig.memory` into {@link ResolvedOrchestratorMemory},\n * or `undefined` when no memory is configured. Centralizes the\n * bare-store-vs-config distinction so the engine context carries one\n * shape and the lifecycle phase stays branch-free.\n */\nexport function resolveOrchestratorMemory(\n  memory: MemoryContract | OrchestratorMemoryConfig | undefined,\n): ResolvedOrchestratorMemory | undefined {\n  if (!memory) {\n    return undefined;\n  }\n\n  if (isBareMemory(memory)) {\n    return {\n      store: memory,\n      remember: true,\n      injectKey: DEFAULT_INJECT_KEY,\n    };\n  }\n\n  return {\n    store: memory.store,\n    k: memory.recall?.k,\n    threshold: memory.recall?.threshold,\n    tier: memory.recall?.tier,\n    remember: memory.remember ?? true,\n    rememberTier: memory.rememberTier,\n    injectKey: memory.injectKey ?? DEFAULT_INJECT_KEY,\n  };\n}\n\n/**\n * Coerce a turn's {@link SupervisorInput} (string or structured object)\n * into the natural-language query the memory store recalls / embeds\n * against. Strings pass through; objects are JSON-serialized — the same\n * coercion the supervisor applies when forwarding an object input to a\n * child agent without an explicit `input(ctx)` override.\n */\nexport function memoryQueryFromInput(input: SupervisorInput): string {\n  return typeof input === \"string\" ? input : JSON.stringify(input);\n}\n\n/**\n * Recall the memories relevant to a turn's input (memory core M2 — the\n * pre-dispatch half). Returns the scored {@link RecalledMemory}[] the\n * lifecycle injects into the turn's `context` bag under\n * `memory.injectKey`. Returns an empty array — never throws on \"no hits\"\n * — and short-circuits when `k === 0` (recall disabled / write-only\n * memory) so a write-only config never round-trips the embedder.\n */\nexport async function recallForTurn(\n  memory: ResolvedOrchestratorMemory,\n  input: SupervisorInput,\n): Promise<RecalledMemory[]> {\n  if (memory.k === 0) {\n    return [];\n  }\n\n  return memory.store.recall(memoryQueryFromInput(input), {\n    k: memory.k,\n    threshold: memory.threshold,\n    tier: memory.tier,\n  });\n}\n\n/**\n * Merge the recalled memories into a fresh per-turn context bag under\n * `memory.injectKey` (memory core M2 — the injection half). Never\n * mutates the caller's `context` object — returns a new bag (or the\n * original when there is nothing to inject) so the request-scoped input\n * stays immutable, and the supervisor's intake (which freezes a\n * shallow copy) sees the recalled set on every `ctx.context[injectKey]`.\n *\n * A pre-existing value at `injectKey` is preserved when recall produced\n * nothing, and overwritten with the recalled set otherwise — the\n * orchestrator owns that key once memory is configured.\n */\nexport function injectMemories(\n  context: Record<string, unknown> | undefined,\n  memory: ResolvedOrchestratorMemory,\n  recalled: RecalledMemory[],\n): Record<string, unknown> | undefined {\n  if (recalled.length === 0) {\n    return context;\n  }\n\n  return { ...(context ?? {}), [memory.injectKey]: recalled };\n}\n\n/**\n * Remember a settled turn's outcome (memory core M2 — the post-dispatch\n * half). Called only after a clean turn (cancelled / failed turns revert\n * and never remember — §17). No-ops when `remember` is `false`\n * (read-only memory) or when the produced text is empty.\n *\n * The remembered text is the turn input followed by the model's textual\n * outcome when one is available, so a later `recall` keyed on a similar\n * input surfaces both the prior question and its answer.\n */\nexport async function rememberTurnOutcome(\n  memory: ResolvedOrchestratorMemory,\n  input: SupervisorInput,\n  outcomeText: string | undefined,\n): Promise<void> {\n  if (!memory.remember) {\n    return;\n  }\n\n  const text = buildOutcomeText(input, outcomeText);\n\n  if (!text) {\n    return;\n  }\n\n  const item: MemoryItem = { text, tier: memory.rememberTier };\n\n  await memory.store.remember(item);\n}\n\n/**\n * Compose the text written to memory for a turn: the input query, plus\n * the outcome text on a following line when the dispatch produced one.\n * Returns `undefined` when neither side carries content so an empty turn\n * never pollutes the store.\n */\nfunction buildOutcomeText(\n  input: SupervisorInput,\n  outcomeText: string | undefined,\n): string | undefined {\n  const query = memoryQueryFromInput(input).trim();\n  const outcome = outcomeText?.trim();\n\n  if (query && outcome) {\n    return `${query}\\n${outcome}`;\n  }\n\n  return query || outcome || undefined;\n}\n\n/**\n * Derive a turn's textual outcome for remembering (memory core M2).\n * Prefers the validated `result.data` (an `output` schema reshaped it);\n * otherwise stringifies the dispatched intents' branch outputs from the\n * turn snapshot, joined newline-wise so a multi-branch fan-out\n * contributes every output. Returns `undefined` when the turn produced\n * no usable text — the caller then remembers the input alone.\n */\nexport function outcomeTextFromTurn(\n  data: unknown,\n  turnSnapshot: TurnSnapshot,\n): string | undefined {\n  const fromData = stringifyOutcome(data);\n\n  if (fromData) {\n    return fromData;\n  }\n\n  const outputs = Object.values(turnSnapshot.result)\n    .map((branch) => stringifyOutcome(branch.output))\n    .filter((text): text is string => Boolean(text));\n\n  return outputs.length > 0 ? outputs.join(\"\\n\") : undefined;\n}\n\n/**\n * Coerce one outcome value to text: strings pass through; everything\n * else (objects, numbers) is JSON-serialized. `undefined` / `null` and\n * empty strings collapse to `undefined` so they don't masquerade as\n * content.\n */\nfunction stringifyOutcome(value: unknown): string | undefined {\n  if (value === undefined || value === null) {\n    return undefined;\n  }\n\n  const text = typeof value === \"string\" ? value : JSON.stringify(value);\n\n  return text.trim() ? text : undefined;\n}\n"],"mappings":";;AAUA,MAAM,qBAAqB;;;;;;;AAkC3B,SAAS,aACP,OACyB;CACzB,OAAO,OAAQ,MAAyB,WAAW;AACrD;;;;;;;AAQA,SAAgB,0BACd,QACwC;CACxC,IAAI,CAAC,QACH;CAGF,IAAI,aAAa,MAAM,GACrB,OAAO;EACL,OAAO;EACP,UAAU;EACV,WAAW;CACb;CAGF,OAAO;EACL,OAAO,OAAO;EACd,GAAG,OAAO,QAAQ;EAClB,WAAW,OAAO,QAAQ;EAC1B,MAAM,OAAO,QAAQ;EACrB,UAAU,OAAO,YAAY;EAC7B,cAAc,OAAO;EACrB,WAAW,OAAO,aAAa;CACjC;AACF;;;;;;;;AASA,SAAgB,qBAAqB,OAAgC;CACnE,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;AACjE;;;;;;;;;AAUA,eAAsB,cACpB,QACA,OAC2B;CAC3B,IAAI,OAAO,MAAM,GACf,OAAO,CAAC;CAGV,OAAO,OAAO,MAAM,OAAO,qBAAqB,KAAK,GAAG;EACtD,GAAG,OAAO;EACV,WAAW,OAAO;EAClB,MAAM,OAAO;CACf,CAAC;AACH;;;;;;;;;;;;;AAcA,SAAgB,eACd,SACA,QACA,UACqC;CACrC,IAAI,SAAS,WAAW,GACtB,OAAO;CAGT,OAAO;EAAE,GAAI,WAAW,CAAC;GAAK,OAAO,YAAY;CAAS;AAC5D;;;;;;;;;;;AAYA,eAAsB,oBACpB,QACA,OACA,aACe;CACf,IAAI,CAAC,OAAO,UACV;CAGF,MAAM,OAAO,iBAAiB,OAAO,WAAW;CAEhD,IAAI,CAAC,MACH;CAGF,MAAM,OAAmB;EAAE;EAAM,MAAM,OAAO;CAAa;CAE3D,MAAM,OAAO,MAAM,SAAS,IAAI;AAClC;;;;;;;AAQA,SAAS,iBACP,OACA,aACoB;CACpB,MAAM,QAAQ,qBAAqB,KAAK,CAAC,CAAC,KAAK;CAC/C,MAAM,UAAU,aAAa,KAAK;CAElC,IAAI,SAAS,SACX,OAAO,GAAG,MAAM,IAAI;CAGtB,OAAO,SAAS,WAAW;AAC7B;;;;;;;;;AAUA,SAAgB,oBACd,MACA,cACoB;CACpB,MAAM,WAAW,iBAAiB,IAAI;CAEtC,IAAI,UACF,OAAO;CAGT,MAAM,UAAU,OAAO,OAAO,aAAa,MAAM,CAAC,CAC/C,KAAK,WAAW,iBAAiB,OAAO,MAAM,CAAC,CAAC,CAChD,QAAQ,SAAyB,QAAQ,IAAI,CAAC;CAEjD,OAAO,QAAQ,SAAS,IAAI,QAAQ,KAAK,IAAI,IAAI;AACnD;;;;;;;AAQA,SAAS,iBAAiB,OAAoC;CAC5D,IAAI,UAAU,UAAa,UAAU,MACnC;CAGF,MAAM,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;CAErE,OAAO,KAAK,KAAK,IAAI,OAAO;AAC9B"}

package/esm/orchestrator/orchestrator-stream.d.mts

@@ -0,0 +1,42 @@
+import { StreamContract } from "../contracts/stream/stream.contract.mjs";
+import { OrchestratorEvent } from "../contracts/orchestrator/orchestrator-event.type.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/orchestrator-stream.d.ts
+/**
+ * Internal async-queue controller driving `orchestrator.stream()`.
+ * Mirrors {@link import("../supervisor/supervisor-stream").createSupervisorStream}'s
+ * controller — same producer/consumer pipe, parameterized by the
+ * orchestrator event union and the terminal result type.
+ *
+ * The turn pushes events as it advances through the lifecycle phases,
+ * then settles with `end(result)` (the same `OrchestratorResult` that
+ * `execute()` resolves) or `fail(error)` on an authoring/drift throw.
+ */
+type OrchestratorStreamController<TResult> = {
+  push(event: OrchestratorEvent): void;
+  end(result: TResult): void;
+  fail(error: Error): void;
+};
+/**
+ * Factory mirroring `createSupervisorStream`. Returns a paired
+ * `{ controller, stream }` — the turn pushes events into the controller
+ * while the caller iterates (or awaits `.result`) on the stream side.
+ *
+ * The `result` promise resolves to the same `OrchestratorResult` value
+ * `execute()` produces; it rejects only when the turn throws before
+ * producing a result (drift / config misuse) — runtime failures ride on
+ * `result.error` and still settle via `end()`.
+ *
+ * Child `supervisor.*` / `agent.*` events bubble through this same pipe
+ * unmodified (the turn forwards them as it observes them on the
+ * delegated run); they share the `{ type, ...payload }` shape with the
+ * orchestrator's own events so iteration narrows uniformly on
+ * `event.type`.
+ */
+declare function createOrchestratorStream<TResult>(): {
+  controller: OrchestratorStreamController<TResult>;
+  stream: StreamContract<TResult, OrchestratorEvent>;
+};
+//#endregion
+export { OrchestratorStreamController, createOrchestratorStream };
+//# sourceMappingURL=orchestrator-stream.d.mts.map

package/esm/orchestrator/orchestrator-stream.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-stream.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/orchestrator-stream.ts"],"mappings":";;;;;;AAaA;;;;;;;;KAAY,4BAAA;EACV,IAAA,CAAK,KAAA,EAAO,iBAAA;EACZ,GAAA,CAAI,MAAA,EAAQ,OAAA;EACZ,IAAA,CAAK,KAAA,EAAO,KAAA;AAAA;;;;;;;AAAK;AAwBnB;;;;;;;;;iBAAgB,wBAAA;EACd,UAAA,EAAY,4BAAA,CAA6B,OAAA;EACzC,MAAA,EAAQ,cAAA,CAAe,OAAA,EAAS,iBAAA;AAAA"}

package/esm/orchestrator/orchestrator-stream.mjs

@@ -0,0 +1,98 @@
+//#region ../@warlock.js/ai/src/orchestrator/orchestrator-stream.ts
+/**
+* Factory mirroring `createSupervisorStream`. Returns a paired
+* `{ controller, stream }` — the turn pushes events into the controller
+* while the caller iterates (or awaits `.result`) on the stream side.
+*
+* The `result` promise resolves to the same `OrchestratorResult` value
+* `execute()` produces; it rejects only when the turn throws before
+* producing a result (drift / config misuse) — runtime failures ride on
+* `result.error` and still settle via `end()`.
+*
+* Child `supervisor.*` / `agent.*` events bubble through this same pipe
+* unmodified (the turn forwards them as it observes them on the
+* delegated run); they share the `{ type, ...payload }` shape with the
+* orchestrator's own events so iteration narrows uniformly on
+* `event.type`.
+*/
+function createOrchestratorStream() {
+	const queue = [];
+	const pending = [];
+	const handlers = /* @__PURE__ */ new Map();
+	let closed = false;
+	let failure;
+	let resolveResult;
+	let rejectResult;
+	const result = new Promise((resolve, reject) => {
+		resolveResult = resolve;
+		rejectResult = reject;
+	});
+	const controller = {
+		push(event) {
+			const handler = handlers.get(event.type);
+			if (handler) try {
+				handler(event);
+			} catch {}
+			const reader = pending.shift();
+			if (reader) {
+				reader.resolve({
+					value: event,
+					done: false
+				});
+				return;
+			}
+			queue.push(event);
+		},
+		end(finalResult) {
+			closed = true;
+			resolveResult(finalResult);
+			while (pending.length > 0) pending.shift()?.resolve({
+				value: void 0,
+				done: true
+			});
+		},
+		fail(error) {
+			closed = true;
+			failure = error;
+			rejectResult(error);
+			while (pending.length > 0) pending.shift()?.reject(error);
+		}
+	};
+	const iterator = { next() {
+		if (queue.length > 0) return Promise.resolve({
+			value: queue.shift(),
+			done: false
+		});
+		if (closed) {
+			if (failure) return Promise.reject(failure);
+			return Promise.resolve({
+				value: void 0,
+				done: true
+			});
+		}
+		return new Promise((resolve, reject) => {
+			pending.push({
+				resolve,
+				reject
+			});
+		});
+	} };
+	const stream = {
+		result,
+		on(handlerMap) {
+			for (const [key, handler] of Object.entries(handlerMap)) if (handler) handlers.set(key, handler);
+			return stream;
+		},
+		[Symbol.asyncIterator]() {
+			return iterator;
+		}
+	};
+	return {
+		controller,
+		stream
+	};
+}
+
+//#endregion
+export { createOrchestratorStream };
+//# sourceMappingURL=orchestrator-stream.mjs.map

package/esm/orchestrator/orchestrator-stream.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-stream.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/orchestrator-stream.ts"],"sourcesContent":["import type { OrchestratorEvent } from \"../contracts/orchestrator/orchestrator-event.type\";\nimport type { StreamContract } from \"../contracts/stream/stream.contract\";\n\n/**\n * Internal async-queue controller driving `orchestrator.stream()`.\n * Mirrors {@link import(\"../supervisor/supervisor-stream\").createSupervisorStream}'s\n * controller — same producer/consumer pipe, parameterized by the\n * orchestrator event union and the terminal result type.\n *\n * The turn pushes events as it advances through the lifecycle phases,\n * then settles with `end(result)` (the same `OrchestratorResult` that\n * `execute()` resolves) or `fail(error)` on an authoring/drift throw.\n */\nexport type OrchestratorStreamController<TResult> = {\n  push(event: OrchestratorEvent): void;\n  end(result: TResult): void;\n  fail(error: Error): void;\n};\n\ntype PendingRead = {\n  resolve(value: IteratorResult<OrchestratorEvent>): void;\n  reject(error: Error): void;\n};\n\n/**\n * Factory mirroring `createSupervisorStream`. Returns a paired\n * `{ controller, stream }` — the turn pushes events into the controller\n * while the caller iterates (or awaits `.result`) on the stream side.\n *\n * The `result` promise resolves to the same `OrchestratorResult` value\n * `execute()` produces; it rejects only when the turn throws before\n * producing a result (drift / config misuse) — runtime failures ride on\n * `result.error` and still settle via `end()`.\n *\n * Child `supervisor.*` / `agent.*` events bubble through this same pipe\n * unmodified (the turn forwards them as it observes them on the\n * delegated run); they share the `{ type, ...payload }` shape with the\n * orchestrator's own events so iteration narrows uniformly on\n * `event.type`.\n */\nexport function createOrchestratorStream<TResult>(): {\n  controller: OrchestratorStreamController<TResult>;\n  stream: StreamContract<TResult, OrchestratorEvent>;\n} {\n  const queue: OrchestratorEvent[] = [];\n  const pending: PendingRead[] = [];\n  const handlers = new Map<string, (event: OrchestratorEvent) => void>();\n\n  let closed = false;\n  let failure: Error | undefined;\n  let resolveResult!: (value: TResult) => void;\n  let rejectResult!: (error: Error) => void;\n\n  const result = new Promise<TResult>((resolve, reject) => {\n    resolveResult = resolve;\n    rejectResult = reject;\n  });\n\n  const controller: OrchestratorStreamController<TResult> = {\n    push(event) {\n      const handler = handlers.get(event.type);\n\n      if (handler) {\n        try {\n          handler(event);\n        } catch {\n          // Stream handlers must never crash the orchestrator.\n        }\n      }\n\n      const reader = pending.shift();\n\n      if (reader) {\n        reader.resolve({ value: event, done: false });\n        return;\n      }\n\n      queue.push(event);\n    },\n\n    end(finalResult) {\n      closed = true;\n      resolveResult(finalResult);\n\n      while (pending.length > 0) {\n        pending.shift()?.resolve({ value: undefined, done: true });\n      }\n    },\n\n    fail(error) {\n      closed = true;\n      failure = error;\n      rejectResult(error);\n\n      while (pending.length > 0) {\n        pending.shift()?.reject(error);\n      }\n    },\n  };\n\n  const iterator: AsyncIterator<OrchestratorEvent> = {\n    next() {\n      if (queue.length > 0) {\n        return Promise.resolve({ value: queue.shift()!, done: false });\n      }\n\n      if (closed) {\n        if (failure) {\n          return Promise.reject(failure);\n        }\n\n        return Promise.resolve({ value: undefined, done: true });\n      }\n\n      return new Promise<IteratorResult<OrchestratorEvent>>(\n        (resolve, reject) => {\n          pending.push({ resolve, reject });\n        },\n      );\n    },\n  };\n\n  const stream = {\n    result,\n    on(handlerMap) {\n      for (const [key, handler] of Object.entries(handlerMap)) {\n        if (handler) {\n          handlers.set(key, handler as (event: OrchestratorEvent) => void);\n        }\n      }\n\n      return stream;\n    },\n    [Symbol.asyncIterator]() {\n      return iterator;\n    },\n  } as StreamContract<TResult, OrchestratorEvent>;\n\n  return { controller, stream };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAwCA,SAAgB,2BAGd;CACA,MAAM,QAA6B,CAAC;CACpC,MAAM,UAAyB,CAAC;CAChC,MAAM,2BAAW,IAAI,IAAgD;CAErE,IAAI,SAAS;CACb,IAAI;CACJ,IAAI;CACJ,IAAI;CAEJ,MAAM,SAAS,IAAI,SAAkB,SAAS,WAAW;EACvD,gBAAgB;EAChB,eAAe;CACjB,CAAC;CAED,MAAM,aAAoD;EACxD,KAAK,OAAO;GACV,MAAM,UAAU,SAAS,IAAI,MAAM,IAAI;GAEvC,IAAI,SACF,IAAI;IACF,QAAQ,KAAK;GACf,QAAQ,CAER;GAGF,MAAM,SAAS,QAAQ,MAAM;GAE7B,IAAI,QAAQ;IACV,OAAO,QAAQ;KAAE,OAAO;KAAO,MAAM;IAAM,CAAC;IAC5C;GACF;GAEA,MAAM,KAAK,KAAK;EAClB;EAEA,IAAI,aAAa;GACf,SAAS;GACT,cAAc,WAAW;GAEzB,OAAO,QAAQ,SAAS,GACtB,QAAQ,MAAM,CAAC,EAAE,QAAQ;IAAE,OAAO;IAAW,MAAM;GAAK,CAAC;EAE7D;EAEA,KAAK,OAAO;GACV,SAAS;GACT,UAAU;GACV,aAAa,KAAK;GAElB,OAAO,QAAQ,SAAS,GACtB,QAAQ,MAAM,CAAC,EAAE,OAAO,KAAK;EAEjC;CACF;CAEA,MAAM,WAA6C,EACjD,OAAO;EACL,IAAI,MAAM,SAAS,GACjB,OAAO,QAAQ,QAAQ;GAAE,OAAO,MAAM,MAAM;GAAI,MAAM;EAAM,CAAC;EAG/D,IAAI,QAAQ;GACV,IAAI,SACF,OAAO,QAAQ,OAAO,OAAO;GAG/B,OAAO,QAAQ,QAAQ;IAAE,OAAO;IAAW,MAAM;GAAK,CAAC;EACzD;EAEA,OAAO,IAAI,SACR,SAAS,WAAW;GACnB,QAAQ,KAAK;IAAE;IAAS;GAAO,CAAC;EAClC,CACF;CACF,EACF;CAEA,MAAM,SAAS;EACb;EACA,GAAG,YAAY;GACb,KAAK,MAAM,CAAC,KAAK,YAAY,OAAO,QAAQ,UAAU,GACpD,IAAI,SACF,SAAS,IAAI,KAAK,OAA6C;GAInE,OAAO;EACT;EACA,CAAC,OAAO,iBAAiB;GACvB,OAAO;EACT;CACF;CAEA,OAAO;EAAE;EAAY;CAAO;AAC9B"}

package/esm/orchestrator/orchestrator.d.mts

@@ -0,0 +1,38 @@
+import { SupervisorIntentValue } from "../contracts/supervisor/intent-entry.type.mjs";
+import { OrchestratorContract } from "../contracts/orchestrator/orchestrator.contract.mjs";
+import { OrchestratorConfig } from "../contracts/orchestrator/orchestrator-config.type.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/orchestrator.d.ts
+/**
+ * `ai.orchestrator(config)` — construct an {@link OrchestratorContract}:
+ * a session-state manager wrapped around a supervisor (orchestrator.md
+ * §1, §15). Validates the config at author time (throws
+ * {@link OrchestratorConfigError} on bad shape), resolves the intent
+ * entries, computes a stable structural signature for drift detection
+ * (§10.1), wires the three-tier event emitter, and returns a handle that
+ * runs one durable session turn per `execute` / `stream` call, resumes
+ * an interrupted `iterate: true` turn via `resume`, and exposes typed
+ * built-in commands plus an `asTool` wrapper.
+ *
+ * The "what runs" fields (`intents`, `route` / `router`, `evaluate`,
+ * `state`, `output`, `initialAgent`, `maxIterations`) are the
+ * supervisor's surface spread directly — the lifecycle builds the
+ * supervisor lazily per turn and delegates to it (§3 Phase 5). Users
+ * never see the supervisor object.
+ *
+ * @example
+ * const supportBot = ai.orchestrator<SessionState>({
+ *   name: "refund-support",
+ *   intents: { classify, lookup, process, compose },
+ *   route: (ctx) => (ctx.iteration === 0 ? "classify" : END),
+ *   iterate: true,
+ *   checkpointStore: ai.checkpoint.pg({ client: pg }),
+ *   snapshotStore: ai.snapshot.pg({ client: pg }),
+ * });
+ *
+ * const result = await supportBot.execute(message, { sessionId, history });
+ */
+declare function orchestrator<TOutput = unknown, TState = TOutput, TIntents extends Record<string, SupervisorIntentValue> = Record<string, SupervisorIntentValue>>(config: OrchestratorConfig<TOutput, TState, TIntents>): OrchestratorContract<TOutput, TState>;
+//#endregion
+export { orchestrator };
+//# sourceMappingURL=orchestrator.d.mts.map

package/esm/orchestrator/orchestrator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/orchestrator.ts"],"mappings":";;;;;;;AA4DA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,YAAA,6BAEL,OAAA,mBACQ,MAAA,SAAe,qBAAA,IAAyB,MAAA,SAEvD,qBAAA,GAGF,MAAA,EAAQ,kBAAA,CAAmB,OAAA,EAAS,MAAA,EAAQ,QAAA,IAC3C,oBAAA,CAAqB,OAAA,EAAS,MAAA"}

package/esm/orchestrator/orchestrator.mjs

@@ -0,0 +1,173 @@
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import { OrchestratorConfigError } from "../errors/orchestrator-config-error.mjs";
+import "../errors/index.mjs";
+import { resolveDefaultSnapshotStore } from "../config.mjs";
+import { asTool } from "./as-tool.mjs";
+import { createCommandDispatcher } from "./commands.mjs";
+import { OrchestratorEmitter } from "./emitter.mjs";
+import { resolveIntentEntries } from "../supervisor/entries.mjs";
+import { OrchestratorExecution } from "./execution.mjs";
+import { createOrchestratorStream } from "./orchestrator-stream.mjs";
+import { computeOrchestratorSignature } from "./signature.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/orchestrator.ts
+/**
+* `ai.orchestrator(config)` — construct an {@link OrchestratorContract}:
+* a session-state manager wrapped around a supervisor (orchestrator.md
+* §1, §15). Validates the config at author time (throws
+* {@link OrchestratorConfigError} on bad shape), resolves the intent
+* entries, computes a stable structural signature for drift detection
+* (§10.1), wires the three-tier event emitter, and returns a handle that
+* runs one durable session turn per `execute` / `stream` call, resumes
+* an interrupted `iterate: true` turn via `resume`, and exposes typed
+* built-in commands plus an `asTool` wrapper.
+*
+* The "what runs" fields (`intents`, `route` / `router`, `evaluate`,
+* `state`, `output`, `initialAgent`, `maxIterations`) are the
+* supervisor's surface spread directly — the lifecycle builds the
+* supervisor lazily per turn and delegates to it (§3 Phase 5). Users
+* never see the supervisor object.
+*
+* @example
+* const supportBot = ai.orchestrator<SessionState>({
+*   name: "refund-support",
+*   intents: { classify, lookup, process, compose },
+*   route: (ctx) => (ctx.iteration === 0 ? "classify" : END),
+*   iterate: true,
+*   checkpointStore: ai.checkpoint.pg({ client: pg }),
+*   snapshotStore: ai.snapshot.pg({ client: pg }),
+* });
+*
+* const result = await supportBot.execute(message, { sessionId, history });
+*/
+function orchestrator(config) {
+	validateFactoryConfig(config);
+	const entries = resolveEntries(config);
+	assertInitialAgent(config, entries);
+	const signature = computeOrchestratorSignature(config, entries);
+	const emitter = new OrchestratorEmitter(config.on);
+	async function execute(input, options) {
+		return new OrchestratorExecution({
+			config,
+			entries,
+			signature,
+			emitter,
+			input,
+			options
+		}).run();
+	}
+	function stream(input, options) {
+		const { controller, stream: contract } = createOrchestratorStream();
+		new OrchestratorExecution({
+			config,
+			entries,
+			signature,
+			emitter,
+			input,
+			options,
+			streamController: controller
+		}).run();
+		return contract;
+	}
+	async function resume(sessionId, options) {
+		return new OrchestratorExecution({
+			config,
+			entries,
+			signature,
+			emitter,
+			resumeSessionId: sessionId,
+			resumeOptions: options
+		}).resume();
+	}
+	const command = createCommandDispatcher({ compact: (args) => {
+		return new OrchestratorExecution({
+			config,
+			entries,
+			signature,
+			emitter
+		}).compact(args);
+	} });
+	const instance = {
+		name: config.name,
+		signature,
+		version: config.version,
+		execute,
+		stream,
+		resume,
+		command,
+		asTool(options) {
+			return asTool(instance, options);
+		},
+		on(event, handler) {
+			return emitter.on(event, handler);
+		},
+		off(event, handler) {
+			emitter.off(event, handler);
+		}
+	};
+	return instance;
+}
+/**
+* Author-time validation (orchestrator.md §17). Enforces the rules that
+* must fail at construction rather than on the first turn:
+*
+* - `name` present and a string.
+* - `intents` present.
+* - `route` XOR `router` (mutually exclusive; at least one required) —
+*   the supervisor's dispatch-source rule, surfaced as an orchestrator
+*   config error.
+* - `router` is a valid agent contract or `{ agent, ... }` entry.
+* - `maxIterations >= 1` when set.
+* - `snapshotStore` resolvable when `iterate: true` — explicit field or
+*   the global `ai.config({ defaultSnapshotStore })` fallback.
+*
+* `initialAgent` membership is checked separately once the intent
+* entries are resolved.
+*/
+function validateFactoryConfig(config) {
+	if (!config.name || typeof config.name !== "string") throw new OrchestratorConfigError("ai.orchestrator: `name` is required and must be a string", { context: { authoring: true } });
+	if (!config.intents || typeof config.intents !== "object") throw new OrchestratorConfigError(`ai.orchestrator("${config.name}"): \`intents\` is required`, { context: { authoring: true } });
+	const hasRoute = typeof config.route === "function";
+	const hasRouter = Boolean(config.router);
+	if (hasRouter) {
+		const router = config.router;
+		const isBareAgent = typeof router.execute === "function";
+		const isEntryForm = !isBareAgent && typeof router.agent === "object" && typeof router.agent?.execute === "function";
+		if (!isBareAgent && !isEntryForm) throw new OrchestratorConfigError(`ai.orchestrator("${config.name}"): \`router\` must be an agent contract or a \`{ agent, placeholders?, input? }\` entry`, { context: { authoring: true } });
+	}
+	if (hasRoute && hasRouter) throw new OrchestratorConfigError(`ai.orchestrator("${config.name}"): \`route\` and \`router\` are mutually exclusive — configure exactly one`, { context: { authoring: true } });
+	if (!hasRoute && !hasRouter) throw new OrchestratorConfigError(`ai.orchestrator("${config.name}"): one of \`route\` or \`router\` is required`, { context: { authoring: true } });
+	if (config.maxIterations !== void 0 && config.maxIterations < 1) throw new OrchestratorConfigError(`ai.orchestrator("${config.name}"): \`maxIterations\` must be >= 1`, { context: {
+		authoring: true,
+		maxIterations: config.maxIterations
+	} });
+	if (config.iterate && !config.snapshotStore && !resolveDefaultSnapshotStore()) throw new OrchestratorConfigError(`ai.orchestrator("${config.name}"): \`iterate: true\` requires a \`snapshotStore\` (or \`ai.config({ defaultSnapshotStore })\`) for mid-turn resume`, { context: { authoring: true } });
+}
+/**
+* Resolve the `intents` map into the supervisor's internal entry shape,
+* re-wrapping the supervisor's authoring failure as an
+* {@link OrchestratorConfigError} so misuse surfaces under the
+* orchestrator's error family rather than the supervisor's.
+*/
+function resolveEntries(config) {
+	try {
+		return resolveIntentEntries(config.intents, config.name);
+	} catch (error) {
+		if (error instanceof SupervisorFailedError) throw new OrchestratorConfigError(error.message, {
+			context: { authoring: true },
+			cause: error
+		});
+		throw error;
+	}
+}
+/**
+* Enforce the `initialAgent` membership rule (§17) once entries are
+* resolved — `initialAgent`, when set, must name a key in `intents`.
+*/
+function assertInitialAgent(config, entries) {
+	if (config.initialAgent && !entries.has(config.initialAgent)) throw new OrchestratorConfigError(`ai.orchestrator("${config.name}"): \`initialAgent\` "${config.initialAgent}" is not a key in \`intents\``, { context: { authoring: true } });
+}
+
+//#endregion
+export { orchestrator };
+//# sourceMappingURL=orchestrator.mjs.map