@cubicecho/agent-core 4.3.0 → 4.5.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:
@@ -797,9 +815,15 @@ once `used` (the last turn's prompt tokens, or the estimate) is past three quart
 The kept tail fills at most 35% of it and starts on a user message, since a transcript resuming
 mid-exchange is one servers refuse; leading system prompts are never folded, and an earlier
 summary is continued rather than summarised. `compactTranscript` writes the summary and tells
-`beforeCompact` hooks what is going while it does. Because the cut lands on
-a user message, one long tool run under a single question has nothing to fold — pruning is what
-keeps that one going.
+`beforeCompact` hooks what is going while it does.
+
+A run that is one question and a long tool loop has no user message to cut at, so there the plan
+cuts inside the loop instead: the question is kept whole (the plan's `question`), the calls and
+results after it are folded up to an assistant message, and the request becomes the summary, the
+question, then the rest of the loop — every tool result still after its call. A transcript with a
+user message to cut at is planned as before. `runAgentLoop({ compact: true })` folds such a run on
+its own; a host that numbers messages across steps passes `hooks.offset`, the stored index of the
+run's first message, so the ids `beforeCompact` is told match its own.
 
 ```ts
 beforeStep: async (messages, step) => {
@@ -932,8 +956,8 @@ leading `system` messages, and reads an earlier summary back out of a `SUMMARY_L
 them. A host whose system prompt is a separate argument and whose summary is a column has neither
 in the array, and knows both exactly. Given them, nothing is scanned.
 
-`applyCompaction(messages, fold)` is the way back — the summary as a `system` message, then
-everything from `through` — and it writes the same `SUMMARY_LEAD` `planCompaction` looks for, so
+`applyCompaction(messages, fold)` is the way back — the summary as a `system` message, then the
+fold's `question` if it was made inside one, then everything from `through` — and it writes the same `SUMMARY_LEAD` `planCompaction` looks for, so
 the next fold continues those notes rather than summarising them a second time. No fold yet hands
 back the messages themselves.
 

package/dist/context/compaction.d.ts

@@ -125,9 +125,17 @@ export interface CompactionOptions {
 export interface CompactionPlan {
     /** The first message folded away. Everything before it is a system prompt and stays. */
     from: number;
-    /** The first message kept whole, always a user message. */
+    /**
+     * The first message kept whole: a user message, or an assistant message on a fold made inside
+     * one question's tool loop (see `question`).
+     */
     cut: number;
-    /** The messages from `from` to `cut`, the ones the summary replaces. */
+    /**
+     * The user message kept whole between the summary and `cut`, on a fold made inside its tool
+     * loop. Absent on a fold that cuts at a user message.
+     */
+    question?: number;
+    /** The messages from `from` to `cut`, `question` left out: the ones the summary replaces. */
     toSummarise: Message[];
     /** The summary an earlier compaction left, which this one continues. */
     previous?: string;
@@ -155,6 +163,13 @@ export interface CompactionPlan {
  * than summarised as if it were conversation. No plan comes back when the window is not full
  * enough, or when the only legal cut folds too little to pay for the summary.
  *
+ * A transcript that is one question and a long tool loop has no user message to cut at, so where
+ * no user cut folds anything the plan cuts inside the last question's loop instead: the question
+ * is kept whole as `question`, the assistant and tool messages after it are folded up to an
+ * assistant message, and the tail resumes there — every tool result in it still follows its call.
+ * `applyCompaction` sends the question after the summary. A transcript with a user cut is planned
+ * exactly as it was.
+ *
  * Both of those are recovered by reading the transcript, which is what a host whose array holds
  * everything it sends has to do. A host that keeps its fold as a record beside an append-only
  * transcript — its system prompt a separate argument, no summary message in the array at all —
@@ -206,6 +221,11 @@ export interface CompactionRecord {
     summary: string;
     /** Index into the transcript the plan was made for: the first message still sent whole. */
     through: number;
+    /**
+     * The user message sent whole after the summary and ahead of `through`, on a fold made inside
+     * that question's tool loop. Absent on a fold that cut at a user message.
+     */
+    question?: number;
     /** ISO 8601, so the chat can show where history was folded and how stale the notes are. */
     at: string;
 }
@@ -213,7 +233,8 @@ export interface CompactionRecord {
 export interface CompactionRunOptions {
     /**
      * Hooks to tell. `context` is extended with `compacting` and `range`, whose indexes are the
-     * plan's — and so the host's own, for a plan made over a stored transcript. `honourVeto` waits
+     * plan's — and so the host's own, for a plan made over a stored transcript. `compacting` leaves
+     * out a `question` the fold keeps. `honourVeto` waits
      * for the hooks and lets one stop the compaction; without it they add no latency.
      */
     hooks?: {
@@ -221,6 +242,14 @@ export interface CompactionRunOptions {
         context: HookContext;
         onNote?: OnNote;
         honourVeto?: boolean;
+        /**
+         * What the transcript's first message is numbered as in the `compacting` uuids: the host's
+         * stored index of `messages[0]`, for a host that numbers messages across steps or requests.
+         * See `turnMessages`.
+         *
+         * @defaultValue `0`
+         */
+        offset?: number;
     };
     /**
      * The window is already exceeded — the caller caught a `ContextOverflow`, or is compacting to
@@ -256,7 +285,8 @@ export declare function runCompaction(messages: Message[], plan: CompactionPlan,
  * Absent, the leading `system` messages are found by scanning, and zero of them is the ordinary
  * case for a host whose system prompt is a separate argument.
  * @returns `messages` itself when there is no record or its summary is blank, otherwise a new
- * array: the kept head, one summary message, then everything from the record's `through` on.
+ * array: the kept head, one summary message, the record's `question` when it has one and the head
+ * does not already hold it, then everything from the record's `through` on.
  *
  * @remarks
  * The inverse of storing a `CompactionRecord`, and the shape `planCompaction` expects to meet
@@ -264,7 +294,7 @@ export declare function runCompaction(messages: Message[], plan: CompactionPlan,
  * continues these notes rather than summarising them a second time. Any earlier summary message in
  * the kept head is dropped, since the record's already contains it.
  */
-export declare function applyCompaction(messages: Message[], record?: Pick<CompactionRecord, 'summary' | 'through'>, { from }?: {
+export declare function applyCompaction(messages: Message[], record?: Pick<CompactionRecord, 'summary' | 'through' | 'question'>, { from }?: {
     from?: number;
 }): Message[];
 /**
@@ -278,7 +308,8 @@ export declare function applyCompaction(messages: Message[], record?: Pick<Compa
  * prompts, when the host keeps them in the array. Zero is the stored-fold case,
  * where the summary is the request's first message.
  * @returns The index in the request. One before the record's `through` gives `head`, where the
- * summary sits — an index among the kept head messages themselves included.
+ * summary sits — an index among the kept head messages themselves included — except the record's
+ * `question`, which is sent whole right after the summary.
  *
  * @remarks
  * A transcript that stays append-only and a request that does not are two numberings of the same
@@ -286,7 +317,7 @@ export declare function applyCompaction(messages: Message[], record?: Pick<Compa
  * hook — has to say which it is in. An index inside the folded stretch answers with the summary
  * message that now stands for it.
  */
-export declare const requestIndex: (index: number, record?: Pick<CompactionRecord, 'through'>, head?: number) => number;
+export declare const requestIndex: (index: number, record?: Pick<CompactionRecord, 'through' | 'question'>, head?: number) => number;
 /**
  * The transcript with the plan's stretch replaced by one system message holding its summary.
  *

package/dist/context/compaction.js

@@ -142,6 +142,56 @@ export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}
  * @returns `index` where it lies from zero to `most`, otherwise the nearer of the two.
  */
 const clamp = (index, most) => Math.min(Math.max(index, 0), most);
+/**
+ * Where to cut, by `target` when there is one and by `keepRatio` otherwise, among the indexes
+ * `isCut` allows.
+ *
+ * @param messages - The transcript. Not written to.
+ * @param search - The weights, the bounds and which indexes are legal cuts. See `CutSearch`.
+ * @returns `cut`, the length of `messages` when no legal cut was found, and on a plan made to a
+ * `target` the cost it leaves as `after`.
+ */
+const findCut = (messages, { from, cost, limit, keepRatio, target, summaryTokens, estimate, isCut, kept }) => {
+    let cut = messages.length;
+    let after;
+    if (target !== undefined && target > 0) {
+        // Forward from the head, so the first cut that reaches the target is the one that folds least.
+        let folded = 0;
+        for (let at = from; at < messages.length; at++) {
+            if (isCut(at)) {
+                cut = at;
+                after = cost - folded + summaryTokens;
+                if (after <= limit * target) {
+                    break;
+                }
+            }
+            if (at !== kept) {
+                folded += estimate(messages[at]);
+            }
+        }
+        return { cut, after };
+    }
+    const budget = limit * keepRatio;
+    let tail = 0;
+    for (let at = messages.length - 1; at > from; at--) {
+        tail += estimate(messages[at]);
+        if (tail > budget) {
+            break;
+        }
+        cut = at;
+    }
+    while (cut < messages.length && isCut(cut) === false) {
+        cut++;
+    }
+    return { cut };
+};
+/**
+ * The index of the last user message in a transcript.
+ *
+ * @param messages - The transcript.
+ * @returns The index, or `-1` when there is none.
+ */
+const lastUser = (messages) => messages.findLastIndex((message) => message.role === Role.User);
 /**
  * Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
  *
@@ -159,6 +209,13 @@ const clamp = (index, most) => Math.min(Math.max(index, 0), most);
  * than summarised as if it were conversation. No plan comes back when the window is not full
  * enough, or when the only legal cut folds too little to pay for the summary.
  *
+ * A transcript that is one question and a long tool loop has no user message to cut at, so where
+ * no user cut folds anything the plan cuts inside the last question's loop instead: the question
+ * is kept whole as `question`, the assistant and tool messages after it are folded up to an
+ * assistant message, and the tail resumes there — every tool result in it still follows its call.
+ * `applyCompaction` sends the question after the summary. A transcript with a user cut is planned
+ * exactly as it was.
+ *
  * Both of those are recovered by reading the transcript, which is what a host whose array holds
  * everything it sends has to do. A host that keeps its fold as a record beside an append-only
  * transcript — its system prompt a separate argument, no summary message in the array at all —
@@ -184,47 +241,53 @@ export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT,
     const head = systemHead(messages);
     const from = clamp(givenFrom ?? head.from, messages.length);
     const previous = givenPrevious ?? head.previous;
-    let cut = messages.length;
-    let after;
-    if (target !== undefined && target > 0) {
-        // Forward from the head, so the first cut that reaches the target is the one that folds least.
-        let folded = 0;
-        for (let at = from; at < messages.length; at++) {
-            if (messages[at].role === Role.User) {
-                cut = at;
-                after = cost - folded + summaryTokens;
-                if (after <= limit * target) {
-                    break;
-                }
-            }
-            folded += estimate(messages[at]);
-        }
+    const search = { from, cost, limit, keepRatio, target, summaryTokens, estimate };
+    const atUser = findCut(messages, { ...search, isCut: (at) => messages[at].role === Role.User });
+    const foldsAtUser = atUser.cut < messages.length && atUser.cut - from >= FEWEST_FOLDED;
+    if (foldsAtUser) {
+        return planFor(messages, from, atUser.cut, previous, atUser.after);
     }
-    else {
-        const budget = limit * keepRatio;
-        let kept = 0;
-        for (let at = messages.length - 1; at > from; at--) {
-            kept += estimate(messages[at]);
-            if (kept > budget) {
-                break;
-            }
-            cut = at;
-        }
-        while (cut < messages.length && messages[cut].role !== Role.User) {
-            cut++;
-        }
+    // A cut that folds too little but already reaches the target means there is nothing to fold.
+    const reachesTarget = target !== undefined && atUser.after !== undefined && atUser.after <= limit * target;
+    if (reachesTarget) {
+        return undefined;
     }
-    if (cut >= messages.length || cut - from < FEWEST_FOLDED) {
+    // No user message to cut at: fold inside the last question's tool loop, keeping the question.
+    const question = lastUser(messages);
+    if (question < 0) {
         return undefined;
     }
-    return {
-        from,
-        cut,
-        toSummarise: messages.slice(from, cut),
-        ...(previous ? { previous } : {}),
-        ...(after === undefined ? {} : { after: Math.round(after) }),
-    };
+    const inLoop = findCut(messages, {
+        ...search,
+        isCut: (at) => at > question && messages[at].role === Role.Assistant,
+        kept: question,
+    });
+    if (inLoop.cut >= messages.length) {
+        return undefined;
+    }
+    const folded = planFor(messages, from, inLoop.cut, previous, inLoop.after, question);
+    return folded.toSummarise.length >= FEWEST_FOLDED ? folded : undefined;
 }
+/**
+ * A plan for a cut `planCompaction` has chosen.
+ *
+ * @param messages - The transcript. Not written to.
+ * @param from - The first message folded.
+ * @param cut - The first message kept whole.
+ * @param [previous] - The summary this one continues.
+ * @param [after] - What the request is expected to cost once folded, on a plan made to a target.
+ * @param [question] - The user message kept whole ahead of `cut`, on a fold inside its tool loop.
+ * Left out of `toSummarise` where it lies between `from` and `cut`.
+ * @returns The plan, `toSummarise` a new array of the same message objects.
+ */
+const planFor = (messages, from, cut, previous, after, question) => ({
+    from,
+    cut,
+    ...(question === undefined ? {} : { question }),
+    toSummarise: messages.slice(from, cut).filter((_, at) => at + from !== question),
+    ...(previous ? { previous } : {}),
+    ...(after === undefined ? {} : { after: Math.round(after) }),
+});
 /**
  * What the summariser is handed for a plan: the earlier summary if there was one, then each
  * message as its role and at most 4000 characters of its text.
@@ -256,6 +319,22 @@ export function summaryInput(plan) {
  * resolves with an empty string where the model wrote nothing.
  */
 export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens = SUMMARY_TOKENS, ...options } = {}) => (text) => ask(config, model, system, text, { maxTokens, ...options });
+/**
+ * What `beforeCompact` hooks are told is going: the plan's stretch as `turnMessages` reads it,
+ * less the question the fold keeps.
+ *
+ * @param sessionId - Prefixes every uuid.
+ * @param messages - The transcript the plan was made for.
+ * @param plan - What `planCompaction` returned for it.
+ * @param [offset] - What `messages[0]` is numbered as in the uuids.
+ * @returns The user and assistant text from `plan.from` to `plan.cut`, `plan.question` left out.
+ */
+const foldedMessages = (sessionId, messages, plan, offset = 0) => {
+    const { from, cut, question } = plan;
+    const read = (start, end) => turnMessages(sessionId, messages, start, end, { offset });
+    const splitsAtQuestion = question !== undefined && question >= from && question < cut;
+    return splitsAtQuestion ? [...read(from, question), ...read(question + 1, cut)] : read(from, cut);
+};
 /**
  * The hooks and the summariser for a plan, as a record to store rather than a transcript to send.
  *
@@ -275,7 +354,7 @@ export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens =
 export async function runCompaction(messages, plan, summarise, { hooks, forced = false } = {}) {
     const context = hooks && {
         ...hooks.context,
-        compacting: turnMessages(hooks.context.session.id, messages, plan.from, plan.cut),
+        compacting: foldedMessages(hooks.context.session.id, messages, plan, hooks.offset),
         range: { from: plan.from, through: plan.cut },
     };
     let summary;
@@ -295,7 +374,12 @@ export async function runCompaction(messages, plan, summarise, { hooks, forced =
     if (!summary.trim()) {
         return undefined;
     }
-    return { summary: summary.trim(), through: plan.cut, at: new Date().toISOString() };
+    return {
+        summary: summary.trim(),
+        through: plan.cut,
+        ...(plan.question === undefined ? {} : { question: plan.question }),
+        at: new Date().toISOString(),
+    };
 }
 /**
  * The transcript as the server should see it: the folded head replaced by its summary.
@@ -308,7 +392,8 @@ export async function runCompaction(messages, plan, summarise, { hooks, forced =
  * Absent, the leading `system` messages are found by scanning, and zero of them is the ordinary
  * case for a host whose system prompt is a separate argument.
  * @returns `messages` itself when there is no record or its summary is blank, otherwise a new
- * array: the kept head, one summary message, then everything from the record's `through` on.
+ * array: the kept head, one summary message, the record's `question` when it has one and the head
+ * does not already hold it, then everything from the record's `through` on.
  *
  * @remarks
  * The inverse of storing a `CompactionRecord`, and the shape `planCompaction` expects to meet
@@ -321,12 +406,22 @@ export function applyCompaction(messages, record, { from } = {}) {
         return messages;
     }
     const head = clamp(from ?? systemHead(messages).from, record.through);
+    const question = keptQuestion(record, head);
     return [
         ...messages.slice(0, head).filter((message) => !isSummary(message)),
         summaryMessage(record.summary),
+        ...(question === undefined ? [] : [messages[question]]),
         ...messages.slice(record.through),
     ];
 }
+/**
+ * The question a fold sends after its summary, unless the kept head already holds it.
+ *
+ * @param record - The fold.
+ * @param head - How many messages are kept ahead of the summary.
+ * @returns `record.question` where it lies from `head` up to `through`, otherwise `undefined`.
+ */
+const keptQuestion = ({ question, through }, head) => question !== undefined && question >= head && question < through ? question : undefined;
 /**
  * Where a stored index sits in the request `applyCompaction` builds, once a fold has shifted
  * everything after it.
@@ -338,7 +433,8 @@ export function applyCompaction(messages, record, { from } = {}) {
  * prompts, when the host keeps them in the array. Zero is the stored-fold case,
  * where the summary is the request's first message.
  * @returns The index in the request. One before the record's `through` gives `head`, where the
- * summary sits — an index among the kept head messages themselves included.
+ * summary sits — an index among the kept head messages themselves included — except the record's
+ * `question`, which is sent whole right after the summary.
  *
  * @remarks
  * A transcript that stays append-only and a request that does not are two numberings of the same
@@ -350,7 +446,12 @@ export const requestIndex = (index, record, head = 0) => {
     if (!record) {
         return index;
     }
-    return index < record.through ? head : index - record.through + head + 1;
+    const question = keptQuestion(record, head);
+    if (index === question) {
+        return head + 1;
+    }
+    const afterSummary = question === undefined ? 1 : 2;
+    return index < record.through ? head : index - record.through + head + afterSummary;
 };
 /**
  * The transcript with the plan's stretch replaced by one system message holding its summary.

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/agent-loop.d.ts

@@ -70,6 +70,14 @@ export interface AgentLoopHooks {
     preface?: string;
     /** Hears each note, from before the request and from `afterTurn`. */
     onNote?: OnNote;
+    /**
+     * What the run's first message is numbered as in the uuids hooks are told — the host's stored
+     * index of `messages[0]`, for a host that numbers messages across steps or runs. Read for
+     * `beforeCompact`'s `compacting` and `afterTurn`'s `turn`. See `turnMessages`.
+     *
+     * @defaultValue `0`
+     */
+    offset?: number;
 }
 /** How full the window is as a step is about to be sent, as `beforeStep` is told it. */
 export interface StepWindow {

package/dist/run/agent-loop.js

@@ -235,10 +235,10 @@ async function foldBeforeStep(transcript, reported, summarise, { options, charsP
         return transcript;
     }
     const folded = await compactTranscript(transcript, plan, summarise, {
-        ...(hooks ? { hooks: { run: hooks.run, context: hooks.context, onNote: hooks.onNote } } : {}),
+        ...(hooks ? { hooks: { run: hooks.run, context: hooks.context, onNote: hooks.onNote, offset: hooks.offset } } : {}),
     });
     if (folded !== transcript) {
-        notice(`compacted ${plan.cut - plan.from} messages into a summary`);
+        notice(`compacted ${plan.toSummarise.length} messages into a summary`);
     }
     return folded;
 }
@@ -260,7 +260,7 @@ const tellAfterTurn = (hooks, messages, at, reply) => notify(hooks.run, HookEven
         ? {
             turn: {
                 index: turnIndex(messages, at),
-                messages: turnMessages(hooks.context.session.id, messages, at),
+                messages: turnMessages(hooks.context.session.id, messages, at, undefined, { offset: hooks.offset }),
             },
         }
         : {}),

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