@owlmeans/llm 0.1.15 → 0.1.16

package/build/plugins/anthropic.js

@@ -1,11 +1,59 @@
 import { ChatAnthropic } from '@langchain/anthropic';
 import { BadRequestError } from '@anthropic-ai/sdk';
-import { ModelProvider, StructuredMode } from '@owlmeans/llm-common';
-import { MAX_CACHE_BREAKPOINTS } from '../consts.js';
+import { ModelProvider, PromptBlock, StructuredMode } from '@owlmeans/llm-common';
+import { CHARS_PER_TOKEN, MAX_CACHE_BREAKPOINTS, MIN_CACHEABLE_TOKENS } from '../consts.js';
+import { readConfig } from '../utils/config.js';
 import { escalateMaxTokens, makeClientOptions } from './utils.js';
 /** Model-name prefix that supports prompt caching through `cache_control` markers. */
 const CACHEABLE_PREFIX = 'claude-';
 export const ANTHROPIC_FAMILY = 'anthropic';
+const supportsCache = (model) => model.modelName?.startsWith(CACHEABLE_PREFIX) === true;
+/**
+ * Shortest prefix worth a breakpoint, in characters. Anthropic silently declines to
+ * create an entry below its own per-model minimum, so a marker there wastes one of the
+ * four breakpoints and reports a cache that was never written.
+ */
+const minCacheableChars = (model) => (readConfig(model).cacheMinTokens ?? MIN_CACHEABLE_TOKENS) * CHARS_PER_TOKEN;
+/**
+ * The marker itself. `ttl` is omitted for the 5-minute default so the emitted bytes stay
+ * the classic shape — a request that differs only in an explicit `"ttl": "5m"` would not
+ * match a prefix cached without it.
+ */
+const marker = (ttl) => ttl === '1h' ? { type: 'ephemeral', ttl: '1h' } : { type: 'ephemeral' };
+const contentLength = (content) => {
+    if (typeof content === 'string') {
+        return content.length;
+    }
+    if (Array.isArray(content)) {
+        return content.reduce((sum, part) => {
+            const text = part.text;
+            return sum + (typeof text === 'string' ? text.length : 0);
+        }, 0);
+    }
+    return 0;
+};
+/**
+ * Put a breakpoint on a message's LAST content block, lifting string content into a block
+ * so the marker has somewhere to live. Idempotent, and it never mutates a block the
+ * caller owns — the array is rebuilt around a fresh copy of the final entry.
+ */
+const markMessage = (msg, mark) => {
+    if (typeof msg.content === 'string') {
+        msg.content = [{ type: 'text', text: msg.content, cache_control: mark }];
+        return true;
+    }
+    if (Array.isArray(msg.content) && msg.content.length > 0) {
+        const blocks = [...msg.content];
+        const last = blocks[blocks.length - 1];
+        if (last.cache_control != null) {
+            return true;
+        }
+        blocks[blocks.length - 1] = { ...last, cache_control: mark };
+        msg.content = blocks;
+        return true;
+    }
+    return false;
+};
 export const anthropicPlugin = {
     type: ModelProvider.Anthropic,
     family: ANTHROPIC_FAMILY,
@@ -57,30 +105,97 @@ export const anthropicPlugin = {
         return new ChatAnthropic(cfg);
     },
     /**
-     * Mark the leading messages with an ephemeral `cache_control` breakpoint. Anthropic
-     * allows at most {@link MAX_CACHE_BREAKPOINTS}; string content is lifted into a
-     * single text block so the marker has somewhere to live.
+     * Render the composed system prompt as Anthropic content blocks, one per section, with
+     * a breakpoint on each stability boundary:
+     *
+     * - after `Role` + `Skills` — the region every call of this role shares;
+     * - after `Packages`        — varies with what the request mentions, so it gets its own
+     *                             entry and can never invalidate the block above it;
+     * - after the last block    — so the whole system prompt is cached, which is the
+     *                             default this layer promises.
+     *
+     * Boundaries that coincide collapse into one. Marking stops as soon as the budget is
+     * spent, earliest boundary first — the earliest prefix is the one most calls share.
      */
-    patchCache: (msgs, { model, useCache, cacheMax }) => {
-        if (!useCache || !model.modelName?.startsWith(CACHEABLE_PREFIX))
+    patchSystem: (blocks, { model, cacheMax, ttl }) => {
+        const content = blocks.map(block => ({ type: 'text', text: block.text }));
+        if (!supportsCache(model) || cacheMax < 1) {
+            return { content: content, breakpoints: 0 };
+        }
+        const lastOf = (...wanted) => blocks.reduce((found, block, i) => wanted.includes(block.block) ? i : found, -1);
+        // Closing the prompt is worth a breakpoint only when the last block is STABLE. A
+        // trailing `Context` changes every call, so marking it would pay a cache write every
+        // time and never read one back — it burns a breakpoint to buy nothing. A prompt that
+        // is ONLY context (a caller that has not adopted role/skills) is still worth marking,
+        // because there it IS the stable part.
+        const last = blocks.length - 1;
+        const closing = blocks[last].block === PromptBlock.Context && blocks.length > 1 ? -1 : last;
+        const boundaries = [...new Set([
+                lastOf(PromptBlock.Role, PromptBlock.Skills),
+                lastOf(PromptBlock.Packages),
+                closing,
+            ].filter(index => index >= 0))].sort((a, b) => a - b);
+        const minChars = minCacheableChars(model);
+        let consumed = 0;
+        let chars = 0;
+        let next = 0;
+        for (let i = 0; i < content.length; i++) {
+            chars += blocks[i].text.length;
+            if (i !== boundaries[next]) {
+                continue;
+            }
+            next++;
+            if (chars < minChars || consumed >= cacheMax) {
+                continue;
+            }
+            content[i].cache_control = marker(ttl);
+            consumed++;
+        }
+        return { content: content, breakpoints: consumed };
+    },
+    /**
+     * One breakpoint, at the end of the stable message prefix (`cacheMax` messages).
+     *
+     * Not one marker per message: the request budget is {@link MAX_CACHE_BREAKPOINTS} in
+     * total across tools, system and messages, and the system prompt — the part that is
+     * genuinely identical between calls — has first claim on it. `reserved` is what the
+     * system prompt already spent.
+     */
+    patchCache: (msgs, { model, useCache, cacheMax, reserved = 0, ttl = '5m' }) => {
+        if (!useCache || !supportsCache(model) || msgs.length === 0) {
             return false;
-        const max = Math.min(cacheMax, MAX_CACHE_BREAKPOINTS);
-        let i = 0;
-        for (const msg of msgs) {
-            msg.content = typeof msg.content === 'string' ? [{
-                    type: 'text',
-                    text: msg.content,
-                    cache_control: { type: 'ephemeral' },
-                }] : msg.content;
-            if (++i > max - 1)
-                break;
         }
-        return true;
+        if (Math.min(cacheMax, MAX_CACHE_BREAKPOINTS - reserved) < 1) {
+            return false;
+        }
+        // The final message is the per-call payload, and `ensureJsonMention` / `applyNoThink`
+        // append to it — including it in the prefix would write a fresh entry every call and
+        // read none. The stable prefix therefore stops one short of the end.
+        const index = Math.min(cacheMax, msgs.length - 1) - 1;
+        const target = index >= 0 ? msgs[index] : null;
+        if (target == null) {
+            return false;
+        }
+        const chars = msgs.slice(0, index + 1)
+            .reduce((sum, msg) => sum + contentLength(msg.content), 0);
+        if (chars < minCacheableChars(model)) {
+            return false;
+        }
+        return markMessage(target, marker(ttl));
     },
     /**
-     * A malformed request (bad schema, unsupported parameter, oversized `max_tokens`)
-     * cannot be fixed by retrying — surface it immediately instead of burning the budget.
+     * A malformed request (bad schema, unsupported parameter, oversized `max_tokens`, too
+     * many cache breakpoints) cannot be fixed by retrying — surface it immediately instead
+     * of burning the budget.
+     *
+     * The `status` check is not redundant with the `instanceof`: `@langchain/anthropic`
+     * carries its OWN nested copy of `@anthropic-ai/sdk`, so the error it throws is an
+     * instance of a DIFFERENT `BadRequestError` class than the one imported here and the
+     * `instanceof` silently fails. That turned every fatal 400 into eight full retries —
+     * a single malformed request became minutes of thrash with the real cause buried.
      */
-    isFatal: e => e instanceof BadRequestError ? e : null,
+    isFatal: e => e instanceof BadRequestError || e?.status === 400
+        ? e
+        : null,
 };
 //# sourceMappingURL=anthropic.js.map

package/build/plugins/anthropic.js.map

@@ -1 +1 @@
-{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../src/plugins/anthropic.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../src/plugins/anthropic.ts"],"names":[],"mappings":"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"}

package/build/plugins/openai.d.ts

@@ -17,6 +17,15 @@ export declare const openAiFamily: {
      * an aggregator route only to providers that actually support structured outputs.
      */
     responseFormat: (toolName: string, schema: unknown) => Record<string, unknown>;
+    /**
+     * A 400 means the request itself is malformed — a schema the endpoint rejects, an
+     * unsupported parameter, a `max_tokens` above the model's per-request limit. Retrying
+     * re-sends the same shape (and the escalator raises `max_tokens`, making the last case
+     * strictly worse), so eight attempts only bury the real message. Matched on `status`
+     * rather than an SDK class: aggregators and nested SDK copies throw their own error
+     * types, and an `instanceof` against one of them silently never matches.
+     */
+    isFatal: (e: unknown) => Error | null;
     refine: ({ base, attempt, temperature, maxOutputCap }: LlmRefineParams) => BaseChatModel;
 };
 /**

package/build/plugins/openai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/plugins/openai.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAA;AAEhF,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAO5D,eAAO,MAAM,aAAa,WAAW,CAAA;AAErC,0FAA0F;AAC1F,eAAO,MAAM,YAAY;;kBAGT,aAAa,KAAG,OAAO;IAErC;;;OAGG;2BACoB,MAAM,KAAG,OAAO;IAEvC;;;;;OAKG;+BACwB,MAAM,UAAU,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;2DAKrB,eAAe,KAAG,aAAa;CA2BvF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,SAsC1B,CAAA"}
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/plugins/openai.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAA;AAEhF,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAO5D,eAAO,MAAM,aAAa,WAAW,CAAA;AAErC,0FAA0F;AAC1F,eAAO,MAAM,YAAY;;kBAGT,aAAa,KAAG,OAAO;IAErC;;;OAGG;2BACoB,MAAM,KAAG,OAAO;IAEvC;;;;;OAKG;+BACwB,MAAM,UAAU,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAK5E;;;;;;;OAOG;iBACU,OAAO,KAAG,KAAK,GAAG,IAAI;2DAGoB,eAAe,KAAG,aAAa;CA2BvF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,SAoD1B,CAAA"}

package/build/plugins/openai.js

@@ -23,6 +23,15 @@ export const openAiFamily = {
         type: 'json_schema',
         json_schema: { name: toolName, schema, strict: false },
     }),
+    /**
+     * A 400 means the request itself is malformed — a schema the endpoint rejects, an
+     * unsupported parameter, a `max_tokens` above the model's per-request limit. Retrying
+     * re-sends the same shape (and the escalator raises `max_tokens`, making the last case
+     * strictly worse), so eight attempts only bury the real message. Matched on `status`
+     * rather than an SDK class: aggregators and nested SDK copies throw their own error
+     * types, and an `instanceof` against one of them silently never matches.
+     */
+    isFatal: (e) => e?.status === 400 ? e : null,
     refine: ({ base, attempt, temperature, maxOutputCap }) => {
         const model = base;
         const currentTemperature = temperature ?? model.temperature ?? 0;
@@ -57,9 +66,20 @@ export const openAiPlugin = {
     ...openAiFamily,
     type: ModelProvider.OpenAI,
     structuredMode: (config) => config.structuredOutput === false ? StructuredMode.Tool : StructuredMode.Native,
-    build: ({ config, secret, callbacks }) => {
+    build: ({ alias, config, secret, callbacks }) => {
         const model = config.model ??= 'gpt-5.4-mini';
         const configuration = makeConfiguration({ baseURL: undefined, headers: config.headers });
+        // OpenAI's prompt cache is automatic and prefix-based — there is nothing to mark. The
+        // one lever a client has is routing: requests are dispatched by a hash of the prompt's
+        // opening tokens, and `prompt_cache_key` is mixed into that hash, so requests sharing
+        // a key land on the same backend and can actually hit each other's entries. The key
+        // must be stable and low-cardinality; the config alias IS the role, which is exactly
+        // the granularity at which a system prefix is shared.
+        //
+        // Deliberately NOT done for the `compatible` plugin: aggregators there run with
+        // `provider.require_parameters`, and an unknown top-level field can exclude every
+        // serving provider from the route.
+        const modelKwargs = { prompt_cache_key: config.cacheKey ?? alias };
         // The Responses API models reject `temperature`/`topP`.
         if (RESPONSES_API_PREFIXES.some(prefix => model.startsWith(prefix))) {
             return new ChatOpenAI({
@@ -70,6 +90,7 @@ export const openAiPlugin = {
                 useResponsesApi: true,
                 metadata: { config },
                 callbacks,
+                modelKwargs,
                 ...configuration,
             });
         }
@@ -82,6 +103,7 @@ export const openAiPlugin = {
             maxRetries: 5,
             metadata: { config },
             callbacks,
+            modelKwargs,
             ...configuration,
         });
     },

package/build/plugins/openai.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/plugins/openai.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/plugins/openai.ts"],"names":[],"mappings":"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"}

package/build/plugins/types.d.ts

@@ -1,7 +1,7 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { BaseCallbackHandler, CallbackHandlerMethods } from '@langchain/core/callbacks/base';
-import type { MessageFieldWithRole } from '@langchain/core/messages';
-import type { StructuredMode } from '@owlmeans/llm-common';
+import type { MessageContent, MessageFieldWithRole } from '@langchain/core/messages';
+import type { CacheTtl, PromptBlock, StructuredMode } from '@owlmeans/llm-common';
 import type { ModelConfig } from '../types.js';
 export interface LlmBuildParams {
     /** Alias the config was registered under — used only for error reporting. */
@@ -29,7 +29,29 @@ export interface LlmCacheParams {
     /** The ORIGINAL (unrefined) model — refined instances do not always keep the name. */
     model: BaseChatModel;
     useCache: boolean;
+    /** How many leading messages form the stable prefix worth caching. */
     cacheMax: number;
+    /** Breakpoints the composed system prompt already spent on this request. */
+    reserved?: number;
+    ttl?: CacheTtl;
+}
+/** One rendered section of the composed system prompt, in emission order. */
+export interface LlmSystemBlock {
+    block: PromptBlock;
+    text: string;
+}
+export interface LlmSystemCacheParams {
+    /** The ORIGINAL (unrefined) model. */
+    model: BaseChatModel;
+    /** Breakpoint budget the system prompt may spend. */
+    cacheMax: number;
+    ttl: CacheTtl;
+}
+/** Provider-native rendering of the composed system prompt. */
+export interface LlmSystemRender {
+    content: MessageContent;
+    /** Breakpoints consumed — subtracted from the message-level budget. */
+    breakpoints: number;
 }
 /**
  * Everything that differs between inference providers, in one replaceable unit.
@@ -66,11 +88,22 @@ export interface LlmPlugin {
     /** Provider-specific `response_format` for {@link StructuredMode.Native}. */
     responseFormat?: (toolName: string, schema: unknown) => Record<string, unknown>;
     /**
-     * Mark leading messages as cacheable in-place. Returns `true` when caching was
-     * actually applied (the model may not support it). Omit for providers with no
-     * explicit prompt-cache markers.
+     * Mark the stable message prefix as cacheable, in-place. ONE breakpoint at the end of
+     * that prefix — not one per message: the budget is four per request and the system
+     * prompt has first claim on it. Returns `true` when a marker was actually placed.
+     * Omit for providers with no explicit prompt-cache markers.
      */
     patchCache?: (msgs: MessageFieldWithRole[], params: LlmCacheParams) => boolean;
+    /**
+     * Render the composed system blocks into provider-native content, placing cache
+     * breakpoints at the stability boundaries between blocks (see `PromptBlock`).
+     *
+     * Return `null` — or omit the method entirely — for providers whose prompt cache is
+     * automatic and prefix-based (OpenAI and friends): the service then joins the blocks
+     * into a plain string, which is all those providers need, since the block ORDER is
+     * what makes their prefix stable.
+     */
+    patchSystem?: (blocks: LlmSystemBlock[], params: LlmSystemCacheParams) => LlmSystemRender | null;
     /**
      * Classify a thrown error as fatal for the retry loop. Return the error to throw
      * immediately, or `null` to let it be retried.

package/build/plugins/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAA;AAChF,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACjG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,CAAC,mBAAmB,GAAG,sBAAsB,CAAC,EAAE,CAAA;CAC5D;AAED,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,IAAI,EAAE,aAAa,CAAA;IACnB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,KAAK,EAAE,aAAa,CAAA;IACpB,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IAEZ;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd,wDAAwD;IACxD,KAAK,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,aAAa,CAAA;IAEhD,sEAAsE;IACtE,IAAI,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAA;IAEvC;;;;OAIG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,aAAa,CAAA;IAElD,sEAAsE;IACtE,cAAc,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,cAAc,CAAA;IAEvD,+EAA+E;IAC/E,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAA;IAEzC,6EAA6E;IAC7E,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAE/E;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,EAAE,EAAE,MAAM,EAAE,cAAc,KAAK,OAAO,CAAA;IAE9E;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,KAAK,GAAG,IAAI,CAAA;CACvC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":"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"}

package/build/prompt/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './types.js';
+export * from './render.js';
+export * from './plugins.js';
+export * from './service.js';
+//# sourceMappingURL=index.d.ts.map

package/build/prompt/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompt/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}

package/build/prompt/index.js

@@ -0,0 +1,4 @@
+export * from './render.js';
+export * from './plugins.js';
+export * from './service.js';
+//# sourceMappingURL=index.js.map

package/build/prompt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompt/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}

package/build/prompt/plugins.d.ts

@@ -0,0 +1,24 @@
+import type { LlmPromptPlugin } from './types.js';
+/**
+ * Block 0 — the base system prompt that tells the model who it is.
+ *
+ * The most stable thing in the whole request, so it goes first and every cache boundary
+ * sits behind it.
+ */
+export declare const rolePlugin: LlmPromptPlugin;
+/**
+ * Block 1 — the declared capabilities, rendered in a deterministic order.
+ *
+ * Registry skills and inline skills are merged by alias with inline winning, so a caller
+ * can override one registered entry without forking the catalogue.
+ */
+export declare const skillsPlugin: LlmPromptPlugin;
+/**
+ * Block 3 — whatever the caller handed over verbatim, plus any skills requested for this
+ * one call. Emitted last and never marked cacheable: its content varies per request by
+ * definition, and a varying tail must not sit inside a prefix other calls depend on.
+ */
+export declare const contextPlugin: LlmPromptPlugin;
+/** The plugins every {@link PromptService} starts with, in run order. */
+export declare const BUILT_IN_PROMPT_PLUGINS: readonly LlmPromptPlugin[];
+//# sourceMappingURL=plugins.d.ts.map

package/build/prompt/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/prompt/plugins.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,eAQxB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,eAa1B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAEpD,CAAA"}

package/build/prompt/plugins.js

@@ -0,0 +1,64 @@
+import { PromptBlock } from '@owlmeans/llm-common';
+import { joinChunks, renderSkill, sortSkills } from './render.js';
+/**
+ * Block 0 — the base system prompt that tells the model who it is.
+ *
+ * The most stable thing in the whole request, so it goes first and every cache boundary
+ * sits behind it.
+ */
+export const rolePlugin = {
+    alias: 'role',
+    order: 0,
+    compose: ctx => {
+        if (ctx.input.role != null && ctx.input.role.trim() !== '') {
+            ctx.add(PromptBlock.Role, ctx.input.role);
+        }
+    },
+};
+/**
+ * Block 1 — the declared capabilities, rendered in a deterministic order.
+ *
+ * Registry skills and inline skills are merged by alias with inline winning, so a caller
+ * can override one registered entry without forking the catalogue.
+ */
+export const skillsPlugin = {
+    alias: 'skills',
+    order: 10,
+    compose: ctx => {
+        const declared = ctx.resolve(ctx.input.skills ?? []);
+        const merged = new Map();
+        for (const skill of [...declared, ...(ctx.input.inline ?? [])]) {
+            merged.set(skill.alias, skill);
+        }
+        for (const skill of sortSkills([...merged.values()])) {
+            ctx.add(skill.block ?? PromptBlock.Skills, renderSkill(skill));
+        }
+    },
+};
+/**
+ * Block 3 — whatever the caller handed over verbatim, plus any skills requested for this
+ * one call. Emitted last and never marked cacheable: its content varies per request by
+ * definition, and a varying tail must not sit inside a prefix other calls depend on.
+ */
+export const contextPlugin = {
+    alias: 'context',
+    order: 90,
+    compose: ctx => {
+        // Everything volatile is merged into ONE chunk rather than added piece by piece: the
+        // block carries no cache breakpoint, so there is nothing to gain from keeping the
+        // parts separable, and a single contiguous section reads as one instruction to the
+        // model instead of a pile of loose fragments.
+        const parts = [
+            ...sortSkills(ctx.resolve(ctx.input.callSkills ?? [])).map(renderSkill),
+            ...(ctx.input.context ?? []),
+        ];
+        if (parts.length > 0) {
+            ctx.add(PromptBlock.Context, joinChunks(parts));
+        }
+    },
+};
+/** The plugins every {@link PromptService} starts with, in run order. */
+export const BUILT_IN_PROMPT_PLUGINS = [
+    rolePlugin, skillsPlugin, contextPlugin,
+];
+//# sourceMappingURL=plugins.js.map

package/build/prompt/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../../src/prompt/plugins.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAElD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGjE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAoB;IACzC,KAAK,EAAE,MAAM;IACb,KAAK,EAAE,CAAC;IACR,OAAO,EAAE,GAAG,CAAC,EAAE;QACb,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC3D,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAC3C,CAAC;IACH,CAAC;CACF,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAoB;IAC3C,KAAK,EAAE,QAAQ;IACf,KAAK,EAAE,EAAE;IACT,OAAO,EAAE,GAAG,CAAC,EAAE;QACb,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAA;QACpD,MAAM,MAAM,GAAG,IAAI,GAAG,EAA2B,CAAA;QACjD,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YAC/D,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QAChC,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAA;QAChE,CAAC;IACH,CAAC;CACF,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAoB;IAC5C,KAAK,EAAE,SAAS;IAChB,KAAK,EAAE,EAAE;IACT,OAAO,EAAE,GAAG,CAAC,EAAE;QACb,qFAAqF;QACrF,kFAAkF;QAClF,mFAAmF;QACnF,8CAA8C;QAC9C,MAAM,KAAK,GAAG;YACZ,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC;YACvE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;SAC7B,CAAA;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAA;QACjD,CAAC;IACH,CAAC;CACF,CAAA;AAED,yEAAyE;AACzE,MAAM,CAAC,MAAM,uBAAuB,GAA+B;IACjE,UAAU,EAAE,YAAY,EAAE,aAAa;CAC/B,CAAA"}

package/build/prompt/render.d.ts

@@ -0,0 +1,28 @@
+import type { SkillDefinition } from '@owlmeans/llm-common';
+/**
+ * Separator between rendered chunks. Every join in this file goes through it: the
+ * composed prompt must be byte-identical between calls, so there is exactly one way to
+ * glue things together.
+ */
+export declare const CHUNK_SEPARATOR = "\n\n";
+/**
+ * Code-unit comparison, NOT `localeCompare`.
+ *
+ * `localeCompare` orders differently depending on the host's ICU data and locale, so two
+ * processes could render the same skill set in different orders and never share a cache
+ * entry. Skill aliases are ASCII slugs; a plain comparison is both correct and stable.
+ */
+export declare const compareAlias: (a: string, b: string) => number;
+/** Deterministic skill order: declared weight first, alias as the tiebreaker. */
+export declare const sortSkills: (skills: readonly SkillDefinition[]) => SkillDefinition[];
+/** Fixed rendering of one skill. Changing this shape invalidates every cached prefix. */
+export declare const renderSkill: (skill: SkillDefinition) => string;
+/** Join rendered chunks into one block, dropping empties. */
+export declare const joinChunks: (parts: readonly string[]) => string;
+/**
+ * Stable digest of a cache prefix — FNV-1a, so there is no crypto dependency and the
+ * result is identical on every runtime. Used as a provider cache-routing key (OpenAI's
+ * `prompt_cache_key`), never for security.
+ */
+export declare const prefixHash: (text: string) => string;
+//# sourceMappingURL=render.d.ts.map

package/build/prompt/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/prompt/render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAE3D;;;;GAIG;AACH,eAAO,MAAM,eAAe,SAAS,CAAA;AAErC;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAAoC,CAAA;AAExF,iFAAiF;AACjF,eAAO,MAAM,UAAU,GAAI,QAAQ,SAAS,eAAe,EAAE,KAAG,eAAe,EAK3E,CAAA;AAEJ,yFAAyF;AACzF,eAAO,MAAM,WAAW,GAAI,OAAO,eAAe,KAAG,MACO,CAAA;AAE5D,6DAA6D;AAC7D,eAAO,MAAM,UAAU,GAAI,OAAO,SAAS,MAAM,EAAE,KAAG,MAC4B,CAAA;AAElF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,MAOzC,CAAA"}

package/build/prompt/render.js

@@ -0,0 +1,39 @@
+import { DEFAULT_SKILL_ORDER } from '@owlmeans/llm-common';
+/**
+ * Separator between rendered chunks. Every join in this file goes through it: the
+ * composed prompt must be byte-identical between calls, so there is exactly one way to
+ * glue things together.
+ */
+export const CHUNK_SEPARATOR = '\n\n';
+/**
+ * Code-unit comparison, NOT `localeCompare`.
+ *
+ * `localeCompare` orders differently depending on the host's ICU data and locale, so two
+ * processes could render the same skill set in different orders and never share a cache
+ * entry. Skill aliases are ASCII slugs; a plain comparison is both correct and stable.
+ */
+export const compareAlias = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+/** Deterministic skill order: declared weight first, alias as the tiebreaker. */
+export const sortSkills = (skills) => [...skills].sort((a, b) => {
+    const left = a.order ?? DEFAULT_SKILL_ORDER;
+    const right = b.order ?? DEFAULT_SKILL_ORDER;
+    return left !== right ? left - right : compareAlias(a.alias, b.alias);
+});
+/** Fixed rendering of one skill. Changing this shape invalidates every cached prefix. */
+export const renderSkill = (skill) => `## ${skill.title ?? skill.alias}\n\n${skill.body.trim()}`;
+/** Join rendered chunks into one block, dropping empties. */
+export const joinChunks = (parts) => parts.map(part => part.trim()).filter(part => part !== '').join(CHUNK_SEPARATOR);
+/**
+ * Stable digest of a cache prefix — FNV-1a, so there is no crypto dependency and the
+ * result is identical on every runtime. Used as a provider cache-routing key (OpenAI's
+ * `prompt_cache_key`), never for security.
+ */
+export const prefixHash = (text) => {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(36);
+};
+//# sourceMappingURL=render.js.map

package/build/prompt/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/prompt/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAG1D;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAA;AAErC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAExF,iFAAiF;AACjF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAkC,EAAqB,EAAE,CAClF,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;IACxB,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,IAAI,mBAAmB,CAAA;IAC3C,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,mBAAmB,CAAA;IAC5C,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAA;AACvE,CAAC,CAAC,CAAA;AAEJ,yFAAyF;AACzF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAsB,EAAU,EAAE,CAC5D,MAAM,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAA;AAE5D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAwB,EAAU,EAAE,CAC7D,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;AAElF;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAU,EAAE;IACjD,IAAI,IAAI,GAAG,UAAU,CAAA;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;QAC1B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,CAAA;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;AAC1B,CAAC,CAAA"}

package/build/prompt/service.d.ts

@@ -0,0 +1,16 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context';
+import type { PromptService, PromptServiceOptions, WithPromptService } from './types.js';
+/** The part of {@link PromptService} this package implements — see {@link promptServiceApi}. */
+export type PromptServiceApi = Pick<PromptService, 'use' | 'register' | 'has' | 'resolve' | 'skills' | 'compose'>;
+/**
+ * Build the skill registry and composition chain WITHOUT registering a context service,
+ * so a consumer can spread it into its own `createService` and publish extra methods
+ * alongside it — the same pattern as `llmServiceApi` / `executionServiceApi`.
+ *
+ * `self` is late-bound because plugins resolve skills through the finished service, which
+ * a consumer may have extended.
+ */
+export declare const promptServiceApi: (options: PromptServiceOptions, self: () => PromptService) => PromptServiceApi;
+export declare const makePromptService: (options?: PromptServiceOptions, alias?: string) => PromptService;
+export declare const appendPromptService: <C extends BasicConfig, T extends BasicContext<C>>(ctx: T, options?: PromptServiceOptions, alias?: string) => T & WithPromptService;
+//# sourceMappingURL=service.d.ts.map

package/build/prompt/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/prompt/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AASlE,OAAO,KAAK,EACoC,aAAa,EAAE,oBAAoB,EACjF,iBAAiB,EAClB,MAAM,YAAY,CAAA;AAKnB,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAC1B,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,UAAU,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAA;AAEpF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,oBAAoB,EAC7B,MAAM,MAAM,aAAa,KACxB,gBAuIF,CAAA;AAED,eAAO,MAAM,iBAAiB,GAC5B,UAAS,oBAAyB,EAClC,QAAO,MAAuB,KAC7B,aAMF,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EAClF,KAAK,CAAC,EACN,UAAS,oBAAyB,EAClC,QAAO,MAAuB,KAC7B,CAAC,GAAG,iBAQN,CAAA"}