@warlock.js/ai 4.2.11 → 4.3.0

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    inputSchema: config.inputSchema,\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/index.mjs

@@ -0,0 +1,6 @@
+import { renderPlaceholders } from "./render-placeholders.mjs";
+import { Instruction, instruction } from "./instruction.mjs";
+import { Persona, persona } from "./persona.mjs";
+import { SystemPrompt, systemPrompt } from "./system-prompt.mjs";
+
+export {  };

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

@@ -54,6 +54,32 @@ import { InstructionContract, PersonaContract, SystemPromptBlockContract, System
 declare class SystemPrompt implements SystemPromptContract {
   readonly blocks: readonly SystemPromptBlockContract[];
   constructor(blocks?: readonly SystemPromptBlockContract[]);
+  /**
+   * Build a system prompt by reading the file at `path` once, synchronously,
+   * at construction time. The file's UTF-8 contents seed a single instruction
+   * block — the same semantics as the string-seed form of `systemPrompt()` —
+   * so placeholders inside the file (`{{language|English}}`) resolve at
+   * `resolve()` time and the result can be forked with further
+   * `.persona()` / `.instruction()` calls.
+   *
+   * One-shot by design: the file is read exactly once here, never re-read on
+   * `resolve()`. Reads are synchronous so the call stays a drop-in for the
+   * synchronous `systemPrompt()` factory and the synchronous `resolve()` API.
+   *
+   * Throws `InvalidRequestError` when the file cannot be read (missing path,
+   * permission denied) — surfacing the underlying cause so a typo in the
+   * prompt path fails loudly at construction instead of silently producing an
+   * empty prompt.
+   *
+   * @param path - Filesystem path to the prompt template file.
+   *
+   * @example
+   * const prompt = SystemPrompt.fromFile("./prompts/support-agent.md");
+   *
+   * const localized = prompt.instruction("Respond in {{language|English}}.");
+   * localized.resolve({ language: "Arabic" });
+   */
+  static fromFile(path: string): SystemPrompt;
   /**
    * Return a new builder with the persona block set. If a persona already
    * exists it's replaced in place (preserving its position in `blocks`);
@@ -78,6 +104,23 @@ declare class SystemPrompt implements SystemPromptContract {
    */
   resolve(placeholders?: Placeholders): string;
 }
+/**
+ * Public factory for `SystemPrompt`, callable directly or via its
+ * `fromFile` static. Exists as a named interface so the callable signature
+ * and the `fromFile` attachment travel together as one public type.
+ */
+interface SystemPromptFactory {
+  (input?: string | ReadonlyArray<SystemPromptBlockContract>): SystemPrompt;
+  /**
+   * Build a system prompt from a file read once at construction. Delegates
+   * to {@link SystemPrompt.fromFile}, so `ai.systemPrompt.fromFile(path)` and
+   * `SystemPrompt.fromFile(path)` behave identically.
+   *
+   * @example
+   * const prompt = ai.systemPrompt.fromFile("./prompts/support-agent.md");
+   */
+  fromFile(path: string): SystemPrompt;
+}
 /**
  * Create a new immutable system-prompt builder.
  *
@@ -85,10 +128,11 @@ declare class SystemPrompt implements SystemPromptContract {
  * free of `new` and consistent with `ai.tool()`, `ai.agent()`,
  * `ai.persona()`, `ai.instruction()`.
  *
- * Three input forms:
+ * Input forms:
  * - No argument → empty builder, chain `.persona()` / `.instruction()`
  * - Single string → seeded with one instruction for quick one-shot prompts
  * - Array of blocks → used verbatim, preserving insertion order
+ * - `.fromFile(path)` → seeded from a file read once at construction
  *
  * @example
  * // Composed builder
@@ -104,6 +148,10 @@ declare class SystemPrompt implements SystemPromptContract {
  * const prompt = systemPrompt("Answer only with JSON matching the schema.");
  *
  * @example
+ * // From a file, read once at construction
+ * const prompt = systemPrompt.fromFile("./prompts/support-agent.md");
+ *
+ * @example
  * // Array form — fully declarative
  * const prompt = systemPrompt([
  *   ai.persona("You are Alex."),
@@ -111,7 +159,7 @@ declare class SystemPrompt implements SystemPromptContract {
  *   ai.instruction("Respond in {{language|English}}."),
  * ]);
  */
-declare function systemPrompt(input?: string | ReadonlyArray<SystemPromptBlockContract>): SystemPrompt;
+declare const systemPrompt: SystemPromptFactory;
 //#endregion
-export { SystemPrompt, systemPrompt };
+export { SystemPrompt, SystemPromptFactory, systemPrompt };
 //# sourceMappingURL=system-prompt.d.mts.map

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":";;;;;;AA6DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2F4C;AAa5C;;;;;;;;;;;cAxGa,YAAA,YAAwB,oBAAA;EAAA,SAEjB,MAAA,WAAiB,yBAAA;cAAjB,MAAA,YAAiB,yBAAA;EAiH1B;;;AAA2B;AAuDtC;;;;AAGC;;;;;;;;;;;;;;;;;EA1DU,OArFK,QAAA,CAAS,IAAA,WAAe,YAAA;;;;;;;;;EAyB/B,OAAA,CAAQ,KAAA,EAAO,eAAA,YAA2B,oBAAA;;;;;;;EAsB1C,WAAA,CACL,KAAA,EAAO,mBAAA,YACN,oBAAA;;;;;;;EAYI,OAAA,CAAQ,YAAA,GAAe,YAAA;AAAA;;;;;;UAaf,mBAAA;EAAA,CACd,KAAA,YAAiB,aAAA,CAAc,yBAAA,IAA6B,YAAA;;;;;;;;;EAU7D,QAAA,CAAS,IAAA,WAAe,YAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAuDb,YAAA,EAAc,mBAG1B"}

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

@@ -1,5 +1,8 @@
+import { InvalidRequestError } from "../errors/invalid-request-error.mjs";
+import "../errors/index.mjs";
 import { Instruction } from "./instruction.mjs";
 import { Persona } from "./persona.mjs";
+import { readFileSync } from "node:fs";
 
 //#region ../@warlock.js/ai/src/system-prompt/system-prompt.ts
 /**
@@ -56,6 +59,43 @@ var SystemPrompt = class SystemPrompt {
 		this.blocks = blocks;
 	}
 	/**
+	* Build a system prompt by reading the file at `path` once, synchronously,
+	* at construction time. The file's UTF-8 contents seed a single instruction
+	* block — the same semantics as the string-seed form of `systemPrompt()` —
+	* so placeholders inside the file (`{{language|English}}`) resolve at
+	* `resolve()` time and the result can be forked with further
+	* `.persona()` / `.instruction()` calls.
+	*
+	* One-shot by design: the file is read exactly once here, never re-read on
+	* `resolve()`. Reads are synchronous so the call stays a drop-in for the
+	* synchronous `systemPrompt()` factory and the synchronous `resolve()` API.
+	*
+	* Throws `InvalidRequestError` when the file cannot be read (missing path,
+	* permission denied) — surfacing the underlying cause so a typo in the
+	* prompt path fails loudly at construction instead of silently producing an
+	* empty prompt.
+	*
+	* @param path - Filesystem path to the prompt template file.
+	*
+	* @example
+	* const prompt = SystemPrompt.fromFile("./prompts/support-agent.md");
+	*
+	* const localized = prompt.instruction("Respond in {{language|English}}.");
+	* localized.resolve({ language: "Arabic" });
+	*/
+	static fromFile(path) {
+		let contents;
+		try {
+			contents = readFileSync(path, "utf8");
+		} catch (error) {
+			throw new InvalidRequestError(`Failed to read system prompt file "${path}" — ${error instanceof Error ? error.message : String(error)}`, {
+				context: { path },
+				cause: error
+			});
+		}
+		return new SystemPrompt([new Instruction(contents)]);
+	}
+	/**
 	* Return a new builder with the persona block set. If a persona already
 	* exists it's replaced in place (preserving its position in `blocks`);
 	* otherwise the new persona is prepended so persona-first remains the
@@ -93,6 +133,11 @@ var SystemPrompt = class SystemPrompt {
 		return this.blocks.map((block) => block.resolve(placeholders)).join("\n\n").trim();
 	}
 };
+function systemPromptFactory(input) {
+	if (input === void 0) return new SystemPrompt();
+	if (typeof input === "string") return new SystemPrompt([new Instruction(input)]);
+	return new SystemPrompt([...input]);
+}
 /**
 * Create a new immutable system-prompt builder.
 *
@@ -100,10 +145,11 @@ var SystemPrompt = class SystemPrompt {
 * free of `new` and consistent with `ai.tool()`, `ai.agent()`,
 * `ai.persona()`, `ai.instruction()`.
 *
-* Three input forms:
+* Input forms:
 * - No argument → empty builder, chain `.persona()` / `.instruction()`
 * - Single string → seeded with one instruction for quick one-shot prompts
 * - Array of blocks → used verbatim, preserving insertion order
+* - `.fromFile(path)` → seeded from a file read once at construction
 *
 * @example
 * // Composed builder
@@ -119,6 +165,10 @@ var SystemPrompt = class SystemPrompt {
 * const prompt = systemPrompt("Answer only with JSON matching the schema.");
 *
 * @example
+* // From a file, read once at construction
+* const prompt = systemPrompt.fromFile("./prompts/support-agent.md");
+*
+* @example
 * // Array form — fully declarative
 * const prompt = systemPrompt([
 *   ai.persona("You are Alex."),
@@ -126,11 +176,7 @@ var SystemPrompt = class SystemPrompt {
 *   ai.instruction("Respond in {{language|English}}."),
 * ]);
 */
-function systemPrompt(input) {
-	if (input === void 0) return new SystemPrompt();
-	if (typeof input === "string") return new SystemPrompt([new Instruction(input)]);
-	return new SystemPrompt([...input]);
-}
+const systemPrompt = Object.assign(systemPromptFactory, { fromFile: SystemPrompt.fromFile });
 
 //#endregion
 export { SystemPrompt, systemPrompt };

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,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"}
+{"version":3,"file":"system-prompt.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/system-prompt/system-prompt.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport type { Placeholders } from \"../contracts/placeholders.type\";\nimport type {\n  InstructionContract,\n  PersonaContract,\n  SystemPromptBlockContract,\n  SystemPromptContract,\n} from \"../contracts/system-prompt.contract\";\nimport { InvalidRequestError } from \"../errors\";\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   * Build a system prompt by reading the file at `path` once, synchronously,\n   * at construction time. The file's UTF-8 contents seed a single instruction\n   * block — the same semantics as the string-seed form of `systemPrompt()` —\n   * so placeholders inside the file (`{{language|English}}`) resolve at\n   * `resolve()` time and the result can be forked with further\n   * `.persona()` / `.instruction()` calls.\n   *\n   * One-shot by design: the file is read exactly once here, never re-read on\n   * `resolve()`. Reads are synchronous so the call stays a drop-in for the\n   * synchronous `systemPrompt()` factory and the synchronous `resolve()` API.\n   *\n   * Throws `InvalidRequestError` when the file cannot be read (missing path,\n   * permission denied) — surfacing the underlying cause so a typo in the\n   * prompt path fails loudly at construction instead of silently producing an\n   * empty prompt.\n   *\n   * @param path - Filesystem path to the prompt template file.\n   *\n   * @example\n   * const prompt = SystemPrompt.fromFile(\"./prompts/support-agent.md\");\n   *\n   * const localized = prompt.instruction(\"Respond in {{language|English}}.\");\n   * localized.resolve({ language: \"Arabic\" });\n   */\n  public static fromFile(path: string): SystemPrompt {\n    let contents: string;\n\n    try {\n      contents = readFileSync(path, \"utf8\");\n    } catch (error) {\n      throw new InvalidRequestError(\n        `Failed to read system prompt file \"${path}\" — ${\n          error instanceof Error ? error.message : String(error)\n        }`,\n        { context: { path }, cause: error },\n      );\n    }\n\n    return new SystemPrompt([new Instruction(contents)]);\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 * Public factory for `SystemPrompt`, callable directly or via its\n * `fromFile` static. Exists as a named interface so the callable signature\n * and the `fromFile` attachment travel together as one public type.\n */\nexport interface SystemPromptFactory {\n  (input?: string | ReadonlyArray<SystemPromptBlockContract>): SystemPrompt;\n\n  /**\n   * Build a system prompt from a file read once at construction. Delegates\n   * to {@link SystemPrompt.fromFile}, so `ai.systemPrompt.fromFile(path)` and\n   * `SystemPrompt.fromFile(path)` behave identically.\n   *\n   * @example\n   * const prompt = ai.systemPrompt.fromFile(\"./prompts/support-agent.md\");\n   */\n  fromFile(path: string): SystemPrompt;\n}\n\nfunction systemPromptFactory(\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\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 * 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 * - `.fromFile(path)` → seeded from a file read once at construction\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 * // From a file, read once at construction\n * const prompt = systemPrompt.fromFile(\"./prompts/support-agent.md\");\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 const systemPrompt: SystemPromptFactory = Object.assign(\n  systemPromptFactory,\n  { fromFile: SystemPrompt.fromFile },\n);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,IAAa,eAAb,MAAa,aAA6C;CACxD,AAAO,YACL,AAAgB,SAA+C,CAAC,GAChE;EADgB;CACf;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BH,OAAc,SAAS,MAA4B;EACjD,IAAI;EAEJ,IAAI;GACF,WAAW,aAAa,MAAM,MAAM;EACtC,SAAS,OAAO;GACd,MAAM,IAAI,oBACR,sCAAsC,KAAK,MACzC,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,KAEvD;IAAE,SAAS,EAAE,KAAK;IAAG,OAAO;GAAM,CACpC;EACF;EAEA,OAAO,IAAI,aAAa,CAAC,IAAI,YAAY,QAAQ,CAAC,CAAC;CACrD;;;;;;;;;CAUA,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;AAqBA,SAAS,oBACP,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAa,eAAoC,OAAO,OACtD,qBACA,EAAE,UAAU,aAAa,SAAS,CACpC"}

package/esm/testing/matcher-logic.d.mts

@@ -0,0 +1,76 @@
+import { BaseReport } from "../contracts/result/base-report.type.mjs";
+import { END } from "../contracts/end.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../@warlock.js/ai/src/testing/matcher-logic.d.ts
+/**
+ * Normalized matcher verdict — the library-agnostic shape every
+ * matcher in this module returns. Vitest's `expect.extend` consumes
+ * the same `{ pass, message }` contract, so the registration layer
+ * forwards these verbatim.
+ */
+type MatcherVerdict = {
+  /** Whether the assertion passed. */pass: boolean; /** Lazy message factory — Vitest calls it only when reporting. */
+  message: () => string;
+};
+/**
+ * Any unified result envelope a matcher can be handed. Accepts the
+ * full `{ report, ... }` result or a bare `BaseReport` so callers can
+ * assert against either `await x.execute()` or `result.report`.
+ */
+type ReportLike = BaseReport | {
+  report: BaseReport;
+};
+/**
+ * Assert that a supervisor routed to (dispatched) the named intent at
+ * least once across its iterations. Targets a `SupervisorResult` or a
+ * `SupervisorReport`.
+ *
+ * @example
+ * expect(await supervisor.execute(input)).toRouteTo("critic");
+ */
+declare function matchRouteTo(received: ReportLike, intent: string): MatcherVerdict;
+/**
+ * Assert that a supervisor converged — terminated on its own decision
+ * (`router` / `route` / `evaluate` / `classifier`) with a
+ * `"completed"` status, rather than hitting the iteration cap, being
+ * cancelled, or erroring. Targets a `SupervisorResult` or
+ * `SupervisorReport`.
+ *
+ * @example
+ * expect(await supervisor.execute(input)).toConverge();
+ */
+declare function matchConverge(received: ReportLike): MatcherVerdict;
+/**
+ * Assert that a workflow step completed successfully. Targets a
+ * `WorkflowResult` or `WorkflowReport`; looks the step up by name in
+ * `report.steps` and checks its status is `"completed"`.
+ *
+ * @example
+ * expect(await workflow.execute(input)).toPassStep("draft");
+ */
+declare function matchPassStep(received: ReportLike, stepName: string): MatcherVerdict;
+/**
+ * Result envelope carrying a typed `data` payload — what
+ * `matchOutputShape` validates against a schema.
+ */
+type DataResult = {
+  data?: unknown;
+};
+/**
+ * Assert that a result's `data` validates against a Standard Schema.
+ * Targets any result envelope with a `data` field (agent / workflow /
+ * supervisor). Runs the schema's `~standard.validate` and passes only
+ * when it reports no issues.
+ *
+ * Synchronous-only: a schema whose `validate` returns a Promise is
+ * rejected with a clear message rather than silently passing — the
+ * async variant belongs on a dedicated async matcher if needed.
+ *
+ * @example
+ * expect(await agent.execute(input, { output: schema })).toOutputShape(schema);
+ */
+declare function matchOutputShape(received: DataResult, schema: StandardSchemaV1): MatcherVerdict;
+//#endregion
+export { MatcherVerdict, matchConverge, matchOutputShape, matchPassStep, matchRouteTo };
+//# sourceMappingURL=matcher-logic.d.mts.map

package/esm/testing/matcher-logic.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher-logic.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/testing/matcher-logic.ts"],"mappings":";;;;;;;AAYA;;;;KAAY,cAAA;EAYP,oCAVH,IAAA;EAEA,OAAO;AAAA;;;;AAQ0C;AAgDnD;KAhDK,UAAA,GAAa,UAAA;EAAe,MAAA,EAAQ,UAAU;AAAA;;;;;;AAgD+B;AAkClF;;iBAlCgB,YAAA,CAAa,QAAA,EAAU,UAAA,EAAY,MAAA,WAAiB,cAAc;;;;;;AAkCf;AAkCnE;;;;iBAlCgB,aAAA,CAAc,QAAA,EAAU,UAAA,GAAa,cAAc;;;;;AAkCkB;AAgCpF;;;iBAhCe,aAAA,CAAc,QAAA,EAAU,UAAA,EAAY,QAAA,WAAmB,cAAc;AAsC7D;AAexB;;;AAfwB,KAAnB,UAAA;EAAe,IAAI;AAAA;;;;;;;;;AAkBP;;;;;iBAHD,gBAAA,CACd,QAAA,EAAU,UAAA,EACV,MAAA,EAAQ,gBAAA,GACP,cAAA"}

package/esm/testing/matcher-logic.mjs

@@ -0,0 +1,144 @@
+import { END } from "../contracts/end.type.mjs";
+
+//#region ../@warlock.js/ai/src/testing/matcher-logic.ts
+/**
+* Coerce a matcher target into its `BaseReport`. Accepts the result
+* envelope (`{ report }`) or a report directly.
+*/
+function toReport(received) {
+	if ("report" in received && received.report) return received.report;
+	return received;
+}
+/** Narrow a `BaseReport` to a `SupervisorReport` by its discriminator. */
+function asSupervisorReport(report) {
+	return report.type === "supervisor" ? report : void 0;
+}
+/** Narrow a `BaseReport` to a `WorkflowReport` by its discriminator. */
+function asWorkflowReport(report) {
+	return report.type === "workflow" ? report : void 0;
+}
+/**
+* Collect every intent name dispatched by a supervisor across all
+* iterations — the keys of each iteration snapshot's `result` record.
+*/
+function dispatchedIntents(report) {
+	const intents = /* @__PURE__ */ new Set();
+	for (const snapshot of report.snapshots) for (const intent of Object.keys(snapshot.result)) intents.add(intent);
+	return [...intents];
+}
+/**
+* Assert that a supervisor routed to (dispatched) the named intent at
+* least once across its iterations. Targets a `SupervisorResult` or a
+* `SupervisorReport`.
+*
+* @example
+* expect(await supervisor.execute(input)).toRouteTo("critic");
+*/
+function matchRouteTo(received, intent) {
+	const report = toReport(received);
+	const supervisorReport = asSupervisorReport(report);
+	if (!supervisorReport) return {
+		pass: false,
+		message: () => `toRouteTo expects a supervisor result, but received a "${report.type}" report`
+	};
+	const intents = dispatchedIntents(supervisorReport);
+	const pass = intents.includes(intent);
+	return {
+		pass,
+		message: () => pass ? `expected supervisor not to route to "${intent}", but it did` : `expected supervisor to route to "${intent}", but it routed to [${intents.join(", ")}]`
+	};
+}
+/**
+* Assert that a supervisor converged — terminated on its own decision
+* (`router` / `route` / `evaluate` / `classifier`) with a
+* `"completed"` status, rather than hitting the iteration cap, being
+* cancelled, or erroring. Targets a `SupervisorResult` or
+* `SupervisorReport`.
+*
+* @example
+* expect(await supervisor.execute(input)).toConverge();
+*/
+function matchConverge(received) {
+	const report = toReport(received);
+	const supervisorReport = asSupervisorReport(report);
+	if (!supervisorReport) return {
+		pass: false,
+		message: () => `toConverge expects a supervisor result, but received a "${report.type}" report`
+	};
+	const nonConvergent = new Set([
+		"max-iterations",
+		"cancelled",
+		"error"
+	]);
+	const pass = supervisorReport.status === "completed" && !nonConvergent.has(supervisorReport.terminatedBy);
+	return {
+		pass,
+		message: () => pass ? `expected supervisor not to converge, but it terminated via "${supervisorReport.terminatedBy}"` : `expected supervisor to converge, but status="${supervisorReport.status}" terminatedBy="${supervisorReport.terminatedBy}" after ${supervisorReport.iterations} iteration(s)`
+	};
+}
+/**
+* Assert that a workflow step completed successfully. Targets a
+* `WorkflowResult` or `WorkflowReport`; looks the step up by name in
+* `report.steps` and checks its status is `"completed"`.
+*
+* @example
+* expect(await workflow.execute(input)).toPassStep("draft");
+*/
+function matchPassStep(received, stepName) {
+	const report = toReport(received);
+	const workflowReport = asWorkflowReport(report);
+	if (!workflowReport) return {
+		pass: false,
+		message: () => `toPassStep expects a workflow result, but received a "${report.type}" report`
+	};
+	const step = workflowReport.steps[stepName];
+	if (!step) {
+		const known = Object.keys(workflowReport.steps).join(", ");
+		return {
+			pass: false,
+			message: () => `expected workflow to have a step "${stepName}", but steps are [${known}]`
+		};
+	}
+	const pass = step.status === "completed";
+	return {
+		pass,
+		message: () => pass ? `expected step "${stepName}" not to pass, but it completed` : `expected step "${stepName}" to pass, but its status was "${step.status}"`
+	};
+}
+/**
+* Assert that a result's `data` validates against a Standard Schema.
+* Targets any result envelope with a `data` field (agent / workflow /
+* supervisor). Runs the schema's `~standard.validate` and passes only
+* when it reports no issues.
+*
+* Synchronous-only: a schema whose `validate` returns a Promise is
+* rejected with a clear message rather than silently passing — the
+* async variant belongs on a dedicated async matcher if needed.
+*
+* @example
+* expect(await agent.execute(input, { output: schema })).toOutputShape(schema);
+*/
+function matchOutputShape(received, schema) {
+	const data = received.data;
+	if (data === void 0) return {
+		pass: false,
+		message: () => "toOutputShape expected result.data to be defined, but it was undefined"
+	};
+	const validation = schema["~standard"].validate(data);
+	if (validation instanceof Promise) return {
+		pass: false,
+		message: () => "toOutputShape received an async schema; use a synchronous Standard Schema for this matcher"
+	};
+	const pass = validation.issues === void 0;
+	return {
+		pass,
+		message: () => {
+			if (pass) return "expected result.data not to match the schema, but it did";
+			return `expected result.data to match the schema, but validation failed: ${(validation.issues ?? []).map((issue) => issue.message).join("; ")}`;
+		}
+	};
+}
+
+//#endregion
+export { matchConverge, matchOutputShape, matchPassStep, matchRouteTo };
+//# sourceMappingURL=matcher-logic.mjs.map

package/esm/testing/matcher-logic.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher-logic.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/testing/matcher-logic.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { END } from \"../contracts/end.type\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { SupervisorReport } from \"../contracts/result/supervisor-result.type\";\nimport type { WorkflowReport } from \"../contracts/result/workflow-result.type\";\n\n/**\n * Normalized matcher verdict — the library-agnostic shape every\n * matcher in this module returns. Vitest's `expect.extend` consumes\n * the same `{ pass, message }` contract, so the registration layer\n * forwards these verbatim.\n */\nexport type MatcherVerdict = {\n  /** Whether the assertion passed. */\n  pass: boolean;\n  /** Lazy message factory — Vitest calls it only when reporting. */\n  message: () => string;\n};\n\n/**\n * Any unified result envelope a matcher can be handed. Accepts the\n * full `{ report, ... }` result or a bare `BaseReport` so callers can\n * assert against either `await x.execute()` or `result.report`.\n */\ntype ReportLike = BaseReport | { report: BaseReport };\n\n/**\n * Coerce a matcher target into its `BaseReport`. Accepts the result\n * envelope (`{ report }`) or a report directly.\n */\nfunction toReport(received: ReportLike): BaseReport {\n  if (\"report\" in received && received.report) {\n    return received.report;\n  }\n\n  return received as BaseReport;\n}\n\n/** Narrow a `BaseReport` to a `SupervisorReport` by its discriminator. */\nfunction asSupervisorReport(report: BaseReport): SupervisorReport | undefined {\n  return report.type === \"supervisor\" ? (report as SupervisorReport) : undefined;\n}\n\n/** Narrow a `BaseReport` to a `WorkflowReport` by its discriminator. */\nfunction asWorkflowReport(report: BaseReport): WorkflowReport | undefined {\n  return report.type === \"workflow\" ? (report as WorkflowReport) : undefined;\n}\n\n/**\n * Collect every intent name dispatched by a supervisor across all\n * iterations — the keys of each iteration snapshot's `result` record.\n */\nfunction dispatchedIntents(report: SupervisorReport): string[] {\n  const intents = new Set<string>();\n\n  for (const snapshot of report.snapshots) {\n    for (const intent of Object.keys(snapshot.result)) {\n      intents.add(intent);\n    }\n  }\n\n  return [...intents];\n}\n\n/**\n * Assert that a supervisor routed to (dispatched) the named intent at\n * least once across its iterations. Targets a `SupervisorResult` or a\n * `SupervisorReport`.\n *\n * @example\n * expect(await supervisor.execute(input)).toRouteTo(\"critic\");\n */\nexport function matchRouteTo(received: ReportLike, intent: string): MatcherVerdict {\n  const report = toReport(received);\n  const supervisorReport = asSupervisorReport(report);\n\n  if (!supervisorReport) {\n    return {\n      pass: false,\n      message: () =>\n        `toRouteTo expects a supervisor result, but received a \"${report.type}\" report`,\n    };\n  }\n\n  const intents = dispatchedIntents(supervisorReport);\n  const pass = intents.includes(intent);\n\n  return {\n    pass,\n    message: () =>\n      pass\n        ? `expected supervisor not to route to \"${intent}\", but it did`\n        : `expected supervisor to route to \"${intent}\", but it routed to [${intents.join(\", \")}]`,\n  };\n}\n\n/**\n * Assert that a supervisor converged — terminated on its own decision\n * (`router` / `route` / `evaluate` / `classifier`) with a\n * `\"completed\"` status, rather than hitting the iteration cap, being\n * cancelled, or erroring. Targets a `SupervisorResult` or\n * `SupervisorReport`.\n *\n * @example\n * expect(await supervisor.execute(input)).toConverge();\n */\nexport function matchConverge(received: ReportLike): MatcherVerdict {\n  const report = toReport(received);\n  const supervisorReport = asSupervisorReport(report);\n\n  if (!supervisorReport) {\n    return {\n      pass: false,\n      message: () =>\n        `toConverge expects a supervisor result, but received a \"${report.type}\" report`,\n    };\n  }\n\n  const nonConvergent = new Set([\"max-iterations\", \"cancelled\", \"error\"]);\n  const pass =\n    supervisorReport.status === \"completed\" &&\n    !nonConvergent.has(supervisorReport.terminatedBy);\n\n  return {\n    pass,\n    message: () =>\n      pass\n        ? `expected supervisor not to converge, but it terminated via \"${supervisorReport.terminatedBy}\"`\n        : `expected supervisor to converge, but status=\"${supervisorReport.status}\" terminatedBy=\"${supervisorReport.terminatedBy}\" after ${supervisorReport.iterations} iteration(s)`,\n  };\n}\n\n/**\n * Assert that a workflow step completed successfully. Targets a\n * `WorkflowResult` or `WorkflowReport`; looks the step up by name in\n * `report.steps` and checks its status is `\"completed\"`.\n *\n * @example\n * expect(await workflow.execute(input)).toPassStep(\"draft\");\n */\nexport function matchPassStep(received: ReportLike, stepName: string): MatcherVerdict {\n  const report = toReport(received);\n  const workflowReport = asWorkflowReport(report);\n\n  if (!workflowReport) {\n    return {\n      pass: false,\n      message: () =>\n        `toPassStep expects a workflow result, but received a \"${report.type}\" report`,\n    };\n  }\n\n  const step = workflowReport.steps[stepName];\n\n  if (!step) {\n    const known = Object.keys(workflowReport.steps).join(\", \");\n    return {\n      pass: false,\n      message: () =>\n        `expected workflow to have a step \"${stepName}\", but steps are [${known}]`,\n    };\n  }\n\n  const pass = step.status === \"completed\";\n\n  return {\n    pass,\n    message: () =>\n      pass\n        ? `expected step \"${stepName}\" not to pass, but it completed`\n        : `expected step \"${stepName}\" to pass, but its status was \"${step.status}\"`,\n  };\n}\n\n/**\n * Result envelope carrying a typed `data` payload — what\n * `matchOutputShape` validates against a schema.\n */\ntype DataResult = { data?: unknown };\n\n/**\n * Assert that a result's `data` validates against a Standard Schema.\n * Targets any result envelope with a `data` field (agent / workflow /\n * supervisor). Runs the schema's `~standard.validate` and passes only\n * when it reports no issues.\n *\n * Synchronous-only: a schema whose `validate` returns a Promise is\n * rejected with a clear message rather than silently passing — the\n * async variant belongs on a dedicated async matcher if needed.\n *\n * @example\n * expect(await agent.execute(input, { output: schema })).toOutputShape(schema);\n */\nexport function matchOutputShape(\n  received: DataResult,\n  schema: StandardSchemaV1,\n): MatcherVerdict {\n  const data = received.data;\n\n  if (data === undefined) {\n    return {\n      pass: false,\n      message: () => \"toOutputShape expected result.data to be defined, but it was undefined\",\n    };\n  }\n\n  const validation = schema[\"~standard\"].validate(data);\n\n  if (validation instanceof Promise) {\n    return {\n      pass: false,\n      message: () =>\n        \"toOutputShape received an async schema; use a synchronous Standard Schema for this matcher\",\n    };\n  }\n\n  const pass = validation.issues === undefined;\n\n  return {\n    pass,\n    message: () => {\n      if (pass) {\n        return \"expected result.data not to match the schema, but it did\";\n      }\n\n      const summary = (validation.issues ?? []).map((issue) => issue.message).join(\"; \");\n      return `expected result.data to match the schema, but validation failed: ${summary}`;\n    },\n  };\n}\n\n// Re-exported so matcher consumers and tests can reference the\n// termination sentinel without reaching into contracts.\nexport { END };\n"],"mappings":";;;;;;;AA8BA,SAAS,SAAS,UAAkC;CAClD,IAAI,YAAY,YAAY,SAAS,QACnC,OAAO,SAAS;CAGlB,OAAO;AACT;;AAGA,SAAS,mBAAmB,QAAkD;CAC5E,OAAO,OAAO,SAAS,eAAgB,SAA8B;AACvE;;AAGA,SAAS,iBAAiB,QAAgD;CACxE,OAAO,OAAO,SAAS,aAAc,SAA4B;AACnE;;;;;AAMA,SAAS,kBAAkB,QAAoC;CAC7D,MAAM,0BAAU,IAAI,IAAY;CAEhC,KAAK,MAAM,YAAY,OAAO,WAC5B,KAAK,MAAM,UAAU,OAAO,KAAK,SAAS,MAAM,GAC9C,QAAQ,IAAI,MAAM;CAItB,OAAO,CAAC,GAAG,OAAO;AACpB;;;;;;;;;AAUA,SAAgB,aAAa,UAAsB,QAAgC;CACjF,MAAM,SAAS,SAAS,QAAQ;CAChC,MAAM,mBAAmB,mBAAmB,MAAM;CAElD,IAAI,CAAC,kBACH,OAAO;EACL,MAAM;EACN,eACE,0DAA0D,OAAO,KAAK;CAC1E;CAGF,MAAM,UAAU,kBAAkB,gBAAgB;CAClD,MAAM,OAAO,QAAQ,SAAS,MAAM;CAEpC,OAAO;EACL;EACA,eACE,OACI,wCAAwC,OAAO,iBAC/C,oCAAoC,OAAO,uBAAuB,QAAQ,KAAK,IAAI,EAAE;CAC7F;AACF;;;;;;;;;;;AAYA,SAAgB,cAAc,UAAsC;CAClE,MAAM,SAAS,SAAS,QAAQ;CAChC,MAAM,mBAAmB,mBAAmB,MAAM;CAElD,IAAI,CAAC,kBACH,OAAO;EACL,MAAM;EACN,eACE,2DAA2D,OAAO,KAAK;CAC3E;CAGF,MAAM,gBAAgB,IAAI,IAAI;EAAC;EAAkB;EAAa;CAAO,CAAC;CACtE,MAAM,OACJ,iBAAiB,WAAW,eAC5B,CAAC,cAAc,IAAI,iBAAiB,YAAY;CAElD,OAAO;EACL;EACA,eACE,OACI,+DAA+D,iBAAiB,aAAa,KAC7F,gDAAgD,iBAAiB,OAAO,kBAAkB,iBAAiB,aAAa,UAAU,iBAAiB,WAAW;CACtK;AACF;;;;;;;;;AAUA,SAAgB,cAAc,UAAsB,UAAkC;CACpF,MAAM,SAAS,SAAS,QAAQ;CAChC,MAAM,iBAAiB,iBAAiB,MAAM;CAE9C,IAAI,CAAC,gBACH,OAAO;EACL,MAAM;EACN,eACE,yDAAyD,OAAO,KAAK;CACzE;CAGF,MAAM,OAAO,eAAe,MAAM;CAElC,IAAI,CAAC,MAAM;EACT,MAAM,QAAQ,OAAO,KAAK,eAAe,KAAK,CAAC,CAAC,KAAK,IAAI;EACzD,OAAO;GACL,MAAM;GACN,eACE,qCAAqC,SAAS,oBAAoB,MAAM;EAC5E;CACF;CAEA,MAAM,OAAO,KAAK,WAAW;CAE7B,OAAO;EACL;EACA,eACE,OACI,kBAAkB,SAAS,mCAC3B,kBAAkB,SAAS,iCAAiC,KAAK,OAAO;CAChF;AACF;;;;;;;;;;;;;;AAqBA,SAAgB,iBACd,UACA,QACgB;CAChB,MAAM,OAAO,SAAS;CAEtB,IAAI,SAAS,QACX,OAAO;EACL,MAAM;EACN,eAAe;CACjB;CAGF,MAAM,aAAa,OAAO,YAAY,CAAC,SAAS,IAAI;CAEpD,IAAI,sBAAsB,SACxB,OAAO;EACL,MAAM;EACN,eACE;CACJ;CAGF,MAAM,OAAO,WAAW,WAAW;CAEnC,OAAO;EACL;EACA,eAAe;GACb,IAAI,MACF,OAAO;GAIT,OAAO,qEADU,WAAW,UAAU,CAAC,EAAC,CAAE,KAAK,UAAU,MAAM,OAAO,CAAC,CAAC,KAAK,IACI;EACnF;CACF;AACF"}

package/esm/testing/matchers.d.mts

@@ -0,0 +1,48 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../@warlock.js/ai/src/testing/matchers.d.ts
+/**
+ * Custom Vitest matchers over the unified `@warlock.js/ai` report tree.
+ *
+ * - `toRouteTo(intent)` — a supervisor dispatched the named intent.
+ * - `toConverge()` — a supervisor terminated cleanly on its own
+ *   decision (not max-iterations / cancelled / error).
+ * - `toPassStep(name)` — a workflow step completed successfully.
+ * - `toOutputShape(schema)` — a result's `data` validates against a
+ *   Standard Schema.
+ *
+ * @example
+ * import { registerAiMatchers } from "@warlock.js/ai";
+ * registerAiMatchers();
+ *
+ * expect(await supervisor.execute(input)).toRouteTo("critic");
+ * expect(await supervisor.execute(input)).toConverge();
+ * expect(await workflow.execute(input)).toPassStep("draft");
+ * expect(await agent.execute(input, { output: schema })).toOutputShape(schema);
+ */
+interface AiMatchers<R = unknown> {
+  /** Assert a supervisor dispatched the named intent across its run. */
+  toRouteTo(intent: string): R;
+  /** Assert a supervisor terminated cleanly on its own decision. */
+  toConverge(): R;
+  /** Assert a named workflow step completed successfully. */
+  toPassStep(stepName: string): R;
+  /** Assert a result's `data` validates against a Standard Schema. */
+  toOutputShape(schema: StandardSchemaV1): R;
+}
+declare module "vitest" {
+  interface Matchers<T = any> extends AiMatchers<T> {}
+}
+/**
+ * Register the `@warlock.js/ai` custom matchers on Vitest's global
+ * `expect`. Call once per test file (or in a shared import) before
+ * using `toRouteTo` / `toConverge` / `toPassStep` / `toOutputShape`.
+ * Idempotent — repeated calls are a no-op.
+ *
+ * @example
+ * import { registerAiMatchers } from "@warlock.js/ai";
+ * registerAiMatchers();
+ */
+//#endregion
+export { AiMatchers };
+//# sourceMappingURL=matchers.d.mts.map

package/esm/testing/matchers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/testing/matchers.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;;;UAAiB,UAAA;EAMe;EAJ9B,SAAA,CAAU,MAAA,WAAiB,CAAA;EAML;EAJtB,UAAA,IAAc,CAAA;EAI2B;EAFzC,UAAA,CAAW,QAAA,WAAmB,CAAA;EAEY;EAA1C,aAAA,CAAc,MAAA,EAAQ,gBAAA,GAAmB,CAAA;AAAA;AAAA;EAAA,UAQ/B,QAAA,kBAA0B,UAAU,CAAC,CAAA;AAAA;;;;;AAAC"}