@warlock.js/ai 4.4.0 → 4.6.0

package/esm/prompt/prompt.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.mjs","names":["createPromptsManager"],"sources":["../../../../../../../@warlock.js/ai/src/prompt/prompt.ts"],"sourcesContent":["import type { SystemPromptContract } from \"../contracts/system-prompt.contract\";\nimport {\n  defaultPromptsManager,\n  prompts as createPromptsManager,\n} from \"../prompts/prompts-manager\";\nimport type { PromptsManagerContract } from \"../prompts/prompts-manager.contract\";\nimport { Instruction } from \"../system-prompt/instruction\";\nimport { renderPlaceholders } from \"../system-prompt/render-placeholders\";\nimport { SystemPrompt } from \"../system-prompt/system-prompt\";\nimport { PromptNotFoundError, PromptValidationError } from \"./errors\";\nimport {\n  syncLangfusePrompts,\n  warmLangfuse,\n} from \"./prompt-langfuse-sync\";\nimport {\n  buildValidationReport,\n  judgePrompt,\n  staticLint,\n} from \"./prompt-validate\";\nimport { agent } from \"../agent/agent\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { ModelContract } from \"../contracts/model.contract\";\nimport type {\n  PromptEntry,\n  PromptRegistryContract,\n  PromptRegistryOptions,\n  PromptResolveOptions,\n  PromptValidateOptions,\n  PromptValidationReport,\n  PromptVersion,\n  ResolvedPrompt,\n} from \"./prompt.type\";\n\n/**\n * Build the one-shot judge agent the `validate()` LLM-as-judge pass runs.\n * Name-bearing (the eval `judge` scorer requires a usable agent) and seeded\n * with a strict-JSON instruction so its verdict parses even without an output\n * schema. Kept module-private so the registry's only model dependency is the\n * `agent()` factory.\n */\nfunction buildJudgeAgent(model: ModelContract): AgentContract<unknown> {\n  return agent({\n    name: \"prompt-quality-judge\",\n    model,\n    systemPrompt:\n      \"You are a strict prompt-quality grader. Respond with JSON only: \" +\n      '{ \"score\": <0..1>, \"passed\": <true|false>, \"reason\": \"<short explanation>\" }.',\n  });\n}\n\n/**\n * Build the `SystemPromptContract` a single {@link PromptVersion} maps to: its\n * `template` becomes one instruction block, and its `required` keys ride along\n * as `meta.required` so the unified manager (and `validate`) can see them.\n *\n * Deliberately ANONYMOUS (no `meta.name`) so the `SystemPrompt` constructor\n * never auto-registers this version into the process-wide `ai.prompts` default\n * manager — each `prompt()` registry owns its OWN isolated\n * {@link PromptsManagerContract}, the single storage shape behind this facade.\n */\nfunction versionToContract(version: PromptVersion): SystemPromptContract {\n  return new SystemPrompt([new Instruction(version.template)], {\n    ...(version.required ? { required: version.required } : {}),\n  });\n}\n\n/**\n * Legacy `PromptRegistryContract` — now a THIN FACADE over the unified\n * {@link PromptsManagerContract} (`ai.prompts`).\n *\n * **Role.** The store behind `ai.prompt(...)`. Historically it held a private\n * `Map<string, PromptVersion[]>`; it now delegates ALL storage to a private,\n * per-instance {@link PromptsManagerContract}, so there is exactly ONE storage\n * shape across the whole prompt surface: a `SystemPromptContract` keyed by\n * `name@version`. A version's raw `template` string maps to a single\n * instruction block and its `required` keys to `meta.required`.\n *\n * **Responsibility.**\n * - Owns: the legacy method surface (`register` / `add` / `versions` /\n *   `resolve` / `validate` / `sync`) and the back-compat behaviors — duplicate\n *   version rejection, required-key assertion on `resolve()`, the\n *   `{ score, notes }` validation report shape, and the optional Langfuse sync.\n * - Does NOT own: the actual storage (delegated to the internal manager),\n *   placeholder rendering (delegated to `renderPlaceholders`), or the unified\n *   validation primitives (delegated to `prompt-validate`).\n *\n * Each `prompt(options)` call builds its own isolated manager — so parallel\n * test suites and multi-tenant apps never share mutable global prompt state,\n * exactly as before the unification.\n *\n * Users construct via the `prompt()` factory — `new PromptRegistry()` is not\n * the public API.\n */\nclass PromptRegistry implements PromptRegistryContract {\n  /** The single backing store — one isolated unified manager per registry. */\n  private readonly manager: PromptsManagerContract;\n\n  /** Per-name version metadata mirror, kept so `versions()` returns the rich\n   * {@link PromptVersion} shape (template + required + meta) the legacy API\n   * promised — the manager itself only stores the flattened contract. */\n  private readonly versionMeta = new Map<string, PromptVersion[]>();\n\n  public constructor(private readonly options: PromptRegistryOptions = {}) {\n    this.manager = createPromptsManager();\n\n    for (const entry of options.prompts ?? []) {\n      this.register(entry);\n    }\n\n    if (options.langfuse) {\n      warmLangfuse(options.langfuse);\n    }\n  }\n\n  /**\n   * Register a whole entry. Merges onto an existing name's history; a\n   * duplicate version label throws {@link PromptValidationError}.\n   */\n  public register(entry: PromptEntry): PromptRegistryContract {\n    for (const version of entry.versions) {\n      this.add(entry.name, version);\n    }\n\n    // An entry with an empty version list still creates the name so `has`\n    // / `list` reflect it.\n    if (!this.versionMeta.has(entry.name)) {\n      this.versionMeta.set(entry.name, []);\n    }\n\n    return this;\n  }\n\n  /**\n   * Add a new version to a name (creating it when absent). A duplicate\n   * version label throws {@link PromptValidationError} — never a silent\n   * overwrite.\n   */\n  public add(name: string, version: PromptVersion): PromptRegistryContract {\n    const mirror = this.versionMeta.get(name) ?? [];\n\n    if (mirror.some(existing => existing.version === version.version)) {\n      throw new PromptValidationError(\n        `Prompt \"${name}\" already has a version labeled \"${version.version}\".`,\n        { context: { name, version: version.version } },\n      );\n    }\n\n    this.manager.register(versionToContract(version), {\n      name,\n      version: version.version,\n    });\n\n    this.versionMeta.set(name, [...mirror, version]);\n\n    return this;\n  }\n\n  /** Whether a name is registered. */\n  public has(name: string): boolean {\n    return this.versionMeta.has(name);\n  }\n\n  /** Every registered prompt name, in registration order. */\n  public list(): string[] {\n    return [...this.versionMeta.keys()];\n  }\n\n  /** Versions registered for a name, latest last. Throws on an unknown name. */\n  public versions(name: string): PromptVersion[] {\n    const mirror = this.versionMeta.get(name);\n\n    if (!mirror) {\n      throw new PromptNotFoundError(name);\n    }\n\n    return [...mirror];\n  }\n\n  /**\n   * Resolve + render. Picks the requested or latest version, validates the\n   * version's `required` keys against the merged placeholders, then renders by\n   * delegating to the shared `renderPlaceholders` over the contract's text.\n   */\n  public resolve(name: string, options: PromptResolveOptions = {}): ResolvedPrompt {\n    const picked = this.pickVersion(name, options.version);\n    const placeholders = options.placeholders ?? {};\n\n    this.assertRequired(name, picked, placeholders);\n\n    // Render the RAW template (placeholders intact) against the merged values —\n    // resolving the contract first would bake inline `{{key|default}}` defaults\n    // in and shadow an explicitly-supplied value. The stored block text is the\n    // single source of the un-rendered template.\n    const contract = this.manager.get(name, picked.version);\n    const template = contract.blocks[0]?.text ?? picked.template;\n    const text = renderPlaceholders(template, placeholders);\n\n    return {\n      name,\n      version: picked.version,\n      text,\n      toSystemPrompt: () => new SystemPrompt([new Instruction(text)]),\n    };\n  }\n\n  /**\n   * Quality-check a raw prompt body or a registered prompt (by name). Backed by\n   * the unified deterministic validate primitives plus the LLM-as-judge pass,\n   * but returns the legacy `{ score, notes }` report shape so existing callers\n   * keep working.\n   *\n   * Always runs the static lint; runs the LLM-as-judge pass too when a model is\n   * resolvable. Never throws when no judge model is available.\n   */\n  public async validate(\n    textOrName: string,\n    options: PromptValidateOptions = {},\n  ): Promise<PromptValidationReport> {\n    const text = this.resolveValidationText(textOrName, options.version);\n    const staticNotes = staticLint(text);\n\n    const model = options.model ?? this.options.judgeModel;\n\n    if (!model) {\n      return buildValidationReport(staticNotes);\n    }\n\n    const judgeResult = await judgePrompt(text, model, buildJudgeAgent);\n\n    return buildValidationReport(staticNotes, judgeResult);\n  }\n\n  /**\n   * Synchronize named prompts with Langfuse-prompts. No-op (resolves) when no\n   * `langfuse` option was configured. The resolved (rendered) body + the\n   * `name@version` label are what is pushed/pulled.\n   */\n  public async sync(): Promise<void> {\n    if (!this.options.langfuse) {\n      return;\n    }\n\n    await syncLangfusePrompts(\n      this.options.langfuse,\n      this.list(),\n      this.snapshotEntries(),\n      entry => this.register(entry),\n    );\n  }\n\n  /**\n   * Pick the requested (or latest) {@link PromptVersion} for a name from the\n   * mirror, throwing {@link PromptNotFoundError} on an unknown name or version.\n   */\n  private pickVersion(name: string, version?: string): PromptVersion {\n    const mirror = this.versionMeta.get(name);\n\n    if (!mirror || mirror.length === 0) {\n      throw new PromptNotFoundError(name);\n    }\n\n    const picked = version\n      ? mirror.find(candidate => candidate.version === version)\n      : mirror[mirror.length - 1];\n\n    if (!picked) {\n      throw new PromptNotFoundError(name, {\n        context: { name, version },\n      });\n    }\n\n    return picked;\n  }\n\n  /**\n   * Resolve the text `validate()` should grade: a registered name yields its\n   * picked version's raw `template`; anything else is treated as the raw body.\n   */\n  private resolveValidationText(textOrName: string, version?: string): string {\n    const mirror = this.versionMeta.get(textOrName);\n\n    if (!mirror || mirror.length === 0) {\n      return textOrName;\n    }\n\n    const picked = version\n      ? mirror.find(candidate => candidate.version === version)\n      : mirror[mirror.length - 1];\n\n    return picked ? picked.template : textOrName;\n  }\n\n  /**\n   * Throw {@link PromptValidationError} listing every `required` key absent\n   * from the merged placeholders. A no-op when the version declares none.\n   */\n  private assertRequired(\n    name: string,\n    version: PromptVersion,\n    placeholders: Record<string, unknown>,\n  ): void {\n    if (!version.required || version.required.length === 0) {\n      return;\n    }\n\n    const missing = version.required.filter(\n      key => placeholders[key] === undefined || placeholders[key] === null || placeholders[key] === \"\",\n    );\n\n    if (missing.length > 0) {\n      throw new PromptValidationError(\n        `Prompt \"${name}\" version \"${version.version}\" is missing required placeholder${\n          missing.length > 1 ? \"s\" : \"\"\n        }: ${missing.join(\", \")}.`,\n        { context: { name, version: version.version, missing } },\n      );\n    }\n  }\n\n  /** Snapshot the catalog as `PromptEntry[]` (for the Langfuse push path). */\n  private snapshotEntries(): PromptEntry[] {\n    return [...this.versionMeta.entries()].map(([name, versions]) => ({\n      name,\n      versions: [...versions],\n    }));\n  }\n}\n\n/**\n * Create a versioned, typed prompt registry — a thin facade over the unified\n * `ai.prompts` manager.\n *\n * **Role.** Public factory for {@link PromptRegistryContract}. Keeps\n * user-facing code free of `new` and consistent with `ai.memory`,\n * `ai.orchestrator`, `ai.batch` (all return instances). Each call returns a\n * fresh, isolated registry backed by its own unified manager, so parallel test\n * suites and multi-tenant apps never share mutable global prompt state.\n *\n * @param options - Seed entries, an optional default judge model, and an\n *   optional Langfuse sync.\n *\n * @example\n * const prompts = prompt({\n *   prompts: [\n *     {\n *       name: \"support-agent\",\n *       versions: [\n *         { version: \"1\", template: \"You are support for {{product}}. Reply in {{language|English}}.\" },\n *         { version: \"2\", template: \"You are senior support for {{product}}.\", required: [\"product\"] },\n *       ],\n *     },\n *   ],\n * });\n *\n * const resolved = prompts.resolve(\"support-agent\", { placeholders: { product: \"Warlock\" } });\n * const agent = ai.agent({ model, systemPrompt: resolved.toSystemPrompt() });\n * // resolved.version === \"2\"; a missing `product` would throw PromptValidationError.\n *\n * @example\n * // Resolve a globally-registered prompt by name from `ai.prompts`.\n * ai.systemPrompt(\"You are support.\", { name: \"support\" });\n * const sp = ai.prompt(\"support\"); // → the registered SystemPromptContract\n */\nfunction promptFactory(\n  name: string,\n  versionOrTag?: string,\n): SystemPromptContract;\nfunction promptFactory(options?: PromptRegistryOptions): PromptRegistryContract;\nfunction promptFactory(\n  first?: string | PromptRegistryOptions,\n  versionOrTag?: string,\n): SystemPromptContract | PromptRegistryContract {\n  // String form: resolve a globally-registered prompt from the process-wide\n  // `ai.prompts` manager (the single unified registry). This is the thin\n  // facade's read path onto the shared store.\n  if (typeof first === \"string\") {\n    return defaultPromptsManager().get(first, versionOrTag);\n  }\n\n  // Options form: build an isolated registry backed by its own unified manager.\n  return new PromptRegistry(first);\n}\n\n/**\n * Create a versioned prompt registry, OR resolve a globally-registered prompt\n * by name from `ai.prompts`.\n *\n * - `prompt(options?)` → a fresh, isolated {@link PromptRegistryContract}.\n * - `prompt(name, versionOrTag?)` → the `SystemPromptContract` registered under\n *   `name` in the process-wide `ai.prompts` manager (latest version by default,\n *   or a specific version / pinned tag).\n */\nexport const prompt: typeof promptFactory = promptFactory;\n"],"mappings":"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"}

package/esm/prompt/prompt.type.d.mts

@@ -0,0 +1,174 @@
+import { ModelContract } from "../contracts/model.contract.mjs";
+import { Placeholders } from "../contracts/placeholders.type.mjs";
+import { SystemPrompt } from "../system-prompt/system-prompt.mjs";
+import { LangfuseClientLike } from "./prompt-langfuse-sync.type.mjs";
+
+//#region ../@warlock.js/ai/src/prompt/prompt.type.d.ts
+/**
+ * One immutable version of a named prompt.
+ *
+ * **Role.** A single addressable snapshot of a prompt body, tagged with a
+ * free-form `version` label and (optionally) the placeholder keys it
+ * requires. Many versions accumulate under one {@link PromptEntry} so a
+ * registered prompt can evolve while older versions stay resolvable.
+ *
+ * The `template` uses the exact same `{{placeholder}}` syntax the shared
+ * `renderPlaceholders` helper supports — `{{key}}`, `{{a.b.c}}`,
+ * `{{key|default}}` — so a version's body renders identically to a
+ * `systemPrompt(string)` seed.
+ */
+type PromptVersion = {
+  /** Monotonic version label, e.g. `"1"`, `"2"`, `"2025-06-draft"`. Free-form string. */version: string; /** The prompt body — same `{{placeholder}}` syntax `renderPlaceholders` supports. */
+  template: string;
+  /**
+   * Placeholder keys this version requires. When set, `.resolve()` throws a
+   * {@link PromptValidationError} if any are missing from the merged
+   * placeholders — closing the silent-passthrough gap `renderPlaceholders`
+   * leaves for an unsupplied `{{key}}`. Absent = no required-key validation.
+   */
+  required?: string[]; /** Optional free-form metadata (author note, model hint, etc.). */
+  meta?: Record<string, unknown>;
+};
+/**
+ * A named prompt and its ordered version history.
+ *
+ * **Role.** The unit `register()` ingests and `versions()` returns. The
+ * `versions` array is ordered oldest-first; the **last** entry is the
+ * default resolved when no explicit `version` is requested.
+ */
+type PromptEntry = {
+  /** Unique name used for lookup, e.g. `"support-agent"`. */name: string; /** Ordered version history; the last entry is the default. */
+  versions: PromptVersion[];
+};
+/**
+ * Options for {@link PromptRegistryContract.resolve}.
+ */
+type PromptResolveOptions = {
+  /** Pick a specific version by its label. Default: the latest registered version. */version?: string; /** Values for the template's `{{placeholders}}`. */
+  placeholders?: Placeholders;
+};
+/**
+ * Outcome of {@link PromptRegistryContract.resolve} — the picked version, its
+ * rendered text, and a one-call bridge to a `SystemPrompt`.
+ */
+type ResolvedPrompt = {
+  /** The prompt name that was resolved. */name: string; /** The version label that was picked. */
+  version: string; /** The rendered string (placeholders substituted). */
+  text: string;
+  /**
+   * A `SystemPrompt` seeded with the rendered text — the exact same seed
+   * `systemPrompt(string)` produces (`new SystemPrompt([new Instruction(text)])`),
+   * so it is a drop-in for `ai.agent({ systemPrompt })`.
+   */
+  toSystemPrompt(): SystemPrompt;
+};
+/** Severity of a single {@link PromptValidationReport} finding. */
+type PromptValidationSeverity = "info" | "warn" | "error";
+/** One finding in a {@link PromptValidationReport}. */
+type PromptValidationNote = {
+  /** How serious this finding is — drives the most-severe-first ordering. */severity: PromptValidationSeverity; /** Human-readable description of the finding. */
+  message: string; /** Optional concrete rewrite/fix for this finding. */
+  suggestion?: string;
+};
+/**
+ * Result of {@link PromptRegistryContract.validate} — an overall quality
+ * score plus individual findings, most severe first.
+ */
+type PromptValidationReport = {
+  /** Overall quality score, `0`–`1`, from the LLM-as-judge rubric + static lint. */score: number; /** Individual findings, most severe first. */
+  notes: PromptValidationNote[];
+};
+/** Options for {@link PromptRegistryContract.validate}. */
+type PromptValidateOptions = {
+  /**
+   * Model that powers the LLM-as-judge pass. When omitted (and no registry
+   * default `judgeModel` is set), `validate()` returns the static-lint
+   * findings only — never throwing.
+   */
+  model?: ModelContract;
+  /**
+   * Validate a registered prompt's specific version (only meaningful when the
+   * first argument is a registered name). Default: the latest version.
+   */
+  version?: string;
+};
+/**
+ * Public surface of the prompt registry returned by `prompt(options?)`.
+ *
+ * **Role.** A named, versioned, typed catalog wrapping `systemPrompt` /
+ * `SystemPrompt.fromFile` with `{{placeholder}}` validation, a `validate()`
+ * quality check (static lint + LLM-as-judge), and an optional Langfuse sync.
+ *
+ * Mutating methods (`register` / `add`) return the same registry for chaining.
+ */
+type PromptRegistryContract = {
+  /**
+   * Register a whole entry (name + its version history). Returns the registry
+   * for chaining. A name registered twice merges the new versions onto the
+   * existing history (duplicate version labels throw a
+   * {@link PromptValidationError}).
+   */
+  register(entry: PromptEntry): PromptRegistryContract;
+  /**
+   * Add a new version to an existing name (creating the name when absent).
+   * A duplicate `version` label throws a {@link PromptValidationError} —
+   * never a silent overwrite.
+   */
+  add(name: string, version: PromptVersion): PromptRegistryContract; /** Whether a name is registered. */
+  has(name: string): boolean; /** Every registered prompt name. */
+  list(): string[];
+  /**
+   * Resolve + render. Throws {@link PromptNotFoundError} on an unknown name
+   * and {@link PromptValidationError} when the picked version's `required`
+   * keys are missing from the merged placeholders.
+   */
+  resolve(name: string, options?: PromptResolveOptions): ResolvedPrompt; /** Versions registered for a name, latest last. Throws {@link PromptNotFoundError} on miss. */
+  versions(name: string): PromptVersion[];
+  /**
+   * Quality-check a prompt body (raw text) or a registered prompt (by name).
+   * Runs a cheap static lint (length, undeclared/unresolved `{{placeholders}}`,
+   * missing role line) PLUS, when a model is resolvable, an LLM-as-judge pass
+   * over a clarity / role / output-format / conflict rubric — reusing the eval
+   * `judge` scorer. With no judge model, returns the static-lint findings only
+   * and never throws.
+   */
+  validate(textOrName: string, options?: PromptValidateOptions): Promise<PromptValidationReport>;
+  /**
+   * Synchronize named prompts with Langfuse-prompts. Lazily imports the
+   * optional `langfuse` peer; pulls named prompts into the catalog and/or
+   * pushes local versions per the configured `direction`. Throws a curated
+   * install error when `langfuse` is not installed.
+   */
+  sync(): Promise<void>;
+};
+/**
+ * Optional Langfuse-prompts sync configuration (see {@link PromptRegistryOptions}).
+ */
+type PromptLangfuseSyncOptions = {
+  /** A pre-built Langfuse client. When supplied, the SDK is never imported. */client?: LangfuseClientLike; /** Langfuse public key — used to construct a client when `client` is omitted. */
+  publicKey?: string; /** Langfuse secret key — used to construct a client when `client` is omitted. */
+  secretKey?: string; /** Langfuse host base URL. Optional; defaults to the SDK's own default. */
+  baseUrl?: string; /** Sync direction. `"pull"` (default) pulls remote prompts; `"push"` pushes local; `"both"` does both. */
+  direction?: "pull" | "push" | "both";
+};
+/**
+ * Options for the `prompt(options?)` factory.
+ */
+type PromptRegistryOptions = {
+  /** Seed entries at construction. */prompts?: PromptEntry[];
+  /**
+   * Default model for the `validate()` LLM-as-judge pass when a call does not
+   * pass its own `model`. Absent = `validate()` is static-lint-only unless a
+   * per-call model is supplied.
+   */
+  judgeModel?: ModelContract;
+  /**
+   * Optional Langfuse-prompts sync. Lazily imports `langfuse`; pulls named
+   * prompts on `.sync()` and (optionally) pushes local versions. Absent =
+   * fully local, no network.
+   */
+  langfuse?: PromptLangfuseSyncOptions;
+};
+//#endregion
+export { PromptEntry, PromptLangfuseSyncOptions, PromptRegistryContract, PromptRegistryOptions, PromptResolveOptions, PromptValidateOptions, PromptValidationNote, PromptValidationReport, PromptValidationSeverity, PromptVersion, ResolvedPrompt };
+//# sourceMappingURL=prompt.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompt/prompt.type.ts"],"mappings":";;;;;;;;AAkBA;;;;;;;;;;AAae;KAbH,aAAA;EAuBW,uFArBrB,OAAA,UAyBuB;EAvBvB,QAAA;EAuBA;;;AAAuB;AAMzB;;EAtBE,QAAA,aA0B2B;EAxB3B,IAAA,GAAO,MAAM;AAAA;;;AAwBc;AAO7B;;;;KArBY,WAAA;EAyBV,2DAvBA,IAAA,UA+BA;EA7BA,QAAA,EAAU,aAAa;AAAA;AA6BO;AAIhC;;AAJgC,KAvBpB,oBAAA;EA2BwB,oFAzBlC,OAAA,WA4BU;EA1BV,YAAA,GAAe,YAAY;AAAA;;;;;KAOjB,cAAA;EAyBA,yCAvBV,IAAA,UA8BU;EA5BV,OAAA;EAEA,IAAA;EA4BA;;;;AAE2B;EAxB3B,cAAA,IAAkB,YAAY;AAAA;;KAIpB,wBAAA;;KAGA,oBAAA;EAgCV,2EA9BA,QAAA,EAAU,wBAAwB,EA8B3B;EA5BP,OAAA,UAwCgC;EAtChC,UAAA;AAAA;;;;;KAOU,sBAAA;EAwDc,kFAtDxB,KAAA,UAkEW;EAhEX,KAAA,EAAO,oBAAoB;AAAA;;KAIjB,qBAAA;EA8BV;;;;;EAxBA,KAAA,GAAQ,aAAa;EA8BM;;;;EAzB3B,OAAA;AAAA;;;;;;;;;;KAYU,sBAAA;EAoCE;;;;;;EA7BZ,QAAA,CAAS,KAAA,EAAO,WAAA,GAAc,sBAAA;EAqCf;AAMjB;;;;EArCE,GAAA,CAAI,IAAA,UAAc,OAAA,EAAS,aAAA,GAAgB,sBAAA,EAuClC;EArCT,GAAA,CAAI,IAAA,oBAyCJ;EAvCA,IAAA;EA2CA;;AAAS;AAMX;;EA3CE,OAAA,CAAQ,IAAA,UAAc,OAAA,GAAU,oBAAA,GAAuB,cAAA,EA6C7C;EA3CV,QAAA,CAAS,IAAA,WAAe,aAAA;EAuDb;;;;;;;;EA9CX,QAAA,CACE,UAAA,UACA,OAAA,GAAU,qBAAA,GACT,OAAA,CAAQ,sBAAA;EA2CyB;AAAA;;;;;EApCpC,IAAA,IAAQ,OAAA;AAAA;;;;KAME,yBAAA;+EAEV,MAAA,GAAS,kBAAkB;EAE3B,SAAA;EAEA,SAAA;EAEA,OAAA;EAEA,SAAA;AAAA;;;;KAMU,qBAAA;sCAEV,OAAA,GAAU,WAAA;;;;;;EAMV,UAAA,GAAa,aAAA;;;;;;EAMb,QAAA,GAAW,yBAAA;AAAA"}

package/esm/prompts/index.d.mts

@@ -0,0 +1,3 @@
+import { ExportedPrompt, ExportedPromptVersion, ExportedRegistry, PromptDiff, PromptDiffBlock, PromptJudgeCacheLike, PromptTemplateVersion, PromptValidateTarget, PromptValidationResult, PromptsManagerOptions, PromptsValidateOptions } from "./prompts-manager.type.mjs";
+import { PromptsManagerContract, PromptsManagerEntry, PromptsManagerRegisterOptions } from "./prompts-manager.contract.mjs";
+import { defaultPromptsManager, promptKey, prompts } from "./prompts-manager.mjs";

package/esm/prompts/index.mjs

@@ -0,0 +1,3 @@
+import { defaultPromptsManager, promptKey, prompts } from "./prompts-manager.mjs";
+
+export {  };

package/esm/prompts/prompts-manager.contract.d.mts

@@ -0,0 +1,154 @@
+import { Placeholders } from "../contracts/placeholders.type.mjs";
+import { ExportedRegistry, PromptDiff, PromptTemplateVersion, PromptValidateTarget, PromptValidationResult, PromptsValidateOptions } from "./prompts-manager.type.mjs";
+import { SystemPromptBlockContract, SystemPromptContract, SystemPromptMeta } from "../contracts/system-prompt.contract.mjs";
+
+//#region ../@warlock.js/ai/src/prompts/prompts-manager.contract.d.ts
+/**
+ * One registered prompt in the {@link PromptsManagerContract} — a named,
+ * versioned `SystemPromptContract` plus the bookkeeping the manager needs to
+ * resolve "latest" deterministically.
+ *
+ * **Role.** The unit `register()` produces and `list()` / `get()` return. The
+ * registry is keyed by `name@version`, so the same `name` can hold many
+ * versions side by side, each its own entry.
+ */
+interface PromptsManagerEntry {
+  /** Registry name (from the contract's `meta.name`). */
+  readonly name: string;
+  /** Version label. Defaults to the next integer when registration omits it. */
+  readonly version: string;
+  /**
+   * Monotonic insertion order, sourced from an internal counter (never
+   * `Date.now()`), so "latest" is the highest `addedAt` for a name —
+   * deterministic and stable across same-tick registrations.
+   */
+  readonly addedAt: number;
+  /** The registered prompt builder. */
+  readonly contract: SystemPromptContract;
+  /** Optional free-form tags for grouping / filtering. */
+  readonly tags?: readonly string[];
+}
+/** Options for {@link PromptsManagerContract.register}. */
+interface PromptsManagerRegisterOptions {
+  /** Optional tags stored alongside the entry. */
+  readonly tags?: readonly string[];
+  /**
+   * Explicit name override. When set, it (not `contract.meta().name`) is the
+   * registry name — used by `define()` / `import()` to register an anonymous
+   * contract under a name without triggering the `SystemPrompt` constructor's
+   * auto-registration into the process-wide default manager.
+   */
+  readonly name?: string;
+  /** Explicit version override, paired with {@link name}. */
+  readonly version?: string;
+}
+/**
+ * Public surface of the prompts manager returned by `prompts()` and exposed as
+ * `ai.prompts`.
+ *
+ * **Role.** A single registry of named, versioned `SystemPromptContract`
+ * builders keyed by `name@version`. It owns registration (deriving the version
+ * when omitted, rejecting non-idempotent duplicates), version resolution
+ * (latest by insertion order), and one-call `resolve()` to the final string.
+ *
+ * **Responsibility.**
+ * - Owns: the `name@version` registry, the monotonic `addedAt` counter, the
+ *   duplicate / idempotency rule, and latest-version selection.
+ * - Does NOT own: how a prompt renders (delegated to the contract's
+ *   `resolve()`), the `{{placeholder}}` syntax, or block composition.
+ */
+interface PromptsManagerContract {
+  /**
+   * Register a prompt builder. The contract must carry `meta.name`; the
+   * version defaults to the next integer for that name when `meta.version` is
+   * omitted. Throws `InvalidRequestError` on a duplicate `name@version` unless
+   * the registered content is byte-identical (idempotent re-registration).
+   * Returns the manager for chaining.
+   */
+  register(contract: SystemPromptContract, options?: PromptsManagerRegisterOptions): PromptsManagerContract;
+  /**
+   * Build a new `SystemPromptContract` — a documented alias of `ai.systemPrompt`.
+   * Identical input forms: no argument → empty builder; a single string → one
+   * instruction-seeded prompt; an array of blocks → used verbatim. Pass a `meta`
+   * with a `name` to auto-register the result in the process-wide `ai.prompts`
+   * default manager (same semantics as `ai.systemPrompt(input, { name })`).
+   *
+   * Provided so prompt authoring and the prompt registry share one entry point:
+   * `ai.prompts.create(...)` reads identically to `ai.prompts.get(...)` /
+   * `ai.prompts.resolve(...)` right beside it.
+   */
+  create(input?: string | ReadonlyArray<SystemPromptBlockContract>, meta?: SystemPromptMeta): SystemPromptContract;
+  /**
+   * Resolve a registered builder. The optional second argument selects the
+   * version by its label, by a pinned tag (`get(name, "production")`), or via
+   * the inline `name@selector` form folded into the first argument
+   * (`get("agent@production")`, `get("agent@2")`). With no selector, returns
+   * the latest by insertion order. Throws `InvalidRequestError` on an unknown
+   * name, version, or tag.
+   */
+  get(name: string, versionOrTag?: string): SystemPromptContract;
+  /** Whether any version of `name` is registered (optionally a specific version/tag). */
+  has(name: string, versionOrTag?: string): boolean;
+  /** Every registered name, in first-seen order. */
+  list(): string[];
+  /** Version labels registered for a name, oldest first. Empty when unknown. */
+  versions(name: string): string[];
+  /**
+   * Resolve a registered prompt to its final string in one call — picks the
+   * version (latest when omitted; a version label, a pinned tag, or the inline
+   * `name@selector` form is accepted) and renders it against `placeholders`.
+   * Throws `InvalidRequestError` on an unknown name / version / tag.
+   */
+  resolve(name: string, versionOrTag?: string, placeholders?: Placeholders): string;
+  /**
+   * Bulk-register many versions of one name in a single call. Each entry's
+   * `template` is a raw string (wrapped into one instruction block) or an
+   * explicit ordered block list (used verbatim). Versions register oldest-first
+   * in array order; the same duplicate / idempotency rule as `register` applies
+   * per `name@version`. Returns the manager for chaining.
+   */
+  define(name: string, versions: readonly PromptTemplateVersion[]): PromptsManagerContract;
+  /**
+   * Pin a tag to a specific registered version of a name (e.g.
+   * `tag("agent", "production", "2")`). The tag then resolves through
+   * `get(name, tag)` / `resolve(name, tag)` / the `name@tag` inline form.
+   * Re-pinning an existing tag moves it. Throws `InvalidRequestError` when the
+   * name or version is unknown. Returns the manager for chaining.
+   */
+  tag(name: string, tag: string, version: string): PromptsManagerContract;
+  /**
+   * Unified prompt validation. ALWAYS runs the deterministic check — every
+   * `{{key}}` placeholder with no inline default that is neither supplied
+   * (`options.placeholders`) nor declared (`options.declare` + the prompt's
+   * `meta.required`) is reported in `missing`, and `ok` is `true` iff `missing`
+   * is empty. When `options.judge` is a model, ALSO runs a Nova-safe
+   * LLM-as-judge quality pass — it never throws and degrades to an `issues`
+   * note (leaving `score` undefined) on failure, so it never flips `ok`.
+   *
+   * `target` is a registered name (or `name@selector`), a `SystemPromptContract`
+   * instance, or a raw prompt string.
+   */
+  validate(target: PromptValidateTarget, options?: PromptsValidateOptions): Promise<PromptValidationResult>;
+  /**
+   * Block-level diff between two registered versions of a name. Blocks are
+   * matched positionally; the result lists added / removed / changed blocks and
+   * an `identical` flag. Throws `InvalidRequestError` on an unknown name or
+   * version.
+   */
+  diff(name: string, from: string, to: string): PromptDiff;
+  /**
+   * Serialize the whole registry to a portable JSON snapshot — every name, its
+   * versions (flattened to `{ type, text }` blocks), pinned tags, and carried
+   * `description` / `required` metadata. Round-trips through `import`.
+   */
+  export(): ExportedRegistry;
+  /**
+   * Rehydrate a registry from an `export()` snapshot. Each version re-registers
+   * under its `name@version` (subject to the same duplicate / idempotency rule)
+   * and pinned tags are restored. Returns the manager for chaining.
+   */
+  import(snapshot: ExportedRegistry): PromptsManagerContract;
+}
+//#endregion
+export { PromptsManagerContract, PromptsManagerEntry, PromptsManagerRegisterOptions };
+//# sourceMappingURL=prompts-manager.contract.d.mts.map

package/esm/prompts/prompts-manager.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts-manager.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompts/prompts-manager.contract.ts"],"mappings":";;;;;;;AAwBA;;;;;;;UAAiB,mBAAA;EAeI;EAAA,SAbV,IAAA;EAgBI;EAAA,SAbJ,OAAA;EAiBM;;;;;EAAA,SAVN,OAAA;EAuBA;EAAA,SApBA,QAAA,EAAU,oBAAoB;EAoBvB;EAAA,SAjBP,IAAA;AAAA;;UAIM,6BAAA;EAyCH;EAAA,SAvCH,IAAA;EAsDwB;;;;;;EAAA,SA9CxB,IAAA;EA2FN;EAAA,SAxFM,OAAA;AAAA;;;;;;;;;;;;;;;;UAkBM,sBAAA;EAyBI;;;;;;;EAjBnB,QAAA,CACE,QAAA,EAAU,oBAAA,EACV,OAAA,GAAU,6BAAA,GACT,sBAAA;EA0Be;;;;;;;;;;;EAblB,MAAA,CACE,KAAA,YAAiB,aAAA,CAAc,yBAAA,GAC/B,IAAA,GAAO,gBAAA,GACN,oBAAA;EA8BD;;;;;;;;EApBF,GAAA,CAAI,IAAA,UAAc,YAAA,YAAwB,oBAAA;EA0CX;EAvC/B,GAAA,CAAI,IAAA,UAAc,YAAA;EAqDlB;EAlDA,IAAA;EAmDE;EAhDF,QAAA,CAAS,IAAA;EAiDP;;;;;;EAzCF,OAAA,CACE,IAAA,UACA,YAAA,WACA,YAAA,GAAe,YAAA;EA+C6B;;;;;;;EArC9C,MAAA,CACE,IAAA,UACA,QAAA,WAAmB,qBAAA,KAClB,sBAAA;EAgDuD;;;;;;;EAvC1D,GAAA,CAAI,IAAA,UAAc,GAAA,UAAa,OAAA,WAAkB,sBAAA;;;;;;;;;;;;;EAcjD,QAAA,CACE,MAAA,EAAQ,oBAAA,EACR,OAAA,GAAU,sBAAA,GACT,OAAA,CAAQ,sBAAA;;;;;;;EAQX,IAAA,CAAK,IAAA,UAAc,IAAA,UAAc,EAAA,WAAa,UAAA;;;;;;EAO9C,MAAA,IAAU,gBAAA;;;;;;EAOV,MAAA,CAAO,QAAA,EAAU,gBAAA,GAAmB,sBAAA;AAAA"}

package/esm/prompts/prompts-manager.d.mts

@@ -0,0 +1,38 @@
+import { PromptsManagerOptions } from "./prompts-manager.type.mjs";
+import { PromptsManagerContract } from "./prompts-manager.contract.mjs";
+
+//#region ../@warlock.js/ai/src/prompts/prompts-manager.d.ts
+/**
+ * Build the `name@version` registry key. Centralized so the duplicate check,
+ * `get`, and `composedFrom` provenance all agree on one label shape.
+ */
+declare function promptKey(name: string, version: string): string;
+/**
+ * Create a new, isolated prompts manager.
+ *
+ * **Role.** Public factory for {@link PromptsManagerContract} — keeps
+ * user-facing code free of `new` and consistent with the other `ai.*`
+ * factories. Each call returns a fresh registry, so parallel test suites and
+ * multi-tenant apps never share mutable global prompt state.
+ *
+ * The process-wide instance that named `systemPrompt(...)` builders
+ * auto-register into is `ai.prompts` (see {@link defaultPromptsManager}).
+ *
+ * @param options - Optional wiring, notably a `judgeCache` that memoizes
+ *   LLM-judge verdicts (absent ⇒ every judge pass runs live).
+ *
+ * @example
+ * const registry = prompts();
+ * registry.register(systemPrompt("You are support.", { name: "support" }));
+ * registry.resolve("support"); // "You are support."
+ *
+ * @example
+ * // Memoize judge verdicts across validations.
+ * const registry = prompts({ judgeCache: new MemoryCacheDriver() });
+ */
+declare function prompts(options?: PromptsManagerOptions): PromptsManagerContract;
+/** Accessor for the process-wide default {@link PromptsManagerContract}. */
+declare function defaultPromptsManager(): PromptsManagerContract;
+//#endregion
+export { defaultPromptsManager, promptKey, prompts };
+//# sourceMappingURL=prompts-manager.d.mts.map

package/esm/prompts/prompts-manager.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts-manager.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompts/prompts-manager.ts"],"mappings":";;;;;;AAsCA;;iBAAgB,SAAA,CAAU,IAAA,UAAc,OAAe;;AAAA;AAqnBvD;;;;;;;;AAAgF;AAehF;;;;AAA+D;;;;;;;;iBAf/C,OAAA,CAAQ,OAAA,GAAU,qBAAA,GAAwB,sBAAsB;;iBAehE,qBAAA,IAAyB,sBAAsB"}