@warlock.js/core 4.4.0 → 4.5.0

package/esm/ai/src/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/ai/src/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/ai/src/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/ai/src/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/ai/src/orchestrator/orchestrator.mjs

@@ -0,0 +1,206 @@
+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 { inProcessSessionLock, noopSessionLock } from "./session-lock.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);
+	const sessionLock = resolveSessionLock(config);
+	warnOnUnlockedDurableStore(config);
+	async function execute(input, options) {
+		const execution = new OrchestratorExecution({
+			config,
+			entries,
+			signature,
+			emitter,
+			input,
+			options
+		});
+		return sessionLock.withLock(options.sessionId, () => execution.run(), { signal: options.signal });
+	}
+	function stream(input, options) {
+		const { controller, stream: contract } = createOrchestratorStream();
+		const execution = new OrchestratorExecution({
+			config,
+			entries,
+			signature,
+			emitter,
+			input,
+			options,
+			streamController: controller
+		});
+		sessionLock.withLock(options.sessionId, () => execution.run(), { signal: options.signal });
+		return contract;
+	}
+	async function resume(sessionId, options) {
+		const execution = new OrchestratorExecution({
+			config,
+			entries,
+			signature,
+			emitter,
+			resumeSessionId: sessionId,
+			resumeOptions: options
+		});
+		return sessionLock.withLock(sessionId, () => execution.resume(), { signal: options?.signal });
+	}
+	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 } });
+}
+/**
+* Resolve the per-session lock (C4): an explicit {@link SessionLock} when
+* supplied, a no-op when `sessionLock: false`, otherwise the framework
+* default in-process mutex.
+*/
+function resolveSessionLock(config) {
+	if (config.sessionLock === false) return noopSessionLock();
+	if (config.sessionLock) return config.sessionLock;
+	return inProcessSessionLock();
+}
+/** Orchestrator names already warned about an unlocked durable store. */
+const warnedUnlockedStores = /* @__PURE__ */ new Set();
+/**
+* Warn once when a durable `checkpointStore` is configured but no explicit
+* `sessionLock` was supplied (C4). The in-process default serializes
+* same-session turns within one process only — a horizontally-scaled
+* deployment needs a distributed lock or sticky routing. Suppressed in
+* tests and when the dev explicitly chose a lock (or `sessionLock: false`).
+*/
+function warnOnUnlockedDurableStore(config) {
+	if (config.sessionLock !== void 0) return;
+	if (!config.checkpointStore) return;
+	if (process.env.NODE_ENV === "test" || process.env.VITEST) return;
+	if (warnedUnlockedStores.has(config.name)) return;
+	warnedUnlockedStores.add(config.name);
+	console.warn(`[warlock-ai] orchestrator "${config.name}" uses a durable checkpointStore with the default in-process sessionLock. That serializes same-session turns within ONE process only; in a horizontally-scaled deployment supply a distributed \`sessionLock\` (Redis/Postgres advisory locks) or use sticky routing. Pass \`sessionLock: false\` to silence this.`);
+}
+
+//#endregion
+export { orchestrator };
+//# sourceMappingURL=orchestrator.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.mjs","names":["orchestratorAsTool"],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/orchestrator.ts"],"sourcesContent":["import type { OrchestratorConfig } from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type {\n  OrchestratorEventHandler,\n  OrchestratorEventName,\n} from \"../contracts/orchestrator/orchestrator-event.type\";\nimport type {\n  OrchestratorAsToolOptions,\n  OrchestratorContract,\n} from \"../contracts/orchestrator/orchestrator.contract\";\nimport type { OrchestratorCommands } from \"../contracts/orchestrator/orchestrator-commands.type\";\nimport type {\n  OrchestratorExecuteOptions,\n  OrchestratorResumeOptions,\n} from \"../contracts/orchestrator/orchestrator-execute-options.type\";\nimport type { OrchestratorEvent } from \"../contracts/orchestrator/orchestrator-event.type\";\nimport type { OrchestratorResult } from \"../contracts/result/orchestrator-result.type\";\nimport type { StreamContract } from \"../contracts/stream/stream.contract\";\nimport type { SupervisorIntentValue } from \"../contracts/supervisor/intent-entry.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport { resolveDefaultSnapshotStore } from \"../config\";\nimport { OrchestratorConfigError } from \"../errors/orchestrator-config-error\";\nimport { resolveIntentEntries, type ResolvedIntentEntry } from \"../supervisor/entries\";\nimport { SupervisorFailedError } from \"../errors\";\nimport type { ToolContract } from \"../tool/tool\";\nimport type { SessionLock } from \"../contracts/orchestrator/session-lock.contract\";\nimport { asTool as orchestratorAsTool } from \"./as-tool\";\nimport { createCommandDispatcher } from \"./commands\";\nimport { OrchestratorEmitter } from \"./emitter\";\nimport { OrchestratorExecution } from \"./execution\";\nimport { createOrchestratorStream } from \"./orchestrator-stream\";\nimport { inProcessSessionLock, noopSessionLock } from \"./session-lock\";\nimport { computeOrchestratorSignature } from \"./signature\";\n\n/**\n * `ai.orchestrator(config)` — construct an {@link OrchestratorContract}:\n * a session-state manager wrapped around a supervisor (orchestrator.md\n * §1, §15). Validates the config at author time (throws\n * {@link OrchestratorConfigError} on bad shape), resolves the intent\n * entries, computes a stable structural signature for drift detection\n * (§10.1), wires the three-tier event emitter, and returns a handle that\n * runs one durable session turn per `execute` / `stream` call, resumes\n * an interrupted `iterate: true` turn via `resume`, and exposes typed\n * built-in commands plus an `asTool` wrapper.\n *\n * The \"what runs\" fields (`intents`, `route` / `router`, `evaluate`,\n * `state`, `output`, `initialAgent`, `maxIterations`) are the\n * supervisor's surface spread directly — the lifecycle builds the\n * supervisor lazily per turn and delegates to it (§3 Phase 5). Users\n * never see the supervisor object.\n *\n * @example\n * const supportBot = ai.orchestrator<SessionState>({\n *   name: \"refund-support\",\n *   intents: { classify, lookup, process, compose },\n *   route: (ctx) => (ctx.iteration === 0 ? \"classify\" : END),\n *   iterate: true,\n *   checkpointStore: ai.checkpoint.pg({ client: pg }),\n *   snapshotStore: ai.snapshot.pg({ client: pg }),\n * });\n *\n * const result = await supportBot.execute(message, { sessionId, history });\n */\nexport function orchestrator<\n  TOutput = unknown,\n  TState = TOutput,\n  TIntents extends Record<string, SupervisorIntentValue> = Record<\n    string,\n    SupervisorIntentValue\n  >,\n>(\n  config: OrchestratorConfig<TOutput, TState, TIntents>,\n): OrchestratorContract<TOutput, TState> {\n  validateFactoryConfig(config as unknown as OrchestratorConfig<unknown>);\n\n  const entries = resolveEntries(config as unknown as OrchestratorConfig<unknown>);\n\n  assertInitialAgent(config as unknown as OrchestratorConfig<unknown>, entries);\n\n  const signature = computeOrchestratorSignature(\n    config as unknown as OrchestratorConfig<unknown>,\n    entries,\n  );\n  const emitter = new OrchestratorEmitter(config.on);\n\n  // Per-session turn serialization (C4). Resolved ONCE so every turn on\n  // this orchestrator shares the same lock — that's what lets the\n  // in-process default actually serialize concurrent same-session calls.\n  const sessionLock = resolveSessionLock(config as unknown as OrchestratorConfig<unknown>);\n  warnOnUnlockedDurableStore(config as unknown as OrchestratorConfig<unknown>);\n\n  async function execute(\n    input: SupervisorInput,\n    options: OrchestratorExecuteOptions<TState>,\n  ): Promise<OrchestratorResult<TOutput>> {\n    const execution = new OrchestratorExecution<TOutput, TState>({\n      config: config as unknown as OrchestratorConfig<TOutput, TState>,\n      entries,\n      signature,\n      emitter,\n      input,\n      options,\n    });\n\n    // Serialize the whole turn (load → dispatch → persist) against any\n    // concurrent turn for the same session, so the checkpoint's\n    // read-modify-write can't lose an update.\n    return sessionLock.withLock(options.sessionId, () => execution.run(), {\n      signal: options.signal,\n    });\n  }\n\n  function stream(\n    input: SupervisorInput,\n    options: OrchestratorExecuteOptions<TState>,\n  ): StreamContract<OrchestratorResult<TOutput>, OrchestratorEvent> {\n    const { controller, stream: contract } = createOrchestratorStream<\n      OrchestratorResult<TOutput>\n    >();\n\n    const execution = new OrchestratorExecution<TOutput, TState>({\n      config: config as unknown as OrchestratorConfig<TOutput, TState>,\n      entries,\n      signature,\n      emitter,\n      input,\n      options,\n      streamController: controller,\n    });\n\n    // The background run waits for the session lock before it starts —\n    // same serialization guarantee as `execute`; the stream contract is\n    // still returned synchronously.\n    void sessionLock.withLock(options.sessionId, () => execution.run(), {\n      signal: options.signal,\n    });\n\n    return contract;\n  }\n\n  async function resume(\n    sessionId: string,\n    options?: OrchestratorResumeOptions,\n  ): Promise<OrchestratorResult<TOutput> | null> {\n    const execution = new OrchestratorExecution<TOutput, TState>({\n      config: config as unknown as OrchestratorConfig<TOutput, TState>,\n      entries,\n      signature,\n      emitter,\n      resumeSessionId: sessionId,\n      resumeOptions: options,\n    });\n\n    return sessionLock.withLock(sessionId, () => execution.resume(), {\n      signal: options?.signal,\n    });\n  }\n\n  // The dispatcher owns command ROUTING only; the `compact` handler\n  // delegates to the shared compaction code path on the lifecycle engine\n  // (§11 / §12.2 — manual compact reuses the post-turn compaction path).\n  const command = createCommandDispatcher({\n    compact: (args: OrchestratorCommands[\"compact\"][\"args\"]) => {\n      const execution = new OrchestratorExecution<TOutput, TState>({\n        config: config as unknown as OrchestratorConfig<TOutput, TState>,\n        entries,\n        signature,\n        emitter,\n      });\n\n      return execution.compact(args);\n    },\n  });\n\n  const instance: OrchestratorContract<TOutput, TState> = {\n    name: config.name,\n    signature,\n    version: config.version,\n    execute,\n    stream,\n    resume,\n    command,\n    asTool<TToolInput = string>(\n      options: OrchestratorAsToolOptions<TToolInput>,\n    ): ToolContract<TToolInput, TOutput> {\n      return orchestratorAsTool<TOutput, TState, TToolInput>(instance, options);\n    },\n    on<K extends OrchestratorEventName>(\n      event: K,\n      handler: OrchestratorEventHandler<K>,\n    ): () => void {\n      return emitter.on(event, handler);\n    },\n    off<K extends OrchestratorEventName>(\n      event: K,\n      handler: OrchestratorEventHandler<K>,\n    ): void {\n      emitter.off(event, handler);\n    },\n  };\n\n  return instance;\n}\n\n/**\n * Author-time validation (orchestrator.md §17). Enforces the rules that\n * must fail at construction rather than on the first turn:\n *\n * - `name` present and a string.\n * - `intents` present.\n * - `route` XOR `router` (mutually exclusive; at least one required) —\n *   the supervisor's dispatch-source rule, surfaced as an orchestrator\n *   config error.\n * - `router` is a valid agent contract or `{ agent, ... }` entry.\n * - `maxIterations >= 1` when set.\n * - `snapshotStore` resolvable when `iterate: true` — explicit field or\n *   the global `ai.config({ defaultSnapshotStore })` fallback.\n *\n * `initialAgent` membership is checked separately once the intent\n * entries are resolved.\n */\nfunction validateFactoryConfig(config: OrchestratorConfig<unknown>): void {\n  if (!config.name || typeof config.name !== \"string\") {\n    throw new OrchestratorConfigError(\n      \"ai.orchestrator: `name` is required and must be a string\",\n      { context: { authoring: true } },\n    );\n  }\n\n  if (!config.intents || typeof config.intents !== \"object\") {\n    throw new OrchestratorConfigError(\n      `ai.orchestrator(\"${config.name}\"): \\`intents\\` is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  const hasRoute = typeof config.route === \"function\";\n  const hasRouter = Boolean(config.router);\n\n  if (hasRouter) {\n    const router = config.router;\n    const isBareAgent = typeof (router as { execute?: unknown }).execute === \"function\";\n    const isEntryForm =\n      !isBareAgent &&\n      typeof (router as { agent?: { execute?: unknown } }).agent === \"object\" &&\n      typeof (router as { agent?: { execute?: unknown } }).agent?.execute === \"function\";\n\n    if (!isBareAgent && !isEntryForm) {\n      throw new OrchestratorConfigError(\n        `ai.orchestrator(\"${config.name}\"): \\`router\\` must be an agent contract or a \\`{ agent, placeholders?, input? }\\` entry`,\n        { context: { authoring: true } },\n      );\n    }\n  }\n\n  if (hasRoute && hasRouter) {\n    throw new OrchestratorConfigError(\n      `ai.orchestrator(\"${config.name}\"): \\`route\\` and \\`router\\` are mutually exclusive — configure exactly one`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (!hasRoute && !hasRouter) {\n    throw new OrchestratorConfigError(\n      `ai.orchestrator(\"${config.name}\"): one of \\`route\\` or \\`router\\` is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (config.maxIterations !== undefined && config.maxIterations < 1) {\n    throw new OrchestratorConfigError(\n      `ai.orchestrator(\"${config.name}\"): \\`maxIterations\\` must be >= 1`,\n      { context: { authoring: true, maxIterations: config.maxIterations } },\n    );\n  }\n\n  if (config.iterate && !config.snapshotStore && !resolveDefaultSnapshotStore()) {\n    throw new OrchestratorConfigError(\n      `ai.orchestrator(\"${config.name}\"): \\`iterate: true\\` requires a \\`snapshotStore\\` (or \\`ai.config({ defaultSnapshotStore })\\`) for mid-turn resume`,\n      { context: { authoring: true } },\n    );\n  }\n}\n\n/**\n * Resolve the `intents` map into the supervisor's internal entry shape,\n * re-wrapping the supervisor's authoring failure as an\n * {@link OrchestratorConfigError} so misuse surfaces under the\n * orchestrator's error family rather than the supervisor's.\n */\nfunction resolveEntries(\n  config: OrchestratorConfig<unknown>,\n): Map<string, ResolvedIntentEntry> {\n  try {\n    return resolveIntentEntries(config.intents, config.name);\n  } catch (error) {\n    if (error instanceof SupervisorFailedError) {\n      throw new OrchestratorConfigError(error.message, {\n        context: { authoring: true },\n        cause: error,\n      });\n    }\n\n    throw error;\n  }\n}\n\n/**\n * Enforce the `initialAgent` membership rule (§17) once entries are\n * resolved — `initialAgent`, when set, must name a key in `intents`.\n */\nfunction assertInitialAgent(\n  config: OrchestratorConfig<unknown>,\n  entries: Map<string, ResolvedIntentEntry>,\n): void {\n  if (config.initialAgent && !entries.has(config.initialAgent)) {\n    throw new OrchestratorConfigError(\n      `ai.orchestrator(\"${config.name}\"): \\`initialAgent\\` \"${config.initialAgent}\" is not a key in \\`intents\\``,\n      { context: { authoring: true } },\n    );\n  }\n}\n\n/**\n * Resolve the per-session lock (C4): an explicit {@link SessionLock} when\n * supplied, a no-op when `sessionLock: false`, otherwise the framework\n * default in-process mutex.\n */\nfunction resolveSessionLock(config: OrchestratorConfig<unknown>): SessionLock {\n  if (config.sessionLock === false) return noopSessionLock();\n  if (config.sessionLock) return config.sessionLock;\n  return inProcessSessionLock();\n}\n\n/** Orchestrator names already warned about an unlocked durable store. */\nconst warnedUnlockedStores = new Set<string>();\n\n/**\n * Warn once when a durable `checkpointStore` is configured but no explicit\n * `sessionLock` was supplied (C4). The in-process default serializes\n * same-session turns within one process only — a horizontally-scaled\n * deployment needs a distributed lock or sticky routing. Suppressed in\n * tests and when the dev explicitly chose a lock (or `sessionLock: false`).\n */\nfunction warnOnUnlockedDurableStore(config: OrchestratorConfig<unknown>): void {\n  if (config.sessionLock !== undefined) return;\n  if (!config.checkpointStore) return;\n  if (process.env.NODE_ENV === \"test\" || process.env.VITEST) return;\n  if (warnedUnlockedStores.has(config.name)) return;\n  warnedUnlockedStores.add(config.name);\n\n  console.warn(\n    `[warlock-ai] orchestrator \"${config.name}\" uses a durable checkpointStore with the default in-process sessionLock. ` +\n      \"That serializes same-session turns within ONE process only; in a horizontally-scaled deployment supply a distributed \" +\n      \"`sessionLock` (Redis/Postgres advisory locks) or use sticky routing. Pass `sessionLock: false` to silence this.\",\n  );\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,74 @@
+import { summarizeRoute } from "./checkpoint.mjs";
+import { deriveRunId, dispatchTurn } from "./dispatch.mjs";
+import { loadSession } from "./load.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/resume.ts
+/**
+* §9 resume protocol. Detects and drains an interrupted `iterate: true`
+* turn:
+*
+* 1. Load the latest checkpoint (§9.1 step 1).
+* 2. Compute the candidate `runId` for the NEXT turn — the one that was
+*    in flight — `${sessionId}.${version}.${turn_index + 1}` (§9.1 step 2).
+* 3. Load the supervisor snapshot for that runId (§9.1 step 3).
+* 4. If a still-`running` snapshot exists, resume the supervisor, persist
+*    a fresh checkpoint for `turn_index + 1`, and return the result
+*    (§9.1 step 4).
+* 5. Otherwise return `null` — nothing in flight; the caller proceeds to
+*    `execute()` normally (§9.1 step 5, §9.3 drain idempotency).
+*
+* Runs the same Phase 2 drift check as `execute()` (§9.4). Resume is a
+* no-op for `iterate: false` orchestrators (no SnapshotStore, nothing to
+* resume) — it returns `null`.
+*/
+async function resolveResume(ctx, sessionId, options, hooks) {
+	if (!ctx.snapshotStore || ctx.config.iterate !== true) return null;
+	const loaded = await loadSession(ctx, sessionId);
+	hooks.assertNoDrift(loaded.record?.signature);
+	const resumedTurnIndex = (loaded.record?.turn_index ?? -1) + 1;
+	const runId = deriveRunId(sessionId, ctx.config.version, resumedTurnIndex);
+	const snapshot = await ctx.snapshotStore.load(runId);
+	if (!snapshot || snapshot.status !== "running") return null;
+	ctx.emitter.emit("orchestrator.turn.starting", {
+		sessionId,
+		turnIndex: resumedTurnIndex
+	});
+	const { result, state, turnSnapshot } = await dispatchTurn({
+		ctx,
+		sessionId,
+		input: snapshot.input,
+		seedState: loaded.state,
+		turnIndex: resumedTurnIndex,
+		history: [],
+		context: options?.context,
+		signal: options?.signal
+	});
+	const status = result.error ? hooks.deriveStatus(result.report.status) : "awaiting-input";
+	if (result.error) {
+		const report = hooks.buildReport(resumedTurnIndex, status, turnSnapshot, result.report);
+		hooks.emitTerminal(resumedTurnIndex, status);
+		return {
+			data: result.data,
+			error: result.error,
+			usage: result.usage,
+			report,
+			sessionId,
+			turnIndex: resumedTurnIndex
+		};
+	}
+	await hooks.persist(resumedTurnIndex, state, summarizeRoute(turnSnapshot.decision.raw), loaded.record?.summarized_through ?? null);
+	const report = hooks.buildReport(resumedTurnIndex, "awaiting-input", turnSnapshot, result.report);
+	hooks.emitTerminal(resumedTurnIndex, "awaiting-input");
+	return {
+		data: result.data,
+		error: void 0,
+		usage: result.usage,
+		report,
+		sessionId,
+		turnIndex: resumedTurnIndex
+	};
+}
+
+//#endregion
+export { resolveResume };
+//# sourceMappingURL=resume.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resume.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/resume.ts"],"sourcesContent":["import type { OrchestratorResumeOptions } from \"../contracts/orchestrator/orchestrator-execute-options.type\";\nimport type {\n  OrchestratorReport,\n  OrchestratorReportStatus,\n  OrchestratorResult,\n  TurnSnapshot,\n} from \"../contracts/result/orchestrator-result.type\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { summarizeRoute } from \"./checkpoint\";\nimport { deriveRunId, dispatchTurn } from \"./dispatch\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\nimport { loadSession } from \"./load\";\n\n/**\n * Hooks the resume protocol borrows from the execution module so it can\n * reuse the drift check, report assembly, status mapping, terminal\n * event emission, and checkpoint persistence without a circular import\n * (execution.ts owns those; resume.ts is called by it).\n */\nexport type ResumeHooks = {\n  assertNoDrift(loadedSignature: string | undefined): void;\n  buildReport(\n    turnIndex: number,\n    status: OrchestratorReportStatus,\n    turnSnapshot: TurnSnapshot | undefined,\n    childReport: BaseReport | undefined,\n  ): OrchestratorReport;\n  deriveStatus(childStatus: BaseReport[\"status\"]): OrchestratorReportStatus;\n  emitTerminal(turnIndex: number, status: OrchestratorReportStatus): void;\n  persist(\n    turnIndex: number,\n    state: unknown,\n    lastRoute: string | string[] | null,\n    summarizedThrough: number | null,\n  ): Promise<unknown>;\n};\n\n/**\n * §9 resume protocol. Detects and drains an interrupted `iterate: true`\n * turn:\n *\n * 1. Load the latest checkpoint (§9.1 step 1).\n * 2. Compute the candidate `runId` for the NEXT turn — the one that was\n *    in flight — `${sessionId}.${version}.${turn_index + 1}` (§9.1 step 2).\n * 3. Load the supervisor snapshot for that runId (§9.1 step 3).\n * 4. If a still-`running` snapshot exists, resume the supervisor, persist\n *    a fresh checkpoint for `turn_index + 1`, and return the result\n *    (§9.1 step 4).\n * 5. Otherwise return `null` — nothing in flight; the caller proceeds to\n *    `execute()` normally (§9.1 step 5, §9.3 drain idempotency).\n *\n * Runs the same Phase 2 drift check as `execute()` (§9.4). Resume is a\n * no-op for `iterate: false` orchestrators (no SnapshotStore, nothing to\n * resume) — it returns `null`.\n */\nexport async function resolveResume<TOutput, TState>(\n  ctx: OrchestratorEngineContext<TOutput, TState>,\n  sessionId: string,\n  options: OrchestratorResumeOptions | undefined,\n  hooks: ResumeHooks,\n): Promise<OrchestratorResult<TOutput> | null> {\n  if (!ctx.snapshotStore || ctx.config.iterate !== true) {\n    return null;\n  }\n\n  const loaded = await loadSession(ctx, sessionId);\n\n  // Drift guard — same as execute() (§9.4).\n  hooks.assertNoDrift(loaded.record?.signature);\n\n  // The in-flight turn is the one AFTER the last settled checkpoint.\n  const resumedTurnIndex = (loaded.record?.turn_index ?? -1) + 1;\n  const runId = deriveRunId(sessionId, ctx.config.version, resumedTurnIndex);\n\n  const snapshot = await ctx.snapshotStore.load(runId);\n\n  if (!snapshot || snapshot.status !== \"running\") {\n    return null;\n  }\n\n  ctx.emitter.emit(\"orchestrator.turn.starting\", {\n    sessionId,\n    turnIndex: resumedTurnIndex,\n  });\n\n  // Re-dispatch: dispatchTurn detects the in-flight snapshot for this\n  // runId and calls supervisor.resume() rather than execute() (§5 step 5).\n  const { result, state, turnSnapshot } = await dispatchTurn<TOutput, TState>({\n    ctx,\n    sessionId,\n    input: snapshot.input,\n    seedState: loaded.state,\n    turnIndex: resumedTurnIndex,\n    history: [],\n    context: options?.context,\n    signal: options?.signal,\n  });\n\n  const status = result.error\n    ? hooks.deriveStatus(result.report.status)\n    : \"awaiting-input\";\n\n  if (result.error) {\n    const report = hooks.buildReport(\n      resumedTurnIndex,\n      status,\n      turnSnapshot,\n      result.report,\n    );\n\n    hooks.emitTerminal(resumedTurnIndex, status);\n\n    return {\n      data: result.data,\n      error: result.error,\n      usage: result.usage,\n      report,\n      sessionId,\n      turnIndex: resumedTurnIndex,\n    };\n  }\n\n  // Finalize: persist a fresh checkpoint for the resumed turn (§9.1 step 4).\n  await hooks.persist(\n    resumedTurnIndex,\n    state,\n    summarizeRoute(turnSnapshot.decision.raw as never),\n    loaded.record?.summarized_through ?? null,\n  );\n\n  const report = hooks.buildReport(\n    resumedTurnIndex,\n    \"awaiting-input\",\n    turnSnapshot,\n    result.report,\n  );\n\n  hooks.emitTerminal(resumedTurnIndex, \"awaiting-input\");\n\n  return {\n    data: result.data,\n    error: undefined,\n    usage: result.usage,\n    report,\n    sessionId,\n    turnIndex: resumedTurnIndex,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuDA,eAAsB,cACpB,KACA,WACA,SACA,OAC6C;CAC7C,IAAI,CAAC,IAAI,iBAAiB,IAAI,OAAO,YAAY,MAC/C,OAAO;CAGT,MAAM,SAAS,MAAM,YAAY,KAAK,SAAS;CAG/C,MAAM,cAAc,OAAO,QAAQ,SAAS;CAG5C,MAAM,oBAAoB,OAAO,QAAQ,cAAc,MAAM;CAC7D,MAAM,QAAQ,YAAY,WAAW,IAAI,OAAO,SAAS,gBAAgB;CAEzE,MAAM,WAAW,MAAM,IAAI,cAAc,KAAK,KAAK;CAEnD,IAAI,CAAC,YAAY,SAAS,WAAW,WACnC,OAAO;CAGT,IAAI,QAAQ,KAAK,8BAA8B;EAC7C;EACA,WAAW;CACb,CAAC;CAID,MAAM,EAAE,QAAQ,OAAO,iBAAiB,MAAM,aAA8B;EAC1E;EACA;EACA,OAAO,SAAS;EAChB,WAAW,OAAO;EAClB,WAAW;EACX,SAAS,CAAC;EACV,SAAS,SAAS;EAClB,QAAQ,SAAS;CACnB,CAAC;CAED,MAAM,SAAS,OAAO,QAClB,MAAM,aAAa,OAAO,OAAO,MAAM,IACvC;CAEJ,IAAI,OAAO,OAAO;EAChB,MAAM,SAAS,MAAM,YACnB,kBACA,QACA,cACA,OAAO,MACT;EAEA,MAAM,aAAa,kBAAkB,MAAM;EAE3C,OAAO;GACL,MAAM,OAAO;GACb,OAAO,OAAO;GACd,OAAO,OAAO;GACd;GACA;GACA,WAAW;EACb;CACF;CAGA,MAAM,MAAM,QACV,kBACA,OACA,eAAe,aAAa,SAAS,GAAY,GACjD,OAAO,QAAQ,sBAAsB,IACvC;CAEA,MAAM,SAAS,MAAM,YACnB,kBACA,kBACA,cACA,OAAO,MACT;CAEA,MAAM,aAAa,kBAAkB,gBAAgB;CAErD,OAAO;EACL,MAAM,OAAO;EACb,OAAO;EACP,OAAO,OAAO;EACd;EACA;EACA,WAAW;CACb;AACF"}