agentfootprint 9.25.0 → 9.26.0

package/dist/esm/core/agent/repeatedCall.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 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.
+ */
+/** How many identical (tool, args, result) landings trigger the note. The
+ *  SECOND one: the first repeat is the first moment the fact exists. */
+export declare const REPEATED_CALL_THRESHOLD = 2;
+/**
+ * The ledger: fingerprint → how many times this exact (tool, args, result) has
+ * landed in this run.
+ *
+ * A plain record of small strings to numbers — a few dozen bytes per distinct
+ * call, and nothing in it that could not be printed in a bug report.
+ */
+export type RepeatedCallLedger = Readonly<Record<string, number>>;
+/**
+ * Where the ledgers live: one per RUN, held beside the dispatch loop.
+ *
+ * ── Why the run and not the conversation ────────────────────────────────────
+ * The failure this counts is a model calling the same thing twice inside ONE
+ * answer. A counter that spanned turns would tell somebody who asked the same
+ * question again tomorrow that they had already asked — which is true, and not
+ * what the note says. `runId` is the exact grain, and it is already the key
+ * every event on this run is stamped with.
+ *
+ * A resume mints a fresh `runId`, so a run that was paused for a person and
+ * continued starts counting again. That is the honest reading of "this turn":
+ * the framework watched half of it.
+ *
+ * ── Why BOUNDED ─────────────────────────────────────────────────────────────
+ * One agent instance serves many runs, and nothing tells this map when a run
+ * ended — a run can also end by throwing, by pausing forever, or by the process
+ * losing interest. So it keeps the most recent few and drops the rest. The cost
+ * of dropping one is exactly one note that is never given; it can never produce
+ * a note for the wrong run, because a run only ever reads counters filed under
+ * its own id.
+ */
+export interface RepeatedCallLedgers {
+    /** This run's counters, or `undefined` before its first tool landed. */
+    read(runId: string): RepeatedCallLedger | undefined;
+    /** File this run's counters, evicting the least recently written run when
+     *  the map is full. */
+    write(runId: string, ledger: RepeatedCallLedger): void;
+}
+/** Build the run-keyed holder. One per agent — the chart is built once, so the
+ *  loop that owns this is built once too. */
+export declare function repeatedCallLedgers(maxRuns?: number): RepeatedCallLedgers;
+/**
+ * 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.
+ */
+export declare function repeatedCallKey(toolName: string, args: unknown, result: string): {
+    readonly key: string;
+    readonly argsFingerprint: string;
+    readonly resultFingerprint: string;
+};
+/** What one landing came to. `occurrences` counts THIS one. */
+export interface RepeatedCallOutcome {
+    /** The ledger to write back to scope. */
+    readonly ledger: RepeatedCallLedger;
+    /** How many times this exact call+result has now landed this run. */
+    readonly occurrences: number;
+    /** The sentence to append, or `undefined` when this landing is not a
+     *  repeat (or the note has already been given for it). */
+    readonly note?: string;
+    /** Digest of the arguments — never the arguments. Rides the typed event. */
+    readonly argsFingerprint: string;
+    /** Digest of the result — never the result. */
+    readonly resultFingerprint: string;
+}
+/**
+ * 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.
+ */
+export declare function noteRepeatedCall(ledger: RepeatedCallLedger | undefined, toolName: string, args: unknown, result: string): RepeatedCallOutcome;

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

@@ -0,0 +1,184 @@
+/**
+ * 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.
+ */
+/** How many identical (tool, args, result) landings trigger the note. The
+ *  SECOND one: the first repeat is the first moment the fact exists. */
+export const 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. */
+export 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);
+            }
+        },
+    };
+}
+/**
+ * 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.
+ */
+export function repeatedCallKey(toolName, args, result) {
+    const argsFingerprint = fingerprint(stableString(args));
+    const resultFingerprint = fingerprint(result);
+    return {
+        key: `${toolName}:${argsFingerprint}:${resultFingerprint}`,
+        argsFingerprint,
+        resultFingerprint,
+    };
+}
+/**
+ * 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.
+ */
+export 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 !== REPEATED_CALL_THRESHOLD)
+        return outcome;
+    return { ...outcome, note: noteFor(toolName, occurrences) };
+}
+//# sourceMappingURL=repeatedCall.js.map

package/dist/esm/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/esm/core/agent/stages/toolCalls.d.ts

@@ -118,6 +118,18 @@ export interface ToolCallsHandlerDeps {
      * `../toolResultCap.ts` for the shape and why it is opt-in.
      */
     readonly maxToolResultChars?: number;
+    /**
+     * Tell the model when it has already made this exact call and already got
+     * this exact answer (9.26.0). Threaded from `AgentOptions.repeatedCallNudge`,
+     * and only when the operator turned it OFF — `undefined` here means the
+     * default, which is on.
+     *
+     * Applied at the BATCH dispatch loop only, which is where a turn's repeats
+     * actually happen. The pause-resume paths deliver a call a PERSON answered
+     * or approved, and a note telling the model it has already done what a human
+     * just authorised would be the framework arguing with the human.
+     */
+    readonly repeatedCallNudge?: boolean;
     /**
      * Skill-graph read_skill GATE (`graph.reachableSkills`). When present, a
      * `read_skill('id')` whose `id` is not reachable from the current cursor is

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

@@ -59,6 +59,7 @@ import { assertAskComponent, InvalidAskComponentError, } from '../../askComponen
 import { shouldCheckIn, isCheckInDecision, checkInDeclined, } from '../../checkin.js';
 import { runToolChain, runToolAfterChain } from '../middleware/runChain.js';
 import { recordDecisions } from '../middleware/ledger.js';
+import { noteRepeatedCall, repeatedCallLedgers } from '../repeatedCall.js';
 import { formatToolArgIssues, validateToolArgs, } from '../toolArgsValidation.js';
 import { safeStringify } from '../validators.js';
 import { capToolResult } from '../toolResultCap.js';
@@ -219,6 +220,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';
 export function buildToolCallsHandler(deps) {
     const { registryByName, externalToolProvider, providerToolCache, permissionChecker } = deps;
     const toolArgValidation = deps.toolArgValidation ?? 'enforce';
@@ -229,6 +241,10 @@ export function buildToolCallsHandler(deps) {
     // that THROWS on use (never undefined) — so a tool can't silently no-op.
     const credentials = deps.credentialProvider ?? 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 = repeatedCallLedgers();
     /**
      * The tool-result ceiling, applied at the ONE place a result leaves dispatch.
      *
@@ -2032,6 +2048,11 @@ export function buildToolCallsHandler(deps) {
                     ...(toolStatus !== undefined && { status: toolStatus }),
                 });
                 let resultStr = typeof modelResult === 'string' ? modelResult : 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.
@@ -2068,6 +2089,35 @@ export 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 = noteRepeatedCall(repeatLedgers.read(runKey), tc.name, callArgs, deliveredResult);
+                    repeatLedgers.write(runKey, repeat.ledger);
+                    if (repeat.note !== undefined) {
+                        resultStr += repeat.note;
+                        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,