@cubicecho/agent-core 2.14.0 → 2.15.0

package/README.md

@@ -370,10 +370,17 @@ 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`, which also makes an identical call — the same name and arguments, byte for byte
-— once for the run. A call that threw is forgotten rather than cached, so asking again is a real
-retry. What a tool throws is what the model reads, and so are arguments that did not parse.
+out. Between steps the loop runs the calls: sequentially by default, or together with `parallel: true`.
+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
+reads, and so are arguments that did not parse.
+
+The scope is the step, not the run: between steps other tools have run, and the file the model read
+may be the file it has since written. `dedupeToolCalls: false` dispatches everything, and a
+predicate is asked per call — which is how `send_email` opts out, since twice is two emails and
+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.
 
 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
@@ -382,7 +389,7 @@ string. What still is not an object throws a `ToolArgumentsError` whose `kind` i
 the turn stopped at the ceiling, with a message telling the model so, and `malformed` otherwise.
 The repaired JSON is what the transcript keeps, and an unreadable call is replayed as `{}`, because
 a server that parses replayed arguments refuses the originals on every later request. `dispatch`
-is still handed the model's own text as `raw`, and the parallel dedupe compares repaired arguments,
+is still handed the model's own text as `raw`, and the dedupe compares repaired arguments,
 so `{'a': 1}` and `{"a": 1}` are one call.
 
 A server whose tool-call parser was written for another template streams the model's call as

package/dist/agent-loop.d.ts

@@ -152,12 +152,26 @@ export interface AgentLoopOptions {
     /** Runs one tool call and returns what the model reads. What it throws, the model reads too. */
     dispatch: (call: ToolCallRequest, signal?: AbortSignal) => Promise<string>;
     /**
-     * Runs a step's calls together rather than one after another, and makes an identical call —
-     * the same name and arguments, word for word — once for the run, handing a repeat the first
-     * answer. A call that threw is not an answer and is made again. Results still go into the
-     * transcript in the order the model asked.
+     * 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;
+    /**
+     * 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.
+     *
+     * On by default, and on whether or not the calls run in `parallel`: a model that asks the same
+     * question twice in one reply gets one answer, and two that are still in flight share the
+     * request. A call that threw is not an answer and is made again. The scope is the step and not
+     * the run, because between steps other tools have run and the file the model read may be the
+     * file it has since written.
+     *
+     * `false` dispatches every call. A predicate is asked per call and is how a tool that does
+     * something rather than reads something opts out — `send_email` twice is two emails, and this
+     * package cannot tell which tools those are. A pool that reads the MCP `readOnlyHint` and
+     * `idempotentHint` annotations can answer it; nothing in an OpenAI tool definition can.
+     */
+    dedupeToolCalls?: boolean | ((call: ToolCallRequest) => boolean);
     /** Hooks gathered onto the question before the first request, and told the reply after. */
     hooks?: AgentLoopHooks;
     /**

package/dist/agent-loop.js

@@ -202,7 +202,8 @@ function cacheDiagnosis(previous, messages, tools, usage) {
  */
 export async function runAgentLoop(options) {
     const { config, system = "", tools = [], catalog = [], dispatch, hooks, signal } = options;
-    const { onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, } = options;
+    const { onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, dedupeToolCalls = true, } = options;
+    const dedupable = typeof dedupeToolCalls === "function" ? dedupeToolCalls : () => dedupeToolCalls;
     const started = Date.now();
     // What the loop emitted, less the token deltas, for `runMetrics` at the end. Stamped here rather
     // than by the bus, which the loop does not know about.
@@ -259,7 +260,6 @@ export async function runAgentLoop(options) {
         : { context: "", notes: [] };
     const usage = { prompt: 0, completion: 0, total: 0, cached: 0 };
     const toolCalls = [];
-    const answered = new Map();
     const loads = { toolsLoaded: 0, redundantLoads: 0, unknownToolNames: 0 };
     let previous;
     for (let step = 0; step < config.maxToolIterations; step++) {
@@ -411,6 +411,9 @@ export async function runAgentLoop(options) {
                 },
             };
         }
+        // Per step, not per run: the answer to a call made two steps ago was true before the tools in
+        // between ran, and the file the model read may be the file it has since written.
+        const answered = new Map();
         const run = async ({ call, args, error: unreadable, normal }) => {
             const { name, arguments: raw } = call.function;
             onEvent({ kind: "tool-call", name, text: preview(raw) });
@@ -436,7 +439,7 @@ export async function runAgentLoop(options) {
                         loaded.add(name);
                     used.add(name);
                     const request = { id: call.id, name, args, raw };
-                    content = parallel
+                    content = dedupable(request)
                         ? await once(answered, `${name}\0${normal}`, () => dispatch(request, signal))
                         : await dispatch(request, signal);
                 }
@@ -470,8 +473,8 @@ export async function runAgentLoop(options) {
 }
 /**
  * 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. A call that rejected is forgotten, so asking again is a
- * real retry rather than a replayed failure.
+ * step make one request between them whether they run together or one after the other. A call
+ * that rejected is forgotten, so asking again is a real retry rather than a replayed failure.
  */
 async function once(answered, key, make) {
     const previous = answered.get(key);

package/package.json

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