@owlmeans/llm 0.1.18-rc.0 → 0.1.18-rc.10

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/llm",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.505Z",
+  "version": "0.1.18-rc.9",
+  "generatedAt": "2026-08-29T20:14:44.155Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/llm/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/llm
 
 **Layer:** Core
-**Install:** `"@owlmeans/llm": "^0.1.18-rc.0"` in `dependencies` (plus the `@langchain/*` peers)
+**Install:** `"@owlmeans/llm": "^0.1.18-rc.9"` in `dependencies` (plus the `@langchain/*` peers)
 
 The inference runtime. Everything provider-specific is a **plugin**; the model itself only
 owns the provider-independent parts (streaming discipline, retries, validation,
@@ -21,7 +21,7 @@ observability). Serializable contracts live in `@owlmeans/llm-common`.
 | `makeLlmModel(options, spectator)` | The four-method model: `ask` / `talk` / `invoke` / `request`. |
 | `makeLlmService(options, alias?)` · `appendLlmService(ctx, options, alias?)` | Model factory/registry — resolves a `ModelConfig` by alias, memoized per alias+override. |
 | `llmServiceApi(options, self)` | The factory half WITHOUT `createService`, to compose into your own service (role accessors, domain helpers). |
-| `makeExecutionService(alias?, options?)` · `appendExecutionService(ctx, alias?, options?)` | Frozen 3-level executions + policy resolution + snapshot/restore/checkpoint. |
+| `makeExecutionService(alias?, options?)` · `appendExecutionService(ctx, alias?, options?)` | Frozen 3-level executions + policy resolution + snapshot/restore/checkpoint + advice. |
 | `makePromptService(options?, alias?)` · `appendPromptService(ctx, options?, alias?)` · `promptServiceApi(options, self)` | Skill registry + the composition plugin chain. Also at `@owlmeans/llm/prompt`. |
 | `rolePlugin`, `skillsPlugin`, `contextPlugin`, `BUILT_IN_PROMPT_PLUGINS` | The built-in composition plugins. |
 | `renderSkill`, `sortSkills`, `joinChunks`, `compareAlias`, `prefixHash` | Deterministic rendering primitives — reuse them, never re-implement. |
@@ -29,6 +29,8 @@ observability). Serializable contracts live in `@owlmeans/llm-common`.
 | `executionServiceApi(options, self)` | The execution half without `createService`, for the same composition pattern. |
 | `plugins`, `registerLlmPlugin`, `resolvePlugin`, `pluginOf`, `pluginFor` | The provider-plugin registry. Also at `@owlmeans/llm/plugins`. |
 | `anthropicPlugin`, `openAiPlugin`, `compatiblePlugin`, `openAiFamily` | Built-in providers; `openAiFamily` is the shared OpenAI-client behaviour to spread into a new plugin. |
+| `NO_SAMPLING_PREFIXES`, `rejectsSampling(model)` | Which Claude families reject `temperature`/`top_p`/`top_k` (4.7+ and the 5 family). Consumers pin presets against it. |
+| `RESPONSES_API_PREFIXES`, `usesResponsesApi(model)` | Which OpenAI families go through the Responses API and therefore reject `temperature`/`top_p` (`gpt-5*`, `codex-*`). The OpenAI counterpart of the pair above; consumers pin presets against it. |
 | `withRetry`, `registerFatalError`, `spectate`, `normalizeInput`, `parseJsonContent`, `coerceToSchema` | Helpers usable alongside a model. Also at `@owlmeans/llm/helpers`. |
 | `LlmError`, `LlmModelError`, `LlmMissconfiguredError`, `LlmPluginError`, `LlmRetryExceededError` | `ResilientError` family. `LlmModelError` is the RETRYABLE one. |
 | `mergePrompt`, `mergePolicy`, `resolveRole`, `effortPatch` | Execution merge helpers; `mergePrompt` unions skills and takes the deepest role. |
@@ -60,6 +62,32 @@ Adding a function? Decide which side it belongs to first, then place it. Do not
 | `cacheKey` (via `ModelConfig.cacheKey`) | provider cache-routing hints such as OpenAI's `prompt_cache_key` |
 | `isFatal` | "this error can never be retried" |
 
+### A provider that removes a parameter is a plugin concern too
+
+`build` is not the only place a parameter reaches the wire, and `refine` is not only a retry
+hook — **every** call is made on the instance `refine` returns, attempt 0 included. A knob
+suppressed in `build` and re-applied in `refine` therefore ships on every single request, not
+on a retry: an unsupported `temperature` restored there 400s the model's whole family on the
+first call, and `isFatal` correctly refuses to retry it, so the failure is immediate and total.
+
+Both built-in plugins gate their rejected parameters in **both** hooks, through a predicate the
+package root exports:
+
+| Family | Rejects | Predicate |
+|---|---|---|
+| Claude 4.7+ and the 5 family | `temperature`, `top_p`, `top_k` | `NO_SAMPLING_PREFIXES` / `rejectsSampling(model)` |
+| OpenAI Responses API (`gpt-5*`, `codex-*`) | `temperature`, `top_p` | `RESPONSES_API_PREFIXES` / `usesResponsesApi(model)` |
+
+Models below those lines keep the deterministic `temperature: 0` default. `refine` reads the
+id off the ACTIVE base (`model.model ?? lc_kwargs.model`), so a same-family `fallback` rung is
+judged on its own id rather than the primary's, and the OpenAI check also accepts a
+`useResponsesApi` already on `lc_kwargs`.
+
+Export the predicate rather than keeping it private: consumers pin presets against it
+(`viable-agent`'s `tests/presets.test.ts` asserts no preset entry declares a parameter its
+model rejects), and a second hand-written copy of the list drifts exactly when a new family is
+added — the moment it has to be right.
+
 **Registration order is load-bearing.** Instance-based lookup (`pluginFor`) returns the
 FIRST plugin whose `owns` matches. `compatible` is registered before `openai` because both
 build a `ChatOpenAI`, and assuming the tool-calling hack for an unlabelled model is safe
@@ -102,6 +130,23 @@ inherited method signatures**, which would be a contravariance error.
 `snapshot` excludes `state` itself; without that, every `derive`/`escalate`/`withPurpose`
 on a task would nest another copy of the previous state.
 
+`forHelper` also accepts `output` — an initial `maxTokens` for a helper whose one answer is
+genuinely large (a whole source file rather than a decision). It is a model selector, not a
+field the helper carries: it becomes a call override, is clamped to `maxOutput`, doubles from
+there under retry, and survives `temperatureFactory`.
+
+### The plugin seam has two hooks, dispatched independently
+
+`ExecutionPlugin` carries `onCheckpoint`/`onRestore` (persist and resume an
+`ExecutionState`) and `advise` (answer a performer's question about the project it is
+working in — `ExecutionService.advise(exec, request)`, first usable answer wins, a throwing
+plugin is skipped, `null` when nobody answers). Advice is advisory by contract: a caller
+appends whatever comes back and proceeds unchanged on `null`.
+
+`checkpoint` dispatches on plugins that declare **`onCheckpoint`**, not on the plugin count —
+otherwise registering an advise-only plugin would silently start composing snapshots nobody
+consumes.
+
 ## Classify a provider error by walking `cause`, never by `instanceof` or a surface read
 
 Two independent layers hide the wire shape of a provider failure, and each one alone is
@@ -162,10 +207,70 @@ Note what this does NOT bound: a call that keeps streaming forever, and retries.
 error misclassified as retryable multiplies its own latency by `DEFAULT_MODEL_RETRIES` —
 see the `instanceof` trap above.
 
+## An outer validation loop must pass its attempt in
+
+A caller that validates the OUTPUT — a diff that has to apply, a file that must not come
+back truncated — runs its own retry loop around whole `ask` calls. Every one of those calls
+starts a FRESH inner loop at attempt 0, so the escalator's two rungs never move: same model,
+same output budget, same deterministic answer, N times. Pass `escalation: <outer attempt>`
+in `LlmCallOptions` and the per-call escalator starts that far up its ladder instead —
+`maxTokens` doubling and the `FALLBACK_AFTER_ATTEMPTS` switch to `ModelConfig.fallback` both
+advance. It is clamped to `retries - 1`, moves the STARTING rung only, and never changes how
+many attempts the call itself makes.
+
+Two things this depends on, and both are preset data rather than code: the role must
+actually declare a `fallback`, and that fallback must be in the same plugin `family` (a
+cross-family one is skipped with a warning, because switching provider mid-call flips the
+structured-output shape).
+
+`LlmCallOptions.fatal` is the matching lever in the other direction — a per-call resolver
+consulted before the global ones and the plugin's `isFatal`, for an error the caller knows
+no retry can fix.
+
+## Output caps: what the deployment wants vs what the provider allows
+
+Four fields, and conflating them is what turns an escalation into a fatal 400 hours into a
+run:
+
+| Field | Means |
+|---|---|
+| `maxTokens` | the budget asked for on the FIRST attempt |
+| `maxTokensCap` | the ceiling the deployment budgets for the escalator |
+| `maxOutput` | what the PROVIDER accepts in one request — a fact about the model |
+| `contextWindow` | total window (input + output); informational, never sent |
+
+`resolveOutputCap` (`utils/config.ts`) is the one place that reconciles them: the declared
+cap chooses the ceiling and the capability trims it, and `DEFAULT_MAX_OUTPUT_CAP` applies
+only when neither is stated. `createModel` additionally clamps `maxTokens` to `maxOutput`
+and warns about a cap above it. For an aggregated model `maxOutput` is the limit of the
+`inferenceProvider` actually pinned, which is often far below what the model can do
+elsewhere. `combinedWindow: true` marks a model whose window is shared between input and
+output (MiniMax M2.x, gpt-oss) — nothing enforces it at runtime; it keeps presets honest
+about leaving room for the prompt.
+
+**A `fallback` that changes `model` must restate `contextWindow`/`maxOutput`** (and reset
+`combinedWindow`): the fallback config is `{...primaryConfig, ...fallback}`, so every field
+the patch does not name is inherited from a different model.
+
+## Config precedence: a preset is a base, not a final word
+
+`createModel` layers four sources, lowest first:
+
+    presetOf(base.preset)  <  base  <  presetOf(override.preset)  <  override
+
+A `preset` is a BASE that its referent refines, so it sits UNDER the config naming it.
+Assigning it last — as this did until the layering was fixed — meant a role declaring
+`preset:` silently discarded both its own fields and the caller's override, which is how
+effort-tier token caps and `temperatureFactory`'s temperature vanished for preset-based
+roles. An override naming a preset (how the execution layer delivers a `modelOverrides`
+string pin) outranks the alias but still yields to explicit override fields. Resolution is
+ONE level deep: a preset meant to carry a model must name one.
+
 ## Resilience already handled — do not reimplement
 
 Idle stream deadline · duplicate-final-chunk dedup · output-budget escalation · reasoning-cap
-shrink · same-family fallback model · schema coercion · JSON salvage from prose · `NullCapture`
+shrink · same-family fallback model · caller-seeded ladder position (`escalation`) · schema
+coercion · JSON salvage from prose · `NullCapture`
 diagnostics · fatal-error short-circuit · blank-content sanitization (whitespace-only text
 blocks are dropped before every call — a blank block, e.g. an empty file read pasted into a
 prompt, is otherwise a fatal Anthropic 400; blank tool results are stubbed to keep their

package/build/execution/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/execution/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKlE,OAAO,KAAK,EACkB,gBAAgB,EAAE,uBAAuB,EAAE,cAAc,EACrD,oBAAoB,EACrD,MAAM,YAAY,CAAA;AAMnB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,cAAc,GAAG,cAAc,WAClE,uBAAuB,QAC1B,MAAM,gBAAgB,CAAC,CAAC,CAAC,KAC9B,gBAAgB,CAAC,CAAC,CAkIpB,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,CAAC,SAAS,cAAc,GAAG,cAAc,UACrE,MAAM,YACJ,uBAAuB,KAC/B,gBAAgB,CAAC,CAAC,CAMpB,CAAA;AAED,eAAO,MAAM,sBAAsB,GACjC,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,cAAc,GAAG,cAAc,OAEtF,CAAC,UACC,MAAM,YACJ,uBAAuB,KAC/B,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAQ5B,CAAA"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/execution/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKlE,OAAO,KAAK,EACkB,gBAAgB,EAAE,uBAAuB,EAAE,cAAc,EACrD,oBAAoB,EACrD,MAAM,YAAY,CAAA;AAMnB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,cAAc,GAAG,cAAc,WAClE,uBAAuB,QAC1B,MAAM,gBAAgB,CAAC,CAAC,CAAC,KAC9B,gBAAgB,CAAC,CAAC,CA2JpB,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,CAAC,SAAS,cAAc,GAAG,cAAc,UACrE,MAAM,YACJ,uBAAuB,KAC/B,gBAAgB,CAAC,CAAC,CAMpB,CAAA;AAED,eAAO,MAAM,sBAAsB,GACjC,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,cAAc,GAAG,cAAc,OAEtF,CAAC,UACC,MAAM,YACJ,uBAAuB,KAC/B,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAQ5B,CAAA"}

package/build/execution/service.js

@@ -61,10 +61,13 @@ export const executionServiceApi = (options, self) => {
             return freeze(taskExec);
         },
         forHelper: (parent, input) => {
-            const { role, effort, dedication, prompt, ...extras } = input;
+            const { role, effort, dedication, prompt, output, ...extras } = input;
             const localPolicy = effort != null ? mergePolicy(parent.policy, { effort }) : parent.policy;
             const scoped = { ...parent, policy: localPolicy };
             const merged = mergePrompt(parent.prompt, prompt);
+            // Destructured out of `extras` deliberately: `output` selects a model budget, it is
+            // not a field the helper carries around.
+            const sizing = output != null ? { maxTokens: output } : undefined;
             const helperExec = {
                 ...parent,
                 ...extras,
@@ -75,8 +78,8 @@ export const executionServiceApi = (options, self) => {
                 policy: localPolicy,
                 ...(merged != null ? { prompt: merged } : {}),
                 role: resolveRole(localPolicy, role),
-                model: self().model(scoped, role),
-                temperatureFactory: self().temperatureFactory(scoped, role),
+                model: self().model(scoped, role, sizing),
+                temperatureFactory: self().temperatureFactory(scoped, role, sizing),
             };
             // A helper is not resumable — drop a parent task's composed state.
             delete helperExec.state;
@@ -93,7 +96,10 @@ export const executionServiceApi = (options, self) => {
             const clean = Object.fromEntries(Object.entries(merged).filter(([, value]) => value !== undefined));
             return exec.models().getModel(effectiveRole, clean);
         },
-        temperatureFactory: (exec, role) => temperature => self().model(exec, role, {
+        temperatureFactory: (exec, role, baseOverride) => temperature => self().model(exec, role, {
+            // A budget the helper was built with survives a temperature refinement — the
+            // work is the same size whether or not it is being retried creatively.
+            ...(typeof baseOverride === 'object' ? baseOverride : {}),
             ...(temperature != null ? { temperature } : {}),
             ...(temperature != null && temperature > 0.2 ? { topP: 0.8 } : {}),
         }),
@@ -101,12 +107,31 @@ export const executionServiceApi = (options, self) => {
             plugins.push(plugin);
         },
         checkpoint: async (exec, key) => {
-            if (plugins.length === 0) {
+            // Guarded on the HOOK, not on the plugin count: a plugin registered for `advise`
+            // alone must not make checkpointing start composing snapshots nobody consumes.
+            if (!plugins.some(plugin => plugin.onCheckpoint != null)) {
                 return;
             }
             const state = self().snapshot(exec);
             await Promise.all(plugins.map(plugin => plugin.onCheckpoint?.(state, exec, key)));
         },
+        advise: async (exec, request) => {
+            for (const plugin of plugins) {
+                if (plugin.advise == null)
+                    continue;
+                try {
+                    const advice = await plugin.advise(exec, request);
+                    if (advice != null && advice.trim() !== '') {
+                        return advice;
+                    }
+                }
+                catch (e) {
+                    // Advice is an optimization. A broken advisor must never take the work with it.
+                    console.warn(`Execution advisor failed for "${request.kind}":`, e);
+                }
+            }
+            return null;
+        },
         snapshot: exec => {
             if (exec.level === ExecutionLevel.Task) {
                 return freeze({ ...exec.state });

package/build/execution/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/execution/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAMnE,OAAO,EACL,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EACnF,WAAW,EAAE,WAAW,GACzB,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,OAAgC,EAChC,IAA+B,EACV,EAAE;IACvB,MAAM,OAAO,GAAsB,EAAE,CAAA;IACrC,MAAM,gBAAgB,GAAG,CAAC,GAAG,iBAAiB,EAAE,GAAG,CAAC,OAAO,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,CAAA;IAEpF,8EAA8E;IAC9E,MAAM,SAAS,GAAG,CAAsB,IAAO,EAAK,EAAE;QACpD,IAAI,IAAI,CAAC,KAAK,KAAK,cAAc,CAAC,IAAI,EAAE,CAAC;YACvC,MAAM,IAAI,GAAG,IAAgC,CAC5C;YAAC,IAAsC,CAAC,KAAK,GAAG,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAA;QAC3F,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC,CAAA;IAED,MAAM,GAAG,GAAwB;QAE/B,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC;YACpB,GAAG,KAAK;YACR,KAAK,EAAE,cAAc,CAAC,OAAO;YAC7B,OAAO,EAAE,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE;YAC7B,MAAM,EAAE,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE;YAC3B,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAiB;QAElB,OAAO,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;YACzB,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,KAAK,CAAA;YACxD,MAAM,MAAM,GAAG,MAAM,IAAI,IAAI;gBAC3B,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC;gBACxC,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,CAAA;YACxB,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;YAEjD,gFAAgF;YAChF,6EAA6E;YAC7E,MAAM,QAAQ,GAAG;gBACf,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,EAAE,MAAM;gBACxF,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAClB,CAC5B;YAAC,QAA0C,CAAC,KAAK,GAAG,gBAAgB,CAAC;gBACpE,GAAG,QAAQ;gBACX,KAAK,EAAE;oBACL,KAAK,EAAE,cAAc,CAAC,IAAI;oBAC1B,OAAO,EAAE,QAAQ,CAAC,OAAO;oBACzB,MAAM,EAAE,QAAQ,CAAC,MAAM;oBACvB,KAAK;oBACL,IAAI;iBACiB;aACxB,EAAE,gBAAgB,CAAC,CAAA;YAEpB,OAAO,MAAM,CAAC,QAAQ,CAAc,CAAA;QACtC,CAAC;QAED,SAAS,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;YAC3B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,KAAK,CAAA;YAC7D,MAAM,WAAW,GAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAA;YAC3F,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,WAAW,EAAe,CAAA;YAC9D,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;YAEjD,MAAM,UAAU,GAAG;gBACjB,GAAG,MAAM;gBACT,GAAG,MAAM;gBACT,KAAK,EAAE,cAAc,CAAC,MAAM;gBAC5B,OAAO,EAAE,UAAU,IAAI,IAAI;oBACzB,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE;oBACnC,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE;gBACzB,MAAM,EAAE,WAAW;gBACnB,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7C,IAAI,EAAE,WAAW,CAAC,WAAW,EAAE,IAAI,CAAC;gBACpC,KAAK,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC;gBACjC,kBAAkB,EAAE,IAAI,EAAE,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC;aAC9B,CAAA;YAC/B,mEAAmE;YACnE,OAAQ,UAAkC,CAAC,KAAK,CAAA;YAEhD,OAAO,MAAM,CAAC,UAAU,CAAgB,CAAA;QAC1C,CAAC;QAED,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QAEjE,WAAW,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAC3B,MAAM,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC;QAExE,QAAQ,EAAE,CAAC,IAAI,EAAE,KAA2B,EAAE,EAAE,CAC9C,MAAM,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QAEzE,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;YAC9B,MAAM,aAAa,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,IAAK,IAAwB,CAAC,IAAI,CAAC,CAAA;YACtF,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,aAAa,CAAC,CAAA;YAClE,MAAM,MAAM,GAAG,aAAa,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAA;YACvF,oEAAoE;YACpE,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAC9B,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CACjD,CAAA;YAElB,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC,CAAA;QACrD,CAAC;QAED,kBAAkB,EAAE,CAAC,IAAI,EAAE,IAAI,EAAsB,EAAE,CACrD,WAAW,CAAC,EAAE,CACZ,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE;YACvB,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,GAAG,CAAC,WAAW,IAAI,IAAI,IAAI,WAAW,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnE,CAAC;QAEN,GAAG,EAAE,MAAM,CAAC,EAAE;YACZ,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACtB,CAAC;QAED,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;YAC9B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAM;YACR,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;YACnC,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAA;QACnF,CAAC;QAED,QAAQ,EAAE,IAAI,CAAC,EAAE;YACf,IAAI,IAAI,CAAC,KAAK,KAAK,cAAc,CAAC,IAAI,EAAE,CAAC;gBACvC,OAAO,MAAM,CAAC,EAAE,GAAI,IAAiC,CAAC,KAAK,EAAE,CAAC,CAAA;YAChE,CAAC;YACD,OAAO,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAA;QACzD,CAAC;QAED,OAAO,EAAE,CAAC,KAAqB,EAAE,aAAa,GAAG,EAAwB,EAAE,EAAE,CAAC,MAAM,CAAC;YACnF,GAAG,KAAK;YACR,GAAG,aAAa;YAChB,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1D,CAAc;KAEO,CAAA;IAExB,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,KAAK,GAAW,iBAAiB,EACjC,OAAO,GAA4B,EAAE,EAChB,EAAE;IACvB,MAAM,OAAO,GAAwB,aAAa,CAChD,KAAK,EAAE,mBAAmB,CAAI,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAwB,CAC7E,CAAA;IAED,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAGpC,GAAM,EACN,KAAK,GAAW,iBAAiB,EACjC,OAAO,GAA4B,EAAE,EACR,EAAE;IAC/B,MAAM,OAAO,GAAG,GAAkC,CAAA;IAElD,OAAO,CAAC,eAAe,CAAC,oBAAoB,CAAI,KAAK,EAAE,OAAO,CAAC,CAAC,CAAA;IAEhE,OAAO,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAsB,KAAK,CAAC,CAAA;IAEtE,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/execution/service.ts"],"names":[],"mappings":"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"}

package/build/execution/types.d.ts

@@ -69,6 +69,16 @@ export interface HelperExecutionInput {
     prompt?: PromptPolicy;
     /** Refines `purpose.dedication`. */
     dedication?: string;
+    /**
+     * Initial output-token budget for this helper's model (`ModelConfig.maxTokens`), for
+     * work whose ONE answer is genuinely large — a whole source file rather than a decision.
+     *
+     * The role's preset value sizes the common case; a helper that routinely needs more
+     * would otherwise spend its first attempt producing a truncated answer and only reach a
+     * workable budget through the retry escalator, which doubles from this number. Clamped
+     * to the provider's `maxOutput` and preserved across `temperatureFactory`.
+     */
+    output?: number;
 }
 /** Collaborators re-attached to a state that was restored from storage. */
 export interface RestoreCollaborators {
@@ -77,16 +87,35 @@ export interface RestoreCollaborators {
     files?: FileProviderRef;
 }
 /**
- * Resilience extension seam. A plugin observes flow boundaries (via
+ * What a performer wants to know before it acts. Runtime-only — never snapshotted, so it
+ * carries whatever the advisor and its callers agree on.
+ */
+export interface AdviceRequest {
+    /** Which advisor is being asked; an advisor that does not own this kind returns null. */
+    kind: string;
+    /** The work at hand, in the caller's own words — normally the assignment text. */
+    task: string;
+    /** Anything that narrows the answer (a subproject, a path prefix, an entity). */
+    hints?: Record<string, unknown>;
+}
+/**
+ * Extension seam. A plugin observes flow boundaries (via
  * {@link ExecutionService.checkpoint}) and can persist/enqueue the JSON-safe
- * {@link ExecutionState}, or supply one back on resume. This package ships NO concrete
- * implementation — with no plugin registered, `checkpoint` is a no-op.
+ * {@link ExecutionState}, or supply one back on resume; it may also ANSWER a performer's
+ * question about its surroundings (`advise`). This package ships NO concrete
+ * implementation — with no plugin registered, both seams are no-ops.
  */
 export interface ExecutionPlugin {
     /** Fired at a flow boundary with a JSON-safe snapshot; persist/enqueue as desired. */
     onCheckpoint?: (state: ExecutionState, exec: Execution, key?: string) => Promise<void>;
     /** Resume hook: return a previously persisted state for `key`, or `null`. */
     onRestore?: (key: string) => Promise<ExecutionState | null>;
+    /**
+     * Answer a performer's question about the project it is working in. Return the text to
+     * hand the model, or `null` when this plugin does not own the request's `kind` — or
+     * cannot answer it. Advice is advisory: a `null` never blocks the work.
+     */
+    advise?: (exec: Execution, request: AdviceRequest) => Promise<string | null>;
 }
 /**
  * The set of domain types an {@link ExecutionService} works with. A consumer declares
@@ -117,13 +146,25 @@ export interface ExecutionService<S extends ExecutionShape = ExecutionShape> ext
     withPurpose: <E extends S['exec']>(exec: E, patch: Partial<S['purpose']>) => E;
     escalate: <E extends S['exec']>(exec: E, patch: Partial<ModelPolicy>) => E;
     model: (exec: S['exec'], role?: ModelRole, override?: ModelConfigOverride) => BaseChatModel;
-    temperatureFactory: (exec: S['exec'], role?: ModelRole) => TemperatureFactory;
-    /** Register a resilience plugin (checkpoint/resume). No-op seam until one is provided. */
+    /**
+     * A factory that re-resolves the same role at another temperature. `baseOverride` is
+     * layered UNDER the temperature patch, so a caller-chosen budget (see
+     * `HelperExecutionInput.output`) survives the refinement.
+     */
+    temperatureFactory: (exec: S['exec'], role?: ModelRole, baseOverride?: ModelConfigOverride) => TemperatureFactory;
+    /** Register an execution plugin (checkpoint/resume, advice). No-op seam until provided. */
     use: (plugin: ExecutionPlugin) => void;
     /** Snapshot `exec` and dispatch it to every registered plugin. No-op if none. */
     checkpoint: (exec: S['exec'], key?: string) => Promise<void>;
     snapshot: (exec: S['exec']) => ExecutionState;
     restore: (state: ExecutionState, collaborators?: S['collaborators']) => S['exec'];
+    /**
+     * Ask the registered plugins about the project this execution runs in. Plugins are
+     * consulted in registration order and the FIRST usable answer wins, so one advisor owns
+     * each `kind` rather than several concatenating half-answers. Never throws: a plugin
+     * that fails is skipped, and `null` means nobody answered.
+     */
+    advise: (exec: S['exec'], request: AdviceRequest) => Promise<string | null>;
 }
 export interface ExecutionServiceOptions {
     /**

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

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

package/build/helpers/spectate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spectate.d.ts","sourceRoot":"","sources":["../../src/helpers/spectate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAe,MAAM,0BAA0B,CAAA;AAIjE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AA+B/D;;;GAGG;AACH,eAAO,MAAM,QAAQ,cAAe,YAAY,YAAY,MAAM,aAEvD,cAAc,EAAE,WACd,SAAS,UACV,MAAM,WACL,MAAM,cACH,MAAM,iEA+BnB,CAAA"}
+{"version":3,"file":"spectate.d.ts","sourceRoot":"","sources":["../../src/helpers/spectate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAe,MAAM,0BAA0B,CAAA;AAIjE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAwC/D;;;GAGG;AACH,eAAO,MAAM,QAAQ,cAAe,YAAY,YAAY,MAAM,aAEvD,cAAc,EAAE,WACd,SAAS,UACV,MAAM,WACL,MAAM,cACH,MAAM,iEA+BnB,CAAA"}

package/build/helpers/spectate.js

@@ -1,6 +1,13 @@
 import { BaseMessage } from '@langchain/core/messages';
 import { SpectatorContentType } from '@owlmeans/llm-common';
 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) => typeof content === 'string' ? content : JSON.stringify(content) ?? '';
 /** Normalize one prompt message into the spectator's storage shape. */
 const describeInput = (msg, callType) => {
     const entry = {
@@ -11,7 +18,7 @@ const describeInput = (msg, callType) => {
     };
     if (msg instanceof BaseMessage) {
         entry.type = msg.type;
-        entry.content = msg.content;
+        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 : undefined;
@@ -19,11 +26,11 @@ const describeInput = (msg, callType) => {
     }
     else if (typeof msg === 'object' && 'content' in msg) {
         entry.type = msg.role ?? 'unknown';
-        entry.content = msg.content ?? msg;
+        entry.content = asText(msg.content ?? msg);
         entry.raw = JSON.stringify(msg);
     }
     else {
-        entry.content = msg;
+        entry.content = asText(msg);
         entry.raw = JSON.stringify(msg);
     }
     return entry;
@@ -44,11 +51,11 @@ export const spectate = (spectator, callType) => async (input, message, action,
         raw: JSON.stringify({ message, content: message.content, meta: message.response_metadata }),
     };
     if (message.tool_calls != null && message.tool_calls.length > 0) {
-        completion.content = message.tool_calls;
+        completion.content = asText(message.tool_calls);
         completion.contentType = SpectatorContentType.ToolCall;
     }
     else {
-        completion.content = message.content;
+        completion.content = asText(message.content);
     }
     // Silent unless the provider reported cache activity, so it costs nothing when
     // caching is off — and is the one signal that tells a stable prefix from a broken one.

package/build/helpers/spectate.js.map

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

package/build/index.d.ts

@@ -8,7 +8,7 @@ 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';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,mBAAmB,CAAA;AACjC,mBAAmB,oBAAoB,CAAA;AACvC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACnG,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,mBAAmB,CAAA;AACjC,mBAAmB,oBAAoB,CAAA;AACvC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACnG,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACjH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EACL,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,GACpF,MAAM,qBAAqB,CAAA"}

package/build/index.js

@@ -6,7 +6,7 @@ export * from './helpers/index.js';
 export * from './execution/index.js';
 export * from './prompt/index.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';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAE3B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,mBAAmB,CAAA;AAEjC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACnG,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAE3B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,mBAAmB,CAAA;AAEjC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACnG,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACjH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EACL,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,GACpF,MAAM,qBAAqB,CAAA"}

package/build/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACuB,QAAQ,EAAE,eAAe,EAC1D,YAAY,EACb,MAAM,YAAY,CAAA;AA8CnB;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,oFAStB,eAAe,aAAa,YAAY,KAAG,QAwY7C,CAAA"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACuB,QAAQ,EAAE,eAAe,EAC1D,YAAY,EACb,MAAM,YAAY,CAAA;AA8CnB;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,oFAStB,eAAe,aAAa,YAAY,KAAG,QAma7C,CAAA"}

package/build/model.js

@@ -1,14 +1,14 @@
 import { Ajv } from 'ajv';
 import { AIMessage, BaseMessage } from '@langchain/core/messages';
 import { StructuredMode } from '@owlmeans/llm-common';
-import { DEFAULT_MAX_OUTPUT_CAP, DEFAULT_MODEL_RETRIES, FALLBACK_AFTER_ATTEMPTS, MAX_CACHE_BREAKPOINTS, } from './consts.js';
+import { DEFAULT_MODEL_RETRIES, FALLBACK_AFTER_ATTEMPTS, MAX_CACHE_BREAKPOINTS, } from './consts.js';
 import { LlmModelError } from './errors.js';
 import { pluginFor, pluginOf } from './plugins/index.js';
 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 { applyNoThink, dropBlankContent, ensureJsonMention, stripCacheMarkers } from './utils/prompt.js';
 import { resolveSchemaValidator, toToolName, unwrapNamed } from './utils/schema.js';
@@ -66,6 +66,15 @@ export const makeLlmModel = ({ model, outputErrors = false, captureNull = false,
     const config = readConfig(model);
     const plugin = 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) => 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.
@@ -158,9 +167,9 @@ export const makeLlmModel = ({ model, outputErrors = false, captureNull = false,
         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) {
             const maxTokens = refined.maxTokens;
@@ -220,10 +229,11 @@ export const makeLlmModel = ({ model, outputErrors = false, captureNull = false,
         return { piece, result, mode };
     };
     const helper = {
-        ask: async (input, { ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills }) => {
+        ask: async (input, { ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills, escalation, fatal, }) => {
             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 = null;
@@ -258,10 +268,11 @@ export const makeLlmModel = ({ model, outputErrors = false, captureNull = false,
                 return output;
             });
         },
-        talk: async (input, { ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills }) => {
+        talk: async (input, { ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills, escalation, fatal, }) => {
             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 = null;
@@ -285,12 +296,13 @@ export const makeLlmModel = ({ model, outputErrors = false, captureNull = false,
                 return message;
             });
         },
-        invoke: async (input, schema, { temperature, ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills }) => {
+        invoke: async (input, schema, { temperature, ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills, escalation, fatal, }) => {
             const msgs = await prepare(input, action, useCache, cacheMax, true, skills);
             const { name, innerSchema, validate } = resolveSchemaValidator(ajv, schema);
             const toolName = toToolName(innerSchema.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);
@@ -323,12 +335,13 @@ export const makeLlmModel = ({ model, outputErrors = false, captureNull = false,
                 return result;
             });
         },
-        request: async (input, schema, { ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills }) => {
+        request: async (input, schema, { ref, filter, action, useCache = false, cacheMax = MAX_CACHE_BREAKPOINTS, skills, escalation, fatal, }) => {
             const msgs = await prepare(input, action, useCache, cacheMax, true, skills);
             const { name, innerSchema, validate } = resolveSchemaValidator(ajv, schema);
             const toolName = toToolName(innerSchema.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);