@warlock.js/ai 4.4.0 → 4.6.0

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"}

package/esm/prompt/prompt.mjs

@@ -0,0 +1,218 @@
+import { agent } from "../agent/agent.mjs";
+import { renderPlaceholders } from "../system-prompt/render-placeholders.mjs";
+import { Instruction } from "../system-prompt/instruction.mjs";
+import { SystemPrompt } from "../system-prompt/system-prompt.mjs";
+import { buildValidationReport, judgePrompt, staticLint } from "./prompt-validate.mjs";
+import { defaultPromptsManager, prompts } from "../prompts/prompts-manager.mjs";
+import { PromptNotFoundError, PromptValidationError } from "./errors.mjs";
+import { syncLangfusePrompts, warmLangfuse } from "./prompt-langfuse-sync.mjs";
+
+//#region ../@warlock.js/ai/src/prompt/prompt.ts
+/**
+* Build the one-shot judge agent the `validate()` LLM-as-judge pass runs.
+* Name-bearing (the eval `judge` scorer requires a usable agent) and seeded
+* with a strict-JSON instruction so its verdict parses even without an output
+* schema. Kept module-private so the registry's only model dependency is the
+* `agent()` factory.
+*/
+function buildJudgeAgent(model) {
+	return agent({
+		name: "prompt-quality-judge",
+		model,
+		systemPrompt: "You are a strict prompt-quality grader. Respond with JSON only: { \"score\": <0..1>, \"passed\": <true|false>, \"reason\": \"<short explanation>\" }."
+	});
+}
+/**
+* Build the `SystemPromptContract` a single {@link PromptVersion} maps to: its
+* `template` becomes one instruction block, and its `required` keys ride along
+* as `meta.required` so the unified manager (and `validate`) can see them.
+*
+* Deliberately ANONYMOUS (no `meta.name`) so the `SystemPrompt` constructor
+* never auto-registers this version into the process-wide `ai.prompts` default
+* manager — each `prompt()` registry owns its OWN isolated
+* {@link PromptsManagerContract}, the single storage shape behind this facade.
+*/
+function versionToContract(version) {
+	return new SystemPrompt([new Instruction(version.template)], { ...version.required ? { required: version.required } : {} });
+}
+/**
+* Legacy `PromptRegistryContract` — now a THIN FACADE over the unified
+* {@link PromptsManagerContract} (`ai.prompts`).
+*
+* **Role.** The store behind `ai.prompt(...)`. Historically it held a private
+* `Map<string, PromptVersion[]>`; it now delegates ALL storage to a private,
+* per-instance {@link PromptsManagerContract}, so there is exactly ONE storage
+* shape across the whole prompt surface: a `SystemPromptContract` keyed by
+* `name@version`. A version's raw `template` string maps to a single
+* instruction block and its `required` keys to `meta.required`.
+*
+* **Responsibility.**
+* - Owns: the legacy method surface (`register` / `add` / `versions` /
+*   `resolve` / `validate` / `sync`) and the back-compat behaviors — duplicate
+*   version rejection, required-key assertion on `resolve()`, the
+*   `{ score, notes }` validation report shape, and the optional Langfuse sync.
+* - Does NOT own: the actual storage (delegated to the internal manager),
+*   placeholder rendering (delegated to `renderPlaceholders`), or the unified
+*   validation primitives (delegated to `prompt-validate`).
+*
+* Each `prompt(options)` call builds its own isolated manager — so parallel
+* test suites and multi-tenant apps never share mutable global prompt state,
+* exactly as before the unification.
+*
+* Users construct via the `prompt()` factory — `new PromptRegistry()` is not
+* the public API.
+*/
+var PromptRegistry = class {
+	constructor(options = {}) {
+		this.options = options;
+		this.versionMeta = /* @__PURE__ */ new Map();
+		this.manager = prompts();
+		for (const entry of options.prompts ?? []) this.register(entry);
+		if (options.langfuse) warmLangfuse(options.langfuse);
+	}
+	/**
+	* Register a whole entry. Merges onto an existing name's history; a
+	* duplicate version label throws {@link PromptValidationError}.
+	*/
+	register(entry) {
+		for (const version of entry.versions) this.add(entry.name, version);
+		if (!this.versionMeta.has(entry.name)) this.versionMeta.set(entry.name, []);
+		return this;
+	}
+	/**
+	* Add a new version to a name (creating it when absent). A duplicate
+	* version label throws {@link PromptValidationError} — never a silent
+	* overwrite.
+	*/
+	add(name, version) {
+		const mirror = this.versionMeta.get(name) ?? [];
+		if (mirror.some((existing) => existing.version === version.version)) throw new PromptValidationError(`Prompt "${name}" already has a version labeled "${version.version}".`, { context: {
+			name,
+			version: version.version
+		} });
+		this.manager.register(versionToContract(version), {
+			name,
+			version: version.version
+		});
+		this.versionMeta.set(name, [...mirror, version]);
+		return this;
+	}
+	/** Whether a name is registered. */
+	has(name) {
+		return this.versionMeta.has(name);
+	}
+	/** Every registered prompt name, in registration order. */
+	list() {
+		return [...this.versionMeta.keys()];
+	}
+	/** Versions registered for a name, latest last. Throws on an unknown name. */
+	versions(name) {
+		const mirror = this.versionMeta.get(name);
+		if (!mirror) throw new PromptNotFoundError(name);
+		return [...mirror];
+	}
+	/**
+	* Resolve + render. Picks the requested or latest version, validates the
+	* version's `required` keys against the merged placeholders, then renders by
+	* delegating to the shared `renderPlaceholders` over the contract's text.
+	*/
+	resolve(name, options = {}) {
+		const picked = this.pickVersion(name, options.version);
+		const placeholders = options.placeholders ?? {};
+		this.assertRequired(name, picked, placeholders);
+		const text = renderPlaceholders(this.manager.get(name, picked.version).blocks[0]?.text ?? picked.template, placeholders);
+		return {
+			name,
+			version: picked.version,
+			text,
+			toSystemPrompt: () => new SystemPrompt([new Instruction(text)])
+		};
+	}
+	/**
+	* Quality-check a raw prompt body or a registered prompt (by name). Backed by
+	* the unified deterministic validate primitives plus the LLM-as-judge pass,
+	* but returns the legacy `{ score, notes }` report shape so existing callers
+	* keep working.
+	*
+	* Always runs the static lint; runs the LLM-as-judge pass too when a model is
+	* resolvable. Never throws when no judge model is available.
+	*/
+	async validate(textOrName, options = {}) {
+		const text = this.resolveValidationText(textOrName, options.version);
+		const staticNotes = staticLint(text);
+		const model = options.model ?? this.options.judgeModel;
+		if (!model) return buildValidationReport(staticNotes);
+		return buildValidationReport(staticNotes, await judgePrompt(text, model, buildJudgeAgent));
+	}
+	/**
+	* Synchronize named prompts with Langfuse-prompts. No-op (resolves) when no
+	* `langfuse` option was configured. The resolved (rendered) body + the
+	* `name@version` label are what is pushed/pulled.
+	*/
+	async sync() {
+		if (!this.options.langfuse) return;
+		await syncLangfusePrompts(this.options.langfuse, this.list(), this.snapshotEntries(), (entry) => this.register(entry));
+	}
+	/**
+	* Pick the requested (or latest) {@link PromptVersion} for a name from the
+	* mirror, throwing {@link PromptNotFoundError} on an unknown name or version.
+	*/
+	pickVersion(name, version) {
+		const mirror = this.versionMeta.get(name);
+		if (!mirror || mirror.length === 0) throw new PromptNotFoundError(name);
+		const picked = version ? mirror.find((candidate) => candidate.version === version) : mirror[mirror.length - 1];
+		if (!picked) throw new PromptNotFoundError(name, { context: {
+			name,
+			version
+		} });
+		return picked;
+	}
+	/**
+	* Resolve the text `validate()` should grade: a registered name yields its
+	* picked version's raw `template`; anything else is treated as the raw body.
+	*/
+	resolveValidationText(textOrName, version) {
+		const mirror = this.versionMeta.get(textOrName);
+		if (!mirror || mirror.length === 0) return textOrName;
+		const picked = version ? mirror.find((candidate) => candidate.version === version) : mirror[mirror.length - 1];
+		return picked ? picked.template : textOrName;
+	}
+	/**
+	* Throw {@link PromptValidationError} listing every `required` key absent
+	* from the merged placeholders. A no-op when the version declares none.
+	*/
+	assertRequired(name, version, placeholders) {
+		if (!version.required || version.required.length === 0) return;
+		const missing = version.required.filter((key) => placeholders[key] === void 0 || placeholders[key] === null || placeholders[key] === "");
+		if (missing.length > 0) throw new PromptValidationError(`Prompt "${name}" version "${version.version}" is missing required placeholder${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}.`, { context: {
+			name,
+			version: version.version,
+			missing
+		} });
+	}
+	/** Snapshot the catalog as `PromptEntry[]` (for the Langfuse push path). */
+	snapshotEntries() {
+		return [...this.versionMeta.entries()].map(([name, versions]) => ({
+			name,
+			versions: [...versions]
+		}));
+	}
+};
+function promptFactory(first, versionOrTag) {
+	if (typeof first === "string") return defaultPromptsManager().get(first, versionOrTag);
+	return new PromptRegistry(first);
+}
+/**
+* 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).
+*/
+const prompt = promptFactory;
+
+//#endregion
+export { prompt };
+//# sourceMappingURL=prompt.mjs.map