@owlmeans/llm 0.1.15 → 0.1.16

package/build/prompt/service.js

@@ -0,0 +1,145 @@
+import { createService } from '@owlmeans/context';
+import { PROMPT_BLOCK_ORDER } from '@owlmeans/llm-common';
+import { DEFAULT_CACHE_TTL, MAX_CACHE_BREAKPOINTS, MAX_SYSTEM_BREAKPOINTS, PROMPT_SERVICE, } from '../consts.js';
+import { BUILT_IN_PROMPT_PLUGINS } from './plugins.js';
+import { CHUNK_SEPARATOR, compareAlias, joinChunks } from './render.js';
+/** Sort weight of a plugin that declares none — between the built-in skills and context. */
+const DEFAULT_PLUGIN_ORDER = 50;
+/**
+ * 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 const promptServiceApi = (options, self) => {
+    const registry = new Map();
+    /** Registration index per plugin alias — the stable tiebreaker for equal `order`. */
+    const seats = new Map();
+    let seq = 0;
+    const seat = (plugin) => {
+        const existing = seats.get(plugin.alias);
+        // Re-registering under the same alias REPLACES rather than appends, so wiring the
+        // same plugin twice (a shared context builder plus an app) cannot double-emit.
+        seats.set(plugin.alias, { plugin, index: existing?.index ?? seq++ });
+    };
+    for (const plugin of [...BUILT_IN_PROMPT_PLUGINS, ...(options.plugins ?? [])]) {
+        seat(plugin);
+    }
+    const ordered = () => [...seats.values()]
+        .sort((a, b) => {
+        const left = a.plugin.order ?? DEFAULT_PLUGIN_ORDER;
+        const right = b.plugin.order ?? DEFAULT_PLUGIN_ORDER;
+        return left !== right ? left - right : a.index - b.index;
+    })
+        .map(entry => entry.plugin);
+    const api = {
+        use: plugin => {
+            seat(plugin);
+        },
+        register: (...skills) => {
+            for (const skill of skills) {
+                registry.set(skill.alias, skill);
+            }
+        },
+        has: alias => registry.has(alias),
+        skills: () => [...registry.values()].sort((a, b) => compareAlias(a.alias, b.alias)),
+        /**
+         * Depth-first over `requires` so a dependency is emitted before the skill that pulled
+         * it in. Unknown aliases are skipped rather than thrown: a skill catalogue is often
+         * assembled from several packages and a missing optional one should degrade the
+         * prompt, not break the call.
+         */
+        resolve: aliases => {
+            const seen = new Set();
+            const out = [];
+            const walk = (alias) => {
+                if (seen.has(alias)) {
+                    return;
+                }
+                seen.add(alias);
+                const skill = registry.get(alias);
+                if (skill == null) {
+                    return;
+                }
+                for (const required of skill.requires ?? []) {
+                    walk(required);
+                }
+                out.push(skill);
+            };
+            for (const alias of aliases) {
+                walk(alias);
+            }
+            return out;
+        },
+        compose: async (input, messages, params) => {
+            const sections = new Map();
+            const ctx = {
+                ...params,
+                input,
+                messages,
+                add: (block, text) => {
+                    const trimmed = text.trim();
+                    if (trimmed === '') {
+                        return;
+                    }
+                    const chunks = sections.get(block);
+                    if (chunks == null) {
+                        sections.set(block, [trimmed]);
+                    }
+                    else {
+                        chunks.push(trimmed);
+                    }
+                },
+                resolve: aliases => self().resolve(aliases),
+            };
+            // Two passes, not one: every static contribution must be in place before a plugin
+            // that reacts to the messages runs, so detection can see what is already covered.
+            const chain = ordered();
+            for (const plugin of chain) {
+                await plugin.compose?.(ctx);
+            }
+            for (const plugin of chain) {
+                await plugin.inspect?.(ctx);
+            }
+            const blocks = [];
+            for (const block of PROMPT_BLOCK_ORDER) {
+                const text = joinChunks(sections.get(block) ?? []);
+                if (text !== '') {
+                    blocks.push({ block, text });
+                }
+            }
+            if (blocks.length === 0) {
+                return { system: null, breakpoints: 0, blocks };
+            }
+            const cacheSystem = input.cacheSystem ?? options.cacheSystem ?? true;
+            const ttl = input.cacheTtl ?? options.cacheTtl ?? DEFAULT_CACHE_TTL;
+            const budget = Math.min(params.cacheMax ?? MAX_CACHE_BREAKPOINTS, MAX_SYSTEM_BREAKPOINTS);
+            const render = cacheSystem && budget > 0
+                ? params.provider?.patchSystem?.(blocks, { model: params.model, cacheMax: budget, ttl })
+                : null;
+            return {
+                system: {
+                    role: 'system',
+                    content: render?.content ?? blocks.map(block => block.text).join(CHUNK_SEPARATOR),
+                },
+                breakpoints: render?.breakpoints ?? 0,
+                blocks,
+            };
+        },
+    };
+    api.register(...(options.skills ?? []));
+    return api;
+};
+export const makePromptService = (options = {}, alias = PROMPT_SERVICE) => {
+    const service = createService(alias, promptServiceApi(options, () => service));
+    return service;
+};
+export const appendPromptService = (ctx, options = {}, alias = PROMPT_SERVICE) => {
+    const context = ctx;
+    context.registerService(makePromptService(options, alias));
+    context.prompts = () => context.service(alias);
+    return context;
+};
+//# sourceMappingURL=service.js.map

package/build/prompt/service.js.map

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

package/build/prompt/types.d.ts

@@ -0,0 +1,101 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { MessageFieldWithRole } from '@langchain/core/messages';
+import type { InitializedService } from '@owlmeans/context';
+import type { CacheTtl, FileProviderRef, LlmPurpose, PromptBlock, PromptPolicy, SkillDefinition } from '@owlmeans/llm-common';
+import type { LlmPlugin, LlmSystemBlock } from '../plugins/types.js';
+/**
+ * Everything that shapes one composed system prompt. The serializable part
+ * ({@link PromptPolicy}) travels on the execution state; the rest is per-call.
+ */
+export interface PromptInput extends PromptPolicy {
+    /** Skills supplied verbatim, without registering them first. */
+    inline?: SkillDefinition[];
+    /**
+     * Raw text for the volatile `Context` block — a caller's own system message, carried
+     * through unchanged. Never part of the cached prefix.
+     */
+    context?: string[];
+    /**
+     * Skill aliases requested for THIS call only. Rendered into `Context`, not `Skills`:
+     * a set that changes per call must not sit inside the region other calls cache.
+     */
+    callSkills?: string[];
+}
+export interface PromptComposeParams {
+    /** The ORIGINAL (unrefined) model the composed prompt will be sent to. */
+    model: BaseChatModel;
+    /** Provider plugin governing the call — supplies the cache-marker strategy. */
+    provider?: LlmPlugin;
+    purpose?: LlmPurpose;
+    action?: string;
+    /** Total breakpoint budget for the request. */
+    cacheMax?: number;
+    /** File access a plugin may use to resolve knowledge from disk. */
+    files?: FileProviderRef;
+}
+/** What a prompt plugin sees and may contribute to. */
+export interface PromptContext extends PromptComposeParams {
+    input: PromptInput;
+    /** The call's messages. Read them for detection; do NOT mutate. */
+    messages: readonly MessageFieldWithRole[];
+    /** Append a rendered chunk to a block. Empty text is ignored. */
+    add: (block: PromptBlock, text: string) => void;
+    /** Resolve skill aliases through the registry, following `requires`. */
+    resolve: (aliases: readonly string[]) => SkillDefinition[];
+}
+/**
+ * A unit of system-prompt composition, registered on the {@link PromptService} at context
+ * composition time. This is the seam that makes the LLM layer pluggable: the package
+ * ships the role and skills plugins, an application adds its own.
+ *
+ * A plugin MUST be deterministic — same input, same bytes. Anything it contributes to a
+ * cached block and cannot reproduce exactly invalidates the prefix for every call that
+ * shares it.
+ */
+export interface LlmPromptPlugin {
+    alias: string;
+    /** Lower runs first. The built-ins occupy 0 (role), 10 (skills) and 90 (context). */
+    order?: number;
+    /** Contribute static content, before anything has looked at the messages. */
+    compose?: (ctx: PromptContext) => void | Promise<void>;
+    /** Contribute content derived from the messages (detection, lookup, fetch). */
+    inspect?: (ctx: PromptContext) => void | Promise<void>;
+}
+export interface PromptResult {
+    /** The composed system message, or `null` when nothing was contributed. */
+    system: MessageFieldWithRole | null;
+    /** Breakpoints the system prompt consumed; subtract from the message budget. */
+    breakpoints: number;
+    /** The rendered blocks in emission order — exposed for tests and diagnostics. */
+    blocks: LlmSystemBlock[];
+}
+export interface PromptServiceOptions {
+    /** Skills registered up front; equivalent to calling `register` after construction. */
+    skills?: SkillDefinition[];
+    /** Plugins registered up front, in addition to the built-ins. */
+    plugins?: LlmPromptPlugin[];
+    /** Default for `PromptPolicy.cacheSystem`. Defaults to `true`. */
+    cacheSystem?: boolean;
+    /** Default for `PromptPolicy.cacheTtl`. */
+    cacheTtl?: CacheTtl;
+}
+/**
+ * Registry of reusable skills plus the plugin chain that turns a role and a set of skill
+ * aliases into a cache-friendly system prompt.
+ */
+export interface PromptService extends InitializedService {
+    /** Register a composition plugin. Runs in `order` then registration order. */
+    use: (plugin: LlmPromptPlugin) => void;
+    /** Register (or replace, by alias) reusable skills. */
+    register: (...skills: SkillDefinition[]) => void;
+    has: (alias: string) => boolean;
+    /** Resolve aliases to definitions, pulling in `requires` transitively. Unknown aliases are skipped. */
+    resolve: (aliases: readonly string[]) => SkillDefinition[];
+    /** Every registered skill, in deterministic order. */
+    skills: () => SkillDefinition[];
+    compose: (input: PromptInput, messages: readonly MessageFieldWithRole[], params: PromptComposeParams) => Promise<PromptResult>;
+}
+export interface WithPromptService {
+    prompts: () => PromptService;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/build/prompt/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/prompt/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/prompt/types.ts"],"names":[],"mappings":""}

package/build/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKlE,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAe,cAAc,EAAE,MAAM,YAAY,CAAA;AAE5F,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,GAAG,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,SAAS,CAAC,CAAA;AAE9G;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,iBAAiB,EAAE,MAAM,MAAM,UAAU,KAAG,aA2ElF,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,SAAS,iBAAiB,EAAE,QAAO,MAAoB,KAAG,UAMxF,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EAC/E,KAAK,CAAC,EACN,SAAS,iBAAiB,EAC1B,QAAO,MAAoB,KAC1B,CAAC,GAAG,cAQN,CAAA"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKlE,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAe,cAAc,EAAE,MAAM,YAAY,CAAA;AAE5F,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,GAAG,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,SAAS,CAAC,CAAA;AAE9G;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,iBAAiB,EAAE,MAAM,MAAM,UAAU,KAAG,aA8ElF,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,SAAS,iBAAiB,EAAE,QAAO,MAAoB,KAAG,UAMxF,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EAC/E,KAAK,CAAC,EACN,SAAS,iBAAiB,EAC1B,QAAO,MAAoB,KAC1B,CAAC,GAAG,cAQN,CAAA"}

package/build/service.js

@@ -42,6 +42,9 @@ export const llmServiceApi = (options, self) => {
             throw new LlmMissconfiguredError(alias);
         }
         const config = { ...baseConfig, ...override };
+        // The service-wide idle deadline is a floor, not an override: a preset that states its
+        // own `streamTimeout` knows something specific about that model and keeps it.
+        config.streamTimeout ??= options.streamTimeout;
         const preset = config.preset != null
             ? { ...(models.find(m => m.alias === config.preset) ?? {}) }
             : {};

package/build/service.js.map

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

package/build/types.d.ts

@@ -3,7 +3,8 @@ import type { AIMessage, BaseMessage, MessageFieldWithRole } from '@langchain/co
 import type { BaseCallbackHandler, CallbackHandlerMethods } from '@langchain/core/callbacks/base';
 import type { JSONSchemaType } from 'ajv';
 import type { InitializedService } from '@owlmeans/context';
-import type { LlmPurpose, ModelProvider, NullCapture, SpectatorArgument, SpectatorEntryLogged } from '@owlmeans/llm-common';
+import type { FileProviderRef, LlmPurpose, ModelProvider, NullCapture, SpectatorArgument, SpectatorEntryLogged } from '@owlmeans/llm-common';
+import type { PromptInput, PromptService } from './prompt/types.js';
 export type MaybeArray<T> = T | T[];
 /**
  * Out-of-band result channel for a model call: the caller passes a `ref` and receives
@@ -39,6 +40,20 @@ export interface LlmLogging {
 export interface LlmModelOptions extends LlmLogging {
     model: BaseChatModel;
     retries?: number;
+    /**
+     * Role and skills for every call this model makes. Composed into a cacheable system
+     * prompt by {@link PromptService}; ignored when no `prompts` resolver is supplied.
+     * Usually just `exec.prompt` from the helper execution.
+     */
+    prompt?: PromptInput;
+    /**
+     * Late-bound resolver for the prompt service — a function, like `Execution.models`, so
+     * the service can be swapped or cloned. Without it the model behaves exactly as before
+     * this layer existed: the caller's messages are sent untouched.
+     */
+    prompts?: () => PromptService;
+    /** File access offered to prompt plugins that resolve knowledge from disk. */
+    files?: FileProviderRef;
 }
 export type ModelMessage = BaseMessage | MessageFieldWithRole;
 export type ModelInputItem = ModelMessage | string;
@@ -46,10 +61,23 @@ export type ModelInput = MaybeArray<ModelInputItem>;
 export interface LlmCallOptions {
     /** Short name of the operation — used as the LangChain run name and in spectator entries. */
     action: string;
-    /** Ask the provider to cache the prompt prefix (no-op for providers without prompt caching). */
+    /**
+     * Cache the leading MESSAGES too. The composed system prompt is cached by default and
+     * independently of this flag — this one is about the conversation prefix, which is only
+     * worth caching when the same leading messages recur across calls.
+     */
     useCache?: boolean;
-    /** How many leading messages to mark as cacheable (capped by the provider's own limit). */
+    /**
+     * How many leading messages form the stable prefix. One breakpoint is placed at its
+     * end (not one per message), capped by whatever the system prompt left unspent.
+     */
     cacheMax?: number;
+    /**
+     * Skill aliases for THIS call only. Rendered into the volatile `Context` block, so they
+     * never disturb the cached region — declare a skill on the execution instead when it
+     * should be part of the shared prefix.
+     */
+    skills?: string[];
 }
 export interface LlmAskOptions extends LlmCallOptions {
     ref?: RefferedResult<AIMessage>;
@@ -165,10 +193,32 @@ export interface ModelConfig {
      * rotating providers mid-call would flip the structured-output format.
      */
     fallback?: Partial<ModelConfig>;
+    /**
+     * Per-model override of {@link MIN_CACHEABLE_TOKENS} — the shortest prefix worth a
+     * cache breakpoint. Anthropic's own minimum is model-dependent and NOT monotonic
+     * across generations (512 on the newest, 1024 on most, 4096 on a few older ones), so a
+     * preset that pins an old model should raise this rather than pay for markers that
+     * silently never cache.
+     */
+    cacheMinTokens?: number;
+    /**
+     * Cache-routing key for providers whose prompt cache is automatic (OpenAI's
+     * `prompt_cache_key`): requests sharing a key are routed to the same backend, which
+     * raises the hit rate for a shared prefix. Must be STABLE and low-cardinality — one
+     * value per role, never per user or per request. Defaults to the config alias.
+     */
+    cacheKey?: string;
 }
 export interface LlmServiceOptions {
     /** The full config list; resolved by `alias` on every `getModel` call. */
     models: () => ModelConfig[];
+    /**
+     * Idle deadline (ms) applied to every model this service builds, unless the model's own
+     * config overrides it. This is the knob an application sets where it composes its
+     * context — one place to tune how long the whole deployment waits on a silent provider,
+     * without touching a preset. Falls back to {@link MODEL_STREAM_TIMEOUT_MS}.
+     */
+    streamTimeout?: number;
 }
 /**
  * Model factory and registry. Builds a `BaseChatModel` from a `ModelConfig` through the

package/build/types.d.ts.map

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

package/build/utils/prompt.d.ts

@@ -1,4 +1,18 @@
 import type { MessageFieldWithRole } from '@langchain/core/messages';
+/**
+ * Drop every `cache_control` marker from the messages.
+ *
+ * Markers are placed in-place, on the caller's own message objects — and a caller that
+ * carries its message array across calls (the coder's growing conversation, a fix loop
+ * re-sending the same sources) hands them back still marked. The provider counts markers
+ * per REQUEST, not per message: Anthropic rejects the fifth outright with
+ * `400 A maximum of 4 blocks with cache_control may be provided. Found 5.`, and since a
+ * 400 is fatal it burns the entire retry budget before surfacing.
+ *
+ * So the pipeline always starts from a clean slate and re-places its own markers, which
+ * makes the per-request count a function of THIS call alone.
+ */
+export declare const stripCacheMarkers: (msgs: MessageFieldWithRole[]) => void;
 /**
  * Ensure the word "json" appears somewhere in the prompt. Several providers refuse or
  * silently ignore a JSON mode unless it does; when it is missing the JSON instruction is

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

@@ -1 +1 @@
-{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/utils/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAyBpE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,oBAAoB,EAAE,KAAG,IAGhE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,oBAAoB,EAAE,EAAE,iBAAiB,OAAO,GAAG,SAAS,KAAG,IAIjG,CAAA"}
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/utils/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAyBpE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,oBAAoB,EAAE,KAAG,IAkBhE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,oBAAoB,EAAE,KAAG,IAGhE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,oBAAoB,EAAE,EAAE,iBAAiB,OAAO,GAAG,SAAS,KAAG,IAIjG,CAAA"}

package/build/utils/prompt.js

@@ -19,6 +19,38 @@ const appendDirective = (msgs, text) => {
         msgs.push({ role: 'user', content: text });
     }
 };
+/**
+ * Drop every `cache_control` marker from the messages.
+ *
+ * Markers are placed in-place, on the caller's own message objects — and a caller that
+ * carries its message array across calls (the coder's growing conversation, a fix loop
+ * re-sending the same sources) hands them back still marked. The provider counts markers
+ * per REQUEST, not per message: Anthropic rejects the fifth outright with
+ * `400 A maximum of 4 blocks with cache_control may be provided. Found 5.`, and since a
+ * 400 is fatal it burns the entire retry budget before surfacing.
+ *
+ * So the pipeline always starts from a clean slate and re-places its own markers, which
+ * makes the per-request count a function of THIS call alone.
+ */
+export const stripCacheMarkers = (msgs) => {
+    for (const msg of msgs) {
+        if (!Array.isArray(msg.content)) {
+            continue;
+        }
+        let found = false;
+        const blocks = msg.content.map(part => {
+            if (typeof part === 'object' && part !== null && 'cache_control' in part) {
+                found = true;
+                const { cache_control: _dropped, ...rest } = part;
+                return rest;
+            }
+            return part;
+        });
+        if (found) {
+            msg.content = blocks;
+        }
+    }
+};
 /**
  * Ensure the word "json" appears somewhere in the prompt. Several providers refuse or
  * silently ignore a JSON mode unless it does; when it is missing the JSON instruction is

package/build/utils/prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/utils/prompt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEnE,MAAM,eAAe,GAAG,CAAC,GAAyB,EAAE,MAAc,EAAW,EAAE;IAC7E,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IACtF,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CACrB,CAAC,IAAa,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,IAAK,IAAgC;eACtG,OAAQ,IAA+B,CAAC,IAAI,KAAK,QAAQ;eACxD,IAA+B,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAC1E,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,qGAAqG;AACrG,MAAM,eAAe,GAAG,CAAC,IAA4B,EAAE,IAAY,EAAQ,EAAE;IAC3E,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAClC,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrD,IAAI,CAAC,OAAO,GAAG,GAAG,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAA;IAC3C,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;IAC5C,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAA4B,EAAQ,EAAE;IACtE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAAE,OAAM;IAC1D,eAAe,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAA;AACzC,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAA4B,EAAE,eAAoC,EAAQ,EAAE;IACvG,IAAI,eAAe,KAAK,IAAI;QAAE,OAAM;IACpC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;QAAE,OAAM;IACzG,eAAe,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAA;AAC3C,CAAC,CAAA"}
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/utils/prompt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEnE,MAAM,eAAe,GAAG,CAAC,GAAyB,EAAE,MAAc,EAAW,EAAE;IAC7E,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IACtF,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CACrB,CAAC,IAAa,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,IAAK,IAAgC;eACtG,OAAQ,IAA+B,CAAC,IAAI,KAAK,QAAQ;eACxD,IAA+B,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAC1E,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,qGAAqG;AACrG,MAAM,eAAe,GAAG,CAAC,IAA4B,EAAE,IAAY,EAAQ,EAAE;IAC3E,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAClC,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrD,IAAI,CAAC,OAAO,GAAG,GAAG,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAA;IAC3C,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;IAC5C,CAAC;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAA4B,EAAQ,EAAE;IACtE,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAChC,SAAQ;QACV,CAAC;QACD,IAAI,KAAK,GAAG,KAAK,CAAA;QACjB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;YACpC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,eAAe,IAAI,IAAI,EAAE,CAAC;gBACzE,KAAK,GAAG,IAAI,CAAA;gBACZ,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,IAA+B,CAAA;gBAC5E,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,IAAI,CAAA;QACb,CAAC,CAAC,CAAA;QACF,IAAI,KAAK,EAAE,CAAC;YACV,GAAG,CAAC,OAAO,GAAG,MAAuC,CAAA;QACvD,CAAC;IACH,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAA4B,EAAQ,EAAE;IACtE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAAE,OAAM;IAC1D,eAAe,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAA;AACzC,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAA4B,EAAE,eAAoC,EAAQ,EAAE;IACvG,IAAI,eAAe,KAAK,IAAI;QAAE,OAAM;IACpC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;QAAE,OAAM;IACzG,eAAe,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAA;AAC3C,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/llm",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -33,6 +33,13 @@
       "default": "./build/helpers/index.js",
       "module": "./build/helpers/index.js",
       "types": "./build/helpers/index.d.ts"
+    },
+    "./prompt": {
+      "import": "./build/prompt/index.js",
+      "require": "./build/prompt/index.js",
+      "default": "./build/prompt/index.js",
+      "module": "./build/prompt/index.js",
+      "types": "./build/prompt/index.d.ts"
     }
   },
   "devDependencies": {
@@ -40,7 +47,7 @@
     "@langchain/core": "^1.1.39",
     "@langchain/openai": "^1.4.4",
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test": "^0.1.15",
+    "@owlmeans/test": "^0.1.16",
     "@types/bun": "^1.3.14",
     "@types/node": "^26.1.0",
     "nodemon": "^3.1.14",
@@ -48,10 +55,10 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
-    "@owlmeans/basic-ids": "^0.1.15",
-    "@owlmeans/context": "^0.1.15",
-    "@owlmeans/error": "^0.1.15",
-    "@owlmeans/llm-common": "^0.1.15",
+    "@owlmeans/basic-ids": "^0.1.16",
+    "@owlmeans/context": "^0.1.16",
+    "@owlmeans/error": "^0.1.16",
+    "@owlmeans/llm-common": "^0.1.16",
     "ajv": "^8.17.1"
   },
   "publishConfig": {

package/src/consts.ts

@@ -1,5 +1,5 @@
 import { ExecutionEffort } from '@owlmeans/llm-common'
-import type { ModelConfigPatch } from '@owlmeans/llm-common'
+import type { CacheTtl, ModelConfigPatch } from '@owlmeans/llm-common'
 
 /** Context-service alias for the {@link LlmService} (model factory / registry). */
 export const LLM_SERVICE = 'owlmeans-llm-service'
@@ -7,6 +7,9 @@ export const LLM_SERVICE = 'owlmeans-llm-service'
 /** Context-service alias for the {@link ExecutionService}. */
 export const EXECUTION_SERVICE = 'owlmeans-llm-execution-service'
 
+/** Context-service alias for the {@link PromptService} (skill registry + composition). */
+export const PROMPT_SERVICE = 'owlmeans-llm-prompt-service'
+
 /** Default number of attempts a single model call makes before giving up. */
 export const DEFAULT_MODEL_RETRIES = 8
 
@@ -17,9 +20,15 @@ export const DEFAULT_MODEL_RETRIES = 8
  * against a provider that accepts the request and then never streams anything (observed
  * with throughput-sorted OpenRouter routing), which would otherwise block forever —
  * `maxRetries` never helps there because the request never errors, it just hangs.
- * Overridable per model via `ModelConfig.streamTimeout`.
+ * Overridable per model via `ModelConfig.streamTimeout`, or for every model at once via
+ * `LlmServiceOptions.streamTimeout` where the application composes its context.
+ *
+ * Three minutes, not longer: the timer resets on every token, so a legitimately long
+ * generation is never at risk — this only bounds SILENCE. The cost of a high value is
+ * paid entirely by hung calls, and a hang that takes five minutes to notice is a hang
+ * that can stall an agent run for half an hour once retries multiply it.
  */
-export const MODEL_STREAM_TIMEOUT_MS = 5 * 60 * 1000
+export const MODEL_STREAM_TIMEOUT_MS = 3 * 60 * 1000
 
 /**
  * Number of failed attempts after which the retry escalator switches from a role's
@@ -37,9 +46,38 @@ export const FALLBACK_AFTER_ATTEMPTS = 3
  */
 export const DEFAULT_MAX_OUTPUT_CAP = 3 * 64000
 
-/** Provider hard limit on prompt-cache breakpoints (Anthropic). */
+/** Provider hard limit on prompt-cache breakpoints per REQUEST (Anthropic). */
 export const MAX_CACHE_BREAKPOINTS = 4
 
+/**
+ * Share of {@link MAX_CACHE_BREAKPOINTS} the composed system prompt may spend.
+ *
+ * Two is all it can use: the only STABLE boundaries are the end of role+skills and the end
+ * of the packages block. The trailing context block is volatile and deliberately never
+ * marked, so the remaining two breakpoints always stay available to the message prefix.
+ */
+export const MAX_SYSTEM_BREAKPOINTS = 2
+
+/** Cache lifetime used when neither the call nor the service asks for another. */
+export const DEFAULT_CACHE_TTL: CacheTtl = '5m'
+
+/**
+ * Smallest prefix worth marking as cacheable, in tokens. Providers silently refuse to
+ * create an entry below their own threshold (1024 tokens on most Claude models, 512 on
+ * the newest, 4096 on a few older ones — it is NOT monotonic across generations), so a
+ * marker on a short prefix costs nothing but wastes a breakpoint and produces a
+ * "caching enabled" log for an entry that was never written. Override per model with
+ * `ModelConfig.cacheMinTokens`.
+ */
+export const MIN_CACHEABLE_TOKENS = 1024
+
+/**
+ * Characters per token used to size a prefix against {@link MIN_CACHEABLE_TOKENS}. A rough
+ * average for English prose and TypeScript; only ever used to decide whether marking is
+ * worth a breakpoint, never for billing or budgeting.
+ */
+export const CHARS_PER_TOKEN = 4
+
 /**
  * Appended to the prompt of `invoke`/`request` when no message already mentions JSON.
  * Some providers refuse or ignore JSON modes unless the word appears in the prompt;
@@ -85,5 +123,5 @@ export const EFFORT_TABLE: Record<ExecutionEffort, ModelConfigPatch> = {
  * without excluding it every `derive`/`escalate`/`withPurpose` would nest another copy.
  */
 export const COLLABORATOR_KEYS: string[] = [
-  'state', 'models', 'model', 'temperatureFactory', 'outputErrors',
+  'state', 'models', 'model', 'temperatureFactory', 'outputErrors', 'files', 'prompts',
 ]