@warlock.js/core 4.8.0 → 4.8.1

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

@@ -1 +0,0 @@
-{"version":3,"file":"load.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/load.ts"],"sourcesContent":["import type { CheckpointRecord } from \"../contracts/orchestrator/checkpoint-store.contract\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\n\n/**\n * Outcome of Phase 1 — load session (orchestrator.md §4 Phase 1).\n *\n * `record` is the latest persisted checkpoint, or `undefined` for a\n * brand-new session. `state` is the starting accumulator the turn\n * mutates: the rehydrated `state` on a subsequent call, or the\n * `config.state ?? {}` seed on first call (the framework never\n * re-seeds from `config.state` once a session exists — §4 Phase 1).\n * `turnIndex` is the index of the turn ABOUT to run (loaded + 1, or 0\n * on first call). `previousTurnIndex` is the loaded value (or -1 when\n * none) — needed by resume's `runId` derivation (§9.1).\n */\nexport type LoadedSession<TState> = {\n  /** Latest persisted checkpoint, or `undefined` for a new session. */\n  record: CheckpointRecord | undefined;\n  /** Whether a prior checkpoint existed (drives `session.loaded.found`). */\n  found: boolean;\n  /** Starting state accumulator for this turn. */\n  state: TState;\n  /** Index of the turn about to run. */\n  turnIndex: number;\n  /** Index of the last settled turn (-1 when the session is new). */\n  previousTurnIndex: number;\n};\n\n/**\n * Deep-clone a JSON-serializable value so a rehydrated checkpoint's\n * `state` can be mutated by the turn without aliasing the stored row\n * (the in-memory store hands back live references). Mirrors the\n * round-trip semantics the design mandates for state (§5 — \"JSON-\n * serializable only\", `JSON.parse(JSON.stringify(...))`-equivalent).\n */\nfunction cloneState<TState>(state: unknown): TState {\n  if (state === undefined || state === null) {\n    return {} as TState;\n  }\n\n  return JSON.parse(JSON.stringify(state)) as TState;\n}\n\n/**\n * Phase 1 — load session. Reads the latest checkpoint for the session\n * and resolves the starting state accumulator + the turn index about\n * to run.\n *\n * First-call seeding (Q2): when no checkpoint exists this is the\n * session's birth — `state` defaults to `config.state ?? {}` and\n * `turnIndex` is 0. Subsequent calls rehydrate the persisted `state`\n * and advance the turn index. The dev-passed `options.history` is the\n * per-call seed (Path 2 — the framework never persists messages), so\n * load does not touch history.\n *\n * Does NOT apply the per-call `state` patch — that shallow-merges over\n * this result in the dispatch phase (§5), where the supervisor seed is\n * assembled.\n */\nexport async function loadSession<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n): Promise<LoadedSession<TState>> {\n  const record = await ctx.checkpointStore.load(ctx.config.name, sessionId);\n\n  if (!record) {\n    return {\n      record: undefined,\n      found: false,\n      state: cloneState<TState>(ctx.config.state),\n      turnIndex: 0,\n      previousTurnIndex: -1,\n    };\n  }\n\n  return {\n    record,\n    found: true,\n    state: cloneState<TState>(record.state),\n    turnIndex: record.turn_index + 1,\n    previousTurnIndex: record.turn_index,\n  };\n}\n"],"mappings":";;;;;;;;AAmCA,SAAS,WAAmB,OAAwB;CAClD,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO,CAAC;CAGV,OAAO,KAAK,MAAM,KAAK,UAAU,KAAK,CAAC;AACzC;;;;;;;;;;;;;;;;;AAkBA,eAAsB,YACpB,KACA,WACgC;CAChC,MAAM,SAAS,MAAM,IAAI,gBAAgB,KAAK,IAAI,OAAO,MAAM,SAAS;CAExE,IAAI,CAAC,QACH,OAAO;EACL,QAAQ;EACR,OAAO;EACP,OAAO,WAAmB,IAAI,OAAO,KAAK;EAC1C,WAAW;EACX,mBAAmB;CACrB;CAGF,OAAO;EACL;EACA,OAAO;EACP,OAAO,WAAmB,OAAO,KAAK;EACtC,WAAW,OAAO,aAAa;EAC/B,mBAAmB,OAAO;CAC5B;AACF"}

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

@@ -1,75 +0,0 @@
-//#region ../@warlock.js/ai/src/orchestrator/lock.ts
-/** Framework default for the compaction-lock wait, in ms (§3 / §12.3). */
-const DEFAULT_LOCK_MAX_WAIT = 3e4;
-/** Poll interval while waiting on a held lock, in ms. */
-const LOCK_POLL_INTERVAL = 100;
-/**
-* Resolve the configured `summarize.lock.maxWait`, falling back to the
-* framework default. The callback form of `summarize` carries no lock
-* config, so it uses the default.
-*/
-function resolveMaxWait(ctx) {
-	const summarize = ctx.config.summarize;
-	if (typeof summarize === "function" || summarize === void 0) return DEFAULT_LOCK_MAX_WAIT;
-	return summarize.lock?.maxWait ?? 3e4;
-}
-/** Whether a checkpoint's lock is still held relative to `now`. */
-function isLocked(record, now) {
-	if (!record.lock_expires_at) return false;
-	const expiresAt = Date.parse(record.lock_expires_at);
-	return Number.isFinite(expiresAt) && expiresAt > now;
-}
-/**
-* Phase 3 — lock check (orchestrator.md §3 / §4 Phase 3). The loaded
-* checkpoint may carry a compaction lock written by a prior turn's
-* Phase 7 (or by `command("compact")`). When the lock is still live,
-* wait up to `summarize.lock.maxWait` (default 30s), re-loading the
-* latest checkpoint each poll, then **fail open** — proceed without
-* the lock.
-*
-* Emits `orchestrator.lock.waiting` once, only when a held lock is
-* observed (§14.1 — "only when locked"). The dispatch then runs
-* against whatever state was written before the lock was taken (§3).
-*
-* A new session (`loaded === undefined`) is never locked, so this
-* returns immediately.
-*/
-async function acquireLock(ctx, sessionId, loaded) {
-	if (!loaded || !isLocked(loaded, Date.now())) return {
-		waited: false,
-		waitedMs: 0,
-		failedOpen: false
-	};
-	const maxWait = resolveMaxWait(ctx);
-	const startedAt = Date.now();
-	ctx.emitter.emit("orchestrator.lock.waiting", {
-		sessionId,
-		waitedMs: 0
-	});
-	let latest = loaded;
-	while (latest && isLocked(latest, Date.now())) {
-		const waitedMs = Date.now() - startedAt;
-		if (waitedMs >= maxWait) return {
-			waited: true,
-			waitedMs,
-			failedOpen: true
-		};
-		await delay(Math.min(LOCK_POLL_INTERVAL, maxWait - waitedMs));
-		latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);
-	}
-	return {
-		waited: true,
-		waitedMs: Date.now() - startedAt,
-		failedOpen: false
-	};
-}
-/** Promise-based sleep used by the cooperative wait loop. */
-function delay(ms) {
-	return new Promise((resolve) => {
-		setTimeout(resolve, ms);
-	});
-}
-
-//#endregion
-export { DEFAULT_LOCK_MAX_WAIT, acquireLock };
-//# sourceMappingURL=lock.mjs.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"lock.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/lock.ts"],"sourcesContent":["import type { CheckpointRecord } from \"../contracts/orchestrator/checkpoint-store.contract\";\nimport type { SummarizeConfig } from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\n\n/** Framework default for the compaction-lock wait, in ms (§3 / §12.3). */\nexport const DEFAULT_LOCK_MAX_WAIT = 30_000;\n\n/** Poll interval while waiting on a held lock, in ms. */\nconst LOCK_POLL_INTERVAL = 100;\n\n/**\n * Resolve the configured `summarize.lock.maxWait`, falling back to the\n * framework default. The callback form of `summarize` carries no lock\n * config, so it uses the default.\n */\nfunction resolveMaxWait(ctx: OrchestratorEngineContext): number {\n  const summarize = ctx.config.summarize;\n\n  if (typeof summarize === \"function\" || summarize === undefined) {\n    return DEFAULT_LOCK_MAX_WAIT;\n  }\n\n  return (summarize as SummarizeConfig).lock?.maxWait ?? DEFAULT_LOCK_MAX_WAIT;\n}\n\n/** Whether a checkpoint's lock is still held relative to `now`. */\nfunction isLocked(record: CheckpointRecord, now: number): boolean {\n  if (!record.lock_expires_at) {\n    return false;\n  }\n\n  const expiresAt = Date.parse(record.lock_expires_at);\n\n  return Number.isFinite(expiresAt) && expiresAt > now;\n}\n\n/**\n * Outcome of Phase 3. `waited` is true when the turn observed a held\n * lock and spent time waiting; `waitedMs` is how long. `failedOpen` is\n * true when the wait timed out and the turn proceeds without the lock\n * (orchestrator.md §3 / §12.3 — a stuck summarizer must never block a\n * session forever).\n */\nexport type LockOutcome = {\n  waited: boolean;\n  waitedMs: number;\n  failedOpen: boolean;\n};\n\n/**\n * Phase 3 — lock check (orchestrator.md §3 / §4 Phase 3). The loaded\n * checkpoint may carry a compaction lock written by a prior turn's\n * Phase 7 (or by `command(\"compact\")`). When the lock is still live,\n * wait up to `summarize.lock.maxWait` (default 30s), re-loading the\n * latest checkpoint each poll, then **fail open** — proceed without\n * the lock.\n *\n * Emits `orchestrator.lock.waiting` once, only when a held lock is\n * observed (§14.1 — \"only when locked\"). The dispatch then runs\n * against whatever state was written before the lock was taken (§3).\n *\n * A new session (`loaded === undefined`) is never locked, so this\n * returns immediately.\n */\nexport async function acquireLock<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n  loaded: CheckpointRecord | undefined,\n): Promise<LockOutcome> {\n  if (!loaded || !isLocked(loaded, Date.now())) {\n    return { waited: false, waitedMs: 0, failedOpen: false };\n  }\n\n  const maxWait = resolveMaxWait(ctx as OrchestratorEngineContext);\n  const startedAt = Date.now();\n\n  ctx.emitter.emit(\"orchestrator.lock.waiting\", { sessionId, waitedMs: 0 });\n\n  let latest: CheckpointRecord | undefined = loaded;\n\n  while (latest && isLocked(latest, Date.now())) {\n    const waitedMs = Date.now() - startedAt;\n\n    if (waitedMs >= maxWait) {\n      return { waited: true, waitedMs, failedOpen: true };\n    }\n\n    await delay(Math.min(LOCK_POLL_INTERVAL, maxWait - waitedMs));\n\n    latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);\n  }\n\n  return { waited: true, waitedMs: Date.now() - startedAt, failedOpen: false };\n}\n\n/** Promise-based sleep used by the cooperative wait loop. */\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n"],"mappings":";;AAKA,MAAa,wBAAwB;;AAGrC,MAAM,qBAAqB;;;;;;AAO3B,SAAS,eAAe,KAAwC;CAC9D,MAAM,YAAY,IAAI,OAAO;CAE7B,IAAI,OAAO,cAAc,cAAc,cAAc,QACnD,OAAO;CAGT,OAAQ,UAA8B,MAAM;AAC9C;;AAGA,SAAS,SAAS,QAA0B,KAAsB;CAChE,IAAI,CAAC,OAAO,iBACV,OAAO;CAGT,MAAM,YAAY,KAAK,MAAM,OAAO,eAAe;CAEnD,OAAO,OAAO,SAAS,SAAS,KAAK,YAAY;AACnD;;;;;;;;;;;;;;;;AA8BA,eAAsB,YACpB,KACA,WACA,QACsB;CACtB,IAAI,CAAC,UAAU,CAAC,SAAS,QAAQ,KAAK,IAAI,CAAC,GACzC,OAAO;EAAE,QAAQ;EAAO,UAAU;EAAG,YAAY;CAAM;CAGzD,MAAM,UAAU,eAAe,GAAgC;CAC/D,MAAM,YAAY,KAAK,IAAI;CAE3B,IAAI,QAAQ,KAAK,6BAA6B;EAAE;EAAW,UAAU;CAAE,CAAC;CAExE,IAAI,SAAuC;CAE3C,OAAO,UAAU,SAAS,QAAQ,KAAK,IAAI,CAAC,GAAG;EAC7C,MAAM,WAAW,KAAK,IAAI,IAAI;EAE9B,IAAI,YAAY,SACd,OAAO;GAAE,QAAQ;GAAM;GAAU,YAAY;EAAK;EAGpD,MAAM,MAAM,KAAK,IAAI,oBAAoB,UAAU,QAAQ,CAAC;EAE5D,SAAS,MAAM,IAAI,gBAAgB,KAAK,IAAI,OAAO,MAAM,SAAS;CACpE;CAEA,OAAO;EAAE,QAAQ;EAAM,UAAU,KAAK,IAAI,IAAI;EAAW,YAAY;CAAM;AAC7E;;AAGA,SAAS,MAAM,IAA2B;CACxC,OAAO,IAAI,SAAS,YAAY;EAC9B,WAAW,SAAS,EAAE;CACxB,CAAC;AACH"}

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

@@ -1,141 +0,0 @@
-//#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

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

@@ -1,98 +0,0 @@
-//#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

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

@@ -1,206 +0,0 @@
-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

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