@owlmeans/llm 0.1.14 → 0.1.16-rc.0

package/src/plugins/anthropic.ts

@@ -1,9 +1,12 @@
 import { ChatAnthropic } from '@langchain/anthropic'
 import { BadRequestError } from '@anthropic-ai/sdk'
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
-import { ModelProvider, StructuredMode } from '@owlmeans/llm-common'
+import type { MessageContent, MessageFieldWithRole } from '@langchain/core/messages'
+import { ModelProvider, PromptBlock, StructuredMode } from '@owlmeans/llm-common'
+import type { CacheTtl } from '@owlmeans/llm-common'
 import type { LlmPlugin } from './types.js'
-import { MAX_CACHE_BREAKPOINTS } from '../consts.js'
+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. */
@@ -11,6 +14,64 @@ const CACHEABLE_PREFIX = 'claude-'
 
 export const ANTHROPIC_FAMILY = 'anthropic'
 
+type ContentBlock = Record<string, unknown>
+
+const supportsCache = (model: BaseChatModel): boolean =>
+  (model as ChatAnthropic).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: BaseChatModel): number =>
+  (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: CacheTtl): ContentBlock =>
+  ttl === '1h' ? { type: 'ephemeral', ttl: '1h' } : { type: 'ephemeral' }
+
+const contentLength = (content: MessageContent | undefined): number => {
+  if (typeof content === 'string') {
+    return content.length
+  }
+  if (Array.isArray(content)) {
+    return content.reduce<number>((sum, part) => {
+      const text = (part as unknown as { text?: unknown }).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: MessageFieldWithRole, mark: ContentBlock): boolean => {
+  if (typeof msg.content === 'string') {
+    msg.content = [{ type: 'text', text: msg.content, cache_control: mark }] as unknown as MessageContent
+    return true
+  }
+  if (Array.isArray(msg.content) && msg.content.length > 0) {
+    const blocks = [...msg.content] as ContentBlock[]
+    const last = blocks[blocks.length - 1]
+    if (last.cache_control != null) {
+      return true
+    }
+    blocks[blocks.length - 1] = { ...last, cache_control: mark }
+    msg.content = blocks as unknown as MessageContent
+    return true
+  }
+
+  return false
+}
+
 export const anthropicPlugin: LlmPlugin = {
   type: ModelProvider.Anthropic,
 
@@ -70,28 +131,106 @@ export const anthropicPlugin: LlmPlugin = {
   },
 
   /**
-   * 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 as ChatAnthropic).modelName?.startsWith(CACHEABLE_PREFIX)) 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
+  patchSystem: (blocks, { model, cacheMax, ttl }) => {
+    const content: ContentBlock[] = blocks.map(block => ({ type: 'text', text: block.text }))
+    if (!supportsCache(model) || cacheMax < 1) {
+      return { content: content as unknown as MessageContent, breakpoints: 0 }
     }
-    return true
+
+    const lastOf = (...wanted: PromptBlock[]): number =>
+      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 as unknown as MessageContent, 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
+    }
+    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 as { status?: unknown })?.status === 400
+    ? e as Error
+    : null,
 }

package/src/plugins/openai.ts

@@ -33,6 +33,17 @@ export const openAiFamily = {
     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: unknown): Error | null =>
+    (e as { status?: unknown })?.status === 400 ? e as Error : null,
+
   refine: ({ base, attempt, temperature, maxOutputCap }: LlmRefineParams): BaseChatModel => {
     const model = base as ChatOpenAI
     const currentTemperature = temperature ?? model.temperature ?? 0
@@ -75,10 +86,22 @@ export const openAiPlugin: LlmPlugin = {
   structuredMode: (config: ModelConfig): StructuredMode =>
     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({
@@ -89,6 +112,7 @@ export const openAiPlugin: LlmPlugin = {
         useResponsesApi: true,
         metadata: { config },
         callbacks,
+        modelKwargs,
         ...configuration,
       })
     }
@@ -102,6 +126,7 @@ export const openAiPlugin: LlmPlugin = {
       maxRetries: 5,
       metadata: { config },
       callbacks,
+      modelKwargs,
       ...configuration,
     })
   },

package/src/plugins/types.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 {
@@ -32,7 +32,32 @@ 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
 }
 
 /**
@@ -78,12 +103,24 @@ export interface LlmPlugin {
   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/src/prompt/index.ts

@@ -0,0 +1,5 @@
+
+export type * from './types.js'
+export * from './render.js'
+export * from './plugins.js'
+export * from './service.js'

package/src/prompt/plugins.ts

@@ -0,0 +1,69 @@
+import { PromptBlock } from '@owlmeans/llm-common'
+import type { SkillDefinition } from '@owlmeans/llm-common'
+import { joinChunks, renderSkill, sortSkills } from './render.js'
+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 const rolePlugin: LlmPromptPlugin = {
+  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: LlmPromptPlugin = {
+  alias: 'skills',
+  order: 10,
+  compose: ctx => {
+    const declared = ctx.resolve(ctx.input.skills ?? [])
+    const merged = new Map<string, SkillDefinition>()
+    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: LlmPromptPlugin = {
+  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: readonly LlmPromptPlugin[] = [
+  rolePlugin, skillsPlugin, contextPlugin,
+] as const

package/src/prompt/render.ts

@@ -0,0 +1,48 @@
+import { DEFAULT_SKILL_ORDER } from '@owlmeans/llm-common'
+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 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: string, b: string): number => a < b ? -1 : a > b ? 1 : 0
+
+/** Deterministic skill order: declared weight first, alias as the tiebreaker. */
+export const sortSkills = (skills: readonly SkillDefinition[]): SkillDefinition[] =>
+  [...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: SkillDefinition): string =>
+  `## ${skill.title ?? skill.alias}\n\n${skill.body.trim()}`
+
+/** Join rendered chunks into one block, dropping empties. */
+export const joinChunks = (parts: readonly string[]): string =>
+  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: string): string => {
+  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)
+}

package/src/prompt/service.ts

@@ -0,0 +1,194 @@
+import { createService } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { PROMPT_BLOCK_ORDER, PromptBlock } from '@owlmeans/llm-common'
+import type { SkillDefinition } from '@owlmeans/llm-common'
+import {
+  DEFAULT_CACHE_TTL, MAX_CACHE_BREAKPOINTS, MAX_SYSTEM_BREAKPOINTS, PROMPT_SERVICE,
+} from '../consts.js'
+import type { LlmSystemBlock } from '../plugins/types.js'
+import { BUILT_IN_PROMPT_PLUGINS } from './plugins.js'
+import { CHUNK_SEPARATOR, compareAlias, joinChunks } from './render.js'
+import type {
+  LlmPromptPlugin, PromptContext, PromptResult, PromptService, PromptServiceOptions,
+  WithPromptService,
+} from './types.js'
+
+/** Sort weight of a plugin that declares none — between the built-in skills and context. */
+const DEFAULT_PLUGIN_ORDER = 50
+
+/** 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 const promptServiceApi = (
+  options: PromptServiceOptions,
+  self: () => PromptService,
+): PromptServiceApi => {
+  const registry = new Map<string, SkillDefinition>()
+  /** Registration index per plugin alias — the stable tiebreaker for equal `order`. */
+  const seats = new Map<string, { plugin: LlmPromptPlugin; index: number }>()
+  let seq = 0
+
+  const seat = (plugin: LlmPromptPlugin): void => {
+    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 = (): LlmPromptPlugin[] =>
+    [...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: PromptServiceApi = {
+
+    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<string>()
+      const out: SkillDefinition[] = []
+      const walk = (alias: string): void => {
+        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): Promise<PromptResult> => {
+      const sections = new Map<PromptBlock, string[]>()
+      const ctx: PromptContext = {
+        ...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: LlmSystemBlock[] = []
+      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: PromptServiceOptions = {},
+  alias: string = PROMPT_SERVICE,
+): PromptService => {
+  const service: PromptService = createService<PromptService>(
+    alias, promptServiceApi(options, () => service) as PromptService
+  )
+
+  return service
+}
+
+export const appendPromptService = <C extends BasicConfig, T extends BasicContext<C>>(
+  ctx: T,
+  options: PromptServiceOptions = {},
+  alias: string = PROMPT_SERVICE,
+): T & WithPromptService => {
+  const context = ctx as T & WithPromptService
+
+  context.registerService(makePromptService(options, alias))
+
+  context.prompts = () => context.service<PromptService>(alias)
+
+  return context
+}