@warlock.js/ai 4.1.1

package/esm/system-prompt/instruction.mjs

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

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

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

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

@@ -0,0 +1,52 @@
+import { Placeholders } from "../contracts/placeholders.type.mjs";
+import { PersonaContract } from "../contracts/system-prompt.contract.mjs";
+
+//#region ../../@warlock.js/ai/src/system-prompt/persona.d.ts
+/**
+ * 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.");
+ */
+declare class Persona implements PersonaContract {
+  readonly text: string;
+  readonly type: "persona";
+  constructor(text: string);
+  /**
+   * 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?: Placeholders): string;
+}
+/**
+ * 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}}.");
+ */
+declare function persona(text: string): Persona;
+//#endregion
+export { Persona, persona };
+//# sourceMappingURL=persona.d.mts.map

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

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

package/esm/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/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/system-prompt/render-placeholders.d.mts

@@ -0,0 +1,31 @@
+import { Placeholders } from "../contracts/placeholders.type.mjs";
+
+//#region ../../@warlock.js/ai/src/system-prompt/render-placeholders.d.ts
+/**
+ * Render a template string against a placeholders map, supporting dot-path
+ * lookups and inline fallback values.
+ *
+ * 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"
+ */
+declare function renderPlaceholders(template: string, placeholders?: Placeholders): string;
+//#endregion
+export { renderPlaceholders };
+//# sourceMappingURL=render-placeholders.d.mts.map

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

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

package/esm/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/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/system-prompt/system-prompt.d.mts

@@ -0,0 +1,117 @@
+import { Placeholders } from "../contracts/placeholders.type.mjs";
+import { InstructionContract, PersonaContract, SystemPromptBlockContract, SystemPromptContract } from "../contracts/system-prompt.contract.mjs";
+
+//#region ../../@warlock.js/ai/src/system-prompt/system-prompt.d.ts
+/**
+ * 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}}."),
+ * ]);
+ */
+declare class SystemPrompt implements SystemPromptContract {
+  readonly blocks: readonly SystemPromptBlockContract[];
+  constructor(blocks?: readonly SystemPromptBlockContract[]);
+  /**
+   * 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: PersonaContract | string): SystemPromptContract;
+  /**
+   * 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: InstructionContract | string): SystemPromptContract;
+  /**
+   * 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?: Placeholders): string;
+}
+/**
+ * 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()`.
+ *
+ * Three 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
+ *
+ * @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
+ * // Array form — fully declarative
+ * const prompt = systemPrompt([
+ *   ai.persona("You are Alex."),
+ *   ai.instruction("Always cite sources."),
+ *   ai.instruction("Respond in {{language|English}}."),
+ * ]);
+ */
+declare function systemPrompt(input?: string | ReadonlyArray<SystemPromptBlockContract>): SystemPrompt;
+//#endregion
+export { SystemPrompt, systemPrompt };
+//# sourceMappingURL=system-prompt.d.mts.map

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

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

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

@@ -0,0 +1,137 @@
+import { Instruction } from "./instruction.mjs";
+import { Persona } from "./persona.mjs";
+
+//#region ../../@warlock.js/ai/src/system-prompt/system-prompt.ts
+/**
+* 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 = []) {
+		this.blocks = blocks;
+	}
+	/**
+	* 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]);
+	}
+	/**
+	* 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();
+	}
+};
+/**
+* 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()`.
+*
+* Three 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
+*
+* @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
+* // Array form — fully declarative
+* const prompt = systemPrompt([
+*   ai.persona("You are Alex."),
+*   ai.instruction("Always cite sources."),
+*   ai.instruction("Respond in {{language|English}}."),
+* ]);
+*/
+function systemPrompt(input) {
+	if (input === void 0) return new SystemPrompt();
+	if (typeof input === "string") return new SystemPrompt([new Instruction(input)]);
+	return new SystemPrompt([...input]);
+}
+
+//#endregion
+export { SystemPrompt, systemPrompt };
+//# sourceMappingURL=system-prompt.mjs.map

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

package/esm/tool/index.d.mts

@@ -0,0 +1 @@
+import { ToolContract, ToolInvokeResult, tool } from "./tool.mjs";

package/esm/tool/index.mjs

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

package/esm/tool/tool.d.mts

@@ -0,0 +1,64 @@
+import { AIError } from "../errors/ai-error.mjs";
+import { Usage } from "../contracts/result/usage.type.mjs";
+import { BaseReport } from "../contracts/result/base-report.type.mjs";
+import { ToolConfig, ToolContext } from "../contracts/tool.contract.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../../@warlock.js/ai/src/tool/tool.d.ts
+/**
+ * Result returned by `ToolContract.invoke()`.
+ *
+ * **Canonical destructure:** `const { data, usage, report, error }` —
+ * matches every other executable (`AgentResult`, `WorkflowResult`,
+ * `SupervisorResult`) so parent agents can treat every tool dispatch
+ * uniformly.
+ *
+ * **Shape.** `data` / `error` carry the outcome; `usage` and `report`
+ * are always present. For leaf tools, `usage` is zero and `report`
+ * is a framework-synthesized {@link BaseReport} (`type: "tool"`,
+ * `children: []`, real timing) so parents never have to nil-check.
+ * For composites wrapped via `asTool()`, `usage` and `report` mirror
+ * the inner primitive's — the nested tree lives in `report.children`.
+ *
+ * @example
+ * const result = await myTool.invoke({ city: "Cairo" });
+ * if (result.error) console.error(result.error.message);
+ * else console.log(result.data, result.report.duration);
+ */
+type ToolInvokeResult<TOutput> = {
+  /** Successfully-returned output. Undefined if execution or validation failed. */data?: TOutput; /** Typed AI error produced by validation or execute(), if any. */
+  error?: AIError; /** Rolled-up usage (zero for leaf tools, populated for composites). */
+  usage: Usage; /** Recursive execution report — `report.children` carries nested executables. */
+  report: BaseReport;
+};
+/**
+ * A `ToolConfig` augmented with a safe `invoke()` entry point for the agent runtime.
+ *
+ * @example
+ * const wrapped: ToolContract<{ city: string }, { temp: number }> = tool(contract);
+ * const result = await wrapped.invoke({ city: "Cairo" });
+ */
+interface ToolContract<TInput = unknown, TOutput = unknown> extends ToolConfig<TInput, TOutput> {
+  /**
+   * Agent-runtime entry point. Validates raw input against the tool's schema,
+   * calls execute(), catches errors, and reports duration.
+   * Never throws — errors surface in the returned `error` field as
+   * typed `AIError` subclasses.
+   *
+   * The optional second argument is a `ToolContext` (Phase 5 /
+   * decisions §35) — when supplied, threaded into `execute(input, ctx)`
+   * so tools can write system-only side data into `ctx.artifacts`.
+   * Standalone callers may omit it; the framework supplies a
+   * degraded `{ artifacts: {} }` so single-arg legacy handlers keep
+   * working unchanged.
+   *
+   * @example
+   * const result = await myTool.invoke(rawLLMArgs);
+   * if (result.error) handleError(result.error);
+   */
+  invoke(rawInput: unknown, ctx?: ToolContext): Promise<ToolInvokeResult<TOutput>>;
+}
+declare function tool<TInput, TOutput>(contract: ToolConfig<TInput, TOutput>): ToolContract<TInput, TOutput>;
+//#endregion
+export { ToolContract, ToolInvokeResult, tool };
+//# sourceMappingURL=tool.d.mts.map

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

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