@warlock.js/core 4.7.0 → 4.8.1

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

@@ -1 +0,0 @@
-{"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/ai/src/system-prompt/system-prompt.mjs

@@ -1,286 +0,0 @@
-import { InvalidRequestError } from "../errors/invalid-request-error.mjs";
-import "../errors/index.mjs";
-import { Instruction } from "./instruction.mjs";
-import { Persona } from "./persona.mjs";
-import { RefinedSystemPrompt } from "./refined-system-prompt.mjs";
-import { defaultPromptsManager, promptKey } from "../prompts/prompts-manager.mjs";
-import { readFileSync } from "node:fs";
-
-//#region ../@warlock.js/ai/src/system-prompt/system-prompt.ts
-/**
-* Monotonic source of the internal, non-registry display id every
-* `SystemPrompt` carries. Anonymous (unnamed) prompts have nothing else to
-* identify them by; this id never feeds the registry and is never derived from
-* the wall clock, so it stays stable and order-deterministic across a run.
-*/
-let displayIdCounter = 0;
-/**
-* Narrow an arbitrary value to a `SystemPromptContract` — true when it exposes
-* the builder surface (`blocks` array + a callable `resolve`). Used by the
-* registry-aware `merge` overload to tell a folded contract from a raw block
-* or a registry name string, robustly across duplicate package copies.
-*/
-function isSystemPromptContract(value) {
-	return typeof value === "object" && value !== null && Array.isArray(value.blocks) && typeof value.resolve === "function";
-}
-/**
-* Build the deterministic provenance label for a prompt — `name@version` when
-* it is registered, otherwise its internal display id. No random suffixes, so
-* the same source always yields the same `composedFrom` entry.
-*/
-function provenanceLabel(prompt) {
-	const meta = prompt.meta();
-	if (meta?.name) return promptKey(meta.name, meta.version ?? "1");
-	return prompt instanceof SystemPrompt ? prompt.id : "anonymous";
-}
-/**
-* Concrete `SystemPromptContract` — an immutable layered prompt builder.
-*
-* **Role.** The top-level composer for a system prompt: it holds an ordered
-* list of typed blocks (persona + instructions) and resolves the whole
-* stack into one final string when the agent is about to call the model.
-*
-* **Responsibility.**
-* - Owns: the ordered `blocks` list and the block-join rules (insertion
-*   order, blank-line separator, trim).
-* - Does NOT own: how any individual block is rendered (delegated to each
-*   block's `resolve()`), the placeholder syntax (delegated to
-*   `renderPlaceholders`), or any knowledge of the agent, model, or
-*   session consuming the resolved text.
-*
-* Blocks are discriminated by a string `type` tag (`"persona"` /
-* `"instruction"`) rather than `instanceof`, so user-supplied blocks that
-* implement `SystemPromptBlockContract` interoperate seamlessly with blocks
-* built via `ai.persona()` / `ai.instruction()` — even across duplicate
-* package copies or bundler scope boundaries.
-*
-* The builder is **immutable** — every `.persona()` / `.instruction()`
-* call returns a fresh `SystemPrompt` instance sharing nothing mutable
-* with its parent. This makes forking a base prompt into specialized
-* variants a safe, side-effect-free operation.
-*
-* Users construct via the `ai.systemPrompt()` factory — `new SystemPrompt()`
-* is not the public API (see §4.2 of code-style.md). Modeled as a class so
-* that methods live on the prototype (one copy shared across every forked
-* instance) and downstream code can branch via `instanceof SystemPrompt`.
-*
-* @example
-* // Chainable form
-* const alex = ai.persona("You are Alex, a TypeScript expert.");
-* const replyIn = ai.instruction("Respond in {{language|English}}.");
-*
-* const base = ai.systemPrompt().persona(alex).instruction(replyIn);
-* const arabicVariant = base.instruction("Prefer Arabic comments.");
-*
-* base.resolve({ language: "English" });
-* arabicVariant.resolve({ language: "Arabic" });
-*
-* @example
-* // Array form — insertion order is preserved exactly
-* const prompt = ai.systemPrompt([
-*   ai.persona("You are Alex, a TypeScript expert."),
-*   ai.instruction("Respond in {{language|English}}."),
-* ]);
-*/
-var SystemPrompt = class SystemPrompt {
-	constructor(blocks = [], metaData) {
-		this.blocks = blocks;
-		this.metaData = metaData;
-		this.id = `prompt#${displayIdCounter++}`;
-		if (metaData?.name) defaultPromptsManager().register(this);
-	}
-	meta(meta) {
-		if (meta === void 0) return this.metaData;
-		return new SystemPrompt(this.blocks, {
-			...this.metaData,
-			...meta
-		});
-	}
-	/**
-	* 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
-	* default for chain-built prompts. Accepts either raw text (auto-wrapped
-	* via `new Persona`) or an existing `PersonaContract` instance for reuse
-	* across prompts.
-	*/
-	persona(value) {
-		const block = typeof value === "string" ? new Persona(value) : value;
-		const existingIndex = this.blocks.findIndex((candidate) => candidate.type === "persona");
-		if (existingIndex >= 0) {
-			const next = [...this.blocks];
-			next[existingIndex] = block;
-			return new SystemPrompt(next);
-		}
-		return new SystemPrompt([block, ...this.blocks]);
-	}
-	/**
-	* Return a new builder with the given instruction appended. Instructions
-	* render in insertion order. Accepts either raw text (auto-wrapped via
-	* `new Instruction`) or an existing `InstructionContract` instance for
-	* cross-prompt reuse.
-	*/
-	instruction(value) {
-		const block = typeof value === "string" ? new Instruction(value) : value;
-		return new SystemPrompt([...this.blocks, block]);
-	}
-	merge(first, ...rest) {
-		if (typeof first === "string") {
-			const options = rest[0];
-			const resolved = defaultPromptsManager().get(first, options?.fromVersion);
-			return this.mergeContract(resolved);
-		}
-		if (isSystemPromptContract(first)) return this.mergeContract(first);
-		const all = [...first ? [first] : [], ...rest];
-		return this.foldBlocks(this, all);
-	}
-	/**
-	* Fold an ordered list of blocks onto a starting prompt: persona blocks
-	* set/replace the single leading persona; every other block appends in
-	* order. The shared core of the variadic-block `merge` and the contract fold.
-	*/
-	foldBlocks(start, blocks) {
-		return blocks.reduce((prompt, block) => {
-			if (block.type === "persona") return prompt.persona(block);
-			return new SystemPrompt([...prompt.blocks, block]);
-		}, start);
-	}
-	/**
-	* Fold another prompt contract into this one (persona replaces, instructions
-	* append) and stamp the deterministic `composedFrom` provenance — this
-	* prompt's existing provenance (or its own label) followed by the folded
-	* source's label. The result is anonymous so it never auto-registers.
-	*/
-	mergeContract(source) {
-		const folded = this.foldBlocks(this, source.blocks);
-		const composedFrom = [...this.metaData?.composedFrom ?? (this.metaData?.name ? [provenanceLabel(this)] : []), provenanceLabel(source)];
-		return new SystemPrompt(folded.blocks, { composedFrom });
-	}
-	/**
-	* Resolve every block against the placeholder map, join the results with
-	* blank-line separators (in insertion order), and trim. Returns an empty
-	* string when no blocks are present — callers treat that as "no system
-	* message".
-	*/
-	resolve(placeholders) {
-		return this.blocks.map((block) => block.resolve(placeholders)).join("\n\n").trim();
-	}
-	/**
-	* Validate this prompt via the process-wide `ai.prompts` manager — sugar for
-	* `ai.prompts.validate(this, options)`. Runs the deterministic placeholder
-	* check and, when `options.judge` is supplied, the Nova-safe LLM-as-judge
-	* pass. Never throws on a judge failure; `ok` tracks the deterministic
-	* verdict alone.
-	*/
-	validate(options) {
-		return defaultPromptsManager().validate(this, options);
-	}
-	/**
-	* Derive the compiled form of this prompt — a lazy wrapper that rewrites
-	* the human-authored text into a model-optimized version on first use,
-	* pins the result, and serves the pin thereafter. See
-	* {@link RefinedSystemPromptContract} for the full semantics (lockfile
-	* pinning, placeholder parity, advisory fallback, `refine()` /
-	* `refinePrompt()`).
-	*
-	* The wrapper's collaborators are injected here rather than imported by
-	* `refined-system-prompt.ts` — importing this module (or the prompts
-	* manager) back from there would close an import cycle.
-	*/
-	refined(options) {
-		return new RefinedSystemPrompt(this, options, {
-			buildPrompt: (blocks, meta) => new SystemPrompt([...blocks], meta),
-			validatePrompt: (target, validateOptions) => defaultPromptsManager().validate(target, validateOptions)
-		});
-	}
-};
-function systemPromptFactory(input, meta) {
-	if (input === void 0) return new SystemPrompt([], meta);
-	if (typeof input === "string") return new SystemPrompt([new Instruction(input)], meta);
-	return new SystemPrompt([...input], meta);
-}
-/**
-* Create a new immutable system-prompt builder.
-*
-* **Role.** Public factory for `SystemPrompt` — keeps user-facing code
-* free of `new` and consistent with `ai.tool()`, `ai.agent()`,
-* `ai.persona()`, `ai.instruction()`.
-*
-* 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
-*
-* Pass a second `meta` argument to name the prompt — a named prompt
-* auto-registers in `ai.prompts` under `name@version` (version defaults to the
-* next integer). Forks (`.persona()`, `.instruction()`, `.merge()`) are
-* anonymous unless re-named via `.meta({ name })`.
-*
-* @example
-* // Composed builder
-* const prompt = systemPrompt()
-*   .persona("You are Alex, a senior TypeScript engineer.")
-*   .instruction("Always include working code examples.")
-*   .instruction("Respond in {{language|English}}.");
-*
-* prompt.resolve({ language: "Arabic" });
-*
-* @example
-* // One-shot seed
-* 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."),
-*   ai.instruction("Always cite sources."),
-*   ai.instruction("Respond in {{language|English}}."),
-* ]);
-*/
-const systemPrompt = Object.assign(systemPromptFactory, { fromFile: SystemPrompt.fromFile });
-
-//#endregion
-export { SystemPrompt, systemPrompt };
-//# sourceMappingURL=system-prompt.mjs.map

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

@@ -1 +0,0 @@
-{"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  RefinedSystemPromptContract,\n  RefinedSystemPromptOptions,\n  SystemPromptBlockContract,\n  SystemPromptContract,\n  SystemPromptMergeOptions,\n  SystemPromptMeta,\n} from \"../contracts/system-prompt.contract\";\nimport { InvalidRequestError } from \"../errors\";\nimport { defaultPromptsManager, promptKey } from \"../prompts/prompts-manager\";\nimport type {\n  PromptValidationResult,\n  PromptsValidateOptions,\n} from \"../prompts/prompts-manager.type\";\nimport { Instruction } from \"./instruction\";\nimport { Persona } from \"./persona\";\nimport { RefinedSystemPrompt } from \"./refined-system-prompt\";\n\n/**\n * Monotonic source of the internal, non-registry display id every\n * `SystemPrompt` carries. Anonymous (unnamed) prompts have nothing else to\n * identify them by; this id never feeds the registry and is never derived from\n * the wall clock, so it stays stable and order-deterministic across a run.\n */\nlet displayIdCounter = 0;\n\n/**\n * Narrow an arbitrary value to a `SystemPromptContract` — true when it exposes\n * the builder surface (`blocks` array + a callable `resolve`). Used by the\n * registry-aware `merge` overload to tell a folded contract from a raw block\n * or a registry name string, robustly across duplicate package copies.\n */\nfunction isSystemPromptContract(\n  value: unknown,\n): value is SystemPromptContract {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    Array.isArray((value as { blocks?: unknown }).blocks) &&\n    typeof (value as { resolve?: unknown }).resolve === \"function\"\n  );\n}\n\n/**\n * Build the deterministic provenance label for a prompt — `name@version` when\n * it is registered, otherwise its internal display id. No random suffixes, so\n * the same source always yields the same `composedFrom` entry.\n */\nfunction provenanceLabel(prompt: SystemPromptContract): string {\n  const meta = prompt.meta();\n\n  if (meta?.name) {\n    return promptKey(meta.name, meta.version ?? \"1\");\n  }\n\n  return prompt instanceof SystemPrompt ? prompt.id : \"anonymous\";\n}\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  /**\n   * Internal, non-registry id for display / provenance. Stable for the life of\n   * the instance; sourced from a monotonic counter, never the wall clock.\n   * Anonymous prompts are identified solely by this id.\n   */\n  public readonly id: string;\n\n  public constructor(\n    public readonly blocks: readonly SystemPromptBlockContract[] = [],\n    private readonly metaData?: SystemPromptMeta,\n  ) {\n    this.id = `prompt#${displayIdCounter++}`;\n\n    // Auto-register the moment a builder acquires a name — whether through the\n    // `systemPrompt(input, { name })` factory or a `.meta({ name })` rename.\n    // Forks built by `persona()` / `instruction()` / `merge()` deliberately\n    // drop the name (they pass no meta), so they stay anonymous and never land\n    // in the registry unless explicitly re-named.\n    if (metaData?.name) {\n      defaultPromptsManager().register(this);\n    }\n  }\n\n  /**\n   * Read the current metadata snapshot (no argument) or derive a renamed\n   * builder (with `meta`). The accessor returns `undefined` for an anonymous\n   * prompt; the updater shallow-merges `meta` onto the current metadata and\n   * returns a fresh builder. Naming the result registers it in `ai.prompts`.\n   */\n  public meta(): SystemPromptMeta | undefined;\n  public meta(meta: SystemPromptMeta): SystemPromptContract;\n  public meta(\n    meta?: SystemPromptMeta,\n  ): SystemPromptMeta | undefined | SystemPromptContract {\n    if (meta === undefined) {\n      return this.metaData;\n    }\n\n    return new SystemPrompt(this.blocks, { ...this.metaData, ...meta });\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   * Fold predefined blocks, another prompt contract, or a registered prompt\n   * name into this builder. Three forms share one method:\n   *\n   * - `merge(...blocks)` — N pre-built `ai.persona()` / `ai.instruction()`\n   *   blocks. A `persona` block sets/replaces the single, leading persona;\n   *   every other block appends in order. `base.merge(reviewer, style, lang)`\n   *   equals `base.persona(reviewer).instruction(style).instruction(lang)`.\n   * - `merge(contract)` — another prompt; its blocks fold in (persona\n   *   replaces, instructions append) and `meta.composedFrom` records the\n   *   provenance of both sides.\n   * - `merge(name, { fromVersion })` — a prompt resolved from `ai.prompts`\n   *   (latest version unless `fromVersion` selects another); throws\n   *   `InvalidRequestError` when the name / version is unregistered.\n   *\n   * Immutable — the original builder is untouched; passing zero blocks returns\n   * an equivalent builder. The folded result is anonymous (no `name`), so it\n   * is never auto-registered even though it carries `composedFrom` provenance.\n   */\n  public merge(\n    ...blocks: readonly SystemPromptBlockContract[]\n  ): SystemPromptContract;\n  public merge(source: SystemPromptContract): SystemPromptContract;\n  public merge(\n    name: string,\n    options?: SystemPromptMergeOptions,\n  ): SystemPromptContract;\n  public merge(\n    first?:\n      | SystemPromptBlockContract\n      | SystemPromptContract\n      | string,\n    // `undefined` is part of the element union so the `merge(name, options?)`\n    // overload's optional trailing `options?` (i.e. `… | undefined`) stays\n    // assignable to this implementation signature.\n    ...rest: readonly (\n      | SystemPromptBlockContract\n      | SystemPromptMergeOptions\n      | undefined\n    )[]\n  ): SystemPromptContract {\n    // Registry-name form: resolve from ai.prompts at the chosen version.\n    if (typeof first === \"string\") {\n      const options = rest[0] as SystemPromptMergeOptions | undefined;\n      const resolved = defaultPromptsManager().get(first, options?.fromVersion);\n\n      return this.mergeContract(resolved);\n    }\n\n    // Contract form: fold another prompt's blocks + record provenance.\n    if (isSystemPromptContract(first)) {\n      return this.mergeContract(first);\n    }\n\n    // Variadic block form (the original behavior).\n    const all = [\n      ...(first ? [first] : []),\n      ...rest,\n    ] as readonly SystemPromptBlockContract[];\n\n    return this.foldBlocks(this, all);\n  }\n\n  /**\n   * Fold an ordered list of blocks onto a starting prompt: persona blocks\n   * set/replace the single leading persona; every other block appends in\n   * order. The shared core of the variadic-block `merge` and the contract fold.\n   */\n  private foldBlocks(\n    start: SystemPromptContract,\n    blocks: readonly SystemPromptBlockContract[],\n  ): SystemPromptContract {\n    return blocks.reduce<SystemPromptContract>((prompt, block) => {\n      if (block.type === \"persona\") {\n        return prompt.persona(block as PersonaContract);\n      }\n\n      return new SystemPrompt([...prompt.blocks, block]);\n    }, start);\n  }\n\n  /**\n   * Fold another prompt contract into this one (persona replaces, instructions\n   * append) and stamp the deterministic `composedFrom` provenance — this\n   * prompt's existing provenance (or its own label) followed by the folded\n   * source's label. The result is anonymous so it never auto-registers.\n   */\n  private mergeContract(\n    source: SystemPromptContract,\n  ): SystemPromptContract {\n    const folded = this.foldBlocks(this, source.blocks);\n\n    const baseProvenance =\n      this.metaData?.composedFrom ??\n      (this.metaData?.name ? [provenanceLabel(this)] : []);\n\n    const composedFrom = [...baseProvenance, provenanceLabel(source)];\n\n    // Carry forward only provenance — never the name — so the merged result is\n    // a fresh anonymous prompt (immutable rename = new key; original stays).\n    return new SystemPrompt(folded.blocks, { composedFrom });\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   * Validate this prompt via the process-wide `ai.prompts` manager — sugar for\n   * `ai.prompts.validate(this, options)`. Runs the deterministic placeholder\n   * check and, when `options.judge` is supplied, the Nova-safe LLM-as-judge\n   * pass. Never throws on a judge failure; `ok` tracks the deterministic\n   * verdict alone.\n   */\n  public validate(\n    options?: PromptsValidateOptions,\n  ): Promise<PromptValidationResult> {\n    return defaultPromptsManager().validate(this, options);\n  }\n\n  /**\n   * Derive the compiled form of this prompt — a lazy wrapper that rewrites\n   * the human-authored text into a model-optimized version on first use,\n   * pins the result, and serves the pin thereafter. See\n   * {@link RefinedSystemPromptContract} for the full semantics (lockfile\n   * pinning, placeholder parity, advisory fallback, `refine()` /\n   * `refinePrompt()`).\n   *\n   * The wrapper's collaborators are injected here rather than imported by\n   * `refined-system-prompt.ts` — importing this module (or the prompts\n   * manager) back from there would close an import cycle.\n   */\n  public refined(\n    options: RefinedSystemPromptOptions,\n  ): RefinedSystemPromptContract {\n    return new RefinedSystemPrompt(this, options, {\n      buildPrompt: (blocks, meta) => new SystemPrompt([...blocks], meta),\n      validatePrompt: (target, validateOptions) =>\n        defaultPromptsManager().validate(target, validateOptions),\n    });\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  (\n    input?: string | ReadonlyArray<SystemPromptBlockContract>,\n    meta?: SystemPromptMeta,\n  ): 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  meta?: SystemPromptMeta,\n): SystemPrompt {\n  if (input === undefined) {\n    return new SystemPrompt([], meta);\n  }\n\n  if (typeof input === \"string\") {\n    return new SystemPrompt([new Instruction(input)], meta);\n  }\n\n  return new SystemPrompt([...input], meta);\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 * Pass a second `meta` argument to name the prompt — a named prompt\n * auto-registers in `ai.prompts` under `name@version` (version defaults to the\n * next integer). Forks (`.persona()`, `.instruction()`, `.merge()`) are\n * anonymous unless re-named via `.meta({ name })`.\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":"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"}

package/esm/ai/src/team/gates.mjs

@@ -1,48 +0,0 @@
-//#region ../@warlock.js/ai/src/team/gates.ts
-/**
-* Build the `"quality"` gate — a review-then-fix `evaluate` callback.
-*
-* After each iteration's intents settle and merge into supervisor
-* `state`, the gate reads `state[gateKey]`. If truthy the run
-* terminates (`{ satisfied: true }`); otherwise it re-dispatches the
-* fixer with the reviewer feedback (`state[feedbackKey]`) threaded into
-* the next iteration's composed input. No termination or re-dispatch
-* code is written here — it leans entirely on the shipped
-* {@link EvaluateResult} semantics.
-*
-* @param gateKey - State key holding the reviewer verdict. Default `"approved"`.
-* @param fixerRole - Member key the gate reassigns to on rejection. Default `"fixer"`.
-* @param feedbackKey - State key holding reviewer feedback. Default `"notes"`.
-*/
-function buildQualityGate(gateKey = "approved", fixerRole = "fixer", feedbackKey = "notes") {
-	return (ctx) => {
-		const state = ctx.state;
-		if (state[gateKey]) return { satisfied: true };
-		return {
-			reassignTo: fixerRole,
-			feedback: String(state[feedbackKey] ?? "")
-		};
-	};
-}
-/**
-* Build the `"verify"` gate — a test-then-fix `evaluate` callback.
-*
-* Identical in shape to {@link buildQualityGate} but keyed on the
-* tester's pass/fail slice (`state[gateKey]`, default `"passed"`)
-* rather than a subjective reviewer score. On failure it re-dispatches
-* the fixer; there is no feedback channel for the pass/fail signal, so
-* none is threaded forward.
-*
-* @param gateKey - State key holding the pass/fail verdict. Default `"passed"`.
-* @param fixerRole - Member key the gate reassigns to on failure. Default `"fixer"`.
-*/
-function buildVerifyGate(gateKey = "passed", fixerRole = "fixer") {
-	return (ctx) => {
-		if (ctx.state[gateKey]) return { satisfied: true };
-		return { reassignTo: fixerRole };
-	};
-}
-
-//#endregion
-export { buildQualityGate, buildVerifyGate };
-//# sourceMappingURL=gates.mjs.map

package/esm/ai/src/team/gates.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"gates.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/team/gates.ts"],"sourcesContent":["import type { EvaluateContext, EvaluateResult } from \"../contracts/supervisor/evaluate-context.type\";\n\n/**\n * Build the `\"quality\"` gate — a review-then-fix `evaluate` callback.\n *\n * After each iteration's intents settle and merge into supervisor\n * `state`, the gate reads `state[gateKey]`. If truthy the run\n * terminates (`{ satisfied: true }`); otherwise it re-dispatches the\n * fixer with the reviewer feedback (`state[feedbackKey]`) threaded into\n * the next iteration's composed input. No termination or re-dispatch\n * code is written here — it leans entirely on the shipped\n * {@link EvaluateResult} semantics.\n *\n * @param gateKey - State key holding the reviewer verdict. Default `\"approved\"`.\n * @param fixerRole - Member key the gate reassigns to on rejection. Default `\"fixer\"`.\n * @param feedbackKey - State key holding reviewer feedback. Default `\"notes\"`.\n */\nexport function buildQualityGate<TState>(\n  gateKey = \"approved\",\n  fixerRole = \"fixer\",\n  feedbackKey = \"notes\",\n): (ctx: EvaluateContext<TState>) => EvaluateResult {\n  return (ctx) => {\n    const state = ctx.state as Record<string, unknown>;\n\n    if (state[gateKey]) {\n      return { satisfied: true };\n    }\n\n    return { reassignTo: fixerRole, feedback: String(state[feedbackKey] ?? \"\") };\n  };\n}\n\n/**\n * Build the `\"verify\"` gate — a test-then-fix `evaluate` callback.\n *\n * Identical in shape to {@link buildQualityGate} but keyed on the\n * tester's pass/fail slice (`state[gateKey]`, default `\"passed\"`)\n * rather than a subjective reviewer score. On failure it re-dispatches\n * the fixer; there is no feedback channel for the pass/fail signal, so\n * none is threaded forward.\n *\n * @param gateKey - State key holding the pass/fail verdict. Default `\"passed\"`.\n * @param fixerRole - Member key the gate reassigns to on failure. Default `\"fixer\"`.\n */\nexport function buildVerifyGate<TState>(\n  gateKey = \"passed\",\n  fixerRole = \"fixer\",\n): (ctx: EvaluateContext<TState>) => EvaluateResult {\n  return (ctx) => {\n    const state = ctx.state as Record<string, unknown>;\n\n    if (state[gateKey]) {\n      return { satisfied: true };\n    }\n\n    return { reassignTo: fixerRole };\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,SAAgB,iBACd,UAAU,YACV,YAAY,SACZ,cAAc,SACoC;CAClD,QAAQ,QAAQ;EACd,MAAM,QAAQ,IAAI;EAElB,IAAI,MAAM,UACR,OAAO,EAAE,WAAW,KAAK;EAG3B,OAAO;GAAE,YAAY;GAAW,UAAU,OAAO,MAAM,gBAAgB,EAAE;EAAE;CAC7E;AACF;;;;;;;;;;;;;AAcA,SAAgB,gBACd,UAAU,UACV,YAAY,SACsC;CAClD,QAAQ,QAAQ;EAGd,IAFc,IAAI,MAER,UACR,OAAO,EAAE,WAAW,KAAK;EAG3B,OAAO,EAAE,YAAY,UAAU;CACjC;AACF"}

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

@@ -1,3 +0,0 @@
-import { team } from "./team.mjs";
-
-export {  };

package/esm/ai/src/team/team.mjs

@@ -1,94 +0,0 @@
-import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
-import "../errors/index.mjs";
-import { supervisor } from "../supervisor/supervisor.mjs";
-import { buildQualityGate, buildVerifyGate } from "./gates.mjs";
-
-//#region ../@warlock.js/ai/src/team/team.ts
-/**
-* `ai.team(config)` — thin, transparent sugar over `ai.supervisor`.
-*
-* Builds a {@link SupervisorConfig} from the team-shaped config and
-* calls `supervisor(...)`, returning the **unchanged**
-* `SupervisorContract<TOutput>` — the same object `ai.supervisor`
-* returns, so `ctx.intents.<member>.execute()`, `.asTool()`,
-* `.resume()`, snapshots, and events all stay intact. `team()` owns no
-* loop: the manager becomes `route`/`router`, the members become
-* `intents`, and the `gate` becomes `evaluate`. Everything else passes
-* through 1:1.
-*
-* A `gate: "quality" | "verify"` string selects a pre-built `evaluate`
-* strategy ({@link buildQualityGate} / {@link buildVerifyGate}); a
-* function forwards straight to `SupervisorConfig.evaluate` (full
-* escape hatch). When the gate is a string, the resolved `fixer` (and,
-* for `"quality"`, the `reviewer`) roles are validated against
-* `members` at construction — a missing role throws an authoring-style
-* {@link SupervisorFailedError} (`context: { authoring: true }`) rather
-* than silently starving until `maxIterations`.
-*
-* @example
-* const codeTeam = ai.team({
-*   name: "code-team",
-*   goal: "Ship a tested module that passes review.",
-*   manager: techLeadRouter,
-*   members: { builder, reviewer, fixer },
-*   gate: "quality",
-*   output: v.object({ code: v.string() }),
-*   maxIterations: 6,
-* });
-*
-* const { data, report } = await codeTeam.execute("Build a debounce<T> utility.");
-*/
-function team(config) {
-	const supervisorConfig = {
-		name: config.name,
-		version: config.version,
-		reportType: "team",
-		intents: config.members,
-		evaluate: resolveGate(config),
-		goal: config.goal,
-		output: config.output,
-		state: config.state,
-		maxIterations: config.maxIterations,
-		snapshotStore: config.snapshotStore,
-		on: config.on,
-		observe: config.observe
-	};
-	if (isRouteManager(config.manager)) supervisorConfig.route = config.manager.route;
-	else supervisorConfig.router = config.manager;
-	return supervisor(supervisorConfig);
-}
-/**
-* Resolve the team's `gate` into a concrete `evaluate` callback. A
-* function forwards untouched; a {@link TeamGate} string is validated
-* against `members` and desugared into the matching pre-built gate.
-*/
-function resolveGate(config) {
-	if (typeof config.gate === "function") return config.gate;
-	const gate = config.gate;
-	const fixerRole = config.roles?.fixer ?? "fixer";
-	assertMemberExists(config, fixerRole, "fixer");
-	if (gate === "quality") {
-		assertMemberExists(config, config.roles?.reviewer ?? "reviewer", "reviewer");
-		return buildQualityGate(config.gateKey ?? "approved", fixerRole);
-	}
-	return buildVerifyGate(config.gateKey ?? "passed", fixerRole);
-}
-/**
-* Construction-time guard: assert the resolved role key exists in
-* `members`, throwing an authoring-style {@link SupervisorFailedError}
-* (tagged `authoring: true`) listing the missing role when it doesn't.
-*/
-function assertMemberExists(config, role, label) {
-	if (!Object.prototype.hasOwnProperty.call(config.members, role)) throw new SupervisorFailedError(`ai.team("${config.name}"): gate "${config.gate}" needs a "${label}" member but no \`members.${role}\` key exists`, { context: { authoring: true } });
-}
-/**
-* Discriminate the `manager` union: `true` when it is the deterministic
-* `{ route }` form, `false` for a bare `AgentContract` / `RouterEntry`.
-*/
-function isRouteManager(manager) {
-	return typeof manager === "object" && manager !== null && "route" in manager && typeof manager.route === "function";
-}
-
-//#endregion
-export { team };
-//# sourceMappingURL=team.mjs.map

package/esm/ai/src/team/team.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"team.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/team/team.ts"],"sourcesContent":["import type {\n  EvaluateContext,\n  EvaluateResult,\n} from \"../contracts/supervisor/evaluate-context.type\";\nimport type { SupervisorIntentValue } from \"../contracts/supervisor/intent-entry.type\";\nimport type { SupervisorConfig } from \"../contracts/supervisor/supervisor-config.type\";\nimport type { SupervisorContract } from \"../contracts/supervisor/supervisor.contract\";\nimport type {\n  TeamConfig,\n  TeamGate,\n  TeamGateFn,\n  TeamMemberValue,\n} from \"../contracts/team/team-config.type\";\nimport { SupervisorFailedError } from \"../errors\";\nimport { supervisor } from \"../supervisor/supervisor\";\nimport { buildQualityGate, buildVerifyGate } from \"./gates\";\n\n/**\n * `ai.team(config)` — thin, transparent sugar over `ai.supervisor`.\n *\n * Builds a {@link SupervisorConfig} from the team-shaped config and\n * calls `supervisor(...)`, returning the **unchanged**\n * `SupervisorContract<TOutput>` — the same object `ai.supervisor`\n * returns, so `ctx.intents.<member>.execute()`, `.asTool()`,\n * `.resume()`, snapshots, and events all stay intact. `team()` owns no\n * loop: the manager becomes `route`/`router`, the members become\n * `intents`, and the `gate` becomes `evaluate`. Everything else passes\n * through 1:1.\n *\n * A `gate: \"quality\" | \"verify\"` string selects a pre-built `evaluate`\n * strategy ({@link buildQualityGate} / {@link buildVerifyGate}); a\n * function forwards straight to `SupervisorConfig.evaluate` (full\n * escape hatch). When the gate is a string, the resolved `fixer` (and,\n * for `\"quality\"`, the `reviewer`) roles are validated against\n * `members` at construction — a missing role throws an authoring-style\n * {@link SupervisorFailedError} (`context: { authoring: true }`) rather\n * than silently starving until `maxIterations`.\n *\n * @example\n * const codeTeam = ai.team({\n *   name: \"code-team\",\n *   goal: \"Ship a tested module that passes review.\",\n *   manager: techLeadRouter,\n *   members: { builder, reviewer, fixer },\n *   gate: \"quality\",\n *   output: v.object({ code: v.string() }),\n *   maxIterations: 6,\n * });\n *\n * const { data, report } = await codeTeam.execute(\"Build a debounce<T> utility.\");\n */\nexport function team<\n  TOutput = unknown,\n  TState = TOutput,\n  TMembers extends Record<string, TeamMemberValue> = Record<string, TeamMemberValue>,\n>(config: TeamConfig<TOutput, TState, TMembers>): SupervisorContract<TOutput> {\n  const supervisorConfig: SupervisorConfig<TOutput, TState> = {\n    name: config.name,\n    version: config.version,\n    // Stamp the report/result discriminator as \"team\" so team runs are\n    // distinguishable on the wire (Panoptic groups/filters them as their\n    // own type) — the only behavioural difference from a plain supervisor.\n    reportType: \"team\",\n    intents: config.members as unknown as Record<string, SupervisorIntentValue>,\n    evaluate: resolveGate<TOutput, TState, TMembers>(config),\n    goal: config.goal,\n    output: config.output,\n    state: config.state,\n    maxIterations: config.maxIterations,\n    snapshotStore: config.snapshotStore,\n    on: config.on,\n    // Forward observability verbatim — the supervisor `team()` returns\n    // routes its report through the generic Observer seam, so a team\n    // inherits observation with no team-specific wiring (F1/F3).\n    observe: config.observe,\n  };\n\n  // Manager → `route` XOR `router`. Reuse the supervisor's own XOR\n  // validation; team() forwards exactly one of the two, so a malformed\n  // manager surfaces the existing SupervisorFailedError downstream.\n  if (isRouteManager(config.manager)) {\n    supervisorConfig.route = config.manager.route;\n  } else {\n    supervisorConfig.router = config.manager;\n  }\n\n  return supervisor<TOutput, TState>(supervisorConfig);\n}\n\n/**\n * Resolve the team's `gate` into a concrete `evaluate` callback. A\n * function forwards untouched; a {@link TeamGate} string is validated\n * against `members` and desugared into the matching pre-built gate.\n */\nfunction resolveGate<\n  TOutput,\n  TState,\n  TMembers extends Record<string, TeamMemberValue>,\n>(\n  config: TeamConfig<TOutput, TState, TMembers>,\n): (ctx: EvaluateContext<TState>) => EvaluateResult | Promise<EvaluateResult> {\n  if (typeof config.gate === \"function\") {\n    return config.gate as TeamGateFn<TState>;\n  }\n\n  const gate: TeamGate = config.gate;\n  const fixerRole = config.roles?.fixer ?? \"fixer\";\n\n  assertMemberExists(config, fixerRole, \"fixer\");\n\n  if (gate === \"quality\") {\n    const reviewerRole = config.roles?.reviewer ?? \"reviewer\";\n\n    assertMemberExists(config, reviewerRole, \"reviewer\");\n\n    const gateKey = config.gateKey ?? \"approved\";\n\n    return buildQualityGate<TState>(gateKey, fixerRole);\n  }\n\n  const gateKey = config.gateKey ?? \"passed\";\n\n  return buildVerifyGate<TState>(gateKey, fixerRole);\n}\n\n/**\n * Construction-time guard: assert the resolved role key exists in\n * `members`, throwing an authoring-style {@link SupervisorFailedError}\n * (tagged `authoring: true`) listing the missing role when it doesn't.\n */\nfunction assertMemberExists<\n  TOutput,\n  TState,\n  TMembers extends Record<string, TeamMemberValue>,\n>(\n  config: TeamConfig<TOutput, TState, TMembers>,\n  role: string,\n  label: string,\n): void {\n  if (!Object.prototype.hasOwnProperty.call(config.members, role)) {\n    throw new SupervisorFailedError(\n      `ai.team(\"${config.name}\"): gate \"${config.gate as string}\" needs a \"${label}\" member but no \\`members.${role}\\` key exists`,\n      { context: { authoring: true } },\n    );\n  }\n}\n\n/**\n * Discriminate the `manager` union: `true` when it is the deterministic\n * `{ route }` form, `false` for a bare `AgentContract` / `RouterEntry`.\n */\nfunction isRouteManager<TOutput, TState>(\n  manager: TeamConfig<TOutput, TState>[\"manager\"],\n): manager is { route: NonNullable<SupervisorConfig<TOutput, TState>[\"route\"]> } {\n  return (\n    typeof manager === \"object\" &&\n    manager !== null &&\n    \"route\" in manager &&\n    typeof (manager as { route?: unknown }).route === \"function\"\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,SAAgB,KAId,QAA4E;CAC5E,MAAM,mBAAsD;EAC1D,MAAM,OAAO;EACb,SAAS,OAAO;EAIhB,YAAY;EACZ,SAAS,OAAO;EAChB,UAAU,YAAuC,MAAM;EACvD,MAAM,OAAO;EACb,QAAQ,OAAO;EACf,OAAO,OAAO;EACd,eAAe,OAAO;EACtB,eAAe,OAAO;EACtB,IAAI,OAAO;EAIX,SAAS,OAAO;CAClB;CAKA,IAAI,eAAe,OAAO,OAAO,GAC/B,iBAAiB,QAAQ,OAAO,QAAQ;MAExC,iBAAiB,SAAS,OAAO;CAGnC,OAAO,WAA4B,gBAAgB;AACrD;;;;;;AAOA,SAAS,YAKP,QAC4E;CAC5E,IAAI,OAAO,OAAO,SAAS,YACzB,OAAO,OAAO;CAGhB,MAAM,OAAiB,OAAO;CAC9B,MAAM,YAAY,OAAO,OAAO,SAAS;CAEzC,mBAAmB,QAAQ,WAAW,OAAO;CAE7C,IAAI,SAAS,WAAW;EAGtB,mBAAmB,QAFE,OAAO,OAAO,YAAY,YAEN,UAAU;EAInD,OAAO,iBAFS,OAAO,WAAW,YAEO,SAAS;CACpD;CAIA,OAAO,gBAFS,OAAO,WAAW,UAEM,SAAS;AACnD;;;;;;AAOA,SAAS,mBAKP,QACA,MACA,OACM;CACN,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,SAAS,IAAI,GAC5D,MAAM,IAAI,sBACR,YAAY,OAAO,KAAK,YAAY,OAAO,KAAe,aAAa,MAAM,4BAA4B,KAAK,gBAC9G,EAAE,SAAS,EAAE,WAAW,KAAK,EAAE,CACjC;AAEJ;;;;;AAMA,SAAS,eACP,SAC+E;CAC/E,OACE,OAAO,YAAY,YACnB,YAAY,QACZ,WAAW,WACX,OAAQ,QAAgC,UAAU;AAEtD"}

package/esm/ai/src/tool/executable-as-tool.mjs

@@ -1,81 +0,0 @@
-import { AgentExecutionError } from "../errors/agent-execution-error.mjs";
-import "../errors/index.mjs";
-import { compositeAsTool } from "./tool.mjs";
-
-//#region ../@warlock.js/ai/src/tool/executable-as-tool.ts
-/**
-* Identity passthrough schema used when an executable is registered as
-* a tool without declaring an `inputSchema`. The model's raw arguments
-* flow straight to `execute()` unchanged — the executable validates
-* internally (workflows via their steps, supervisors/agents via their
-* own input handling).
-*/
-function passthroughSchema() {
-	return { "~standard": {
-		version: 1,
-		vendor: "warlock-ai",
-		validate: (value) => ({ value })
-	} };
-}
-/**
-* Type guard distinguishing a raw executable primitive from a built
-* `ToolContract`. An executable exposes `execute()` and no `invoke()`;
-* a `ToolContract` exposes `invoke()`. The `invoke` check is the
-* load-bearing discriminator — `.asTool()`-wrapped composites keep
-* their own `execute` too, so checking `execute` alone is insufficient.
-*/
-function isExecutableTool(entry) {
-	if (!entry || typeof entry !== "object") return false;
-	const candidate = entry;
-	return typeof candidate.execute === "function" && typeof candidate.invoke !== "function";
-}
-/**
-* Adapt a raw executable primitive (agent / workflow / supervisor) into
-* a `ToolContract` so an agent can dispatch it inside its tool-call
-* loop WITHOUT the caller writing `.asTool()`. Derives the LLM tool
-* manifest from the executable's own `name` + `description` +
-* (optional) `inputSchema`, then dispatches through the executable's
-* `execute()` — the inner report nests under the outer tool-call node
-* exactly like an explicit `.asTool()` wrapper.
-*
-* Throws `AgentExecutionError` at author time when the executable lacks
-* a usable `name` — the agent's tool surface needs a stable id, the
-* same constraint `.asTool()` enforces.
-*/
-function executableToTool(executable) {
-	if (!executable.name || typeof executable.name !== "string") throw new AgentExecutionError("tools[]: an executable (agent/workflow/supervisor) used as a tool must have a `name`", { context: { authoring: true } });
-	return compositeAsTool({
-		name: executable.name,
-		description: executable.description ?? `Invoke "${executable.name}" as a tool.`,
-		input: executable.inputSchema ?? passthroughSchema(),
-		execute: async (input, ctx) => {
-			const result = await executable.execute(input, ctx?.signal ? { signal: ctx.signal } : void 0);
-			if (result.error) throw result.error;
-			return {
-				data: result.data,
-				usage: result.usage,
-				report: result.report
-			};
-		}
-	});
-}
-/**
-* Normalize an agent's `tools: []` array into a uniform
-* `ToolContract[]` for the runtime. Already-built `ToolContract`s
-* (`.asTool()` / `ai.tool()`) pass through untouched; raw executable
-* primitives are auto-adapted via {@link executableToTool}.
-*
-* Returns `undefined` when no tools were supplied so the agent's
-* existing `config.tools ?? []` fallbacks stay byte-identical.
-*/
-function normalizeAgentTools(tools) {
-	if (!tools) return;
-	return tools.map((entry) => {
-		if (isExecutableTool(entry)) return executableToTool(entry);
-		return entry;
-	});
-}
-
-//#endregion
-export { executableToTool, isExecutableTool, normalizeAgentTools };
-//# sourceMappingURL=executable-as-tool.mjs.map

package/esm/ai/src/tool/executable-as-tool.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"executable-as-tool.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/tool/executable-as-tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { BaseResult } from \"../contracts/result/base-result.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AgentExecutionError, type AIError } from \"../errors\";\nimport { compositeAsTool, type ToolContract } from \"./tool\";\n\n/**\n * Envelope every executable's `execute()` resolves to. Agent, workflow,\n * and supervisor results all satisfy this shape — `data` / `error`\n * carry the outcome while `usage` and `report` are always present —\n * which is exactly what {@link compositeAsTool} needs to nest the inner\n * run under the outer tool-call node.\n */\ntype ExecutableEnvelope<TOutput> = BaseResult & {\n  data?: TOutput;\n  error?: AIError;\n  report: BaseReport;\n};\n\n/**\n * Structural view of an executable primitive (agent / workflow /\n * supervisor) when it is dropped straight into an agent's `tools: []`\n * array WITHOUT being wrapped via `.asTool()` first.\n *\n * Only the fields the auto-adapt path reads are declared:\n * - `name` — becomes the LLM tool name (required; anonymous executables\n *   are rejected at author time, mirroring `.asTool()`).\n * - `description` — the \"when would the model pick this?\" line.\n * - `inputSchema` — opt-in Standard Schema typing the tool's arguments.\n *   Surfaced on `WorkflowInstance` / `SupervisorContract` from the new\n *   optional `inputSchema` config field. Absent for agents (which take\n *   a plain string prompt).\n * - `execute` — the dispatch entry every `ExecutableContract` exposes.\n *\n * `invoke` is declared `never` so a `ToolContract` (which HAS `invoke`)\n * can never be mistaken for an executable by the {@link isExecutableTool}\n * guard.\n */\nexport type ExecutableTool<TInput = unknown, TOutput = unknown> = {\n  readonly name: string;\n  readonly description?: string;\n  readonly inputSchema?: StandardSchemaV1<TInput>;\n  execute(input: TInput, options?: unknown): Promise<ExecutableEnvelope<TOutput>>;\n  invoke?: never;\n};\n\n/**\n * Entry accepted in an agent's `tools: []` array — either an already-\n * built `ToolContract` (the `.asTool()` / `ai.tool()` path) or a raw\n * executable primitive the framework auto-adapts on the caller's\n * behalf.\n */\nexport type AgentToolEntry<TInput = unknown, TOutput = unknown> =\n  | ToolContract<TInput, TOutput>\n  | ExecutableTool<TInput, TOutput>;\n\n/**\n * Identity passthrough schema used when an executable is registered as\n * a tool without declaring an `inputSchema`. The model's raw arguments\n * flow straight to `execute()` unchanged — the executable validates\n * internally (workflows via their steps, supervisors/agents via their\n * own input handling).\n */\nfunction passthroughSchema<TInput>(): StandardSchemaV1<TInput> {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-ai\",\n      validate: (value: unknown) => ({ value: value as TInput }),\n    },\n  };\n}\n\n/**\n * Type guard distinguishing a raw executable primitive from a built\n * `ToolContract`. An executable exposes `execute()` and no `invoke()`;\n * a `ToolContract` exposes `invoke()`. The `invoke` check is the\n * load-bearing discriminator — `.asTool()`-wrapped composites keep\n * their own `execute` too, so checking `execute` alone is insufficient.\n */\nexport function isExecutableTool(entry: unknown): entry is ExecutableTool {\n  if (!entry || typeof entry !== \"object\") {\n    return false;\n  }\n\n  const candidate = entry as { execute?: unknown; invoke?: unknown };\n\n  return typeof candidate.execute === \"function\" && typeof candidate.invoke !== \"function\";\n}\n\n/**\n * Adapt a raw executable primitive (agent / workflow / supervisor) into\n * a `ToolContract` so an agent can dispatch it inside its tool-call\n * loop WITHOUT the caller writing `.asTool()`. Derives the LLM tool\n * manifest from the executable's own `name` + `description` +\n * (optional) `inputSchema`, then dispatches through the executable's\n * `execute()` — the inner report nests under the outer tool-call node\n * exactly like an explicit `.asTool()` wrapper.\n *\n * Throws `AgentExecutionError` at author time when the executable lacks\n * a usable `name` — the agent's tool surface needs a stable id, the\n * same constraint `.asTool()` enforces.\n */\nexport function executableToTool<TInput, TOutput>(\n  executable: ExecutableTool<TInput, TOutput>,\n): ToolContract<TInput, TOutput> {\n  if (!executable.name || typeof executable.name !== \"string\") {\n    throw new AgentExecutionError(\n      \"tools[]: an executable (agent/workflow/supervisor) used as a tool must have a `name`\",\n      { context: { authoring: true } },\n    );\n  }\n\n  return compositeAsTool<TInput, TOutput>({\n    name: executable.name,\n    description: executable.description ?? `Invoke \"${executable.name}\" as a tool.`,\n    input: executable.inputSchema ?? passthroughSchema<TInput>(),\n    execute: async (input, ctx) => {\n      // Relay the outer run's cancellation signal so a cancelled parent\n      // aborts this nested agent/workflow/supervisor (C2). Omit the\n      // options object entirely when there's no signal so primitives that\n      // treat any second arg as meaningful stay byte-identical.\n      const result = await executable.execute(\n        input,\n        ctx?.signal ? { signal: ctx.signal } : undefined,\n      );\n\n      if (result.error) {\n        // Surface the inner typed error so the surrounding\n        // `compositeAsTool` wrapper produces a `ToolExecutionError`\n        // with `cause` pointing back at the original subclass — the\n        // agent's tool-call loop sees one uniform error class\n        // regardless of which primitive failed.\n        throw result.error;\n      }\n\n      return {\n        data: result.data as TOutput,\n        usage: result.usage as Usage,\n        report: result.report,\n      };\n    },\n  });\n}\n\n/**\n * Normalize an agent's `tools: []` array into a uniform\n * `ToolContract[]` for the runtime. Already-built `ToolContract`s\n * (`.asTool()` / `ai.tool()`) pass through untouched; raw executable\n * primitives are auto-adapted via {@link executableToTool}.\n *\n * Returns `undefined` when no tools were supplied so the agent's\n * existing `config.tools ?? []` fallbacks stay byte-identical.\n */\nexport function normalizeAgentTools(\n  tools: ReadonlyArray<AgentToolEntry> | undefined,\n): ToolContract<unknown, unknown>[] | undefined {\n  if (!tools) {\n    return undefined;\n  }\n\n  return tools.map((entry) => {\n    if (isExecutableTool(entry)) {\n      return executableToTool(entry) as ToolContract<unknown, unknown>;\n    }\n\n    return entry as ToolContract<unknown, unknown>;\n  });\n}\n"],"mappings":";;;;;;;;;;;;AAgEA,SAAS,oBAAsD;CAC7D,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,WAAoB,EAAS,MAAgB;CAC1D,EACF;AACF;;;;;;;;AASA,SAAgB,iBAAiB,OAAyC;CACxE,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO;CAGT,MAAM,YAAY;CAElB,OAAO,OAAO,UAAU,YAAY,cAAc,OAAO,UAAU,WAAW;AAChF;;;;;;;;;;;;;;AAeA,SAAgB,iBACd,YAC+B;CAC/B,IAAI,CAAC,WAAW,QAAQ,OAAO,WAAW,SAAS,UACjD,MAAM,IAAI,oBACR,wFACA,EAAE,SAAS,EAAE,WAAW,KAAK,EAAE,CACjC;CAGF,OAAO,gBAAiC;EACtC,MAAM,WAAW;EACjB,aAAa,WAAW,eAAe,WAAW,WAAW,KAAK;EAClE,OAAO,WAAW,eAAe,kBAA0B;EAC3D,SAAS,OAAO,OAAO,QAAQ;GAK7B,MAAM,SAAS,MAAM,WAAW,QAC9B,OACA,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,MACzC;GAEA,IAAI,OAAO,OAMT,MAAM,OAAO;GAGf,OAAO;IACL,MAAM,OAAO;IACb,OAAO,OAAO;IACd,QAAQ,OAAO;GACjB;EACF;CACF,CAAC;AACH;;;;;;;;;;AAWA,SAAgB,oBACd,OAC8C;CAC9C,IAAI,CAAC,OACH;CAGF,OAAO,MAAM,KAAK,UAAU;EAC1B,IAAI,iBAAiB,KAAK,GACxB,OAAO,iBAAiB,KAAK;EAG/B,OAAO;CACT,CAAC;AACH"}

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

@@ -1,4 +0,0 @@
-import { tool } from "./tool.mjs";
-import { executableToTool, isExecutableTool, normalizeAgentTools } from "./executable-as-tool.mjs";
-
-export {  };