@cubicecho/agent-core 4.3.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:

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/turn/side-task.d.ts

@@ -122,6 +122,33 @@ export interface SideTask {
  * `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 {
     /**
@@ -150,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
@@ -216,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
@@ -227,7 +254,7 @@ 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.

package/dist/turn/side-task.js

@@ -72,7 +72,27 @@ export const resetHints = () => noHints().clear();
  * @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);
 }
 /**
@@ -89,8 +109,8 @@ export function ask(config, model, system, user, options = {}) {
  * 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, extraBody, signal, onNotice }, format) {
@@ -168,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.
@@ -204,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
@@ -217,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,
@@ -229,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.
@@ -321,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
@@ -332,7 +354,7 @@ 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.

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.3.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",