@warlock.js/core 4.3.0 → 4.5.0

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

@@ -0,0 +1,83 @@
+//#region ../@warlock.js/ai/src/orchestrator/session-lock.ts
+/**
+* Reason an aborted lock-wait rejects with — the signal's `reason` when
+* one was supplied to `controller.abort(reason)`, else a generic error.
+*/
+function abortReason(signal) {
+	return signal.reason ?? /* @__PURE__ */ new Error("session lock wait aborted");
+}
+/**
+* Framework-default in-process {@link SessionLock} — a per-key promise-
+* chain mutex. It holds one tail promise per session key; each acquirer
+* waits on the previous holder's release, then installs its own tail.
+* Keyed by `sessionId`, so different sessions never contend. The wait is
+* abortable, so a cancelled caller never deadlocks behind a stuck
+* predecessor (the deadlock-on-cancel trap).
+*
+* In-process only: serializes same-session turns within ONE process.
+* Supply a distributed {@link SessionLock} for multi-process deployments.
+*/
+function inProcessSessionLock() {
+	const tails = /* @__PURE__ */ new Map();
+	return { async withLock(key, fn, options) {
+		const existing = tails.get(key);
+		const prev = existing ?? Promise.resolve();
+		const waitSignal = existing ? options?.signal : void 0;
+		let release;
+		const held = new Promise((resolve) => {
+			release = resolve;
+		});
+		const mine = prev.then(() => held, () => held);
+		tails.set(key, mine);
+		const cleanup = () => {
+			if (tails.get(key) === mine) tails.delete(key);
+		};
+		try {
+			await waitForTurn(prev, waitSignal);
+		} catch (error) {
+			release();
+			cleanup();
+			throw error;
+		}
+		try {
+			return await fn();
+		} finally {
+			release();
+			cleanup();
+		}
+	} };
+}
+/**
+* Wait for `prev` (the previous holder's release) to settle, racing it
+* against `signal` so a cancelled caller stops waiting instead of
+* deadlocking. Predecessor rejections are swallowed — a failed turn still
+* releases the lock to the next waiter.
+*/
+function waitForTurn(prev, signal) {
+	const settled = prev.then(() => {}, () => {});
+	if (!signal) return settled;
+	if (signal.aborted) return Promise.reject(abortReason(signal));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(abortReason(signal));
+		signal.addEventListener("abort", onAbort, { once: true });
+		settled.then(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		});
+	});
+}
+/**
+* No-op {@link SessionLock} for `sessionLock: false` — runs `fn` with no
+* serialization at all. Opt out only when an external mechanism (sticky
+* routing, a single-writer guarantee) already serializes same-session
+* turns.
+*/
+function noopSessionLock() {
+	return { withLock(_key, fn) {
+		return fn();
+	} };
+}
+
+//#endregion
+export { inProcessSessionLock, noopSessionLock };
+//# sourceMappingURL=session-lock.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-lock.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/session-lock.ts"],"sourcesContent":["import type { SessionLock } from \"../contracts/orchestrator/session-lock.contract\";\n\n/**\n * Reason an aborted lock-wait rejects with — the signal's `reason` when\n * one was supplied to `controller.abort(reason)`, else a generic error.\n */\nfunction abortReason(signal: AbortSignal): unknown {\n  return signal.reason ?? new Error(\"session lock wait aborted\");\n}\n\n/**\n * Framework-default in-process {@link SessionLock} — a per-key promise-\n * chain mutex. It holds one tail promise per session key; each acquirer\n * waits on the previous holder's release, then installs its own tail.\n * Keyed by `sessionId`, so different sessions never contend. The wait is\n * abortable, so a cancelled caller never deadlocks behind a stuck\n * predecessor (the deadlock-on-cancel trap).\n *\n * In-process only: serializes same-session turns within ONE process.\n * Supply a distributed {@link SessionLock} for multi-process deployments.\n */\nexport function inProcessSessionLock(): SessionLock {\n  const tails = new Map<string, Promise<void>>();\n\n  return {\n    async withLock<T>(\n      key: string,\n      fn: () => Promise<T>,\n      options?: { signal?: AbortSignal },\n    ): Promise<T> {\n      const existing = tails.get(key);\n      const prev = existing ?? Promise.resolve();\n\n      // The caller's signal aborts a genuine WAIT only. When the lock is\n      // free (no existing tail) we acquire immediately and let `fn` own\n      // cancellation — so a pre-aborted signal never pre-empts graceful\n      // in-flight handling (e.g. the orchestrator emitting turn.cancelled).\n      const waitSignal = existing ? options?.signal : undefined;\n\n      let release!: () => void;\n      const held = new Promise<void>(resolve => {\n        release = resolve;\n      });\n\n      // Successors queue behind OUR release. A predecessor that rejects\n      // still lets us through (both branches resolve to `held`), so a\n      // single failed turn never wedges the whole session.\n      const mine = prev.then(\n        () => held,\n        () => held,\n      );\n      tails.set(key, mine);\n\n      const cleanup = () => {\n        // Drop the map entry once we're the tail, so idle sessions don't\n        // leak Promise references.\n        if (tails.get(key) === mine) {\n          tails.delete(key);\n        }\n      };\n\n      try {\n        await waitForTurn(prev, waitSignal);\n      } catch (error) {\n        // Never acquired the critical section — release immediately so\n        // successors aren't blocked by an aborted waiter, then surface\n        // the abort to the caller.\n        release();\n        cleanup();\n        throw error;\n      }\n\n      try {\n        return await fn();\n      } finally {\n        release();\n        cleanup();\n      }\n    },\n  };\n}\n\n/**\n * Wait for `prev` (the previous holder's release) to settle, racing it\n * against `signal` so a cancelled caller stops waiting instead of\n * deadlocking. Predecessor rejections are swallowed — a failed turn still\n * releases the lock to the next waiter.\n */\nfunction waitForTurn(prev: Promise<void>, signal?: AbortSignal): Promise<void> {\n  const settled = prev.then(\n    () => {},\n    () => {},\n  );\n\n  if (!signal) return settled;\n  if (signal.aborted) return Promise.reject(abortReason(signal));\n\n  return new Promise<void>((resolve, reject) => {\n    const onAbort = () => reject(abortReason(signal));\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n    void settled.then(() => {\n      signal.removeEventListener(\"abort\", onAbort);\n      resolve();\n    });\n  });\n}\n\n/**\n * No-op {@link SessionLock} for `sessionLock: false` — runs `fn` with no\n * serialization at all. Opt out only when an external mechanism (sticky\n * routing, a single-writer guarantee) already serializes same-session\n * turns.\n */\nexport function noopSessionLock(): SessionLock {\n  return {\n    withLock<T>(_key: string, fn: () => Promise<T>): Promise<T> {\n      return fn();\n    },\n  };\n}\n"],"mappings":";;;;;AAMA,SAAS,YAAY,QAA8B;CACjD,OAAO,OAAO,0BAAU,IAAI,MAAM,2BAA2B;AAC/D;;;;;;;;;;;;AAaA,SAAgB,uBAAoC;CAClD,MAAM,wBAAQ,IAAI,IAA2B;CAE7C,OAAO,EACL,MAAM,SACJ,KACA,IACA,SACY;EACZ,MAAM,WAAW,MAAM,IAAI,GAAG;EAC9B,MAAM,OAAO,YAAY,QAAQ,QAAQ;EAMzC,MAAM,aAAa,WAAW,SAAS,SAAS;EAEhD,IAAI;EACJ,MAAM,OAAO,IAAI,SAAc,YAAW;GACxC,UAAU;EACZ,CAAC;EAKD,MAAM,OAAO,KAAK,WACV,YACA,IACR;EACA,MAAM,IAAI,KAAK,IAAI;EAEnB,MAAM,gBAAgB;GAGpB,IAAI,MAAM,IAAI,GAAG,MAAM,MACrB,MAAM,OAAO,GAAG;EAEpB;EAEA,IAAI;GACF,MAAM,YAAY,MAAM,UAAU;EACpC,SAAS,OAAO;GAId,QAAQ;GACR,QAAQ;GACR,MAAM;EACR;EAEA,IAAI;GACF,OAAO,MAAM,GAAG;EAClB,UAAU;GACR,QAAQ;GACR,QAAQ;EACV;CACF,EACF;AACF;;;;;;;AAQA,SAAS,YAAY,MAAqB,QAAqC;CAC7E,MAAM,UAAU,KAAK,WACb,CAAC,SACD,CAAC,CACT;CAEA,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI,OAAO,SAAS,OAAO,QAAQ,OAAO,YAAY,MAAM,CAAC;CAE7D,OAAO,IAAI,SAAe,SAAS,WAAW;EAC5C,MAAM,gBAAgB,OAAO,YAAY,MAAM,CAAC;EAChD,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACxD,AAAK,QAAQ,WAAW;GACtB,OAAO,oBAAoB,SAAS,OAAO;GAC3C,QAAQ;EACV,CAAC;CACH,CAAC;AACH;;;;;;;AAQA,SAAgB,kBAA+B;CAC7C,OAAO,EACL,SAAY,MAAc,IAAkC;EAC1D,OAAO,GAAG;CACZ,EACF;AACF"}

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

@@ -0,0 +1,120 @@
+//#region ../@warlock.js/ai/src/orchestrator/signature.ts
+/**
+* Deterministic structural fingerprint of an orchestrator definition
+* (orchestrator.md §10.1). Persisted on every checkpoint so Phase 2 can
+* refuse a turn when the live definition no longer matches the saved
+* session shape. Covers exactly the dispatch contract:
+*
+* - `name`.
+* - The `intents` map — each intent key + its resolved description +
+*   the underlying unit's stable identity (agent name, workflow name +
+*   signature, or a `"callback"` marker for dev-callback intents).
+*   Reuses the supervisor's resolved-entry fingerprinting verbatim.
+* - `route` callback presence (its body is code, not data).
+* - `router` agent identity when LLM routing is configured.
+* - `evaluate` callback presence.
+* - `initialAgent` when set.
+* - `maxIterations`.
+* - The `iterate` flag — flipping single-dispatch to delegated
+*   iteration is a semantic shape change.
+* - The `historyWindow` config SHAPE — which roles window and whether
+*   each is a number or a callback (not the window value itself).
+*
+* Does NOT cover (§10.1): `version` (metadata only), `systemPrompt`
+* text, logger config, store identities, event handlers, or callback
+* function bodies (callbacks fingerprint as their presence/`"callback"`
+* marker only). The orchestrator signature does NOT aggregate the
+* internal supervisor's signature — that is a per-run concern delegated
+* to `supervisor.resume()`'s own drift check on `iterate: true`.
+*
+* @example
+* const signature = computeOrchestratorSignature(config, resolvedEntries);
+* // "1a2b3c4d" — 8-char FNV-1a hex, stable across process restarts.
+*/
+function computeOrchestratorSignature(config, entries) {
+	const intentsFingerprint = [...entries.entries()].sort(([first], [second]) => first.localeCompare(second)).map(([intent, entry]) => ({
+		k: intent,
+		d: entry.description,
+		u: fingerprintUnit(entry)
+	}));
+	const fingerprint = {
+		n: config.name,
+		a: intentsFingerprint,
+		r: resolveRouterName(config.router),
+		rc: config.route ? 1 : 0,
+		e: config.evaluate ? 1 : 0,
+		i: config.initialAgent ?? null,
+		m: config.maxIterations ?? null,
+		it: config.iterate ? 1 : 0,
+		hw: fingerprintHistoryWindow(config.historyWindow)
+	};
+	return hash(JSON.stringify(fingerprint));
+}
+/**
+* Router identity for the fingerprint. Accepts both the bare-agent
+* shorthand and the `{ agent, ... }` entry form, returning the agent's
+* name (or `null` when no router is configured). Mirrors the
+* supervisor's `resolveRouterName`.
+*/
+function resolveRouterName(router) {
+	if (!router) return null;
+	if (typeof router.execute === "function") return router.name ?? null;
+	return router.agent?.name ?? null;
+}
+/**
+* Structural fingerprint of the `historyWindow` config. Records the
+* windowing strategy per role (`"number"` / `"callback"` / `null`) so a
+* dev swapping a fixed-size window for a token-counting callback drifts
+* the signature, while tuning the window value (e.g. `5` → `8`) does
+* not. The window value is a runtime knob, not a shape change.
+*/
+function fingerprintHistoryWindow(historyWindow) {
+	return {
+		router: fingerprintHistoryWindowRole(historyWindow?.router),
+		agents: fingerprintHistoryWindowRole(historyWindow?.agents)
+	};
+}
+function fingerprintHistoryWindowRole(window) {
+	if (window === void 0) return null;
+	if (typeof window === "function") return "callback";
+	return "number";
+}
+/**
+* Stable identity of one resolved intent's underlying unit. Agents
+* fingerprint by name; workflows by name + their own signature;
+* callbacks by a type marker only (their closure can't be hashed
+* deterministically, so drift covers add/remove/rename, not body
+* edits). Identical to the supervisor's `fingerprintUnit`.
+*/
+function fingerprintUnit(entry) {
+	if (entry.type === "callback") return { t: "callback" };
+	if (entry.type === "workflow") {
+		const workflow = entry.unit;
+		return {
+			t: "workflow",
+			n: workflow.name,
+			s: workflow.signature
+		};
+	}
+	return {
+		t: "agent",
+		n: entry.unit.name
+	};
+}
+/**
+* FNV-1a 32-bit — the same hash `supervisor/signature.ts` and
+* `workflow/signature.ts` use. Deterministic, no crypto dependency,
+* cheap; signatures are 8-char hex.
+*/
+function hash(input) {
+	let h = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		h ^= input.charCodeAt(i);
+		h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+	}
+	return h.toString(16).padStart(8, "0");
+}
+
+//#endregion
+export { computeOrchestratorSignature };
+//# sourceMappingURL=signature.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"signature.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/signature.ts"],"sourcesContent":["import type { OrchestratorConfig } from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type { ResolvedIntentEntry } from \"../supervisor/entries\";\n\n/**\n * Shape of the `historyWindow` config a fingerprint records. A number\n * window is recorded as `\"number\"`; a callback window as `\"callback\"`;\n * an absent role as `null`. The window VALUE (the literal `5`, the\n * callback body) is deliberately excluded — only the structural choice\n * of windowing strategy per role drifts the signature (§10.1).\n */\ntype HistoryWindowRoleFingerprint = \"number\" | \"callback\" | null;\n\n/**\n * Deterministic structural fingerprint of an orchestrator definition\n * (orchestrator.md §10.1). Persisted on every checkpoint so Phase 2 can\n * refuse a turn when the live definition no longer matches the saved\n * session shape. Covers exactly the dispatch contract:\n *\n * - `name`.\n * - The `intents` map — each intent key + its resolved description +\n *   the underlying unit's stable identity (agent name, workflow name +\n *   signature, or a `\"callback\"` marker for dev-callback intents).\n *   Reuses the supervisor's resolved-entry fingerprinting verbatim.\n * - `route` callback presence (its body is code, not data).\n * - `router` agent identity when LLM routing is configured.\n * - `evaluate` callback presence.\n * - `initialAgent` when set.\n * - `maxIterations`.\n * - The `iterate` flag — flipping single-dispatch to delegated\n *   iteration is a semantic shape change.\n * - The `historyWindow` config SHAPE — which roles window and whether\n *   each is a number or a callback (not the window value itself).\n *\n * Does NOT cover (§10.1): `version` (metadata only), `systemPrompt`\n * text, logger config, store identities, event handlers, or callback\n * function bodies (callbacks fingerprint as their presence/`\"callback\"`\n * marker only). The orchestrator signature does NOT aggregate the\n * internal supervisor's signature — that is a per-run concern delegated\n * to `supervisor.resume()`'s own drift check on `iterate: true`.\n *\n * @example\n * const signature = computeOrchestratorSignature(config, resolvedEntries);\n * // \"1a2b3c4d\" — 8-char FNV-1a hex, stable across process restarts.\n */\nexport function computeOrchestratorSignature(\n  config: OrchestratorConfig<unknown>,\n  entries: Map<string, ResolvedIntentEntry>,\n): string {\n  const intentsFingerprint = [...entries.entries()]\n    .sort(([first], [second]) => first.localeCompare(second))\n    .map(([intent, entry]) => ({\n      k: intent,\n      d: entry.description,\n      u: fingerprintUnit(entry),\n    }));\n\n  const fingerprint = {\n    n: config.name,\n    a: intentsFingerprint,\n    r: resolveRouterName(config.router),\n    rc: config.route ? 1 : 0,\n    e: config.evaluate ? 1 : 0,\n    i: config.initialAgent ?? null,\n    m: config.maxIterations ?? null,\n    it: config.iterate ? 1 : 0,\n    hw: fingerprintHistoryWindow(config.historyWindow),\n  };\n\n  return hash(JSON.stringify(fingerprint));\n}\n\n/**\n * Router identity for the fingerprint. Accepts both the bare-agent\n * shorthand and the `{ agent, ... }` entry form, returning the agent's\n * name (or `null` when no router is configured). Mirrors the\n * supervisor's `resolveRouterName`.\n */\nfunction resolveRouterName(router: OrchestratorConfig<unknown>[\"router\"]): string | null {\n  if (!router) {\n    return null;\n  }\n\n  if (typeof (router as { execute?: unknown }).execute === \"function\") {\n    return (router as { name?: string }).name ?? null;\n  }\n\n  return (router as { agent?: { name?: string } }).agent?.name ?? null;\n}\n\n/**\n * Structural fingerprint of the `historyWindow` config. Records the\n * windowing strategy per role (`\"number\"` / `\"callback\"` / `null`) so a\n * dev swapping a fixed-size window for a token-counting callback drifts\n * the signature, while tuning the window value (e.g. `5` → `8`) does\n * not. The window value is a runtime knob, not a shape change.\n */\nfunction fingerprintHistoryWindow(\n  historyWindow: OrchestratorConfig<unknown>[\"historyWindow\"],\n): { router: HistoryWindowRoleFingerprint; agents: HistoryWindowRoleFingerprint } {\n  return {\n    router: fingerprintHistoryWindowRole(historyWindow?.router),\n    agents: fingerprintHistoryWindowRole(historyWindow?.agents),\n  };\n}\n\nfunction fingerprintHistoryWindowRole(\n  window: number | ((...args: never[]) => unknown) | undefined,\n): HistoryWindowRoleFingerprint {\n  if (window === undefined) {\n    return null;\n  }\n\n  if (typeof window === \"function\") {\n    return \"callback\";\n  }\n\n  return \"number\";\n}\n\n/**\n * Stable identity of one resolved intent's underlying unit. Agents\n * fingerprint by name; workflows by name + their own signature;\n * callbacks by a type marker only (their closure can't be hashed\n * deterministically, so drift covers add/remove/rename, not body\n * edits). Identical to the supervisor's `fingerprintUnit`.\n */\nfunction fingerprintUnit(entry: ResolvedIntentEntry): unknown {\n  if (entry.type === \"callback\") {\n    return { t: \"callback\" };\n  }\n\n  if (entry.type === \"workflow\") {\n    const workflow = entry.unit;\n    return { t: \"workflow\", n: workflow.name, s: workflow.signature };\n  }\n\n  return { t: \"agent\", n: entry.unit.name };\n}\n\n/**\n * FNV-1a 32-bit — the same hash `supervisor/signature.ts` and\n * `workflow/signature.ts` use. Deterministic, no crypto dependency,\n * cheap; signatures are 8-char hex.\n */\nfunction hash(input: string): string {\n  let h = 0x811c9dc5;\n\n  for (let i = 0; i < input.length; i++) {\n    h ^= input.charCodeAt(i);\n    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;\n  }\n\n  return h.toString(16).padStart(8, \"0\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAAgB,6BACd,QACA,SACQ;CACR,MAAM,qBAAqB,CAAC,GAAG,QAAQ,QAAQ,CAAC,CAAC,CAC9C,MAAM,CAAC,QAAQ,CAAC,YAAY,MAAM,cAAc,MAAM,CAAC,CAAC,CACxD,KAAK,CAAC,QAAQ,YAAY;EACzB,GAAG;EACH,GAAG,MAAM;EACT,GAAG,gBAAgB,KAAK;CAC1B,EAAE;CAEJ,MAAM,cAAc;EAClB,GAAG,OAAO;EACV,GAAG;EACH,GAAG,kBAAkB,OAAO,MAAM;EAClC,IAAI,OAAO,QAAQ,IAAI;EACvB,GAAG,OAAO,WAAW,IAAI;EACzB,GAAG,OAAO,gBAAgB;EAC1B,GAAG,OAAO,iBAAiB;EAC3B,IAAI,OAAO,UAAU,IAAI;EACzB,IAAI,yBAAyB,OAAO,aAAa;CACnD;CAEA,OAAO,KAAK,KAAK,UAAU,WAAW,CAAC;AACzC;;;;;;;AAQA,SAAS,kBAAkB,QAA8D;CACvF,IAAI,CAAC,QACH,OAAO;CAGT,IAAI,OAAQ,OAAiC,YAAY,YACvD,OAAQ,OAA6B,QAAQ;CAG/C,OAAQ,OAAyC,OAAO,QAAQ;AAClE;;;;;;;;AASA,SAAS,yBACP,eACgF;CAChF,OAAO;EACL,QAAQ,6BAA6B,eAAe,MAAM;EAC1D,QAAQ,6BAA6B,eAAe,MAAM;CAC5D;AACF;AAEA,SAAS,6BACP,QAC8B;CAC9B,IAAI,WAAW,QACb,OAAO;CAGT,IAAI,OAAO,WAAW,YACpB,OAAO;CAGT,OAAO;AACT;;;;;;;;AASA,SAAS,gBAAgB,OAAqC;CAC5D,IAAI,MAAM,SAAS,YACjB,OAAO,EAAE,GAAG,WAAW;CAGzB,IAAI,MAAM,SAAS,YAAY;EAC7B,MAAM,WAAW,MAAM;EACvB,OAAO;GAAE,GAAG;GAAY,GAAG,SAAS;GAAM,GAAG,SAAS;EAAU;CAClE;CAEA,OAAO;EAAE,GAAG;EAAS,GAAG,MAAM,KAAK;CAAK;AAC1C;;;;;;AAOA,SAAS,KAAK,OAAuB;CACnC,IAAI,IAAI;CAER,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,KAAK,MAAM,WAAW,CAAC;EACvB,IAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,SAAU;CACxE;CAEA,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;AACvC"}

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

@@ -0,0 +1,56 @@
+//#region ../@warlock.js/ai/src/orchestrator/window.ts
+/**
+* Framework-default history windows (orchestrator.md §4 Phase 4 — "5
+* for the router, 15 for intents"). Applied when neither a per-entity
+* override nor a tier default is configured.
+*/
+const DEFAULT_ROUTER_WINDOW = 5;
+const DEFAULT_AGENTS_WINDOW = 15;
+/**
+* Apply a single window to a history array. A number keeps the last N
+* messages (most recent, chronological order preserved); a callback
+* takes full control of the slice (the escape hatch for token-counting
+* or semantic windowing — §4 Phase 4). `N <= 0` keeps nothing.
+*/
+function applyWindow(messages, window) {
+	if (typeof window === "function") return window(messages);
+	if (window <= 0) return [];
+	if (messages.length <= window) return messages.slice();
+	return messages.slice(messages.length - window);
+}
+/**
+* Phase 4 — window history (orchestrator.md §3 / §4 Phase 4). Applies
+* the `historyWindow` cascade to the dev-supplied `history` before it
+* is bound into the router and the dispatched agents. Two tiers,
+* evaluated per-role:
+*
+* 1. Tier default — `historyWindow.router` / `historyWindow.agents`.
+* 2. Framework default — `5` for the router, `15` for agents.
+*
+* (The first cascade layer — per-entity overrides on individual
+* intents / the router entry — is the supervisor's concern: it lives
+* on the intent entries the orchestrator spreads into the supervisor,
+* and the supervisor applies it to the agent-windowed slice this phase
+* produces. The orchestrator owns only the two role-level tiers.)
+*
+* Emits `orchestrator.history.windowed` with the agent-slice message
+* count. Pure aside from the event — returns the per-role slices for
+* the dispatch phase to thread through.
+*/
+function windowHistory(ctx, sessionId, history) {
+	const config = ctx.config.historyWindow;
+	const router = applyWindow(history, config?.router ?? 5);
+	const agents = applyWindow(history, config?.agents ?? 15);
+	ctx.emitter.emit("orchestrator.history.windowed", {
+		sessionId,
+		messageCount: agents.length
+	});
+	return {
+		router,
+		agents
+	};
+}
+
+//#endregion
+export { windowHistory };
+//# sourceMappingURL=window.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"window.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/window.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\n\n/**\n * Framework-default history windows (orchestrator.md §4 Phase 4 — \"5\n * for the router, 15 for intents\"). Applied when neither a per-entity\n * override nor a tier default is configured.\n */\nexport const DEFAULT_ROUTER_WINDOW = 5;\nexport const DEFAULT_AGENTS_WINDOW = 15;\n\n/** A history window: keep the last N messages, or a custom slicer. */\nexport type HistoryWindowValue =\n  | number\n  | ((messages: Message[]) => Message[]);\n\n/**\n * The windowed history bound into each consumer for a turn (§4 Phase\n * 4). Applied per-dispatchable, independently: the router can see a\n * different slice than the dispatched agents.\n */\nexport type WindowedHistory = {\n  /** Slice bound into the router's context. */\n  router: Message[];\n  /** Slice forwarded to every dispatched intent/agent. */\n  agents: Message[];\n};\n\n/**\n * Apply a single window to a history array. A number keeps the last N\n * messages (most recent, chronological order preserved); a callback\n * takes full control of the slice (the escape hatch for token-counting\n * or semantic windowing — §4 Phase 4). `N <= 0` keeps nothing.\n */\nexport function applyWindow(\n  messages: Message[],\n  window: HistoryWindowValue,\n): Message[] {\n  if (typeof window === \"function\") {\n    return window(messages);\n  }\n\n  if (window <= 0) {\n    return [];\n  }\n\n  if (messages.length <= window) {\n    return messages.slice();\n  }\n\n  return messages.slice(messages.length - window);\n}\n\n/**\n * Phase 4 — window history (orchestrator.md §3 / §4 Phase 4). Applies\n * the `historyWindow` cascade to the dev-supplied `history` before it\n * is bound into the router and the dispatched agents. Two tiers,\n * evaluated per-role:\n *\n * 1. Tier default — `historyWindow.router` / `historyWindow.agents`.\n * 2. Framework default — `5` for the router, `15` for agents.\n *\n * (The first cascade layer — per-entity overrides on individual\n * intents / the router entry — is the supervisor's concern: it lives\n * on the intent entries the orchestrator spreads into the supervisor,\n * and the supervisor applies it to the agent-windowed slice this phase\n * produces. The orchestrator owns only the two role-level tiers.)\n *\n * Emits `orchestrator.history.windowed` with the agent-slice message\n * count. Pure aside from the event — returns the per-role slices for\n * the dispatch phase to thread through.\n */\nexport function windowHistory(\n  ctx: OrchestratorEngineContext,\n  sessionId: string,\n  history: Message[],\n): WindowedHistory {\n  const config = ctx.config.historyWindow;\n\n  const router = applyWindow(history, config?.router ?? DEFAULT_ROUTER_WINDOW);\n  const agents = applyWindow(history, config?.agents ?? DEFAULT_AGENTS_WINDOW);\n\n  ctx.emitter.emit(\"orchestrator.history.windowed\", {\n    sessionId,\n    messageCount: agents.length,\n  });\n\n  return { router, agents };\n}\n"],"mappings":";;;;;;AAQA,MAAa,wBAAwB;AACrC,MAAa,wBAAwB;;;;;;;AAyBrC,SAAgB,YACd,UACA,QACW;CACX,IAAI,OAAO,WAAW,YACpB,OAAO,OAAO,QAAQ;CAGxB,IAAI,UAAU,GACZ,OAAO,CAAC;CAGV,IAAI,SAAS,UAAU,QACrB,OAAO,SAAS,MAAM;CAGxB,OAAO,SAAS,MAAM,SAAS,SAAS,MAAM;AAChD;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,cACd,KACA,WACA,SACiB;CACjB,MAAM,SAAS,IAAI,OAAO;CAE1B,MAAM,SAAS,YAAY,SAAS,QAAQ,WAA+B;CAC3E,MAAM,SAAS,YAAY,SAAS,QAAQ,YAA+B;CAE3E,IAAI,QAAQ,KAAK,iCAAiC;EAChD;EACA,cAAc,OAAO;CACvB,CAAC;CAED,OAAO;EAAE;EAAQ;CAAO;AAC1B"}

package/esm/ai/src/planner/dag-scheduler.mjs

@@ -0,0 +1,97 @@
+import { PlannerPlanInvalidError } from "../errors/planner-plan-invalid-error.mjs";
+
+//#region ../@warlock.js/ai/src/planner/dag-scheduler.ts
+/**
+* Build the execution DAG from a plan's steps.
+*
+* Each step's `id` (falling back to its array index) and its `dependsOn`
+* become an adjacency list. A `dependsOn` that names a step not in the
+* plan, or any dependency cycle, raises a typed
+* {@link PlannerPlanInvalidError} BEFORE any step runs — the same error
+* class `generatePlan` uses for an unusable plan, with forensic context.
+*
+* @throws PlannerPlanInvalidError on a duplicate id, an unknown
+*   `dependsOn` target, or a cycle.
+*/
+function buildDag(steps, plannerName = "planner") {
+	const nodes = [];
+	const byId = /* @__PURE__ */ new Map();
+	for (let index = 0; index < steps.length; index++) {
+		const step = steps[index];
+		const id = step.id ?? String(index);
+		if (byId.has(id)) throw new PlannerPlanInvalidError(`ai.planner("${plannerName}"): duplicate step id "${id}" in DAG plan`, { context: { id } });
+		const node = {
+			id,
+			index,
+			step,
+			dependencies: []
+		};
+		nodes.push(node);
+		byId.set(id, node);
+	}
+	const dependents = /* @__PURE__ */ new Map();
+	for (const node of nodes) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const dependency of node.step.dependsOn ?? []) {
+			if (dependency === node.id) continue;
+			if (!byId.has(dependency)) throw new PlannerPlanInvalidError(`ai.planner("${plannerName}"): step "${node.id}" depends on unknown step "${dependency}"`, { context: {
+				id: node.id,
+				dependency
+			} });
+			if (seen.has(dependency)) continue;
+			seen.add(dependency);
+			node.dependencies.push(dependency);
+			const reverse = dependents.get(dependency) ?? [];
+			reverse.push(node.id);
+			dependents.set(dependency, reverse);
+		}
+	}
+	assertAcyclic(nodes, byId, plannerName);
+	return {
+		nodes,
+		byId,
+		dependents
+	};
+}
+/**
+* Compute the next ready set: nodes not yet done whose every dependency
+* is in `completed`. Preserves original plan order so a level dispatches
+* deterministically. A node whose dependency is `unreachable` (a failed
+* or skipped ancestor) is NOT ready — it never becomes ready and is
+* recorded skipped by the caller.
+*/
+function readyNodes(dag, completed, done) {
+	return dag.nodes.filter((node) => !done.has(node.id) && node.dependencies.every((dependency) => completed.has(dependency)));
+}
+/**
+* The topological sink(s) — nodes nothing depends on. Used to define the
+* "final output" under parallelism: with an `output` schema set, a
+* single sink is the unambiguous final step; multiple sinks are a
+* convergence error the caller surfaces.
+*/
+function sinkNodes(dag) {
+	return dag.nodes.filter((node) => (dag.dependents.get(node.id) ?? []).length === 0);
+}
+/**
+* Depth-first cycle detection over the dependency edges. A back-edge to
+* a node on the current recursion stack means a cycle — raised as a
+* typed {@link PlannerPlanInvalidError} naming the offending node.
+*/
+function assertAcyclic(nodes, byId, plannerName) {
+	const VISITING = 1;
+	const DONE = 2;
+	const state = /* @__PURE__ */ new Map();
+	const visit = (node) => {
+		const current = state.get(node.id);
+		if (current === DONE) return;
+		if (current === VISITING) throw new PlannerPlanInvalidError(`ai.planner("${plannerName}"): dependency cycle detected at step "${node.id}"`, { context: { id: node.id } });
+		state.set(node.id, VISITING);
+		for (const dependency of node.dependencies) visit(byId.get(dependency));
+		state.set(node.id, DONE);
+	};
+	for (const node of nodes) visit(node);
+}
+
+//#endregion
+export { buildDag, readyNodes, sinkNodes };
+//# sourceMappingURL=dag-scheduler.mjs.map

package/esm/ai/src/planner/dag-scheduler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag-scheduler.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/planner/dag-scheduler.ts"],"sourcesContent":["import type { PlannerStep } from \"../contracts/planner/planner-plan.type\";\nimport { PlannerPlanInvalidError } from \"../errors/planner-plan-invalid-error\";\n\n/**\n * One node in the planner's execution DAG — a plan step plus the\n * resolved structural metadata the scheduler needs to order it.\n *\n * `id` is the step's own `id` when present, falling back to the step's\n * array index stringified (exactly as {@link PlannerStep.id} documents).\n * `dependencies` is the resolved set of node ids this step waits on,\n * de-duplicated and self-references dropped.\n */\nexport type DagNode = {\n  /** Stable id — the step's own `id`, or its array index as a string. */\n  id: string;\n  /** 0-based position of the step in the original plan array. */\n  index: number;\n  /** The plan step this node schedules. */\n  step: PlannerStep;\n  /** Resolved ids this step depends on (subset of the DAG's node ids). */\n  dependencies: string[];\n};\n\n/**\n * The built execution DAG — the ordered node list plus the lookups the\n * scheduler walks. Ordering follows the original plan array so a\n * dependency-free plan executes in author order, level by level.\n */\nexport type PlannerDag = {\n  /** Nodes in original plan order. */\n  nodes: DagNode[];\n  /** id → node, for dependency resolution and sink detection. */\n  byId: Map<string, DagNode>;\n  /** id → ids of the nodes that depend on it (reverse edges). */\n  dependents: Map<string, string[]>;\n};\n\n/**\n * Build the execution DAG from a plan's steps.\n *\n * Each step's `id` (falling back to its array index) and its `dependsOn`\n * become an adjacency list. A `dependsOn` that names a step not in the\n * plan, or any dependency cycle, raises a typed\n * {@link PlannerPlanInvalidError} BEFORE any step runs — the same error\n * class `generatePlan` uses for an unusable plan, with forensic context.\n *\n * @throws PlannerPlanInvalidError on a duplicate id, an unknown\n *   `dependsOn` target, or a cycle.\n */\nexport function buildDag(steps: PlannerStep[], plannerName = \"planner\"): PlannerDag {\n  const nodes: DagNode[] = [];\n  const byId = new Map<string, DagNode>();\n\n  // Pass 1 — assign every step a stable id (own id or array index) and\n  // index the nodes. Duplicate explicit ids are a malformed plan.\n  for (let index = 0; index < steps.length; index++) {\n    const step = steps[index] as PlannerStep;\n    const id = step.id ?? String(index);\n\n    if (byId.has(id)) {\n      throw new PlannerPlanInvalidError(\n        `ai.planner(\"${plannerName}\"): duplicate step id \"${id}\" in DAG plan`,\n        { context: { id } },\n      );\n    }\n\n    const node: DagNode = { id, index, step, dependencies: [] };\n    nodes.push(node);\n    byId.set(id, node);\n  }\n\n  // Pass 2 — resolve dependencies against the id set; reject unknowns,\n  // dedupe, and drop self-references (a no-op edge, never a cycle).\n  const dependents = new Map<string, string[]>();\n\n  for (const node of nodes) {\n    const seen = new Set<string>();\n\n    for (const dependency of node.step.dependsOn ?? []) {\n      if (dependency === node.id) {\n        continue;\n      }\n\n      if (!byId.has(dependency)) {\n        throw new PlannerPlanInvalidError(\n          `ai.planner(\"${plannerName}\"): step \"${node.id}\" depends on unknown step \"${dependency}\"`,\n          { context: { id: node.id, dependency } },\n        );\n      }\n\n      if (seen.has(dependency)) {\n        continue;\n      }\n\n      seen.add(dependency);\n      node.dependencies.push(dependency);\n\n      const reverse = dependents.get(dependency) ?? [];\n      reverse.push(node.id);\n      dependents.set(dependency, reverse);\n    }\n  }\n\n  assertAcyclic(nodes, byId, plannerName);\n\n  return { nodes, byId, dependents };\n}\n\n/**\n * Compute the next ready set: nodes not yet done whose every dependency\n * is in `completed`. Preserves original plan order so a level dispatches\n * deterministically. A node whose dependency is `unreachable` (a failed\n * or skipped ancestor) is NOT ready — it never becomes ready and is\n * recorded skipped by the caller.\n */\nexport function readyNodes(\n  dag: PlannerDag,\n  completed: ReadonlySet<string>,\n  done: ReadonlySet<string>,\n): DagNode[] {\n  return dag.nodes.filter(\n    (node) =>\n      !done.has(node.id) &&\n      node.dependencies.every((dependency) => completed.has(dependency)),\n  );\n}\n\n/**\n * The topological sink(s) — nodes nothing depends on. Used to define the\n * \"final output\" under parallelism: with an `output` schema set, a\n * single sink is the unambiguous final step; multiple sinks are a\n * convergence error the caller surfaces.\n */\nexport function sinkNodes(dag: PlannerDag): DagNode[] {\n  return dag.nodes.filter((node) => (dag.dependents.get(node.id) ?? []).length === 0);\n}\n\n/**\n * Depth-first cycle detection over the dependency edges. A back-edge to\n * a node on the current recursion stack means a cycle — raised as a\n * typed {@link PlannerPlanInvalidError} naming the offending node.\n */\nfunction assertAcyclic(\n  nodes: DagNode[],\n  byId: Map<string, DagNode>,\n  plannerName: string,\n): void {\n  const VISITING = 1;\n  const DONE = 2;\n  const state = new Map<string, number>();\n\n  const visit = (node: DagNode): void => {\n    const current = state.get(node.id);\n\n    if (current === DONE) {\n      return;\n    }\n\n    if (current === VISITING) {\n      throw new PlannerPlanInvalidError(\n        `ai.planner(\"${plannerName}\"): dependency cycle detected at step \"${node.id}\"`,\n        { context: { id: node.id } },\n      );\n    }\n\n    state.set(node.id, VISITING);\n\n    for (const dependency of node.dependencies) {\n      visit(byId.get(dependency) as DagNode);\n    }\n\n    state.set(node.id, DONE);\n  };\n\n  for (const node of nodes) {\n    visit(node);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAiDA,SAAgB,SAAS,OAAsB,cAAc,WAAuB;CAClF,MAAM,QAAmB,CAAC;CAC1B,MAAM,uBAAO,IAAI,IAAqB;CAItC,KAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS;EACjD,MAAM,OAAO,MAAM;EACnB,MAAM,KAAK,KAAK,MAAM,OAAO,KAAK;EAElC,IAAI,KAAK,IAAI,EAAE,GACb,MAAM,IAAI,wBACR,eAAe,YAAY,yBAAyB,GAAG,gBACvD,EAAE,SAAS,EAAE,GAAG,EAAE,CACpB;EAGF,MAAM,OAAgB;GAAE;GAAI;GAAO;GAAM,cAAc,CAAC;EAAE;EAC1D,MAAM,KAAK,IAAI;EACf,KAAK,IAAI,IAAI,IAAI;CACnB;CAIA,MAAM,6BAAa,IAAI,IAAsB;CAE7C,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,uBAAO,IAAI,IAAY;EAE7B,KAAK,MAAM,cAAc,KAAK,KAAK,aAAa,CAAC,GAAG;GAClD,IAAI,eAAe,KAAK,IACtB;GAGF,IAAI,CAAC,KAAK,IAAI,UAAU,GACtB,MAAM,IAAI,wBACR,eAAe,YAAY,YAAY,KAAK,GAAG,6BAA6B,WAAW,IACvF,EAAE,SAAS;IAAE,IAAI,KAAK;IAAI;GAAW,EAAE,CACzC;GAGF,IAAI,KAAK,IAAI,UAAU,GACrB;GAGF,KAAK,IAAI,UAAU;GACnB,KAAK,aAAa,KAAK,UAAU;GAEjC,MAAM,UAAU,WAAW,IAAI,UAAU,KAAK,CAAC;GAC/C,QAAQ,KAAK,KAAK,EAAE;GACpB,WAAW,IAAI,YAAY,OAAO;EACpC;CACF;CAEA,cAAc,OAAO,MAAM,WAAW;CAEtC,OAAO;EAAE;EAAO;EAAM;CAAW;AACnC;;;;;;;;AASA,SAAgB,WACd,KACA,WACA,MACW;CACX,OAAO,IAAI,MAAM,QACd,SACC,CAAC,KAAK,IAAI,KAAK,EAAE,KACjB,KAAK,aAAa,OAAO,eAAe,UAAU,IAAI,UAAU,CAAC,CACrE;AACF;;;;;;;AAQA,SAAgB,UAAU,KAA4B;CACpD,OAAO,IAAI,MAAM,QAAQ,UAAU,IAAI,WAAW,IAAI,KAAK,EAAE,KAAK,CAAC,EAAC,CAAE,WAAW,CAAC;AACpF;;;;;;AAOA,SAAS,cACP,OACA,MACA,aACM;CACN,MAAM,WAAW;CACjB,MAAM,OAAO;CACb,MAAM,wBAAQ,IAAI,IAAoB;CAEtC,MAAM,SAAS,SAAwB;EACrC,MAAM,UAAU,MAAM,IAAI,KAAK,EAAE;EAEjC,IAAI,YAAY,MACd;EAGF,IAAI,YAAY,UACd,MAAM,IAAI,wBACR,eAAe,YAAY,yCAAyC,KAAK,GAAG,IAC5E,EAAE,SAAS,EAAE,IAAI,KAAK,GAAG,EAAE,CAC7B;EAGF,MAAM,IAAI,KAAK,IAAI,QAAQ;EAE3B,KAAK,MAAM,cAAc,KAAK,cAC5B,MAAM,KAAK,IAAI,UAAU,CAAY;EAGvC,MAAM,IAAI,KAAK,IAAI,IAAI;CACzB;CAEA,KAAK,MAAM,QAAQ,OACjB,MAAM,IAAI;AAEd"}

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

@@ -0,0 +1,6 @@
+import { buildPlanSystemPrompt } from "./plan-prompt.mjs";
+import { planSchema } from "./plan-schema.mjs";
+import { computeSignature } from "./signature.mjs";
+import { planner } from "./planner.mjs";
+
+export {  };

package/esm/ai/src/planner/plan-prompt.mjs

@@ -0,0 +1,31 @@
+//#region ../@warlock.js/ai/src/planner/plan-prompt.ts
+/**
+* Assemble the plan-generation system prompt: optional caller framing on
+* top, then the mechanical block listing every capability + its
+* description and the rules for emitting an ordered plan.
+*
+* Runs once at factory time (the capability set is fixed for the
+* planner's lifetime) — the produced string is baked onto the internal
+* planning agent.
+*/
+function buildPlanSystemPrompt(capabilities, maxSteps, prefix, dag = false) {
+	const capabilityLines = capabilities.map((capability) => `- ${capability.name}: ${capability.description}`);
+	const sections = [];
+	const resolvedPrefix = resolvePrefix(prefix);
+	if (resolvedPrefix && resolvedPrefix.trim().length > 0) sections.push(resolvedPrefix.trim(), "");
+	sections.push("You are a planner. Break the user's goal into an ordered sequence of steps,", "each one dispatching exactly one of the available capabilities below.", "", "Available capabilities:", ...capabilityLines, "", "Rules:", `- Produce at most ${maxSteps} steps.`, "- Each step's `capability` must be exactly one name from the list above.", "- Each step's `input` is the concrete instruction passed to that capability.", "- Order the steps so each builds on the outputs of the ones before it.", "- Never invent a capability name that is not listed.", "- Keep the plan minimal — only the steps actually needed to satisfy the goal.");
+	if (dag) sections.push("- Give each step a stable `id` and list the ids it builds on in `dependsOn`.", "- Steps with no `dependsOn` between them run in PARALLEL — only add a", "  dependency when a step genuinely needs an earlier step's output.", "- The plan must converge: avoid dependency cycles.");
+	return sections.join("\n");
+}
+/**
+* Resolve a caller-supplied `systemPrompt` (string or contract) to plain
+* text. Returns `undefined` when none was supplied.
+*/
+function resolvePrefix(prompt) {
+	if (!prompt) return;
+	return typeof prompt === "string" ? prompt : prompt.resolve();
+}
+
+//#endregion
+export { buildPlanSystemPrompt };
+//# sourceMappingURL=plan-prompt.mjs.map

package/esm/ai/src/planner/plan-prompt.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-prompt.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/planner/plan-prompt.ts"],"sourcesContent":["import type { PlannerCapability } from \"../contracts/planner/planner-capability.type\";\nimport type { SystemPromptContract } from \"../contracts/system-prompt.contract\";\n\n/**\n * Assemble the plan-generation system prompt: optional caller framing on\n * top, then the mechanical block listing every capability + its\n * description and the rules for emitting an ordered plan.\n *\n * Runs once at factory time (the capability set is fixed for the\n * planner's lifetime) — the produced string is baked onto the internal\n * planning agent.\n */\nexport function buildPlanSystemPrompt(\n  capabilities: PlannerCapability[],\n  maxSteps: number,\n  prefix: SystemPromptContract | string | undefined,\n  dag = false,\n): string {\n  const capabilityLines = capabilities.map(\n    (capability) => `- ${capability.name}: ${capability.description}`,\n  );\n\n  const sections: string[] = [];\n  const resolvedPrefix = resolvePrefix(prefix);\n\n  if (resolvedPrefix && resolvedPrefix.trim().length > 0) {\n    sections.push(resolvedPrefix.trim(), \"\");\n  }\n\n  sections.push(\n    \"You are a planner. Break the user's goal into an ordered sequence of steps,\",\n    \"each one dispatching exactly one of the available capabilities below.\",\n    \"\",\n    \"Available capabilities:\",\n    ...capabilityLines,\n    \"\",\n    \"Rules:\",\n    `- Produce at most ${maxSteps} steps.`,\n    \"- Each step's `capability` must be exactly one name from the list above.\",\n    \"- Each step's `input` is the concrete instruction passed to that capability.\",\n    \"- Order the steps so each builds on the outputs of the ones before it.\",\n    \"- Never invent a capability name that is not listed.\",\n    \"- Keep the plan minimal — only the steps actually needed to satisfy the goal.\",\n  );\n\n  if (dag) {\n    // DAG mode — the runtime schedules independent steps in parallel off\n    // `dependsOn`, so the model should declare dependencies explicitly\n    // rather than relying purely on array order.\n    sections.push(\n      \"- Give each step a stable `id` and list the ids it builds on in `dependsOn`.\",\n      \"- Steps with no `dependsOn` between them run in PARALLEL — only add a\",\n      \"  dependency when a step genuinely needs an earlier step's output.\",\n      \"- The plan must converge: avoid dependency cycles.\",\n    );\n  }\n\n  return sections.join(\"\\n\");\n}\n\n/**\n * Resolve a caller-supplied `systemPrompt` (string or contract) to plain\n * text. Returns `undefined` when none was supplied.\n */\nfunction resolvePrefix(prompt: SystemPromptContract | string | undefined): string | undefined {\n  if (!prompt) {\n    return undefined;\n  }\n\n  return typeof prompt === \"string\" ? prompt : prompt.resolve();\n}\n"],"mappings":";;;;;;;;;;AAYA,SAAgB,sBACd,cACA,UACA,QACA,MAAM,OACE;CACR,MAAM,kBAAkB,aAAa,KAClC,eAAe,KAAK,WAAW,KAAK,IAAI,WAAW,aACtD;CAEA,MAAM,WAAqB,CAAC;CAC5B,MAAM,iBAAiB,cAAc,MAAM;CAE3C,IAAI,kBAAkB,eAAe,KAAK,CAAC,CAAC,SAAS,GACnD,SAAS,KAAK,eAAe,KAAK,GAAG,EAAE;CAGzC,SAAS,KACP,+EACA,yEACA,IACA,2BACA,GAAG,iBACH,IACA,UACA,qBAAqB,SAAS,UAC9B,4EACA,gFACA,0EACA,wDACA,+EACF;CAEA,IAAI,KAIF,SAAS,KACP,gFACA,yEACA,sEACA,oDACF;CAGF,OAAO,SAAS,KAAK,IAAI;AAC3B;;;;;AAMA,SAAS,cAAc,QAAuE;CAC5F,IAAI,CAAC,QACH;CAGF,OAAO,OAAO,WAAW,WAAW,SAAS,OAAO,QAAQ;AAC9D"}

package/esm/ai/src/planner/plan-schema.mjs

@@ -0,0 +1,120 @@
+//#region ../@warlock.js/ai/src/planner/plan-schema.ts
+/**
+* Build the Standard Schema the planning agent emits — an ordered
+* `{ steps: [...], summary? }` plan whose every step references one of
+* `capabilityNames` via the `capability` field.
+*
+* Mirrors the router's hand-built schema approach
+* (`supervisor/router-factory.ts`): the JSON Schema extension carries
+* the capability names as an `enum` so capable providers enforce the
+* choice natively, while `validate()` still accepts the shape softly so
+* providers without native structured output can pass a parsed object
+* through. Validation is intentionally lenient on `capability` — an
+* unknown name is surfaced later by the planner as a typed
+* `PlannerPlanInvalidError`, with the full forensic context, rather
+* than as an opaque schema issue here.
+*
+* `maxSteps`, when provided, is emitted as the `steps` array's
+* `maxItems` so capable providers refuse to over-produce up front
+* (the planner still truncates the tail to `skipped` defensively).
+*/
+function planSchema(capabilityNames, maxSteps) {
+	const jsonSchema = {
+		type: "object",
+		properties: {
+			summary: {
+				type: ["string", "null"],
+				description: "One-line summary of the overall strategy."
+			},
+			steps: {
+				type: "array",
+				description: "Ordered steps to execute, one capability dispatch each.",
+				items: stepItemsSchema(capabilityNames)
+			}
+		},
+		required: ["summary", "steps"],
+		additionalProperties: false
+	};
+	return { "~standard": {
+		version: 1,
+		vendor: "warlock-planner",
+		jsonSchema: { input: () => jsonSchema },
+		validate(value) {
+			if (!value || typeof value !== "object") return { issues: [{ message: "plan must be an object" }] };
+			const record = value;
+			if (!Array.isArray(record.steps) || record.steps.length === 0) return { issues: [{ message: "plan `steps` must be a non-empty array" }] };
+			const steps = [];
+			for (const raw of record.steps) {
+				const normalized = normalizeStep(raw);
+				if (!normalized) return { issues: [{ message: "each plan step must carry a string `capability` and `input`" }] };
+				steps.push(normalized);
+			}
+			const summary = typeof record.summary === "string" ? record.summary : void 0;
+			return { value: summary !== void 0 ? {
+				steps,
+				summary
+			} : { steps } };
+		}
+	} };
+}
+/** Per-step JSON Schema object — one capability dispatch. */
+function stepItemsSchema(capabilityNames) {
+	return {
+		type: "object",
+		properties: {
+			id: {
+				type: ["string", "null"],
+				description: "Stable step id, referenced by dependsOn."
+			},
+			capability: {
+				type: "string",
+				enum: capabilityNames,
+				description: "Name of the capability to dispatch for this step."
+			},
+			input: {
+				type: "string",
+				description: "Concrete input passed to the capability's execute()."
+			},
+			reason: {
+				type: ["string", "null"],
+				description: "Why this step exists."
+			},
+			dependsOn: {
+				type: ["array", "null"],
+				items: { type: "string" },
+				description: "Ids of steps this one conceptually follows."
+			}
+		},
+		required: [
+			"id",
+			"capability",
+			"input",
+			"reason",
+			"dependsOn"
+		],
+		additionalProperties: false
+	};
+}
+/**
+* Coerce one raw step object into a {@link PlannerStep}, returning
+* `undefined` when the mandatory `capability` / `input` strings are
+* missing. Optional fields are copied only when well-typed.
+*/
+function normalizeStep(raw) {
+	if (!raw || typeof raw !== "object") return;
+	const record = raw;
+	if (typeof record.capability !== "string" || record.capability.length === 0) return;
+	if (typeof record.input !== "string") return;
+	const step = {
+		capability: record.capability,
+		input: record.input
+	};
+	if (typeof record.id === "string") step.id = record.id;
+	if (typeof record.reason === "string") step.reason = record.reason;
+	if (Array.isArray(record.dependsOn) && record.dependsOn.every((entry) => typeof entry === "string")) step.dependsOn = record.dependsOn;
+	return step;
+}
+
+//#endregion
+export { planSchema };
+//# sourceMappingURL=plan-schema.mjs.map

package/esm/ai/src/planner/plan-schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-schema.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/planner/plan-schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { PlannerPlan, PlannerStep } from \"../contracts/planner/planner-plan.type\";\n\n/**\n * Build the Standard Schema the planning agent emits — an ordered\n * `{ steps: [...], summary? }` plan whose every step references one of\n * `capabilityNames` via the `capability` field.\n *\n * Mirrors the router's hand-built schema approach\n * (`supervisor/router-factory.ts`): the JSON Schema extension carries\n * the capability names as an `enum` so capable providers enforce the\n * choice natively, while `validate()` still accepts the shape softly so\n * providers without native structured output can pass a parsed object\n * through. Validation is intentionally lenient on `capability` — an\n * unknown name is surfaced later by the planner as a typed\n * `PlannerPlanInvalidError`, with the full forensic context, rather\n * than as an opaque schema issue here.\n *\n * `maxSteps`, when provided, is emitted as the `steps` array's\n * `maxItems` so capable providers refuse to over-produce up front\n * (the planner still truncates the tail to `skipped` defensively).\n */\nexport function planSchema(\n  capabilityNames: string[],\n  maxSteps?: number,\n): StandardSchemaV1<PlannerPlan> {\n  // OpenAI strict `json_schema` mode (and other native structured-output\n  // providers) require EVERY property to appear in `required` — with truly\n  // optional fields expressed as nullable — and reject array `minItems` /\n  // `maxItems`. So the schema is strict-shaped: all keys required, the\n  // optional ones nullable, no item-count bounds. A non-empty plan is\n  // enforced in `validate()`, and `maxSteps` by the runtime's tail\n  // truncation, so neither bound is needed on the wire.\n  void maxSteps;\n\n  const jsonSchema = {\n    type: \"object\",\n    properties: {\n      summary: {\n        type: [\"string\", \"null\"],\n        description: \"One-line summary of the overall strategy.\",\n      },\n      steps: {\n        type: \"array\",\n        description: \"Ordered steps to execute, one capability dispatch each.\",\n        items: stepItemsSchema(capabilityNames),\n      },\n    },\n    required: [\"summary\", \"steps\"],\n    additionalProperties: false,\n  };\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-planner\",\n      jsonSchema: {\n        input: () => jsonSchema,\n      },\n      validate(value: unknown): StandardSchemaV1.Result<PlannerPlan> {\n        if (!value || typeof value !== \"object\") {\n          return { issues: [{ message: \"plan must be an object\" }] };\n        }\n\n        const record = value as { steps?: unknown; summary?: unknown };\n\n        if (!Array.isArray(record.steps) || record.steps.length === 0) {\n          return { issues: [{ message: \"plan `steps` must be a non-empty array\" }] };\n        }\n\n        const steps: PlannerStep[] = [];\n\n        for (const raw of record.steps) {\n          const normalized = normalizeStep(raw);\n\n          if (!normalized) {\n            return {\n              issues: [{ message: \"each plan step must carry a string `capability` and `input`\" }],\n            };\n          }\n\n          steps.push(normalized);\n        }\n\n        const summary = typeof record.summary === \"string\" ? record.summary : undefined;\n\n        return { value: summary !== undefined ? { steps, summary } : { steps } };\n      },\n    } as StandardSchemaV1<PlannerPlan>[\"~standard\"] & {\n      jsonSchema: { input: () => Record<string, unknown> };\n    },\n  };\n}\n\n/** Per-step JSON Schema object — one capability dispatch. */\nfunction stepItemsSchema(capabilityNames: string[]): Record<string, unknown> {\n  return {\n    type: \"object\",\n    properties: {\n      id: {\n        type: [\"string\", \"null\"],\n        description: \"Stable step id, referenced by dependsOn.\",\n      },\n      capability: {\n        type: \"string\",\n        enum: capabilityNames,\n        description: \"Name of the capability to dispatch for this step.\",\n      },\n      input: {\n        type: \"string\",\n        description: \"Concrete input passed to the capability's execute().\",\n      },\n      reason: { type: [\"string\", \"null\"], description: \"Why this step exists.\" },\n      dependsOn: {\n        type: [\"array\", \"null\"],\n        items: { type: \"string\" },\n        description: \"Ids of steps this one conceptually follows.\",\n      },\n    },\n    // Strict mode: every property required; the genuinely-optional ones\n    // (id / reason / dependsOn) are nullable. `validate()` treats null and\n    // missing identically, so a model emitting `null` round-trips fine.\n    required: [\"id\", \"capability\", \"input\", \"reason\", \"dependsOn\"],\n    additionalProperties: false,\n  };\n}\n\n/**\n * Coerce one raw step object into a {@link PlannerStep}, returning\n * `undefined` when the mandatory `capability` / `input` strings are\n * missing. Optional fields are copied only when well-typed.\n */\nfunction normalizeStep(raw: unknown): PlannerStep | undefined {\n  if (!raw || typeof raw !== \"object\") {\n    return undefined;\n  }\n\n  const record = raw as {\n    id?: unknown;\n    capability?: unknown;\n    input?: unknown;\n    reason?: unknown;\n    dependsOn?: unknown;\n  };\n\n  if (typeof record.capability !== \"string\" || record.capability.length === 0) {\n    return undefined;\n  }\n\n  if (typeof record.input !== \"string\") {\n    return undefined;\n  }\n\n  const step: PlannerStep = {\n    capability: record.capability,\n    input: record.input,\n  };\n\n  if (typeof record.id === \"string\") {\n    step.id = record.id;\n  }\n\n  if (typeof record.reason === \"string\") {\n    step.reason = record.reason;\n  }\n\n  if (Array.isArray(record.dependsOn) && record.dependsOn.every((entry) => typeof entry === \"string\")) {\n    step.dependsOn = record.dependsOn as string[];\n  }\n\n  return step;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,WACd,iBACA,UAC+B;CAU/B,MAAM,aAAa;EACjB,MAAM;EACN,YAAY;GACV,SAAS;IACP,MAAM,CAAC,UAAU,MAAM;IACvB,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;IACb,OAAO,gBAAgB,eAAe;GACxC;EACF;EACA,UAAU,CAAC,WAAW,OAAO;EAC7B,sBAAsB;CACxB;CAEA,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,YAAY,EACV,aAAa,WACf;EACA,SAAS,OAAsD;GAC7D,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAAE;GAG3D,MAAM,SAAS;GAEf,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,KAAK,OAAO,MAAM,WAAW,GAC1D,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yCAAyC,CAAC,EAAE;GAG3E,MAAM,QAAuB,CAAC;GAE9B,KAAK,MAAM,OAAO,OAAO,OAAO;IAC9B,MAAM,aAAa,cAAc,GAAG;IAEpC,IAAI,CAAC,YACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,8DAA8D,CAAC,EACrF;IAGF,MAAM,KAAK,UAAU;GACvB;GAEA,MAAM,UAAU,OAAO,OAAO,YAAY,WAAW,OAAO,UAAU;GAEtE,OAAO,EAAE,OAAO,YAAY,SAAY;IAAE;IAAO;GAAQ,IAAI,EAAE,MAAM,EAAE;EACzE;CACF,EAGF;AACF;;AAGA,SAAS,gBAAgB,iBAAoD;CAC3E,OAAO;EACL,MAAM;EACN,YAAY;GACV,IAAI;IACF,MAAM,CAAC,UAAU,MAAM;IACvB,aAAa;GACf;GACA,YAAY;IACV,MAAM;IACN,MAAM;IACN,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;GACf;GACA,QAAQ;IAAE,MAAM,CAAC,UAAU,MAAM;IAAG,aAAa;GAAwB;GACzE,WAAW;IACT,MAAM,CAAC,SAAS,MAAM;IACtB,OAAO,EAAE,MAAM,SAAS;IACxB,aAAa;GACf;EACF;EAIA,UAAU;GAAC;GAAM;GAAc;GAAS;GAAU;EAAW;EAC7D,sBAAsB;CACxB;AACF;;;;;;AAOA,SAAS,cAAc,KAAuC;CAC5D,IAAI,CAAC,OAAO,OAAO,QAAQ,UACzB;CAGF,MAAM,SAAS;CAQf,IAAI,OAAO,OAAO,eAAe,YAAY,OAAO,WAAW,WAAW,GACxE;CAGF,IAAI,OAAO,OAAO,UAAU,UAC1B;CAGF,MAAM,OAAoB;EACxB,YAAY,OAAO;EACnB,OAAO,OAAO;CAChB;CAEA,IAAI,OAAO,OAAO,OAAO,UACvB,KAAK,KAAK,OAAO;CAGnB,IAAI,OAAO,OAAO,WAAW,UAC3B,KAAK,SAAS,OAAO;CAGvB,IAAI,MAAM,QAAQ,OAAO,SAAS,KAAK,OAAO,UAAU,OAAO,UAAU,OAAO,UAAU,QAAQ,GAChG,KAAK,YAAY,OAAO;CAG1B,OAAO;AACT"}