@cubicecho/agent-core 4.2.0 → 4.3.0

package/README.md

@@ -588,7 +588,7 @@ one just over it means the ranking chose arbitrarily, which is the case a model
 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. `preselect` also takes a `temperature` and a
-`reasoningEffort`, read as `ask` reads them, and `runAgentLoop({ preselect: true })` makes the call
+`reasoningEffort` and an `extraBody`, 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
@@ -1196,7 +1196,7 @@ 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
+temperature, reasoning effort and `extraBody` — 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:
@@ -1217,6 +1217,13 @@ no-thinking hints by default, and absent or `"off"` keeps them; a level — `"lo
 sent as `reasoning_effort` in their place, for a compaction model an operator pointed at a model
 that should deliberate.
 
+`extraBody` carries the sampler fields a model card asks for, as it does on the main model: `ask`,
+`askJson`, `summariser` and `preselect` all take one in their options, merge it in after the
+temperature, and offer its keys to `negotiate` as `droppable`, so a field the endpoint refuses by
+name is latched off for that model and the request is sent again without it. The agent's own
+`model.extraBody` is never sent to a side task, and `taskCall` lays a task's over the host's key by
+key.
+
 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

package/dist/endpoint/capabilities.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointIdentity } from '../core/config.ts';
+import { type EndpointIdentity } from '../core/config.ts';
 import type { Produced } from '../wire/stream.ts';
 /**
  * What an endpoint turned out not to support, and answering it when it says so.
@@ -307,6 +307,20 @@ export declare const ceilingAndTemperature: (refused: ModelCapabilities | undefi
 } | {
     temperature?: number | undefined;
 };
+/**
+ * The request fields an `extraBody` adds as this model takes them, to spread into a request body.
+ *
+ * @param refused - What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param [extraBody] - The fields to add. Absent adds none.
+ * @returns A fresh object of the fields, less the `RESERVED_BODY_FIELDS` and those the model has
+ * refused by name.
+ *
+ * @remarks
+ * The keys are what a caller hands `negotiate` as `droppable`, so a field the endpoint has never
+ * heard of is latched into `refusedFields` and left out of the next send.
+ */
+export declare const extraFields: (refused: ModelCapabilities | undefined, extraBody?: Record<string, unknown>) => Record<string, unknown>;
 /** What `negotiate` takes besides the request. All optional. */
 export interface NegotiateOptions {
     /**

package/dist/endpoint/capabilities.js

@@ -1,3 +1,4 @@
+import { RESERVED_BODY_FIELDS } from '../core/config.js';
 import { getOrCreate } from '../core/guards.js';
 import { scoped } from '../core/scope.js';
 import { errorMessage } from '../wire/errors.js';
@@ -353,6 +354,20 @@ export const ceilingAndTemperature = (refused, maxTokens, temperature) => {
         ...(refused?.chosenTemperature === false ? {} : { temperature }),
     };
 };
+/**
+ * The request fields an `extraBody` adds as this model takes them, to spread into a request body.
+ *
+ * @param refused - What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param [extraBody] - The fields to add. Absent adds none.
+ * @returns A fresh object of the fields, less the `RESERVED_BODY_FIELDS` and those the model has
+ * refused by name.
+ *
+ * @remarks
+ * The keys are what a caller hands `negotiate` as `droppable`, so a field the endpoint has never
+ * heard of is latched into `refusedFields` and left out of the next send.
+ */
+export const extraFields = (refused, extraBody = {}) => Object.fromEntries(Object.entries(extraBody).filter(([field]) => !RESERVED_BODY_FIELDS.includes(field) && !refused?.refusedFields.has(field)));
 /**
  * How to answer a refused effort *value*, or `undefined` when there is nothing new to learn or
  * nowhere left to go — in which case the refusal is the caller's, as it was before this existed.

package/dist/run/request-body.d.ts

@@ -1,5 +1,5 @@
 import type OpenAI from 'openai';
-import { type ModelParams } from '../core/config.ts';
+import type { ModelParams } from '../core/config.ts';
 import { type Capabilities, type ModelCapabilities } from '../endpoint/capabilities.ts';
 import { type ToolOrder } from '../tools/tool-loading.ts';
 /**

package/dist/run/request-body.js

@@ -1,5 +1,4 @@
-import { RESERVED_BODY_FIELDS } from '../core/config.js';
-import { ceilingAndTemperature, effortFor, } from '../endpoint/capabilities.js';
+import { ceilingAndTemperature, effortFor, extraFields, } from '../endpoint/capabilities.js';
 import { relaxTools, sanitizeTools } from '../endpoint/schema-compat.js';
 import { orderTools } from '../tools/tool-loading.js';
 /**
@@ -33,12 +32,11 @@ export function buildBody(config, supports, refused, messages, tools = [], order
     const sorted = orderTools(tools, order);
     const declared = supports.strictSchemas ? sanitizeTools(sorted) : relaxTools(sanitizeTools(sorted));
     const effort = effortFor(refused, config.reasoningEffort);
-    const extra = Object.entries(config.extraBody ?? {}).filter(([field]) => !RESERVED_BODY_FIELDS.includes(field) && !refused?.refusedFields.has(field));
     return {
         ...ceilingAndTemperature(refused, config.maxTokens, config.temperature),
         ...(effort ? { reasoning_effort: effort } : {}),
         ...(supports.usageInStream ? { stream_options: { include_usage: true } } : {}),
-        ...Object.fromEntries(extra),
+        ...extraFields(refused, config.extraBody),
         model: config.model,
         messages,
         stream: true,

package/dist/spec/spec.d.ts

@@ -151,6 +151,8 @@ export interface TaskSpec {
      * side task is sent by default; see `SideTaskOptions.reasoningEffort`.
      */
     reasoningEffort?: string;
+    /** Request fields the interface cannot spell, as `model.extraBody` but for this task alone. */
+    extraBody?: Record<string, unknown>;
 }
 /** A tool call bound to a lifecycle event, run by the host rather than the model. */
 export interface AgentHook {
@@ -198,7 +200,7 @@ export interface SpecBundle {
  * One side task, resolved: a model, and the endpoint it is reached through.
  *
  * @remarks
- * The three settings are present only where a layer stated them, and nothing is filled in from
+ * The 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.
  */
@@ -209,6 +211,8 @@ export interface ResolvedTask {
     maxTokens?: number;
     temperature?: number;
     reasoningEffort?: string;
+    /** Merged key by key across the layers. `model.extraBody` is the agent's and never reaches it. */
+    extraBody?: Record<string, unknown>;
 }
 /**
  * What layered documents resolve to: the flat shape the loop already takes, plus the parts of an

package/dist/spec/spec.js

@@ -241,10 +241,6 @@ const parseSampling = (report, path, value) => ({
  * @param value - What the document held under `model`.
  * @returns The fields that survived — an empty object where none did — or `undefined` where the
  * section is absent or is not an object.
- *
- * @remarks
- * `extraBody` comes back as a new object without the `RESERVED_BODY_FIELDS`, each of which is
- * warned about. An empty one survives as an empty one.
  */
 function parseModel(report, value) {
     if (absent(value)) {
@@ -253,31 +249,41 @@ function parseModel(report, value) {
     if (!isRecord(value)) {
         return void report.drop('model', 'must be an object');
     }
-    let extraBody;
-    if (!absent(value.extraBody)) {
-        if (!isRecord(value.extraBody)) {
-            report.drop('model.extraBody', 'must be an object');
-        }
-        else {
-            extraBody = {};
-            for (const [key, held] of Object.entries(value.extraBody)) {
-                // `buildBody` would overwrite them anyway; better to say so on import.
-                if (RESERVED_BODY_FIELDS.includes(key)) {
-                    report.drop(`model.extraBody.${key}`, "is the loop's to set");
-                }
-                else {
-                    extraBody[key] = held;
-                }
-            }
-        }
-    }
     return kept({
         model: report.string('model.model', value.model),
         ...parseSampling(report, 'model', value),
         contextLength: report.number('model.contextLength', value.contextLength, 0),
-        extraBody,
+        extraBody: parseExtraBody(report, 'model.extraBody', value.extraBody),
     });
 }
+/**
+ * Reads an `extraBody`, the agent's model's or a side task's.
+ *
+ * @param report - Where what is dropped is written.
+ * @param path - Where it sits in the document: `model.extraBody`, or `tasks.title.extraBody`.
+ * @param value - What the document held there.
+ * @returns A new object without the `RESERVED_BODY_FIELDS`, each of which is warned about, or
+ * `undefined` where it is absent or is not an object. An empty one survives as an empty one.
+ */
+function parseExtraBody(report, path, value) {
+    if (absent(value)) {
+        return undefined;
+    }
+    if (!isRecord(value)) {
+        return void report.drop(path, 'must be an object');
+    }
+    const extraBody = {};
+    for (const [key, held] of Object.entries(value)) {
+        // The request is built around them and they would be overwritten anyway; better to say so on import.
+        if (RESERVED_BODY_FIELDS.includes(key)) {
+            report.drop(`${path}.${key}`, "is the loop's to set");
+        }
+        else {
+            extraBody[key] = held;
+        }
+    }
+    return extraBody;
+}
 /**
  * Reads the `prompt` array, part by part.
  *
@@ -429,6 +435,7 @@ function parseTasks(report, value) {
             model: report.string(`${path}.model`, held.model),
             endpoint: parseEndpoint(report, `${path}.endpoint`, held.endpoint),
             ...parseSampling(report, path, held),
+            extraBody: parseExtraBody(report, `${path}.extraBody`, held.extraBody),
         });
     }
     return tasks;
@@ -767,16 +774,18 @@ function mergeById(items, idOf) {
  * @param layers - The documents, weakest first. None is written to.
  * @param endpoint - The agent's merged endpoint. Read, not written to.
  * @returns The tasks whose merged `model` is not empty, keyed as the documents keyed them — one a
- * layer declined with `model: ""` is not among them.
+ * layer declined with `model: ""` is not among them. A task's `extraBody` merges by key.
  */
 function resolveTasks(layers, endpoint) {
     const merged = new Map();
     for (const layer of layers) {
         for (const [key, task] of Object.entries(layer.tasks ?? {})) {
+            const below = merged.get(key);
             merged.set(key, {
-                ...(merged.get(key) ?? {}),
+                ...below,
                 ...task,
-                endpoint: mergeLayers([merged.get(key)?.endpoint, task.endpoint]),
+                endpoint: mergeLayers([below?.endpoint, task.endpoint]),
+                extraBody: mergeLayers([below?.extraBody, task.extraBody]),
             });
         }
     }
@@ -793,6 +802,7 @@ function resolveTasks(layers, endpoint) {
             maxTokens: task.maxTokens,
             temperature: task.temperature,
             reasoningEffort: task.reasoningEffort,
+            extraBody: task.extraBody && said(task.extraBody) ? task.extraBody : undefined,
         });
     }
     return tasks;

package/dist/tools/preselect.d.ts

@@ -158,6 +158,8 @@ export interface PreselectOptions {
     temperature?: number;
     /** As `SideTaskOptions.reasoningEffort`: absent keeps the no-thinking hints. */
     reasoningEffort?: string;
+    /** As `SideTaskOptions.extraBody`: sampler fields the options cannot spell. */
+    extraBody?: Record<string, unknown>;
     /**
      * The most tools the choice may name.
      *
@@ -181,8 +183,8 @@ export interface PreselectOptions {
  * `toolSelectModel: settings.toolSelectModel || settings.model`.
  * @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, the temperature and reasoning effort
- * as `ask` reads them, the cap the choice is held to, and whether to try the words first.
+ * @param [options] - Cancellation, notices, the reply ceiling, the temperature, reasoning effort and
+ * extra fields as `ask` reads them, the cap the choice is held to, and whether to try the words first.
  * @returns Names as the catalogue spells them, never more than `maxPerLoad`. Empty where `model` is
  * empty, the catalogue has no tools, the call failed, or its reply named nothing in the catalogue.
  *
@@ -198,4 +200,4 @@ export interface PreselectOptions {
  * starting now and starting in a few seconds. The words have to be clear about it; see
  * `preselectByKeywords` for what that means.
  */
-export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, temperature, reasoningEffort, maxPerLoad, keywords, }?: PreselectOptions): Promise<string[]>;
+export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, temperature, reasoningEffort, extraBody, maxPerLoad, keywords, }?: PreselectOptions): Promise<string[]>;

package/dist/tools/preselect.js

@@ -248,8 +248,8 @@ export function preselectByKeywords(catalog, prompt, { maxPerLoad = MAX_PER_LOAD
  * `toolSelectModel: settings.toolSelectModel || settings.model`.
  * @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, the temperature and reasoning effort
- * as `ask` reads them, the cap the choice is held to, and whether to try the words first.
+ * @param [options] - Cancellation, notices, the reply ceiling, the temperature, reasoning effort and
+ * extra fields as `ask` reads them, the cap the choice is held to, and whether to try the words first.
  * @returns Names as the catalogue spells them, never more than `maxPerLoad`. Empty where `model` is
  * empty, the catalogue has no tools, the call failed, or its reply named nothing in the catalogue.
  *
@@ -265,7 +265,7 @@ export function preselectByKeywords(catalog, prompt, { maxPerLoad = MAX_PER_LOAD
  * starting now and starting in a few seconds. The words have to be clear about it; see
  * `preselectByKeywords` for what that means.
  */
-export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, temperature, reasoningEffort, maxPerLoad = MAX_PER_LOAD, keywords, } = {}) {
+export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, temperature, reasoningEffort, extraBody, maxPerLoad = MAX_PER_LOAD, keywords, } = {}) {
     if (!model || !catalog.some((server) => server.tools.length > 0)) {
         return [];
     }
@@ -285,6 +285,7 @@ export async function preselect(config, model, catalog, prompt, { signal, onNoti
         maxTokens,
         temperature,
         reasoningEffort,
+        extraBody,
         signal,
         onNotice,
     }), { onNotice, signal });

package/dist/turn/side-task.d.ts

@@ -55,6 +55,16 @@ export interface SideTaskOptions {
      * refused it by value, and `chat_template_kwargs` is left out of the request altogether.
      */
     reasoningEffort?: string;
+    /**
+     * Request fields these options cannot spell, as `ModelParams.extraBody` is for the main model:
+     * `top_p`, `top_k`, `min_p` and the penalties a model card asks for.
+     *
+     * @remarks
+     * Merged in after the ceiling, temperature and thinking fields, so it may override them, and
+     * before `askJson`'s `response_format`. `model`, `messages`, `stream` and `tools` are dropped. A
+     * field the endpoint refuses by name is latched for the model and the request sent again without it.
+     */
+    extraBody?: Record<string, unknown>;
     /** Abandons the call, usually because the run it supports has gone away. */
     signal?: AbortSignal;
     /**
@@ -97,6 +107,8 @@ export interface SideTask {
     temperature?: number;
     /** As `SideTaskOptions.reasoningEffort`: a level replaces the no-thinking hints. */
     reasoningEffort?: string;
+    /** As `SideTaskOptions.extraBody`: the sampler fields a model card asks for, sent as given. */
+    extraBody?: Record<string, unknown>;
 }
 /**
  * Runs a side task and returns the reply text, thinking stripped. Throws like any request.
@@ -105,7 +117,7 @@ export interface SideTask {
  * @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, a reasoning effort, cancellation, notices.
+ * @param [options] - Reply ceiling, temperature, a reasoning effort, extra fields, cancellation, notices.
  * @returns The reply's content, trimmed. Where that is empty once the thinking is stripped, a
  * `reasoning_content` the server sent beside it, stripped the same way, or an empty string.
  */
@@ -219,6 +231,7 @@ export declare const listLines: (text: string, max: number, maxChars: number) =>
  * 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.
+ * `extraBody` is merged key by key, the task's keys winning, as layers merge it.
  * 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.
  *

package/dist/turn/side-task.js

@@ -1,5 +1,5 @@
 import { scoped } from '../core/scope.js';
-import { capabilitiesFor, ceilingAndTemperature, EFFORT_NONE, effortFor, modelCapabilitiesFor, negotiate, } from '../endpoint/capabilities.js';
+import { capabilitiesFor, ceilingAndTemperature, EFFORT_NONE, effortFor, extraFields, modelCapabilitiesFor, negotiate, } from '../endpoint/capabilities.js';
 import { endpointId, getClient, modelKey, resolveApiKey, sameUrl } from '../endpoint/client.js';
 import { relaxSchema, sanitizeSchema } from '../endpoint/schema-compat.js';
 import { errorMessage } from '../wire/errors.js';
@@ -68,7 +68,7 @@ export const resetHints = () => noHints().clear();
  * @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, a reasoning effort, cancellation, notices.
+ * @param [options] - Reply ceiling, temperature, a reasoning effort, extra fields, cancellation, notices.
  * @returns The reply's content, trimmed. Where that is empty once the thinking is stripped, a
  * `reasoning_content` the server sent beside it, stripped the same way, or an empty string.
  */
@@ -86,13 +86,14 @@ export function ask(config, model, system, user, options = {}) {
  * @param user - The input, sent as the user message as it was given.
  * @param options - A side task's options. A `reasoningEffort` that is a level leaves the
  * no-thinking hints out; absent, `""` or `"off"` sends them unless this pair has refused them.
+ * An `extraBody` goes out less the fields this model has refused by name.
  * @param [format] - Builds the extra body fields from the endpoint's capabilities and the model's.
  * Called on every send, so a re-send is built from what has been latched since. Absent adds none.
  * @returns The first choice's message as `answerOf` reads it, empty when there was no answer.
  * Throws what the request throws, except that a 400 or 422 `negotiate` did not answer, on a
  * request that carried the hints or an effort, is retried once without either.
  */
-async function complete(config, model, system, user, { maxTokens = 512, temperature = 0.3, reasoningEffort, signal, onNotice }, format) {
+async function complete(config, model, system, user, { maxTokens = 512, temperature = 0.3, reasoningEffort, extraBody, 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);
@@ -120,6 +121,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
             // Not gated on `hints`: a model that refuses `chat_template_kwargs` may still read the
             // effort, and the two latches would otherwise contradict each other.
             ...(sentEffort ? { reasoning_effort: asked } : {}),
+            ...extraFields(refused, extraBody),
             ...(format && refused ? format(supports, refused) : {}),
         }, { signal });
     };
@@ -131,6 +133,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
     const attempt = (hints, effort) => negotiate(supports, (latched, _produced, refused) => send(hints, effort, latched, refused), {
         model,
         onNotice,
+        droppable: Object.keys(extraBody ?? {}),
     });
     const key = modelKey(endpointId(config), model);
     // A chosen effort replaces the template hint rather than riding beside it: `enable_thinking:
@@ -333,6 +336,7 @@ export const listLines = (text, max, maxChars) => text
  * 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.
+ * `extraBody` is merged key by key, the task's keys winning, as layers merge it.
  * 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.
  *
@@ -356,6 +360,9 @@ export function taskCall(task, options, agent) {
     if (task.reasoningEffort !== undefined) {
         stated.reasoningEffort = task.reasoningEffort;
     }
+    if (task.extraBody !== undefined) {
+        stated.extraBody = { ...options?.extraBody, ...task.extraBody };
+    }
     return {
         endpoint: agent
             ? {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "4.2.0",
+  "version": "4.3.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",