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

package/src/helpers/spectate.ts

@@ -5,6 +5,15 @@ import type { SpectatorEntryMessage } from '@owlmeans/llm-common'
 import type { LlmSpectator, ModelInputItem } from '../types.js'
 import { hasCacheActivity, readCacheUsage } from './cache.js'
 
+/**
+ * The trace's `content` column is a string; LangChain content is a string-or-blocks union, and
+ * tool calls are arrays. Anything non-string must be stored as JSON — a plain string coercion
+ * downstream turns it into `[object Object]` and destroys the readable half of the trace
+ * (`raw` keeps the payload, but `content` is what trace readers query).
+ */
+const asText = (content: unknown): string =>
+  typeof content === 'string' ? content : JSON.stringify(content) ?? ''
+
 /** Normalize one prompt message into the spectator's storage shape. */
 const describeInput = (msg: ModelInputItem, callType: string): SpectatorEntryMessage => {
   const entry: SpectatorEntryMessage = {
@@ -16,17 +25,17 @@ const describeInput = (msg: ModelInputItem, callType: string): SpectatorEntryMes
 
   if (msg instanceof BaseMessage) {
     entry.type = msg.type
-    entry.content = msg.content as unknown as string
+    entry.content = asText(msg.content)
     entry.name = msg.name
     entry.contentType = typeof msg.content === 'string' ? SpectatorContentType.Text : SpectatorContentType.Json
     entry.usage = 'usage_metadata' in msg ? msg.usage_metadata as UsageMetadata : undefined
     entry.raw = JSON.stringify({ message: msg, content: msg.content, meta: msg.response_metadata })
   } else if (typeof msg === 'object' && 'content' in msg) {
     entry.type = msg.role as string ?? 'unknown'
-    entry.content = msg.content as string ?? msg as unknown as string
+    entry.content = asText(msg.content ?? msg)
     entry.raw = JSON.stringify(msg)
   } else {
-    entry.content = msg as unknown as string
+    entry.content = asText(msg)
     entry.raw = JSON.stringify(msg)
   }
 
@@ -58,10 +67,10 @@ export const spectate = (spectator: LlmSpectator, callType: string) =>
     }
 
     if (message.tool_calls != null && message.tool_calls.length > 0) {
-      completion.content = message.tool_calls as unknown as string
+      completion.content = asText(message.tool_calls)
       completion.contentType = SpectatorContentType.ToolCall
     } else {
-      completion.content = message.content as unknown as string
+      completion.content = asText(message.content)
     }
 
     // Silent unless the provider reported cache activity, so it costs nothing when

package/src/index.ts

@@ -9,6 +9,8 @@ export * from './execution/index.js'
 export * from './prompt/index.js'
 export type * from './plugins/types.js'
 export { plugins, registerLlmPlugin, pluginOf, pluginFor, resolvePlugin } from './plugins/index.js'
-export { anthropicPlugin, ANTHROPIC_FAMILY } from './plugins/anthropic.js'
+export { anthropicPlugin, ANTHROPIC_FAMILY, NO_SAMPLING_PREFIXES, rejectsSampling } from './plugins/anthropic.js'
 export { compatiblePlugin } from './plugins/compatible.js'
-export { openAiPlugin, openAiFamily, OPENAI_FAMILY } from './plugins/openai.js'
+export {
+  openAiPlugin, openAiFamily, OPENAI_FAMILY, RESPONSES_API_PREFIXES, usesResponsesApi,
+} from './plugins/openai.js'

package/src/model.ts

@@ -6,7 +6,7 @@ import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
 import { StructuredMode } from '@owlmeans/llm-common'
 import type { NullKind } from '@owlmeans/llm-common'
 import {
-  DEFAULT_MAX_OUTPUT_CAP, DEFAULT_MODEL_RETRIES, FALLBACK_AFTER_ATTEMPTS, MAX_CACHE_BREAKPOINTS,
+  DEFAULT_MODEL_RETRIES, FALLBACK_AFTER_ATTEMPTS, MAX_CACHE_BREAKPOINTS,
 } from './consts.js'
 import { LlmModelError } from './errors.js'
 import { pluginFor, pluginOf } from './plugins/index.js'
@@ -15,7 +15,7 @@ import { coerceToSchema, parseJsonContent } from './helpers/json.js'
 import { normalizeInput } from './helpers/messages.js'
 import { withRetry } from './helpers/retry.js'
 import { spectate } from './helpers/spectate.js'
-import { idleTimeout, readConfig } from './utils/config.js'
+import { idleTimeout, readConfig, resolveOutputCap } from './utils/config.js'
 import { reportNull } from './utils/null-report.js'
 import type { NullReportParams } from './utils/null-report.js'
 import { applyNoThink, dropBlankContent, ensureJsonMention, stripCacheMarkers } from './utils/prompt.js'
@@ -88,6 +88,7 @@ export const makeLlmModel = ({
   prompt,
   prompts,
   files,
+  utility,
 }: LlmModelOptions, spectator: LlmSpectator): LlmModel => {
 
   const ajv = new Ajv({ strict: false })
@@ -98,6 +99,17 @@ export const makeLlmModel = ({
   const plugin: LlmPlugin | undefined = pluginOf(config.provider) ?? pluginFor(model)
   const timeout = idleTimeout(config)
 
+  /**
+   * Where on the escalation ladder this call starts.
+   *
+   * The ladder has exactly `retries` rungs, so a seed past the last one buys nothing and
+   * would only inflate the attempt number handed to `refine`. Clamped, `refineModel` sees
+   * at most `2 * (retries - 1)` — the escalator's own doubling stays bounded by the
+   * output cap either way.
+   */
+  const ladderSeed = (escalation?: number): number =>
+    Math.max(0, Math.min(Math.floor(escalation ?? 0), retries - 1))
+
   /**
    * Normalize, compose the system prompt, then apply every in-place prompt adaptation, in
    * dependency order.
@@ -133,7 +145,7 @@ export const makeLlmModel = ({
           callSkills: callSkills ?? prompt?.callSkills,
         },
         msgs,
-        { model, provider: plugin, purpose, action, cacheMax, files },
+        { model, provider: plugin, purpose, action, cacheMax, files, utility },
       )
       if (composed.system != null) {
         msgs.unshift(composed.system)
@@ -147,7 +159,9 @@ export const makeLlmModel = ({
     }
 
     if (json) ensureJsonMention(msgs)
-    applyNoThink(msgs, config.disableThinking)
+    // The soft switch is for models with no request-level control; a plugin that sends the
+    // real parameter must not also get the directive as prompt text.
+    applyNoThink(msgs, config.disableThinking === true && plugin?.suppressesThinking?.(config) !== true)
     // Cache markers replace string content with content blocks, so they must go last.
     const ttl = prompt?.cacheTtl
     const marked = plugin?.patchCache?.(msgs, {
@@ -216,9 +230,9 @@ export const makeLlmModel = ({
     const basePlugin = pluginOf(baseConfig.provider) ?? pluginFor(base)
     if (basePlugin == null) return base
 
-    const maxOutputCap = typeof baseConfig.maxTokensCap === 'number' && baseConfig.maxTokensCap > 0
-      ? baseConfig.maxTokensCap
-      : DEFAULT_MAX_OUTPUT_CAP
+    // Read from the ACTIVE base — after the fallback swap that is the fallback's own
+    // config, so the escalator sizes the model it is actually talking to.
+    const maxOutputCap = resolveOutputCap(baseConfig)
     const refined = basePlugin.refine({ base, attempt, temperature, maxOutputCap })
 
     if (attempt > 0) {
@@ -297,11 +311,15 @@ export const makeLlmModel = ({
   const helper: LlmModel = {
     ask: async (
       input,
-      { ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills }: LlmAskOptions
+      {
+        ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills,
+        escalation, fatal,
+      }: LlmAskOptions
     ) => {
       const msgs = await prepare(input, action, useCache, cacheMax, false, skills)
-      return withRetry({ retries, outputErrors }, async i => {
-        const refined = refineModel(i)
+      const seed = ladderSeed(escalation)
+      return withRetry({ retries, outputErrors, fatal }, async i => {
+        const refined = refineModel(seed + i)
         console.log('Use model to ask: ', refined.getName(), refined.lc_kwargs.model)
         const startedAt = Date.now()
         let result: AIMessageChunk | null = null
@@ -315,7 +333,7 @@ export const makeLlmModel = ({
         }
 
         const message = new AIMessage(result)
-        let output: string | null = typeof result.content === 'string'
+        let output: string = typeof result.content === 'string'
           ? result.content
           : Array.isArray(result.content)
             ? result.content
@@ -323,19 +341,39 @@ export const makeLlmModel = ({
                 typeof c === 'object' && c !== null && 'type' in c && c.type === 'text'
               )
               .map(c => c.text)
-              .join('') || null
-            : null
+              .join('')
+            : ''
+
+        // A completion can carry text in blocks this strict filter does not name — the tolerant
+        // extractor reads any block with a string `text`. Only consulted once the strict pass
+        // found nothing, so the usual path keeps its exact spacing.
+        if (output.trim() === '') {
+          output = textOf(result.content)
+        }
 
         const entry = await spectate(spectator, 'ask')(msgs, message, action, i, startedAt)
         if (ref != null) ref.spectatorEntry = entry
 
+        // An empty completion is a NULL RESULT, and it is diagnosed here rather than blamed on
+        // the caller. Both shipped filters return null only for empty input, so letting one run
+        // first reported every empty answer as `filter-rejected` — naming the innocent party and,
+        // worse, skipping `reportNull`, whose stop reason and output-token count are the only
+        // things that say WHY nothing came back (a model that spent its whole budget thinking).
+        if (output.trim() === '') {
+          throw await nullResult('ask', {
+            action, attempt: i, startedAt, refined, msgs, raw: result, useCache,
+          })
+        }
+
         if (filter != null) {
-          output = await filter(output ?? '', message)
-          if (output == null) {
-            throw new LlmModelError(`filter-rejected:${JSON.stringify(message).substring(0, 50)}...`)
+          const produced = output
+          const filtered = await filter(produced, message)
+          if (filtered == null) {
+            // The OUTPUT, not the message envelope: `JSON.stringify(new AIMessage(...))` is 80
+            // constant characters of LangChain serialization stub and says nothing at all.
+            throw new LlmModelError(`filter-rejected:${produced.substring(0, 200)}`)
           }
-        } else if (output == null || output.trim() === '') {
-          throw new LlmModelError(`empty-content:${JSON.stringify(message).substring(0, 50)}...`)
+          output = filtered
         }
 
         notifyRef(ref, message)
@@ -345,11 +383,15 @@ export const makeLlmModel = ({
 
     talk: async (
       input,
-      { ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills }: LlmTalkOptions
+      {
+        ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills,
+        escalation, fatal,
+      }: LlmTalkOptions
     ) => {
       const msgs = await prepare(input, action, useCache, cacheMax, false, skills)
-      return withRetry({ retries, outputErrors }, async i => {
-        const refined = refineModel(i)
+      const seed = ladderSeed(escalation)
+      return withRetry({ retries, outputErrors, fatal }, async i => {
+        const refined = refineModel(seed + i)
         console.log('Use model to talk: ', refined.getName(), refined.lc_kwargs.model)
         const startedAt = Date.now()
         let result: AIMessageChunk | null = null
@@ -381,14 +423,18 @@ export const makeLlmModel = ({
     invoke: async <T>(
       input: ModelInput,
       schema: JSONSchemaType<T>,
-      { temperature, ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills }: LlmInvokeOptions<T>
+      {
+        temperature, ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS,
+        skills, escalation, fatal,
+      }: LlmInvokeOptions<T>
     ) => {
       const msgs = await prepare(input, action, useCache, cacheMax, true, skills)
       const { name, innerSchema, validate } = resolveSchemaValidator<T>(ajv, schema)
       const toolName = toToolName((innerSchema as { title?: string }).title ?? name)
 
-      return withRetry({ retries, outputErrors }, async i => {
-        const refined = refineModel(i, temperature)
+      const seed = ladderSeed(escalation)
+      return withRetry({ retries, outputErrors, fatal }, async i => {
+        const refined = refineModel(seed + i, temperature)
         console.log('Use model invoke: ', refined.getName(), refined.lc_kwargs.model)
         const startedAt = Date.now()
         const { piece, result: collected } = await streamStructured(refined, msgs, innerSchema, toolName, action)
@@ -429,14 +475,18 @@ export const makeLlmModel = ({
     request: async <T>(
       input: ModelInput,
       schema: JSONSchemaType<T>,
-      { ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills }: LlmRequestOptions
+      {
+        ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills,
+        escalation, fatal,
+      }: LlmRequestOptions
     ) => {
       const msgs = await prepare(input, action, useCache, cacheMax, true, skills)
       const { name, innerSchema, validate } = resolveSchemaValidator<T>(ajv, schema)
       const toolName = toToolName((innerSchema as { title?: string }).title ?? name)
 
-      return withRetry({ retries, outputErrors }, async i => {
-        const refined = refineModel(i)
+      const seed = ladderSeed(escalation)
+      return withRetry({ retries, outputErrors, fatal }, async i => {
+        const refined = refineModel(seed + i)
         console.log('Use model request: ', refined.getName(), refined.lc_kwargs.model)
         const startedAt = Date.now()
         const { piece, result: collected } = await streamStructured(refined, msgs, innerSchema, toolName, action)

package/src/plugins/anthropic.ts

@@ -5,13 +5,68 @@ import type { MessageContent, MessageFieldWithRole } from '@langchain/core/messa
 import { ModelProvider, PromptBlock, StructuredMode } from '@owlmeans/llm-common'
 import type { CacheTtl } from '@owlmeans/llm-common'
 import type { LlmPlugin } from './types.js'
+import type { ModelConfig } from '../types.js'
 import { CHARS_PER_TOKEN, MAX_CACHE_BREAKPOINTS, MIN_CACHEABLE_TOKENS } from '../consts.js'
+import { resolveOutputCap } from '../utils/config.js'
 import { readConfig } from '../utils/config.js'
 import { escalateMaxTokens, isBadRequest, makeClientOptions } from './utils.js'
 
 /** Model-name prefix that supports prompt caching through `cache_control` markers. */
 const CACHEABLE_PREFIX = 'claude-'
 
+/**
+ * Model families that REJECT the sampling parameters — Claude 4.7 and later, and the whole
+ * 5 family. `temperature`, `top_p` and `top_k` were removed there, and sending any of them
+ * is a 400, not a silently ignored field. Matched with `startsWith`, so a dated snapshot
+ * (`claude-sonnet-5-20260114`) is covered by its base id.
+ *
+ * This is the Anthropic counterpart of the OpenAI plugin's `RESPONSES_API_PREFIXES`: the
+ * older models below the line (`claude-sonnet-4-6`, `claude-haiku-4-5`, and earlier) still
+ * accept sampling and still want the deterministic `temperature: 0` default.
+ */
+export const NO_SAMPLING_PREFIXES = [
+  'claude-fable-5',
+  'claude-mythos-5',
+  'claude-mythos-preview',
+  'claude-opus-5',
+  'claude-opus-4-8',
+  'claude-opus-4-7',
+  'claude-sonnet-5',
+]
+
+/** Whether this model id rejects `temperature`/`top_p`/`top_k`. */
+export const rejectsSampling = (model: string | undefined): boolean =>
+  model != null && NO_SAMPLING_PREFIXES.some(prefix => model.startsWith(prefix))
+
+/**
+ * Whether the request has to say, on the wire, that the model must not reason.
+ *
+ * The adaptive family reasons unless told otherwise: an absent `thinking` parameter means
+ * "adaptive", and langchain forwards the parameter only when a caller sets it — so a config
+ * that asks for no thinking is only honoured if the plugin sends `thinking: disabled` itself.
+ * Silent reasoning is what the request pays for twice: its tokens bill as output, and the
+ * summarised stream delivers them in bursts minutes apart, which an idle deadline reads as a
+ * dead connection and retries from scratch. Older models reason only when asked and get nothing.
+ */
+export const suppressesThinking = (config: Pick<ModelConfig, 'model' | 'disableThinking'>): boolean =>
+  config.disableThinking === true && rejectsSampling(config.model)
+
+/**
+ * The smallest output budget an always-reasoning model is given.
+ *
+ * The same models that took the sampling knobs away also think ADAPTIVELY unless the request
+ * turns it off (`disableThinking` → `thinking: disabled`, see `suppressesThinking`), and by
+ * default that thinking is not shown — it arrives as thinking blocks with empty text. Reasoning is billed against the same `max_tokens` as the answer, so a budget
+ * sized for the answer alone can be spent entirely on thinking: the response is a well-formed
+ * completion carrying no text at all, `stop_reason: "max_tokens"`, and every retry at the same
+ * budget draws from the same distribution.
+ *
+ * The floor buys room for the reasoning AND the answer. It is a floor, not an override — a preset
+ * asking for more keeps it — and it is clamped to what the provider accepts, so it can never turn
+ * a retryable empty answer into a 400.
+ */
+export const ADAPTIVE_MIN_MAX_TOKENS = 32_000
+
 export const ANTHROPIC_FAMILY = 'anthropic'
 
 type ContentBlock = Record<string, unknown>
@@ -91,19 +146,38 @@ export const anthropicPlugin: LlmPlugin = {
    */
   toolChoice: (toolName: string): unknown => ({ type: 'tool', name: toolName }),
 
+  suppressesThinking: config => suppressesThinking(config),
+
   build: ({ config, secret, callbacks }) => {
-    const model = config.model ??= 'claude-haiku-4-5-20251001'
+    const model = config.model ??= 'claude-haiku-4-5'
+    // Claude 4.7+ took the sampling knobs away: not "ignored", a 400. A configured
+    // `temperature` on such a model is a preset bug, and dropping it here is the only
+    // reading that keeps the call alive — there is nothing to translate it into.
+    const sampling = rejectsSampling(model)
+      ? {}
+      : {
+        // Neither knob set → pin temperature to 0 for determinism.
+        ...(config.temperature == null && config.topP == null ? { temperature: 0 } : {}),
+        ...(config.temperature != null ? { temperature: config.temperature } : {}),
+        ...(config.topP != null && config.temperature == null ? { topP: config.topP } : {}),
+      }
+    // Room for the reasoning these models always do, and for the answer after it.
+    const requested = config.maxTokens ?? 4096
+    const maxTokens = rejectsSampling(model)
+      ? Math.min(Math.max(requested, ADAPTIVE_MIN_MAX_TOKENS), resolveOutputCap(config))
+      : requested
+
     const cfg = {
       model,
       apiKey: secret,
-      // Neither knob set → pin temperature to 0 for determinism.
-      ...(config.temperature == null && config.topP == null ? { temperature: 0 } : {}),
-      maxTokens: config.maxTokens ?? 4096,
+      maxTokens,
       maxRetries: 5,
       metadata: { config },
       callbacks,
-      ...(config.temperature != null ? { temperature: config.temperature } : {}),
-      ...(config.topP != null && config.temperature == null ? { topP: config.topP } : {}),
+      ...sampling,
+      ...(suppressesThinking({ model, disableThinking: config.disableThinking })
+        ? { thinking: { type: 'disabled' as const } }
+        : {}),
       ...makeClientOptions({ headers: config.headers }),
     }
     // Anthropic rejects temperature and top_p together.
@@ -118,6 +192,15 @@ export const anthropicPlugin: LlmPlugin = {
     const model = base as ChatAnthropic
     const currentTemperature = temperature ?? model.temperature ?? 0
     const maxTokens = escalateMaxTokens(model.maxTokens, attempt, maxOutputCap)
+    // `lc_kwargs` carries whatever `build` put there, so a no-sampling model arrives clean;
+    // what has to be suppressed is the escalator's own re-application of a temperature.
+    if (rejectsSampling(model.modelName ?? model.model)) {
+      const cfg = { ...(model.lc_kwargs as Partial<ChatAnthropic>), maxTokens }
+      delete cfg.temperature
+      delete cfg.topP
+
+      return new ChatAnthropic(cfg as Partial<ChatAnthropic>)
+    }
     const cfg: Partial<ChatAnthropic> = {
       ...(model.lc_kwargs as Partial<ChatAnthropic>), temperature: currentTemperature, maxTokens,
     }

package/src/plugins/openai.ts

@@ -5,8 +5,20 @@ import type { LlmPlugin, LlmRefineParams } from './types.js'
 import type { ModelConfig } from '../types.js'
 import { escalateMaxTokens, isBadRequest, makeConfiguration } from './utils.js'
 
-/** Model families served through OpenAI's Responses API rather than chat completions. */
-const RESPONSES_API_PREFIXES = ['gpt-5', 'codex-']
+/**
+ * Model families served through OpenAI's Responses API rather than chat completions. That
+ * endpoint REJECTS `temperature`/`top_p` — a 400 naming the parameter, not a silently
+ * ignored field. Matched with `startsWith`, so a dated snapshot (`gpt-5.6-terra-2026-08`)
+ * is covered by its base id.
+ *
+ * This is the OpenAI counterpart of the anthropic plugin's `NO_SAMPLING_PREFIXES`, and it
+ * gates BOTH hooks for the same reason: see `refine`.
+ */
+export const RESPONSES_API_PREFIXES = ['gpt-5', 'codex-']
+
+/** Whether this model id goes through the Responses API and therefore rejects sampling. */
+export const usesResponsesApi = (model: string | undefined): boolean =>
+  model != null && RESPONSES_API_PREFIXES.some(prefix => model.startsWith(prefix))
 
 export const OPENAI_FAMILY = 'openai'
 
@@ -52,6 +64,8 @@ export const openAiFamily = {
     const baseKwargs = model.lc_kwargs as ConstructorParameters<typeof ChatOpenAI>[0] & {
       modelKwargs?: { reasoning?: { max_tokens?: number } } & Record<string, unknown>
     }
+    const responsesApi = usesResponsesApi(model.model ?? baseKwargs.model)
+      || baseKwargs.useResponsesApi === true
     // The dominant cause of an empty response is a reasoning model spending the whole
     // budget on hidden thinking (finish_reason=length, empty content). The retry already
     // raises maxTokens; ALSO shrink the absolute reasoning cap so the extra budget becomes
@@ -65,6 +79,22 @@ export const openAiFamily = {
       }
       : baseKwargs.modelKwargs
 
+    // `build` hands a Responses-API model over without sampling knobs, but EVERY call is
+    // made on the instance `refine` returns — attempt 0 included — so re-applying a
+    // temperature here puts it on the wire for every single request, not just a retry.
+    // Suppressing it in one hook and restoring it in the other ships the parameter anyway.
+    if (responsesApi) {
+      const cfg = {
+        ...baseKwargs,
+        maxTokens,
+        ...(modelKwargs != null ? { modelKwargs } : {}),
+      }
+      delete cfg.temperature
+      delete cfg.topP
+
+      return new ChatOpenAI(cfg)
+    }
+
     return new ChatOpenAI({
       ...baseKwargs,
       temperature: currentTemperature,
@@ -104,7 +134,7 @@ export const openAiPlugin: LlmPlugin = {
     const modelKwargs = { prompt_cache_key: config.cacheKey ?? alias }
 
     // The Responses API models reject `temperature`/`topP`.
-    if (RESPONSES_API_PREFIXES.some(prefix => model.startsWith(prefix))) {
+    if (usesResponsesApi(model)) {
       return new ChatOpenAI({
         model,
         apiKey: secret,

package/src/plugins/types.ts

@@ -93,6 +93,14 @@ export interface LlmPlugin {
    */
   refine: (params: LlmRefineParams) => BaseChatModel
 
+  /**
+   * Does this plugin turn the model's reasoning off NATIVELY when the config asks for it
+   * (`ModelConfig.disableThinking`)? When it does, the service must not also inject the
+   * `/no_think` prompt directive — that is a soft switch for models with no request-level
+   * control, and on a provider that has one it is nothing but text in the prompt.
+   */
+  suppressesThinking?: (config: Pick<ModelConfig, 'model' | 'disableThinking'>) => boolean
+
   /** How this provider should be asked for schema-conforming output. */
   structuredMode: (config: ModelConfig) => StructuredMode
 

package/src/prompt/service.ts

@@ -105,6 +105,10 @@ export const promptServiceApi = (
 
     compose: async (input, messages, params): Promise<PromptResult> => {
       const sections = new Map<PromptBlock, string[]>()
+      // Scoped to this composition, never to the service: a claim is about who renders a
+      // thing in ONE prompt, and carrying it across calls would silently drop the content
+      // from every later prompt that shares the service.
+      const claimed = new Set<string>()
       const ctx: PromptContext = {
         ...params,
         input,
@@ -122,6 +126,14 @@ export const promptServiceApi = (
           }
         },
         resolve: aliases => self().resolve(aliases),
+        claim: key => {
+          if (claimed.has(key)) {
+            return false
+          }
+          claimed.add(key)
+
+          return true
+        },
       }
 
       // Two passes, not one: every static contribution must be in place before a plugin

package/src/prompt/types.ts

@@ -36,6 +36,16 @@ export interface PromptComposeParams {
   cacheMax?: number
   /** File access a plugin may use to resolve knowledge from disk. */
   files?: FileProviderRef
+  /**
+   * A cheap model a plugin may spend ONE call on while composing — picking which of a
+   * hundred candidate skills a request is actually about, classifying an ask. Resolved
+   * lazily and allowed to yield `undefined`: no cheap tier is configured on most
+   * deployments, and a plugin that cannot get one must degrade rather than fail.
+   *
+   * Whatever it returns must not change what lands in a CACHED block — a model's answer
+   * is not reproducible byte-for-byte, so it belongs in `Packages` or `Context`.
+   */
+  utility?: () => BaseChatModel | undefined
 }
 
 /** What a prompt plugin sees and may contribute to. */
@@ -47,6 +57,16 @@ export interface PromptContext extends PromptComposeParams {
   add: (block: PromptBlock, text: string) => void
   /** Resolve skill aliases through the registry, following `requires`. */
   resolve: (aliases: readonly string[]) => SkillDefinition[]
+  /**
+   * Take exclusive ownership of `key` for THIS composition: the first caller gets `true`,
+   * every later one `false`. Two plugins that can each render the same skill — a static
+   * catalogue and a detector — would otherwise emit it twice, which costs tokens and
+   * tells the model the same thing in two voices.
+   *
+   * The claim set is per `compose` call and consulted by nobody else, so a composition
+   * where no plugin claims renders exactly the bytes it rendered before this seam existed.
+   */
+  claim: (key: string) => boolean
 }
 
 /**

package/src/service.ts

@@ -38,11 +38,39 @@ export const llmServiceApi = (options: LlmServiceOptions, self: () => LlmService
     })
   }
 
+  /** A named alias's config, ready to be layered under something else. */
+  const presetOf = (
+    models: ModelConfig[], name: string | undefined
+  ): Partial<ModelConfig> => {
+    if (name == null) return {}
+    const { alias: _alias, ...rest } = { ...(models.find(m => m.alias === name) ?? {}) }
+    return rest
+  }
+
+  /**
+   * Drop keys that are present but `undefined` — they must not shadow a layer below.
+   * `mergeOverride` in the execution layer strips these already; a hand-built override
+   * need not.
+   */
+  const defined = (config: Partial<ModelConfig>): Partial<ModelConfig> =>
+    Object.fromEntries(
+      Object.entries(config).filter(([, value]) => value !== undefined)
+    ) as Partial<ModelConfig>
+
   /**
    * Resolve `alias` → config (inheriting a `preset`, applying `override`) and build it.
    * A declared `fallback` is built as well and attached to the primary as a
    * non-enumerable `__fallbackModel`, which the model's retry escalator reads. The
    * fallback spec is merged OVER the primary config, so it inherits secret/headers.
+   *
+   * Four layers, lowest first — the alias's own preset, the alias, the override's preset,
+   * the override. A `preset` is a BASE that its referent refines, so it has to sit under
+   * the config naming it; the previous order assigned it last, which meant a role
+   * declaring `preset:` silently discarded both its own fields and the caller's override —
+   * effort-tier token caps and `temperatureFactory`'s temperature among them. An override
+   * naming a preset (how the execution layer delivers a `modelOverrides` string pin) still
+   * outranks the alias, because picking a different model is a stronger statement than the
+   * role's default; explicit override fields stay on top of everything.
    */
   const createModel = (alias: string, override: Partial<ModelConfig> = {}): BaseChatModel => {
     const models = options.models()
@@ -50,17 +78,35 @@ export const llmServiceApi = (options: LlmServiceOptions, self: () => LlmService
     if (baseConfig == null) {
       throw new LlmMissconfiguredError(alias)
     }
-    const config: ModelConfig = { ...baseConfig, ...override }
+    const config: ModelConfig = {
+      ...presetOf(models, baseConfig.preset),
+      ...defined(baseConfig),
+      ...presetOf(models, override.preset),
+      ...defined(override),
+      alias: baseConfig.alias,
+    }
     // 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: Partial<ModelConfig> = config.preset != null
-      ? { ...(models.find(m => m.alias === config.preset) ?? {}) }
-      : {}
-    if (preset.alias != null) {
-      delete preset.alias
+
+    // What the provider accepts bounds what we may ask for. A preset that over-declares is
+    // corrected here rather than at the provider, where it surfaces as a fatal 400 on the
+    // one call that finally escalated far enough to exceed the limit.
+    if (config.maxOutput != null && config.maxOutput > 0) {
+      if (config.maxTokensCap != null && config.maxTokensCap > config.maxOutput) {
+        console.warn(
+          `Model "${alias}" declares maxTokensCap ${config.maxTokensCap} above the provider's`
+          + ` maxOutput ${config.maxOutput}; the escalator will stop at ${config.maxOutput}.`
+        )
+      }
+      if (config.maxTokens != null && config.maxTokens > config.maxOutput) {
+        console.warn(
+          `Model "${alias}" declares maxTokens ${config.maxTokens} above the provider's`
+          + ` maxOutput ${config.maxOutput}; clamping.`
+        )
+        config.maxTokens = config.maxOutput
+      }
     }
-    Object.assign(config, preset)
 
     const { fallback, ...primaryConfig } = config
     const primary = buildModel(alias, primaryConfig)