@warlock.js/ai 4.1.1

package/esm/supervisor/signature.mjs

@@ -0,0 +1,89 @@
+//#region ../../@warlock.js/ai/src/supervisor/signature.ts
+/**
+* Deterministic structural fingerprint of a supervisor definition.
+* Persisted on every snapshot so `resume()` can detect drift between
+* the saved run and the current definition. Covers:
+*
+* - Supervisor name.
+* - Every intent key + its resolved description + the underlying
+*   unit's stable identity (agent name, workflow name + signature,
+*   or `"callback"` marker for dev-callback intents).
+* - Router agent's name (if the supervisor uses LLM routing).
+* - Whether a deterministic `route` callback is configured (but not
+*   its contents — route callbacks are code, not data).
+* - Whether an `evaluate` callback is configured.
+* - `initialAgent` when set.
+* - `maxIterations` (a semantic shape change, not a cosmetic one).
+*
+* Does NOT cover: system prompt text, logger, store identity, per-
+* event handlers — all runtime knobs that don't change the shape of
+* a resumable run.
+*/
+function computeSignature(config, entries) {
+	const intentsFingerprint = [...entries.entries()].sort(([a], [b]) => a.localeCompare(b)).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,
+		c: resolveClassifierFingerprint(config.classifier)
+	};
+	return hash(JSON.stringify(fingerprint));
+}
+function resolveRouterName(router) {
+	if (!router) return null;
+	if (typeof router.execute === "function") return router.name ?? null;
+	return router.agent?.name ?? null;
+}
+function resolveClassifierFingerprint(classifier) {
+	if (!classifier) return null;
+	if (typeof classifier === "function") return { t: "callback" };
+	if (typeof classifier.execute === "function") return {
+		t: "agent",
+		n: classifier.name ?? null
+	};
+	if (typeof classifier.run === "function") return { t: "callback" };
+	if (typeof classifier.agent?.execute === "function") return {
+		t: "agent",
+		n: classifier.agent?.name ?? null
+	};
+	return { t: "unknown" };
+}
+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 — same hash `workflow/signature.ts` uses. 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 { computeSignature };
+//# sourceMappingURL=signature.mjs.map

package/esm/supervisor/signature.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/signature.ts"],"sourcesContent":["import { ClassifierAgentEntry, ClassifierRunEntry } from \"../contracts\";\nimport type { SupervisorConfig } from \"../contracts/supervisor/supervisor-config.type\";\nimport type { ResolvedIntentEntry } from \"./entries\";\n\n/**\n * Deterministic structural fingerprint of a supervisor definition.\n * Persisted on every snapshot so `resume()` can detect drift between\n * the saved run and the current definition. Covers:\n *\n * - Supervisor name.\n * - Every intent key + its resolved description + the underlying\n *   unit's stable identity (agent name, workflow name + signature,\n *   or `\"callback\"` marker for dev-callback intents).\n * - Router agent's name (if the supervisor uses LLM routing).\n * - Whether a deterministic `route` callback is configured (but not\n *   its contents — route callbacks are code, not data).\n * - Whether an `evaluate` callback is configured.\n * - `initialAgent` when set.\n * - `maxIterations` (a semantic shape change, not a cosmetic one).\n *\n * Does NOT cover: system prompt text, logger, store identity, per-\n * event handlers — all runtime knobs that don't change the shape of\n * a resumable run.\n */\nexport function computeSignature(\n  config: SupervisorConfig<unknown>,\n  entries: Map<string, ResolvedIntentEntry>,\n): string {\n  const intentsFingerprint = [...entries.entries()]\n    .sort(([a], [b]) => a.localeCompare(b))\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    // Phase 7 / decisions §37 — classifier is part of structural identity.\n    // Resume drift detection notices when the classifier swap changes\n    // routing semantics. Same fingerprint shape as router (agent name\n    // when applicable; \"callback\" marker for callback form).\n    c: resolveClassifierFingerprint(config.classifier),\n  };\n\n  return hash(JSON.stringify(fingerprint));\n}\n\nfunction resolveRouterName(router: SupervisorConfig<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\nfunction resolveClassifierFingerprint(\n  classifier: SupervisorConfig<unknown>[\"classifier\"],\n): unknown {\n  if (!classifier) {\n    return null;\n  }\n\n  if (typeof classifier === \"function\") {\n    return { t: \"callback\" };\n  }\n\n  if (typeof (classifier as { execute?: unknown }).execute === \"function\") {\n    return { t: \"agent\", n: (classifier as { name?: string }).name ?? null };\n  }\n\n  if (typeof (classifier as ClassifierRunEntry).run === \"function\") {\n    return { t: \"callback\" };\n  }\n\n  if (typeof (classifier as ClassifierAgentEntry).agent?.execute === \"function\") {\n    return {\n      t: \"agent\",\n      n: (classifier as ClassifierAgentEntry).agent?.name ?? null,\n    };\n  }\n\n  return { t: \"unknown\" };\n}\n\nfunction fingerprintUnit(entry: ResolvedIntentEntry): unknown {\n  if (entry.type === \"callback\") {\n    // Callbacks are dev code — fingerprint the type + intent name\n    // only (the closure itself can't be hashed deterministically).\n    // Drift detection covers add/remove/rename of callback intents,\n    // not edits to the function body. Same trade-off as `route`.\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 — same hash `workflow/signature.ts` uses. Deterministic,\n * no crypto dependency, 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":";;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,iBACd,QACA,SACQ;CACR,MAAM,qBAAqB,CAAC,GAAG,QAAQ,QAAQ,CAAC,EAC7C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,EACrC,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;EAK3B,GAAG,6BAA6B,OAAO,UAAU;CACnD;CAEA,OAAO,KAAK,KAAK,UAAU,WAAW,CAAC;AACzC;AAEA,SAAS,kBAAkB,QAA4D;CACrF,IAAI,CAAC,QACH,OAAO;CAGT,IAAI,OAAQ,OAAiC,YAAY,YACvD,OAAQ,OAA6B,QAAQ;CAG/C,OAAQ,OAAyC,OAAO,QAAQ;AAClE;AAEA,SAAS,6BACP,YACS;CACT,IAAI,CAAC,YACH,OAAO;CAGT,IAAI,OAAO,eAAe,YACxB,OAAO,EAAE,GAAG,WAAW;CAGzB,IAAI,OAAQ,WAAqC,YAAY,YAC3D,OAAO;EAAE,GAAG;EAAS,GAAI,WAAiC,QAAQ;CAAK;CAGzE,IAAI,OAAQ,WAAkC,QAAQ,YACpD,OAAO,EAAE,GAAG,WAAW;CAGzB,IAAI,OAAQ,WAAoC,OAAO,YAAY,YACjE,OAAO;EACL,GAAG;EACH,GAAI,WAAoC,OAAO,QAAQ;CACzD;CAGF,OAAO,EAAE,GAAG,UAAU;AACxB;AAEA,SAAS,gBAAgB,OAAqC;CAC5D,IAAI,MAAM,SAAS,YAKjB,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;;;;;AAMA,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,EAAE,SAAS,GAAG,GAAG;AACvC"}

package/esm/supervisor/snapshot.d.mts

@@ -0,0 +1,54 @@
+import { IterationSnapshot } from "../contracts/supervisor/iteration-snapshot.type.mjs";
+import { SupervisorInput } from "../contracts/supervisor/supervisor-input.type.mjs";
+import { SupervisorConfig } from "../contracts/supervisor/supervisor-config.type.mjs";
+import { SupervisorResumeOptions } from "../contracts/supervisor/supervisor-execute-options.type.mjs";
+import { SupervisorSnapshot, SupervisorSnapshotStatus } from "../contracts/supervisor/supervisor-snapshot.type.mjs";
+
+//#region ../../@warlock.js/ai/src/supervisor/snapshot.d.ts
+type PersistParams = {
+  config: SupervisorConfig<unknown>;
+  signature: string;
+  runId: string;
+  input: SupervisorInput;
+  startedAt: string;
+  iteration: number;
+  snapshots: IterationSnapshot[];
+  status: SupervisorSnapshotStatus;
+};
+type PersistOutcome = {
+  ok: true;
+} | {
+  ok: false;
+  error: unknown;
+};
+/**
+ * Write the current run state to the resolved snapshot store. No-op
+ * (ok) when neither the supervisor's `snapshotStore` nor the global
+ * `defaultStore` is configured. Failures are returned as
+ * `{ ok: false }` rather than thrown so the engine can surface them
+ * via events/logs without aborting the run — callers decide whether
+ * a failed checkpoint is fatal.
+ */
+declare function persistSupervisorSnapshot(params: PersistParams): Promise<PersistOutcome>;
+/**
+ * Load a persisted snapshot for `resume()` and run the drift check.
+ * Throws `SupervisorFailedError` when no store is configured or when
+ * the run is missing; throws `SupervisorDriftError` when the stored
+ * signature doesn't match the current definition (unless `force` is
+ * set).
+ */
+declare function loadSnapshotForResume(params: {
+  config: SupervisorConfig<unknown>;
+  signature: string;
+  runId: string;
+  options?: SupervisorResumeOptions;
+}): Promise<SupervisorSnapshot>;
+/**
+ * Canonical key shape used in the KVStore. Prefixed so supervisor
+ * snapshots don't collide with workflow / session snapshots in a
+ * shared store.
+ */
+declare function snapshotKey(runId: string): string;
+//#endregion
+export { loadSnapshotForResume, persistSupervisorSnapshot, snapshotKey };
+//# sourceMappingURL=snapshot.d.mts.map

package/esm/supervisor/snapshot.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/snapshot.ts"],"mappings":";;;;;;;KAoBY,aAAA;EACV,MAAA,EAAQ,gBAAA;EACR,SAAA;EACA,KAAA;EACA,KAAA,EAAO,eAAA;EACP,SAAA;EACA,SAAA;EACA,SAAA,EAAW,iBAAA;EACX,MAAA,EAAQ,wBAAA;AAAA;AAAA,KAGE,cAAA;EAAmB,EAAA;AAAA;EAAe,EAAA;EAAW,KAAA;AAAA;;;;;;;;;iBAUnC,yBAAA,CACpB,MAAA,EAAQ,aAAA,GACP,OAAA,CAAQ,cAAA;AAZX;;;;;;;AAAA,iBA+CsB,qBAAA,CAAsB,MAAA;EAC1C,MAAA,EAAQ,gBAAA;EACR,SAAA;EACA,KAAA;EACA,OAAA,GAAU,uBAAA;AAAA,IACR,OAAA,CAAQ,kBAAA;;;;;;iBAuCI,WAAA,CAAY,KAAa"}

package/esm/supervisor/snapshot.mjs

@@ -0,0 +1,77 @@
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import { SupervisorDriftError } from "../errors/supervisor-drift-error.mjs";
+import "../errors/index.mjs";
+import { resolveDefaultStore } from "../config.mjs";
+
+//#region ../../@warlock.js/ai/src/supervisor/snapshot.ts
+/**
+* Resolve the effective snapshot store: the supervisor's own
+* `snapshotStore` field wins; absent that, fall back to the global
+* default set via `ai.config({ defaultStore })`.
+*/
+function resolveSnapshotStore(config) {
+	return config.snapshotStore ?? resolveDefaultStore();
+}
+/**
+* Write the current run state to the resolved snapshot store. No-op
+* (ok) when neither the supervisor's `snapshotStore` nor the global
+* `defaultStore` is configured. Failures are returned as
+* `{ ok: false }` rather than thrown so the engine can surface them
+* via events/logs without aborting the run — callers decide whether
+* a failed checkpoint is fatal.
+*/
+async function persistSupervisorSnapshot(params) {
+	const store = resolveSnapshotStore(params.config);
+	if (!store) return { ok: true };
+	const snapshot = {
+		runId: params.runId,
+		supervisorName: params.config.name,
+		signature: params.signature,
+		input: params.input,
+		iteration: params.iteration,
+		snapshots: params.snapshots,
+		status: params.status,
+		startedAt: params.startedAt,
+		savedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	try {
+		await store.set(snapshotKey(params.runId), snapshot);
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+/**
+* Load a persisted snapshot for `resume()` and run the drift check.
+* Throws `SupervisorFailedError` when no store is configured or when
+* the run is missing; throws `SupervisorDriftError` when the stored
+* signature doesn't match the current definition (unless `force` is
+* set).
+*/
+async function loadSnapshotForResume(params) {
+	const store = resolveSnapshotStore(params.config);
+	if (!store) throw new SupervisorFailedError(`supervisor "${params.config.name}" has no store configured — set \`snapshotStore\` on the config or call \`ai.config({ defaultStore })\` at boot before calling resume()`, { context: { runId: params.runId } });
+	const snapshot = await store.get(snapshotKey(params.runId)) ?? null;
+	if (!snapshot) throw new SupervisorFailedError(`supervisor "${params.config.name}": no snapshot for runId "${params.runId}"`, { context: { runId: params.runId } });
+	if (!params.options?.force && snapshot.signature !== params.signature) throw new SupervisorDriftError(`supervisor "${params.config.name}" signature drift on resume`, {
+		savedSignature: snapshot.signature,
+		currentSignature: params.signature,
+		runId: params.runId
+	});
+	return snapshot;
+}
+/**
+* Canonical key shape used in the KVStore. Prefixed so supervisor
+* snapshots don't collide with workflow / session snapshots in a
+* shared store.
+*/
+function snapshotKey(runId) {
+	return `supervisor:${runId}`;
+}
+
+//#endregion
+export { loadSnapshotForResume, persistSupervisorSnapshot, snapshotKey };
+//# sourceMappingURL=snapshot.mjs.map

package/esm/supervisor/snapshot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/snapshot.ts"],"sourcesContent":["import { resolveDefaultStore } from \"../config\";\nimport type { IterationSnapshot } from \"../contracts/supervisor/iteration-snapshot.type\";\nimport type { SupervisorConfig } from \"../contracts/supervisor/supervisor-config.type\";\nimport type { SupervisorResumeOptions } from \"../contracts/supervisor/supervisor-execute-options.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport type {\n  SupervisorSnapshot,\n  SupervisorSnapshotStatus,\n} from \"../contracts/supervisor/supervisor-snapshot.type\";\nimport { SupervisorDriftError, SupervisorFailedError } from \"../errors\";\n\n/**\n * Resolve the effective snapshot store: the supervisor's own\n * `snapshotStore` field wins; absent that, fall back to the global\n * default set via `ai.config({ defaultStore })`.\n */\nfunction resolveSnapshotStore(config: SupervisorConfig<unknown>) {\n  return config.snapshotStore ?? resolveDefaultStore();\n}\n\nexport type PersistParams = {\n  config: SupervisorConfig<unknown>;\n  signature: string;\n  runId: string;\n  input: SupervisorInput;\n  startedAt: string;\n  iteration: number;\n  snapshots: IterationSnapshot[];\n  status: SupervisorSnapshotStatus;\n};\n\nexport type PersistOutcome = { ok: true } | { ok: false; error: unknown };\n\n/**\n * Write the current run state to the resolved snapshot store. No-op\n * (ok) when neither the supervisor's `snapshotStore` nor the global\n * `defaultStore` is configured. Failures are returned as\n * `{ ok: false }` rather than thrown so the engine can surface them\n * via events/logs without aborting the run — callers decide whether\n * a failed checkpoint is fatal.\n */\nexport async function persistSupervisorSnapshot(\n  params: PersistParams,\n): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.config);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  const snapshot: SupervisorSnapshot = {\n    runId: params.runId,\n    supervisorName: params.config.name,\n    signature: params.signature,\n    input: params.input,\n    iteration: params.iteration,\n    snapshots: params.snapshots,\n    status: params.status,\n    startedAt: params.startedAt,\n    savedAt: new Date().toISOString(),\n  };\n\n  try {\n    await store.set(snapshotKey(params.runId), snapshot);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Load a persisted snapshot for `resume()` and run the drift check.\n * Throws `SupervisorFailedError` when no store is configured or when\n * the run is missing; throws `SupervisorDriftError` when the stored\n * signature doesn't match the current definition (unless `force` is\n * set).\n */\nexport async function loadSnapshotForResume(params: {\n  config: SupervisorConfig<unknown>;\n  signature: string;\n  runId: string;\n  options?: SupervisorResumeOptions;\n}): Promise<SupervisorSnapshot> {\n  const store = resolveSnapshotStore(params.config);\n\n  if (!store) {\n    throw new SupervisorFailedError(\n      `supervisor \"${params.config.name}\" has no store configured — set \\`snapshotStore\\` on the config or call \\`ai.config({ defaultStore })\\` at boot before calling resume()`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  const snapshot =\n    (await store.get<SupervisorSnapshot>(snapshotKey(params.runId))) ?? null;\n\n  if (!snapshot) {\n    throw new SupervisorFailedError(\n      `supervisor \"${params.config.name}\": no snapshot for runId \"${params.runId}\"`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  if (!params.options?.force && snapshot.signature !== params.signature) {\n    throw new SupervisorDriftError(\n      `supervisor \"${params.config.name}\" signature drift on resume`,\n      {\n        savedSignature: snapshot.signature,\n        currentSignature: params.signature,\n        runId: params.runId,\n      },\n    );\n  }\n\n  return snapshot;\n}\n\n/**\n * Canonical key shape used in the KVStore. Prefixed so supervisor\n * snapshots don't collide with workflow / session snapshots in a\n * shared store.\n */\nexport function snapshotKey(runId: string): string {\n  return `supervisor:${runId}`;\n}\n"],"mappings":";;;;;;;;;;;AAgBA,SAAS,qBAAqB,QAAmC;CAC/D,OAAO,OAAO,iBAAiB,oBAAoB;AACrD;;;;;;;;;AAuBA,eAAsB,0BACpB,QACyB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,MAAM;CAEhD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,MAAM,WAA+B;EACnC,OAAO,OAAO;EACd,gBAAgB,OAAO,OAAO;EAC9B,WAAW,OAAO;EAClB,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,WAAW,OAAO;EAClB,QAAQ,OAAO;EACf,WAAW,OAAO;EAClB,0BAAS,IAAI,KAAK,GAAE,YAAY;CAClC;CAEA,IAAI;EACF,MAAM,MAAM,IAAI,YAAY,OAAO,KAAK,GAAG,QAAQ;EAEnD,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;;;AASA,eAAsB,sBAAsB,QAKZ;CAC9B,MAAM,QAAQ,qBAAqB,OAAO,MAAM;CAEhD,IAAI,CAAC,OACH,MAAM,IAAI,sBACR,eAAe,OAAO,OAAO,KAAK,0IAClC,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,MAAM,WACH,MAAM,MAAM,IAAwB,YAAY,OAAO,KAAK,CAAC,KAAM;CAEtE,IAAI,CAAC,UACH,MAAM,IAAI,sBACR,eAAe,OAAO,OAAO,KAAK,4BAA4B,OAAO,MAAM,IAC3E,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,IAAI,CAAC,OAAO,SAAS,SAAS,SAAS,cAAc,OAAO,WAC1D,MAAM,IAAI,qBACR,eAAe,OAAO,OAAO,KAAK,8BAClC;EACE,gBAAgB,SAAS;EACzB,kBAAkB,OAAO;EACzB,OAAO,OAAO;CAChB,CACF;CAGF,OAAO;AACT;;;;;;AAOA,SAAgB,YAAY,OAAuB;CACjD,OAAO,cAAc;AACvB"}

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

@@ -0,0 +1,29 @@
+import { StreamContract } from "../contracts/stream/stream.contract.mjs";
+import { SupervisorStreamEvent } from "../contracts/supervisor/supervisor-stream-event.type.mjs";
+
+//#region ../../@warlock.js/ai/src/supervisor/supervisor-stream.d.ts
+/**
+ * Internal async-queue controller driving `supervisor.stream()`.
+ * Mirrors `StreamController` from `agent-stream.ts` — same
+ * producer/consumer pipe, same semantics, parameterized by the
+ * supervisor event union and terminal result type.
+ */
+type SupervisorStreamController<TResult> = {
+  push(event: SupervisorStreamEvent): void;
+  end(result: TResult): void;
+  fail(error: Error): void;
+};
+/**
+ * Factory mirroring `createAgentStream`. Returns a paired
+ * `{ controller, stream }` — the `SupervisorExecution` pushes events
+ * into the controller while the caller iterates (or awaits `.result`)
+ * on the stream side. See `agent-stream.ts` for the full role
+ * description.
+ */
+declare function createSupervisorStream<TResult>(): {
+  controller: SupervisorStreamController<TResult>;
+  stream: StreamContract<TResult, SupervisorStreamEvent>;
+};
+//#endregion
+export { SupervisorStreamController, createSupervisorStream };
+//# sourceMappingURL=supervisor-stream.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-stream.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/supervisor-stream.ts"],"mappings":";;;;;AAaA;;;;;KAAY,0BAAA;EACV,IAAA,CAAK,KAAA,EAAO,qBAAA;EACZ,GAAA,CAAI,MAAA,EAAQ,OAAA;EACZ,IAAA,CAAK,KAAA,EAAO,KAAA;AAAA;;;;;;;;iBAeE,sBAAA,SAAA,CAAA;EACd,UAAA,EAAY,0BAAA,CAA2B,OAAA;EACvC,MAAA,EAAQ,cAAA,CAAe,OAAA,EAAS,qBAAA;AAAA"}

package/esm/supervisor/supervisor-stream.mjs

@@ -0,0 +1,89 @@
+//#region ../../@warlock.js/ai/src/supervisor/supervisor-stream.ts
+/**
+* Factory mirroring `createAgentStream`. Returns a paired
+* `{ controller, stream }` — the `SupervisorExecution` pushes events
+* into the controller while the caller iterates (or awaits `.result`)
+* on the stream side. See `agent-stream.ts` for the full role
+* description.
+*/
+function createSupervisorStream() {
+	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 { createSupervisorStream };
+//# sourceMappingURL=supervisor-stream.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-stream.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/supervisor-stream.ts"],"sourcesContent":["import type { StreamContract } from \"../contracts/stream/stream.contract\";\nimport type { SupervisorStreamEvent } from \"../contracts/supervisor/supervisor-stream-event.type\";\n\n// Re-export so internal callers that already imported from this file\n// keep working unchanged. Canonical home is the contracts barrel.\nexport type { SupervisorStreamEvent };\n\n/**\n * Internal async-queue controller driving `supervisor.stream()`.\n * Mirrors `StreamController` from `agent-stream.ts` — same\n * producer/consumer pipe, same semantics, parameterized by the\n * supervisor event union and terminal result type.\n */\nexport type SupervisorStreamController<TResult> = {\n  push(event: SupervisorStreamEvent): void;\n  end(result: TResult): void;\n  fail(error: Error): void;\n};\n\ntype PendingRead = {\n  resolve(value: IteratorResult<SupervisorStreamEvent>): void;\n  reject(error: Error): void;\n};\n\n/**\n * Factory mirroring `createAgentStream`. Returns a paired\n * `{ controller, stream }` — the `SupervisorExecution` pushes events\n * into the controller while the caller iterates (or awaits `.result`)\n * on the stream side. See `agent-stream.ts` for the full role\n * description.\n */\nexport function createSupervisorStream<TResult>(): {\n  controller: SupervisorStreamController<TResult>;\n  stream: StreamContract<TResult, SupervisorStreamEvent>;\n} {\n  const queue: SupervisorStreamEvent[] = [];\n  const pending: PendingRead[] = [];\n  const handlers = new Map<string, (event: SupervisorStreamEvent) => 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: SupervisorStreamController<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 supervisor.\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<SupervisorStreamEvent> = {\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<SupervisorStreamEvent>>(\n        (resolve, reject) => {\n          pending.push({ resolve, reject });\n        },\n      );\n    },\n  };\n\n  // The `StreamContract<TResult>` shape is shared across primitives —\n  // it types `on()` over the generic `StreamEvent` union (agent\n  // events). Supervisor events are a distinct discriminated union\n  // with the same `type`-keyed shape, so we satisfy the contract via\n  // a structural cast — handlers see the supervisor events at their\n  // correct narrowed types.\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: SupervisorStreamEvent) => void);\n        }\n      }\n\n      return stream;\n    },\n    [Symbol.asyncIterator]() {\n      return iterator;\n    },\n  } as StreamContract<TResult, SupervisorStreamEvent>;\n\n  return { controller, stream };\n}\n"],"mappings":";;;;;;;;AA+BA,SAAgB,yBAGd;CACA,MAAM,QAAiC,CAAC;CACxC,MAAM,UAAyB,CAAC;CAChC,MAAM,2BAAW,IAAI,IAAoD;CAEzE,IAAI,SAAS;CACb,IAAI;CACJ,IAAI;CACJ,IAAI;CAEJ,MAAM,SAAS,IAAI,SAAkB,SAAS,WAAW;EACvD,gBAAgB;EAChB,eAAe;CACjB,CAAC;CAED,MAAM,aAAkD;EACtD,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,GAAG,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,GAAG,OAAO,KAAK;EAEjC;CACF;CAEA,MAAM,WAAiD,EACrD,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;CAQA,MAAM,SAAS;EACb;EACA,GAAG,YAAY;GACb,KAAK,MAAM,CAAC,KAAK,YAAY,OAAO,QAAQ,UAAU,GACpD,IAAI,SACF,SAAS,IAAI,KAAK,OAAiD;GAIvE,OAAO;EACT;EACA,CAAC,OAAO,iBAAiB;GACvB,OAAO;EACT;CACF;CAEA,OAAO;EAAE;EAAY;CAAO;AAC9B"}

package/esm/supervisor/supervisor.d.mts

@@ -0,0 +1,27 @@
+import { SupervisorIntentValue } from "../contracts/supervisor/intent-entry.type.mjs";
+import { SupervisorConfig } from "../contracts/supervisor/supervisor-config.type.mjs";
+import { SupervisorContract } from "../contracts/supervisor/supervisor.contract.mjs";
+
+//#region ../../@warlock.js/ai/src/supervisor/supervisor.d.ts
+/**
+ * `ai.supervisor(config)` — construct a `SupervisorContract`. Validates
+ * the config at author time (throws `SupervisorFailedError` on bad
+ * shape), resolves agent entries, computes a stable structural
+ * signature, wires the three-tier event emitter, and returns an
+ * instance that satisfies `ExecutableContract` so it can compose into
+ * tools, outer agents, and (future) orchestrators uniformly.
+ *
+ * @example
+ * const support = ai.supervisor({
+ *   name: "customer-support",
+ *   router: routerAgent,
+ *   intents: { triage, orderLookup, billingLookup, resolver },
+ *   evaluate: (ctx) => ctx.result.resolver?.output ? { satisfied: true } : undefined,
+ *   output: z.object({ response: z.string(), refund: z.boolean() }),
+ *   maxIterations: 6,
+ * });
+ */
+declare function supervisor<TOutput = unknown, TState = TOutput, TIntents extends Record<string, SupervisorIntentValue> = Record<string, SupervisorIntentValue>, TArtifacts = Record<string, unknown>>(config: SupervisorConfig<TOutput, TState, TIntents, TArtifacts>): SupervisorContract<TOutput>;
+//#endregion
+export { supervisor };
+//# sourceMappingURL=supervisor.d.mts.map

package/esm/supervisor/supervisor.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/supervisor.ts"],"mappings":";;;;;;;AA8CA;;;;;;;;;;;;;;;;iBAAgB,UAAA,6BAEL,OAAA,mBACQ,MAAA,SAAe,qBAAA,IAAyB,MAAA,SAAe,qBAAA,gBAC3D,MAAA,kBAAA,CACb,MAAA,EAAQ,gBAAA,CAAiB,OAAA,EAAS,MAAA,EAAQ,QAAA,EAAU,UAAA,IAAc,kBAAA,CAAmB,OAAA"}

package/esm/supervisor/supervisor.mjs

@@ -0,0 +1,138 @@
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import "../errors/index.mjs";
+import { asTool } from "./as-tool.mjs";
+import { SupervisorEmitter } from "./emitter.mjs";
+import { assertRouterDescriptions, resolveIntentEntries } from "./entries.mjs";
+import { loadSnapshotForResume } from "./snapshot.mjs";
+import { SupervisorExecution } from "./execution.mjs";
+import { computeSignature } from "./signature.mjs";
+import { createSupervisorStream } from "./supervisor-stream.mjs";
+
+//#region ../../@warlock.js/ai/src/supervisor/supervisor.ts
+/**
+* `ai.supervisor(config)` — construct a `SupervisorContract`. Validates
+* the config at author time (throws `SupervisorFailedError` on bad
+* shape), resolves agent entries, computes a stable structural
+* signature, wires the three-tier event emitter, and returns an
+* instance that satisfies `ExecutableContract` so it can compose into
+* tools, outer agents, and (future) orchestrators uniformly.
+*
+* @example
+* const support = ai.supervisor({
+*   name: "customer-support",
+*   router: routerAgent,
+*   intents: { triage, orderLookup, billingLookup, resolver },
+*   evaluate: (ctx) => ctx.result.resolver?.output ? { satisfied: true } : undefined,
+*   output: z.object({ response: z.string(), refund: z.boolean() }),
+*   maxIterations: 6,
+* });
+*/
+function supervisor(config) {
+	validateFactoryConfig(config);
+	const entries = resolveIntentEntries(config.intents, config.name);
+	assertRouterDescriptions(config, entries);
+	if (config.initialAgent && !entries.has(config.initialAgent)) throw new SupervisorFailedError(`ai.supervisor("${config.name}"): \`initialAgent\` "${config.initialAgent}" is not a key in \`intents\``, { context: { authoring: true } });
+	const signature = computeSignature(config, entries);
+	const emitter = new SupervisorEmitter(config.on);
+	async function execute(input, options) {
+		return new SupervisorExecution({
+			config,
+			entries,
+			signature,
+			emitter,
+			input,
+			runId: options?.runId ?? generateRunId(),
+			options
+		}).run();
+	}
+	function stream(input, options) {
+		const runId = options?.runId ?? generateRunId();
+		const { controller, stream: contract } = createSupervisorStream();
+		new SupervisorExecution({
+			config,
+			entries,
+			signature,
+			emitter,
+			input,
+			runId,
+			options,
+			streamController: controller
+		}).run();
+		return contract;
+	}
+	async function resume(runId, options) {
+		const snapshot = await loadSnapshotForResume({
+			config,
+			signature,
+			runId,
+			options
+		});
+		return new SupervisorExecution({
+			config,
+			entries,
+			signature,
+			emitter,
+			input: snapshot.input,
+			runId,
+			options,
+			resumeFrom: snapshot
+		}).run();
+	}
+	const instance = {
+		name: config.name,
+		signature,
+		execute,
+		stream,
+		resume,
+		on(event, handler) {
+			return emitter.on(event, handler);
+		},
+		off(event, handler) {
+			emitter.off(event, handler);
+		},
+		asTool(options) {
+			return asTool(instance, options);
+		}
+	};
+	return instance;
+}
+/**
+* Factory-time validation. Enforces the XOR + pairing rules the design
+* locked in §2 and surfaces any violation as a typed
+* `SupervisorFailedError` tagged `authoring: true`.
+*/
+function validateFactoryConfig(config) {
+	if (!config.name || typeof config.name !== "string") throw new SupervisorFailedError("ai.supervisor: `name` is required and must be a string", { context: { authoring: true } });
+	if (!config.intents || typeof config.intents !== "object") throw new SupervisorFailedError(`ai.supervisor("${config.name}"): \`intents\` is required`, { context: { authoring: true } });
+	const hasRoute = typeof config.route === "function";
+	const hasRouter = !!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 SupervisorFailedError(`ai.supervisor("${config.name}"): \`router\` must be an agent contract or a \`{ agent, placeholders?, input? }\` entry`, { context: { authoring: true } });
+	}
+	if (hasRoute && hasRouter) throw new SupervisorFailedError(`ai.supervisor("${config.name}"): \`route\` and \`router\` are mutually exclusive — configure exactly one`, { context: { authoring: true } });
+	const hasClassifier = config.classifier !== void 0;
+	if (!hasRoute && !hasRouter && !hasClassifier) throw new SupervisorFailedError(`ai.supervisor("${config.name}"): one of \`route\`, \`router\`, or \`classifier\` is required`, { context: { authoring: true } });
+	if (hasClassifier && config.initialAgent) throw new SupervisorFailedError(`ai.supervisor("${config.name}"): \`classifier\` and \`initialAgent\` are mutually exclusive — both decide which intent runs first. Pick one.`, { context: { authoring: true } });
+	if (config.ack !== void 0) {
+		const ack = config.ack;
+		const isCallback = typeof ack === "function";
+		const isAgentEntry = typeof ack === "object" && ack !== null && typeof ack.agent?.execute === "function";
+		const isRunEntry = typeof ack === "object" && ack !== null && typeof ack.run === "function";
+		if (!isCallback && !isAgentEntry && !isRunEntry) throw new SupervisorFailedError(`ai.supervisor("${config.name}"): \`ack\` must be an \`{ agent, ... }\` entry, an \`{ run, ... }\` entry, or a bare callback function`, { context: { authoring: true } });
+		if (isAgentEntry && isRunEntry) throw new SupervisorFailedError(`ai.supervisor("${config.name}"): \`ack\` cannot declare both \`agent\` and \`run\` — pick one`, { context: { authoring: true } });
+	}
+	if (config.maxIterations !== void 0 && config.maxIterations < 1) throw new SupervisorFailedError(`ai.supervisor("${config.name}"): \`maxIterations\` must be >= 1`, { context: {
+		authoring: true,
+		maxIterations: config.maxIterations
+	} });
+}
+function generateRunId() {
+	return `sup_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+//#endregion
+export { supervisor };
+//# sourceMappingURL=supervisor.mjs.map

package/esm/supervisor/supervisor.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/supervisor.ts"],"sourcesContent":["import type { SupervisorEventMap } from \"../contracts/events/event-map.type\";\nimport type { SupervisorResult } from \"../contracts/result/supervisor-result.type\";\nimport type { StreamContract } from \"../contracts/stream/stream.contract\";\nimport type { SupervisorIntentValue } from \"../contracts/supervisor/intent-entry.type\";\nimport type {\n  SupervisorConfig,\n  SupervisorEventHandler,\n} from \"../contracts/supervisor/supervisor-config.type\";\nimport type {\n  SupervisorExecuteOptions,\n  SupervisorResumeOptions,\n} from \"../contracts/supervisor/supervisor-execute-options.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport type { SupervisorStreamEvent } from \"../contracts/supervisor/supervisor-stream-event.type\";\nimport type {\n  SupervisorAsToolOptions,\n  SupervisorContract,\n} from \"../contracts/supervisor/supervisor.contract\";\nimport { SupervisorFailedError } from \"../errors\";\nimport type { ToolContract } from \"../tool/tool\";\nimport { asTool } from \"./as-tool\";\nimport { SupervisorEmitter } from \"./emitter\";\nimport { assertRouterDescriptions, resolveIntentEntries } from \"./entries\";\nimport { SupervisorExecution } from \"./execution\";\nimport { computeSignature } from \"./signature\";\nimport { loadSnapshotForResume } from \"./snapshot\";\nimport { createSupervisorStream } from \"./supervisor-stream\";\n\n/**\n * `ai.supervisor(config)` — construct a `SupervisorContract`. Validates\n * the config at author time (throws `SupervisorFailedError` on bad\n * shape), resolves agent entries, computes a stable structural\n * signature, wires the three-tier event emitter, and returns an\n * instance that satisfies `ExecutableContract` so it can compose into\n * tools, outer agents, and (future) orchestrators uniformly.\n *\n * @example\n * const support = ai.supervisor({\n *   name: \"customer-support\",\n *   router: routerAgent,\n *   intents: { triage, orderLookup, billingLookup, resolver },\n *   evaluate: (ctx) => ctx.result.resolver?.output ? { satisfied: true } : undefined,\n *   output: z.object({ response: z.string(), refund: z.boolean() }),\n *   maxIterations: 6,\n * });\n */\nexport function supervisor<\n  TOutput = unknown,\n  TState = TOutput,\n  TIntents extends Record<string, SupervisorIntentValue> = Record<string, SupervisorIntentValue>,\n  TArtifacts = Record<string, unknown>,\n>(config: SupervisorConfig<TOutput, TState, TIntents, TArtifacts>): SupervisorContract<TOutput> {\n  validateFactoryConfig(config as unknown as SupervisorConfig<TOutput>);\n\n  const entries = resolveIntentEntries(config.intents, config.name);\n\n  assertRouterDescriptions(config as SupervisorConfig<unknown>, entries);\n\n  if (config.initialAgent && !entries.has(config.initialAgent)) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${config.name}\"): \\`initialAgent\\` \"${config.initialAgent}\" is not a key in \\`intents\\``,\n      { context: { authoring: true } },\n    );\n  }\n\n  const signature = computeSignature(config as SupervisorConfig<unknown>, entries);\n  const emitter = new SupervisorEmitter(config.on);\n\n  async function execute(\n    input: SupervisorInput,\n    options?: SupervisorExecuteOptions,\n  ): Promise<SupervisorResult<TOutput>> {\n    const runId = options?.runId ?? generateRunId();\n\n    const execution = new SupervisorExecution<TOutput>({\n      config: config as unknown as SupervisorConfig<TOutput>,\n      entries,\n      signature,\n      emitter,\n      input,\n      runId,\n      options,\n    });\n\n    return execution.run();\n  }\n\n  function stream(\n    input: SupervisorInput,\n    options?: SupervisorExecuteOptions,\n  ): StreamContract<SupervisorResult<TOutput>, SupervisorStreamEvent> {\n    const runId = options?.runId ?? generateRunId();\n    const { controller, stream: contract } = createSupervisorStream<SupervisorResult<TOutput>>();\n\n    const execution = new SupervisorExecution<TOutput>({\n      config: config as unknown as SupervisorConfig<TOutput>,\n      entries,\n      signature,\n      emitter,\n      input,\n      runId,\n      options,\n      streamController: controller,\n    });\n\n    void execution.run();\n\n    return contract;\n  }\n\n  async function resume(\n    runId: string,\n    options?: SupervisorResumeOptions,\n  ): Promise<SupervisorResult<TOutput>> {\n    const snapshot = await loadSnapshotForResume({\n      config: config as SupervisorConfig<unknown>,\n      signature,\n      runId,\n      options,\n    });\n\n    const execution = new SupervisorExecution<TOutput>({\n      config: config as unknown as SupervisorConfig<TOutput>,\n      entries,\n      signature,\n      emitter,\n      input: snapshot.input,\n      runId,\n      options,\n      resumeFrom: snapshot,\n    });\n\n    return execution.run();\n  }\n\n  const instance: SupervisorContract<TOutput> = {\n    name: config.name,\n    signature,\n    execute,\n    stream,\n    resume,\n    on<K extends keyof SupervisorEventMap>(\n      event: K,\n      handler: SupervisorEventHandler<K>,\n    ): () => void {\n      return emitter.on(event, handler);\n    },\n    off<K extends keyof SupervisorEventMap>(event: K, handler: SupervisorEventHandler<K>): void {\n      emitter.off(event, handler);\n    },\n    asTool<TToolInput = string>(\n      options: SupervisorAsToolOptions<TToolInput>,\n    ): ToolContract<TToolInput, TOutput> {\n      return asTool<TOutput, TToolInput>(instance, options);\n    },\n  };\n\n  return instance;\n}\n\n/**\n * Factory-time validation. Enforces the XOR + pairing rules the design\n * locked in §2 and surfaces any violation as a typed\n * `SupervisorFailedError` tagged `authoring: true`.\n */\nfunction validateFactoryConfig<T>(config: SupervisorConfig<T>): void {\n  if (!config.name || typeof config.name !== \"string\") {\n    throw new SupervisorFailedError(\"ai.supervisor: `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 SupervisorFailedError(`ai.supervisor(\"${config.name}\"): \\`intents\\` is required`, {\n      context: { authoring: true },\n    });\n  }\n\n  const hasRoute = typeof config.route === \"function\";\n  const hasRouter = !!config.router;\n\n  if (hasRouter) {\n    const router = config.router as { execute?: unknown } | { agent?: { execute?: unknown } };\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 SupervisorFailedError(\n        `ai.supervisor(\"${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 SupervisorFailedError(\n      `ai.supervisor(\"${config.name}\"): \\`route\\` and \\`router\\` are mutually exclusive — configure exactly one`,\n      { context: { authoring: true } },\n    );\n  }\n\n  // Phase 7 / decisions §37 — `classifier` is the iter-0 prelude;\n  // satisfies the \"must have a dispatch source\" rule on its own.\n  // Composes with router/route (classifier drives iter 0; router/route\n  // takes iter 1+). When configured alone, supervisor terminates after\n  // iter 0's branch settles.\n  const hasClassifier = config.classifier !== undefined;\n\n  if (!hasRoute && !hasRouter && !hasClassifier) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${config.name}\"): one of \\`route\\`, \\`router\\`, or \\`classifier\\` is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  // Phase 7 — classifier and initialAgent both decide what runs first.\n  // Coexistence is meaningless; throw loudly.\n  if (hasClassifier && config.initialAgent) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${config.name}\"): \\`classifier\\` and \\`initialAgent\\` are mutually exclusive — both decide which intent runs first. Pick one.`,\n      { context: { authoring: true } },\n    );\n  }\n\n  // Phase 3.4 (Q9) — evaluate now pairs with both `route` and\n  // `router`. State-driven termination is useful in either dispatch\n  // mode; the historical router-only restriction was incidental,\n  // not principled.\n\n  if (config.ack !== undefined) {\n    const ack = config.ack;\n    const isCallback = typeof ack === \"function\";\n    const isAgentEntry =\n      typeof ack === \"object\" &&\n      ack !== null &&\n      typeof (ack as { agent?: { execute?: unknown } }).agent?.execute === \"function\";\n    const isRunEntry =\n      typeof ack === \"object\" &&\n      ack !== null &&\n      typeof (ack as { run?: unknown }).run === \"function\";\n\n    if (!isCallback && !isAgentEntry && !isRunEntry) {\n      throw new SupervisorFailedError(\n        `ai.supervisor(\"${config.name}\"): \\`ack\\` must be an \\`{ agent, ... }\\` entry, an \\`{ run, ... }\\` entry, or a bare callback function`,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (isAgentEntry && isRunEntry) {\n      throw new SupervisorFailedError(\n        `ai.supervisor(\"${config.name}\"): \\`ack\\` cannot declare both \\`agent\\` and \\`run\\` — pick one`,\n        { context: { authoring: true } },\n      );\n    }\n  }\n\n  if (config.maxIterations !== undefined && config.maxIterations < 1) {\n    throw new SupervisorFailedError(\n      `ai.supervisor(\"${config.name}\"): \\`maxIterations\\` must be >= 1`,\n      { context: { authoring: true, maxIterations: config.maxIterations } },\n    );\n  }\n}\n\nfunction generateRunId(): string {\n  return `sup_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;\n}\n"],"mappings":"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"}

package/esm/system-prompt/instruction.d.mts

@@ -0,0 +1,52 @@
+import { Placeholders } from "../contracts/placeholders.type.mjs";
+import { InstructionContract } from "../contracts/system-prompt.contract.mjs";
+
+//#region ../../@warlock.js/ai/src/system-prompt/instruction.d.ts
+/**
+ * Concrete `InstructionContract` — a reusable directive block.
+ *
+ * **Role.** A single addressable prompt block representing one rule the
+ * agent must follow (`"Always respond in {{language|English}}."`). Exists
+ * as its own type so the same instruction can be shared across many
+ * prompts and agents, each render supplying its own placeholder map.
+ *
+ * **Responsibility.**
+ * - Owns: the `type: "instruction"` discriminator, the raw template text,
+ *   and the placeholder-rendering step.
+ * - Does NOT own: ordering relative to other instructions, joining with a
+ *   persona, or any surrounding prompt composition — those concerns live
+ *   in `SystemPrompt`.
+ *
+ * Users construct via the `ai.instruction()` factory — `new Instruction()`
+ * is not the public API (see §4.2 of code-style.md).
+ *
+ * @example
+ * const replyInLanguage = ai.instruction("Respond in {{language|English}}.");
+ *
+ * const prompt = ai.systemPrompt()
+ *   .persona("You are Alex.")
+ *   .instruction(replyInLanguage)
+ *   .instruction("Always include code examples.");
+ */
+declare class Instruction implements InstructionContract {
+  readonly text: string;
+  readonly type: "instruction";
+  constructor(text: string);
+  /**
+   * Substitute `{{mustache}}` placeholders in the instruction text against
+   * the supplied map. Delegates to the shared `renderPlaceholders` helper
+   * so persona / instruction / system-prompt rendering stays identical.
+   */
+  resolve(placeholders?: Placeholders): string;
+}
+/**
+ * Create an `Instruction` from raw template text.
+ *
+ * @example
+ * const replyIn = instruction("Respond in {{language|English}}.");
+ * const cite = instruction("Always cite sources inline.");
+ */
+declare function instruction(text: string): Instruction;
+//#endregion
+export { Instruction, instruction };
+//# sourceMappingURL=instruction.d.mts.map

package/esm/system-prompt/instruction.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/system-prompt/instruction.ts"],"mappings":";;;;;;AA8BA;;;;;;;;;;;;;AAY4C;AAY5C;;;;AAAsD;;;;;;cAxBzC,WAAA,YAAuB,mBAAmB;EAAA,SAGlB,IAAA;EAAA,SAFnB,IAAA;cAEmB,IAAA;;;;;;EAS5B,OAAA,CAAQ,YAAA,GAAe,YAAA;AAAA;;;;;;;;iBAYhB,WAAA,CAAY,IAAA,WAAe,WAAW"}