@warlock.js/ai 4.1.14 → 4.2.0

package/esm/supervisor/router-prompt.d.mts

@@ -2,7 +2,7 @@ import { IterationSnapshot } from "../contracts/supervisor/iteration-snapshot.ty
 import { SupervisorInput } from "../contracts/supervisor/supervisor-input.type.mjs";
 import { ResolvedIntentEntry } from "./entries.mjs";
 
-//#region ../../@warlock.js/ai/src/supervisor/router-prompt.d.ts
+//#region ../@warlock.js/ai/src/supervisor/router-prompt.d.ts
 /**
  * Build the per-turn user message the supervisor feeds to the router
  * agent. Carries everything the LLM needs to make a routing decision:

package/esm/supervisor/router-prompt.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"router-prompt.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/router-prompt.ts"],"mappings":";;;;;;;AAmBA;;;;;;;;;;;;iBAAgB,yBAAA,CAA0B,MAAA;EACxC,OAAA,EAAS,GAAA,SAAY,mBAAA;EACrB,SAAA;EACA,aAAA;EACA,UAAA,EAAY,iBAAA;EACZ,KAAA,EAAO,eAAA;EAAA;;;;;;EAOP,KAAA,GAAQ,MAAA;EAqBT;AAAA;;;;EAfC,QAAA;;;;;;;EAOA,gBAAA;;;;;;;EAOA,IAAA;AAAA"}
+{"version":3,"file":"router-prompt.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/router-prompt.ts"],"mappings":";;;;;;;AAmBA;;;;;;;;;;;;iBAAgB,yBAAA,CAA0B,MAAA;EACxC,OAAA,EAAS,GAAA,SAAY,mBAAA;EACrB,SAAA;EACA,aAAA;EACA,UAAA,EAAY,iBAAA;EACZ,KAAA,EAAO,eAAA;EAAA;;;;;;EAOP,KAAA,GAAQ,MAAA;EAqBT;AAAA;;;;EAfC,QAAA;;;;;;;EAOA,gBAAA;;;;;;;EAOA,IAAA;AAAA"}

package/esm/supervisor/router-prompt.mjs

@@ -1,6 +1,6 @@
 import { END } from "../contracts/end.type.mjs";
 
-//#region ../../@warlock.js/ai/src/supervisor/router-prompt.ts
+//#region ../@warlock.js/ai/src/supervisor/router-prompt.ts
 /**
 * Build the per-turn user message the supervisor feeds to the router
 * agent. Carries everything the LLM needs to make a routing decision:

package/esm/supervisor/router-prompt.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"router-prompt.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/router-prompt.ts"],"sourcesContent":["import { END } from \"../contracts/end.type\";\nimport type { IterationSnapshot } from \"../contracts/supervisor/iteration-snapshot.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport type { ResolvedIntentEntry } from \"./entries\";\n\n/**\n * Build the per-turn user message the supervisor feeds to the router\n * agent. Carries everything the LLM needs to make a routing decision:\n *\n * - Available intents with descriptions (so the router knows what\n *   to pick from).\n * - The reserved `END` sentinel value it can emit to terminate.\n * - Iteration counter + ceiling so the router can pace itself.\n * - Compact history of prior iterations (intent + short output clip).\n * - The supervisor's original input so the router stays anchored.\n *\n * Note the router's own `systemPrompt` is kept persistent across\n * turns — this function produces only the per-turn USER message.\n */\nexport function buildRouterContextMessage(params: {\n  entries: Map<string, ResolvedIntentEntry>;\n  iteration: number;\n  maxIterations: number;\n  iterations: IterationSnapshot[];\n  input: SupervisorInput;\n  /**\n   * Per-execute state at the START of this iteration (post-merge of\n   * the previous iteration). Rendered as a JSON snippet so the\n   * router can pick the next intent based on what's already filled\n   * in (Q14).\n   */\n  state?: Record<string, unknown>;\n  /**\n   * Reviewer feedback string from the previous iteration's evaluate\n   * verdict. Rendered as its own section so the router weighs it\n   * alongside the intent list (Q18).\n   */\n  feedback?: string;\n  /**\n   * Supervisor-level system prompt text, when configured. Surfaced at\n   * the TOP of the router's per-turn user message so the router reads\n   * team/domain context before the routing mechanics block. Skipped\n   * when the supervisor didn't configure `systemPrompt`.\n   */\n  supervisorPrompt?: string;\n  /**\n   * Resolved natural-language objective from `SupervisorConfig.goal`.\n   * Surfaced as its own labeled section near the top of the router's\n   * user message so routing decisions are objective-aware. Skipped\n   * when no goal was configured.\n   */\n  goal?: string;\n}): string {\n  const {\n    entries,\n    iteration,\n    maxIterations,\n    iterations,\n    input,\n    state,\n    feedback,\n    supervisorPrompt,\n    goal,\n  } = params;\n\n  const intentLines = [...entries.values()].map(\n    entry => `- ${entry.intent}: ${entry.description}`,\n  );\n\n  const historyLines =\n    iterations.length === 0\n      ? [\"(none yet)\"]\n      : iterations.map(snapshot => formatHistoryLine(snapshot));\n\n  const sections: string[] = [];\n\n  if (supervisorPrompt) {\n    sections.push(supervisorPrompt.trim(), \"\");\n  }\n\n  if (goal) {\n    sections.push(\"Goal:\", goal.trim(), \"\");\n  }\n\n  sections.push(\n    \"Available intents:\",\n    ...intentLines,\n    \"\",\n    \"Reserved values:\",\n    `- ${END} = terminate the run`,\n    \"\",\n    `Iteration: ${iteration + 1} / ${maxIterations}`,\n    \"\",\n    \"History:\",\n    ...historyLines,\n  );\n\n  if (state && Object.keys(state).length > 0) {\n    sections.push(\"\", \"Current state:\", safeStringify(state));\n  }\n\n  if (feedback) {\n    sections.push(\"\", `Reviewer feedback from last iteration: ${feedback}`);\n  }\n\n  const renderedInput =\n    typeof input === \"string\" ? input : safeStringify(input);\n\n  sections.push(\"\", `Original input: ${renderedInput}`);\n\n  return sections.join(\"\\n\");\n}\n\nfunction formatHistoryLine(snapshot: IterationSnapshot): string {\n  const branches = Object.entries(snapshot.result).map(\n    ([intent, branch]) => `${intent} → ${clip(branch.output)}`,\n  );\n\n  return `[${snapshot.iteration}] ${branches.join(\" | \")}`;\n}\n\nfunction clip(value: unknown, maxLength = 160): string {\n  if (value === undefined || value === null) {\n    return String(value);\n  }\n\n  const raw = typeof value === \"string\" ? value : safeStringify(value);\n\n  if (raw.length <= maxLength) {\n    return raw;\n  }\n\n  return `${raw.slice(0, maxLength - 1)}…`;\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return `[unserializable: ${typeof value}]`;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAmBA,SAAgB,0BAA0B,QAiC/B;CACT,MAAM,EACJ,SACA,WACA,eACA,YACA,OACA,OACA,UACA,kBACA,SACE;CAEJ,MAAM,cAAc,CAAC,GAAG,QAAQ,OAAO,CAAC,EAAE,KACxC,UAAS,KAAK,MAAM,OAAO,IAAI,MAAM,aACvC;CAEA,MAAM,eACJ,WAAW,WAAW,IAClB,CAAC,YAAY,IACb,WAAW,KAAI,aAAY,kBAAkB,QAAQ,CAAC;CAE5D,MAAM,WAAqB,CAAC;CAE5B,IAAI,kBACF,SAAS,KAAK,iBAAiB,KAAK,GAAG,EAAE;CAG3C,IAAI,MACF,SAAS,KAAK,SAAS,KAAK,KAAK,GAAG,EAAE;CAGxC,SAAS,KACP,sBACA,GAAG,aACH,IACA,oBACA,KAAK,IAAI,uBACT,IACA,cAAc,YAAY,EAAE,KAAK,iBACjC,IACA,YACA,GAAG,YACL;CAEA,IAAI,SAAS,OAAO,KAAK,KAAK,EAAE,SAAS,GACvC,SAAS,KAAK,IAAI,kBAAkB,cAAc,KAAK,CAAC;CAG1D,IAAI,UACF,SAAS,KAAK,IAAI,0CAA0C,UAAU;CAGxE,MAAM,gBACJ,OAAO,UAAU,WAAW,QAAQ,cAAc,KAAK;CAEzD,SAAS,KAAK,IAAI,mBAAmB,eAAe;CAEpD,OAAO,SAAS,KAAK,IAAI;AAC3B;AAEA,SAAS,kBAAkB,UAAqC;CAC9D,MAAM,WAAW,OAAO,QAAQ,SAAS,MAAM,EAAE,KAC9C,CAAC,QAAQ,YAAY,GAAG,OAAO,KAAK,KAAK,OAAO,MAAM,GACzD;CAEA,OAAO,IAAI,SAAS,UAAU,IAAI,SAAS,KAAK,KAAK;AACvD;AAEA,SAAS,KAAK,OAAgB,YAAY,KAAa;CACrD,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO,OAAO,KAAK;CAGrB,MAAM,MAAM,OAAO,UAAU,WAAW,QAAQ,cAAc,KAAK;CAEnE,IAAI,IAAI,UAAU,WAChB,OAAO;CAGT,OAAO,GAAG,IAAI,MAAM,GAAG,YAAY,CAAC,EAAE;AACxC;AAEA,SAAS,cAAc,OAAwB;CAC7C,IAAI;EACF,OAAO,KAAK,UAAU,KAAK;CAC7B,QAAQ;EACN,OAAO,oBAAoB,OAAO,MAAM;CAC1C;AACF"}
+{"version":3,"file":"router-prompt.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/router-prompt.ts"],"sourcesContent":["import { END } from \"../contracts/end.type\";\nimport type { IterationSnapshot } from \"../contracts/supervisor/iteration-snapshot.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport type { ResolvedIntentEntry } from \"./entries\";\n\n/**\n * Build the per-turn user message the supervisor feeds to the router\n * agent. Carries everything the LLM needs to make a routing decision:\n *\n * - Available intents with descriptions (so the router knows what\n *   to pick from).\n * - The reserved `END` sentinel value it can emit to terminate.\n * - Iteration counter + ceiling so the router can pace itself.\n * - Compact history of prior iterations (intent + short output clip).\n * - The supervisor's original input so the router stays anchored.\n *\n * Note the router's own `systemPrompt` is kept persistent across\n * turns — this function produces only the per-turn USER message.\n */\nexport function buildRouterContextMessage(params: {\n  entries: Map<string, ResolvedIntentEntry>;\n  iteration: number;\n  maxIterations: number;\n  iterations: IterationSnapshot[];\n  input: SupervisorInput;\n  /**\n   * Per-execute state at the START of this iteration (post-merge of\n   * the previous iteration). Rendered as a JSON snippet so the\n   * router can pick the next intent based on what's already filled\n   * in (Q14).\n   */\n  state?: Record<string, unknown>;\n  /**\n   * Reviewer feedback string from the previous iteration's evaluate\n   * verdict. Rendered as its own section so the router weighs it\n   * alongside the intent list (Q18).\n   */\n  feedback?: string;\n  /**\n   * Supervisor-level system prompt text, when configured. Surfaced at\n   * the TOP of the router's per-turn user message so the router reads\n   * team/domain context before the routing mechanics block. Skipped\n   * when the supervisor didn't configure `systemPrompt`.\n   */\n  supervisorPrompt?: string;\n  /**\n   * Resolved natural-language objective from `SupervisorConfig.goal`.\n   * Surfaced as its own labeled section near the top of the router's\n   * user message so routing decisions are objective-aware. Skipped\n   * when no goal was configured.\n   */\n  goal?: string;\n}): string {\n  const {\n    entries,\n    iteration,\n    maxIterations,\n    iterations,\n    input,\n    state,\n    feedback,\n    supervisorPrompt,\n    goal,\n  } = params;\n\n  const intentLines = [...entries.values()].map(\n    entry => `- ${entry.intent}: ${entry.description}`,\n  );\n\n  const historyLines =\n    iterations.length === 0\n      ? [\"(none yet)\"]\n      : iterations.map(snapshot => formatHistoryLine(snapshot));\n\n  const sections: string[] = [];\n\n  if (supervisorPrompt) {\n    sections.push(supervisorPrompt.trim(), \"\");\n  }\n\n  if (goal) {\n    sections.push(\"Goal:\", goal.trim(), \"\");\n  }\n\n  sections.push(\n    \"Available intents:\",\n    ...intentLines,\n    \"\",\n    \"Reserved values:\",\n    `- ${END} = terminate the run`,\n    \"\",\n    `Iteration: ${iteration + 1} / ${maxIterations}`,\n    \"\",\n    \"History:\",\n    ...historyLines,\n  );\n\n  if (state && Object.keys(state).length > 0) {\n    sections.push(\"\", \"Current state:\", safeStringify(state));\n  }\n\n  if (feedback) {\n    sections.push(\"\", `Reviewer feedback from last iteration: ${feedback}`);\n  }\n\n  const renderedInput =\n    typeof input === \"string\" ? input : safeStringify(input);\n\n  sections.push(\"\", `Original input: ${renderedInput}`);\n\n  return sections.join(\"\\n\");\n}\n\nfunction formatHistoryLine(snapshot: IterationSnapshot): string {\n  const branches = Object.entries(snapshot.result).map(\n    ([intent, branch]) => `${intent} → ${clip(branch.output)}`,\n  );\n\n  return `[${snapshot.iteration}] ${branches.join(\" | \")}`;\n}\n\nfunction clip(value: unknown, maxLength = 160): string {\n  if (value === undefined || value === null) {\n    return String(value);\n  }\n\n  const raw = typeof value === \"string\" ? value : safeStringify(value);\n\n  if (raw.length <= maxLength) {\n    return raw;\n  }\n\n  return `${raw.slice(0, maxLength - 1)}…`;\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return `[unserializable: ${typeof value}]`;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAmBA,SAAgB,0BAA0B,QAiC/B;CACT,MAAM,EACJ,SACA,WACA,eACA,YACA,OACA,OACA,UACA,kBACA,SACE;CAEJ,MAAM,cAAc,CAAC,GAAG,QAAQ,OAAO,CAAC,CAAC,CAAC,KACxC,UAAS,KAAK,MAAM,OAAO,IAAI,MAAM,aACvC;CAEA,MAAM,eACJ,WAAW,WAAW,IAClB,CAAC,YAAY,IACb,WAAW,KAAI,aAAY,kBAAkB,QAAQ,CAAC;CAE5D,MAAM,WAAqB,CAAC;CAE5B,IAAI,kBACF,SAAS,KAAK,iBAAiB,KAAK,GAAG,EAAE;CAG3C,IAAI,MACF,SAAS,KAAK,SAAS,KAAK,KAAK,GAAG,EAAE;CAGxC,SAAS,KACP,sBACA,GAAG,aACH,IACA,oBACA,KAAK,IAAI,uBACT,IACA,cAAc,YAAY,EAAE,KAAK,iBACjC,IACA,YACA,GAAG,YACL;CAEA,IAAI,SAAS,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,GACvC,SAAS,KAAK,IAAI,kBAAkB,cAAc,KAAK,CAAC;CAG1D,IAAI,UACF,SAAS,KAAK,IAAI,0CAA0C,UAAU;CAGxE,MAAM,gBACJ,OAAO,UAAU,WAAW,QAAQ,cAAc,KAAK;CAEzD,SAAS,KAAK,IAAI,mBAAmB,eAAe;CAEpD,OAAO,SAAS,KAAK,IAAI;AAC3B;AAEA,SAAS,kBAAkB,UAAqC;CAC9D,MAAM,WAAW,OAAO,QAAQ,SAAS,MAAM,CAAC,CAAC,KAC9C,CAAC,QAAQ,YAAY,GAAG,OAAO,KAAK,KAAK,OAAO,MAAM,GACzD;CAEA,OAAO,IAAI,SAAS,UAAU,IAAI,SAAS,KAAK,KAAK;AACvD;AAEA,SAAS,KAAK,OAAgB,YAAY,KAAa;CACrD,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO,OAAO,KAAK;CAGrB,MAAM,MAAM,OAAO,UAAU,WAAW,QAAQ,cAAc,KAAK;CAEnE,IAAI,IAAI,UAAU,WAChB,OAAO;CAGT,OAAO,GAAG,IAAI,MAAM,GAAG,YAAY,CAAC,EAAE;AACxC;AAEA,SAAS,cAAc,OAAwB;CAC7C,IAAI;EACF,OAAO,KAAK,UAAU,KAAK;CAC7B,QAAQ;EACN,OAAO,oBAAoB,OAAO,MAAM;CAC1C;AACF"}

package/esm/supervisor/signature.d.mts

@@ -1,7 +1,7 @@
 import { SupervisorConfig } from "../contracts/supervisor/supervisor-config.type.mjs";
 import { ResolvedIntentEntry } from "./entries.mjs";
 
-//#region ../../@warlock.js/ai/src/supervisor/signature.d.ts
+//#region ../@warlock.js/ai/src/supervisor/signature.d.ts
 /**
  * Deterministic structural fingerprint of a supervisor definition.
  * Persisted on every snapshot so `resume()` can detect drift between

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

@@ -1 +1 @@
-{"version":3,"file":"signature.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/supervisor/signature.ts"],"mappings":";;;;;;AAwBA;;;;;;;;;;;;;;AAE2C;;;;iBAF3B,gBAAA,CACd,MAAA,EAAQ,gBAAA,WACR,OAAA,EAAS,GAAA,SAAY,mBAAA"}
+{"version":3,"file":"signature.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/supervisor/signature.ts"],"mappings":";;;;;;AAwBA;;;;;;;;;;;;;;AAE2C;;;;iBAF3B,gBAAA,CACd,MAAA,EAAQ,gBAAA,WACR,OAAA,EAAS,GAAA,SAAY,mBAAA"}

package/esm/supervisor/signature.mjs

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/ai/src/supervisor/signature.ts
+//#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

package/esm/supervisor/signature.mjs.map

@@ -1 +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"}
+{"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,CAAC,CAC9C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CACtC,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,CAAC,CAAC,SAAS,GAAG,GAAG;AACvC"}

package/esm/supervisor/snapshot.d.mts

@@ -4,7 +4,7 @@ import { SupervisorConfig } from "../contracts/supervisor/supervisor-config.type
 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
+//#region ../@warlock.js/ai/src/supervisor/snapshot.d.ts
 type PersistParams = {
   config: SupervisorConfig<unknown>;
   signature: string;

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

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

@@ -3,7 +3,7 @@ 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
+//#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

package/esm/supervisor/snapshot.mjs.map

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

@@ -1,7 +1,7 @@
 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
+//#region ../@warlock.js/ai/src/supervisor/supervisor-stream.d.ts
 /**
  * Internal async-queue controller driving `supervisor.stream()`.
  * Mirrors `StreamController` from `agent-stream.ts` — same

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

@@ -1 +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"}
+{"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;EACd,UAAA,EAAY,0BAAA,CAA2B,OAAA;EACvC,MAAA,EAAQ,cAAA,CAAe,OAAA,EAAS,qBAAA;AAAA"}

package/esm/supervisor/supervisor-stream.mjs

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/ai/src/supervisor/supervisor-stream.ts
+//#region ../@warlock.js/ai/src/supervisor/supervisor-stream.ts
 /**
 * Factory mirroring `createAgentStream`. Returns a paired
 * `{ controller, stream }` — the `SupervisorExecution` pushes events

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

@@ -1 +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"}
+{"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,CAAC,EAAE,QAAQ;IAAE,OAAO;IAAW,MAAM;GAAK,CAAC;EAE7D;EAEA,KAAK,OAAO;GACV,SAAS;GACT,UAAU;GACV,aAAa,KAAK;GAElB,OAAO,QAAQ,SAAS,GACtB,QAAQ,MAAM,CAAC,EAAE,OAAO,KAAK;EAEjC;CACF;CAEA,MAAM,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

@@ -2,7 +2,7 @@ import { SupervisorIntentValue } from "../contracts/supervisor/intent-entry.type
 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
+//#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

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

@@ -1 +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"}
+{"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,mBACb,MAAA,EAAQ,gBAAA,CAAiB,OAAA,EAAS,MAAA,EAAQ,QAAA,EAAU,UAAA,IAAc,kBAAA,CAAmB,OAAA"}

package/esm/supervisor/supervisor.mjs

@@ -8,7 +8,7 @@ import { SupervisorExecution } from "./execution.mjs";
 import { computeSignature } from "./signature.mjs";
 import { createSupervisorStream } from "./supervisor-stream.mjs";
 
-//#region ../../@warlock.js/ai/src/supervisor/supervisor.ts
+//#region ../@warlock.js/ai/src/supervisor/supervisor.ts
 /**
 * `ai.supervisor(config)` — construct a `SupervisorContract`. Validates
 * the config at author time (throws `SupervisorFailedError` on bad

package/esm/supervisor/supervisor.mjs.map

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

@@ -1,7 +1,7 @@
 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
+//#region ../@warlock.js/ai/src/system-prompt/instruction.d.ts
 /**
  * Concrete `InstructionContract` — a reusable directive block.
  *

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

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

package/esm/system-prompt/instruction.mjs

@@ -1,6 +1,6 @@
 import { renderPlaceholders } from "./render-placeholders.mjs";
 
-//#region ../../@warlock.js/ai/src/system-prompt/instruction.ts
+//#region ../@warlock.js/ai/src/system-prompt/instruction.ts
 /**
 * Concrete `InstructionContract` — a reusable directive block.
 *

package/esm/system-prompt/instruction.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"instruction.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/system-prompt/instruction.ts"],"sourcesContent":["import type { Placeholders } from \"../contracts/placeholders.type\";\nimport type { InstructionContract } from \"../contracts/system-prompt.contract\";\nimport { renderPlaceholders } from \"./render-placeholders\";\n\n/**\n * Concrete `InstructionContract` — a reusable directive block.\n *\n * **Role.** A single addressable prompt block representing one rule the\n * agent must follow (`\"Always respond in {{language|English}}.\"`). Exists\n * as its own type so the same instruction can be shared across many\n * prompts and agents, each render supplying its own placeholder map.\n *\n * **Responsibility.**\n * - Owns: the `type: \"instruction\"` discriminator, the raw template text,\n *   and the placeholder-rendering step.\n * - Does NOT own: ordering relative to other instructions, joining with a\n *   persona, or any surrounding prompt composition — those concerns live\n *   in `SystemPrompt`.\n *\n * Users construct via the `ai.instruction()` factory — `new Instruction()`\n * is not the public API (see §4.2 of code-style.md).\n *\n * @example\n * const replyInLanguage = ai.instruction(\"Respond in {{language|English}}.\");\n *\n * const prompt = ai.systemPrompt()\n *   .persona(\"You are Alex.\")\n *   .instruction(replyInLanguage)\n *   .instruction(\"Always include code examples.\");\n */\nexport class Instruction implements InstructionContract {\n  public readonly type = \"instruction\" as const;\n\n  public constructor(public readonly text: string) {\n    //\n  }\n\n  /**\n   * Substitute `{{mustache}}` placeholders in the instruction text against\n   * the supplied map. Delegates to the shared `renderPlaceholders` helper\n   * so persona / instruction / system-prompt rendering stays identical.\n   */\n  public resolve(placeholders?: Placeholders): string {\n    return renderPlaceholders(this.text, placeholders);\n  }\n}\n\n/**\n * Create an `Instruction` from raw template text.\n *\n * @example\n * const replyIn = instruction(\"Respond in {{language|English}}.\");\n * const cite = instruction(\"Always cite sources inline.\");\n */\nexport function instruction(text: string): Instruction {\n  return new Instruction(text);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,IAAa,cAAb,MAAwD;CAGtD,AAAO,YAAY,AAAgB,MAAc;EAAd;cAFZ;CAIvB;;;;;;CAOA,AAAO,QAAQ,cAAqC;EAClD,OAAO,mBAAmB,KAAK,MAAM,YAAY;CACnD;AACF;;;;;;;;AASA,SAAgB,YAAY,MAA2B;CACrD,OAAO,IAAI,YAAY,IAAI;AAC7B"}
+{"version":3,"file":"instruction.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/system-prompt/instruction.ts"],"sourcesContent":["import type { Placeholders } from \"../contracts/placeholders.type\";\nimport type { InstructionContract } from \"../contracts/system-prompt.contract\";\nimport { renderPlaceholders } from \"./render-placeholders\";\n\n/**\n * Concrete `InstructionContract` — a reusable directive block.\n *\n * **Role.** A single addressable prompt block representing one rule the\n * agent must follow (`\"Always respond in {{language|English}}.\"`). Exists\n * as its own type so the same instruction can be shared across many\n * prompts and agents, each render supplying its own placeholder map.\n *\n * **Responsibility.**\n * - Owns: the `type: \"instruction\"` discriminator, the raw template text,\n *   and the placeholder-rendering step.\n * - Does NOT own: ordering relative to other instructions, joining with a\n *   persona, or any surrounding prompt composition — those concerns live\n *   in `SystemPrompt`.\n *\n * Users construct via the `ai.instruction()` factory — `new Instruction()`\n * is not the public API (see §4.2 of code-style.md).\n *\n * @example\n * const replyInLanguage = ai.instruction(\"Respond in {{language|English}}.\");\n *\n * const prompt = ai.systemPrompt()\n *   .persona(\"You are Alex.\")\n *   .instruction(replyInLanguage)\n *   .instruction(\"Always include code examples.\");\n */\nexport class Instruction implements InstructionContract {\n  public readonly type = \"instruction\" as const;\n\n  public constructor(public readonly text: string) {\n    //\n  }\n\n  /**\n   * Substitute `{{mustache}}` placeholders in the instruction text against\n   * the supplied map. Delegates to the shared `renderPlaceholders` helper\n   * so persona / instruction / system-prompt rendering stays identical.\n   */\n  public resolve(placeholders?: Placeholders): string {\n    return renderPlaceholders(this.text, placeholders);\n  }\n}\n\n/**\n * Create an `Instruction` from raw template text.\n *\n * @example\n * const replyIn = instruction(\"Respond in {{language|English}}.\");\n * const cite = instruction(\"Always cite sources inline.\");\n */\nexport function instruction(text: string): Instruction {\n  return new Instruction(text);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,IAAa,cAAb,MAAwD;CAGtD,AAAO,YAAY,AAAgB,MAAc;EAAd;cAFZ;CAIvB;;;;;;CAOA,AAAO,QAAQ,cAAqC;EAClD,OAAO,mBAAmB,KAAK,MAAM,YAAY;CACnD;AACF;;;;;;;;AASA,SAAgB,YAAY,MAA2B;CACrD,OAAO,IAAI,YAAY,IAAI;AAC7B"}

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

@@ -1,7 +1,7 @@
 import { Placeholders } from "../contracts/placeholders.type.mjs";
 import { PersonaContract } from "../contracts/system-prompt.contract.mjs";
 
-//#region ../../@warlock.js/ai/src/system-prompt/persona.d.ts
+//#region ../@warlock.js/ai/src/system-prompt/persona.d.ts
 /**
  * Concrete `PersonaContract` — a reusable "who the agent is" block.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"persona.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/system-prompt/persona.ts"],"mappings":";;;;;;AA8BA;;;;;;;;;;;;;AAY4C;AAY5C;;;;AAA8C;;;;;;cAxBjC,OAAA,YAAmB,eAAe;EAAA,SAGV,IAAA;EAAA,SAFnB,IAAA;cAEmB,IAAA;;;;;;EAS5B,OAAA,CAAQ,YAAA,GAAe,YAAA;AAAA;;;;;;;;iBAYhB,OAAA,CAAQ,IAAA,WAAe,OAAO"}
+{"version":3,"file":"persona.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/system-prompt/persona.ts"],"mappings":";;;;;;AA8BA;;;;;;;;;;;;;AAY4C;AAY5C;;;;AAA8C;;;;;;cAxBjC,OAAA,YAAmB,eAAe;EAAA,SAGV,IAAA;EAAA,SAFnB,IAAA;cAEmB,IAAA;;;;;;EAS5B,OAAA,CAAQ,YAAA,GAAe,YAAA;AAAA;;;;;;;;iBAYhB,OAAA,CAAQ,IAAA,WAAe,OAAO"}

package/esm/system-prompt/persona.mjs

@@ -1,6 +1,6 @@
 import { renderPlaceholders } from "./render-placeholders.mjs";
 
-//#region ../../@warlock.js/ai/src/system-prompt/persona.ts
+//#region ../@warlock.js/ai/src/system-prompt/persona.ts
 /**
 * Concrete `PersonaContract` — a reusable "who the agent is" block.
 *

package/esm/system-prompt/persona.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"persona.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/system-prompt/persona.ts"],"sourcesContent":["import type { Placeholders } from \"../contracts/placeholders.type\";\nimport type { PersonaContract } from \"../contracts/system-prompt.contract\";\nimport { renderPlaceholders } from \"./render-placeholders\";\n\n/**\n * Concrete `PersonaContract` — a reusable \"who the agent is\" block.\n *\n * **Role.** A single addressable prompt block representing the agent's\n * identity (`\"You are Alex, a senior TypeScript engineer.\"`). Exists as\n * its own type so personas can be defined once and reused across many\n * `SystemPrompt` compositions, agents, and sessions — each render can\n * supply a different placeholder map.\n *\n * **Responsibility.**\n * - Owns: the `type: \"persona\"` discriminator, the raw template text, and\n *   the placeholder-rendering step.\n * - Does NOT own: composition with instructions, ordering, joining, or\n *   any knowledge of the surrounding `SystemPrompt`. Those concerns live\n *   in `SystemPrompt`.\n *\n * Users construct via the `ai.persona()` factory — `new Persona()` is not\n * the public API (see §4.2 of code-style.md).\n *\n * @example\n * const alex = ai.persona(\"You are Alex, a TypeScript expert.\");\n *\n * const prompt = ai.systemPrompt()\n *   .persona(alex)\n *   .instruction(\"Always cite sources.\");\n */\nexport class Persona implements PersonaContract {\n  public readonly type = \"persona\" as const;\n\n  public constructor(public readonly text: string) {\n    //\n  }\n\n  /**\n   * Substitute `{{mustache}}` placeholders in the persona text against the\n   * supplied map. Delegates to the shared `renderPlaceholders` helper so\n   * persona / instruction / system-prompt rendering stays identical.\n   */\n  public resolve(placeholders?: Placeholders): string {\n    return renderPlaceholders(this.text, placeholders);\n  }\n}\n\n/**\n * Create a `Persona` from raw template text.\n *\n * @example\n * const alex = persona(\"You are Alex, a TypeScript expert.\");\n * const greeter = persona(\"You are a greeter in {{language|English}}.\");\n */\nexport function persona(text: string): Persona {\n  return new Persona(text);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,IAAa,UAAb,MAAgD;CAG9C,AAAO,YAAY,AAAgB,MAAc;EAAd;cAFZ;CAIvB;;;;;;CAOA,AAAO,QAAQ,cAAqC;EAClD,OAAO,mBAAmB,KAAK,MAAM,YAAY;CACnD;AACF;;;;;;;;AASA,SAAgB,QAAQ,MAAuB;CAC7C,OAAO,IAAI,QAAQ,IAAI;AACzB"}
+{"version":3,"file":"persona.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/system-prompt/persona.ts"],"sourcesContent":["import type { Placeholders } from \"../contracts/placeholders.type\";\nimport type { PersonaContract } from \"../contracts/system-prompt.contract\";\nimport { renderPlaceholders } from \"./render-placeholders\";\n\n/**\n * Concrete `PersonaContract` — a reusable \"who the agent is\" block.\n *\n * **Role.** A single addressable prompt block representing the agent's\n * identity (`\"You are Alex, a senior TypeScript engineer.\"`). Exists as\n * its own type so personas can be defined once and reused across many\n * `SystemPrompt` compositions, agents, and sessions — each render can\n * supply a different placeholder map.\n *\n * **Responsibility.**\n * - Owns: the `type: \"persona\"` discriminator, the raw template text, and\n *   the placeholder-rendering step.\n * - Does NOT own: composition with instructions, ordering, joining, or\n *   any knowledge of the surrounding `SystemPrompt`. Those concerns live\n *   in `SystemPrompt`.\n *\n * Users construct via the `ai.persona()` factory — `new Persona()` is not\n * the public API (see §4.2 of code-style.md).\n *\n * @example\n * const alex = ai.persona(\"You are Alex, a TypeScript expert.\");\n *\n * const prompt = ai.systemPrompt()\n *   .persona(alex)\n *   .instruction(\"Always cite sources.\");\n */\nexport class Persona implements PersonaContract {\n  public readonly type = \"persona\" as const;\n\n  public constructor(public readonly text: string) {\n    //\n  }\n\n  /**\n   * Substitute `{{mustache}}` placeholders in the persona text against the\n   * supplied map. Delegates to the shared `renderPlaceholders` helper so\n   * persona / instruction / system-prompt rendering stays identical.\n   */\n  public resolve(placeholders?: Placeholders): string {\n    return renderPlaceholders(this.text, placeholders);\n  }\n}\n\n/**\n * Create a `Persona` from raw template text.\n *\n * @example\n * const alex = persona(\"You are Alex, a TypeScript expert.\");\n * const greeter = persona(\"You are a greeter in {{language|English}}.\");\n */\nexport function persona(text: string): Persona {\n  return new Persona(text);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,IAAa,UAAb,MAAgD;CAG9C,AAAO,YAAY,AAAgB,MAAc;EAAd;cAFZ;CAIvB;;;;;;CAOA,AAAO,QAAQ,cAAqC;EAClD,OAAO,mBAAmB,KAAK,MAAM,YAAY;CACnD;AACF;;;;;;;;AASA,SAAgB,QAAQ,MAAuB;CAC7C,OAAO,IAAI,QAAQ,IAAI;AACzB"}

package/esm/system-prompt/render-placeholders.d.mts

@@ -1,6 +1,6 @@
 import { Placeholders } from "../contracts/placeholders.type.mjs";
 
-//#region ../../@warlock.js/ai/src/system-prompt/render-placeholders.d.ts
+//#region ../@warlock.js/ai/src/system-prompt/render-placeholders.d.ts
 /**
  * Render a template string against a placeholders map, supporting dot-path
  * lookups and inline fallback values.

package/esm/system-prompt/render-placeholders.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"render-placeholders.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/system-prompt/render-placeholders.ts"],"mappings":";;;;;AA4BA;;;;;;;;AAEiC;;;;;;;;;;;;;;iBAFjB,kBAAA,CACd,QAAA,UACA,YAAA,GAAc,YAAiB"}
+{"version":3,"file":"render-placeholders.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/system-prompt/render-placeholders.ts"],"mappings":";;;;;AA4BA;;;;;;;;AAEiC;;;;;;;;;;;;;;iBAFjB,kBAAA,CACd,QAAA,UACA,YAAA,GAAc,YAAiB"}

package/esm/system-prompt/render-placeholders.mjs

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/ai/src/system-prompt/render-placeholders.ts
+//#region ../@warlock.js/ai/src/system-prompt/render-placeholders.ts
 const PLACEHOLDER_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/g;
 /**
 * Render a template string against a placeholders map, supporting dot-path

package/esm/system-prompt/render-placeholders.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"render-placeholders.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/system-prompt/render-placeholders.ts"],"sourcesContent":["import type { Placeholders } from \"../contracts/placeholders.type\";\n\nconst PLACEHOLDER_PATTERN = /\\{\\{\\s*([^{}]+?)\\s*\\}\\}/g;\n\n/**\n * Render a template string against a placeholders map, supporting dot-path\n * lookups and inline fallback values.\n *\n * Supported syntax:\n * - `{{key}}` — replaced by `placeholders.key`, left untouched if missing.\n * - `{{a.b.c}}` — dot-path lookup into nested objects.\n * - `{{key|default}}` — substitutes `default` when the key resolves to\n *   `undefined`, `null`, or empty string.\n *\n * Whitespace inside the braces is ignored (`{{ key }}` == `{{key}}`).\n * Values are coerced to strings via `String(value)`.\n *\n * @example\n * renderPlaceholders(\n *   \"Hello {{user.name|friend}}, your role is {{role}}\",\n *   { user: { name: \"Hasan\" }, role: \"admin\" },\n * );\n * // \"Hello Hasan, your role is admin\"\n *\n * @example\n * renderPlaceholders(\"Hello {{user.name|friend}}\", {});\n * // \"Hello friend\"\n */\nexport function renderPlaceholders(\n  template: string,\n  placeholders: Placeholders = {},\n): string {\n  return template.replace(\n    PLACEHOLDER_PATTERN,\n    (match, rawExpression: string) => {\n      const [rawPath, rawFallback] = rawExpression.split(\"|\");\n      const path = rawPath.trim();\n      const fallback = rawFallback?.trim();\n\n      const value = lookupPath(placeholders, path);\n\n      if (value === undefined || value === null || value === \"\") {\n        if (fallback !== undefined) {\n          return fallback;\n        }\n\n        return match;\n      }\n\n      return String(value);\n    },\n  );\n}\n\n/**\n * Walk a dot-path (`\"a.b.c\"`) through an arbitrary record, returning the\n * leaf value or `undefined` when any segment is missing or blocks traversal\n * (non-object). Never throws.\n */\nfunction lookupPath(source: Placeholders, path: string): unknown {\n  const segments = path.split(\".\");\n  let current: unknown = source;\n\n  for (const segment of segments) {\n    if (current === null || current === undefined) {\n      return undefined;\n    }\n\n    if (typeof current !== \"object\") {\n      return undefined;\n    }\n\n    current = (current as Record<string, unknown>)[segment];\n  }\n\n  return current;\n}\n"],"mappings":";AAEA,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;AA0B5B,SAAgB,mBACd,UACA,eAA6B,CAAC,GACtB;CACR,OAAO,SAAS,QACd,sBACC,OAAO,kBAA0B;EAChC,MAAM,CAAC,SAAS,eAAe,cAAc,MAAM,GAAG;EACtD,MAAM,OAAO,QAAQ,KAAK;EAC1B,MAAM,WAAW,aAAa,KAAK;EAEnC,MAAM,QAAQ,WAAW,cAAc,IAAI;EAE3C,IAAI,UAAU,UAAa,UAAU,QAAQ,UAAU,IAAI;GACzD,IAAI,aAAa,QACf,OAAO;GAGT,OAAO;EACT;EAEA,OAAO,OAAO,KAAK;CACrB,CACF;AACF;;;;;;AAOA,SAAS,WAAW,QAAsB,MAAuB;CAC/D,MAAM,WAAW,KAAK,MAAM,GAAG;CAC/B,IAAI,UAAmB;CAEvB,KAAK,MAAM,WAAW,UAAU;EAC9B,IAAI,YAAY,QAAQ,YAAY,QAClC;EAGF,IAAI,OAAO,YAAY,UACrB;EAGF,UAAW,QAAoC;CACjD;CAEA,OAAO;AACT"}
+{"version":3,"file":"render-placeholders.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/system-prompt/render-placeholders.ts"],"sourcesContent":["import type { Placeholders } from \"../contracts/placeholders.type\";\n\nconst PLACEHOLDER_PATTERN = /\\{\\{\\s*([^{}]+?)\\s*\\}\\}/g;\n\n/**\n * Render a template string against a placeholders map, supporting dot-path\n * lookups and inline fallback values.\n *\n * Supported syntax:\n * - `{{key}}` — replaced by `placeholders.key`, left untouched if missing.\n * - `{{a.b.c}}` — dot-path lookup into nested objects.\n * - `{{key|default}}` — substitutes `default` when the key resolves to\n *   `undefined`, `null`, or empty string.\n *\n * Whitespace inside the braces is ignored (`{{ key }}` == `{{key}}`).\n * Values are coerced to strings via `String(value)`.\n *\n * @example\n * renderPlaceholders(\n *   \"Hello {{user.name|friend}}, your role is {{role}}\",\n *   { user: { name: \"Hasan\" }, role: \"admin\" },\n * );\n * // \"Hello Hasan, your role is admin\"\n *\n * @example\n * renderPlaceholders(\"Hello {{user.name|friend}}\", {});\n * // \"Hello friend\"\n */\nexport function renderPlaceholders(\n  template: string,\n  placeholders: Placeholders = {},\n): string {\n  return template.replace(\n    PLACEHOLDER_PATTERN,\n    (match, rawExpression: string) => {\n      const [rawPath, rawFallback] = rawExpression.split(\"|\");\n      const path = rawPath.trim();\n      const fallback = rawFallback?.trim();\n\n      const value = lookupPath(placeholders, path);\n\n      if (value === undefined || value === null || value === \"\") {\n        if (fallback !== undefined) {\n          return fallback;\n        }\n\n        return match;\n      }\n\n      return String(value);\n    },\n  );\n}\n\n/**\n * Walk a dot-path (`\"a.b.c\"`) through an arbitrary record, returning the\n * leaf value or `undefined` when any segment is missing or blocks traversal\n * (non-object). Never throws.\n */\nfunction lookupPath(source: Placeholders, path: string): unknown {\n  const segments = path.split(\".\");\n  let current: unknown = source;\n\n  for (const segment of segments) {\n    if (current === null || current === undefined) {\n      return undefined;\n    }\n\n    if (typeof current !== \"object\") {\n      return undefined;\n    }\n\n    current = (current as Record<string, unknown>)[segment];\n  }\n\n  return current;\n}\n"],"mappings":";AAEA,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;AA0B5B,SAAgB,mBACd,UACA,eAA6B,CAAC,GACtB;CACR,OAAO,SAAS,QACd,sBACC,OAAO,kBAA0B;EAChC,MAAM,CAAC,SAAS,eAAe,cAAc,MAAM,GAAG;EACtD,MAAM,OAAO,QAAQ,KAAK;EAC1B,MAAM,WAAW,aAAa,KAAK;EAEnC,MAAM,QAAQ,WAAW,cAAc,IAAI;EAE3C,IAAI,UAAU,UAAa,UAAU,QAAQ,UAAU,IAAI;GACzD,IAAI,aAAa,QACf,OAAO;GAGT,OAAO;EACT;EAEA,OAAO,OAAO,KAAK;CACrB,CACF;AACF;;;;;;AAOA,SAAS,WAAW,QAAsB,MAAuB;CAC/D,MAAM,WAAW,KAAK,MAAM,GAAG;CAC/B,IAAI,UAAmB;CAEvB,KAAK,MAAM,WAAW,UAAU;EAC9B,IAAI,YAAY,QAAQ,YAAY,QAClC;EAGF,IAAI,OAAO,YAAY,UACrB;EAGF,UAAW,QAAoC;CACjD;CAEA,OAAO;AACT"}

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

@@ -1,7 +1,7 @@
 import { Placeholders } from "../contracts/placeholders.type.mjs";
 import { InstructionContract, PersonaContract, SystemPromptBlockContract, SystemPromptContract } from "../contracts/system-prompt.contract.mjs";
 
-//#region ../../@warlock.js/ai/src/system-prompt/system-prompt.d.ts
+//#region ../@warlock.js/ai/src/system-prompt/system-prompt.d.ts
 /**
  * Concrete `SystemPromptContract` — an immutable layered prompt builder.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/system-prompt/system-prompt.ts"],"mappings":";;;;;;AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiD4C;AAyC5C;;;;;;;;;;;;;AAEe;;cA5FF,YAAA,YAAwB,oBAAA;EAAA,SAEjB,MAAA,WAAiB,yBAAA;cAAjB,MAAA,YAAiB,yBAAA;;;;;;;;;EAW5B,OAAA,CAAQ,KAAA,EAAO,eAAA,YAA2B,oBAAA;;;;;;;EAsB1C,WAAA,CACL,KAAA,EAAO,mBAAA,YACN,oBAAA;;;;;;;EAYI,OAAA,CAAQ,YAAA,GAAe,YAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyChB,YAAA,CACd,KAAA,YAAiB,aAAA,CAAc,yBAAA,IAC9B,YAAA"}
+{"version":3,"file":"system-prompt.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/system-prompt/system-prompt.ts"],"mappings":";;;;;;AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiD4C;AAyC5C;;;;;;;;;;;;;AAEe;;cA5FF,YAAA,YAAwB,oBAAA;EAAA,SAEjB,MAAA,WAAiB,yBAAA;cAAjB,MAAA,YAAiB,yBAAA;;;;;;;;;EAW5B,OAAA,CAAQ,KAAA,EAAO,eAAA,YAA2B,oBAAA;;;;;;;EAsB1C,WAAA,CACL,KAAA,EAAO,mBAAA,YACN,oBAAA;;;;;;;EAYI,OAAA,CAAQ,YAAA,GAAe,YAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyChB,YAAA,CACd,KAAA,YAAiB,aAAA,CAAc,yBAAA,IAC9B,YAAA"}

package/esm/system-prompt/system-prompt.mjs

@@ -1,7 +1,7 @@
 import { Instruction } from "./instruction.mjs";
 import { Persona } from "./persona.mjs";
 
-//#region ../../@warlock.js/ai/src/system-prompt/system-prompt.ts
+//#region ../@warlock.js/ai/src/system-prompt/system-prompt.ts
 /**
 * Concrete `SystemPromptContract` — an immutable layered prompt builder.
 *

package/esm/system-prompt/system-prompt.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/system-prompt/system-prompt.ts"],"sourcesContent":["import type { Placeholders } from \"../contracts/placeholders.type\";\nimport type {\n  InstructionContract,\n  PersonaContract,\n  SystemPromptBlockContract,\n  SystemPromptContract,\n} from \"../contracts/system-prompt.contract\";\nimport { Instruction } from \"./instruction\";\nimport { Persona } from \"./persona\";\n\n/**\n * Concrete `SystemPromptContract` — an immutable layered prompt builder.\n *\n * **Role.** The top-level composer for a system prompt: it holds an ordered\n * list of typed blocks (persona + instructions) and resolves the whole\n * stack into one final string when the agent is about to call the model.\n *\n * **Responsibility.**\n * - Owns: the ordered `blocks` list and the block-join rules (insertion\n *   order, blank-line separator, trim).\n * - Does NOT own: how any individual block is rendered (delegated to each\n *   block's `resolve()`), the placeholder syntax (delegated to\n *   `renderPlaceholders`), or any knowledge of the agent, model, or\n *   session consuming the resolved text.\n *\n * Blocks are discriminated by a string `type` tag (`\"persona\"` /\n * `\"instruction\"`) rather than `instanceof`, so user-supplied blocks that\n * implement `SystemPromptBlockContract` interoperate seamlessly with blocks\n * built via `ai.persona()` / `ai.instruction()` — even across duplicate\n * package copies or bundler scope boundaries.\n *\n * The builder is **immutable** — every `.persona()` / `.instruction()`\n * call returns a fresh `SystemPrompt` instance sharing nothing mutable\n * with its parent. This makes forking a base prompt into specialized\n * variants a safe, side-effect-free operation.\n *\n * Users construct via the `ai.systemPrompt()` factory — `new SystemPrompt()`\n * is not the public API (see §4.2 of code-style.md). Modeled as a class so\n * that methods live on the prototype (one copy shared across every forked\n * instance) and downstream code can branch via `instanceof SystemPrompt`.\n *\n * @example\n * // Chainable form\n * const alex = ai.persona(\"You are Alex, a TypeScript expert.\");\n * const replyIn = ai.instruction(\"Respond in {{language|English}}.\");\n *\n * const base = ai.systemPrompt().persona(alex).instruction(replyIn);\n * const arabicVariant = base.instruction(\"Prefer Arabic comments.\");\n *\n * base.resolve({ language: \"English\" });\n * arabicVariant.resolve({ language: \"Arabic\" });\n *\n * @example\n * // Array form — insertion order is preserved exactly\n * const prompt = ai.systemPrompt([\n *   ai.persona(\"You are Alex, a TypeScript expert.\"),\n *   ai.instruction(\"Respond in {{language|English}}.\"),\n * ]);\n */\nexport class SystemPrompt implements SystemPromptContract {\n  public constructor(\n    public readonly blocks: readonly SystemPromptBlockContract[] = [],\n  ) {}\n\n  /**\n   * Return a new builder with the persona block set. If a persona already\n   * exists it's replaced in place (preserving its position in `blocks`);\n   * otherwise the new persona is prepended so persona-first remains the\n   * default for chain-built prompts. Accepts either raw text (auto-wrapped\n   * via `new Persona`) or an existing `PersonaContract` instance for reuse\n   * across prompts.\n   */\n  public persona(value: PersonaContract | string): SystemPromptContract {\n    const block = typeof value === \"string\" ? new Persona(value) : value;\n    const existingIndex = this.blocks.findIndex(\n      candidate => candidate.type === \"persona\",\n    );\n\n    if (existingIndex >= 0) {\n      const next = [...this.blocks];\n      next[existingIndex] = block;\n\n      return new SystemPrompt(next) as this;\n    }\n\n    return new SystemPrompt([block, ...this.blocks]);\n  }\n\n  /**\n   * Return a new builder with the given instruction appended. Instructions\n   * render in insertion order. Accepts either raw text (auto-wrapped via\n   * `new Instruction`) or an existing `InstructionContract` instance for\n   * cross-prompt reuse.\n   */\n  public instruction(\n    value: InstructionContract | string,\n  ): SystemPromptContract {\n    const block = typeof value === \"string\" ? new Instruction(value) : value;\n\n    return new SystemPrompt([...this.blocks, block]);\n  }\n\n  /**\n   * Resolve every block against the placeholder map, join the results with\n   * blank-line separators (in insertion order), and trim. Returns an empty\n   * string when no blocks are present — callers treat that as \"no system\n   * message\".\n   */\n  public resolve(placeholders?: Placeholders): string {\n    return this.blocks\n      .map(block => block.resolve(placeholders))\n      .join(\"\\n\\n\")\n      .trim();\n  }\n}\n\n/**\n * Create a new immutable system-prompt builder.\n *\n * **Role.** Public factory for `SystemPrompt` — keeps user-facing code\n * free of `new` and consistent with `ai.tool()`, `ai.agent()`,\n * `ai.persona()`, `ai.instruction()`.\n *\n * Three input forms:\n * - No argument → empty builder, chain `.persona()` / `.instruction()`\n * - Single string → seeded with one instruction for quick one-shot prompts\n * - Array of blocks → used verbatim, preserving insertion order\n *\n * @example\n * // Composed builder\n * const prompt = systemPrompt()\n *   .persona(\"You are Alex, a senior TypeScript engineer.\")\n *   .instruction(\"Always include working code examples.\")\n *   .instruction(\"Respond in {{language|English}}.\");\n *\n * prompt.resolve({ language: \"Arabic\" });\n *\n * @example\n * // One-shot seed\n * const prompt = systemPrompt(\"Answer only with JSON matching the schema.\");\n *\n * @example\n * // Array form — fully declarative\n * const prompt = systemPrompt([\n *   ai.persona(\"You are Alex.\"),\n *   ai.instruction(\"Always cite sources.\"),\n *   ai.instruction(\"Respond in {{language|English}}.\"),\n * ]);\n */\nexport function systemPrompt(\n  input?: string | ReadonlyArray<SystemPromptBlockContract>,\n): SystemPrompt {\n  if (input === undefined) {\n    return new SystemPrompt();\n  }\n\n  if (typeof input === \"string\") {\n    return new SystemPrompt([new Instruction(input)]);\n  }\n\n  return new SystemPrompt([...input]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,IAAa,eAAb,MAAa,aAA6C;CACxD,AAAO,YACL,AAAgB,SAA+C,CAAC,GAChE;EADgB;CACf;;;;;;;;;CAUH,AAAO,QAAQ,OAAuD;EACpE,MAAM,QAAQ,OAAO,UAAU,WAAW,IAAI,QAAQ,KAAK,IAAI;EAC/D,MAAM,gBAAgB,KAAK,OAAO,WAChC,cAAa,UAAU,SAAS,SAClC;EAEA,IAAI,iBAAiB,GAAG;GACtB,MAAM,OAAO,CAAC,GAAG,KAAK,MAAM;GAC5B,KAAK,iBAAiB;GAEtB,OAAO,IAAI,aAAa,IAAI;EAC9B;EAEA,OAAO,IAAI,aAAa,CAAC,OAAO,GAAG,KAAK,MAAM,CAAC;CACjD;;;;;;;CAQA,AAAO,YACL,OACsB;EACtB,MAAM,QAAQ,OAAO,UAAU,WAAW,IAAI,YAAY,KAAK,IAAI;EAEnE,OAAO,IAAI,aAAa,CAAC,GAAG,KAAK,QAAQ,KAAK,CAAC;CACjD;;;;;;;CAQA,AAAO,QAAQ,cAAqC;EAClD,OAAO,KAAK,OACT,KAAI,UAAS,MAAM,QAAQ,YAAY,CAAC,EACxC,KAAK,MAAM,EACX,KAAK;CACV;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,aACd,OACc;CACd,IAAI,UAAU,QACZ,OAAO,IAAI,aAAa;CAG1B,IAAI,OAAO,UAAU,UACnB,OAAO,IAAI,aAAa,CAAC,IAAI,YAAY,KAAK,CAAC,CAAC;CAGlD,OAAO,IAAI,aAAa,CAAC,GAAG,KAAK,CAAC;AACpC"}
+{"version":3,"file":"system-prompt.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/system-prompt/system-prompt.ts"],"sourcesContent":["import type { Placeholders } from \"../contracts/placeholders.type\";\nimport type {\n  InstructionContract,\n  PersonaContract,\n  SystemPromptBlockContract,\n  SystemPromptContract,\n} from \"../contracts/system-prompt.contract\";\nimport { Instruction } from \"./instruction\";\nimport { Persona } from \"./persona\";\n\n/**\n * Concrete `SystemPromptContract` — an immutable layered prompt builder.\n *\n * **Role.** The top-level composer for a system prompt: it holds an ordered\n * list of typed blocks (persona + instructions) and resolves the whole\n * stack into one final string when the agent is about to call the model.\n *\n * **Responsibility.**\n * - Owns: the ordered `blocks` list and the block-join rules (insertion\n *   order, blank-line separator, trim).\n * - Does NOT own: how any individual block is rendered (delegated to each\n *   block's `resolve()`), the placeholder syntax (delegated to\n *   `renderPlaceholders`), or any knowledge of the agent, model, or\n *   session consuming the resolved text.\n *\n * Blocks are discriminated by a string `type` tag (`\"persona\"` /\n * `\"instruction\"`) rather than `instanceof`, so user-supplied blocks that\n * implement `SystemPromptBlockContract` interoperate seamlessly with blocks\n * built via `ai.persona()` / `ai.instruction()` — even across duplicate\n * package copies or bundler scope boundaries.\n *\n * The builder is **immutable** — every `.persona()` / `.instruction()`\n * call returns a fresh `SystemPrompt` instance sharing nothing mutable\n * with its parent. This makes forking a base prompt into specialized\n * variants a safe, side-effect-free operation.\n *\n * Users construct via the `ai.systemPrompt()` factory — `new SystemPrompt()`\n * is not the public API (see §4.2 of code-style.md). Modeled as a class so\n * that methods live on the prototype (one copy shared across every forked\n * instance) and downstream code can branch via `instanceof SystemPrompt`.\n *\n * @example\n * // Chainable form\n * const alex = ai.persona(\"You are Alex, a TypeScript expert.\");\n * const replyIn = ai.instruction(\"Respond in {{language|English}}.\");\n *\n * const base = ai.systemPrompt().persona(alex).instruction(replyIn);\n * const arabicVariant = base.instruction(\"Prefer Arabic comments.\");\n *\n * base.resolve({ language: \"English\" });\n * arabicVariant.resolve({ language: \"Arabic\" });\n *\n * @example\n * // Array form — insertion order is preserved exactly\n * const prompt = ai.systemPrompt([\n *   ai.persona(\"You are Alex, a TypeScript expert.\"),\n *   ai.instruction(\"Respond in {{language|English}}.\"),\n * ]);\n */\nexport class SystemPrompt implements SystemPromptContract {\n  public constructor(\n    public readonly blocks: readonly SystemPromptBlockContract[] = [],\n  ) {}\n\n  /**\n   * Return a new builder with the persona block set. If a persona already\n   * exists it's replaced in place (preserving its position in `blocks`);\n   * otherwise the new persona is prepended so persona-first remains the\n   * default for chain-built prompts. Accepts either raw text (auto-wrapped\n   * via `new Persona`) or an existing `PersonaContract` instance for reuse\n   * across prompts.\n   */\n  public persona(value: PersonaContract | string): SystemPromptContract {\n    const block = typeof value === \"string\" ? new Persona(value) : value;\n    const existingIndex = this.blocks.findIndex(\n      candidate => candidate.type === \"persona\",\n    );\n\n    if (existingIndex >= 0) {\n      const next = [...this.blocks];\n      next[existingIndex] = block;\n\n      return new SystemPrompt(next) as this;\n    }\n\n    return new SystemPrompt([block, ...this.blocks]);\n  }\n\n  /**\n   * Return a new builder with the given instruction appended. Instructions\n   * render in insertion order. Accepts either raw text (auto-wrapped via\n   * `new Instruction`) or an existing `InstructionContract` instance for\n   * cross-prompt reuse.\n   */\n  public instruction(\n    value: InstructionContract | string,\n  ): SystemPromptContract {\n    const block = typeof value === \"string\" ? new Instruction(value) : value;\n\n    return new SystemPrompt([...this.blocks, block]);\n  }\n\n  /**\n   * Resolve every block against the placeholder map, join the results with\n   * blank-line separators (in insertion order), and trim. Returns an empty\n   * string when no blocks are present — callers treat that as \"no system\n   * message\".\n   */\n  public resolve(placeholders?: Placeholders): string {\n    return this.blocks\n      .map(block => block.resolve(placeholders))\n      .join(\"\\n\\n\")\n      .trim();\n  }\n}\n\n/**\n * Create a new immutable system-prompt builder.\n *\n * **Role.** Public factory for `SystemPrompt` — keeps user-facing code\n * free of `new` and consistent with `ai.tool()`, `ai.agent()`,\n * `ai.persona()`, `ai.instruction()`.\n *\n * Three input forms:\n * - No argument → empty builder, chain `.persona()` / `.instruction()`\n * - Single string → seeded with one instruction for quick one-shot prompts\n * - Array of blocks → used verbatim, preserving insertion order\n *\n * @example\n * // Composed builder\n * const prompt = systemPrompt()\n *   .persona(\"You are Alex, a senior TypeScript engineer.\")\n *   .instruction(\"Always include working code examples.\")\n *   .instruction(\"Respond in {{language|English}}.\");\n *\n * prompt.resolve({ language: \"Arabic\" });\n *\n * @example\n * // One-shot seed\n * const prompt = systemPrompt(\"Answer only with JSON matching the schema.\");\n *\n * @example\n * // Array form — fully declarative\n * const prompt = systemPrompt([\n *   ai.persona(\"You are Alex.\"),\n *   ai.instruction(\"Always cite sources.\"),\n *   ai.instruction(\"Respond in {{language|English}}.\"),\n * ]);\n */\nexport function systemPrompt(\n  input?: string | ReadonlyArray<SystemPromptBlockContract>,\n): SystemPrompt {\n  if (input === undefined) {\n    return new SystemPrompt();\n  }\n\n  if (typeof input === \"string\") {\n    return new SystemPrompt([new Instruction(input)]);\n  }\n\n  return new SystemPrompt([...input]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,IAAa,eAAb,MAAa,aAA6C;CACxD,AAAO,YACL,AAAgB,SAA+C,CAAC,GAChE;EADgB;CACf;;;;;;;;;CAUH,AAAO,QAAQ,OAAuD;EACpE,MAAM,QAAQ,OAAO,UAAU,WAAW,IAAI,QAAQ,KAAK,IAAI;EAC/D,MAAM,gBAAgB,KAAK,OAAO,WAChC,cAAa,UAAU,SAAS,SAClC;EAEA,IAAI,iBAAiB,GAAG;GACtB,MAAM,OAAO,CAAC,GAAG,KAAK,MAAM;GAC5B,KAAK,iBAAiB;GAEtB,OAAO,IAAI,aAAa,IAAI;EAC9B;EAEA,OAAO,IAAI,aAAa,CAAC,OAAO,GAAG,KAAK,MAAM,CAAC;CACjD;;;;;;;CAQA,AAAO,YACL,OACsB;EACtB,MAAM,QAAQ,OAAO,UAAU,WAAW,IAAI,YAAY,KAAK,IAAI;EAEnE,OAAO,IAAI,aAAa,CAAC,GAAG,KAAK,QAAQ,KAAK,CAAC;CACjD;;;;;;;CAQA,AAAO,QAAQ,cAAqC;EAClD,OAAO,KAAK,OACT,KAAI,UAAS,MAAM,QAAQ,YAAY,CAAC,CAAC,CACzC,KAAK,MAAM,CAAC,CACZ,KAAK;CACV;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,aACd,OACc;CACd,IAAI,UAAU,QACZ,OAAO,IAAI,aAAa;CAG1B,IAAI,OAAO,UAAU,UACnB,OAAO,IAAI,aAAa,CAAC,IAAI,YAAY,KAAK,CAAC,CAAC;CAGlD,OAAO,IAAI,aAAa,CAAC,GAAG,KAAK,CAAC;AACpC"}

package/esm/tool/tool.d.mts

@@ -4,7 +4,7 @@ import { BaseReport } from "../contracts/result/base-report.type.mjs";
 import { ToolConfig, ToolContext } from "../contracts/tool.contract.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
-//#region ../../@warlock.js/ai/src/tool/tool.d.ts
+//#region ../@warlock.js/ai/src/tool/tool.d.ts
 /**
  * Result returned by `ToolContract.invoke()`.
  *

package/esm/tool/tool.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/tool/tool.ts"],"mappings":";;;;;;;;;;AAwCA;;;;;;;;;;;;;;;;;KAAY,gBAAA;EAQQ,iFANlB,IAAA,GAAO,OAAA,EAgBQ;EAdf,KAAA,GAAQ,OAAA,EAcmB;EAZ3B,KAAA,EAAO,KAAA,EAcP;EAZA,MAAA,EAAQ,UAAA;AAAA;;;;;;;;UAUO,YAAA,8CAA0D,UAAA,CACzE,MAAA,EACA,OAAA;EADA;;;;;;;;;;AAoB8E;AAuJhF;;;;;;EAvJE,MAAA,CAAO,QAAA,WAAmB,GAAA,GAAM,WAAA,GAAc,OAAA,CAAQ,gBAAA,CAAiB,OAAA;AAAA;AAAA,iBAuJzD,IAAA,iBAAA,CACd,QAAA,EAAU,UAAA,CAAW,MAAA,EAAQ,OAAA,IAC5B,YAAA,CAAa,MAAA,EAAQ,OAAA"}
+{"version":3,"file":"tool.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/tool/tool.ts"],"mappings":";;;;;;;;;;AAwCA;;;;;;;;;;;;;;;;;KAAY,gBAAA;EAQQ,iFANlB,IAAA,GAAO,OAAA,EAgBQ;EAdf,KAAA,GAAQ,OAAA,EAcmB;EAZ3B,KAAA,EAAO,KAAA,EAcP;EAZA,MAAA,EAAQ,UAAA;AAAA;;;;;;;;UAUO,YAAA,8CAA0D,UAAA,CACzE,MAAA,EACA,OAAA;EADA;;;;;;;;;;AAoB8E;AAuJhF;;;;;;EAvJE,MAAA,CAAO,QAAA,WAAmB,GAAA,GAAM,WAAA,GAAc,OAAA,CAAQ,gBAAA,CAAiB,OAAA;AAAA;AAAA,iBAuJzD,IAAA,kBACd,QAAA,EAAU,UAAA,CAAW,MAAA,EAAQ,OAAA,IAC5B,YAAA,CAAa,MAAA,EAAQ,OAAA"}

package/esm/tool/tool.mjs

@@ -3,7 +3,7 @@ import { ToolExecutionError } from "../errors/tool-execution-error.mjs";
 import "../errors/index.mjs";
 import { generateRunId } from "../utils/generate-run-id.mjs";
 
-//#region ../../@warlock.js/ai/src/tool/tool.ts
+//#region ../@warlock.js/ai/src/tool/tool.ts
 /**
 * Degraded `ToolContext` supplied when no caller threads one through
 * (`tool.invoke(input)` standalone, batch scripts, tests). Per
@@ -154,7 +154,7 @@ function tool(contract) {
 				};
 			};
 			let validationResult;
-			try {
+			if (contract.input) try {
 				validationResult = await contract.input["~standard"].validate(rawInput);
 			} catch (thrown) {
 				const message = thrown instanceof Error ? thrown.message : String(thrown);
@@ -163,6 +163,7 @@ function tool(contract) {
 					context: { toolName: contract.name }
 				}) });
 			}
+			else validationResult = { value: rawInput };
 			if (validationResult.issues) return finish({ error: new SchemaValidationError(`Validation failed: ${validationResult.issues.map((issue) => issue.message).join("; ")}`, {
 				issues: validationResult.issues,
 				context: { toolName: contract.name }