@cubicecho/agent-core 4.2.0 → 4.4.0

package/README.md

@@ -268,6 +268,24 @@ const page: SideTaskInput = [
 const text = await ask(config, visionModel, "You are an OCR engine.", page);
 ```
 
+### Telling a finished reply from a cut-off one
+
+`ask` returns the text alone, so a reply that ran into `maxTokens` reads like one that finished.
+Where the reply is the product, `askReply` takes the same arguments and also returns the choice's
+`finish_reason` as the server sent it, or `undefined` where it sent none. A model looping on a page
+writes until the ceiling stops it, and a transcript saved from that is worse than none:
+
+```ts
+const { text, finishReason } = await askReply(config, visionModel, "You are an OCR engine.", page);
+if (finishReason === FinishReason.Length) {
+  // cut off: retry with a higher ceiling, or keep the OCR text already there
+}
+```
+
+Nothing is thrown for a cut-off reply, since whether one is still worth keeping is the caller's
+call. `askJson` needs no such variant: a reply cut off before its JSON closed does not parse, so it
+comes back `undefined`, as a reply with no JSON in it does.
+
 ## Sizing a request before sending it
 
 `runTurn` will refuse a request that cannot fit rather than spending a round trip finding out:
@@ -588,7 +606,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 +1214,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 +1235,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/index.d.ts

@@ -31,7 +31,7 @@ export { type KeywordPreselection, type KeywordPreselectOptions, PRESELECT_SCHEM
 export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, type ToolOrder, } from './tools/tool-loading.ts';
 export { type ContinueTurnOptions, continueTurn, } from './turn/continuation.ts';
 export { type RunTurnOptions, runTurn } from './turn/run-turn.ts';
-export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTask, type SideTaskInput, type SideTaskOptions, taskCall, tryAsk, } from './turn/side-task.ts';
+export { type AskJsonOptions, ask, askJson, askReply, clean, listLines, parseJson, resetHints, type SideTask, type SideTaskInput, type SideTaskOptions, type SideTaskReply, taskCall, tryAsk, } from './turn/side-task.ts';
 export { AgentLoopError, type AgentLoopFailure, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from './wire/errors.ts';
 export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, SMALLEST_LIKELY_WINDOW, } from './wire/retry.ts';
 export { CacheBreakReason, type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from './wire/stream.ts';

package/dist/index.js

@@ -30,7 +30,7 @@ export { PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, pre
 export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, orderTools, PROXY_TOOLS, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, } from './tools/tool-loading.js';
 export { continueTurn, } from './turn/continuation.js';
 export { runTurn } from './turn/run-turn.js';
-export { ask, askJson, clean, listLines, parseJson, resetHints, taskCall, tryAsk, } from './turn/side-task.js';
+export { ask, askJson, askReply, clean, listLines, parseJson, resetHints, taskCall, tryAsk, } from './turn/side-task.js';
 export { AgentLoopError, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from './wire/errors.js';
 export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, SMALLEST_LIKELY_WINDOW, } from './wire/retry.js';
 export { CacheBreakReason, streamTurn, } from './wire/stream.js';

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,11 +117,38 @@ 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.
  */
 export declare function ask(config: Endpoint, model: string, system: string, user: SideTaskInput, options?: SideTaskOptions): Promise<string>;
+/** A side task's reply, with why the model stopped writing it. */
+export interface SideTaskReply {
+    /** The reply's content as `ask` returns it: trimmed, thinking stripped. */
+    text: string;
+    /**
+     * The first choice's `finish_reason` as the server sent it, compared with `FinishReason`.
+     * `FinishReason.Length` means `text` was cut off at the ceiling. Undefined when none was sent.
+     */
+    finishReason: string | undefined;
+}
+/**
+ * Runs a side task as `ask` does, and says why the reply ended as well as what it said.
+ *
+ * @param config - Where to send it and how long to wait.
+ * @param model - The model to ask.
+ * @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, extra fields, cancellation, notices.
+ * @returns The text `ask` would return, and the `finish_reason` it came with.
+ *
+ * @remarks
+ * For a caller whose reply is the product, such as a page's transcript: one that ran into the
+ * ceiling, often because the model was looping, reads like a finished one in its text alone.
+ * Nothing is thrown for it, because whether a cut-off reply is still worth keeping is the
+ * caller's call.
+ */
+export declare function askReply(config: Endpoint, model: string, system: string, user: SideTaskInput, options?: SideTaskOptions): Promise<SideTaskReply>;
 /** What `askJson` takes besides a side task's options. */
 export interface AskJsonOptions extends SideTaskOptions {
     /**
@@ -138,7 +177,7 @@ export interface AskJsonOptions extends SideTaskOptions {
  * @param schema - The JSON Schema of the answer. Its root is held to an object, as a tool's is.
  * @param [options] - A side task's options, plus the schema's `name` and whether it is `strict`.
  * @returns What the reply parsed to, unchecked against the schema: `T` is the caller's claim.
- * `undefined` when `parseJson` found nothing in it.
+ * `undefined` when `parseJson` found nothing in it, as in a reply cut off before its JSON closed.
  *
  * @remarks
  * Sends `response_format` with the schema, which a llama.cpp server compiles into a grammar and
@@ -204,7 +243,7 @@ export declare const clean: (line: string) => string;
 export declare const listLines: (text: string, max: number, maxChars: number) => 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.
+ * `ask`, `askReply`, `askJson`, `summariser` and `preselect` take last.
  *
  * @param task - The task, ordinarily `resolved.tasks.<key>`.
  * @param [options] - What the host adds — cancellation, notices, `keywords` — and its own defaults
@@ -215,10 +254,11 @@ export declare const listLines: (text: string, max: number, maxChars: number) =>
  * `endpoint` is the task's own object when no `agent` was given, a copy otherwise.
  *
  * @remarks
- * A helper rather than a second signature on each of the four, so a setting added to a task later
+ * A helper rather than a second signature on each entry point, 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.
+ * `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,11 +68,31 @@ 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.
  */
-export function ask(config, model, system, user, options = {}) {
+export async function ask(config, model, system, user, options = {}) {
+    const { text } = await complete(config, model, system, user, options);
+    return text;
+}
+/**
+ * Runs a side task as `ask` does, and says why the reply ended as well as what it said.
+ *
+ * @param config - Where to send it and how long to wait.
+ * @param model - The model to ask.
+ * @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, extra fields, cancellation, notices.
+ * @returns The text `ask` would return, and the `finish_reason` it came with.
+ *
+ * @remarks
+ * For a caller whose reply is the product, such as a page's transcript: one that ran into the
+ * ceiling, often because the model was looping, reads like a finished one in its text alone.
+ * Nothing is thrown for it, because whether a cut-off reply is still worth keeping is the
+ * caller's call.
+ */
+export function askReply(config, model, system, user, options = {}) {
     return complete(config, model, system, user, options);
 }
 /**
@@ -86,13 +106,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
+ * @returns The first choice's message as `answerOf` reads it, empty when there was no answer, and
+ * its `finish_reason`. 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 +141,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 +153,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:
@@ -165,7 +188,9 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
             modelCapabilitiesFor(supports, model).reasoningEffort = false;
         }
     }
-    return answerOf(response.choices[0]?.message);
+    const [choice] = response.choices;
+    // Typed as always present, and sent as `null` or not at all by servers that have none to give.
+    return { text: answerOf(choice?.message), finishReason: choice?.finish_reason ?? undefined };
 }
 /**
  * A reply's answer, thinking stripped, or its scratchpad where the answer is nothing else.
@@ -201,7 +226,7 @@ function answerOf(message) {
  * @param schema - The JSON Schema of the answer. Its root is held to an object, as a tool's is.
  * @param [options] - A side task's options, plus the schema's `name` and whether it is `strict`.
  * @returns What the reply parsed to, unchecked against the schema: `T` is the caller's claim.
- * `undefined` when `parseJson` found nothing in it.
+ * `undefined` when `parseJson` found nothing in it, as in a reply cut off before its JSON closed.
  *
  * @remarks
  * Sends `response_format` with the schema, which a llama.cpp server compiles into a grammar and
@@ -214,7 +239,7 @@ function answerOf(message) {
 export async function askJson(config, model, system, user, schema, { name = 'answer', strict = true, ...options } = {}) {
     const sanitized = sanitizeSchema(schema);
     const instruction = `${system}\n\nReply with JSON alone, matching this JSON Schema:\n${JSON.stringify(sanitized)}`;
-    const reply = await complete(config, model, instruction, user, options, (supports, refused) => refused.structuredOutput
+    const { text } = await complete(config, model, instruction, user, options, (supports, refused) => refused.structuredOutput
         ? {
             response_format: {
                 type: JSON_SCHEMA_FORMAT,
@@ -226,7 +251,7 @@ export async function askJson(config, model, system, user, schema, { name = 'ans
             },
         }
         : {});
-    return parseJson(reply);
+    return parseJson(text);
 }
 /**
  * Runs a side task and answers `undefined` where it fails, so the work it supports carries on.
@@ -318,7 +343,7 @@ export const listLines = (text, max, maxChars) => text
     .slice(0, max);
 /**
  * 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.
+ * `ask`, `askReply`, `askJson`, `summariser` and `preselect` take last.
  *
  * @param task - The task, ordinarily `resolved.tasks.<key>`.
  * @param [options] - What the host adds — cancellation, notices, `keywords` — and its own defaults
@@ -329,10 +354,11 @@ export const listLines = (text, max, maxChars) => text
  * `endpoint` is the task's own object when no `agent` was given, a copy otherwise.
  *
  * @remarks
- * A helper rather than a second signature on each of the four, so a setting added to a task later
+ * A helper rather than a second signature on each entry point, 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.
+ * `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 +382,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/llms.txt

@@ -305,6 +305,7 @@ One-shot calls that support a run without being one: picking tools, naming a ses
 - `AskJsonOptions` (type) — What `askJson` takes besides a side task's options.
 - `ask` — Runs a side task and returns the reply text, thinking stripped.
 - `askJson` — A side task whose answer is JSON matching a schema, parsed.
+- `askReply` — Runs a side task as `ask` does, and says why the reply ended as well as what it said.
 - `clean` — Strips the quoting and list punctuation models decorate short answers with.
 - `listLines` — A list-shaped reply, one item per line, cleaned of the bullets and quotes models decorate them with.
 - `parseJson` — The first array or object in a model's reply, parsed, whatever prose or fence surrounds it.
@@ -312,7 +313,8 @@ One-shot calls that support a run without being one: picking tools, naming a ses
 - `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.
-- `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.
+- `SideTaskReply` (type) — A side task's reply, with why the model stopped writing it.
+- `taskCall` — A side task's settings as the call that honours them: its endpoint, its model, and the options `ask`, `askReply`, `askJson`, `summariser` and `preselect` take last.
 - `tryAsk` — Runs a side task and answers `undefined` where it fails, so the work it supports carries on.
 
 ### errors

package/package.json

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