@cubicecho/agent-core 4.6.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`,

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

@@ -230,10 +230,25 @@ export interface AgentLoopOptions {
      */
     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.
-     */
-    parallel?: boolean;
+     * 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 | ((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.

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

@@ -93,7 +93,8 @@ export interface Calling {
     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

@@ -189,25 +189,21 @@ function collect(run, links, from) {
     }
 }
 /**
- * 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.
+ * A call looked through and built into the request every host callback is handed.
  *
- * @param run - The run the call belongs to.
+ * @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`.
- * @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 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, step) {
-    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) {
@@ -222,6 +218,79 @@ async function runCall(run, entry, answered, step) {
     // 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;
@@ -233,9 +302,7 @@ async function runCall(run, entry, answered, step) {
         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 {
@@ -249,9 +316,6 @@ async function runCall(run, entry, answered, step) {
                 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}`;
-            const dedupable = run.dedupable(request);
             // Read before `once` looks, which it does before it awaits anything.
             shared = dedupable && answered.has(key);
             const answer = dedupable
@@ -310,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, step);
+            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, step);
+            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/package.json

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