@cubicecho/agent-core 2.21.0 → 2.22.0

package/README.md

@@ -36,7 +36,7 @@ only, Node >=22.
 | `continuation` | `continueTurn`: carries on an answer the token ceiling cut off, by prefilling it as a trailing assistant message. |
 | `config` | The structural interfaces every function here asks for. |
 | `run-turn` | `runTurn`: one turn with the retry loop around the negotiation around the stream. The whole loop, for a caller that wants it rather than its parts. Sizes the request against an opt-in `contextLimit`. |
-| `agent-loop` | `runAgentLoop`: the loop above a turn — `runTurn` per step, the tools between, `load_tools` and preselection handled, until the model stops asking. Plus the parts it is made of: `buildBody`, `preselect`, `preview`, and `resolveApiKey` for a caller deciding which key an endpoint gets. |
+| `agent-loop` | `runAgentLoop`: the loop above a turn — `runTurn` per step, the tools between, `load_tools` and preselection handled, until the model stops asking. Plus the parts it is made of: `buildBody`, `preselect`, `preview`, `resolveApiKey` for a caller deciding which key an endpoint gets, and `taskCall` for running a side task on the settings an agent spec gives it. |
 | `tool-calls` | Reading what a model meant by a tool call it did not write cleanly: `parseToolArguments` repairs almost-JSON arguments and says when they were cut off, `recoverToolCalls` finds calls written into the reply as text. |
 | `compaction` | Keeping a long run inside its window: `pruneToolResults` clears stale tool results, `planCompaction` and `compactTranscript` fold the oldest stretch into a summary. |
 | `ledger` | What stretches of a transcript cost, read off the prompt counts the server reported rather than estimated: `recordRequest`, `tokensBetween`, `estimateFrom`, `rebaseLedger`. |
@@ -279,15 +279,24 @@ const turn = await runTurn(client, supports, build, {
 });
 ```
 
-`contextLimitFor` answers the operator's number when there is one. Otherwise it asks for the window
-the server is actually serving the model in (`servedWindow`): llama.cpp's `/props`
-(`default_generation_settings.n_ctx`) and LM Studio's `/api/v0/models` (`loaded_context_length`).
-That differs from the trained window in the case the guard exists for, a 256k model started at `-c
-16384`. A server with neither route is latched and not asked again. Failing both, it reads the
-`/v1/models` listing: `max_model_len` from vLLM, `context_length` from OpenRouter, and llama.cpp's
-`meta.n_ctx_train`, which is only the trained window. Ollama reports no window on any route this
-reads, and truncates an over-long prompt rather than refusing it, so on Ollama pass `contextLength`
-or there is no guard at all.
+`contextLimitFor` answers the operator's number when there is one. Otherwise it reads the
+`/v1/models` listing first. A window at the top of the model's entry (`context_length`,
+`max_context_window`, `max_model_len`, `context_window` or `n_ctx`: vLLM's `max_model_len`,
+OpenRouter's `context_length`) is taken as the one being served, and nothing else is asked.
+
+Where the listing does not settle it, the server's own API is asked (`servedWindow`): llama.cpp's
+`/props` (`default_generation_settings.n_ctx`), then LM Studio's `/api/v0/models`
+(`loaded_context_length`). That covers a model listed with no window, which is LM Studio, and one
+listed with only `meta.n_ctx_train`, which is llama.cpp. The trained window differs from the served
+one in the case the guard exists for, a 256k model started at `-c 16384`, so it is used only when
+neither native route gives a number. A server with neither route is latched and not asked again.
+`/api/v0/models` is also dropped on its own: for the life of the process once it answers 404, 405
+or 501, and for `listingMissMs` after any other error.
+
+A top-level listing key is trusted without a second opinion, so on a server that puts a trained
+window there, pass `contextLength`. Ollama reports no window on any route this reads, and truncates
+an over-long prompt rather than refusing it, so on Ollama pass `contextLength` or there is no guard
+at all.
 
 What is weighed is the prompt plus the reply ceiling the body carries, under whichever spelling
 was chosen, because that is what the endpoint weighs: a 30k prompt into a 32k window with
@@ -555,7 +564,9 @@ have to score well below the ones it kept — a hit just under the line scoring
 one just over it means the ranking chose arbitrarily, which is the case a model is worth spending
 on. Matching nothing is not confident either, since the words cannot tell a request that needs no
 tools from one whose words are not in the catalogue. An empty `toolSelectModel` still means no
-preselection at all, words included.
+preselection at all, words included. `preselect` also takes a `temperature` and a
+`reasoningEffort`, read as `ask` reads them, and `runAgentLoop({ preselect: true })` makes the call
+itself — see "Its side tasks" below.
 
 A turn cut off at `maxTokens` is said so as a notice, and with `maxContinuations` above zero it is
 continued first. `continueTurn` is the same thing for a caller with its own loop:
@@ -1141,6 +1152,47 @@ a form can load it. Nothing in `src/` imports it — the same direction the conf
 what lets a document travel between hosts without the loop growing an opinion about where an agent
 comes from.
 
+### Its side tasks
+
+`tasks.<key>` configures a side task apart from the main model — its own model, endpoint, ceiling,
+temperature and reasoning effort — and resolution hands each back as a `ResolvedTask` holding only
+what a layer stated. `taskCall` turns one into the arguments `ask`, `askJson`, `summariser` and
+`preselect` already take, so a setting added to a task later arrives without the host's call
+changing:
+
+```ts
+const title = taskCall(config.tasks.title, { signal, onNotice }, config);
+const name = await ask(title.endpoint, title.model, "Name this chat.", firstMessage, title.options);
+```
+
+**An absent setting is the side task's own default, never the agent's.** A titler under an agent
+running at temperature 1.0 is still sent 0.3, and its ceiling is still `ask`'s 512, `summariser`'s
+1024 or `preselect`'s 256. What the task does state wins over the same field in the options beside
+it, so the options are where a host puts its own default for a task that names none. `maxTokens: 0`
+sends no ceiling, as it does on the main model.
+
+`reasoningEffort` is the one that reads differently from the main model's. A side task is sent the
+no-thinking hints by default, and absent or `"off"` keeps them; a level — `"low"`, `"high"` — is
+sent as `reasoning_effort` in their place, for a compaction model an operator pointed at a model
+that should deliberate.
+
+The third argument is the endpoint the main turn uses. Given it, a task on the same endpoint is
+sent the agent's spelling of the URL and, having no key of its own, the agent's key, so the two
+share one entry in `capabilitiesFor` and a refusal learned by either is known to both; a task on
+another endpoint is sent only a key of its own, as `resolveApiKey` has it.
+
+The loop reads two of them when asked to. `preselect: true` has `runAgentLoop` make the
+preselection itself with `tasks.toolSelect` — or with `toolSelectModel` on the agent's endpoint,
+which stays the flattened spelling for a host that is not on the spec — and `compact: true` has it
+fold the transcript before a step, once `planCompaction` says a `contextLength` window is filling,
+with `tasks.compaction` writing the summary and no falling back to the main model without it. Both
+are off by default: a host that already calls `preselect` or compacts in `beforeStep` is not sent
+a second request.
+
+```ts
+const result = await runAgentLoop({ config, preselect: { keywords: true }, compact: true, ... });
+```
+
 ## What is kept for the life of the process
 
 Four caches outlive any one run: the `OpenAI` clients, the model listings, the latched

package/dist/agent-loop.d.ts

@@ -1,10 +1,12 @@
 import type OpenAI from "openai";
 import { type Capabilities, type ModelCapabilities } from "./capabilities.ts";
 import type { CatalogServer } from "./catalog.ts";
+import { type CompactionOptions } from "./compaction.ts";
 import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from "./config.ts";
 import { type RunEventInput, type RunMetrics } from "./events.ts";
 import { type HookContext, type HookEvent, type HookNote, type HookRunner } from "./hooks.ts";
 import { type TokenLedger } from "./ledger.ts";
+import { type SideTask, type SideTaskOptions } from "./side-task.ts";
 import type { Turn, TurnUsage } from "./stream.ts";
 import { type KeywordPreselectOptions, type ToolOrder } from "./tool-loading.ts";
 /**
@@ -64,6 +66,38 @@ export declare function resolveApiKey(own: {
     baseUrl: string;
     apiKey?: string;
 }, env?: Record<string, string | undefined>): string;
+/**
+ * A side task's settings as the call that honours them: its endpoint, its model, and the options
+ * `ask`, `askJson`, `summariser` and `preselect` take last.
+ *
+ * A helper rather than a second signature on each of the four, so a setting added to a task later
+ * arrives through `options` without a host's call changing. What the task states wins over the
+ * same field in `options`: the host's code is written once and the task is what an operator
+ * configured over it, so a host passes its own ceiling as the value for a task that names none.
+ * A setting the task leaves out and `options` does too is absent from the result, which is what
+ * leaves it to the entry point's own default — 0.3, not the agent's temperature.
+ *
+ * A resolved spec carries no key, so a task on the agent's own endpoint would otherwise go out
+ * unkeyed, and be remembered under a second capability entry beside the agent's. Given `agent`,
+ * such a task is sent the agent's `baseUrl` as the agent spells it and, having no key of its own,
+ * the agent's key, so `capabilitiesFor` answers both with one object; a task on another endpoint
+ * is sent only a key of its own, as `resolveApiKey` has it. The environment is not read: the
+ * agent's key is whatever the main turn is sent.
+ *
+ * @param task The task, ordinarily `resolved.tasks.<key>`.
+ * @param options What the host adds — cancellation, notices, `keywords` — and its own defaults
+ * for the settings a task may leave out.
+ * @param agent The endpoint the main turn uses, key included. Absent sends the task's endpoint
+ * as it stands.
+ */
+export declare function taskCall<Options extends SideTaskOptions = SideTaskOptions>(task: SideTask, options?: Options, agent?: {
+    baseUrl: string;
+    apiKey?: string;
+}): {
+    endpoint: Endpoint;
+    model: string;
+    options: Options;
+};
 /**
  * The tools a request is likely to need, picked by a small model before the run starts, or none.
  *
@@ -83,13 +117,18 @@ export declare function resolveApiKey(own: {
  * means by empty.
  * @param catalog The servers to choose from.
  * @param prompt The request being planned for. Only its head is read; see `preselectInput`.
- * @param options Cancellation, notices, the reply ceiling (256), the cap the choice is held to
+ * @param options Cancellation, notices, the reply ceiling (256), the temperature and reasoning
+ * effort as `ask` reads them (0.3 and none when absent), the cap the choice is held to
  * (`MAX_PER_LOAD`), and whether to try the words first.
  */
-export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, maxPerLoad, keywords, }?: {
+export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, temperature, reasoningEffort, maxPerLoad, keywords, }?: {
     signal?: AbortSignal;
     onNotice?: (message: string) => void;
     maxTokens?: number;
+    /** As `SideTaskOptions.temperature`: absent is 0.3. */
+    temperature?: number;
+    /** As `SideTaskOptions.reasoningEffort`: absent keeps the no-thinking hints. */
+    reasoningEffort?: string;
     maxPerLoad?: number;
     /**
      * Try `preselectByKeywords` first and spend the model only on what it cannot settle. `true`
@@ -202,9 +241,14 @@ export interface AgentLoopOptions {
      * `toolDiscovery` absent is eager, `maxRetries` absent is none, and `contextLength` is handed
      * to `runTurn` as `contextLimit`, which sizes each request against the window before sending.
      * `"proxy"` is on-demand loading behind a tool array that never changes; see `PROXY_TOOLS`.
+     *
+     * `tasks` is a resolved agent's, and is read only for the side tasks the loop was asked to run:
+     * `tasks.toolSelect` under `preselect` and `tasks.compaction` under `compact`. `toolSelectModel`
+     * is the flattened spelling of the first, for a host that is not on the spec.
      */
-    config: Endpoint & ModelParams & Pick<ToolPolicy, "maxToolIterations"> & Partial<Pick<ToolPolicy, "toolDiscovery">> & Partial<RetryPolicy> & {
+    config: Endpoint & ModelParams & Pick<ToolPolicy, "maxToolIterations"> & Partial<Pick<ToolPolicy, "toolDiscovery" | "toolSelectModel">> & Partial<RetryPolicy> & {
         contextLength?: number;
+        tasks?: Readonly<Record<string, SideTask>>;
     };
     /**
      * The standing instruction, sent as the first message. On-demand and proxied modes append the
@@ -260,6 +304,43 @@ export interface AgentLoopOptions {
      * mode, or proxied, where no step is routed either way.
      */
     preselectRouting?: "exclusive" | "append";
+    /**
+     * Has the loop make the preselection itself, before its first request, with the preselector
+     * the config names. Off by default: a host that passes a resolved agent and calls `preselect`
+     * on its own is not sent a second one.
+     *
+     * The preselector is `config.tasks.toolSelect` with everything it states — its endpoint, model,
+     * ceiling, temperature and reasoning effort, keyed as `taskCall` keys a task against `config` —
+     * and otherwise `config.toolSelectModel` on the config's own endpoint at `preselect`'s defaults.
+     * What it is asked about is the text of the last user message. Nothing is asked in eager mode,
+     * with neither preselector named, with no user message, or when `preselected` is given — an
+     * empty one included, which is how a host says it has already decided.
+     *
+     * `true` takes `preselect`'s defaults; an object passes `keywords` and `maxPerLoad` through.
+     * Its notices arrive as `notice` events, and a preselection that fails picks nothing rather
+     * than ending the run. It runs before the hooks gather, not beside them.
+     */
+    preselect?: boolean | {
+        keywords?: boolean | KeywordPreselectOptions;
+        maxPerLoad?: number;
+    };
+    /**
+     * Has the loop fold the transcript itself before a step, once `planCompaction` says the window
+     * is filling, with the summary written by `config.tasks.compaction` on its own settings. Off by
+     * default, and nothing is folded without that task — there is no falling back to the main model
+     * — or without a `config.contextLength` to plan against.
+     *
+     * It runs after `beforeStep`, on what that returned, and is `compactTranscript` and nothing
+     * more: the plan is made from the last request's reported prompt, or an estimate before the
+     * first step and after a `beforeStep` rewrite; `hooks`, when given, are told `beforeCompact`
+     * beside the summary; and a fold is said as a `notice` event. A summary that fails is a notice
+     * too and folds nothing. Tool results are not pruned — `beforeStep` is where a host does that.
+     *
+     * The result's `messages` then open with the summary in place of what was folded, so a host
+     * that keeps its transcript append-only wants `runCompaction` and a stored fold instead. `true`
+     * plans by `planCompaction`'s defaults; an object moves its thresholds.
+     */
+    compact?: boolean | Pick<CompactionOptions, "compactAt" | "keepRatio" | "target">;
     /**
      * Tools already loaded, carried from an earlier question. See `carryOver`. Not read in proxied
      * mode, where a tool is loaded only while its definition is in the history.
@@ -469,6 +550,11 @@ export interface AgentLoopResult {
  * the question. `call_tool` is honoured on demand too, unless the host has a tool of that name —
  * a session switched out of proxied mode still has it in its history, and the model copies it.
  *
+ * Neither side task is run unless asked for. `preselect` has the loop make the preselection and
+ * `compact` has it fold the transcript, each by the task `config.tasks` carries for it and on
+ * that task's own settings — a setting the task leaves out is the side task's default, never the
+ * run's `temperature` or `maxTokens`.
+ *
  * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.
  */

package/dist/agent-loop.js

@@ -1,6 +1,7 @@
 import { charsPerTokenFor } from "./calibration.js";
 import { capabilitiesFor, effortFor, modelCapabilitiesFor, } from "./capabilities.js";
 import { firstTokenMs, getClient, NO_KEY, timeoutMs } from "./client.js";
+import { compactTranscript, planCompaction, summariser, } from "./compaction.js";
 import { continueTurn } from "./continuation.js";
 import { AgentLoopError, AgentLoopOverflow, errorMessage, ToolIterationLimit, } from "./errors.js";
 import { runMetrics } from "./events.js";
@@ -106,6 +107,52 @@ export function resolveApiKey(own, inherited, env = process.env) {
         return NO_KEY;
     return inherited?.apiKey || env.OPENAI_API_KEY || NO_KEY;
 }
+/**
+ * A side task's settings as the call that honours them: its endpoint, its model, and the options
+ * `ask`, `askJson`, `summariser` and `preselect` take last.
+ *
+ * A helper rather than a second signature on each of the four, so a setting added to a task later
+ * arrives through `options` without a host's call changing. What the task states wins over the
+ * same field in `options`: the host's code is written once and the task is what an operator
+ * configured over it, so a host passes its own ceiling as the value for a task that names none.
+ * A setting the task leaves out and `options` does too is absent from the result, which is what
+ * leaves it to the entry point's own default — 0.3, not the agent's temperature.
+ *
+ * A resolved spec carries no key, so a task on the agent's own endpoint would otherwise go out
+ * unkeyed, and be remembered under a second capability entry beside the agent's. Given `agent`,
+ * such a task is sent the agent's `baseUrl` as the agent spells it and, having no key of its own,
+ * the agent's key, so `capabilitiesFor` answers both with one object; a task on another endpoint
+ * is sent only a key of its own, as `resolveApiKey` has it. The environment is not read: the
+ * agent's key is whatever the main turn is sent.
+ *
+ * @param task The task, ordinarily `resolved.tasks.<key>`.
+ * @param options What the host adds — cancellation, notices, `keywords` — and its own defaults
+ * for the settings a task may leave out.
+ * @param agent The endpoint the main turn uses, key included. Absent sends the task's endpoint
+ * as it stands.
+ */
+export function taskCall(task, options, agent) {
+    const own = task.endpoint;
+    const shared = agent && (!own.baseUrl.trim() || sameUrl(own.baseUrl, agent.baseUrl));
+    const stated = {};
+    if (task.maxTokens !== undefined)
+        stated.maxTokens = task.maxTokens;
+    if (task.temperature !== undefined)
+        stated.temperature = task.temperature;
+    if (task.reasoningEffort !== undefined)
+        stated.reasoningEffort = task.reasoningEffort;
+    return {
+        endpoint: agent
+            ? {
+                ...own,
+                ...(shared ? { baseUrl: agent.baseUrl } : {}),
+                apiKey: resolveApiKey(own, agent, {}),
+            }
+            : own,
+        model: task.model,
+        options: { ...options, ...stated },
+    };
+}
 /**
  * The tools a request is likely to need, picked by a small model before the run starts, or none.
  *
@@ -125,10 +172,11 @@ export function resolveApiKey(own, inherited, env = process.env) {
  * means by empty.
  * @param catalog The servers to choose from.
  * @param prompt The request being planned for. Only its head is read; see `preselectInput`.
- * @param options Cancellation, notices, the reply ceiling (256), the cap the choice is held to
+ * @param options Cancellation, notices, the reply ceiling (256), the temperature and reasoning
+ * effort as `ask` reads them (0.3 and none when absent), the cap the choice is held to
  * (`MAX_PER_LOAD`), and whether to try the words first.
  */
-export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, maxPerLoad = MAX_PER_LOAD, keywords, } = {}) {
+export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, temperature, reasoningEffort, maxPerLoad = MAX_PER_LOAD, keywords, } = {}) {
     if (!model || !catalog.some((server) => server.tools.length > 0))
         return [];
     if (keywords) {
@@ -141,7 +189,7 @@ export async function preselect(config, model, catalog, prompt, { signal, onNoti
             return guess.names;
         }
     }
-    const reply = await tryAsk("preselect", () => askJson(config, model, preselectSystem(maxPerLoad), preselectInput(catalog, prompt), PRESELECT_SCHEMA, { name: "preselection", maxTokens, signal, onNotice }), { onNotice });
+    const reply = await tryAsk("preselect", () => askJson(config, model, preselectSystem(maxPerLoad), preselectInput(catalog, prompt), PRESELECT_SCHEMA, { name: "preselection", maxTokens, temperature, reasoningEffort, signal, onNotice }), { onNotice });
     return preselection(reply, catalog, maxPerLoad);
 }
 /**
@@ -240,6 +288,11 @@ const UNRUN_CALL = "Not run: the run stopped first.";
  * the question. `call_tool` is honoured on demand too, unless the host has a tool of that name —
  * a session switched out of proxied mode still has it in its history, and the model copies it.
  *
+ * Neither side task is run unless asked for. `preselect` has the loop make the preselection and
+ * `compact` has it fold the transcript, each by the task `config.tasks` carries for it and on
+ * that task's own settings — a setting the task leaves out is the side task's default, never the
+ * run's `temperature` or `maxTokens`.
+ *
  * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.
  */
@@ -270,6 +323,15 @@ export async function runAgentLoop(options) {
         return result;
     throw new ToolIterationLimit(`Stopped after ${options.config.maxToolIterations} tool iterations.`, standing.read());
 }
+/** A message's words, as the preselector is asked about them: its string, or its text parts. */
+const userText = (message) => {
+    const content = message?.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.flatMap((part) => (part.type === "text" ? part.text : [])).join("\n");
+};
 /**
  * The steps of `runAgentLoop`, throwing what they caught as it was caught. Resolves to nothing
  * when `maxToolIterations` is spent, and tells `standing` how to read the run either way.
@@ -311,10 +373,44 @@ async function runSteps(options, standing) {
     const onDemand = proxied || (config.toolDiscovery === "ondemand" && catalog.length > 0);
     // Proxied, `loaded` is what this run has put a definition in the history for, and starts empty.
     const loaded = new Set(onDemand && !proxied ? (options.loaded ?? []) : []);
-    const preselected = onDemand ? [...(options.preselected ?? [])] : [];
+    // The loop's own preselection, where it was asked for and the host has not already decided: by
+    // the task where the config carries one, and by the flattened name on its own endpoint where
+    // it does not. `preselect` answers an empty model with nothing, so neither named asks nothing.
+    const choose = async () => {
+        const prompt = userText(options.messages.findLast((message) => message.role === "user"));
+        if (!prompt.trim())
+            return [];
+        const asked = {
+            ...(typeof options.preselect === "object" ? options.preselect : {}),
+            signal,
+            onNotice: notice,
+        };
+        const selector = config.tasks?.toolSelect;
+        if (!selector?.model) {
+            return preselect(config, config.toolSelectModel ?? "", catalog, prompt, asked);
+        }
+        const call = taskCall(selector, asked, config);
+        return preselect(call.endpoint, call.model, catalog, prompt, call.options);
+    };
+    const preselected = !onDemand
+        ? []
+        : options.preselect && options.preselected === undefined
+            ? await choose()
+            : [...(options.preselected ?? [])];
     if (!proxied)
         for (const name of preselected)
             loaded.add(name);
+    // The loop's own compaction, which is the task's or nothing: a summary the main model writes is
+    // a second full-price request the operator did not ask for.
+    const compactor = options.compact ? config.tasks?.compaction : undefined;
+    const summarise = (() => {
+        if (!compactor?.model)
+            return undefined;
+        const call = taskCall(compactor, { signal, onNotice: notice }, config);
+        const write = summariser(call.endpoint, call.model, call.options);
+        // A summary that fails folds nothing, and the step goes out as it was.
+        return async (text) => (await tryAsk("compaction", () => write(text), { onNotice: notice })) ?? "";
+    })();
     const used = new Set();
     const definitions = new Map();
     for (const tool of tools) {
@@ -418,11 +514,32 @@ async function runSteps(options, standing) {
             limit: config.contextLength ?? 0,
             ledger,
         });
+        let next = rewritten ?? messages;
+        if (summarise) {
+            const plan = planCompaction(next, {
+                ...(typeof options.compact === "object" ? options.compact : {}),
+                limit: config.contextLength ?? 0,
+                // The last request's prompt describes this transcript only while nothing has rewritten it.
+                ...(next === messages && previous && previous.prompt > 0 ? { used: previous.prompt } : {}),
+                charsPerToken: charsPerTokenFor(supports, config.model),
+                ...((compactor?.maxTokens ?? 0) > 0 ? { summaryTokens: compactor?.maxTokens } : {}),
+            });
+            if (plan) {
+                const folded = await compactTranscript(next, plan, summarise, {
+                    ...(hooks
+                        ? { hooks: { run: hooks.run, context: hooks.context, onNote: hooks.onNote } }
+                        : {}),
+                });
+                if (folded !== next)
+                    notice(`compacted ${plan.cut - plan.from} messages into a summary`);
+                next = folded;
+            }
+        }
         // A rewrite may have folded a definition away, and a load answered "already loaded" would
         // then point at nothing. Forgetting costs a definition sent twice at worst.
-        if (proxied && rewritten && rewritten !== messages)
+        if (proxied && next !== messages)
             loaded.clear();
-        messages = rewritten ?? messages;
+        messages = next;
         ledger = rebaseLedger(ledger, before, messages);
         onEvent({ kind: "turn", text: `turn ${step + 1}` });
         // Appended, the shortlist is already in `loaded` — after what was carried, and once — so the

package/dist/client.d.ts

@@ -18,7 +18,8 @@ export interface ClientPoolOptions {
     maxClients?: number;
     /**
      * How long, in milliseconds, a model an endpoint did not list — or a server that answered
-     * without a served window — is taken at its word before the endpoint is asked again.
+     * without a served window, or whose `/api/v0/models` answered with an error other than a
+     * missing route — is taken at its word before the endpoint is asked again.
      */
     listingMissMs?: number;
 }
@@ -66,7 +67,12 @@ export declare const firstTokenMs: (config: Pick<Endpoint, "requestTimeoutSecond
  * @param config Where to send requests and how long to wait. An absent `apiKey` becomes `NO_KEY`.
  */
 export declare function getClient(config: Endpoint): OpenAI;
-/** A model an endpoint offers, and what it says the model will read. Zero means it did not say. */
+/**
+ * A model an endpoint offers, and what it says the model will read. Zero means it did not say.
+ *
+ * The number is whatever the listing carried, which from llama.cpp is the trained window rather
+ * than the served one; `contextLimitFor` is the lookup that knows the difference.
+ */
 export interface ModelInfo {
     id: string;
     contextLength: number;
@@ -109,7 +115,8 @@ export declare const endpointId: (config: {
     apiKey?: string;
 }) => string;
 /**
- * The window a local server is actually serving a model in, which its listing does not say.
+ * The window a local server's own API says it is serving a model in, for the servers whose
+ * listing does not say.
  *
  * llama.cpp reports it on `/props` as `default_generation_settings.n_ctx`, per slot, and LM
  * Studio on `/api/v0/models` as `loaded_context_length` while the model is loaded. Both differ
@@ -117,8 +124,12 @@ export declare const endpointId: (config: {
  * built for, and reading the trained one lets an overflow through the guard meant to catch it.
  * Ollama reports nothing on either; an operator there has to declare the window.
  *
- * Zero where no answer was found. A server without either route, which is every hosted API, is
- * latched and not asked again; one that could not be reached is not remembered at all.
+ * Zero where no answer was found, which is remembered for `listingMissMs`. A server without
+ * either route is latched and not asked again. `/api/v0/models` is also dropped on its own: until
+ * `resetClients` once it answers as a route that is not there, and for `listingMissMs` after any
+ * other error. A server that could not be reached is not remembered at all.
+ *
+ * The listing is not read here; `contextLimitFor` reads it first and comes here after.
  *
  * @param config The endpoint, plus the model whose window is wanted.
  */
@@ -139,11 +150,18 @@ export declare function listModels(config: Endpoint): Promise<ModelInfo[]>;
  * happily load a 256k model at `-c 16384` and go on listing it as 256k — and a run refused on
  * the honest-looking number is a run that fails at the endpoint instead.
  *
- * Otherwise the window the server is actually serving the model in, where it has an API that
- * says (`servedWindow`), and failing that the endpoint's listing — asked once, and again whenever
- * it does not name this model, since a model can arrive after the first listing was taken. A
- * server that will not list models still has to be able to run a turn: a failure here is an
- * unknown window, not a failed run.
+ * Otherwise the endpoint's listing — asked once, and again whenever it does not name this model,
+ * since a model can arrive after the first listing was taken. A window stated at the top of the
+ * model's entry is taken as the one being served, and nothing else is asked. Where the listing
+ * did not settle it — no window, only llama.cpp's trained one, no entry, no listing — the
+ * server's own API is asked (`servedWindow`), and what it says wins; the trained window is what
+ * is left when it says nothing. A server that will not list models still has to be able to run a
+ * turn: a failure here is an unknown window, not a failed run.
+ *
+ * The listing goes first because it is the one route every server here has, and the native ones
+ * are two more requests that a server stating its window in the listing never needed. Asked
+ * first, they were also asked again every `listingMissMs` for the life of the process on a server
+ * whose `/props` answers without a window, by any host that sizes the window per turn.
  *
  * @param config The endpoint, plus the model whose window is wanted.
  * @param declared The operator's own number. Above zero it wins and the endpoint is not asked.

package/dist/client.js

@@ -162,18 +162,26 @@ const CONTEXT_KEYS = [
     "n_ctx",
 ];
 const positive = (value) => (typeof value === "number" && value > 0 ? value : 0);
+/**
+ * A listing entry's window, and whether it is only the one the model was trained with.
+ *
+ * The two are told apart because they are trusted differently: a top-level key is taken as the
+ * window being served and settles the lookup, and a trained one is a ceiling the server may be
+ * running well under, so `contextLimitFor` still asks the native routes before settling for it.
+ */
 function contextLengthOf(model) {
     const record = model;
     for (const key of CONTEXT_KEYS) {
         const value = positive(record[key]);
         if (value)
-            return value;
+            return { contextLength: value, trained: false };
     }
     // llama.cpp's, and the window the model was trained with rather than the one it is served in:
     // a 256k model started at `-c 16384` lists 262144 here. Better than nothing, and why the
-    // served window is asked for first. `meta` is `null` while the model loads.
+    // served window is still asked for after it. `meta` is `null` while the model loads.
     const meta = record.meta;
-    return positive(meta?.n_ctx_train);
+    const contextLength = positive(meta?.n_ctx_train);
+    return { contextLength, trained: contextLength > 0 };
 }
 /**
  * The last listing from each endpoint, so a run can size its window without a round trip.
@@ -190,6 +198,13 @@ function contextLengthOf(model) {
  * whatever was there rather than emptying it.
  */
 const listings = new Map();
+/**
+ * The models in each endpoint's last listing whose window is only the trained one, by id.
+ *
+ * Kept beside `listings` rather than on `ModelInfo`, so what `listModels` hands back is the shape
+ * it has always been. Replaced with each listing that lands, and left alone by one that fails.
+ */
+const trainedOnly = new Map();
 /**
  * When an endpoint was last asked about a model it did not name, keyed on the two together.
  *
@@ -243,8 +258,25 @@ export const endpointId = (config) => createHash("sha256").update(endpointKey(co
  * is asked again after `listingMissMs`, like a listing that did not name the model.
  */
 const served = new Map();
-/** Endpoints that answered both probes with a refusal, and are not asked again. */
+/** Endpoints with neither native route, which are not asked for either again. */
 const unserved = new Set();
+/**
+ * Endpoints whose `/api/v0/models` answered with an error, and when.
+ *
+ * `gone` is a route the server does not have (`NOT_THERE`), which is a fact about the server and
+ * stands until `resetClients`. Any other error stands for `listingMissMs` only, because it may be
+ * one the server gets over, and LM Studio latched for good on a passing 5xx would have no window
+ * at all until the process restarted, its listing carrying none.
+ *
+ * Per endpoint and on its own, whatever `/props` said: a server whose `/props` answers without a
+ * window is never `unserved`, and without this its missing route was asked again with every miss.
+ */
+const refusals = new Map();
+/** Whether `/api/v0/models` is to be left alone on this endpoint for now. */
+const refused = (endpoint) => {
+    const refusal = refusals.get(endpoint);
+    return (refusal !== undefined && (refusal.gone || Date.now() - refusal.at < poolLimits.listingMissMs));
+};
 /** How long a probe may take before the window is taken from the listing instead. */
 const PROBE_TIMEOUT_MS = 10_000;
 /** The server root behind an OpenAI-compatible base URL, which is where the native APIs live. */
@@ -252,8 +284,9 @@ const rootOf = (baseUrl) => baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");
 /** A route this server does not have, rather than one that failed to answer. */
 const NOT_THERE = new Set([404, 405, 501]);
 /**
- * Asks one native endpoint. `missing` is a server without the route; `body` is absent for that
- * and for any other refusal, and a server that could not be reached throws.
+ * Asks one native endpoint. `failed` is any answer that was not a 2xx and `missing` the ones among
+ * them that mean a server without the route; `body` is absent for both, and for a 2xx that was not
+ * JSON. A server that could not be reached throws.
  */
 async function probe(config, path) {
     const apiKey = config.apiKey || undefined;
@@ -262,16 +295,17 @@ async function probe(config, path) {
         signal: AbortSignal.timeout(timeoutMs(config) ?? PROBE_TIMEOUT_MS),
     });
     if (!response.ok)
-        return { missing: NOT_THERE.has(response.status) };
+        return { failed: true, missing: NOT_THERE.has(response.status) };
     try {
-        return { missing: false, body: await response.json() };
+        return { failed: false, missing: false, body: await response.json() };
     }
     catch {
-        return { missing: false };
+        return { failed: false, missing: false };
     }
 }
 /**
- * The window a local server is actually serving a model in, which its listing does not say.
+ * The window a local server's own API says it is serving a model in, for the servers whose
+ * listing does not say.
  *
  * llama.cpp reports it on `/props` as `default_generation_settings.n_ctx`, per slot, and LM
  * Studio on `/api/v0/models` as `loaded_context_length` while the model is loaded. Both differ
@@ -279,8 +313,12 @@ async function probe(config, path) {
  * built for, and reading the trained one lets an overflow through the guard meant to catch it.
  * Ollama reports nothing on either; an operator there has to declare the window.
  *
- * Zero where no answer was found. A server without either route, which is every hosted API, is
- * latched and not asked again; one that could not be reached is not remembered at all.
+ * Zero where no answer was found, which is remembered for `listingMissMs`. A server without
+ * either route is latched and not asked again. `/api/v0/models` is also dropped on its own: until
+ * `resetClients` once it answers as a route that is not there, and for `listingMissMs` after any
+ * other error. A server that could not be reached is not remembered at all.
+ *
+ * The listing is not read here; `contextLimitFor` reads it first and comes here after.
  *
  * @param config The endpoint, plus the model whose window is wanted.
  */
@@ -300,13 +338,19 @@ export async function servedWindow(config) {
             ?.default_generation_settings;
         window = positive(settings?.n_ctx);
         if (!window) {
-            const lmstudio = await probe(config, "/api/v0/models");
-            const { data } = (lmstudio.body ?? {});
-            const entry = Array.isArray(data)
-                ? data.find((model) => model?.id === config.model)
-                : undefined;
-            window = positive(entry?.loaded_context_length);
-            if (props.missing && lmstudio.missing) {
+            if (!refused(endpoint)) {
+                const lmstudio = await probe(config, "/api/v0/models");
+                if (lmstudio.failed)
+                    refusals.set(endpoint, { at: Date.now(), gone: lmstudio.missing });
+                else
+                    refusals.delete(endpoint);
+                const { data } = (lmstudio.body ?? {});
+                const entry = Array.isArray(data)
+                    ? data.find((model) => model?.id === config.model)
+                    : undefined;
+                window = positive(entry?.loaded_context_length);
+            }
+            if (props.missing && refusals.get(endpoint)?.gone) {
                 unserved.add(endpoint);
                 return 0;
             }
@@ -325,10 +369,18 @@ export async function servedWindow(config) {
  */
 export async function listModels(config) {
     const { data } = await getClient(config).models.list();
+    const trained = new Set();
     const models = data
-        .map((model) => ({ id: model.id, contextLength: contextLengthOf(model) }))
+        .map((model) => {
+        const window = contextLengthOf(model);
+        if (window.trained)
+            trained.add(model.id);
+        return { id: model.id, contextLength: window.contextLength };
+    })
         .sort((a, b) => a.id.localeCompare(b.id));
-    listings.set(endpointKey(config), models);
+    const key = endpointKey(config);
+    listings.set(key, models);
+    trainedOnly.set(key, trained);
     return models;
 }
 /**
@@ -339,11 +391,18 @@ export async function listModels(config) {
  * happily load a 256k model at `-c 16384` and go on listing it as 256k — and a run refused on
  * the honest-looking number is a run that fails at the endpoint instead.
  *
- * Otherwise the window the server is actually serving the model in, where it has an API that
- * says (`servedWindow`), and failing that the endpoint's listing — asked once, and again whenever
- * it does not name this model, since a model can arrive after the first listing was taken. A
- * server that will not list models still has to be able to run a turn: a failure here is an
- * unknown window, not a failed run.
+ * Otherwise the endpoint's listing — asked once, and again whenever it does not name this model,
+ * since a model can arrive after the first listing was taken. A window stated at the top of the
+ * model's entry is taken as the one being served, and nothing else is asked. Where the listing
+ * did not settle it — no window, only llama.cpp's trained one, no entry, no listing — the
+ * server's own API is asked (`servedWindow`), and what it says wins; the trained window is what
+ * is left when it says nothing. A server that will not list models still has to be able to run a
+ * turn: a failure here is an unknown window, not a failed run.
+ *
+ * The listing goes first because it is the one route every server here has, and the native ones
+ * are two more requests that a server stating its window in the listing never needed. Asked
+ * first, they were also asked again every `listingMissMs` for the life of the process on a server
+ * whose `/props` answers without a window, by any host that sizes the window per turn.
  *
  * @param config The endpoint, plus the model whose window is wanted.
  * @param declared The operator's own number. Above zero it wins and the endpoint is not asked.
@@ -351,9 +410,6 @@ export async function listModels(config) {
 export async function contextLimitFor(config, declared = 0) {
     if (declared > 0)
         return declared;
-    const window = await servedWindow(config);
-    if (window > 0)
-        return window;
     const key = endpointKey(config);
     const listed = () => listings.get(key)?.find((model) => model.id === config.model);
     // The listing is asked for again when it does not name this model, rather than only when
@@ -369,26 +425,30 @@ export async function contextLimitFor(config, declared = 0) {
         // Asked again, but not on every call. A model that is never coming answers the same zero
         // however often the endpoint is asked, and a caller sizing a window per turn pays a round
         // trip for each of them; `listingMissMs` is how long that answer is allowed to stand.
-        if (asked !== undefined && Date.now() - asked < poolLimits.listingMissMs)
-            return 0;
-        // A failure is not remembered: an endpoint that was down when the last run started is not
-        // an endpoint with no models, and a window nobody could ask about is not a failed run.
-        try {
-            await listModels(config);
-        }
-        catch {
-            return 0;
+        if (asked === undefined || Date.now() - asked >= poolLimits.listingMissMs) {
+            // A failure is not remembered: an endpoint that was down when the last run started is not
+            // an endpoint with no models, and a window nobody could ask about is not a failed run.
+            const answered = await listModels(config).then(() => true, () => false);
+            // Recorded where the endpoint was actually asked, and only there. Stamping it on the calls
+            // that skipped the request would push the deadline out ahead of any caller polling faster
+            // than the interval, which is a memory that never expires rather than one that expires in
+            // half a minute.
+            if (answered) {
+                if (listed())
+                    misses.delete(missKey);
+                else
+                    misses.set(missKey, Date.now());
+            }
         }
-        // Recorded where the endpoint was actually asked, and only there. Stamping it on the calls
-        // that skipped the request would push the deadline out ahead of any caller polling faster
-        // than the interval, which is a memory that never expires rather than one that expires in
-        // half a minute.
-        if (listed())
-            misses.delete(missKey);
-        else
-            misses.set(missKey, Date.now());
     }
-    return listed()?.contextLength ?? 0;
+    const entry = listed();
+    const fromListing = entry?.contextLength ?? 0;
+    // A top-level key settles it. A trained window does not: llama.cpp lists the one the model was
+    // built with, and taking it over what `/props` says lets an overflow through the guard.
+    if (fromListing > 0 && !trainedOnly.get(key)?.has(config.model))
+        return fromListing;
+    const window = await servedWindow(config);
+    return window > 0 ? window : fromListing;
 }
 /**
  * Forgets every cached client and listing, and puts `configureClients` back to the defaults. For
@@ -399,6 +459,8 @@ export function resetClients() {
     clients.clear();
     listings.clear();
     misses.clear();
+    trainedOnly.clear();
     served.clear();
     unserved.clear();
+    refusals.clear();
 }

package/dist/index.d.ts

@@ -9,7 +9,7 @@
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
-export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, buildBody, preselect, preview, resolveApiKey, runAgentLoop, type StepWindow, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult, } from "./agent-loop.ts";
+export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, buildBody, preselect, preview, resolveApiKey, runAgentLoop, type StepWindow, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult, taskCall, } from "./agent-loop.ts";
 export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.ts";
 export { type Capabilities, capabilitiesFor, EFFORT_LADDER, effortFor, expireCapabilities, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
 export type { CatalogServer } from "./catalog.ts";
@@ -25,7 +25,7 @@ export { resetAll } from "./reset.ts";
 export { backoffMs, CHARS_PER_TOKEN, type ContextBreakdown, type ContextBreakdownOptions, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, type TokenEstimateOptions, toolsChars, } from "./retry.ts";
 export { type RunTurnOptions, runTurn } from "./run-turn.ts";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
-export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTaskInput, type SideTaskOptions, tryAsk, } from "./side-task.ts";
+export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTask, type SideTaskInput, type SideTaskOptions, tryAsk, } from "./side-task.ts";
 export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from "./snapshot.ts";
 export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, type AgentHook, type AgentSpec, type EndpointSpec, type ExportSpecOptions, exportSpec, type ModelSpec, type ParsedSpec, type ParseSpecOptions, type PromptPart, parseSpec, RESOLVED_DEFAULTS, type ResolvedAgent, type ResolvedTask, type RetrySpec, resolveAgentSpec, SPEC_EVENTS, type SpecBundle, type SpecServer, type TaskSpec, type ToolsSpec, } from "./spec.ts";
 export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";

package/dist/index.js

@@ -9,7 +9,7 @@
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
-export { buildBody, preselect, preview, resolveApiKey, runAgentLoop, } from "./agent-loop.js";
+export { buildBody, preselect, preview, resolveApiKey, runAgentLoop, taskCall, } from "./agent-loop.js";
 export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.js";
 export { capabilitiesFor, EFFORT_LADDER, effortFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.js";

package/dist/side-task.d.ts

@@ -20,10 +20,22 @@ export declare const resetHints: () => void;
 export type SideTaskInput = string | OpenAI.ChatCompletionContentPart[];
 /** What a side task may be given. All optional — one given none of them still runs. */
 export interface SideTaskOptions {
-    /** Ceiling on the reply, default 512. These answers are meant to be short. */
+    /**
+     * Ceiling on the reply, default 512. These answers are meant to be short. Zero or less sends
+     * none and leaves it to the server, which is what `maxTokens: 0` means on the main model too.
+     */
     maxTokens?: number;
     /** Sampling temperature, default 0.3. Naming and classifying want the same answer twice. */
     temperature?: number;
+    /**
+     * A reasoning effort to ask for in place of the no-thinking hints, for a side task an operator
+     * has pointed at a model that should deliberate — a compaction summary is the usual one.
+     *
+     * Absent, `""` and `"off"` all keep the hints, because off is what they already ask for. Any
+     * other value is sent as `reasoning_effort`, stepped up by `effortFor` where the model has
+     * refused it by value, and `chat_template_kwargs` is left out of the request altogether.
+     */
+    reasoningEffort?: string;
     /** Abandons the call, usually because the run it supports has gone away. */
     signal?: AbortSignal;
     /**
@@ -40,6 +52,27 @@ export interface SideTaskOptions {
      */
     onNotice?: (message: string) => void;
 }
+/**
+ * One side task's own settings, as a resolved agent spec carries them under `tasks.<key>`.
+ *
+ * Declared here rather than imported from `spec.ts`, whose `ResolvedTask` it matches field for
+ * field: the spec module is one nothing else in `src/` imports, and a host that is not on the spec
+ * can write one of these by hand. An absent setting is the side task's own default — 0.3, the
+ * entry point's ceiling, thinking off — and never the main model's, so raising the agent's
+ * temperature for the chat does not make its titler creative. See `taskCall`.
+ */
+export interface SideTask {
+    /** The model that does the task. */
+    model: string;
+    /** Where that model is reached, which need not be where the agent's is. */
+    endpoint: Endpoint;
+    /** The reply's ceiling. Absent is the entry point's default; zero sends none. */
+    maxTokens?: number;
+    /** Absent is 0.3, whatever the agent's own temperature is. Zero means zero. */
+    temperature?: number;
+    /** As `SideTaskOptions.reasoningEffort`: a level replaces the no-thinking hints. */
+    reasoningEffort?: string;
+}
 /**
  * Runs a side task and returns the reply text, thinking stripped. Throws like any request.
  *
@@ -47,7 +80,7 @@ export interface SideTaskOptions {
  * @param model The model to ask, usually smaller than the one running the work.
  * @param system The instruction.
  * @param user The input it applies to. Content parts where the model is being shown an image.
- * @param options Reply ceiling, temperature, cancellation, notices.
+ * @param options Reply ceiling, temperature, a reasoning effort, cancellation, notices.
  */
 export declare function ask(config: Endpoint, model: string, system: string, user: SideTaskInput, options?: SideTaskOptions): Promise<string>;
 /** What `askJson` takes besides a side task's options. */

package/dist/side-task.js

@@ -72,7 +72,7 @@ function rejectedTheRequest(error) {
  * @param model The model to ask, usually smaller than the one running the work.
  * @param system The instruction.
  * @param user The input it applies to. Content parts where the model is being shown an image.
- * @param options Reply ceiling, temperature, cancellation, notices.
+ * @param options Reply ceiling, temperature, a reasoning effort, cancellation, notices.
  */
 export function ask(config, model, system, user, options = {}) {
     return complete(config, model, system, user, options);
@@ -81,22 +81,29 @@ export function ask(config, model, system, user, options = {}) {
  * The request `ask` and `askJson` share, with `format` deciding the extra body fields from what
  * the model and the endpoint have refused, rebuilt on every re-send.
  */
-async function complete(config, model, system, user, { maxTokens = 512, temperature = 0.3, signal, onNotice }, format) {
+async function complete(config, model, system, user, { maxTokens = 512, temperature = 0.3, reasoningEffort, signal, onNotice }, format) {
+    // The effort the caller chose, or empty where it chose none: `""` and `"off"` read as absent,
+    // since off is what the hints below already ask for.
+    const level = effortFor(undefined, reasoningEffort);
     // Whether the last request carried an effort, which `negotiate` decides and not this function.
     let sentEffort = false;
     const send = (hints, effort, supports, refused) => {
         // `none` is what a side task wants and not always what the model offers: OpenAI's reasoning
         // models refuse it by value and list `minimal` as their floor. `effortFor` answers with the
         // cheapest rung this one takes, which `negotiate` has been stepping up as it was refused.
-        const asked = effort ? effortFor(refused, "none") : "";
+        // A level the caller chose goes through the same ladder, which only ever steps up from it.
+        const asked = effort ? effortFor(refused, level || "none") : "";
         sentEffort = asked !== "";
         return getClient(config).chat.completions.create({
             model,
             // The reasoning models want the ceiling spelled the other way, and they are exactly the
-            // models a side task most wants to stop deliberating.
-            ...(refused && !refused.legacyTokenLimit
-                ? { max_completion_tokens: maxTokens }
-                : { max_tokens: maxTokens }),
+            // models a side task most wants to stop deliberating. Zero is no ceiling, as it is on the
+            // main model: a spec's `maxTokens: 0` sent as `max_tokens: 0` asks for an empty reply.
+            ...(maxTokens > 0
+                ? refused && !refused.legacyTokenLimit
+                    ? { max_completion_tokens: maxTokens }
+                    : { max_tokens: maxTokens }
+                : {}),
             // One that will only run at the temperature it was built with is sent none: a side task
             // wants the same answer twice, and 1.0 from that model is as close as it gets.
             ...(refused && !refused.chosenTemperature ? {} : { temperature }),
@@ -121,7 +128,9 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         onNotice,
     });
     const key = hintKey(endpointId(config), model);
-    const hints = !noHints.has(key);
+    // A chosen effort replaces the template hint rather than riding beside it: `enable_thinking:
+    // false` next to `reasoning_effort: "high"` is a request that contradicts itself.
+    const hints = !level && !noHints.has(key);
     let response;
     try {
         response = await attempt(hints, true);
@@ -134,7 +143,9 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         const effort = sentEffort;
         if (!(hints || effort) || !rejectedTheRequest(error))
             throw error;
-        onNotice?.(`${model} rejected a request carrying the no-thinking hints; retrying without them`);
+        onNotice?.(level
+            ? `${model} rejected a request carrying a reasoning effort; retrying without it`
+            : `${model} rejected a request carrying the no-thinking hints; retrying without them`);
         response = await attempt(false, false);
         // Latched on the finding, not the hypothesis: a context overflow is a 400 `negotiate` does
         // not recognise too, and it fails the retry the same way, leaving the next call to try the

package/dist/spec.d.ts

@@ -132,8 +132,14 @@ export interface TaskSpec {
     model?: string;
     /** Where that model lives, when it is not on the agent's endpoint. */
     endpoint?: EndpointSpec;
+    /** The reply's ceiling. Absent is the side task's own default, not the agent's `maxTokens`. */
     maxTokens?: number;
+    /** Absent is the side task's own default, 0.3, whatever the agent's temperature is. */
     temperature?: number;
+    /**
+     * A level has the task deliberate. Absent and `"off"` leave it with the no-thinking hints a
+     * side task is sent by default; see `SideTaskOptions.reasoningEffort`.
+     */
     reasoningEffort?: string;
 }
 /** A tool call bound to a lifecycle event, run by the host rather than the model. */
@@ -178,7 +184,13 @@ export interface SpecBundle {
      */
     mcpServers?: SpecServer[];
 }
-/** One side task, resolved: a model, and the endpoint it is reached through. */
+/**
+ * One side task, resolved: a model, and the endpoint it is reached through.
+ *
+ * The three settings are present only where a layer stated them, and nothing is filled in from
+ * the agent's own model — `taskCall` turns one into a call, and what is absent there is left to
+ * the side task's default.
+ */
 export interface ResolvedTask {
     model: string;
     /** This task's endpoint, which is the agent's unless a layer named another. */

package/llms.txt

@@ -26,6 +26,7 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 - `ToolCallOutcome` (type) — What one tool call did, in the order the model asked.
 - `ToolCallRequest` (type) — One call the model made, as `dispatch` and `onToolCall` are handed it.
 - `ToolCallResult` (type) — One call's whole answer, as `onToolResult` is handed it.
+- `taskCall` — A side task's settings as the call that honours them: its endpoint, its model, and the options `ask`, `askJson`, `summariser` and `preselect` take last.
 
 ### calibration
 
@@ -70,7 +71,7 @@ The contract between whatever holds the tools and the loop that offers them to a
 - `ModelInfo` (type) — A model an endpoint offers, and what it says the model will read.
 - `NO_KEY` — The SDK insists on a non-empty key even where the server will not look at it.
 - `resetClients` — Forgets every cached client and listing, and puts `configureClients` back to the defaults.
-- `servedWindow` — The window a local server is actually serving a model in, which its listing does not say.
+- `servedWindow` — The window a local server's own API says it is serving a model in, for the servers whose listing does not say.
 - `timeoutMs` — Zero, less, or absent means no limit, which the SDK spells as `undefined`.
 
 ### compaction
@@ -240,6 +241,7 @@ One-shot calls that support a run without being one: picking tools, naming a ses
 - `listLines` — A list-shaped reply, one item per line, cleaned of the bullets and quotes models decorate them with.
 - `parseJson` — Models are asked for JSON and often answer with prose around it, or a fenced block.
 - `resetHints` — Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints.
+- `SideTask` (type) — One side task's own settings, as a resolved agent spec carries them under `tasks.<key>`.
 - `SideTaskInput` (type) — The input a side task applies its instruction to: text, or the content parts a vision model reads.
 - `SideTaskOptions` (type) — What a side task may be given.
 - `tryAsk` — A side task is never worth failing the work it supports.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",