@owlmeans/llm 0.1.15 → 0.1.16

package/src/utils/prompt.ts

@@ -23,6 +23,39 @@ const appendDirective = (msgs: MessageFieldWithRole[], text: string): void => {
   }
 }
 
+/**
+ * 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: MessageFieldWithRole[]): void => {
+  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 as Record<string, unknown>
+        return rest
+      }
+      return part
+    })
+    if (found) {
+      msg.content = blocks as unknown as typeof msg.content
+    }
+  }
+}
+
 /**
  * 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/tests/execution.spec.ts

@@ -180,6 +180,48 @@ describe('@owlmeans/llm — snapshot and restore', () => {
   })
 })
 
+describe('@owlmeans/llm — prompt policy accumulation', () => {
+  const withPrompt = () => service.root({
+    models: makeService(),
+    policy: { effort: DEFAULT_EFFORT },
+    purpose: { type: 'spec' },
+    prompt: { role: 'project role', skills: ['base'] },
+  })
+
+  // Skills accumulate as work narrows — that is how a helper ends up knowing everything
+  // the project, the task and its own role declared, without any of them repeating it.
+  test('skills accumulate down the chain while the deepest role wins', () => {
+    const task = service.forTask(withPrompt(), { prompt: { skills: ['task'] } })
+    expect(task.prompt?.skills).toEqual(['base', 'task'])
+    expect(task.prompt?.role).toBe('project role')
+
+    const helper = service.forHelper(task, {
+      role: Role.Analyst, prompt: { role: 'helper role', skills: ['helper'] },
+    })
+    expect(helper.prompt?.skills).toEqual(['base', 'task', 'helper'])
+    expect(helper.prompt?.role).toBe('helper role')
+  })
+
+  // A skill declared twice must not render twice, or the composed prefix differs from the
+  // one a single declaration would have produced.
+  test('a repeated skill is unioned, not duplicated', () => {
+    const task = service.forTask(withPrompt(), { prompt: { skills: ['base', 'task'] } })
+    expect(task.prompt?.skills).toEqual(['base', 'task'])
+  })
+
+  test('levels that declare nothing inherit the policy untouched', () => {
+    const helper = service.forHelper(service.forTask(withPrompt(), {}), { role: Role.Analyst })
+    expect(helper.prompt).toEqual({ role: 'project role', skills: ['base'] })
+  })
+
+  // It is part of ExecutionState, so a resumed run rebuilds the same system prompt.
+  test('the policy survives a snapshot/restore round trip', () => {
+    const helper = service.forHelper(withPrompt(), { role: Role.Analyst })
+    const restored = service.restore(service.snapshot(helper), { models: makeService() })
+    expect(restored.prompt).toEqual({ role: 'project role', skills: ['base'] })
+  })
+})
+
 describe('@owlmeans/llm — resilience plugin seam', () => {
   test('checkpoint is a no-op until a plugin is registered', async () => {
     await expect(service.checkpoint(root, 'key')).resolves.toBeUndefined()

package/tests/plugins.spec.ts

@@ -2,13 +2,14 @@ import { describe, expect, test } from 'bun:test'
 import { ChatAnthropic } from '@langchain/anthropic'
 import { ChatOpenAI } from '@langchain/openai'
 import { BadRequestError } from '@anthropic-ai/sdk'
-import { ModelProvider, StructuredMode } from '@owlmeans/llm-common'
+import { ModelProvider, PromptBlock, StructuredMode } from '@owlmeans/llm-common'
 import {
   anthropicPlugin, compatiblePlugin, makeLlmService, openAiPlugin, pluginFor, pluginOf,
   registerLlmPlugin, resolvePlugin,
 } from '@owlmeans/llm'
 import type { LlmPlugin, ModelConfig } from '@owlmeans/llm'
 import { offlineConfigs, Role } from './context.js'
+import { stripCacheMarkers } from '../src/utils/prompt.js'
 
 const build = (plugin: LlmPlugin, config: Partial<ModelConfig> = {}) =>
   plugin.build({
@@ -164,26 +165,251 @@ describe('@owlmeans/llm — retry escalation behaviour', () => {
   })
 })
 
-describe('@owlmeans/llm — prompt caching', () => {
-  test('anthropic marks up to the requested number of leading messages', () => {
+describe('@owlmeans/llm — message prompt caching', () => {
+  /** `cacheMinTokens: 1` puts the minimum at 4 characters so fixtures stay readable. */
+  const cheap = () => build(anthropicPlugin, { model: 'claude-haiku-4-5-20251001', cacheMinTokens: 1 })
+
+  // The budget is four breakpoints for the WHOLE request, and the composed system prompt
+  // has first claim on it — so the messages get one marker at the end of their stable
+  // prefix, not one marker each.
+  test('anthropic places a single breakpoint at the end of the stable prefix', () => {
+    const msgs = [
+      { role: 'system' as const, content: 'aaaa' },
+      { role: 'user' as const, content: 'bbbb' },
+      { role: 'user' as const, content: 'cccc' },
+    ]
+    expect(anthropicPlugin.patchCache?.(msgs, { model: cheap(), useCache: true, cacheMax: 2 })).toBe(true)
+    expect(msgs[0]!.content).toBe('aaaa')
+    expect(msgs[1]!.content).toEqual([{ type: 'text', text: 'bbbb', cache_control: { type: 'ephemeral' } }])
+    expect(msgs[2]!.content).toBe('cccc')
+  })
+
+  // The last message is the per-call payload (and `ensureJsonMention` / `applyNoThink`
+  // append to it) — caching it would write a fresh entry every call and read none.
+  test('the final message is never part of the cached prefix', () => {
+    const msgs = [
+      { role: 'system' as const, content: 'aaaa' },
+      { role: 'user' as const, content: 'bbbb' },
+    ]
+    expect(anthropicPlugin.patchCache?.(msgs, { model: cheap(), useCache: true, cacheMax: 9 })).toBe(true)
+    expect(msgs[0]!.content).toEqual([{ type: 'text', text: 'aaaa', cache_control: { type: 'ephemeral' } }])
+    expect(msgs[1]!.content).toBe('bbbb')
+
+    const single = [{ role: 'user' as const, content: 'aaaa' }]
+    expect(anthropicPlugin.patchCache?.(single, { model: cheap(), useCache: true, cacheMax: 4 })).toBe(false)
+    expect(single[0]!.content).toBe('aaaa')
+  })
+
+  test('a marker is appended to block content rather than replacing it, and is idempotent', () => {
+    const msgs = [
+      { role: 'system' as const, content: [{ type: 'text', text: 'aa' }, { type: 'text', text: 'bb' }] },
+      { role: 'user' as const, content: 'cccc' },
+    ]
+    expect(anthropicPlugin.patchCache?.(msgs, { model: cheap(), useCache: true, cacheMax: 1 })).toBe(true)
+    expect(msgs[0]!.content).toEqual([
+      { type: 'text', text: 'aa' },
+      { type: 'text', text: 'bb', cache_control: { type: 'ephemeral' } },
+    ])
+
+    const before = JSON.stringify(msgs[0]!.content)
+    expect(anthropicPlugin.patchCache?.(msgs, { model: cheap(), useCache: true, cacheMax: 1 })).toBe(true)
+    expect(JSON.stringify(msgs[0]!.content)).toBe(before)
+  })
+
+  // A prefix under the provider's own minimum is silently never cached, so a marker there
+  // buys nothing and costs one of the four breakpoints.
+  test('a prefix below the cacheable minimum is left unmarked', () => {
     const model = build(anthropicPlugin, { model: 'claude-haiku-4-5-20251001' })
     const msgs = [
-      { role: 'system' as const, content: 'a' },
-      { role: 'user' as const, content: 'b' },
-      { role: 'user' as const, content: 'c' },
+      { role: 'system' as const, content: 'short' },
+      { role: 'user' as const, content: 'also short' },
     ]
-    expect(anthropicPlugin.patchCache?.(msgs, { model, useCache: true, cacheMax: 2 })).toBe(true)
-    expect(msgs[0]!.content).toEqual([{ type: 'text', text: 'a', cache_control: { type: 'ephemeral' } }])
-    expect(msgs[1]!.content).toEqual([{ type: 'text', text: 'b', cache_control: { type: 'ephemeral' } }])
-    expect(msgs[2]!.content).toBe('c')
+    expect(anthropicPlugin.patchCache?.(msgs, { model, useCache: true, cacheMax: 4 })).toBe(false)
+    expect(msgs[0]!.content).toBe('short')
+  })
+
+  test('the message budget yields to whatever the system prompt already spent', () => {
+    const msgs = [
+      { role: 'system' as const, content: 'aaaa' },
+      { role: 'user' as const, content: 'bbbb' },
+    ]
+    expect(anthropicPlugin.patchCache?.(
+      msgs, { model: cheap(), useCache: true, cacheMax: 4, reserved: 4 }
+    )).toBe(false)
+    expect(msgs[0]!.content).toBe('aaaa')
   })
 
   test('caching is a no-op when not requested, and for providers without it', () => {
-    const model = build(anthropicPlugin, { model: 'claude-haiku-4-5-20251001' })
-    const msgs = [{ role: 'user' as const, content: 'a' }]
-    expect(anthropicPlugin.patchCache?.(msgs, { model, useCache: false, cacheMax: 4 })).toBe(false)
-    expect(msgs[0]!.content).toBe('a')
+    const msgs = [{ role: 'user' as const, content: 'aaaa' }, { role: 'user' as const, content: 'bbbb' }]
+    expect(anthropicPlugin.patchCache?.(msgs, { model: cheap(), useCache: false, cacheMax: 4 })).toBe(false)
+    expect(msgs[0]!.content).toBe('aaaa')
     expect(openAiPlugin.patchCache).toBeUndefined()
+    expect(openAiPlugin.patchSystem).toBeUndefined()
+  })
+})
+
+describe('@owlmeans/llm — system prompt caching', () => {
+  const model = () => build(anthropicPlugin, { model: 'claude-haiku-4-5-20251001', cacheMinTokens: 1 })
+  const blocks = (...pairs: Array<[PromptBlock, string]>) =>
+    pairs.map(([block, text]) => ({ block, text }))
+
+  const marks = (content: unknown): boolean[] =>
+    (content as Array<Record<string, unknown>>).map(part => part.cache_control != null)
+
+  // Role + skills is the region every call of this role shares; packages vary with the
+  // request. Two boundaries, so a changing package block can never invalidate the skills.
+  test('breakpoints land on the stability boundaries, not on every block', () => {
+    const render = anthropicPlugin.patchSystem?.(
+      blocks(
+        [PromptBlock.Role, 'role text'],
+        [PromptBlock.Skills, 'skill text'],
+        [PromptBlock.Packages, 'package text'],
+      ),
+      { model: model(), cacheMax: 3, ttl: '5m' },
+    )
+    expect(render?.breakpoints).toBe(2)
+    expect(marks(render?.content)).toEqual([false, true, true])
+  })
+
+  // "Fully cached by default" also has to hold for a caller that has not migrated and
+  // still hands over a single system message of its own.
+  test('a lone context block is still cached', () => {
+    const render = anthropicPlugin.patchSystem?.(
+      blocks([PromptBlock.Context, 'legacy system message']),
+      { model: model(), cacheMax: 3, ttl: '5m' },
+    )
+    expect(render?.breakpoints).toBe(1)
+    expect(marks(render?.content)).toEqual([true])
+  })
+
+  test('marking stops at the budget, earliest boundary first', () => {
+    const render = anthropicPlugin.patchSystem?.(
+      blocks(
+        [PromptBlock.Skills, 'skill text'],
+        [PromptBlock.Packages, 'package text'],
+        [PromptBlock.Context, 'context text'],
+      ),
+      { model: model(), cacheMax: 1, ttl: '5m' },
+    )
+    expect(render?.breakpoints).toBe(1)
+    expect(marks(render?.content)).toEqual([true, false, false])
+  })
+
+  // An explicit `"ttl": "5m"` is different BYTES from no ttl at all, and a prefix cached
+  // one way would not match the other.
+  test('the default ttl is omitted from the marker, and 1h is spelled out', () => {
+    const short = anthropicPlugin.patchSystem?.(
+      blocks([PromptBlock.Skills, 'skill text']), { model: model(), cacheMax: 3, ttl: '5m' }
+    )
+    expect((short?.content as Array<Record<string, unknown>>)[0]!.cache_control)
+      .toEqual({ type: 'ephemeral' })
+
+    const long = anthropicPlugin.patchSystem?.(
+      blocks([PromptBlock.Skills, 'skill text']), { model: model(), cacheMax: 3, ttl: '1h' }
+    )
+    expect((long?.content as Array<Record<string, unknown>>)[0]!.cache_control)
+      .toEqual({ type: 'ephemeral', ttl: '1h' })
+  })
+
+  // A trailing context block changes every call. Marking it would pay a cache WRITE per
+  // call and never read one back — a breakpoint spent to buy nothing.
+  test('a trailing context block is never marked when stable blocks precede it', () => {
+    const render = anthropicPlugin.patchSystem?.(
+      blocks(
+        [PromptBlock.Role, 'role text'],
+        [PromptBlock.Skills, 'skill text'],
+        [PromptBlock.Context, 'per-call text'],
+      ),
+      { model: model(), cacheMax: 2, ttl: '5m' },
+    )
+    expect(render?.breakpoints).toBe(1)
+    expect(marks(render?.content)).toEqual([false, true, false])
+  })
+
+  test('the packages boundary is still marked with context trailing behind it', () => {
+    const render = anthropicPlugin.patchSystem?.(
+      blocks(
+        [PromptBlock.Role, 'role text'],
+        [PromptBlock.Skills, 'skill text'],
+        [PromptBlock.Packages, 'package text'],
+        [PromptBlock.Context, 'per-call text'],
+      ),
+      { model: model(), cacheMax: 2, ttl: '5m' },
+    )
+    expect(render?.breakpoints).toBe(2)
+    expect(marks(render?.content)).toEqual([false, true, true, false])
+  })
+
+  test('a non-claude model still renders the blocks, just without markers', () => {
+    const render = anthropicPlugin.patchSystem?.(
+      blocks([PromptBlock.Role, 'role text']),
+      { model: build(anthropicPlugin, { model: 'some-other-model' }), cacheMax: 3, ttl: '5m' },
+    )
+    expect(render?.breakpoints).toBe(0)
+    expect(render?.content).toEqual([{ type: 'text', text: 'role text' }])
+  })
+})
+
+describe('@owlmeans/llm — the four-breakpoint request budget', () => {
+  const cheap = () => build(anthropicPlugin, { model: 'claude-haiku-4-5-20251001', cacheMinTokens: 1 })
+
+  const markers = (msgs: Array<{ content: unknown }>): number =>
+    msgs.reduce((sum, msg) => sum + (Array.isArray(msg.content)
+      ? (msg.content as Array<Record<string, unknown>>).filter(b => b.cache_control != null).length
+      : 0), 0)
+
+  // The live failure: a caller that carries its message array across calls hands back
+  // messages this pipeline already marked. They accumulate until Anthropic rejects the
+  // request with `400 A maximum of 4 blocks with cache_control may be provided. Found 5.`
+  test('markers left over from a previous call are cleared before new ones are placed', () => {
+    const msgs = [
+      { role: 'system' as const, content: 'aaaa' },
+      { role: 'user' as const, content: 'bbbb' },
+      { role: 'user' as const, content: 'cccc' },
+    ]
+    // Call one marks the stable prefix.
+    anthropicPlugin.patchCache?.(msgs, { model: cheap(), useCache: true, cacheMax: 2 })
+    expect(markers(msgs)).toBe(1)
+
+    // Call two: the caller appends a turn and re-sends the SAME objects.
+    msgs.push({ role: 'user' as const, content: 'dddd' })
+    stripCacheMarkers(msgs)
+    expect(markers(msgs)).toBe(0)
+
+    anthropicPlugin.patchCache?.(msgs, { model: cheap(), useCache: true, cacheMax: 3 })
+    expect(markers(msgs)).toBe(1)
+  })
+
+  test('the system prompt plus the message prefix never exceed the provider limit', () => {
+    // Worst case: every stability boundary distinct, so the system claims its full share.
+    const system = anthropicPlugin.patchSystem?.(
+      [
+        { block: PromptBlock.Role, text: 'role text' },
+        { block: PromptBlock.Skills, text: 'skill text' },
+        { block: PromptBlock.Packages, text: 'package text' },
+        { block: PromptBlock.Context, text: 'context text' },
+      ],
+      { model: cheap(), cacheMax: 3, ttl: '5m' },
+    )
+    const reserved = system?.breakpoints ?? 0
+    expect(reserved).toBeLessThanOrEqual(3)
+
+    const msgs = [
+      { role: 'system' as const, content: system?.content as never },
+      { role: 'user' as const, content: 'bbbb' },
+      { role: 'user' as const, content: 'cccc' },
+    ]
+    anthropicPlugin.patchCache?.(msgs, { model: cheap(), useCache: true, cacheMax: 4, reserved })
+    expect(markers(msgs)).toBeLessThanOrEqual(4)
+  })
+
+  test('stripping leaves the rest of a content block untouched', () => {
+    const msgs = [{
+      role: 'user' as const,
+      content: [{ type: 'text', text: 'keep me', cache_control: { type: 'ephemeral' } }] as never,
+    }]
+    stripCacheMarkers(msgs)
+    expect(msgs[0]!.content).toEqual([{ type: 'text', text: 'keep me' }] as never)
   })
 })
 
@@ -193,6 +419,22 @@ describe('@owlmeans/llm — fatal error classification', () => {
     expect(anthropicPlugin.isFatal?.(bad)).toBe(bad)
     expect(anthropicPlugin.isFatal?.(new Error('transient'))).toBeNull()
   })
+
+  // `@langchain/anthropic` bundles its OWN nested copy of `@anthropic-ai/sdk`, so the
+  // error it throws is an instance of a different class than the one imported here and
+  // `instanceof` silently misses. That turned every fatal 400 into eight full retries.
+  test('a 400 from a foreign SDK copy is still fatal', () => {
+    const foreign = Object.assign(new Error('400 too many cache_control blocks'), { status: 400 })
+    expect(anthropicPlugin.isFatal?.(foreign)).toBe(foreign)
+    expect(openAiPlugin.isFatal?.(foreign)).toBe(foreign)
+    expect(compatiblePlugin.isFatal?.(foreign)).toBe(foreign)
+  })
+
+  test('a retryable status is not treated as fatal', () => {
+    const overloaded = Object.assign(new Error('529'), { status: 529 })
+    expect(anthropicPlugin.isFatal?.(overloaded)).toBeNull()
+    expect(openAiPlugin.isFatal?.(overloaded)).toBeNull()
+  })
 })
 
 describe('@owlmeans/llm — service', () => {
@@ -203,6 +445,29 @@ describe('@owlmeans/llm — service', () => {
     expect(service.getModel(Role.Analyst, {}, true)).not.toBe(first)
   })
 
+  // The knob an application sets where it composes its context: one place to bound how
+  // long the whole deployment waits on a silent provider.
+  test('a service-wide idle deadline reaches every model it builds', () => {
+    const service = makeLlmService(
+      { models: offlineConfigs, streamTimeout: 90_000 }, 'spec-llm-timeout'
+    )
+    const config = (service.getModel(Role.Analyst) as unknown as {
+      metadata: { config: ModelConfig }
+    }).metadata.config
+    expect(config.streamTimeout).toBe(90_000)
+  })
+
+  // A preset that names its own deadline knows something specific about that model.
+  test('a model config keeps its own deadline over the service default', () => {
+    const configs = (): ModelConfig[] =>
+      offlineConfigs().map(c => c.alias === Role.Analyst ? { ...c, streamTimeout: 12_000 } : c)
+    const service = makeLlmService({ models: configs, streamTimeout: 90_000 }, 'spec-llm-timeout-2')
+    const config = (service.getModel(Role.Analyst) as unknown as {
+      metadata: { config: ModelConfig }
+    }).metadata.config
+    expect(config.streamTimeout).toBe(12_000)
+  })
+
   test('an override participates in the cache key', () => {
     const service = makeLlmService({ models: offlineConfigs }, 'spec-llm-override')
     const plain = service.getModel(Role.Analyst)

package/tests/prompt.spec.ts

@@ -0,0 +1,194 @@
+import { describe, expect, test } from 'bun:test'
+import { PromptBlock } from '@owlmeans/llm-common'
+import type { SkillDefinition } from '@owlmeans/llm-common'
+import { anthropicPlugin, makePromptService } from '@owlmeans/llm'
+import type { LlmPromptPlugin, ModelConfig, PromptService } from '@owlmeans/llm'
+
+/** `cacheMinTokens: 1` puts the cacheable minimum at 4 characters so fixtures stay short. */
+const model = anthropicPlugin.build({
+  alias: 'spec',
+  secret: 'sk-test',
+  callbacks: [],
+  config: { alias: 'spec', model: 'claude-haiku-4-5-20251001', cacheMinTokens: 1 } as ModelConfig,
+})
+
+let seq = 0
+const service = (skills: SkillDefinition[] = [], plugins: LlmPromptPlugin[] = []): PromptService =>
+  makePromptService({ skills, plugins }, `spec-prompt-${seq++}`)
+
+const compose = (svc: PromptService, input: Parameters<PromptService['compose']>[0] = {}) =>
+  svc.compose(input, [{ role: 'user', content: 'the task' }], { model, provider: anthropicPlugin })
+
+const skill = (alias: string, body: string, extra: Partial<SkillDefinition> = {}): SkillDefinition =>
+  ({ alias, body, ...extra })
+
+describe('@owlmeans/llm — skill registry', () => {
+  test('resolve follows requires depth-first and de-duplicates', () => {
+    const svc = service([
+      skill('a', 'A', { requires: ['b', 'c'] }),
+      skill('b', 'B', { requires: ['c'] }),
+      skill('c', 'C'),
+    ])
+    expect(svc.resolve(['a']).map(s => s.alias)).toEqual(['c', 'b', 'a'])
+    expect(svc.resolve(['a', 'b', 'c']).map(s => s.alias)).toEqual(['c', 'b', 'a'])
+  })
+
+  // A catalogue is assembled from several packages; a missing optional entry should
+  // degrade the prompt, not break the call.
+  test('an unknown alias is skipped rather than thrown', () => {
+    const svc = service([skill('known', 'K')])
+    expect(svc.resolve(['known', 'missing']).map(s => s.alias)).toEqual(['known'])
+    expect(svc.has('missing')).toBe(false)
+  })
+
+  test('a cyclic requires graph terminates', () => {
+    const svc = service([skill('a', 'A', { requires: ['b'] }), skill('b', 'B', { requires: ['a'] })])
+    expect(svc.resolve(['a']).map(s => s.alias).sort()).toEqual(['a', 'b'])
+  })
+})
+
+describe('@owlmeans/llm — prompt composition', () => {
+  test('blocks are emitted in stability order regardless of who contributed them', async () => {
+    const late: LlmPromptPlugin = {
+      alias: 'late', order: 99, compose: ctx => ctx.add(PromptBlock.Packages, 'package text'),
+    }
+    const result = await compose(
+      service([skill('s', 'skill text')], [late]),
+      { role: 'role text', skills: ['s'], context: ['context text'] },
+    )
+    expect(result.blocks.map(block => block.block))
+      .toEqual([PromptBlock.Role, PromptBlock.Skills, PromptBlock.Packages, PromptBlock.Context])
+  })
+
+  // The whole design rests on this: a prompt cache is a byte-exact prefix match, so two
+  // calls that declare the same thing must render the same thing.
+  test('the same declaration composes to identical bytes', async () => {
+    const svc = service([skill('a', 'A'), skill('b', 'B')])
+    const first = await compose(svc, { role: 'R', skills: ['a', 'b'] })
+    const second = await compose(svc, { role: 'R', skills: ['b', 'a'] })
+    expect(JSON.stringify(second.system)).toBe(JSON.stringify(first.system))
+  })
+
+  test('skill order comes from the definitions, not from registration or request order', async () => {
+    const forward = service([skill('z', 'Z', { order: 1 }), skill('a', 'A', { order: 2 })])
+    const backward = service([skill('a', 'A', { order: 2 }), skill('z', 'Z', { order: 1 })])
+    const one = await compose(forward, { skills: ['a', 'z'] })
+    const two = await compose(backward, { skills: ['z', 'a'] })
+    expect(one.blocks[0]!.text).toBe(two.blocks[0]!.text)
+    expect(one.blocks[0]!.text.indexOf('## z')).toBeLessThan(one.blocks[0]!.text.indexOf('## a'))
+  })
+
+  // The reason packages get their own block: whatever a request happens to mention must
+  // not shift a single byte of the region every call shares.
+  test('a changing packages block leaves the cached region byte-identical', async () => {
+    const inject = (text: string): LlmPromptPlugin =>
+      ({ alias: 'pkg', inspect: ctx => ctx.add(PromptBlock.Packages, text) })
+    const base = { role: 'R', skills: ['a'] }
+    const one = await compose(service([skill('a', 'A')], [inject('first')]), base)
+    const two = await compose(service([skill('a', 'A')], [inject('second')]), base)
+
+    const stable = (blocks: typeof one.blocks) =>
+      blocks.filter(b => b.block !== PromptBlock.Packages).map(b => b.text).join('|')
+    expect(stable(two.blocks)).toBe(stable(one.blocks))
+    expect(two.blocks.find(b => b.block === PromptBlock.Packages)?.text).toBe('second')
+  })
+
+  test('per-call skills render into the volatile context block, not the cached one', async () => {
+    const result = await compose(
+      service([skill('static', 'S'), skill('percall', 'P')]),
+      { skills: ['static'], callSkills: ['percall'] },
+    )
+    expect(result.blocks.find(b => b.block === PromptBlock.Skills)?.text).toContain('## static')
+    expect(result.blocks.find(b => b.block === PromptBlock.Skills)?.text).not.toContain('## percall')
+    expect(result.blocks.find(b => b.block === PromptBlock.Context)?.text).toContain('## percall')
+  })
+
+  test('an inline skill overrides the registered one of the same alias', async () => {
+    const result = await compose(
+      service([skill('a', 'registered body')]),
+      { skills: ['a'], inline: [skill('a', 'inline body')] },
+    )
+    expect(result.blocks[0]!.text).toContain('inline body')
+    expect(result.blocks[0]!.text).not.toContain('registered body')
+  })
+
+  test('registering the same plugin alias twice replaces it instead of emitting twice', async () => {
+    const svc = service()
+    const plugin: LlmPromptPlugin = {
+      alias: 'dup', compose: ctx => ctx.add(PromptBlock.Skills, 'once'),
+    }
+    svc.use(plugin)
+    svc.use(plugin)
+    const result = await compose(svc)
+    expect(result.blocks[0]!.text).toBe('once')
+  })
+
+  // Detection plugins need every static contribution already in place.
+  test('every compose pass runs before the first inspect pass', async () => {
+    const seen: string[] = []
+    const plugins: LlmPromptPlugin[] = [
+      { alias: 'x', order: 1, compose: () => { seen.push('compose:x') }, inspect: () => { seen.push('inspect:x') } },
+      { alias: 'y', order: 2, compose: () => { seen.push('compose:y') } },
+    ]
+    await compose(service([], plugins))
+    expect(seen).toEqual(['compose:x', 'compose:y', 'inspect:x'])
+  })
+
+  // Volatile parts are merged rather than emitted separately: the block carries no
+  // breakpoint, so keeping them separable buys nothing and reads worse to the model.
+  test('every volatile part lands in a single context chunk', async () => {
+    const result = await compose(
+      service([skill('a', 'A'), skill('percall', 'P')]),
+      { skills: ['a'], callSkills: ['percall'], context: ['first note', 'second note'] },
+    )
+    const context = result.blocks.filter(block => block.block === PromptBlock.Context)
+    expect(context).toHaveLength(1)
+    expect(context[0]!.text).toContain('## percall')
+    expect(context[0]!.text).toContain('first note')
+    expect(context[0]!.text).toContain('second note')
+  })
+
+  test('nothing declared composes to no system message at all', async () => {
+    const result = await compose(service())
+    expect(result.system).toBeNull()
+    expect(result.breakpoints).toBe(0)
+  })
+})
+
+describe('@owlmeans/llm — composed prompt caching', () => {
+  test('the system prompt is cached by default, and marks its boundaries', async () => {
+    const result = await compose(
+      service([skill('a', 'A')], [{ alias: 'pkg', inspect: ctx => ctx.add(PromptBlock.Packages, 'pkg') }]),
+      { role: 'R', skills: ['a'] },
+    )
+    expect(result.breakpoints).toBe(2)
+    expect(Array.isArray(result.system?.content)).toBe(true)
+  })
+
+  test('opting out yields a plain joined string and spends no breakpoints', async () => {
+    const result = await compose(service([skill('a', 'A')]), { role: 'R', skills: ['a'], cacheSystem: false })
+    expect(result.breakpoints).toBe(0)
+    expect(typeof result.system?.content).toBe('string')
+    expect(result.system?.content).toContain('## a')
+  })
+
+  test('a provider without explicit markers still gets the blocks, in order', async () => {
+    const svc = service([skill('a', 'A')])
+    const result = await svc.compose({ role: 'R', skills: ['a'] }, [], { model })
+    expect(result.breakpoints).toBe(0)
+    expect(result.system?.content).toBe('R\n\n## a\n\nA')
+  })
+
+  // Two stable boundaries at most, so the messages always keep half the request budget.
+  test('the system prompt never spends more than half the request budget', async () => {
+    const noisy: LlmPromptPlugin = {
+      alias: 'noisy',
+      compose: ctx => {
+        ctx.add(PromptBlock.Packages, 'pkg')
+        ctx.add(PromptBlock.Context, 'ctx')
+      },
+    }
+    const result = await compose(service([skill('a', 'A')], [noisy]), { role: 'R', skills: ['a'] })
+    expect(result.breakpoints).toBeLessThanOrEqual(2)
+  })
+})