@cubicecho/agent-core 4.9.0 → 4.11.0

package/README.md

@@ -532,6 +532,41 @@ its calls made on the error too, read off with `failedRun`.
 A link meant for the model alone — one whose MCP `audience` leaves out `"user"` — is the
 dispatcher's to drop, since that is MCP's rule and this package knows nothing of MCP.
 
+### A call that ends the run
+
+A tool whose call is the end of the job — handing off, asking a person — says so with `end` on
+its `ToolAnswer`, `true` or `{ reason }`. The loop answers every call of that step, sends no
+further request, and resolves with `ended`; aborting the run's signal from inside `dispatch` was
+the way out before, and that is a failure the host then has to dig the run back out of.
+
+```ts
+const result = await runAgentLoop({
+  // ...
+  dispatch: async ({ name, args }, signal) =>
+    name === "ask_person"
+      ? { text: "Asked. This run ends here.", end: { reason: String(args.question) } }
+      : pool.call(name, args, { signal }),
+});
+if (result.ended) {
+  // { callId, name: "ask_person", reason }
+  const { callId, name, reason = "" } = result.ended;
+  emit(runId, { kind: RunEventKind.Done, ok: true, id: callId, name, text: reason });
+}
+```
+
+The step's other calls still run, whichever side of the end the model asked for them and however
+`parallel` batches them: they were asked for in the same turn, and a model that says "write the
+file, then hand off" wants the file written in either order. Where two calls end it, `ended` is
+the first in the order asked. Everything else is a finished run's — `usage`, `metrics`,
+`messages`, `artifacts`, the `afterTurn` hooks — with `metrics.outcome` `ended` and a notice
+saying which tool ended it. `turn` is the turn that made the call, so its `content` is whatever
+the model wrote beside its calls, often nothing; the run's answer is what the ending tool took.
+The tool, its definition and its wording stay the host's: this is only the exit.
+
+A host's `done` that carries the call — `id`, `name` the tool, `text` the reason — is read by
+`runMetrics` as `ended` too, so the outcome is the same whether it is read off the result or the
+events.
+
 Arguments go through `parseToolArguments`, which is lenient where the model's meaning is plain:
 JSON held in a string is opened, and the almost-JSON local models write — single quotes, Python's
 `True` and `None`, bare keys, a trailing comma — is repaired, without touching what is inside a
@@ -623,6 +658,29 @@ a `tool-call` and a `tool-result` event, told to `onToolCall` and `onToolResult`
 id is numbered by where the call lands in the transcript, so two questions do not share one. A name
 with no definition in `tools`, or outside the catalogue, is left out, and none left is no exchange.
 
+### What the servers said on the way
+
+A server can log while a call runs — a warning that the cache was stale, an error it recovered
+from — and that is often why the call went the way it did. `dispatch` is handed a third argument,
+`report`, and `report.log(entry)` tells watchers of one such message as a `server-log` event for
+the call: `id` the call's, `name` the tool, `level` the server's, and `text` the message's `data`,
+as it was where a string and as JSON otherwise, cut by `preview`. The entry is MCP's
+`notifications/message` params, `{ level, logger?, data }`, declared structurally, so
+agent-mcp-pool's `onLog` takes `report.log` as it stands:
+
+```ts
+dispatch: (call, signal, report) =>
+  pool.call(call.name, call.args, { servers, signal, onLog: report.log }),
+```
+
+None of it reaches the transcript: it is for the person watching, not the model. A call the loop
+answers itself never logs, a deduplicated repeat reports nothing of its own, and a message heard
+after the call has answered is dropped rather than landing after the result it explains.
+`runMetrics` counts `warning` as `serverWarnings` and `error` and above as `serverErrors`, so a
+summary can say the server complained without the events. A dispatcher written for
+`(call, signal)` needs no change. `report` is an object so that what a call can report — progress
+is next — grows there without `dispatch` changing again.
+
 ### What the servers say about themselves
 
 An MCP server may send `instructions` when it connects — "resolve the library id before querying

package/dist/index.d.ts

@@ -39,5 +39,5 @@ export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow,
 export { CacheBreakReason, type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from './wire/stream.ts';
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, SPLIT_OUTPUT, SPLIT_REASONING, type Split, stripThinking, THINK_FENCE, } from './wire/thinking.ts';
 export { type ContextBreakdown, type ContextBreakdownOptions, compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, type TokenEstimateOptions, } from './wire/tokens.ts';
-export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, parseToolArguments, type ResourceLink, type RunArtifact, recoverToolCalls, type ToolAnswer, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult, } from './wire/tool-calls.ts';
+export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, type EndedBy, parseToolArguments, type ResourceLink, type RunArtifact, recoverToolCalls, type ServerLogEntry, ServerLogLevel, type ToolAnswer, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult, } from './wire/tool-calls.ts';
 export { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire/wire.ts';

package/dist/index.js

@@ -38,5 +38,5 @@ export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow,
 export { CacheBreakReason, streamTurn, } from './wire/stream.js';
 export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, SPLIT_OUTPUT, SPLIT_REASONING, stripThinking, THINK_FENCE, } from './wire/thinking.js';
 export { compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, } from './wire/tokens.js';
-export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, parseToolArguments, recoverToolCalls, ToolArgumentsError, } from './wire/tool-calls.js';
+export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, parseToolArguments, recoverToolCalls, ServerLogLevel, ToolArgumentsError, } from './wire/tool-calls.js';
 export { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire/wire.js';

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

@@ -10,7 +10,7 @@ import { type KeywordPreselectOptions } from '../tools/preselect.ts';
 import { type ToolOrder } from '../tools/tool-loading.ts';
 import { type SideTask } from '../turn/side-task.ts';
 import { type Turn, type TurnUsage } from '../wire/stream.ts';
-import { type RunArtifact, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
+import { type EndedBy, type RunArtifact, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
 import { type RunEventInput, type RunMetrics } from './events.ts';
 import { type ToolDispatch } from './run-calls.ts';
 /**
@@ -243,7 +243,8 @@ export interface AgentLoopOptions {
      * @remarks
      * A `ToolAnswer` in place of the string adds what the call produced: its `text` is the whole of
      * what goes into the transcript, and its `links` become the result's `artifacts`, an `artifact`
-     * event the first time each uri is seen, and `links` on what `onToolResult` is handed.
+     * event the first time each uri is seen, and `links` on what `onToolResult` is handed. Its `end`
+     * ends the run once the step's calls are answered; see `AgentLoopResult.ended`.
      */
     dispatch: ToolDispatch;
     /**
@@ -395,8 +396,29 @@ export interface AgentLoopOptions {
 }
 /** What a finished loop hands back. */
 export interface AgentLoopResult {
-    /** The last turn: the one that asked for no tools, as `onTurn` was handed it. */
+    /**
+     * The last turn, as `onTurn` was handed it: the one that asked for no tools, or — where a call
+     * `ended` the run — the one that made that call.
+     *
+     * @remarks
+     * Ended by a call, its `content` is what the model wrote beside its calls, which is often
+     * nothing, and its `toolCalls` are not empty. The run's answer is then whatever the ending tool
+     * took — the question it asked, the work it handed off — and not this text.
+     */
     turn: Turn;
+    /**
+     * The call whose answer said `end`, where one did: the first in the order the model asked, once
+     * every call of its step was answered. Absent where the run ended on a turn that asked for no
+     * tools.
+     *
+     * @remarks
+     * Every other field is as a finished run has it: `messages` close on the step's tool results
+     * with no assistant turn after them, the hooks are told `afterTurn` with `turn.content`, and
+     * `metrics.outcome` is `ended`. No `beforeStep` or `compact` runs after the end, since no request
+     * follows it. A host saying `done` passes the call on it — `id` the call, `name` the tool, `text`
+     * the reason — which is how `runMetrics` reads the same outcome off the events.
+     */
+    ended?: EndedBy;
     /** The transcript, with every assistant turn and tool result the run added. No system prompt. */
     messages: OpenAI.ChatCompletionMessageParam[];
     /** Summed over every turn of the run. */
@@ -463,14 +485,16 @@ export interface AgentLoopResult {
 }
 /**
  * Runs a question to its answer: one `runTurn` per step, the tools it asks for between them,
- * until a turn asks for none. Throws when `maxToolIterations` is spent, when stopped, and on
- * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
+ * until a turn asks for none or a call's answer ends the run. Throws when `maxToolIterations` is
+ * spent, when stopped, and on whatever `runTurn` throws — `ContextOverflow` among them, however it
+ * was found out.
  *
  * @param options - The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.
- * @returns The turn that asked for no tools and the run around it: the transcript with what the
- * run added, usage, every call, what is loaded and used, the hooks' notes and context, metrics
- * and the ledger. See `AgentLoopResult`.
+ * @returns The turn that asked for no tools — or made the call that ended the run, with `ended`
+ * naming it — and the run around it: the transcript with what the run added, usage, every call,
+ * what is loaded and used, the hooks' notes and context, metrics and the ledger. See
+ * `AgentLoopResult`.
  *
  * @remarks
  * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded`, `used`
@@ -482,6 +506,11 @@ export interface AgentLoopResult {
  * well-formed: the results that came back are kept, and each call without one is answered with a
  * line saying it was stopped or never run, since a call with no result is refused on replay.
  *
+ * A tool that finishes the job — a hand-off, a question for a person — ends the run with a
+ * `ToolAnswer` whose `end` is set, rather than by aborting it: the step's calls are all run and
+ * answered, no further request is sent, and the loop resolves with `ended`. An end in the last step
+ * `maxToolIterations` allows resolves too, since nothing was left undone.
+ *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
  * prompt unchanged from step to step, a load adds to the tool array — which every request sends
  * in the stable order `toolOrder` asks for — and

package/dist/run/agent-loop.js

@@ -63,14 +63,16 @@ function cacheDiagnosis(previous, next, usage) {
 }
 /**
  * Runs a question to its answer: one `runTurn` per step, the tools it asks for between them,
- * until a turn asks for none. Throws when `maxToolIterations` is spent, when stopped, and on
- * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
+ * until a turn asks for none or a call's answer ends the run. Throws when `maxToolIterations` is
+ * spent, when stopped, and on whatever `runTurn` throws — `ContextOverflow` among them, however it
+ * was found out.
  *
  * @param options - The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.
- * @returns The turn that asked for no tools and the run around it: the transcript with what the
- * run added, usage, every call, what is loaded and used, the hooks' notes and context, metrics
- * and the ledger. See `AgentLoopResult`.
+ * @returns The turn that asked for no tools — or made the call that ended the run, with `ended`
+ * naming it — and the run around it: the transcript with what the run added, usage, every call,
+ * what is loaded and used, the hooks' notes and context, metrics and the ledger. See
+ * `AgentLoopResult`.
  *
  * @remarks
  * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded`, `used`
@@ -82,6 +84,11 @@ function cacheDiagnosis(previous, next, usage) {
  * well-formed: the results that came back are kept, and each call without one is answered with a
  * line saying it was stopped or never run, since a call with no result is refused on replay.
  *
+ * A tool that finishes the job — a hand-off, a question for a person — ends the run with a
+ * `ToolAnswer` whose `end` is set, rather than by aborting it: the step's calls are all run and
+ * answered, no further request is sent, and the loop resolves with `ended`. An end in the last step
+ * `maxToolIterations` allows resolves too, since nothing was left undone.
+ *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
  * prompt unchanged from step to step, a load adds to the tool array — which every request sends
  * in the stable order `toolOrder` asks for — and
@@ -471,8 +478,8 @@ function turnCalls(turn, recoverable, notice) {
  * @param standing - Written to: once the steps have set themselves up, its `read` is theirs, so the
  * caller can read the run as it stands whether they return or throw.
  * @param [pin] - What the run's session adds to each request. Absent adds nothing.
- * @returns The result of the turn that asked for no tools, or `undefined` when `maxToolIterations`
- * is spent.
+ * @returns The result of the turn that asked for no tools or whose calls ended the run, or
+ * `undefined` when `maxToolIterations` is spent.
  */
 async function runSteps(options, standing, pin) {
     const { config, system = '', tools = [], catalog = [], dispatch, hooks, signal } = options;
@@ -706,13 +713,27 @@ async function runSteps(options, standing, pin) {
         const assistant = assistantMessage(content, parsed);
         messages.push(assistant);
         await announce(assistant, step, shown);
-        if (!calls.length) {
+        const isAnswer = calls.length === 0;
+        const ended = isAnswer ? undefined : await runCalls(calling, parsed, messages, step);
+        if (ended) {
+            const by = ended.reason ? `: ${ended.reason}` : '';
+            notice(`${ended.name} ended the run${by}`);
+        }
+        if (isAnswer || ended) {
             // Not awaited: the answer is ready, and remembering it is not something to hold it for.
             // Handed back instead, for a host that wants its notes.
             const afterTurn = hooks ? tellAfterTurn(hooks, messages, questionAt(), turn.content) : Promise.resolve([]);
             const metrics = runMetrics(recorded, { contextLength: config.contextLength });
+            let outcome = RunOutcome.Answered;
+            if (ended) {
+                outcome = RunOutcome.Ended;
+            }
+            else if (turn.finishReason === FinishReason.Length) {
+                outcome = RunOutcome.Truncated;
+            }
             return {
                 turn: shown,
+                ...(ended ? { ended } : {}),
                 messages,
                 usage,
                 toolCalls,
@@ -728,12 +749,11 @@ async function runSteps(options, standing, pin) {
                     ...metrics,
                     ...(onDemand ? loads : {}),
                     wallMs: Date.now() - started,
-                    outcome: turn.finishReason === FinishReason.Length ? RunOutcome.Truncated : RunOutcome.Answered,
+                    outcome,
                 },
                 ledger,
             };
         }
-        await runCalls(calling, parsed, messages, step);
     }
     return undefined;
 }

package/dist/run/events.d.ts

@@ -1,7 +1,7 @@
 import type { TokenLedger } from '../context/ledger.ts';
 import type { TurnUsage } from '../wire/stream.ts';
 import { CacheBreakReason } from '../wire/stream.ts';
-import type { ResourceLink } from '../wire/tool-calls.ts';
+import { type ResourceLink } from '../wire/tool-calls.ts';
 /**
  * What a run is doing, while it is doing it.
  *
@@ -96,13 +96,23 @@ export declare const RunEventKind: {
      * per uri per run: a later call that links the same uri again only adds to its count.
      */
     readonly Artifact: 'artifact';
+    /**
+     * A tool's server logged something while a call was running, which the dispatcher passed on
+     * through `report.log`. `id` is the call's, `name` the tool, `level` the server's, and `text`
+     * the message's data — as it was where a string, as JSON otherwise — cut by `preview`. Never in
+     * the transcript, and never from a call the loop answers itself.
+     */
+    readonly ServerLog: 'server-log';
     /**
      * What the run has cost so far, at the end of every turn, and what that one turn did. Sent
      * whether or not the endpoint reported tokens, since the timings and the cache comparison are
      * measured either way.
      */
     readonly Usage: 'usage';
-    /** The run ended. Always last, and always sent. */
+    /**
+     * The run ended. Always last, and always sent. A run a tool call ended carries that call: `id`
+     * the call's, `name` the tool, and `text` the reason, as `AgentLoopResult.ended` has them.
+     */
     readonly Done: 'done';
 };
 /** Any one of the kinds in `RunEventKind`. */
@@ -164,7 +174,7 @@ export interface RunEvent {
     kind: RunEventKind;
     /** The delta, the arguments, the result, or the reason — whatever the kind carries. */
     text: string;
-    /** Tool name on the tool kinds, otherwise empty. */
+    /** Tool name on the tool kinds, and on a `done` the tool that ended the run; otherwise empty. */
     name: string;
     /**
      * The call's id on the tool kinds, which pairs a `tool-result` with its `tool-call` when one
@@ -187,6 +197,11 @@ export interface RunEvent {
      * an event built before it existed still compiles.
      */
     link?: ResourceLink;
+    /**
+     * The level the server logged at, on `server-log` and on no other kind. Optional for the reason
+     * `id` is.
+     */
+    level?: string;
 }
 /**
  * What `emit` is given: the run and the sequence are the bus's to assign.
@@ -314,6 +329,10 @@ export interface RunMetrics {
     loadCalls: number;
     /** `artifact` events: the distinct things the run's tool calls linked to. */
     artifacts: number;
+    /** `server-log` events at `warning`. */
+    serverWarnings: number;
+    /** `server-log` events at `error` or above: `critical`, `alert` and `emergency` with it. */
+    serverErrors: number;
     /**
      * Tools `load_tools` loaded that were not loaded already. Filled by `runAgentLoop`, which sees
      * the resolution; the events carry only its text.
@@ -374,6 +393,11 @@ export declare const RunOutcome: {
     readonly Answered: 'answered';
     /** The run did not fail, and its last turn is an answer the reply ceiling cut off. */
     readonly Truncated: 'truncated';
+    /**
+     * The run did not fail, and a tool call ended it: `AgentLoopResult.ended` says which, and so
+     * does a `done` that names the tool.
+     */
+    readonly Ended: 'ended';
     /**
      * `done` said the run was not ok. Whether that was an error, a stop or the tool budget is in
      * the host's own `done` text and not here.

package/dist/run/events.js

@@ -3,6 +3,7 @@ import { ABORT_EVENT, MS_PER_MINUTE } from '../core/platform.js';
 import { assignSettings, scoped } from '../core/scope.js';
 import { LOAD_TOOLS } from '../tools/tool-loading.js';
 import { CacheBreakReason } from '../wire/stream.js';
+import { ServerLogLevel } from '../wire/tool-calls.js';
 import { FinishReason } from '../wire/wire.js';
 /** How many minutes an unended run's events are kept, absent a `retainUnendedMs`. */
 const RETAIN_UNENDED_MINUTES = 30;
@@ -62,13 +63,23 @@ export const RunEventKind = {
      * per uri per run: a later call that links the same uri again only adds to its count.
      */
     Artifact: 'artifact',
+    /**
+     * A tool's server logged something while a call was running, which the dispatcher passed on
+     * through `report.log`. `id` is the call's, `name` the tool, `level` the server's, and `text`
+     * the message's data — as it was where a string, as JSON otherwise — cut by `preview`. Never in
+     * the transcript, and never from a call the loop answers itself.
+     */
+    ServerLog: 'server-log',
     /**
      * What the run has cost so far, at the end of every turn, and what that one turn did. Sent
      * whether or not the endpoint reported tokens, since the timings and the cache comparison are
      * measured either way.
      */
     Usage: 'usage',
-    /** The run ended. Always last, and always sent. */
+    /**
+     * The run ended. Always last, and always sent. A run a tool call ended carries that call: `id`
+     * the call's, `name` the tool, and `text` the reason, as `AgentLoopResult.ended` has them.
+     */
     Done: 'done',
 };
 /**
@@ -453,12 +464,21 @@ export function fold(events) {
     close();
     return blocks;
 }
+/** The log levels quietest first, which is what makes "warning and above" a comparison. */
+const SEVERITY = Object.values(ServerLogLevel);
+/** Where `warning` sits in `SEVERITY`: a level past it is an error. */
+const WARNING = SEVERITY.indexOf(ServerLogLevel.Warning);
 /** How a run ended, as `runMetrics` reads it. */
 export const RunOutcome = {
     /** The run did not fail, and its last turn was not cut off. */
     Answered: 'answered',
     /** The run did not fail, and its last turn is an answer the reply ceiling cut off. */
     Truncated: 'truncated',
+    /**
+     * The run did not fail, and a tool call ended it: `AgentLoopResult.ended` says which, and so
+     * does a `done` that names the tool.
+     */
+    Ended: 'ended',
     /**
      * `done` said the run was not ok. Whether that was an error, a stop or the tool budget is in
      * the host's own `done` text and not here.
@@ -468,15 +488,21 @@ export const RunOutcome = {
 /**
  * How a run that reported `done` ended.
  *
- * @param ok - What the `done` event said. Only `false` is a failure; anything else is read off the turn.
+ * @param done - The `done` event. Only an `ok` of `false` is a failure; one that names a tool was
+ * ended by it; anything else is read off the turn.
  * @param last - The last turn a `usage` event reported, if any did.
- * @returns `failed` for a `done` that was not ok, `truncated` where the last turn ran into the
- * reply ceiling, and `answered` otherwise.
+ * @returns `failed` for a `done` that was not ok, `ended` for one that names the tool that ended
+ * the run, `truncated` where the last turn ran into the reply ceiling, and `answered` otherwise.
  */
-function outcomeOf(ok, last) {
+function outcomeOf({ ok, name }, last) {
     if (ok === false) {
         return RunOutcome.Failed;
     }
+    // Read as a truthy string, so an event put together by hand without one is not ended.
+    const isEnded = Boolean(name);
+    if (isEnded) {
+        return RunOutcome.Ended;
+    }
     if (last?.finishReason === FinishReason.Length) {
         return RunOutcome.Truncated;
     }
@@ -507,6 +533,8 @@ export function runMetrics(events, { contextLength } = {}) {
         toolErrors: {},
         loadCalls: 0,
         artifacts: 0,
+        serverWarnings: 0,
+        serverErrors: 0,
         promptTokens: 0,
         completionTokens: 0,
         cachedTokens: 0,
@@ -550,6 +578,15 @@ export function runMetrics(events, { contextLength } = {}) {
         else if (event.kind === RunEventKind.Artifact) {
             metrics.artifacts++;
         }
+        else if (event.kind === RunEventKind.ServerLog) {
+            const severity = SEVERITY.indexOf(event.level ?? '');
+            if (severity === WARNING) {
+                metrics.serverWarnings++;
+            }
+            else if (severity > WARNING) {
+                metrics.serverErrors++;
+            }
+        }
         else if (event.kind === RunEventKind.Usage && event.usage?.turn) {
             const turn = event.usage.turn;
             last = turn;
@@ -591,7 +628,7 @@ export function runMetrics(events, { contextLength } = {}) {
             }
         }
         else if (event.kind === RunEventKind.Done) {
-            metrics.outcome = outcomeOf(event.ok, last);
+            metrics.outcome = outcomeOf(event, last);
         }
     }
     if (events.length > 1) {

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

@@ -1,7 +1,7 @@
 import type OpenAI from 'openai';
 import type { CatalogServer } from '../tools/catalog.ts';
 import type { Turn } from '../wire/stream.ts';
-import { type RunArtifact, type ToolAnswer, type ToolCall, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
+import { type EndedBy, type RunArtifact, type ToolAnswer, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
 import type { RunEventInput } from './events.ts';
 /**
  * The tools between two turns: a step's calls read, run and written into the transcript.
@@ -66,8 +66,13 @@ export declare const definedAs: (definitions: ReadonlyMap<string, OpenAI.ChatCom
 /**
  * Runs one tool call and resolves to what the model reads, alone or with what the call produced;
  * what it throws, the model reads too.
+ *
+ * @remarks
+ * `report` is how the call tells watchers what its server said on the way, and a dispatcher with
+ * nothing to report leaves it off: one written for `(call, signal)` is a `ToolDispatch` still.
+ * `signal` is `undefined` rather than optional so that `report` can follow it.
  */
-export type ToolDispatch = (call: ToolCallRequest, signal?: AbortSignal) => Promise<string | ToolAnswer>;
+export type ToolDispatch = (call: ToolCallRequest, signal: AbortSignal | undefined, report: ToolCallReport) => Promise<string | ToolAnswer>;
 /**
  * What running a step's calls reads of the run and writes back into it. One per run, shared by
  * every step: the sets and counts here are the run's own, not copies.
@@ -109,13 +114,21 @@ export interface Calling {
  * @param parsed - The step's calls, with their arguments read.
  * @param messages - The transcript the results are written into.
  * @param step - Which step this is, for the host told of each result.
+ * @returns The first call, in the order asked, whose answer ended the run, or `undefined` where
+ * none did.
  *
  * @remarks
  * A failure part-way leaves the transcript well-formed before it is rethrown: a call with no
  * result is a transcript no endpoint takes back, so every call of the step is answered — with what
  * it returned where it had, and otherwise with a line saying it was stopped, or never run.
+ *
+ * An answer that ends the run does not end the step. The calls after it still run, in whatever
+ * batch `parallel` puts them, because the model asked for them in the same breath and how a host
+ * schedules calls is not what they mean: a reply that says "write the file, then hand off" in one
+ * turn wants the file written whichever order it named the two in, and a call batched beside the
+ * end was running already. A tool that must have nothing after it says so in its description.
  */
-export declare function runCalls(run: Calling, parsed: ReadCall[], messages: OpenAI.ChatCompletionMessageParam[], step: number): Promise<void>;
+export declare function runCalls(run: Calling, parsed: ReadCall[], messages: OpenAI.ChatCompletionMessageParam[], step: number): Promise<EndedBy | undefined>;
 /**
  * Writes a proxied preselection into the transcript as a `load_tools` exchange: the tool array is
  * fixed, so a shortlist has nowhere else to go, and it is answered as though the model had loaded

package/dist/run/run-calls.js

@@ -84,13 +84,63 @@ export const assistantMessage = (content, parsed) => ({
  * @returns A new array of the definitions themselves, not copies.
  */
 export const definedAs = (definitions, names) => [...names].flatMap((name) => definitions.get(name) ?? []);
+/**
+ * A server's log message as the text of its event.
+ *
+ * @param data - What the server sent: a string, or any JSON value.
+ * @returns A string as it was, anything else as JSON, cut by `preview`. What JSON cannot spell is
+ * shown as `String` shows it.
+ */
+function logText(data) {
+    if (typeof data === 'string') {
+        return preview(data);
+    }
+    try {
+        return preview(JSON.stringify(data) ?? String(data));
+    }
+    catch {
+        return preview(String(data));
+    }
+}
+/**
+ * What one call's dispatcher may report through, and the switch that closes it once it has answered.
+ *
+ * @param run - The run, whose watchers hear what is reported.
+ * @param id - The call's id, which every event it reports carries.
+ * @param name - The tool the call is shown as.
+ * @returns The report to hand `dispatch`, and `close`, after which it reports nothing.
+ */
+function reportFor(run, id, name) {
+    let isOpen = true;
+    const log = ({ level, data }) => {
+        if (isOpen) {
+            run.onEvent({ kind: RunEventKind.ServerLog, id, name, level, text: logText(data) });
+        }
+    };
+    return {
+        report: { log },
+        close: () => {
+            isOpen = false;
+        },
+    };
+}
 /**
  * A dispatcher's answer in the one shape, whichever it gave.
  *
  * @param answer - What `dispatch` resolved to.
- * @returns The text and the links, a string answer's being none.
+ * @returns The text, the links and whether it ends the run, a string answer having no links and
+ * ending nothing.
  */
-const answerOf = (answer) => typeof answer === 'string' ? { text: answer, links: [] } : { text: answer.text, links: answer.links ?? [] };
+function answerOf(answer) {
+    if (typeof answer === 'string') {
+        return { text: answer, links: [], end: false };
+    }
+    const { text, links = [], end = false } = answer;
+    if (typeof end === 'object') {
+        return { text, links, end: { reason: end.reason } };
+    }
+    return { text, links, end: end ? {} : false };
+}
 /**
  * What a call is shown, counted and dispatched as: a `call_tool` as the tool it names.
  *
@@ -282,9 +332,9 @@ function batchEnd(run, ready, from, total, answered) {
  * @param prepared - The call, with its request built.
  * @param answered - The step's calls already made, by tool and arguments, for `dedupeToolCalls`.
  * @param step - Which step this is, for the artifacts the call's links become.
- * @returns The call's id, the name it was shown under, whether it worked, the whole of what the
- * model reads, and the links its answer carried, where it carried any. Rejects where the run was
- * stopped or a host callback threw.
+ * @returns The result — the call's id, the name it was shown under, whether it worked, the whole
+ * of what the model reads, and the links its answer carried, where it carried any — and whether
+ * the answer ended the run. Rejects where the run was stopped or a host callback threw.
  */
 async function runCall(run, prepared, answered, step) {
     const { catalog, onDemand, proxied, signal } = run;
@@ -293,8 +343,10 @@ async function runCall(run, prepared, answered, step) {
     const { name, raw } = request;
     run.onEvent({ kind: RunEventKind.ToolCall, id: call.id, name, text: preview(raw) });
     run.onToolCall?.(request);
+    const { report, close } = reportFor(run, call.id, name);
     let content;
     let links = [];
+    let end = false;
     let ok = true;
     // Answered from an earlier identical call of the step, whose links are already counted.
     let shared = false;
@@ -318,10 +370,12 @@ async function runCall(run, prepared, answered, step) {
             run.used.add(name);
             // Read before `once` looks, which it does before it awaits anything.
             shared = dedupable && answered.has(key);
+            // A repeat answered from the first call reports nothing of its own: the first call's
+            // report is the one its dispatcher holds.
             const answer = dedupable
-                ? await once(answered, key, () => run.dispatch(request, signal))
-                : await run.dispatch(request, signal);
-            ({ text: content, links } = answerOf(answer));
+                ? await once(answered, key, () => run.dispatch(request, signal, report))
+                : await run.dispatch(request, signal, report);
+            ({ text: content, links, end } = answerOf(answer));
         }
     }
     catch (error) {
@@ -331,6 +385,9 @@ async function runCall(run, prepared, answered, step) {
         content = errorMessage(error);
         ok = false;
     }
+    finally {
+        close();
+    }
     run.onEvent({ kind: RunEventKind.ToolResult, id: call.id, name, ok, text: preview(content) });
     const isFirstAnswer = shared === false;
     if (isFirstAnswer) {
@@ -338,7 +395,7 @@ async function runCall(run, prepared, answered, step) {
     }
     const result = { id: call.id, name, ok, content, ...(links.length ? { links } : {}) };
     run.onToolResult?.(result);
-    return result;
+    return { result, end };
 }
 /**
  * Runs a step's calls and writes each result into the transcript, in the order asked.
@@ -347,11 +404,19 @@ async function runCall(run, prepared, answered, step) {
  * @param parsed - The step's calls, with their arguments read.
  * @param messages - The transcript the results are written into.
  * @param step - Which step this is, for the host told of each result.
+ * @returns The first call, in the order asked, whose answer ended the run, or `undefined` where
+ * none did.
  *
  * @remarks
  * A failure part-way leaves the transcript well-formed before it is rethrown: a call with no
  * result is a transcript no endpoint takes back, so every call of the step is answered — with what
  * it returned where it had, and otherwise with a line saying it was stopped, or never run.
+ *
+ * An answer that ends the run does not end the step. The calls after it still run, in whatever
+ * batch `parallel` puts them, because the model asked for them in the same breath and how a host
+ * schedules calls is not what they mean: a reply that says "write the file, then hand off" in one
+ * turn wants the file written whichever order it named the two in, and a call batched beside the
+ * end was running already. A tool that must have nothing after it says so in its description.
  */
 export async function runCalls(run, parsed, messages, step) {
     const { signal, toolCalls } = run;
@@ -360,6 +425,7 @@ export async function runCalls(run, parsed, messages, step) {
     const answered = new Map();
     // By position, so a call that came back while another was being stopped is still found.
     const outcomes = parsed.map(() => undefined);
+    const ends = parsed.map(() => false);
     // How many of the step's calls were handed off, and how many have their result in the
     // transcript. Both count from the front, since results are written in the order asked.
     let begun = 0;
@@ -390,7 +456,9 @@ export async function runCalls(run, parsed, messages, step) {
             const to = batchEnd(run, ready, start, parsed.length, answered);
             begun = to;
             await Promise.all(parsed.slice(start, to).map(async (_, offset) => {
-                outcomes[start + offset] = await runCall(run, ready(start + offset), answered, step);
+                const { result, end } = await runCall(run, ready(start + offset), answered, step);
+                outcomes[start + offset] = result;
+                ends[start + offset] = end;
             }));
             for (const { id, name, ok, content } of outcomes.slice(from, to).flatMap((outcome) => outcome ?? [])) {
                 toolCalls.push({ id, name, ok });
@@ -398,6 +466,15 @@ export async function runCalls(run, parsed, messages, step) {
             }
             from = to;
         }
+        // The first by position rather than by finishing: a batch's calls end in no order worth
+        // reporting, and a deduplicated repeat shares its answer's `end` with the call before it.
+        const at = ends.findIndex((end) => end !== false);
+        const end = ends[at];
+        const outcome = outcomes[at];
+        if (end === undefined || end === false || outcome === undefined) {
+            return undefined;
+        }
+        return { callId: outcome.id, name: outcome.name, ...(end.reason === undefined ? {} : { reason: end.reason }) };
     }
     catch (error) {
         // Only a call that was made counts in `toolCalls`.

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

@@ -188,6 +188,80 @@ export interface ToolAnswer {
     text: string;
     /** What the call produced, in the order the tool gave them. Never sent to the model. */
     links?: ResourceLink[];
+    /**
+     * Ends the run once this step's calls are answered: no further request is sent, and the loop
+     * resolves with `ended` rather than throwing. An object says why, for the host and its `done`.
+     *
+     * @remarks
+     * The step's other calls still run and are answered, so the transcript stays one an endpoint
+     * will take back. For a tool whose call is the end of the job — handing off, asking a person —
+     * where the alternative is an abort, which the loop reads as a failure.
+     */
+    end?: boolean | {
+        reason: string;
+    };
+}
+/** The call that ended a run through its answer's `end`, as `AgentLoopResult.ended` says it. */
+export interface EndedBy {
+    /** The call's id. */
+    callId: string;
+    /** The tool, under the name it was announced by: for a `call_tool`, the tool it names. */
+    name: string;
+    /** Why, where the answer said: absent for `end: true`. */
+    reason?: string;
+}
+/**
+ * The levels a server's log message is sent at, quietest first: MCP's, which are syslog's.
+ *
+ * @remarks
+ * `runMetrics` reads `warning` and the four above it as a server complaining. A level outside
+ * this list is still shown, and is counted as neither.
+ */
+export declare const ServerLogLevel: {
+    readonly Debug: 'debug';
+    readonly Info: 'info';
+    readonly Notice: 'notice';
+    readonly Warning: 'warning';
+    readonly Error: 'error';
+    readonly Critical: 'critical';
+    readonly Alert: 'alert';
+    readonly Emergency: 'emergency';
+};
+/** Any one of the levels in `ServerLogLevel`. */
+export type ServerLogLevel = (typeof ServerLogLevel)[keyof typeof ServerLogLevel];
+/**
+ * One log message a tool's server sent while the call was running, as `ToolCallReport.log` is
+ * handed it.
+ *
+ * @remarks
+ * The params of MCP's `notifications/message`, declared structurally rather than imported, as
+ * `ResourceLink` is: agent-mcp-pool's `ServerLogEntry` has these field names, so its `onLog`
+ * takes `report.log` as it stands. `level` is a plain string so a server's own word is shown
+ * rather than refused.
+ */
+export interface ServerLogEntry {
+    /** How serious the server says it is: one of `ServerLogLevel`, by the spec. */
+    level: string;
+    /** The server's name for the part of itself that logged, where it gave one. */
+    logger?: string;
+    /** Whatever the server sent: a string usually, any JSON value by the spec. */
+    data: unknown;
+}
+/**
+ * What a dispatcher may tell the run about the call it is making, besides its answer.
+ *
+ * @remarks
+ * An object rather than a fourth and fifth argument, so what a call can report grows here —
+ * progress is the next one — without `dispatch` changing again. Every member is a bound function,
+ * so it can be handed on alone: `onLog: report.log`. What is reported reaches the run's events
+ * and never the transcript: it is for the person watching, not the model.
+ */
+export interface ToolCallReport {
+    /**
+     * Tells watchers of a server's log message, as a `server-log` event for this call. Heard after
+     * the call has answered, it is dropped: the event would land after the result it explains.
+     */
+    log: (entry: ServerLogEntry) => void;
 }
 /**
  * One thing a run's tool calls produced: the first link to a uri, and where it came from.

package/dist/wire/tool-calls.js

@@ -472,3 +472,20 @@ export function recoverToolCalls(content, { names = [] } = {}) {
     rest += tail.slice(cursor);
     return { content: `${content.slice(0, from)}${rest}`.trim(), toolCalls };
 }
+/**
+ * The levels a server's log message is sent at, quietest first: MCP's, which are syslog's.
+ *
+ * @remarks
+ * `runMetrics` reads `warning` and the four above it as a server complaining. A level outside
+ * this list is still shown, and is counted as neither.
+ */
+export const ServerLogLevel = {
+    Debug: 'debug',
+    Info: 'info',
+    Notice: 'notice',
+    Warning: 'warning',
+    Error: 'error',
+    Critical: 'critical',
+    Alert: 'alert',
+    Emergency: 'emergency',
+};

package/llms.txt

@@ -163,7 +163,7 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 - `PRESELECT_APPEND` — The `preselectRouting` that loads the shortlist after what was carried, and sends the first step like any other.
 - `PRESELECT_EXCLUSIVE` — The `preselectRouting` that sends the first step the shortlist alone.
 - `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.
+- `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.
 
 ### events
@@ -402,14 +402,18 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 
 - `ARGUMENTS_MALFORMED` — The `ToolArgumentsError` kind for a call the model wrote wrongly.
 - `ARGUMENTS_TRUNCATED` — The `ToolArgumentsError` kind for a call cut off at the reply ceiling.
+- `EndedBy` (type) — The call that ended a run through its answer's `end`, as `AgentLoopResult.ended` says it.
 - `parseToolArguments` — A tool call's arguments as the object the tool is handed.
 - `ResourceLink` (type) — A handle to something a tool call made or found — a document it wrote, a file it saved.
 - `RunArtifact` (type) — One thing a run's tool calls produced: the first link to a uri, and where it came from.
 - `recoverToolCalls` — Tool calls a model wrote into its reply as text, taken out of it and made into calls.
+- `ServerLogEntry` (type) — One log message a tool's server sent while the call was running, as `ToolCallReport.log` is handed it.
+- `ServerLogLevel` — Any one of the levels in `ServerLogLevel`.
 - `ToolAnswer` (type) — A dispatcher's answer when it has more to say than the text: what the model reads, and what the call produced for the host.
 - `ToolArgumentsError` — Tool arguments that could not be read as an object, with why.
 - `ToolCall` (type) — A tool call as the loop handles it, recovered or streamed.
 - `ToolCallOutcome` (type) — What one tool call did, in the order the model asked.
+- `ToolCallReport` (type) — What a dispatcher may tell the run about the call it is making, besides its answer.
 - `ToolCallRequest` (type) — One call the model made, as `dispatch` and `onToolCall` are handed it.
 - `ToolCallResult` (type) — One call's whole answer, as `onToolResult` is handed it.
 

package/package.json

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