@warlock.js/ai 4.3.0 → 4.5.0

package/esm/planner/planner.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"planner.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/planner.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { agent } from \"../agent/agent\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { PlannerCapability } from \"../contracts/planner/planner-capability.type\";\nimport type { PlannerConfig } from \"../contracts/planner/planner-config.type\";\nimport type { PlannerExecuteOptions } from \"../contracts/planner/planner-execute-options.type\";\nimport type { PlannerResult } from \"../contracts/planner/planner-result.type\";\nimport type { PlannerContract } from \"../contracts/planner/planner.contract\";\nimport { PlannerFailedError } from \"../errors\";\nimport { buildPlanSystemPrompt } from \"./plan-prompt\";\nimport { PlannerRun } from \"./planner-run\";\nimport { computeSignature } from \"./signature\";\n\nconst LOG_MODULE = \"ai.planner\";\n\n/**\n * `ai.planner(config)` — construct a {@link PlannerContract}.\n *\n * Validates the config at author time (throws {@link PlannerFailedError}\n * on a bad shape), builds (or adopts) the plan-generation agent, computes\n * a stable structural signature, and returns an instance satisfying\n * `ExecutableContract` so the planner composes into supervisors,\n * orchestrators, and outer agents through the same uniform surface.\n *\n * At `execute(goal)` the planner asks its LLM for an ordered plan over\n * the registered `capabilities`, then executes that plan step-by-step\n * through each capability's own `execute()` — reusing the existing\n * executable machinery rather than forking it — and returns the unified\n * `{ data, report, usage, error }` envelope with `report.type ===\n * \"planner\"`.\n *\n * @example\n * const research = ai.planner({\n *   name: \"research-assistant\",\n *   model: ai.openai.model({ name: \"gpt-4o\" }),\n *   capabilities: [\n *     { name: \"search\", description: \"Search the web\", executable: searchAgent },\n *     { name: \"write\", description: \"Draft a summary\", executable: writerAgent },\n *   ],\n *   maxSteps: 6,\n * });\n *\n * const { data, report } = await research.execute(\"Compare React vs Vue in 2026\");\n */\nexport function planner<TOutput = unknown>(\n  config: PlannerConfig<TOutput>,\n): PlannerContract<TOutput> {\n  validateConfig(config);\n\n  const maxSteps = config.maxSteps ?? 10;\n  const capabilities = new Map<string, PlannerCapability>();\n\n  for (const capability of config.capabilities) {\n    capabilities.set(capability.name, capability);\n  }\n\n  const signature = computeSignature(config.name, config.capabilities);\n  const planningAgent = resolvePlanningAgent(config, maxSteps);\n\n  async function execute(\n    goal: string,\n    options?: PlannerExecuteOptions<TOutput>,\n  ): Promise<PlannerResult<TOutput>> {\n    log.debug(LOG_MODULE, \"execute\", \"Planner run starting\", {\n      name: config.name,\n      capabilities: capabilities.size,\n    });\n\n    return new PlannerRun<TOutput>({\n      config,\n      capabilities,\n      maxSteps,\n      signature,\n      planningAgent,\n      goal,\n      options,\n    }).run();\n  }\n\n  return {\n    name: config.name,\n    signature,\n    execute,\n  };\n}\n\n/**\n * Resolve the plan-generation agent: either adopt the dev's `planner`\n * agent, or build an internal one from `model` with the generated\n * plan-system-prompt baked on. The plan output schema is supplied\n * per-call in {@link PlannerRun}, so it isn't baked here.\n *\n * **`maxSteps` and BYO planners.** In `model` mode the cap is woven\n * into the generated plan-system-prompt *and* the per-call plan schema\n * (`steps.maxItems`). In `planner` (BYO) mode the dev owns the prompt,\n * so the cap is communicated only through that same per-call schema —\n * and, regardless of mode, {@link PlannerRun} truncates any over-long\n * plan to `skipped` at execution time, so the cap is always enforced.\n */\nfunction resolvePlanningAgent<TOutput>(\n  config: PlannerConfig<TOutput>,\n  maxSteps: number,\n): AgentContract<unknown> {\n  if (config.planner) {\n    return config.planner;\n  }\n\n  const systemPrompt = buildPlanSystemPrompt(config.capabilities, maxSteps, config.systemPrompt);\n\n  return agent({\n    name: `${config.name}-planner`,\n    description: \"Generates an ordered execution plan over the planner's capabilities.\",\n    model: config.model!,\n    systemPrompt,\n    maxTrips: 1,\n  });\n}\n\n/**\n * Factory-time validation. Surfaces every violation as a typed\n * {@link PlannerFailedError} tagged `authoring: true`, mirroring the\n * supervisor/orchestrator authoring-error convention.\n */\nfunction validateConfig<TOutput>(config: PlannerConfig<TOutput>): void {\n  if (!config.name || typeof config.name !== \"string\") {\n    throw new PlannerFailedError(\"ai.planner: `name` is required and must be a string\", {\n      context: { authoring: true },\n    });\n  }\n\n  const hasModel = config.model !== undefined;\n  const hasPlanner = config.planner !== undefined;\n\n  if (!hasModel && !hasPlanner) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): one of \\`model\\` or \\`planner\\` is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (hasModel && hasPlanner) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): \\`model\\` and \\`planner\\` are mutually exclusive — configure exactly one`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (!Array.isArray(config.capabilities) || config.capabilities.length === 0) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): at least one capability is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  const seen = new Set<string>();\n\n  for (const capability of config.capabilities) {\n    if (!capability || typeof capability.name !== \"string\" || capability.name.length === 0) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): every capability needs a non-empty \\`name\\``,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (typeof capability.description !== \"string\" || capability.description.length === 0) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): capability \"${capability.name}\" needs a \\`description\\``,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (!capability.executable || typeof capability.executable.execute !== \"function\") {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): capability \"${capability.name}\" needs an \\`executable\\` with an execute() method`,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (seen.has(capability.name)) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): duplicate capability name \"${capability.name}\"`,\n        { context: { authoring: true } },\n      );\n    }\n\n    seen.add(capability.name);\n  }\n\n  if (config.maxSteps !== undefined && config.maxSteps < 1) {\n    throw new PlannerFailedError(`ai.planner(\"${config.name}\"): \\`maxSteps\\` must be >= 1`, {\n      context: { authoring: true, maxSteps: config.maxSteps },\n    });\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"planner.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/planner.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { agent } from \"../agent/agent\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { PlannerCapability } from \"../contracts/planner/planner-capability.type\";\nimport type { PlannerConfig } from \"../contracts/planner/planner-config.type\";\nimport type { PlannerExecuteOptions } from \"../contracts/planner/planner-execute-options.type\";\nimport type { PlannerResult } from \"../contracts/planner/planner-result.type\";\nimport type { PlannerContract } from \"../contracts/planner/planner.contract\";\nimport { PlannerFailedError } from \"../errors\";\nimport { buildPlanSystemPrompt } from \"./plan-prompt\";\nimport { PlannerRun } from \"./planner-run\";\nimport { computeSignature } from \"./signature\";\n\nconst LOG_MODULE = \"ai.planner\";\n\n/**\n * `ai.planner(config)` — construct a {@link PlannerContract}.\n *\n * Validates the config at author time (throws {@link PlannerFailedError}\n * on a bad shape), builds (or adopts) the plan-generation agent, computes\n * a stable structural signature, and returns an instance satisfying\n * `ExecutableContract` so the planner composes into supervisors,\n * orchestrators, and outer agents through the same uniform surface.\n *\n * At `execute(goal)` the planner asks its LLM for an ordered plan over\n * the registered `capabilities`, then executes that plan step-by-step\n * through each capability's own `execute()` — reusing the existing\n * executable machinery rather than forking it — and returns the unified\n * `{ data, report, usage, error }` envelope with `report.type ===\n * \"planner\"`.\n *\n * @example\n * const research = ai.planner({\n *   name: \"research-assistant\",\n *   model: ai.openai.model({ name: \"gpt-4o\" }),\n *   capabilities: [\n *     { name: \"search\", description: \"Search the web\", executable: searchAgent },\n *     { name: \"write\", description: \"Draft a summary\", executable: writerAgent },\n *   ],\n *   maxSteps: 6,\n * });\n *\n * const { data, report } = await research.execute(\"Compare React vs Vue in 2026\");\n */\nexport function planner<TOutput = unknown>(\n  config: PlannerConfig<TOutput>,\n): PlannerContract<TOutput> {\n  validateConfig(config);\n\n  const maxSteps = config.maxSteps ?? 10;\n  const capabilities = new Map<string, PlannerCapability>();\n\n  for (const capability of config.capabilities) {\n    capabilities.set(capability.name, capability);\n  }\n\n  const signature = computeSignature(config.name, config.capabilities);\n  const planningAgent = resolvePlanningAgent(config, maxSteps);\n\n  async function execute(\n    goal: string,\n    options?: PlannerExecuteOptions<TOutput>,\n  ): Promise<PlannerResult<TOutput>> {\n    log.debug(LOG_MODULE, \"execute\", \"Planner run starting\", {\n      name: config.name,\n      capabilities: capabilities.size,\n    });\n\n    return new PlannerRun<TOutput>({\n      config,\n      capabilities,\n      maxSteps,\n      signature,\n      planningAgent,\n      goal,\n      options,\n    }).run();\n  }\n\n  return {\n    name: config.name,\n    signature,\n    execute,\n  };\n}\n\n/**\n * Resolve the plan-generation agent: either adopt the dev's `planner`\n * agent, or build an internal one from `model` with the generated\n * plan-system-prompt baked on. The plan output schema is supplied\n * per-call in {@link PlannerRun}, so it isn't baked here.\n *\n * **`maxSteps` and BYO planners.** In `model` mode the cap is woven\n * into the generated plan-system-prompt *and* the per-call plan schema\n * (`steps.maxItems`). In `planner` (BYO) mode the dev owns the prompt,\n * so the cap is communicated only through that same per-call schema —\n * and, regardless of mode, {@link PlannerRun} truncates any over-long\n * plan to `skipped` at execution time, so the cap is always enforced.\n */\nfunction resolvePlanningAgent<TOutput>(\n  config: PlannerConfig<TOutput>,\n  maxSteps: number,\n): AgentContract<unknown> {\n  if (config.planner) {\n    return config.planner;\n  }\n\n  const systemPrompt = buildPlanSystemPrompt(\n    config.capabilities,\n    maxSteps,\n    config.systemPrompt,\n    config.dag === true,\n  );\n\n  return agent({\n    name: `${config.name}-planner`,\n    description: \"Generates an ordered execution plan over the planner's capabilities.\",\n    model: config.model!,\n    systemPrompt,\n    maxTrips: 1,\n  });\n}\n\n/**\n * Factory-time validation. Surfaces every violation as a typed\n * {@link PlannerFailedError} tagged `authoring: true`, mirroring the\n * supervisor/orchestrator authoring-error convention.\n */\nfunction validateConfig<TOutput>(config: PlannerConfig<TOutput>): void {\n  if (!config.name || typeof config.name !== \"string\") {\n    throw new PlannerFailedError(\"ai.planner: `name` is required and must be a string\", {\n      context: { authoring: true },\n    });\n  }\n\n  const hasModel = config.model !== undefined;\n  const hasPlanner = config.planner !== undefined;\n\n  if (!hasModel && !hasPlanner) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): one of \\`model\\` or \\`planner\\` is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (hasModel && hasPlanner) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): \\`model\\` and \\`planner\\` are mutually exclusive — configure exactly one`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (!Array.isArray(config.capabilities) || config.capabilities.length === 0) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): at least one capability is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  const seen = new Set<string>();\n\n  for (const capability of config.capabilities) {\n    if (!capability || typeof capability.name !== \"string\" || capability.name.length === 0) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): every capability needs a non-empty \\`name\\``,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (typeof capability.description !== \"string\" || capability.description.length === 0) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): capability \"${capability.name}\" needs a \\`description\\``,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (!capability.executable || typeof capability.executable.execute !== \"function\") {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): capability \"${capability.name}\" needs an \\`executable\\` with an execute() method`,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (seen.has(capability.name)) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): duplicate capability name \"${capability.name}\"`,\n        { context: { authoring: true } },\n      );\n    }\n\n    seen.add(capability.name);\n  }\n\n  if (config.maxSteps !== undefined && config.maxSteps < 1) {\n    throw new PlannerFailedError(`ai.planner(\"${config.name}\"): \\`maxSteps\\` must be >= 1`, {\n      context: { authoring: true, maxSteps: config.maxSteps },\n    });\n  }\n}\n"],"mappings":"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"}

package/esm/prompt/errors.d.mts

@@ -0,0 +1,57 @@
+import { ErrorCategory } from "../errors/error-category.type.mjs";
+import { AIError, AIErrorOptions } from "../errors/ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/prompt/errors.d.ts
+/**
+ * A prompt name was looked up in the registry but is not registered.
+ *
+ * Thrown by `resolve(name, …)` and `versions(name)` on an unknown name —
+ * closing the silent first-match / empty-result gap a bare `Map.get` would
+ * leave. The missing name is carried in `context.name` for logging.
+ *
+ * Reuses the `"validation"` category (an authoring-time lookup mistake, not a
+ * provider failure) and the shared `PROVIDER_INVALID_REQUEST` code, since the
+ * prompt registry is a local primitive with no dedicated error code.
+ *
+ * @example
+ * try {
+ *   prompts.resolve("unknown-agent");
+ * } catch (error) {
+ *   if (error instanceof PromptNotFoundError) {
+ *     console.error(error.context?.name);
+ *   }
+ * }
+ */
+declare class PromptNotFoundError extends AIError {
+  static readonly defaultCategory: ErrorCategory;
+  constructor(name: string, options?: AIErrorOptions);
+}
+/**
+ * A prompt-registry authoring or resolution invariant was violated:
+ *
+ * - `add(name, version)` / `register(entry)` with a duplicate version label
+ *   (no silent overwrite).
+ * - `resolve(name, …)` where the picked version declares `required` keys that
+ *   are missing from the merged placeholders (the missing keys are listed in
+ *   the message and carried on `context.missing`).
+ *
+ * Reuses the `"validation"` category and the shared `SCHEMA_VALIDATION_FAILED`
+ * code — it is the same class of "you supplied something the registry can't
+ * use" failure as a schema-validation miss.
+ *
+ * @example
+ * try {
+ *   prompts.resolve("support-agent", { placeholders: {} });
+ * } catch (error) {
+ *   if (error instanceof PromptValidationError) {
+ *     console.error(error.context?.missing); // ["product"]
+ *   }
+ * }
+ */
+declare class PromptValidationError extends AIError {
+  static readonly defaultCategory: ErrorCategory;
+  constructor(message: string, options?: AIErrorOptions);
+}
+//#endregion
+export { PromptNotFoundError, PromptValidationError };
+//# sourceMappingURL=errors.d.mts.map

package/esm/prompt/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompt/errors.ts"],"mappings":";;;;;;AAuBA;;;;;;;;;;;;;;;;AAG2D;AA+B3D;cAlCa,mBAAA,SAA4B,OAAA;EAAA,gBAChB,eAAA,EAAiB,aAAA;cAErB,IAAA,UAAc,OAAA,GAAU,cAAA;AAAA;;;;;;;;;;;;AAkCiB;;;;;;;;;;;cAHjD,qBAAA,SAA8B,OAAA;EAAA,gBAClB,eAAA,EAAiB,aAAA;cAErB,OAAA,UAAiB,OAAA,GAAU,cAAA;AAAA"}

package/esm/prompt/errors.mjs

@@ -0,0 +1,73 @@
+import { AIError } from "../errors/ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/prompt/errors.ts
+/**
+* A prompt name was looked up in the registry but is not registered.
+*
+* Thrown by `resolve(name, …)` and `versions(name)` on an unknown name —
+* closing the silent first-match / empty-result gap a bare `Map.get` would
+* leave. The missing name is carried in `context.name` for logging.
+*
+* Reuses the `"validation"` category (an authoring-time lookup mistake, not a
+* provider failure) and the shared `PROVIDER_INVALID_REQUEST` code, since the
+* prompt registry is a local primitive with no dedicated error code.
+*
+* @example
+* try {
+*   prompts.resolve("unknown-agent");
+* } catch (error) {
+*   if (error instanceof PromptNotFoundError) {
+*     console.error(error.context?.name);
+*   }
+* }
+*/
+var PromptNotFoundError = class extends AIError {
+	static {
+		this.defaultCategory = "validation";
+	}
+	constructor(name, options) {
+		super("PROVIDER_INVALID_REQUEST", `Prompt "${name}" is not registered.`, {
+			...options,
+			context: {
+				name,
+				...options?.context
+			}
+		});
+		this.name = "PromptNotFoundError";
+	}
+};
+/**
+* A prompt-registry authoring or resolution invariant was violated:
+*
+* - `add(name, version)` / `register(entry)` with a duplicate version label
+*   (no silent overwrite).
+* - `resolve(name, …)` where the picked version declares `required` keys that
+*   are missing from the merged placeholders (the missing keys are listed in
+*   the message and carried on `context.missing`).
+*
+* Reuses the `"validation"` category and the shared `SCHEMA_VALIDATION_FAILED`
+* code — it is the same class of "you supplied something the registry can't
+* use" failure as a schema-validation miss.
+*
+* @example
+* try {
+*   prompts.resolve("support-agent", { placeholders: {} });
+* } catch (error) {
+*   if (error instanceof PromptValidationError) {
+*     console.error(error.context?.missing); // ["product"]
+*   }
+* }
+*/
+var PromptValidationError = class extends AIError {
+	static {
+		this.defaultCategory = "validation";
+	}
+	constructor(message, options) {
+		super("SCHEMA_VALIDATION_FAILED", message, options);
+		this.name = "PromptValidationError";
+	}
+};
+
+//#endregion
+export { PromptNotFoundError, PromptValidationError };
+//# sourceMappingURL=errors.mjs.map

package/esm/prompt/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompt/errors.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"../errors/ai-error\";\nimport type { ErrorCategory } from \"../errors/error-category.type\";\n\n/**\n * A prompt name was looked up in the registry but is not registered.\n *\n * Thrown by `resolve(name, …)` and `versions(name)` on an unknown name —\n * closing the silent first-match / empty-result gap a bare `Map.get` would\n * leave. The missing name is carried in `context.name` for logging.\n *\n * Reuses the `\"validation\"` category (an authoring-time lookup mistake, not a\n * provider failure) and the shared `PROVIDER_INVALID_REQUEST` code, since the\n * prompt registry is a local primitive with no dedicated error code.\n *\n * @example\n * try {\n *   prompts.resolve(\"unknown-agent\");\n * } catch (error) {\n *   if (error instanceof PromptNotFoundError) {\n *     console.error(error.context?.name);\n *   }\n * }\n */\nexport class PromptNotFoundError extends AIError {\n  public static readonly defaultCategory: ErrorCategory = \"validation\";\n\n  public constructor(name: string, options?: AIErrorOptions) {\n    super(\"PROVIDER_INVALID_REQUEST\", `Prompt \"${name}\" is not registered.`, {\n      ...options,\n      context: { name, ...options?.context },\n    });\n    this.name = \"PromptNotFoundError\";\n  }\n}\n\n/**\n * A prompt-registry authoring or resolution invariant was violated:\n *\n * - `add(name, version)` / `register(entry)` with a duplicate version label\n *   (no silent overwrite).\n * - `resolve(name, …)` where the picked version declares `required` keys that\n *   are missing from the merged placeholders (the missing keys are listed in\n *   the message and carried on `context.missing`).\n *\n * Reuses the `\"validation\"` category and the shared `SCHEMA_VALIDATION_FAILED`\n * code — it is the same class of \"you supplied something the registry can't\n * use\" failure as a schema-validation miss.\n *\n * @example\n * try {\n *   prompts.resolve(\"support-agent\", { placeholders: {} });\n * } catch (error) {\n *   if (error instanceof PromptValidationError) {\n *     console.error(error.context?.missing); // [\"product\"]\n *   }\n * }\n */\nexport class PromptValidationError extends AIError {\n  public static readonly defaultCategory: ErrorCategory = \"validation\";\n\n  public constructor(message: string, options?: AIErrorOptions) {\n    super(\"SCHEMA_VALIDATION_FAILED\", message, options);\n    this.name = \"PromptValidationError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,IAAa,sBAAb,cAAyC,QAAQ;;yBACS;;CAExD,AAAO,YAAY,MAAc,SAA0B;EACzD,MAAM,4BAA4B,WAAW,KAAK,uBAAuB;GACvE,GAAG;GACH,SAAS;IAAE;IAAM,GAAG,SAAS;GAAQ;EACvC,CAAC;EACD,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;;;;;;;AAwBA,IAAa,wBAAb,cAA2C,QAAQ;;yBACO;;CAExD,AAAO,YAAY,SAAiB,SAA0B;EAC5D,MAAM,4BAA4B,SAAS,OAAO;EAClD,KAAK,OAAO;CACd;AACF"}

package/esm/prompt/index.d.mts

@@ -0,0 +1,3 @@
+import { PromptEntry, PromptLangfuseSyncOptions, PromptRegistryContract, PromptRegistryOptions, PromptResolveOptions, PromptValidateOptions, PromptValidationNote, PromptValidationReport, PromptValidationSeverity, PromptVersion, ResolvedPrompt } from "./prompt.type.mjs";
+import { prompt } from "./prompt.mjs";
+import { PromptNotFoundError, PromptValidationError } from "./errors.mjs";

package/esm/prompt/index.mjs

@@ -0,0 +1,4 @@
+import { PromptNotFoundError, PromptValidationError } from "./errors.mjs";
+import { prompt } from "./prompt.mjs";
+
+export {  };

package/esm/prompt/prompt-langfuse-sync.mjs

@@ -0,0 +1,104 @@
+//#region ../@warlock.js/ai/src/prompt/prompt-langfuse-sync.ts
+let LangfuseSdk;
+let isModuleExists = null;
+let loadingPromise;
+const PROMPT_LANGFUSE_INSTALL_INSTRUCTIONS = `
+The prompt registry's Langfuse sync requires the langfuse package.
+Install it with:
+
+  npm install langfuse
+
+Or with your preferred package manager:
+
+  pnpm add langfuse
+  yarn add langfuse
+`.trim();
+/**
+* Settle the lazy import of `langfuse` once, concurrency-safe. Only needed
+* when the caller did not pass a ready `client`. A bare `catch` flips the
+* flag to `false`; the curated install string surfaces at use time, never a
+* raw module-resolution stack trace.
+*/
+function loadLangfuse() {
+	if (isModuleExists !== null) return Promise.resolve();
+	if (loadingPromise) return loadingPromise;
+	loadingPromise = (async () => {
+		try {
+			LangfuseSdk = await import("langfuse");
+			isModuleExists = true;
+		} catch {
+			isModuleExists = false;
+		}
+	})();
+	return loadingPromise;
+}
+/**
+* Resolve the Langfuse client — the caller-supplied one when present,
+* otherwise a lazily-constructed client from credentials. Throws the curated
+* install error when the SDK is missing and no client was supplied.
+*/
+async function resolveClient(options) {
+	if (options.client) return options.client;
+	await loadLangfuse();
+	if (!isModuleExists) throw new Error(PROMPT_LANGFUSE_INSTALL_INSTRUCTIONS);
+	return new LangfuseSdk.Langfuse({
+		publicKey: options.publicKey,
+		secretKey: options.secretKey,
+		baseUrl: options.baseUrl
+	});
+}
+/**
+* Map one Langfuse prompt handle onto a {@link PromptEntry} version snapshot.
+* Langfuse versions are numeric; they become the string `version` label.
+*/
+function toEntry(remote) {
+	return {
+		name: remote.name,
+		versions: [{
+			version: String(remote.version),
+			template: remote.prompt
+		}]
+	};
+}
+/**
+* Warm the lazy `langfuse` import without blocking — call when a registry is
+* constructed with a `langfuse` option but no pre-built client, so the first
+* `.sync()` does not pay the resolution cost. A bare miss is tolerated.
+*/
+function warmLangfuse(options) {
+	if (!options.client) loadLangfuse();
+}
+/**
+* Run one Langfuse-prompts sync pass.
+*
+* **Pull** (`direction: "pull"` | `"both"`) fetches each named prompt from
+* Langfuse and hands the mapped {@link PromptEntry} to `upsert`. **Push**
+* (`direction: "push"` | `"both"`) writes the latest version of each local
+* entry back as a new Langfuse text prompt. Default direction is `"pull"`.
+*
+* Lazily imports `langfuse` (unless a `client` was supplied) and throws a
+* curated install error when the peer is missing.
+*
+* @param options - The configured sync options (client / credentials / direction).
+* @param names - The prompt names to pull (ignored for push-only).
+* @param localEntries - Snapshot of the local catalog, for push.
+* @param upsert - Callback receiving each pulled entry to merge into the catalog.
+*/
+async function syncLangfusePrompts(options, names, localEntries, upsert) {
+	const direction = options.direction ?? "pull";
+	const client = await resolveClient(options);
+	if (direction === "pull" || direction === "both") for (const name of names) upsert(toEntry(await client.getPrompt(name)));
+	if (direction === "push" || direction === "both") for (const entry of localEntries) {
+		const latest = entry.versions[entry.versions.length - 1];
+		if (!latest) continue;
+		await client.createPrompt({
+			name: entry.name,
+			prompt: latest.template,
+			type: "text"
+		});
+	}
+}
+
+//#endregion
+export { syncLangfusePrompts, warmLangfuse };
+//# sourceMappingURL=prompt-langfuse-sync.mjs.map

package/esm/prompt/prompt-langfuse-sync.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-langfuse-sync.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompt/prompt-langfuse-sync.ts"],"sourcesContent":["import type { PromptEntry, PromptLangfuseSyncOptions } from \"./prompt.type\";\nimport type {\n  LangfuseClientLike,\n  LangfusePromptLike,\n} from \"./prompt-langfuse-sync.type\";\n\n// ============================================================\n// Lazily-loaded langfuse SDK (OPTIONAL peer)\n// ============================================================\n\nlet LangfuseSdk: typeof import(\"langfuse\");\nlet isModuleExists: boolean | null = null;\nlet loadingPromise: Promise<void> | undefined;\n\nconst PROMPT_LANGFUSE_INSTALL_INSTRUCTIONS = `\nThe prompt registry's Langfuse sync requires the langfuse package.\nInstall it with:\n\n  npm install langfuse\n\nOr with your preferred package manager:\n\n  pnpm add langfuse\n  yarn add langfuse\n`.trim();\n\n/**\n * Settle the lazy import of `langfuse` once, concurrency-safe. Only needed\n * when the caller did not pass a ready `client`. A bare `catch` flips the\n * flag to `false`; the curated install string surfaces at use time, never a\n * raw module-resolution stack trace.\n */\nfunction loadLangfuse(): Promise<void> {\n  if (isModuleExists !== null) {\n    return Promise.resolve();\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      LangfuseSdk = await import(\"langfuse\");\n      isModuleExists = true;\n    } catch {\n      isModuleExists = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Resolve the Langfuse client — the caller-supplied one when present,\n * otherwise a lazily-constructed client from credentials. Throws the curated\n * install error when the SDK is missing and no client was supplied.\n */\nasync function resolveClient(\n  options: PromptLangfuseSyncOptions,\n): Promise<LangfuseClientLike> {\n  if (options.client) {\n    return options.client;\n  }\n\n  await loadLangfuse();\n\n  if (!isModuleExists) {\n    throw new Error(PROMPT_LANGFUSE_INSTALL_INSTRUCTIONS);\n  }\n\n  return new LangfuseSdk.Langfuse({\n    publicKey: options.publicKey,\n    secretKey: options.secretKey,\n    baseUrl: options.baseUrl,\n  }) as unknown as LangfuseClientLike;\n}\n\n/**\n * Map one Langfuse prompt handle onto a {@link PromptEntry} version snapshot.\n * Langfuse versions are numeric; they become the string `version` label.\n */\nfunction toEntry(remote: LangfusePromptLike): PromptEntry {\n  return {\n    name: remote.name,\n    versions: [{ version: String(remote.version), template: remote.prompt }],\n  };\n}\n\n/**\n * Warm the lazy `langfuse` import without blocking — call when a registry is\n * constructed with a `langfuse` option but no pre-built client, so the first\n * `.sync()` does not pay the resolution cost. A bare miss is tolerated.\n */\nexport function warmLangfuse(options: PromptLangfuseSyncOptions): void {\n  if (!options.client) {\n    void loadLangfuse();\n  }\n}\n\n/**\n * Run one Langfuse-prompts sync pass.\n *\n * **Pull** (`direction: \"pull\"` | `\"both\"`) fetches each named prompt from\n * Langfuse and hands the mapped {@link PromptEntry} to `upsert`. **Push**\n * (`direction: \"push\"` | `\"both\"`) writes the latest version of each local\n * entry back as a new Langfuse text prompt. Default direction is `\"pull\"`.\n *\n * Lazily imports `langfuse` (unless a `client` was supplied) and throws a\n * curated install error when the peer is missing.\n *\n * @param options - The configured sync options (client / credentials / direction).\n * @param names - The prompt names to pull (ignored for push-only).\n * @param localEntries - Snapshot of the local catalog, for push.\n * @param upsert - Callback receiving each pulled entry to merge into the catalog.\n */\nexport async function syncLangfusePrompts(\n  options: PromptLangfuseSyncOptions,\n  names: string[],\n  localEntries: PromptEntry[],\n  upsert: (entry: PromptEntry) => void,\n): Promise<void> {\n  const direction = options.direction ?? \"pull\";\n  const client = await resolveClient(options);\n\n  if (direction === \"pull\" || direction === \"both\") {\n    for (const name of names) {\n      const remote = await client.getPrompt(name);\n      upsert(toEntry(remote));\n    }\n  }\n\n  if (direction === \"push\" || direction === \"both\") {\n    for (const entry of localEntries) {\n      const latest = entry.versions[entry.versions.length - 1];\n\n      if (!latest) {\n        continue;\n      }\n\n      await client.createPrompt({\n        name: entry.name,\n        prompt: latest.template,\n        type: \"text\",\n      });\n    }\n  }\n}\n"],"mappings":";AAUA,IAAI;AACJ,IAAI,iBAAiC;AACrC,IAAI;AAEJ,MAAM,uCAAuC;;;;;;;;;;EAU3C,KAAK;;;;;;;AAQP,SAAS,eAA8B;CACrC,IAAI,mBAAmB,MACrB,OAAO,QAAQ,QAAQ;CAGzB,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GACF,cAAc,MAAM,OAAO;GAC3B,iBAAiB;EACnB,QAAQ;GACN,iBAAiB;EACnB;CACF,EAAC,CAAE;CAEH,OAAO;AACT;;;;;;AAOA,eAAe,cACb,SAC6B;CAC7B,IAAI,QAAQ,QACV,OAAO,QAAQ;CAGjB,MAAM,aAAa;CAEnB,IAAI,CAAC,gBACH,MAAM,IAAI,MAAM,oCAAoC;CAGtD,OAAO,IAAI,YAAY,SAAS;EAC9B,WAAW,QAAQ;EACnB,WAAW,QAAQ;EACnB,SAAS,QAAQ;CACnB,CAAC;AACH;;;;;AAMA,SAAS,QAAQ,QAAyC;CACxD,OAAO;EACL,MAAM,OAAO;EACb,UAAU,CAAC;GAAE,SAAS,OAAO,OAAO,OAAO;GAAG,UAAU,OAAO;EAAO,CAAC;CACzE;AACF;;;;;;AAOA,SAAgB,aAAa,SAA0C;CACrE,IAAI,CAAC,QAAQ,QACX,AAAK,aAAa;AAEtB;;;;;;;;;;;;;;;;;AAkBA,eAAsB,oBACpB,SACA,OACA,cACA,QACe;CACf,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,SAAS,MAAM,cAAc,OAAO;CAE1C,IAAI,cAAc,UAAU,cAAc,QACxC,KAAK,MAAM,QAAQ,OAEjB,OAAO,QAAQ,MADM,OAAO,UAAU,IAAI,CACrB,CAAC;CAI1B,IAAI,cAAc,UAAU,cAAc,QACxC,KAAK,MAAM,SAAS,cAAc;EAChC,MAAM,SAAS,MAAM,SAAS,MAAM,SAAS,SAAS;EAEtD,IAAI,CAAC,QACH;EAGF,MAAM,OAAO,aAAa;GACxB,MAAM,MAAM;GACZ,QAAQ,OAAO;GACf,MAAM;EACR,CAAC;CACH;AAEJ"}

package/esm/prompt/prompt-langfuse-sync.type.d.mts

@@ -0,0 +1,32 @@
+//#region ../@warlock.js/ai/src/prompt/prompt-langfuse-sync.type.d.ts
+/**
+ * Minimal structural view of the parts of the `langfuse` SDK the prompt sync
+ * actually calls. Declared locally (rather than importing the SDK's own types)
+ * so this module type-checks even when `langfuse` is not installed — it is an
+ * OPTIONAL peer, lazily imported at runtime. The shape tracks Langfuse SDK v3's
+ * prompt API: `getPrompt(name, version?)` reads a prompt and `createPrompt(...)`
+ * writes a new prompt version.
+ */
+type LangfuseClientLike = {
+  /** Fetch a single prompt by name (optionally a specific version). */getPrompt(name: string, version?: number): Promise<LangfusePromptLike>; /** Create (push) a new text prompt version. */
+  createPrompt(body: LangfuseCreatePromptBody): Promise<LangfusePromptLike>;
+};
+/**
+ * A Langfuse prompt handle as returned by `getPrompt` / `createPrompt`. Only
+ * the `name` / `version` / `prompt` (body) fields the sync maps are modeled.
+ */
+type LangfusePromptLike = {
+  /** Prompt name. */name: string; /** Numeric version assigned by Langfuse. */
+  version: number; /** The prompt body text (Langfuse `type: "text"` prompts). */
+  prompt: string;
+};
+/** Body accepted by `client.createPrompt(...)` for a text prompt. */
+type LangfuseCreatePromptBody = {
+  /** Prompt name. */name: string; /** Prompt body text. */
+  prompt: string; /** Discriminator — always `"text"` for the bodies this sync pushes. */
+  type?: "text"; /** Deploy labels (e.g. `["production"]`). Optional. */
+  labels?: string[];
+};
+//#endregion
+export { LangfuseClientLike };
+//# sourceMappingURL=prompt-langfuse-sync.type.d.mts.map

package/esm/prompt/prompt-langfuse-sync.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-langfuse-sync.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompt/prompt-langfuse-sync.type.ts"],"mappings":";;AAQA;;;;;;;KAAY,kBAAA;EAI2C,qEAFrD,SAAA,CAAU,IAAA,UAAc,OAAA,YAAmB,OAAA,CAAQ,kBAAA,GAAnD;EAEA,YAAA,CAAa,IAAA,EAAM,wBAAA,GAA2B,OAAA,CAAQ,kBAAA;AAAA;;;;;KAO5C,kBAAA;EAPoC,mBAS9C,IAAA,UATwE;EAWxE,OAAA,UAJU;EAMV,MAAA;AAAA;;KAIU,wBAAA;EANV,mBAQA,IAAA,UANM;EAQN,MAAA,UAJU;EAMV,IAAA;EAEA,MAAA;AAAA"}

package/esm/prompt/prompt-validate.mjs

@@ -0,0 +1,170 @@
+import { judge } from "../eval/judge-scorer.mjs";
+
+//#region ../@warlock.js/ai/src/prompt/prompt-validate.ts
+/**
+* Placeholder matcher — kept in lock-step with the matcher
+* `renderPlaceholders` uses (`src/system-prompt/render-placeholders.ts`) so the
+* lint sees the same `{{key}}` / `{{a.b}}` / `{{key|default}}` set the renderer
+* substitutes. Global so every occurrence is collected.
+*/
+const PLACEHOLDER_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/g;
+/** Lower bound below which a prompt is suspiciously terse. */
+const MIN_REASONABLE_LENGTH = 12;
+/** Upper bound above which a prompt is likely bloated / unfocused. */
+const MAX_REASONABLE_LENGTH = 8e3;
+/**
+* Severity rank for most-severe-first ordering. Higher sorts earlier.
+*/
+const SEVERITY_RANK = {
+	error: 2,
+	warn: 1,
+	info: 0
+};
+/**
+* The fixed rubric the LLM-as-judge grades a prompt body against. Surfaced
+* here (not inline) so the static-lint pass and the judge pass document the
+* same quality dimensions.
+*/
+const PROMPT_JUDGE_RUBRIC = [
+	"Grade this SYSTEM PROMPT on a 0..1 scale for overall quality:",
+	"- Clarity: is the intent unambiguous and easy to follow?",
+	"- Role definition: does it clearly state who/what the assistant is?",
+	"- Output-format specificity: does it say how the answer should be shaped?",
+	"- No conflicting instructions: are any directives contradictory?",
+	"Score 1.0 only when all four hold; deduct for each weakness and explain why."
+].join("\n");
+/**
+* Heuristic role-line detector — a prompt that never says "you are …" /
+* "act as …" / "your role is …" typically lacks a persona. Case-insensitive.
+*/
+const ROLE_HINT_PATTERN = /\b(you are|act as|your role is|you're a|you will act)\b/i;
+/**
+* Run the cheap, model-free static lint over a prompt body. Flags:
+* - length out of the reasonable band (too terse / too bloated),
+* - any `{{placeholder}}` that survives (undeclared / unresolved at lint time),
+* - a missing role line.
+*
+* Pure and synchronous — used standalone (no judge model) and merged with the
+* judge findings when a model is available.
+*
+* @param text - The prompt body to lint.
+*/
+function staticLint(text) {
+	const notes = [];
+	const trimmed = text.trim();
+	if (trimmed.length < MIN_REASONABLE_LENGTH) notes.push({
+		severity: "warn",
+		message: `Prompt is very short (${trimmed.length} chars) — it may be too vague to steer the model.`,
+		suggestion: "Add an explicit role and at least one concrete instruction."
+	});
+	if (trimmed.length > MAX_REASONABLE_LENGTH) notes.push({
+		severity: "warn",
+		message: `Prompt is very long (${trimmed.length} chars) — long prompts dilute focus and inflate cost.`,
+		suggestion: "Split into a tighter persona plus a few focused instructions."
+	});
+	const placeholders = collectPlaceholders(text);
+	for (const placeholder of placeholders) notes.push({
+		severity: "info",
+		message: `Unresolved placeholder "{{${placeholder}}}" — confirm it is supplied at resolve time or give it a default ("{{${placeholder}|...}}").`
+	});
+	if (!ROLE_HINT_PATTERN.test(trimmed)) notes.push({
+		severity: "warn",
+		message: "No role line found — the prompt never states who the assistant is.",
+		suggestion: "Open with a role, e.g. \"You are a senior support engineer for …\"."
+	});
+	return notes;
+}
+/**
+* Collect every distinct placeholder PATH (the part before any `|default`)
+* from a template, in first-seen order. Matches `renderPlaceholders`' own
+* parsing so the lint never disagrees with the renderer.
+*/
+function collectPlaceholders(template) {
+	const found = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of template.matchAll(PLACEHOLDER_PATTERN)) {
+		const path = match[1].split("|")[0].trim();
+		if (path.length > 0 && !seen.has(path)) {
+			seen.add(path);
+			found.push(path);
+		}
+	}
+	return found;
+}
+/**
+* Stable, most-severe-first ordering: `error` before `warn` before `info`,
+* preserving original order within a severity. Returns a fresh array.
+*/
+function sortNotesBySeverity(notes) {
+	return notes.map((note, index) => ({
+		note,
+		index
+	})).sort((a, b) => {
+		const rankDiff = SEVERITY_RANK[b.note.severity] - SEVERITY_RANK[a.note.severity];
+		return rankDiff !== 0 ? rankDiff : a.index - b.index;
+	}).map((entry) => entry.note);
+}
+/**
+* Score the static-lint findings alone, on a `0..1` scale. Starts at `1.0`
+* and deducts per finding by severity, clamped at `0`. Used as the report
+* score when no judge model is available.
+*/
+function staticScore(notes) {
+	let score = 1;
+	for (const note of notes) if (note.severity === "error") score -= .4;
+	else if (note.severity === "warn") score -= .2;
+	else score -= .05;
+	return Math.max(0, Number(score.toFixed(4)));
+}
+/**
+* Run the LLM-as-judge pass over `text` using a judge agent built from
+* `model`, REUSING the eval `judge` scorer so there is no second judging
+* path. Returns the judge `score` (`0..1`) and a single derived note carrying
+* its reason (when present). The judge prompt is the prompt-quality rubric;
+* the "answer to grade" is the prompt body itself.
+*
+* @param text - The prompt body under evaluation.
+* @param model - The model that powers the judge agent.
+* @param buildJudgeAgent - Factory that wraps a model into a name-bearing judge agent.
+*/
+async function judgePrompt(text, model, buildJudgeAgent) {
+	const score = await judge({
+		agent: buildJudgeAgent(model),
+		rubric: PROMPT_JUDGE_RUBRIC
+	})({
+		case: {
+			name: "prompt-quality",
+			input: "Grade the system prompt below."
+		},
+		text,
+		result: { text },
+		output: void 0
+	});
+	const notes = [];
+	if (score.reason) notes.push({
+		severity: score.passed ? "info" : "warn",
+		message: `LLM-as-judge: ${score.reason}`
+	});
+	return {
+		score: score.score,
+		notes
+	};
+}
+/**
+* Assemble the final {@link PromptValidationReport} from the static-lint
+* findings and (optionally) the judge findings. Notes are merged and sorted
+* most-severe-first. The score is the static score alone when no judge ran,
+* else the mean of the static score and the judge score.
+*/
+function buildValidationReport(staticNotes, judgeResult) {
+	const allNotes = judgeResult ? [...staticNotes, ...judgeResult.notes] : staticNotes;
+	const lintScore = staticScore(staticNotes);
+	return {
+		score: judgeResult ? Number(((lintScore + judgeResult.score) / 2).toFixed(4)) : lintScore,
+		notes: sortNotesBySeverity(allNotes)
+	};
+}
+
+//#endregion
+export { PROMPT_JUDGE_RUBRIC, buildValidationReport, judgePrompt, staticLint };
+//# sourceMappingURL=prompt-validate.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-validate.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompt/prompt-validate.ts"],"sourcesContent":["import type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { ModelContract } from \"../contracts/model.contract\";\nimport { judge } from \"../eval/judge-scorer\";\nimport type { PromptValidationNote, PromptValidationReport } from \"./prompt.type\";\n\n/**\n * Placeholder matcher — kept in lock-step with the matcher\n * `renderPlaceholders` uses (`src/system-prompt/render-placeholders.ts`) so the\n * lint sees the same `{{key}}` / `{{a.b}}` / `{{key|default}}` set the renderer\n * substitutes. Global so every occurrence is collected.\n */\nconst PLACEHOLDER_PATTERN = /\\{\\{\\s*([^{}]+?)\\s*\\}\\}/g;\n\n/** Lower bound below which a prompt is suspiciously terse. */\nconst MIN_REASONABLE_LENGTH = 12;\n\n/** Upper bound above which a prompt is likely bloated / unfocused. */\nconst MAX_REASONABLE_LENGTH = 8000;\n\n/**\n * Severity rank for most-severe-first ordering. Higher sorts earlier.\n */\nconst SEVERITY_RANK: Record<PromptValidationNote[\"severity\"], number> = {\n  error: 2,\n  warn: 1,\n  info: 0,\n};\n\n/**\n * The fixed rubric the LLM-as-judge grades a prompt body against. Surfaced\n * here (not inline) so the static-lint pass and the judge pass document the\n * same quality dimensions.\n */\nexport const PROMPT_JUDGE_RUBRIC = [\n  \"Grade this SYSTEM PROMPT on a 0..1 scale for overall quality:\",\n  \"- Clarity: is the intent unambiguous and easy to follow?\",\n  \"- Role definition: does it clearly state who/what the assistant is?\",\n  \"- Output-format specificity: does it say how the answer should be shaped?\",\n  \"- No conflicting instructions: are any directives contradictory?\",\n  \"Score 1.0 only when all four hold; deduct for each weakness and explain why.\",\n].join(\"\\n\");\n\n/**\n * Heuristic role-line detector — a prompt that never says \"you are …\" /\n * \"act as …\" / \"your role is …\" typically lacks a persona. Case-insensitive.\n */\nconst ROLE_HINT_PATTERN = /\\b(you are|act as|your role is|you're a|you will act)\\b/i;\n\n/**\n * Run the cheap, model-free static lint over a prompt body. Flags:\n * - length out of the reasonable band (too terse / too bloated),\n * - any `{{placeholder}}` that survives (undeclared / unresolved at lint time),\n * - a missing role line.\n *\n * Pure and synchronous — used standalone (no judge model) and merged with the\n * judge findings when a model is available.\n *\n * @param text - The prompt body to lint.\n */\nexport function staticLint(text: string): PromptValidationNote[] {\n  const notes: PromptValidationNote[] = [];\n  const trimmed = text.trim();\n\n  if (trimmed.length < MIN_REASONABLE_LENGTH) {\n    notes.push({\n      severity: \"warn\",\n      message: `Prompt is very short (${trimmed.length} chars) — it may be too vague to steer the model.`,\n      suggestion: \"Add an explicit role and at least one concrete instruction.\",\n    });\n  }\n\n  if (trimmed.length > MAX_REASONABLE_LENGTH) {\n    notes.push({\n      severity: \"warn\",\n      message: `Prompt is very long (${trimmed.length} chars) — long prompts dilute focus and inflate cost.`,\n      suggestion: \"Split into a tighter persona plus a few focused instructions.\",\n    });\n  }\n\n  const placeholders = collectPlaceholders(text);\n\n  for (const placeholder of placeholders) {\n    notes.push({\n      severity: \"info\",\n      message: `Unresolved placeholder \"{{${placeholder}}}\" — confirm it is supplied at resolve time or give it a default (\"{{${placeholder}|...}}\").`,\n    });\n  }\n\n  if (!ROLE_HINT_PATTERN.test(trimmed)) {\n    notes.push({\n      severity: \"warn\",\n      message: \"No role line found — the prompt never states who the assistant is.\",\n      suggestion: 'Open with a role, e.g. \"You are a senior support engineer for …\".',\n    });\n  }\n\n  return notes;\n}\n\n/**\n * Collect every distinct placeholder PATH (the part before any `|default`)\n * from a template, in first-seen order. Matches `renderPlaceholders`' own\n * parsing so the lint never disagrees with the renderer.\n */\nfunction collectPlaceholders(template: string): string[] {\n  const found: string[] = [];\n  const seen = new Set<string>();\n\n  for (const match of template.matchAll(PLACEHOLDER_PATTERN)) {\n    const path = match[1].split(\"|\")[0].trim();\n\n    if (path.length > 0 && !seen.has(path)) {\n      seen.add(path);\n      found.push(path);\n    }\n  }\n\n  return found;\n}\n\n/**\n * Stable, most-severe-first ordering: `error` before `warn` before `info`,\n * preserving original order within a severity. Returns a fresh array.\n */\nexport function sortNotesBySeverity(\n  notes: PromptValidationNote[],\n): PromptValidationNote[] {\n  return notes\n    .map((note, index) => ({ note, index }))\n    .sort((a, b) => {\n      const rankDiff = SEVERITY_RANK[b.note.severity] - SEVERITY_RANK[a.note.severity];\n\n      return rankDiff !== 0 ? rankDiff : a.index - b.index;\n    })\n    .map(entry => entry.note);\n}\n\n/**\n * Score the static-lint findings alone, on a `0..1` scale. Starts at `1.0`\n * and deducts per finding by severity, clamped at `0`. Used as the report\n * score when no judge model is available.\n */\nexport function staticScore(notes: PromptValidationNote[]): number {\n  let score = 1;\n\n  for (const note of notes) {\n    if (note.severity === \"error\") {\n      score -= 0.4;\n    } else if (note.severity === \"warn\") {\n      score -= 0.2;\n    } else {\n      score -= 0.05;\n    }\n  }\n\n  return Math.max(0, Number(score.toFixed(4)));\n}\n\n/**\n * Run the LLM-as-judge pass over `text` using a judge agent built from\n * `model`, REUSING the eval `judge` scorer so there is no second judging\n * path. Returns the judge `score` (`0..1`) and a single derived note carrying\n * its reason (when present). The judge prompt is the prompt-quality rubric;\n * the \"answer to grade\" is the prompt body itself.\n *\n * @param text - The prompt body under evaluation.\n * @param model - The model that powers the judge agent.\n * @param buildJudgeAgent - Factory that wraps a model into a name-bearing judge agent.\n */\nexport async function judgePrompt(\n  text: string,\n  model: ModelContract,\n  buildJudgeAgent: (model: ModelContract) => AgentContract<unknown>,\n): Promise<{ score: number; notes: PromptValidationNote[] }> {\n  const judgeAgent = buildJudgeAgent(model);\n  const scorer = judge({ agent: judgeAgent, rubric: PROMPT_JUDGE_RUBRIC });\n\n  const score = await scorer({\n    // The judge scorer only reads `case.input` / `case.expected` / `text` /\n    // `output` from the context. We feed the rubric question via `input` and\n    // the prompt body as the answer to grade via `text`.\n    case: { name: \"prompt-quality\", input: \"Grade the system prompt below.\" },\n    text,\n    // `result` is unused by the judge scorer's prompt builder; a minimal\n    // stand-in keeps the structural contract satisfied without a real run.\n    result: { text } as never,\n    output: undefined,\n  });\n\n  const notes: PromptValidationNote[] = [];\n\n  if (score.reason) {\n    notes.push({\n      severity: score.passed ? \"info\" : \"warn\",\n      message: `LLM-as-judge: ${score.reason}`,\n    });\n  }\n\n  return { score: score.score, notes };\n}\n\n/**\n * Assemble the final {@link PromptValidationReport} from the static-lint\n * findings and (optionally) the judge findings. Notes are merged and sorted\n * most-severe-first. The score is the static score alone when no judge ran,\n * else the mean of the static score and the judge score.\n */\nexport function buildValidationReport(\n  staticNotes: PromptValidationNote[],\n  judgeResult?: { score: number; notes: PromptValidationNote[] },\n): PromptValidationReport {\n  const allNotes = judgeResult\n    ? [...staticNotes, ...judgeResult.notes]\n    : staticNotes;\n\n  const lintScore = staticScore(staticNotes);\n\n  const score = judgeResult\n    ? Number(((lintScore + judgeResult.score) / 2).toFixed(4))\n    : lintScore;\n\n  return {\n    score,\n    notes: sortNotesBySeverity(allNotes),\n  };\n}\n"],"mappings":"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"}

package/esm/prompt/prompt.d.mts

@@ -0,0 +1,54 @@
+import { SystemPromptContract } from "../contracts/system-prompt.contract.mjs";
+import { PromptRegistryContract, PromptRegistryOptions } from "./prompt.type.mjs";
+
+//#region ../@warlock.js/ai/src/prompt/prompt.d.ts
+/**
+ * Create a versioned, typed prompt registry — a thin facade over the unified
+ * `ai.prompts` manager.
+ *
+ * **Role.** Public factory for {@link PromptRegistryContract}. Keeps
+ * user-facing code free of `new` and consistent with `ai.memory`,
+ * `ai.orchestrator`, `ai.batch` (all return instances). Each call returns a
+ * fresh, isolated registry backed by its own unified manager, so parallel test
+ * suites and multi-tenant apps never share mutable global prompt state.
+ *
+ * @param options - Seed entries, an optional default judge model, and an
+ *   optional Langfuse sync.
+ *
+ * @example
+ * const prompts = prompt({
+ *   prompts: [
+ *     {
+ *       name: "support-agent",
+ *       versions: [
+ *         { version: "1", template: "You are support for {{product}}. Reply in {{language|English}}." },
+ *         { version: "2", template: "You are senior support for {{product}}.", required: ["product"] },
+ *       ],
+ *     },
+ *   ],
+ * });
+ *
+ * const resolved = prompts.resolve("support-agent", { placeholders: { product: "Warlock" } });
+ * const agent = ai.agent({ model, systemPrompt: resolved.toSystemPrompt() });
+ * // resolved.version === "2"; a missing `product` would throw PromptValidationError.
+ *
+ * @example
+ * // Resolve a globally-registered prompt by name from `ai.prompts`.
+ * ai.systemPrompt("You are support.", { name: "support" });
+ * const sp = ai.prompt("support"); // → the registered SystemPromptContract
+ */
+declare function promptFactory(name: string, versionOrTag?: string): SystemPromptContract;
+declare function promptFactory(options?: PromptRegistryOptions): PromptRegistryContract;
+/**
+ * Create a versioned prompt registry, OR resolve a globally-registered prompt
+ * by name from `ai.prompts`.
+ *
+ * - `prompt(options?)` → a fresh, isolated {@link PromptRegistryContract}.
+ * - `prompt(name, versionOrTag?)` → the `SystemPromptContract` registered under
+ *   `name` in the process-wide `ai.prompts` manager (latest version by default,
+ *   or a specific version / pinned tag).
+ */
+declare const prompt: typeof promptFactory;
+//#endregion
+export { prompt };
+//# sourceMappingURL=prompt.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompt/prompt.ts"],"mappings":";;;;;;AA+BuB;;;;;;;;AA+UA;AAAA;;;;;;;;AACwD;AAyB/E;;;;AAAyD;;;;;;;;;;;iBA7BhD,aAAA,CACP,IAAA,UACA,YAAA,YACC,oBAAoB;AAAA,iBACd,aAAA,CAAc,OAAA,GAAU,qBAAA,GAAwB,sBAAsB;;;;;;;;;;cAyBlE,MAAA,SAAe,aAA6B"}