@cubicecho/agent-core 4.19.0 → 4.20.0

package/README.md

@@ -610,8 +610,10 @@ string. What still is not an object throws a `ToolArgumentsError` whose `kind` i
 the turn stopped at the ceiling, with a message telling the model so, and `malformed` otherwise.
 The repaired JSON is what the transcript keeps, and an unreadable call is replayed as `{}`, because
 a server that parses replayed arguments refuses the originals on every later request. `dispatch`
-is still handed the model's own text as `raw`, and the dedupe compares repaired arguments,
-so `{'a': 1}` and `{"a": 1}` are one call.
+is still handed the model's own text as `raw`, with `repaired` true where reading it took a repair
+— whitespace and blank arguments do not count — and the dedupe compares repaired arguments, so
+`{'a': 1}` and `{"a": 1}` are one call. A call recovered from text, below, is always `repaired`,
+and its `raw` is the arguments recovery read out of the reply, as JSON.
 
 A server whose tool-call parser was written for another template streams the model's call as
 plain text, and the run ends on a reply that is nothing but a call nobody made. Unless
@@ -969,7 +971,11 @@ try {
 
 `onMessage` hears the assistant message as it will be replayed — recovered calls folded in, and
 arguments repaired, which the turn `onTurn` is handed does not show — together with that `Turn`,
-and then each tool result, in transcript order. `onTurn` is not awaited and never sees a tool
+and then each tool result, in transcript order. Beside an assistant message the model wrote comes a
+fourth argument, `{ raw }`: the same message as the model produced it, its text whole with any call
+written into it left there, and its calls' arguments exactly as streamed, under the same ids. Store
+or show `raw` to keep what the model said; replay `message` to keep what an endpoint will take back.
+The loop's own messages — a proxied run's preselected load — come without it. `onTurn` is not awaited and never sees a tool
 result; this is the one to store from. What it returns is ignored, since `beforeStep` is the one way to rewrite
 the transcript, and what it throws ends the run.
 

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools,
 export { CACHE_PROMPT_FIELD, resetSlots, SESSION_HEADER, SLOT_FIELD, type SlotAllocator, slotAllocator, } from './endpoint/slots.ts';
 export { HOOK_EVENTS, HookEvent, INJECT_EVENTS } from './hooks/hook-events.ts';
 export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, type HookContext, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from './hooks/hooks.ts';
-export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, PRESELECT_APPEND, PRESELECT_EXCLUSIVE, PRESELECTED_NOTICE, runAgentLoop, type StepWindow, } from './run/agent-loop.ts';
+export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, PRESELECT_APPEND, PRESELECT_EXCLUSIVE, PRESELECTED_NOTICE, runAgentLoop, type StepWindow, type WrittenMessage, } from './run/agent-loop.ts';
 export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type LoadCounts, type RunEvent, type RunEventInput, RunEventKind, type RunMetrics, type RunMetricsOptions, RunOutcome, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from './run/events.ts';
 export { buildBody } from './run/request-body.ts';
 export { preview, type ToolDispatch } from './run/run-calls.ts';

package/dist/run/agent-loop.d.ts

@@ -23,6 +23,24 @@ import { type ToolDispatch } from './run-calls.ts';
  * and two never did. What is here is the part that does not know what the run is for; the
  * prompts, the tools and what a run means stay with the caller.
  */
+/**
+ * What `onMessage` is handed beside an assistant message the model wrote: that message as the model
+ * produced it.
+ *
+ * @remarks
+ * The message `onMessage` is handed is what later requests replay — arguments repaired, `{}` for
+ * none, recovered calls taken out of the text and made calls — which is right to send and quietly
+ * wrong to show as the model's. Absent for a message the loop wrote itself, such as a proxied
+ * run's preselected load.
+ */
+export interface WrittenMessage {
+    /**
+     * The reply as it streamed: its text whole, a call written into it as text left there, and the
+     * calls it sent as calls with their arguments as streamed. A call that never got a name is left
+     * off, since nothing answers it. Ids are the turn's, so the tool results pair with either.
+     */
+    raw: OpenAI.ChatCompletionAssistantMessageParam;
+}
 /**
  * One step's request as `onRequest` is handed it: what the model is about to read.
  *
@@ -459,8 +477,12 @@ export interface AgentLoopOptions {
      * a proxied run writes for its `preselected` shortlist, told as step zero's before any request.
      * What it returns is ignored: `beforeStep` is the one way to rewrite the transcript. What it
      * throws ends the run, and it is not called again for that run.
+     *
+     * Beside an assistant message the model wrote comes `written`, whose `raw` is the message as the
+     * model produced it, for a host that shows or stores what was said rather than what is replayed.
+     * See `WrittenMessage`.
      */
-    onMessage?: (message: OpenAI.ChatCompletionMessageParam, step: number, turn?: Turn) => void | Promise<void>;
+    onMessage?: (message: OpenAI.ChatCompletionMessageParam, step: number, turn?: Turn, written?: WrittenMessage) => void | Promise<void>;
     /**
      * How many times an answer cut off at `maxTokens` is continued, zero for never. Opt-in because
      * it spends another request, and on a server that does not continue a trailing assistant

package/dist/run/agent-loop.js

@@ -22,7 +22,7 @@ import { recoverToolCalls, } from '../wire/tool-calls.js';
 import { FinishReason, PartType, Role } from '../wire/wire.js';
 import { RunEventKind, RunOutcome, runMetrics, stamp, } from './events.js';
 import { buildBody } from './request-body.js';
-import { assistantMessage, definedAs, loadShortlist, readCalls, runCalls, } from './run-calls.js';
+import { assistantMessage, definedAs, loadShortlist, readCalls, runCalls, writtenMessage, } from './run-calls.js';
 /** The `preselectRouting` that sends the first step the shortlist alone. */
 export const PRESELECT_EXCLUSIVE = 'exclusive';
 /** The `preselectRouting` that loads the shortlist after what was carried, and sends the first step like any other. */
@@ -502,8 +502,8 @@ function definitionsByName(tools) {
  * Offers each message written into the transcript to the host.
  *
  * @param onMessage - The host's callback, awaited. Absent offers nothing.
- * @returns The offer, taking a message, its step and the turn it came with: it resolves once the
- * host has taken the message, and rejects with what the host threw — once.
+ * @returns The offer, taking a message, its step, the turn it came with and what the model wrote:
+ * it resolves once the host has taken the message, and rejects with what the host threw — once.
  *
  * @remarks
  * Once `onMessage` has thrown the run is ending on that, and the results still to be written are
@@ -511,12 +511,12 @@ function definitionsByName(tools) {
  */
 function announcer(onMessage) {
     let heard = true;
-    return async (message, step, turn) => {
+    return async (message, step, turn, written) => {
         if (!onMessage || !heard) {
             return;
         }
         try {
-            await onMessage(message, step, turn);
+            await onMessage(message, step, turn, written);
         }
         catch (error) {
             heard = false;
@@ -558,21 +558,21 @@ const usageEvent = (usage, turn, ledger, contextLength) => {
  * nothing is looked for in a turn that made a named call of its own or has no text.
  * @param notice - Told when calls were recovered, and how many.
  * @returns `calls`, the turn's own less any with no name, and `content`, its text as it was — or,
- * where calls were recovered, those calls and the text without them.
+ * where calls were recovered, those calls and the text without them, and `recovered` true.
  */
 function turnCalls(turn, recoverable, notice) {
     // A call with no name is a fragment the server never finished sending: nothing to run, and
     // an assistant message naming it would be answered by nothing.
     const calls = turn.toolCalls.filter((call) => call.function.name);
     if (!recoverable || calls.length || !turn.content) {
-        return { calls, content: turn.content };
+        return { calls, content: turn.content, recovered: false };
     }
     const recovered = recoverToolCalls(turn.content, { names: recoverable });
     if (!recovered.toolCalls.length) {
-        return { calls, content: turn.content };
+        return { calls, content: turn.content, recovered: false };
     }
     notice(`recovered ${counted(recovered.toolCalls.length, 'tool call')} the model wrote as text; the server's tool-call parser does not match this model's template`);
-    return { calls: recovered.toolCalls, content: recovered.content };
+    return { calls: recovered.toolCalls, content: recovered.content, recovered: true };
 }
 /**
  * The steps of `runAgentLoop`, throwing what they caught as it was caught.
@@ -850,15 +850,16 @@ async function runSteps(options, standing, pin) {
             notice(`the model stopped at maxTokens (${config.maxTokens}); this turn is cut short`);
         }
         const canRecover = recover && (tools.length > 0 || hostTools.length > 0 || onDemand);
-        const { calls, content } = turnCalls(turn, canRecover ? recoverable : undefined, notice);
+        const { calls, content, recovered } = turnCalls(turn, canRecover ? recoverable : undefined, notice);
         const shown = { ...turn, content, toolCalls: calls };
         onTurn?.(shown, step);
         // Read before the assistant message is written, so what is replayed on every later request
         // is the repaired JSON.
-        const parsed = readCalls(calls, turn.finishReason);
+        const parsed = readCalls(calls, turn.finishReason, recovered);
         const assistant = assistantMessage(content, parsed);
         messages.push(assistant);
-        await announce(assistant, step, shown);
+        // Recovered calls were never calls on the wire: what the model said is the text they came from.
+        await announce(assistant, step, shown, { raw: writtenMessage(turn.content, recovered ? [] : calls) });
         const isAnswer = calls.length === 0;
         const ended = isAnswer ? undefined : await runCalls(calling, parsed, messages, step);
         if (ended) {

package/dist/run/run-calls.d.ts

@@ -31,12 +31,15 @@ export interface ReadCall {
     error?: unknown;
     /** The arguments as every later request replays them: the repaired JSON, or `{}` for none. */
     normal: string;
+    /** Whether `args` took a repair to read, as `ToolCallRequest.repaired` says. */
+    repaired: boolean;
 }
 /**
  * A turn's calls with their arguments read.
  *
  * @param calls - The turn's calls, in the order the model made them.
  * @param finishReason - Why the turn ended, which tells a call cut off from one written wrongly.
+ * @param [recovered] - Whether the calls were recovered from the reply's text.
  * @returns One entry per call, in the same order. Unreadable arguments do not throw: the entry
  * carries the error in place of them.
  *
@@ -44,7 +47,7 @@ export interface ReadCall {
  * A server that parses replayed arguments refuses the almost-JSON a model wrote, so each is
  * normalised here, and one that could not be read at all is replayed as no arguments.
  */
-export declare const readCalls: (calls: ToolCall[], finishReason: Turn['finishReason']) => ReadCall[];
+export declare const readCalls: (calls: ToolCall[], finishReason: Turn['finishReason'], recovered?: boolean) => ReadCall[];
 /**
  * The assistant message a turn is written into the transcript as, its calls' arguments repaired.
  *
@@ -54,6 +57,15 @@ export declare const readCalls: (calls: ToolCall[], finishReason: Turn['finishRe
  * @returns A new message, each call on it a copy with `normal` for its arguments.
  */
 export declare const assistantMessage: (content: string, parsed: ReadCall[]) => OpenAI.ChatCompletionAssistantMessageParam;
+/**
+ * The assistant message a turn is, as the model produced it: its text and calls as they streamed.
+ *
+ * @param content - The turn's text, recovered calls left in it. Empty is written as `null`.
+ * @param calls - The calls the model sent as calls, with their arguments as streamed. Not written
+ * to. None leaves `tool_calls` off the message rather than empty.
+ * @returns A new message, each call on it a copy.
+ */
+export declare const writtenMessage: (content: string, calls: ToolCall[]) => OpenAI.ChatCompletionAssistantMessageParam;
 /**
  * The definitions the host gave for these names, in the order the names are given.
  *

package/dist/run/run-calls.js

@@ -1,3 +1,4 @@
+import { isRecord } from '../core/guards.js';
 import { CALL_TOOL, expandNames, inCatalog, LOAD_TOOLS, loadResult, proxiedCall, proxyLoadResult, requestedNames, shownCall, toolName, } from '../tools/tool-loading.js';
 import { errorMessage } from '../wire/errors.js';
 import { parseToolArguments, } from '../wire/tool-calls.js';
@@ -26,20 +27,40 @@ export const preview = (text, limit = 2000) => text.length > limit ? `${text.sli
 const STOPPED_CALL = 'Stopped before this call finished.';
 /** The same for a call of that step the loop never got to. */
 const UNRUN_CALL = 'Not run: the run stopped first.';
+/**
+ * Whether a call's arguments are, as written, the JSON of an object — or no arguments at all.
+ *
+ * @param raw - The arguments as the turn carried them: a string, or an object a server parsed.
+ * @returns False where reading them took `parseToolArguments`' repairs.
+ */
+function readsAsWritten(raw) {
+    if (typeof raw !== 'string' || !raw.trim()) {
+        return true;
+    }
+    try {
+        return isRecord(JSON.parse(raw));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * One call with its arguments read, or with why they could not be.
  *
  * @param call - The call as the turn carried it.
  * @param finishReason - Why the turn ended, which tells a call cut off from one written wrongly.
+ * @param recovered - Whether the call was recovered from the reply's text, which makes it repaired
+ * whatever its arguments.
  * @returns The call beside its arguments and their repaired JSON, or beside the error and `{}`.
  */
-function readCall(call, finishReason) {
+function readCall(call, finishReason, recovered) {
     try {
         const args = parseToolArguments(call.function.arguments, { finishReason });
-        return { call, args, normal: JSON.stringify(args) };
+        const repaired = recovered || !readsAsWritten(call.function.arguments);
+        return { call, args, normal: JSON.stringify(args), repaired };
     }
     catch (error) {
-        return { call, error, normal: '{}' };
+        return { call, error, normal: '{}', repaired: false };
     }
 }
 /**
@@ -47,6 +68,7 @@ function readCall(call, finishReason) {
  *
  * @param calls - The turn's calls, in the order the model made them.
  * @param finishReason - Why the turn ended, which tells a call cut off from one written wrongly.
+ * @param [recovered] - Whether the calls were recovered from the reply's text.
  * @returns One entry per call, in the same order. Unreadable arguments do not throw: the entry
  * carries the error in place of them.
  *
@@ -54,7 +76,7 @@ function readCall(call, finishReason) {
  * A server that parses replayed arguments refuses the almost-JSON a model wrote, so each is
  * normalised here, and one that could not be read at all is replayed as no arguments.
  */
-export const readCalls = (calls, finishReason) => calls.map((call) => readCall(call, finishReason));
+export const readCalls = (calls, finishReason, recovered = false) => calls.map((call) => readCall(call, finishReason, recovered));
 /**
  * The assistant message a turn is written into the transcript as, its calls' arguments repaired.
  *
@@ -75,6 +97,19 @@ export const assistantMessage = (content, parsed) => ({
         }
         : {}),
 });
+/**
+ * The assistant message a turn is, as the model produced it: its text and calls as they streamed.
+ *
+ * @param content - The turn's text, recovered calls left in it. Empty is written as `null`.
+ * @param calls - The calls the model sent as calls, with their arguments as streamed. Not written
+ * to. None leaves `tool_calls` off the message rather than empty.
+ * @returns A new message, each call on it a copy.
+ */
+export const writtenMessage = (content, calls) => ({
+    role: Role.Assistant,
+    content: content || null,
+    ...(calls.length ? { tool_calls: calls.map((call) => ({ ...call, function: { ...call.function } })) } : {}),
+});
 /**
  * The definitions the host gave for these names, in the order the names are given.
  *
@@ -284,7 +319,7 @@ function prepare(run, entry) {
     }
     // Built for every call rather than only the dispatched ones, so a host hears of the calls
     // the loop answers itself in the same shape. Arguments that could not be read are none.
-    const request = { id: call.id, name, args: inner, raw };
+    const request = { id: call.id, name, args: inner, raw, repaired: entry.repaired };
     // By the name the model called, not the one a `call_tool` wraps: `load_tools` is not in
     // the catalogue, and one reached through `call_tool` is refused like any other.
     const load = onDemand && call.function.name === LOAD_TOOLS;
@@ -540,7 +575,7 @@ export async function loadShortlist(run, shortlist, messages) {
     // host that shortlisted more has already chosen.
     const content = proxyLoadResult(expandNames(names, catalog, names.length), catalog, shortlist);
     run.onEvent({ kind: RunEventKind.ToolCall, id, name: LOAD_TOOLS, text: preview(args) });
-    run.onToolCall?.({ id, name: LOAD_TOOLS, args: { names }, raw: args });
+    run.onToolCall?.({ id, name: LOAD_TOOLS, args: { names }, raw: args, repaired: false });
     const loads = { toolsLoaded: names.length, redundantLoads: 0, unknownToolNames: 0 };
     run.onEvent({ kind: RunEventKind.ToolResult, id, name: LOAD_TOOLS, ok: true, text: preview(content), loads });
     run.onToolResult?.({ id, name: LOAD_TOOLS, ok: true, content });

package/dist/wire/tool-calls.d.ts

@@ -114,9 +114,24 @@ export interface ToolCallRequest {
     args: Record<string, unknown>;
     /**
      * The arguments as the model wrote them, before any repair. Through `call_tool`, the inner
-     * arguments as JSON text.
+     * arguments as JSON text. For a call recovered from the reply's text, the arguments recovery read
+     * out of it, as JSON text: the words the model wrote are the reply's content, which `onMessage`'s
+     * `raw` message carries.
      */
     raw: string;
+    /**
+     * Whether `args` took a repair to read: true where `raw` does not parse, as written, to the JSON
+     * object `args` holds — near-JSON, or JSON inside a string — and for every call recovered from
+     * text, which the model never sent as a call. False for blank arguments, which every reader takes
+     * as none, and for arguments that could not be read at all. Through `call_tool`, whether the
+     * `call_tool`'s own arguments did.
+     *
+     * @remarks
+     * A host that shows or stores what the model said reads `raw` where this is true. Whitespace is
+     * not a repair, though the replayed arguments are re-serialised either way. `runAgentLoop` always
+     * sets it; optional so a request built before it existed still compiles.
+     */
+    repaired?: boolean;
 }
 /** What one tool call did, in the order the model asked. */
 export interface ToolCallOutcome {

package/llms.txt

@@ -176,6 +176,7 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 - `PRESELECTED_NOTICE` — What opens the notice naming the loop's own picks, ahead of the names.
 - `runAgentLoop` — Runs a question to its answer: one `runTurn` per step, the tools it asks for between them, until a turn asks for none or a call's answer ends the run.
 - `StepWindow` (type) — How full the window is as a step is about to be sent, as `beforeStep` is told it.
+- `WrittenMessage` (type) — What `onMessage` is handed beside an assistant message the model wrote: that message as the model produced it.
 
 ### events
 

package/package.json

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