@warlock.js/core 4.3.0 → 4.5.0

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

@@ -0,0 +1,57 @@
+import { renderPlaceholders } from "./render-placeholders.mjs";
+
+//#region ../@warlock.js/ai/src/system-prompt/persona.ts
+/**
+* Concrete `PersonaContract` — a reusable "who the agent is" block.
+*
+* **Role.** A single addressable prompt block representing the agent's
+* identity (`"You are Alex, a senior TypeScript engineer."`). Exists as
+* its own type so personas can be defined once and reused across many
+* `SystemPrompt` compositions, agents, and sessions — each render can
+* supply a different placeholder map.
+*
+* **Responsibility.**
+* - Owns: the `type: "persona"` discriminator, the raw template text, and
+*   the placeholder-rendering step.
+* - Does NOT own: composition with instructions, ordering, joining, or
+*   any knowledge of the surrounding `SystemPrompt`. Those concerns live
+*   in `SystemPrompt`.
+*
+* Users construct via the `ai.persona()` factory — `new Persona()` is not
+* the public API (see §4.2 of code-style.md).
+*
+* @example
+* const alex = ai.persona("You are Alex, a TypeScript expert.");
+*
+* const prompt = ai.systemPrompt()
+*   .persona(alex)
+*   .instruction("Always cite sources.");
+*/
+var Persona = class {
+	constructor(text) {
+		this.text = text;
+		this.type = "persona";
+	}
+	/**
+	* Substitute `{{mustache}}` placeholders in the persona text against the
+	* supplied map. Delegates to the shared `renderPlaceholders` helper so
+	* persona / instruction / system-prompt rendering stays identical.
+	*/
+	resolve(placeholders) {
+		return renderPlaceholders(this.text, placeholders);
+	}
+};
+/**
+* Create a `Persona` from raw template text.
+*
+* @example
+* const alex = persona("You are Alex, a TypeScript expert.");
+* const greeter = persona("You are a greeter in {{language|English}}.");
+*/
+function persona(text) {
+	return new Persona(text);
+}
+
+//#endregion
+export { Persona, persona };
+//# sourceMappingURL=persona.mjs.map

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

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

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

@@ -0,0 +1,58 @@
+//#region ../@warlock.js/ai/src/system-prompt/render-placeholders.ts
+const PLACEHOLDER_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/g;
+/**
+* Render a template string against a placeholders map, supporting dot-path
+* lookups and inline fallback values.
+*
+* Supported syntax:
+* - `{{key}}` — replaced by `placeholders.key`, left untouched if missing.
+* - `{{a.b.c}}` — dot-path lookup into nested objects.
+* - `{{key|default}}` — substitutes `default` when the key resolves to
+*   `undefined`, `null`, or empty string.
+*
+* Whitespace inside the braces is ignored (`{{ key }}` == `{{key}}`).
+* Values are coerced to strings via `String(value)`.
+*
+* @example
+* renderPlaceholders(
+*   "Hello {{user.name|friend}}, your role is {{role}}",
+*   { user: { name: "Hasan" }, role: "admin" },
+* );
+* // "Hello Hasan, your role is admin"
+*
+* @example
+* renderPlaceholders("Hello {{user.name|friend}}", {});
+* // "Hello friend"
+*/
+function renderPlaceholders(template, placeholders = {}) {
+	return template.replace(PLACEHOLDER_PATTERN, (match, rawExpression) => {
+		const [rawPath, rawFallback] = rawExpression.split("|");
+		const path = rawPath.trim();
+		const fallback = rawFallback?.trim();
+		const value = lookupPath(placeholders, path);
+		if (value === void 0 || value === null || value === "") {
+			if (fallback !== void 0) return fallback;
+			return match;
+		}
+		return String(value);
+	});
+}
+/**
+* Walk a dot-path (`"a.b.c"`) through an arbitrary record, returning the
+* leaf value or `undefined` when any segment is missing or blocks traversal
+* (non-object). Never throws.
+*/
+function lookupPath(source, path) {
+	const segments = path.split(".");
+	let current = source;
+	for (const segment of segments) {
+		if (current === null || current === void 0) return;
+		if (typeof current !== "object") return;
+		current = current[segment];
+	}
+	return current;
+}
+
+//#endregion
+export { renderPlaceholders };
+//# sourceMappingURL=render-placeholders.mjs.map

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

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

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

@@ -0,0 +1,267 @@
+import { InvalidRequestError } from "../errors/invalid-request-error.mjs";
+import "../errors/index.mjs";
+import { Instruction } from "./instruction.mjs";
+import { Persona } from "./persona.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);
+	}
+};
+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

@@ -0,0 +1 @@
+{"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  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\";\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/**\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

@@ -0,0 +1,48 @@
+//#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

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

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

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

@@ -0,0 +1,94 @@
+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

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