@owlmeans/llm 0.1.18-rc.2 → 0.1.18-rc.21

package/src/types.ts

@@ -63,6 +63,12 @@ export interface LlmModelOptions extends LlmLogging {
   prompts?: () => PromptService
   /** File access offered to prompt plugins that resolve knowledge from disk. */
   files?: FileProviderRef
+  /**
+   * Cheap model offered to prompt plugins for a single side call while composing —
+   * normally `() => executions().utility(exec)`. Omitted, plugins that would use one
+   * fall back to whatever they can decide without a model.
+   */
+  utility?: () => BaseChatModel | undefined
 }
 
 export type ModelMessage = BaseMessage | MessageFieldWithRole
@@ -89,6 +95,27 @@ export interface LlmCallOptions {
    * should be part of the shared prefix.
    */
   skills?: string[]
+  /**
+   * How many failures of this SAME piece of work the caller has already observed — the
+   * per-call escalator starts that far up its ladder instead of at the bottom.
+   *
+   * A caller that validates the OUTPUT (a diff that must apply, a file that must not come
+   * back truncated) runs its own retry loop around whole calls, and every one of those
+   * calls used to start at attempt 0: same model, same output budget, same answer. Passing
+   * the outer attempt here advances both rungs the escalator owns — the `maxTokens`
+   * doubling and the {@link FALLBACK_AFTER_ATTEMPTS} switch to `ModelConfig.fallback` — so
+   * a repeatedly-rejected call actually reaches the stronger model.
+   *
+   * Clamped to `retries - 1`; it moves the STARTING rung only and never changes how many
+   * attempts this call makes. Unrelated to `ExecutionService.escalate`, which raises the
+   * effort tier of an execution before any model is resolved.
+   */
+  escalation?: number
+  /**
+   * Abort THIS call's retry loop for an error no retry can fix. Consulted before the
+   * globally registered resolvers and the provider plugin's `isFatal`.
+   */
+  fatal?: (e: unknown) => Error | null
 }
 
 export interface LlmAskOptions extends LlmCallOptions {
@@ -151,20 +178,63 @@ export interface TemperatureFactory {
 export interface ModelConfig {
   provider?: ModelProvider | string
   secret?: string
+  /**
+   * Which delegate transport answers this model's calls.
+   *
+   * Only meaningful for {@link ModelProvider.Delegated}: the key the application seated a
+   * transport under, so one deployment can hold many at once — one per connected agent — and a
+   * config names the one that belongs to its run.
+   */
+  delegate?: string
   alias: string
   /** Inherit every field of another alias in the same config list. */
   preset?: string
   model?: string
   temperature?: number
-  /** Initial output-token budget per request (`max_tokens`). */
+  /**
+   * Initial output-token budget per request (`max_tokens`) — what THIS deployment asks
+   * for first, not what the model can do. Clamped to {@link ModelConfig.maxOutput}.
+   */
   maxTokens?: number
   /**
    * Hard ceiling for output tokens used by the retry escalator. Each retry doubles
    * `maxTokens` toward this cap; without it the escalator uses
    * {@link DEFAULT_MAX_OUTPUT_CAP}, which exceeds many models' real per-request output
    * limit and turns retries into 400 "max_tokens exceeds model limit" errors.
+   *
+   * This is the budget the PRESET chooses; {@link ModelConfig.maxOutput} is what the
+   * provider allows. The effective ceiling is the smaller of the two, so a preset that
+   * over-declares is corrected at refine time rather than at the provider.
    */
   maxTokensCap?: number
+  /**
+   * Total context window the model accepts — input plus output. Informational: it is
+   * never sent to the provider and the runtime cannot enforce it (the input size is not
+   * known at config time). It documents the model and lets the preset test catch a
+   * `maxOutput` that could not possibly fit.
+   */
+  contextWindow?: number
+  /**
+   * What the PROVIDER accepts as output in a single request. Unlike `maxTokens` and
+   * `maxTokensCap` — both deployment choices — this is a property of the model behind
+   * this alias, and for an aggregated model it is the limit of the `inferenceProvider`
+   * actually pinned here, which is often well below what the model can do elsewhere.
+   *
+   * Hard ceiling: `maxTokens` is clamped to it at build time and the escalator's cap is
+   * `min(maxTokensCap, maxOutput)`.
+   *
+   * A `fallback` that changes `model` MUST redeclare this (and `contextWindow`), because
+   * the fallback config inherits every field the patch does not name — otherwise the
+   * escalator would size the fallback by the primary's capability.
+   */
+  maxOutput?: number
+  /**
+   * The context window is SHARED between input and output rather than being an input
+   * allowance with a separate output limit (MiniMax M2.x, gpt-oss). Nothing enforces it
+   * at runtime; it marks the entry so `maxOutput` is read as "spends the same budget the
+   * prompt spends" and keeps presets honest about leaving room for input.
+   */
+  combinedWindow?: boolean
   topP?: number
   baseUrl?: string
   organization?: string

package/src/utils/config.ts

@@ -1,5 +1,5 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
-import { MODEL_STREAM_TIMEOUT_MS } from '../consts.js'
+import { DEFAULT_MAX_OUTPUT_CAP, MODEL_STREAM_TIMEOUT_MS } from '../consts.js'
 import type { ModelConfig } from '../types.js'
 
 /**
@@ -17,3 +17,25 @@ export const readConfig = (model: BaseChatModel): Partial<ModelConfig> => {
 /** Per-model idle stream timeout (ms), falling back to the package default. */
 export const idleTimeout = (config: Partial<ModelConfig>): number =>
   config.streamTimeout ?? MODEL_STREAM_TIMEOUT_MS
+
+/**
+ * The output ceiling the retry escalator may climb to.
+ *
+ * Two different things claim to bound the output, and only one of them is a fact:
+ * `maxTokensCap` is what this deployment budgeted, `maxOutput` is what the provider will
+ * accept. Taking the declared cap alone let a preset out-declare its model and turned
+ * every escalation into a 400; taking the capability alone would ignore a deliberately
+ * frugal budget. So the declared value chooses the ceiling and the capability trims it,
+ * and only when neither is stated does {@link DEFAULT_MAX_OUTPUT_CAP} apply.
+ */
+export const resolveOutputCap = (config: Partial<ModelConfig>): number => {
+  const declared = typeof config.maxTokensCap === 'number' && config.maxTokensCap > 0
+    ? config.maxTokensCap
+    : undefined
+  const capability = typeof config.maxOutput === 'number' && config.maxOutput > 0
+    ? config.maxOutput
+    : undefined
+  const cap = declared ?? capability ?? DEFAULT_MAX_OUTPUT_CAP
+
+  return capability != null ? Math.min(cap, capability) : cap
+}

package/src/utils/null-report.ts

@@ -45,6 +45,7 @@ export const buildNullReport = (p: NullReportParams): NullCapture => {
     finish_reason?: string
     usage?: { prompt_tokens?: number; completion_tokens?: number; reasoning_tokens?: number }
   } | undefined
+  const stopReason = (raw?.additional_kwargs as { stop_reason?: string } | undefined)?.stop_reason
   const usageMeta = raw?.usage_metadata as { input_tokens?: number; output_tokens?: number } | undefined
   const toolCalls = (raw as unknown as { tool_calls?: unknown[] } | null)?.tool_calls
 
@@ -81,7 +82,14 @@ export const buildNullReport = (p: NullReportParams): NullCapture => {
       tool_calls: toolCalls,
     } : null,
     diagnostics: {
-      finishReason: responseMeta?.finish_reason,
+      // Two providers, two places. OpenAI-compatible APIs put it on `response_metadata`;
+      // Anthropic never does — it arrives on the `message_delta` event and langchain spreads it
+      // into `additional_kwargs.stop_reason`. Reading only the first printed `undefined` for
+      // every Anthropic null, hiding the `max_tokens` that explains most of them.
+      finishReason: responseMeta?.finish_reason ?? stopReason,
+      /** No text block at all — the shape of a completion that was all reasoning. */
+      thinkingOnly: Array.isArray(raw?.content) && raw.content.length > 0
+        && !raw.content.some(part => (part as { type?: string }).type === 'text'),
       inputTokens: usageMeta?.input_tokens ?? responseMeta?.usage?.prompt_tokens,
       outputTokens: usageMeta?.output_tokens ?? responseMeta?.usage?.completion_tokens,
       reasoningTokens: responseMeta?.usage?.reasoning_tokens,

package/tests/context.ts

@@ -16,6 +16,8 @@ export const gates = makeGates({
 export const Role = {
   Analyst: 'analyst',
   Picker: 'picker',
+  /** The conventional cheap tier — same value as `UTILITY_ROLE`. */
+  Utility: 'utility',
 } as const
 
 /**
@@ -60,6 +62,7 @@ export const anthropicConfigs = (): ModelConfig[] => [
  */
 export const offlineConfigs = (): ModelConfig[] => [
   { alias: Role.Analyst, provider: ModelProvider.OpenAI, model: 'gpt-4.1-mini', secret: 'sk-test' },
+  { alias: Role.Utility, provider: ModelProvider.OpenAI, model: 'gpt-4.1-nano', secret: 'sk-test' },
   {
     alias: Role.Picker, provider: ModelProvider.Compatible, model: 'some/model', secret: 'sk-test',
     baseUrl: 'https://openrouter.ai/api/v1',

package/tests/execution.spec.ts

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, test } from 'bun:test'
-import { ExecutionEffort, ExecutionLevel } from '@owlmeans/llm-common'
+import { ExecutionEffort, ExecutionLevel, UTILITY_ROLE } from '@owlmeans/llm-common'
 import type { ExecutionState, ModelConfigPatch, TaskExecutionState } from '@owlmeans/llm-common'
 import { DEFAULT_EFFORT, EFFORT_TABLE, makeExecutionService, makeLlmService } from '@owlmeans/llm'
 import type { ExecutionService, ProjectExecution, TaskExecution } from '@owlmeans/llm'
@@ -135,6 +135,65 @@ describe('@owlmeans/llm — model policy resolution', () => {
   })
 })
 
+describe('@owlmeans/llm — utility tier', () => {
+  test('the conventional role is resolved at the cheapest tier', () => {
+    service.utility(root)
+    expect(resolved.at(-1))
+      .toEqual({ alias: UTILITY_ROLE, override: EFFORT_TABLE[ExecutionEffort.Economy] })
+  })
+
+  // The whole point of routing it through `model`: a deployment remaps or pins the cheap
+  // tier with the levers it already uses for every other role.
+  test('a role override remaps which model the utility tier resolves', () => {
+    const remapped = service.escalate(root, { roleOverrides: { [UTILITY_ROLE]: Role.Picker } })
+    service.utility(remapped)
+    expect(resolved.at(-1)?.alias).toBe(Role.Picker)
+  })
+
+  test('a policy utility role replaces the conventional one, and is still remapped', () => {
+    const named = service.root({
+      models: makeService(),
+      policy: { effort: DEFAULT_EFFORT, utilityRole: Role.Analyst },
+      purpose: { type: 'spec' },
+    })
+    service.utility(named)
+    expect(resolved.at(-1)?.alias).toBe(Role.Analyst)
+
+    service.utility(service.escalate(named, { roleOverrides: { [Role.Analyst]: Role.Picker } }))
+    expect(resolved.at(-1)?.alias).toBe(Role.Picker)
+  })
+
+  test('a model override pins the utility role like any other', () => {
+    const pinned = service.escalate(root, { modelOverrides: { [UTILITY_ROLE]: { maxTokens: 512 } } })
+    service.utility(pinned)
+    expect(resolved.at(-1)?.override)
+      .toEqual({ ...EFFORT_TABLE[ExecutionEffort.Economy], maxTokens: 512 })
+  })
+
+  // The floor is local — asking for a cheap side model must not quietly downgrade the
+  // execution that the real work still runs on.
+  test('the economy floor does not touch the execution it was asked on', () => {
+    const high = service.escalate(root, { effort: ExecutionEffort.Max })
+    service.utility(high)
+    expect(high.policy.effort).toBe(ExecutionEffort.Max)
+
+    service.model(high, Role.Analyst)
+    expect(resolved.at(-1)?.override).toEqual(EFFORT_TABLE[ExecutionEffort.Max])
+  })
+
+  test('a named utility role survives refinement of the branch', () => {
+    const named = service.root({
+      models: makeService(),
+      policy: { effort: DEFAULT_EFFORT, utilityRole: Role.Analyst },
+      purpose: { type: 'spec' },
+    })
+    const task = service.forTask(named, { effort: ExecutionEffort.High })
+    expect(task.policy.utilityRole).toBe(Role.Analyst)
+    service.utility(task)
+    expect(resolved.at(-1)?.alias).toBe(Role.Analyst)
+  })
+})
+
 describe('@owlmeans/llm — snapshot and restore', () => {
   test('a snapshot carries the state and none of the collaborators', () => {
     const state = service.snapshot(root) as ExecutionState & Record<string, unknown>
@@ -222,21 +281,97 @@ describe('@owlmeans/llm — prompt policy accumulation', () => {
   })
 })
 
-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()
+describe('@owlmeans/llm — plugin registration', () => {
+  test('seats a plugin by alias, so a layer wired twice answers once', async () => {
+    // Mixins compose. A plugin registered twice would answer twice, and since the first usable
+    // answer wins, the duplicate is silent rather than loud.
+    const asked: string[] = []
+    service.use({ alias: 'files', advise: async () => { asked.push('first'); return null } })
+    service.use({ alias: 'files', advise: async () => { asked.push('second'); return 'answer' } })
+
+    await service.advise(root, { kind: 'files', task: 'x' })
+
+    expect(asked).toEqual(['second'])
   })
 
-  test('a registered plugin receives the JSON-safe state and the execution', async () => {
-    const seen: Array<{ state: ExecutionState, key?: string }> = []
-    service.use({ onCheckpoint: async (state, _exec, key) => { seen.push({ state, key }) } })
+  test('a plugin with no alias is simply appended', async () => {
+    const asked: string[] = []
+    service.use({ advise: async () => { asked.push('a'); return null } })
+    service.use({ advise: async () => { asked.push('b'); return null } })
 
-    const task = service.forTask(root, { phase: 'draft' })
-    await service.checkpoint(task, 'project-1')
+    await service.advise(root, { kind: 'files', task: 'x' })
+
+    expect(asked).toEqual(['a', 'b'])
+  })
+})
+
+describe('@owlmeans/llm — advice seam', () => {
+  test('advise resolves to null when no plugin is registered', async () => {
+    await expect(service.advise(root, { kind: 'files', task: 'x' })).resolves.toBeNull()
+  })
+
+  test('an advisor receives the execution and the request', async () => {
+    const seen: Array<{ kind: string, task: string, level: string }> = []
+    service.use({
+      advise: async (exec, request) => {
+        seen.push({ kind: request.kind, task: request.task, level: exec.level })
+        return 'the card'
+      },
+    })
+
+    const helper = service.forHelper(root, { role: Role.Analyst })
+    await expect(service.advise(helper, { kind: 'files', task: 'implement X' })).resolves.toBe('the card')
+    expect(seen).toEqual([{ kind: 'files', task: 'implement X', level: ExecutionLevel.Helper }])
+  })
+
+  test('the first usable answer wins and later advisors are not consulted', async () => {
+    let secondCalled = false
+    service.use({ advise: async () => null })
+    service.use({ advise: async () => '   ' })
+    service.use({ advise: async () => 'first real' })
+    service.use({ advise: async () => { secondCalled = true; return 'second' } })
+
+    await expect(service.advise(root, { kind: 'k', task: 't' })).resolves.toBe('first real')
+    expect(secondCalled).toBe(false)
+  })
+
+  test('a throwing advisor is skipped rather than failing the work', async () => {
+    service.use({ advise: async () => { throw new Error('advisor down') } })
+    service.use({ advise: async () => 'survived' })
+
+    await expect(service.advise(root, { kind: 'k', task: 't' })).resolves.toBe('survived')
+  })
+
+  test('a plugin without advise is ignored', async () => {
+    service.use({ onCheckpoint: async () => {} })
+    await expect(service.advise(root, { kind: 'k', task: 't' })).resolves.toBeNull()
+  })
+})
+
+describe('@owlmeans/llm — per-helper output sizing', () => {
+  test('output becomes the resolved model\'s initial maxTokens', () => {
+    service.forHelper(root, { role: Role.Analyst, output: 24000 })
+
+    const call = resolved.at(-1)!
+    expect(call.override?.maxTokens).toBe(24000)
+  })
+
+  test('output is not carried onto the helper as a field', () => {
+    const helper = service.forHelper(root, { role: Role.Analyst, output: 24000 })
+    expect((helper as unknown as { output?: unknown }).output).toBeUndefined()
+  })
+
+  test('a temperature refinement keeps the helper\'s output budget', () => {
+    const helper = service.forHelper(root, { role: Role.Analyst, output: 24000 })
+    helper.temperatureFactory(0.7)
+
+    const call = resolved.at(-1)!
+    expect(call.override?.maxTokens).toBe(24000)
+    expect(call.override?.temperature).toBe(0.7)
+  })
 
-    expect(seen).toHaveLength(1)
-    expect(seen[0]!.key).toBe('project-1')
-    expect((seen[0]!.state as TaskExecutionState).phase).toBe('draft')
-    expect((seen[0]!.state as unknown as { models?: unknown }).models).toBeUndefined()
+  test('without output the override carries no token sizing', () => {
+    service.forHelper(root, { role: Role.Analyst })
+    expect(resolved.at(-1)!.override?.maxTokens).toBeUndefined()
   })
 })

package/tests/helpers.spec.ts

@@ -187,6 +187,9 @@ describe('helpers/spectate', () => {
 
     const last = spectator.entries[0]!.messages.at(-1)!
     expect(last.contentType).toBe('tool_call')
-    expect(last.content).toEqual([{ id: '1', name: 'extract', args: { a: 1 } }] as unknown as string)
+    // Serialized, not the raw array: a trace row is a string column, and handing it an object
+    // is what stored `[object Object]` for every tool call until this was fixed.
+    expect(typeof last.content).toBe('string')
+    expect(JSON.parse(last.content)).toEqual([{ id: '1', name: 'extract', args: { a: 1 } }])
   })
 })

package/tests/plugins.spec.ts

@@ -9,8 +9,12 @@ import {
   registerLlmPlugin, resolvePlugin,
 } from '@owlmeans/llm'
 import type { LlmPlugin, ModelConfig } from '@owlmeans/llm'
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
+import { DEFAULT_MAX_OUTPUT_CAP } from '@owlmeans/llm'
 import { offlineConfigs, Role } from './context.js'
 import { stripCacheMarkers } from '../src/utils/prompt.js'
+import { resolveOutputCap } from '../src/utils/config.js'
+import { ADAPTIVE_MIN_MAX_TOKENS } from '../src/plugins/anthropic.js'
 
 const build = (plugin: LlmPlugin, config: Partial<ModelConfig> = {}) =>
   plugin.build({
@@ -146,6 +150,30 @@ describe('@owlmeans/llm — retry escalation behaviour', () => {
     expect((openAiPlugin.refine({ base, attempt: 8, maxOutputCap: 5000 }) as ChatOpenAI).maxTokens).toBe(5000)
   })
 
+  /**
+   * `refine` rebuilds the model for EVERY attempt, attempt 0 included, so a parameter the
+   * Responses API rejects has to be suppressed in both hooks: omitting it in `build` alone
+   * still put `temperature` on every single request and 400'd the whole gpt-5 family.
+   */
+  test('refine never restores sampling knobs on a Responses-API model', () => {
+    const base = build(openAiPlugin, { model: 'gpt-5.6-terra', maxTokens: 1000 })
+    const read = (model: unknown) => model as ChatOpenAI & { topP?: number }
+
+    for (const attempt of [0, 1, 4]) {
+      const refined = read(openAiPlugin.refine({ base, attempt, temperature: 0.7, maxOutputCap: 8000 }))
+      expect(refined.temperature).toBeUndefined()
+      expect(refined.topP).toBeUndefined()
+      expect((refined.lc_kwargs as { useResponsesApi?: boolean }).useResponsesApi).toBe(true)
+    }
+
+    // The chat-completions families still get the deterministic default and the escalator.
+    const chat = read(openAiPlugin.refine({
+      base: build(openAiPlugin, { model: 'gpt-4.1-mini', maxTokens: 1000 }),
+      attempt: 0, maxOutputCap: 8000,
+    }))
+    expect(chat.temperature).toBe(0)
+  })
+
   // Extra budget must become visible output, not more hidden reasoning.
   test('refine shrinks an absolute reasoning cap as the attempt grows', () => {
     const base = build(compatiblePlugin, {
@@ -513,3 +541,186 @@ describe('@owlmeans/llm — service', () => {
     expect(() => service.getModel('no-such-role')).toThrow()
   })
 })
+
+/**
+ * A `preset` is a BASE its referent refines, not a final word. Asserted as a full ladder
+ * because the failure it guards was silent: with the preset assigned last, a role that
+ * declared one discarded its own fields AND the caller's override, so effort-tier token
+ * caps and a temperature refinement simply vanished.
+ */
+describe('@owlmeans/llm — config precedence', () => {
+  const layered = (): ModelConfig[] => [
+    {
+      alias: 'base', provider: ModelProvider.OpenAI, model: 'base-model', secret: 'sk-test',
+      maxTokens: 1000, temperature: 0.3, topP: 0.5,
+    },
+    { alias: 'role', preset: 'base', provider: ModelProvider.OpenAI, secret: 'sk-test', maxTokens: 2000 },
+    {
+      alias: 'other', provider: ModelProvider.OpenAI, model: 'other-model', secret: 'sk-test',
+      maxTokens: 500,
+    },
+  ]
+  const configOf = (model: BaseChatModel) =>
+    (model as unknown as { metadata: { config: ModelConfig } }).metadata.config
+
+  test('an alias refines its preset instead of being overwritten by it', () => {
+    const service = makeLlmService({ models: layered }, 'spec-prec-alias')
+    const config = configOf(service.getModel('role'))
+
+    expect(config.model).toBe('base-model')   // inherited
+    expect(config.maxTokens).toBe(2000)       // the alias's own field wins
+    expect(config.temperature).toBe(0.3)      // inherited
+  })
+
+  test('a call override outranks both the alias and its preset', () => {
+    const service = makeLlmService({ models: layered }, 'spec-prec-override')
+    const config = configOf(service.getModel('role', { maxTokens: 3000, temperature: 0.1 }))
+
+    expect(config.maxTokens).toBe(3000)
+    expect(config.temperature).toBe(0.1)
+    expect(config.model).toBe('base-model')
+  })
+
+  test('an override naming a preset picks that model but yields to explicit fields', () => {
+    const service = makeLlmService({ models: layered }, 'spec-prec-pin')
+    const config = configOf(service.getModel('other', { preset: 'base', maxTokensCap: 32000 }))
+
+    expect(config.model).toBe('base-model')   // the pin outranks the alias's own model
+    expect(config.maxTokensCap).toBe(32000)   // explicit override field survives the pin
+    expect(config.alias).toBe('other')        // the alias asked for is what is built
+  })
+
+  test('preset resolution stays one level deep', () => {
+    // `role` inherits its model FROM `base`, so pinning `role` contributes only the
+    // fields `role` itself declares. One level is the long-standing rule; the layering
+    // fix did not make it a chain, and a preset meant to carry a model must name one.
+    const service = makeLlmService({ models: layered }, 'spec-prec-depth')
+    const config = configOf(service.getModel('other', { preset: 'role' }))
+
+    expect(config.model).toBe('other-model')
+    expect(config.maxTokens).toBe(2000)
+  })
+
+  test('an undefined override value does not shadow the layer below', () => {
+    const service = makeLlmService({ models: layered }, 'spec-prec-undef')
+    const config = configOf(service.getModel('role', { maxTokens: undefined }))
+
+    expect(config.maxTokens).toBe(2000)
+  })
+
+  test('the service-wide stream timeout stays a floor under the merge', () => {
+    const service = makeLlmService(
+      { models: layered, streamTimeout: 12_000 }, 'spec-prec-timeout'
+    )
+    expect(configOf(service.getModel('role')).streamTimeout).toBe(12_000)
+  })
+})
+
+describe('@owlmeans/llm — output capability', () => {
+  const capped = (): ModelConfig[] => [
+    {
+      alias: 'small', provider: ModelProvider.OpenAI, model: 'small-model', secret: 'sk-test',
+      maxTokens: 16000, maxTokensCap: 64000, maxOutput: 8000, contextWindow: 200_000,
+    },
+    {
+      alias: 'honest', provider: ModelProvider.OpenAI, model: 'honest-model', secret: 'sk-test',
+      maxTokens: 4000, maxTokensCap: 32000, maxOutput: 64000, contextWindow: 200_000,
+      fallback: { model: 'big-model', maxOutput: 128_000, contextWindow: 1_000_000 },
+    },
+  ]
+
+  test('the declared cap chooses the ceiling and the capability trims it', () => {
+    expect(resolveOutputCap({ maxTokensCap: 32000 })).toBe(32000)
+    expect(resolveOutputCap({ maxOutput: 64000 })).toBe(64000)
+    expect(resolveOutputCap({ maxTokensCap: 64000, maxOutput: 8000 })).toBe(8000)
+    expect(resolveOutputCap({ maxTokensCap: 16000, maxOutput: 64000 })).toBe(16000)
+    expect(resolveOutputCap({})).toBe(DEFAULT_MAX_OUTPUT_CAP)
+  })
+
+  test('an initial budget above the provider capability is clamped at build time', () => {
+    const service = makeLlmService({ models: capped }, 'spec-cap-clamp')
+    const config = (service.getModel('small') as unknown as { metadata: { config: ModelConfig } })
+      .metadata.config
+
+    expect(config.maxTokens).toBe(8000)
+  })
+
+  test('a fallback carries its own capability rather than the primary\'s', () => {
+    const service = makeLlmService({ models: capped }, 'spec-cap-fallback')
+    const primary = service.getModel('honest')
+    const fallback = (primary as unknown as { __fallbackModel?: BaseChatModel }).__fallbackModel!
+    const config = (fallback as unknown as { metadata: { config: ModelConfig } }).metadata.config
+
+    expect(config.maxOutput).toBe(128_000)
+    expect(resolveOutputCap(config)).toBe(32000)
+  })
+})
+
+/**
+ * The models that took the sampling knobs away also think adaptively whether asked to or not,
+ * and that thinking is billed against the same `max_tokens` as the answer. A budget sized for
+ * the answer alone gets spent on reasoning, and the completion comes back with no text at all.
+ */
+describe('@owlmeans/llm — adaptive-thinking output budget', () => {
+  const maxTokensOf = (model: BaseChatModel): number | undefined =>
+    (model as unknown as { maxTokens?: number }).maxTokens
+
+  test('an always-reasoning model gets room for the reasoning AND the answer', () => {
+    const model = build(anthropicPlugin, { model: 'claude-sonnet-5', maxTokens: 8192 })
+
+    expect(maxTokensOf(model)).toBe(ADAPTIVE_MIN_MAX_TOKENS)
+  })
+
+  test('the floor never lowers a preset that asked for more', () => {
+    const model = build(anthropicPlugin, {
+      model: 'claude-sonnet-5', maxTokens: 64_000, maxTokensCap: 64_000, maxOutput: 128_000,
+    })
+
+    expect(maxTokensOf(model)).toBe(64_000)
+  })
+
+  /** Raising the floor past what the provider accepts turns a retryable empty into a 400. */
+  test('the floor is clamped to what the provider accepts', () => {
+    const model = build(anthropicPlugin, {
+      model: 'claude-sonnet-5', maxTokens: 4096, maxOutput: 8192,
+    })
+
+    expect(maxTokensOf(model)).toBe(8192)
+  })
+
+  test('models that still accept sampling keep the budget their preset asked for', () => {
+    const model = build(anthropicPlugin, { model: 'claude-haiku-4-5', maxTokens: 8192 })
+
+    expect(maxTokensOf(model)).toBe(8192)
+  })
+})
+
+describe('@owlmeans/llm — anthropic thinking control', () => {
+  // `thinkingExplicitlySet` is what decides whether langchain puts `thinking` on the wire at
+  // all; the field itself defaults to `disabled` and so proves nothing on its own.
+  const wire = (model: unknown) => model as { thinkingExplicitlySet: boolean; thinking: { type: string } }
+
+  test('disableThinking sends an explicit thinking:disabled to the adaptive family', () => {
+    const on = wire(build(anthropicPlugin, { model: 'claude-sonnet-5', disableThinking: true }))
+    expect(on.thinkingExplicitlySet).toBe(true)
+    expect(on.thinking).toEqual({ type: 'disabled' })
+    expect(anthropicPlugin.suppressesThinking?.({ alias: 'a', model: 'claude-sonnet-5', disableThinking: true } as ModelConfig)).toBe(true)
+  })
+
+  test('without the flag nothing is sent and the provider default applies', () => {
+    expect(wire(build(anthropicPlugin, { model: 'claude-sonnet-5' })).thinkingExplicitlySet).toBe(false)
+    expect(anthropicPlugin.suppressesThinking?.({ alias: 'a', model: 'claude-sonnet-5' } as ModelConfig)).toBe(false)
+  })
+
+  test('models that reason only when asked are left alone', () => {
+    expect(wire(build(anthropicPlugin, { model: 'claude-haiku-4-5', disableThinking: true })).thinkingExplicitlySet).toBe(false)
+    expect(anthropicPlugin.suppressesThinking?.({ alias: 'a', model: 'claude-haiku-4-5', disableThinking: true } as ModelConfig)).toBe(false)
+  })
+
+  test('refine keeps thinking off on every attempt', () => {
+    const base = build(anthropicPlugin, { model: 'claude-sonnet-5', disableThinking: true, maxTokens: 1000 })
+    const refined = wire(anthropicPlugin.refine({ base, attempt: 1, maxOutputCap: 64000 }))
+    expect(refined.thinkingExplicitlySet).toBe(true)
+    expect(refined.thinking).toEqual({ type: 'disabled' })
+  })
+})

package/tests/prompt.spec.ts

@@ -148,6 +148,49 @@ describe('@owlmeans/llm — prompt composition', () => {
     expect(context[0]!.text).toContain('second note')
   })
 
+  // Two plugins can each be able to render the same skill — a static catalogue and a
+  // detector. Without the claim they both do, and the model is told the same thing twice.
+  test('a key is claimed by the first plugin only, within one composition', async () => {
+    const grants: boolean[] = []
+    const claimer = (alias: string): LlmPromptPlugin => ({
+      alias,
+      compose: ctx => {
+        if (ctx.claim('skill:a')) {
+          ctx.add(PromptBlock.Packages, `from ${alias}`)
+        }
+        grants.push(ctx.claim('probe'))
+      },
+    })
+    const result = await compose(service([], [claimer('first'), claimer('second')]))
+
+    expect(grants).toEqual([true, false])
+    expect(result.blocks.find(b => b.block === PromptBlock.Packages)?.text).toBe('from first')
+  })
+
+  test('the claim set is per composition, not per service', async () => {
+    const svc = service([], [{
+      alias: 'claimer', compose: ctx => ctx.add(PromptBlock.Packages, `${ctx.claim('once')}`),
+    }])
+    const first = await compose(svc)
+    const second = await compose(svc)
+
+    expect(first.blocks[0]!.text).toBe('true')
+    expect(second.blocks[0]!.text).toBe('true')
+  })
+
+  // The seam has to be free: a composition where nobody claims must render the bytes it
+  // rendered before the seam existed, or every cached prefix in the fleet is invalidated.
+  test('claiming nothing changes nothing about the composed bytes', async () => {
+    const input = { role: 'R', skills: ['a'], context: ['note'] }
+    const plain = await compose(service([skill('a', 'A')]), input)
+    const claiming = await compose(
+      service([skill('a', 'A')], [{ alias: 'quiet', compose: ctx => { ctx.claim('a') } }]),
+      input,
+    )
+    expect(JSON.stringify(claiming.system)).toBe(JSON.stringify(plain.system))
+    expect(claiming.breakpoints).toBe(plain.breakpoints)
+  })
+
   test('nothing declared composes to no system message at all', async () => {
     const result = await compose(service())
     expect(result.system).toBeNull()