@cubicecho/agent-core 2.21.1 → 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`. |
@@ -564,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:
@@ -1150,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/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
 
@@ -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.1",
+  "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",