@cubicecho/agent-core 4.5.0 → 4.7.0

package/README.md

@@ -449,7 +449,8 @@ const { turn, messages, usage, loaded } = await runAgentLoop({
 
 Each step is one `runTurn` with the body from `buildBody`, so everything `negotiate` answers is
 answered here too, and a request that is too big throws `ContextOverflow` whichever side found
-out. Between steps the loop runs the calls: sequentially by default, or together with `parallel: true`.
+out. Between steps the loop runs the calls: sequentially by default, together with `parallel: true`, or
+reads together and writes in order with a predicate (below).
 Either way an identical call — the same name and arguments, byte for byte — is made once and its
 answer handed to the repeat, and two still in flight share the request. A call that threw is
 forgotten rather than cached, so asking again is a real retry. What a tool throws is what the model
@@ -461,6 +462,26 @@ predicate is asked per call — which is how `send_email` opts out, since twice
 nothing in an OpenAI tool definition says which tools those are. A pool that reads the MCP
 `readOnlyHint` and `idempotentHint` annotations can answer it; this package cannot.
 
+`parallel` takes a predicate for the same reason. Consecutive calls it passes run together, and a
+call it fails is a barrier: it waits for every call before it and every call after waits for it,
+so a read asked for after a write sees what the write did.
+
+```
+read A, read B, write C, read D, read E   →   [A ‖ B] → C → [D ‖ E]
+```
+
+Results go into the transcript in the order the model asked, and inside a batch `onToolResult` and
+the events arrive as calls finish, as with `parallel: true`. The calls the loop answers itself —
+`load_tools`, unreadable arguments, an identical repeat — are not put to the predicate and count
+as reads. `@cubicecho/agent-mcp-pool` (3.10.0 and later) answers both predicates from the
+annotations of a server whose row sets `trustAnnotations`, and the worst case — run alone, send
+every time — for everything else:
+
+```ts
+const reads = (call: ToolCallRequest) => pool.readsOnly(call.name, { servers });
+await runAgentLoop({ ...options, parallel: reads, dedupeToolCalls: reads });
+```
+
 Three kinds of call never reach `dispatch`: `load_tools`, which the loop answers itself, a call
 whose arguments could not be read, and that identical repeat. A host that draws each call as a
 card and fills it in when the result lands hears of those through `onToolCall` and `onToolResult`,
@@ -481,6 +502,34 @@ await runAgentLoop({
 });
 ```
 
+### What the calls made
+
+A tool that wrote a document or saved a file can say so, and `dispatch` can pass that on: it
+resolves to a `ToolAnswer`, `{ text, links }`, in place of the string. `text` is the whole of
+what goes into the transcript, so the request, the prompt cache, pruning and compaction never see
+the links. `links` are `ResourceLink`s, MCP's own shape declared structurally, so what
+agent-mcp-pool's `call` answers with `links: true` is a dispatcher's answer as it stands.
+
+```ts
+const { artifacts } = await runAgentLoop({
+  // ...
+  dispatch: ({ name, args }, signal) => pool.call(name, args, { signal, links: true }),
+});
+// [{ link: { uri, name, title?, ... }, callId, tool, step, count }]
+```
+
+The loop collects them into the run's `artifacts`: one per uri in the order first seen, each with
+the call, tool and step that first linked to it and the number of calls that did. A link is what
+one call answered with; an artifact is what the run made. `onToolResult` hears a call's `links`
+beside its `content`, an `artifact` event goes out the first time each uri appears — `name` the
+tool, `text` the title or else the uri, and `link` the link — and `runMetrics` counts those events
+as `artifacts`. A deduplicated repeat shares the first call's answer and links but adds nothing to
+the count, since nothing was made twice. A call that threw made nothing. A failed run carries what
+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.
+
 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

package/dist/index.d.ts

@@ -21,7 +21,7 @@ export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_C
 export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopRequest, type AgentLoopResult, PRESELECT_APPEND, PRESELECT_EXCLUSIVE, PRESELECTED_NOTICE, runAgentLoop, type StepWindow, } from './run/agent-loop.ts';
 export { configureEvents, type EventBusOptions, emit, endRun, fold, history, 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 } from './run/run-calls.ts';
+export { preview, type ToolDispatch } from './run/run-calls.ts';
 export { resetAll } from './runtime/reset.ts';
 export { createRuntime, defaultRuntime, type Runtime, type RuntimeOptions } from './runtime/runtime.ts';
 export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from './runtime/snapshot.ts';
@@ -37,5 +37,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, recoverToolCalls, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult, } from './wire/tool-calls.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 { FinishReason, FUNCTION_TOOL, JSON_SCHEMA_FORMAT, PartType, Role, SchemaType } from './wire/wire.ts';

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

@@ -9,7 +9,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 ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
+import { 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';
 /**
@@ -220,13 +220,35 @@ export interface AgentLoopOptions {
      * mode, where a tool is loaded only while its definition is in the history.
      */
     loaded?: Iterable<string>;
-    /** Runs one tool call and returns what the model reads. What it throws, the model reads too. */
+    /**
+     * Runs one tool call and returns what the model reads. What it throws, the model reads too.
+     *
+     * @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.
+     */
     dispatch: ToolDispatch;
     /**
-     * Runs a step's calls together rather than one after another. Results still go into the
-     * transcript in the order the model asked. See `dedupeToolCalls`, which applies either way.
+     * Runs a step's calls together rather than one after another, or — given a predicate — runs
+     * together the consecutive calls it passes, and each one it fails alone, in the order asked.
+     *
+     * @defaultValue `false`
+     *
+     * @remarks
+     * Results go into the transcript in the order the model asked, whichever way they ran. See
+     * `dedupeToolCalls`, which applies either way.
+     *
+     * A predicate is how a host runs reads together while its writes keep their order: a call it
+     * fails is a barrier, waiting for every call before it, and every call after waits for it. Read
+     * A, read B, write C, read D, read E runs as `[A ‖ B] → C → [D ‖ E]`, so a read asked for after
+     * a write sees what the write did. Calls the loop answers itself — `load_tools`, a call whose
+     * arguments could not be read, an identical repeat `dedupeToolCalls` answers — are not put to
+     * it, and count as reads. Inside a batch, `onToolResult` and the events arrive as calls finish.
+     * A pool that reads the MCP `readOnlyHint` annotation can answer it; nothing in an OpenAI tool
+     * definition can.
      */
-    parallel?: boolean;
+    parallel?: boolean | ((call: ToolCallRequest) => boolean);
     /**
      * Answers an identical repeat of a call — the same name and the same arguments, word for word —
      * within one step from the first one, rather than dispatching it again.
@@ -354,6 +376,12 @@ export interface AgentLoopResult {
      * proxied preselection's among them, first.
      */
     toolCalls: ToolCallOutcome[];
+    /**
+     * What the run's calls linked to, one per uri in the order first seen, each with the call and
+     * step that first linked to it and how many calls did. Empty where `dispatch` answered with
+     * strings only.
+     */
+    artifacts: RunArtifact[];
     /**
      * What is loaded at the end, for `carryOver`. Empty in eager mode, and in proxied mode: a
      * definition loaded there is already in the history, and one a compaction folded away has to be

package/dist/run/agent-loop.js

@@ -116,6 +116,7 @@ export async function runAgentLoop(options) {
             messages: [...options.messages],
             usage: noUsage(),
             toolCalls: [],
+            artifacts: [],
             loaded: [],
             used: [],
             preselected: [],
@@ -450,10 +451,12 @@ async function runSteps(options, standing) {
     let messages = [...options.messages];
     let usage = noUsage();
     const toolCalls = [];
+    const artifacts = new Map();
     standing.read = () => ({
         messages,
         usage,
         toolCalls,
+        artifacts: [...artifacts.values()],
         // As the result would have said it: proxied, nothing is loaded that the history does not hold.
         loaded: proxied ? [] : [...loaded],
         used: [...used],
@@ -498,6 +501,7 @@ async function runSteps(options, standing) {
         loads,
         used,
         toolCalls,
+        artifacts,
         dedupable,
         dispatch,
         parallel,
@@ -645,6 +649,7 @@ async function runSteps(options, standing) {
                 messages,
                 usage,
                 toolCalls,
+                artifacts: [...artifacts.values()],
                 loaded: proxied ? [] : [...loaded],
                 used: [...used],
                 preselected: [...preselected],

package/dist/run/events.d.ts

@@ -1,6 +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';
 /**
  * What a run is doing, while it is doing it.
  *
@@ -89,6 +90,12 @@ export declare const RunEventKind: {
     readonly ToolResult: 'tool-result';
     /** Something the runner did that is not the model's doing — a preselection, a retry. */
     readonly Notice: 'notice';
+    /**
+     * A tool call's answer linked to something the run had not produced before. `id` is the call's,
+     * `name` the tool, `text` the link's title or else its uri, and `link` the link itself. Once
+     * per uri per run: a later call that links the same uri again only adds to its count.
+     */
+    readonly Artifact: 'artifact';
     /**
      * 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
@@ -136,8 +143,8 @@ export interface TurnReport extends TurnUsage {
  * One thing that happened in a run, as a watcher receives it.
  *
  * @remarks
- * Every field but `id` is always present — the empty ones are `""` or `null` rather than
- * missing — so a client reads it without guarding each key.
+ * Every field but `id` and `link` is always present — the empty ones are `""` or `null` rather
+ * than missing — so a client reads it without guarding each key.
  */
 export interface RunEvent {
     /** The run it belongs to. `emit` fills this in; a caller does not pass it. */
@@ -175,6 +182,11 @@ export interface RunEvent {
     ok: boolean | null;
     /** Running totals on `usage`, otherwise null. */
     usage: RunUsage | null;
+    /**
+     * What the call produced, on `artifact` and on no other kind. Optional for the reason `id` is:
+     * an event built before it existed still compiles.
+     */
+    link?: ResourceLink;
 }
 /**
  * What `emit` is given: the run and the sequence are the bus's to assign.
@@ -300,6 +312,8 @@ export interface RunMetrics {
     toolErrors: Record<string, number>;
     /** `load_tools` calls. */
     loadCalls: number;
+    /** `artifact` events: the distinct things the run's tool calls linked to. */
+    artifacts: number;
     /**
      * Tools `load_tools` loaded that were not loaded already. Filled by `runAgentLoop`, which sees
      * the resolution; the events carry only its text.

package/dist/run/events.js

@@ -56,6 +56,12 @@ export const RunEventKind = {
     ToolResult: 'tool-result',
     /** Something the runner did that is not the model's doing — a preselection, a retry. */
     Notice: 'notice',
+    /**
+     * A tool call's answer linked to something the run had not produced before. `id` is the call's,
+     * `name` the tool, `text` the link's title or else its uri, and `link` the link itself. Once
+     * per uri per run: a later call that links the same uri again only adds to its count.
+     */
+    Artifact: 'artifact',
     /**
      * 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
@@ -500,6 +506,7 @@ export function runMetrics(events, { contextLength } = {}) {
         toolCalls: 0,
         toolErrors: {},
         loadCalls: 0,
+        artifacts: 0,
         promptTokens: 0,
         completionTokens: 0,
         cachedTokens: 0,
@@ -540,6 +547,9 @@ export function runMetrics(events, { contextLength } = {}) {
                 add('toolMs', event.at - called);
             }
         }
+        else if (event.kind === RunEventKind.Artifact) {
+            metrics.artifacts++;
+        }
         else if (event.kind === RunEventKind.Usage && event.usage?.turn) {
             const turn = event.usage.turn;
             last = turn;

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 ToolCall, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from '../wire/tool-calls.ts';
+import { type RunArtifact, type ToolAnswer, type ToolCall, type ToolCallOutcome, 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.
@@ -63,8 +63,11 @@ export declare const assistantMessage: (content: string, parsed: ReadCall[]) =>
  * @returns A new array of the definitions themselves, not copies.
  */
 export declare const definedAs: (definitions: ReadonlyMap<string, OpenAI.ChatCompletionTool>, names: Iterable<string>) => (OpenAI.ChatCompletionCustomTool | OpenAI.ChatCompletionFunctionTool)[];
-/** Runs one tool call and resolves to what the model reads; what it throws, the model reads too. */
-export type ToolDispatch = (call: ToolCallRequest, signal?: AbortSignal) => Promise<string>;
+/**
+ * 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.
+ */
+export type ToolDispatch = (call: ToolCallRequest, signal?: AbortSignal) => 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.
@@ -86,9 +89,12 @@ export interface Calling {
     };
     used: Set<string>;
     toolCalls: ToolCallOutcome[];
+    /** What the run's calls linked to, by uri, in the order first seen. */
+    artifacts: Map<string, RunArtifact>;
     dedupable: (call: ToolCallRequest) => boolean;
     dispatch: ToolDispatch;
-    parallel: boolean;
+    /** All of a step's calls together, each alone, or together in runs of the calls it passes. */
+    parallel: boolean | ((call: ToolCallRequest) => boolean);
     signal: AbortSignal | undefined;
     onEvent: (input: RunEventInput) => void;
     onToolCall: ((call: ToolCallRequest) => void) | undefined;

package/dist/run/run-calls.js

@@ -84,6 +84,13 @@ 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 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.
+ */
+const answerOf = (answer) => typeof answer === 'string' ? { text: answer, links: [] } : { text: answer.text, links: answer.links ?? [] };
 /**
  * What a call is shown, counted and dispatched as: a `call_tool` as the tool it names.
  *
@@ -129,6 +136,7 @@ function answerLoad(run, args) {
  * Makes a call at most once per key, sharing the in-flight promise so two identical calls in one
  * step make one request between them whether they run together or one after the other.
  *
+ * @typeParam T - What a call answers with.
  * @param answered - The step's calls so far, by key. Written to.
  * @param key - What makes two calls the same one.
  * @param make - Makes the call. Not called where the key has an answer, or one on its way.
@@ -157,23 +165,45 @@ async function once(answered, key, make) {
     }
 }
 /**
- * Runs one call to its result, telling the host of both. A tool that throws is that call's answer
- * rather than the run's end, unless the run was stopped.
+ * Adds one call's links to the run's artifacts, telling watchers of each uri the first time.
  *
- * @param run - The run the call belongs to.
+ * @param run - The run. Written to: a new uri is added to `artifacts`, and a known one counted.
+ * @param links - What the call's answer linked to.
+ * @param from - The call they came from.
+ */
+function collect(run, links, from) {
+    // Per call, so a tool that lists one uri twice in an answer is counted as making it once.
+    const seen = new Set();
+    for (const link of links) {
+        if (seen.has(link.uri)) {
+            continue;
+        }
+        seen.add(link.uri);
+        const known = run.artifacts.get(link.uri);
+        if (known) {
+            known.count++;
+            continue;
+        }
+        run.artifacts.set(link.uri, { link, ...from, count: 1 });
+        run.onEvent({ kind: RunEventKind.Artifact, id: from.callId, name: from.tool, text: link.title || link.uri, link });
+    }
+}
+/**
+ * A call looked through and built into the request every host callback is handed.
+ *
+ * @param run - The run the call belongs to. Read, never written to.
  * @param entry - The call, with its arguments read.
- * @param answered - The step's calls already made, by tool and arguments, for `dedupeToolCalls`.
- * @returns The call's id, the name it was shown under, whether it worked, and the whole of what
- * the model reads. Rejects where the run was stopped or a host callback threw.
+ * @returns The call, its request, and whether the loop answers it itself or may answer it from
+ * an identical call. `dedupeToolCalls` is asked only of a call that would reach `dispatch`.
  */
-async function runCall(run, entry, answered) {
-    const { catalog, onDemand, proxied, signal } = run;
-    const { call, args, error: unreadable, normal } = entry;
+function prepare(run, entry) {
+    const { catalog, onDemand } = run;
+    const { call, args, normal } = entry;
     const proxy = run.proxies && call.function.name === CALL_TOOL;
     const { name, input: raw } = shownAs(run, entry);
     // Looked through before the call is announced, so a host is told of the tool it names with
     // that tool's arguments. A name outside the catalogue is refused here, so `call_tool` reaches
-    // nothing a load could not, and the refusal is the call's answer below.
+    // nothing a load could not, and the refusal is the call's answer.
     let inner = args ?? {};
     let refused;
     if (proxy && args) {
@@ -188,17 +218,91 @@ async function runCall(run, entry, answered) {
     // 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 };
+    // 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;
+    const dispatched = args !== undefined && load === false && refused === undefined;
+    // Keyed on the inner call, so one made through `call_tool` and one made natively share.
+    const key = `${name}\0${proxy ? JSON.stringify(inner) : normal}`;
+    return { entry, request, load, refused, dedupable: dispatched && run.dedupable(request), key };
+}
+/**
+ * Whether a call is answered without `dispatch` seeing it, so it can run beside anything.
+ *
+ * @param prepared - The call.
+ * @param answered - The step's calls already made, by key. A call that threw is not in it.
+ * @param batch - The keys of the calls in the batch being gathered, which a repeat shares.
+ * @returns True for a `load_tools`, a call whose arguments could not be read, a `call_tool` that
+ * was refused, and an identical repeat that `dedupeToolCalls` answers from the first.
+ */
+const answersItself = ({ entry, load, refused, dedupable, key }, answered, batch) => entry.args === undefined || load || refused !== undefined || (dedupable && (answered.has(key) || batch.has(key)));
+/**
+ * Where the batch of calls starting at `from` ends: every call, one call, or the calls up to the
+ * first one the host's predicate does not pass.
+ *
+ * @param run - The run, read for `parallel`.
+ * @param ready - The step's calls by position, prepared as they are first asked for.
+ * @param from - Where the batch starts.
+ * @param total - How many calls the step has.
+ * @param answered - The step's calls already made, by key.
+ * @returns The position after the batch's last call; always past `from`.
+ *
+ * @remarks
+ * A call the predicate fails is a barrier: it waits for every call before it, and runs alone, so
+ * a read asked for after a write sees what the write did. Calls the loop answers itself are not
+ * put to the predicate — they touch nothing a tool could — and count as reads.
+ */
+function batchEnd(run, ready, from, total, answered) {
+    const { parallel } = run;
+    if (parallel === true) {
+        return total;
+    }
+    if (parallel === false) {
+        return from + 1;
+    }
+    const batch = new Set();
+    for (let at = from; at < total; at++) {
+        const prepared = ready(at);
+        prepared.passed ??= answersItself(prepared, answered, batch) || parallel(prepared.request);
+        const reads = prepared.passed;
+        if (reads === false) {
+            return at === from ? at + 1 : at;
+        }
+        if (prepared.dedupable) {
+            batch.add(prepared.key);
+        }
+    }
+    return total;
+}
+/**
+ * Runs one call to its result, telling the host of both. A tool that throws is that call's answer
+ * rather than the run's end, unless the run was stopped.
+ *
+ * @param run - The run the call belongs to.
+ * @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.
+ */
+async function runCall(run, prepared, answered, step) {
+    const { catalog, onDemand, proxied, signal } = run;
+    const { entry, request, load, refused, dedupable, key } = prepared;
+    const { call, args, error: unreadable } = entry;
+    const { name, raw } = request;
     run.onEvent({ kind: RunEventKind.ToolCall, id: call.id, name, text: preview(raw) });
     run.onToolCall?.(request);
     let content;
+    let links = [];
     let ok = true;
+    // Answered from an earlier identical call of the step, whose links are already counted.
+    let shared = false;
     try {
         if (!args) {
             throw unreadable;
         }
-        // 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 below like any other.
-        if (onDemand && call.function.name === LOAD_TOOLS) {
+        if (load) {
             ({ content, ok } = answerLoad(run, args));
         }
         else {
@@ -212,11 +316,12 @@ async function runCall(run, entry, answered) {
                 run.loaded.add(name);
             }
             run.used.add(name);
-            // Keyed on the inner call, so one made through `call_tool` and one made natively share.
-            const key = `${name}\0${proxy ? JSON.stringify(inner) : normal}`;
-            content = run.dedupable(request)
+            // Read before `once` looks, which it does before it awaits anything.
+            shared = dedupable && answered.has(key);
+            const answer = dedupable
                 ? await once(answered, key, () => run.dispatch(request, signal))
                 : await run.dispatch(request, signal);
+            ({ text: content, links } = answerOf(answer));
         }
     }
     catch (error) {
@@ -227,7 +332,11 @@ async function runCall(run, entry, answered) {
         ok = false;
     }
     run.onEvent({ kind: RunEventKind.ToolResult, id: call.id, name, ok, text: preview(content) });
-    const result = { id: call.id, name, ok, content };
+    const isFirstAnswer = shared === false;
+    if (isFirstAnswer) {
+        collect(run, links, { callId: call.id, tool: name, step });
+    }
+    const result = { id: call.id, name, ok, content, ...(links.length ? { links } : {}) };
     run.onToolResult?.(result);
     return result;
 }
@@ -265,26 +374,29 @@ export async function runCalls(run, parsed, messages, step) {
         kept++;
         await run.announce(result, step);
     };
+    // Prepared when first asked for, so a predicate is put only calls the step got to.
+    const prepared = [];
+    const ready = (at) => {
+        prepared[at] ??= prepare(run, parsed[at]);
+        return prepared[at];
+    };
     try {
-        if (run.parallel) {
+        // One batch of every call, a batch per call, or batches split at the calls the host's
+        // predicate does not pass; a batch's calls run together and the next waits for all of them.
+        let from = 0;
+        while (from < parsed.length) {
             signal?.throwIfAborted();
-            begun = parsed.length;
-            await Promise.all(parsed.map(async (call, at) => {
-                outcomes[at] = await runCall(run, call, answered);
+            const start = from;
+            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);
             }));
-            for (const { id, name, ok, content } of outcomes.flatMap((outcome) => outcome ?? [])) {
-                toolCalls.push({ id, name, ok });
-                await keep(id, content);
-            }
-        }
-        else {
-            for (const [at, call] of parsed.entries()) {
-                signal?.throwIfAborted();
-                begun = at + 1;
-                const { id, name, ok, content } = await runCall(run, call, answered);
+            for (const { id, name, ok, content } of outcomes.slice(from, to).flatMap((outcome) => outcome ?? [])) {
                 toolCalls.push({ id, name, ok });
                 await keep(id, content);
             }
+            from = to;
         }
     }
     catch (error) {

package/dist/wire/errors.d.ts

@@ -1,7 +1,7 @@
 import type OpenAI from 'openai';
 import { ContextOverflow } from './retry.ts';
 import type { TurnUsage } from './stream.ts';
-import type { ToolCallOutcome } from './tool-calls.ts';
+import type { RunArtifact, ToolCallOutcome } from './tool-calls.ts';
 /**
  * What went wrong, as a string.
  *
@@ -34,6 +34,12 @@ export interface AgentLoopFailure {
     usage: TurnUsage;
     /** Every call that was made, in order. One the run was stopped during is `ok: false`. */
     toolCalls: ToolCallOutcome[];
+    /**
+     * What the calls that came back linked to, as the result's `artifacts` would have said it: a
+     * failed run's writes were still made. `runAgentLoop` always sets it; optional so a failure
+     * built before it existed still compiles.
+     */
+    artifacts?: RunArtifact[];
     /** What was loaded when the run failed, for `carryOver`. Empty in eager and proxied modes. */
     loaded: string[];
     /** The tools the model had called, `load_tools` excluded. */
@@ -55,6 +61,7 @@ export declare class AgentLoopError extends Error implements AgentLoopFailure {
     readonly messages: OpenAI.ChatCompletionMessageParam[];
     readonly usage: TurnUsage;
     readonly toolCalls: ToolCallOutcome[];
+    readonly artifacts: RunArtifact[];
     readonly loaded: string[];
     readonly used: string[];
     readonly preselected: string[];
@@ -88,6 +95,7 @@ export declare class AgentLoopOverflow extends ContextOverflow implements AgentL
     readonly messages: OpenAI.ChatCompletionMessageParam[];
     readonly usage: TurnUsage;
     readonly toolCalls: ToolCallOutcome[];
+    readonly artifacts: RunArtifact[];
     readonly loaded: string[];
     readonly used: string[];
     readonly preselected: string[];

package/dist/wire/errors.js

@@ -26,6 +26,7 @@ export class AgentLoopError extends Error {
     messages;
     usage;
     toolCalls;
+    artifacts;
     loaded;
     used;
     preselected;
@@ -39,6 +40,7 @@ export class AgentLoopError extends Error {
         this.messages = run.messages;
         this.usage = run.usage;
         this.toolCalls = run.toolCalls;
+        this.artifacts = run.artifacts ?? [];
         this.loaded = run.loaded;
         this.used = run.used;
         this.preselected = run.preselected;
@@ -67,6 +69,7 @@ export class AgentLoopOverflow extends ContextOverflow {
     messages;
     usage;
     toolCalls;
+    artifacts;
     loaded;
     used;
     preselected;
@@ -80,6 +83,7 @@ export class AgentLoopOverflow extends ContextOverflow {
         this.messages = run.messages;
         this.usage = run.usage;
         this.toolCalls = run.toolCalls;
+        this.artifacts = run.artifacts ?? [];
         this.loaded = run.loaded;
         this.used = run.used;
         this.preselected = run.preselected;

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

@@ -146,4 +146,68 @@ export interface ToolCallResult extends ToolCallOutcome {
      * `load_tools` answer, or why the arguments could not be read.
      */
     content: string;
+    /**
+     * What the dispatcher's answer said the call produced, as it said it. Absent where it said
+     * nothing, and always for a call that threw. A deduplicated repeat carries the first call's.
+     */
+    links?: ResourceLink[];
+}
+/**
+ * A handle to something a tool call made or found — a document it wrote, a file it saved.
+ *
+ * @remarks
+ * MCP's `ResourceLink` less its `type`, declared structurally rather than imported, the way
+ * agent-mcp-pool declares `ToolDefinition` against `ChatCompletionTool`: the pool's own
+ * `ResourceLink` has these field names exactly, so its answer is assignable here and neither
+ * package depends on the other.
+ */
+export interface ResourceLink {
+    uri: string;
+    name: string;
+    title?: string;
+    mimeType?: string;
+    description?: string;
+    /** Who the link is for, how much it matters, and when it last changed — the server's word. */
+    annotations?: {
+        audience?: ('user' | 'assistant')[];
+        priority?: number;
+        lastModified?: string;
+    };
+    _meta?: Record<string, unknown>;
+}
+/**
+ * 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.
+ *
+ * @remarks
+ * 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.
+ */
+export interface ToolAnswer {
+    /** What goes into the transcript, exactly as a string answer does. */
+    text: string;
+    /** What the call produced, in the order the tool gave them. Never sent to the model. */
+    links?: ResourceLink[];
+}
+/**
+ * One thing a run's tool calls produced: the first link to a uri, and where it came from.
+ *
+ * @remarks
+ * A link is what one call answered with; an artifact is what the run made, one per uri however
+ * many calls linked to it.
+ */
+export interface RunArtifact {
+    /** The link as the first call to give its uri gave it. A later call's says nothing new here. */
+    link: ResourceLink;
+    /** The call that first linked to it. */
+    callId: string;
+    /** That call's tool. For a `call_tool`, the tool it named. */
+    tool: string;
+    /** The loop's step that call was made in, from 0. */
+    step: number;
+    /**
+     * How many calls linked to it. A deduplicated repeat does not count, since nothing was made
+     * twice, and a call that links one uri twice counts once.
+     */
+    count: number;
 }

package/llms.txt

@@ -185,6 +185,7 @@ What a run is doing, while it is doing it.
 The tools between two turns: a step's calls read, run and written into the transcript.
 
 - `preview` — A long tool argument or result cut to what a watcher needs, with the full length said.
+- `ToolDispatch` (type) — 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.
 
 ### reset
 
@@ -384,7 +385,10 @@ 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.
 - `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.
+- `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.

package/package.json

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