agentfootprint 9.24.0 → 9.26.0

package/dist/core/agent/repeatedCall.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * core/agent/repeatedCall — tell a model when it has already asked this.
+ *
+ * ── The measured failure ────────────────────────────────────────────────────
+ * A traced production run: the model called one tool three times in a row with
+ * byte-identical arguments and got a byte-identical result each time. The tool
+ * was doing its job — the arguments named a filter the backend did not honour,
+ * so the same rows came back — and the model read the same rows as a fresh
+ * answer each iteration, concluded nothing had changed, and tried again. Three
+ * calls, three identical results, one wasted turn, and nothing anywhere in the
+ * loop that could say "you have done this".
+ *
+ * That class of loop is invisible from inside the conversation, because the
+ * history genuinely does show three separate calls that each returned data. The
+ * only party with the whole picture is the framework, which watched all three
+ * land.
+ *
+ * ── The intervention: a NOTE, never a refusal ───────────────────────────────
+ * On the Nth identical (tool, args) → identical result, the framework appends
+ * one sentence to that result. It does not block the call, does not change the
+ * result, does not error, and does not stop a later identical call from
+ * running. That restraint is the design:
+ *
+ *   • **A repeat is sometimes correct.** Polling a job until its status
+ *     changes is a loop of identical calls returning identical results, on
+ *     purpose. Refusing it would break a legitimate pattern to fix an
+ *     illegitimate one, and the model is the only party that knows which it is
+ *     doing.
+ *   • **A note is evidence; a refusal is a wall.** The model reads what
+ *     happened and decides. That is the same posture every teaching refusal in
+ *     this library takes, minus the refusal.
+ *
+ * ── Why the result must match too ───────────────────────────────────────────
+ * Identical ARGUMENTS alone are not evidence of anything: a "check status" call
+ * with the same arguments returning a DIFFERENT status is progress. It is the
+ * identical RESULT that makes the repeat pointless, so both halves are
+ * required. Which also means the note can say something true and specific —
+ * *calling again will not change it* — rather than a vague "you seem to be
+ * repeating yourself".
+ *
+ * ── What is stored, and what is deliberately not ────────────────────────────
+ * A short non-cryptographic FINGERPRINT of the arguments and the result, never
+ * the values. Tool arguments routinely carry the things redaction exists for,
+ * and a fingerprint answers the only question this feature asks ("is this the
+ * same?") and answers nothing else.
+ *
+ * ── And WHERE it is stored: beside the run, never inside its state ──────────
+ * The counters live in {@link repeatedCallLedgers}, a run-keyed map the
+ * dispatch loop holds — NOT on tracked scope. That is not a tidiness
+ * preference, it is the zero-cost law:
+ *
+ *   • Tracked scope IS the commit log, the snapshot, the narrative, every
+ *     recording and every causal slice. A key written there on every tool
+ *     landing would appear in all of them for every existing agent the moment
+ *     it upgraded — a turn that never repeated anything would no longer be
+ *     byte-identical to the release before, and a consumer asserting a state-key
+ *     set would break for a feature it never asked for.
+ *   • A within-turn counter is not conversation state. Nothing resumes from it,
+ *     nothing branches on it later, and no reader of a trace needs it: the
+ *     repeat itself lands on the record as `agentfootprint.tools.repeated_call`,
+ *     which is the telemetry channel this library puts per-attempt facts on
+ *     (the same reasoning as retries and streaming tokens, and the same
+ *     reasoning that keeps a consent record off tracked state).
+ *
+ * So an agent that never repeats a call is byte-identical to 9.25 in behaviour,
+ * in state AND in events — the ledger exists only in memory, only for the
+ * duration of a run, and only where a tool actually landed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noteRepeatedCall = exports.repeatedCallKey = exports.repeatedCallLedgers = exports.REPEATED_CALL_THRESHOLD = void 0;
+/** How many identical (tool, args, result) landings trigger the note. The
+ *  SECOND one: the first repeat is the first moment the fact exists. */
+exports.REPEATED_CALL_THRESHOLD = 2;
+/** How many runs' counters one dispatch loop keeps at once. Small on purpose:
+ *  concurrent runs on ONE agent instance are the only reason for more than
+ *  one, and a deployment serving many callers at once gives each its own
+ *  agent (that is what `agentFactory` is for). */
+const LEDGER_RUNS = 8;
+/** Build the run-keyed holder. One per agent — the chart is built once, so the
+ *  loop that owns this is built once too. */
+function repeatedCallLedgers(maxRuns = LEDGER_RUNS) {
+    const byRun = new Map();
+    return {
+        read: (runId) => byRun.get(runId),
+        write: (runId, ledger) => {
+            // Delete-then-set makes insertion order recency order, which is what the
+            // eviction below reads.
+            byRun.delete(runId);
+            byRun.set(runId, ledger);
+            while (byRun.size > maxRuns) {
+                const oldest = byRun.keys().next();
+                if (oldest.done === true)
+                    break;
+                byRun.delete(oldest.value);
+            }
+        },
+    };
+}
+exports.repeatedCallLedgers = repeatedCallLedgers;
+/**
+ * A stable, order-insensitive fingerprint of one call.
+ *
+ * Object keys are SORTED before hashing, at every depth: `{ a: 1, b: 2 }` and
+ * `{ b: 2, a: 1 }` are the same call, and a model that happens to emit its JSON
+ * in a different key order twice is repeating itself just as surely. Arrays
+ * keep their order, because `[1, 2]` and `[2, 1]` are not the same argument.
+ */
+function stableString(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'undefined';
+    if (Array.isArray(value))
+        return `[${value.map(stableString).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableString(v)}`).join(',')}}`;
+}
+/**
+ * FNV-1a, 32-bit, as 8 hex characters.
+ *
+ * Non-cryptographic ON PURPOSE and stated as such: this compares a string to
+ * ITSELF a few iterations later inside one run, where an adversary has nothing
+ * to gain from a collision and the cost of `crypto.subtle` (async, and one
+ * digest per tool result) buys nothing. A collision produces one unnecessary
+ * teaching note, which is the cheapest possible failure this could have.
+ */
+function fingerprint(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+/**
+ * The two fingerprints for one landing, and the ledger key that joins them.
+ *
+ * Kept apart on the way out so a debugger reading the event can tell "same
+ * call, different answer" from "same call, same answer" — without either value
+ * being present anywhere.
+ */
+function repeatedCallKey(toolName, args, result) {
+    const argsFingerprint = fingerprint(stableString(args));
+    const resultFingerprint = fingerprint(result);
+    return {
+        key: `${toolName}:${argsFingerprint}:${resultFingerprint}`,
+        argsFingerprint,
+        resultFingerprint,
+    };
+}
+exports.repeatedCallKey = repeatedCallKey;
+/**
+ * The teaching sentence.
+ *
+ * It says three things, in the order the model needs them: what happened (the
+ * fact it cannot see), what follows from it (calling again is not going to
+ * help), and what to do instead (two named options, neither of which is "stop"
+ * — a model told only to stop tends to stop answering).
+ */
+function noteFor(toolName, occurrences) {
+    return (`\n\n[identical call: '${toolName}' has now returned exactly this result ${occurrences} ` +
+        `times this turn, for exactly these arguments. Calling it again will not change it — ` +
+        `act on what you have, or change the arguments (a different filter, a wider range, a ` +
+        `different tool). If you are waiting for something to change, say so in your answer ` +
+        `rather than calling again.]`);
+}
+/**
+ * Record one landing and decide whether it earns the note.
+ *
+ * PURE — takes the ledger, returns the next one. The dispatch loop owns reading
+ * and writing scope, so this file never imports the agent and can be tested as
+ * a table.
+ *
+ * The note fires ONCE per distinct call, on the Nth landing exactly. A third
+ * and fourth identical call add nothing further: the model has been told, and
+ * repeating the lesson every iteration would be the framework doing the very
+ * thing it is complaining about.
+ */
+function noteRepeatedCall(ledger, toolName, args, result) {
+    const { key, argsFingerprint, resultFingerprint } = repeatedCallKey(toolName, args, result);
+    const occurrences = (ledger?.[key] ?? 0) + 1;
+    const next = { ...(ledger ?? {}), [key]: occurrences };
+    const outcome = { ledger: next, occurrences, argsFingerprint, resultFingerprint };
+    if (occurrences !== exports.REPEATED_CALL_THRESHOLD)
+        return outcome;
+    return { ...outcome, note: noteFor(toolName, occurrences) };
+}
+exports.noteRepeatedCall = noteRepeatedCall;
+//# sourceMappingURL=repeatedCall.js.map

package/dist/core/agent/repeatedCall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeatedCall.js","sourceRoot":"","sources":["../../../src/core/agent/repeatedCall.ts"],"names":[],"mappings":"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"}

package/dist/core/agent/stages/toolCalls.js

@@ -62,6 +62,7 @@ const askComponent_js_1 = require("../../askComponent.js");
 const checkin_js_1 = require("../../checkin.js");
 const runChain_js_1 = require("../middleware/runChain.js");
 const ledger_js_1 = require("../middleware/ledger.js");
+const repeatedCall_js_1 = require("../repeatedCall.js");
 const toolArgsValidation_js_1 = require("../toolArgsValidation.js");
 const validators_js_1 = require("../validators.js");
 const toolResultCap_js_1 = require("../toolResultCap.js");
@@ -222,6 +223,17 @@ function argsForPausedCall(scope, toolCallId) {
 function appendBatchResult(scope, entry) {
     scope.toolResults = [...(scope.toolResults ?? []), entry];
 }
+/**
+ * The ledger key for a handler built with no `currentRun` accessor — a
+ * hand-composed dispatch loop in a test, never an Agent (which always wires
+ * it).
+ *
+ * One shared bucket, stated rather than hidden: without a run id there is
+ * nothing to tell two runs apart by, and the honest consequence is that such a
+ * loop counts across them. It cannot leak anything — the ledger holds
+ * fingerprints — and the only visible effect is a note arriving one call early.
+ */
+const UNSCOPED_RUN = '#no-run-id';
 function buildToolCallsHandler(deps) {
     const { registryByName, externalToolProvider, providerToolCache, permissionChecker } = deps;
     const toolArgValidation = deps.toolArgValidation ?? 'enforce';
@@ -232,6 +244,10 @@ function buildToolCallsHandler(deps) {
     // that THROWS on use (never undefined) — so a tool can't silently no-op.
     const credentials = deps.credentialProvider ?? (0, types_js_2.unconfiguredCredentialProvider)();
     const hasCredentials = deps.credentialProvider !== undefined;
+    // The repeated-call counters (9.26.0), run-keyed and OFF tracked scope — an
+    // empty Map here, and not one byte written anywhere a reader can see until a
+    // tool actually lands. See `../repeatedCall.ts` for why they are not state.
+    const repeatLedgers = (0, repeatedCall_js_1.repeatedCallLedgers)();
     /**
      * The tool-result ceiling, applied at the ONE place a result leaves dispatch.
      *
@@ -2035,6 +2051,11 @@ function buildToolCallsHandler(deps) {
                     ...(toolStatus !== undefined && { status: toolStatus }),
                 });
                 let resultStr = typeof modelResult === 'string' ? modelResult : (0, validators_js_1.safeStringify)(modelResult);
+                // The tool's OWN answer, before any framework suffix joins it — what
+                // the repeated-call ledger fingerprints. Fingerprinting the decorated
+                // string instead would compare our own additions (a step that advanced
+                // once, an effect note) and miss the repeat they decorate.
+                const deliveredResult = resultStr;
                 // ── Step boundary (9.18.0): advance decided, then decorate, THEN
                 // push — the suffix must be part of the one past every reader sees
                 // (history, `lastToolResult`, the batch), never spliced in later.
@@ -2071,6 +2092,35 @@ function buildToolCallsHandler(deps) {
                 if (toolEnvelope !== undefined && executed && !error && !denied) {
                     resultStr += applyToolEffects(scope, { toolName: tc.name, toolCallId: tc.id, iteration }, toolEnvelope, transitionState);
                 }
+                // ── Repeated-call nudge (9.26.0) ───────────────────────────────
+                // The framework is the only party that watched all three landings, so
+                // it is the only one that can say so. A NOTE on the result — the call
+                // ran, nothing was refused, and a later identical call is not blocked.
+                // Only for a call that RAN: a permission denial, a gate rejection and
+                // a ceiling refusal each already teach their own lesson, and stacking
+                // a second one would bury it.
+                if (deps.repeatedCallNudge !== false && executed && !denied && !skillRejected) {
+                    // Counted beside the run, never inside its state: a tracked write is
+                    // a commit-log entry, a snapshot key, a narrative line and a row in
+                    // every recording, and a turn that repeats NOTHING must stay
+                    // byte-identical to the release before this one. `currentRun()` is
+                    // the same accessor `ctx.runId` is composed from — one answer to
+                    // "which run is this", not a second spelling of it.
+                    const runKey = deps.currentRun?.().runId ?? UNSCOPED_RUN;
+                    const repeat = (0, repeatedCall_js_1.noteRepeatedCall)(repeatLedgers.read(runKey), tc.name, callArgs, deliveredResult);
+                    repeatLedgers.write(runKey, repeat.ledger);
+                    if (repeat.note !== undefined) {
+                        resultStr += repeat.note;
+                        (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.tools.repeated_call', {
+                            toolName: tc.name,
+                            toolCallId: tc.id,
+                            iteration,
+                            occurrences: repeat.occurrences,
+                            argsFingerprint: repeat.argsFingerprint,
+                            resultFingerprint: repeat.resultFingerprint,
+                        });
+                    }
+                }
                 newHistory.push({
                     role: 'tool',
                     content: resultStr,