agentfootprint 9.24.0 → 9.26.0

package/dist/artifacts/streaming.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * artifacts/streaming — the OPTIONAL leg of the port, and how to ask for it.
+ *
+ * A claim check exists so a 6 MB result never rides the conversation. It does
+ * not follow that the 6 MB should ride the PROCESS: a store that can accept
+ * bytes as they arrive, and hand them back the same way, lets a report be
+ * written to a bucket without ever existing whole in memory. That is what
+ * `putStream` / `getStream` are for.
+ *
+ * ── Why OPTIONAL members and not two more verbs ─────────────────────────────
+ * Not every backend can honor the promise, and the ones that cannot must say
+ * so by ABSENCE rather than by faking it. A `Map`-backed store "streaming"
+ * bytes it already holds whole would be theatre: the memory was already spent,
+ * and a consumer that chose it to bound memory would have been told a
+ * falsehood in the shape of a capability. So:
+ *
+ *   • `fileArtifacts`  — YES. The bytes go to a sibling file as they arrive.
+ *   • object stores    — YES, through the SDK's own streaming upload/download.
+ *   • `sqliteArtifacts`— NO. `node:sqlite` reads and writes a BLOB whole;
+ *                        there is no incremental blob I/O to build on, so a
+ *                        stream here would buffer everything and call it a
+ *                        stream.
+ *   • `inMemoryArtifacts` — NO, by design. It holds payloads whole, under a
+ *                        byte budget; streaming into it would defeat both.
+ *
+ * ── Web streams, one shape ──────────────────────────────────────────────────
+ * `ReadableStream<Uint8Array>` — the shape that exists in every supported Node
+ * AND in a browser, so the port stays the same object everywhere the rest of
+ * this folder already works (the Buffer-free base64 law in `payload.ts`, for
+ * the same reason). Node-native adapters bridge at their own edge with
+ * `Readable.toWeb` / `Readable.fromWeb`; that bridge is an ADAPTER detail and
+ * never leaks into the port.
+ *
+ * ── What `ctx.artifacts` does NOT get, and why (a decision, not an omission) ─
+ * The tool-facing capability keeps FIVE verbs this phase. A tool receives its
+ * artifacts pre-scoped and answers a model; the model cannot hold a stream,
+ * and a tool that genuinely moves gigabytes wants the store itself, with its
+ * own lifecycle and its own error handling. So a tool that needs streaming
+ * holds the store (it already constructed it) and calls it directly — while
+ * `ctx.artifacts` stays the small, safe, scope-bound surface a model-driven
+ * tool can be trusted with.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertStreamBytes = exports.bytesAsStream = exports.collectStream = exports.canStreamArtifacts = exports.canGetArtifactStream = exports.canPutArtifactStream = void 0;
+const types_js_1 = require("./types.js");
+/**
+ * Can this store take a streamed put? Narrowing type guard — the answer is
+ * the type, so a consumer branches once and the compiler carries it.
+ *
+ * @example
+ *   if (canPutArtifactStream(store)) await store.putStream(scope, input, body);
+ *   else await store.put(scope, { ...input, data: await collect(body) });
+ */
+function canPutArtifactStream(store) {
+    return typeof store.putStream === 'function';
+}
+exports.canPutArtifactStream = canPutArtifactStream;
+/** Can this store hand back a stream? Narrowing type guard. */
+function canGetArtifactStream(store) {
+    return typeof store.getStream === 'function';
+}
+exports.canGetArtifactStream = canGetArtifactStream;
+/** Both halves at once — for a consumer that needs the round trip. */
+function canStreamArtifacts(store) {
+    return canPutArtifactStream(store) && canGetArtifactStream(store);
+}
+exports.canStreamArtifacts = canStreamArtifacts;
+/**
+ * Read a stream to its bytes, refusing at a ceiling instead of growing until
+ * the process dies.
+ *
+ * Adapters that must hold the payload to store it (an object `put` of a
+ * declared length) use this, and so does any consumer bridging a stream into
+ * `put`. The ceiling is the caller's declared `bytes`: a producer that says
+ * 10 MB and sends 11 is refused rather than trusted, because the meta it
+ * would otherwise mint describes a payload that does not exist.
+ */
+async function collectStream(body, ceiling) {
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value === undefined)
+                continue;
+            total += value.byteLength;
+            if (total > ceiling) {
+                await reader.cancel();
+                return { bytes: new Uint8Array(0), overflowed: true };
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { bytes: out, overflowed: false };
+}
+exports.collectStream = collectStream;
+/** One chunk of bytes as a web stream — how a store that HOLDS the payload
+ *  answers `getStream` honestly (it never claimed to be lazy; it is handing
+ *  over what it has, in the port's shape). */
+function bytesAsStream(bytes) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+exports.bytesAsStream = bytesAsStream;
+/** The stated `bytes` on a streamed put, checked before anything is stored. */
+function assertStreamBytes(adapter, bytes) {
+    if (typeof bytes !== 'number' || !Number.isFinite(bytes) || bytes < 0) {
+        throw new types_js_1.InvalidArtifactError(`${adapter}: putStream needs a stated \`bytes\` (got ${JSON.stringify(bytes)}). A stream ` +
+            `has no length until it ends, and both the retention plan and the upload need the size ` +
+            `BEFORE the first chunk. State the exact byte length, or use put() with the payload.`);
+    }
+    return Math.floor(bytes);
+}
+exports.assertStreamBytes = assertStreamBytes;
+//# sourceMappingURL=streaming.js.map

package/dist/artifacts/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../src/artifacts/streaming.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;;;AAEH,yCAAsE;AAYtE;;;;;;;GAOG;AACH,SAAgB,oBAAoB,CAAC,KAAoB;IACvD,OAAO,OAAO,KAAK,CAAC,SAAS,KAAK,UAAU,CAAC;AAC/C,CAAC;AAFD,oDAEC;AAED,+DAA+D;AAC/D,SAAgB,oBAAoB,CAAC,KAAoB;IACvD,OAAO,OAAO,KAAK,CAAC,SAAS,KAAK,UAAU,CAAC;AAC/C,CAAC;AAFD,oDAEC;AAED,sEAAsE;AACtE,SAAgB,kBAAkB,CAAC,KAAoB;IACrD,OAAO,oBAAoB,CAAC,KAAK,CAAC,IAAI,oBAAoB,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AAFD,gDAEC;AAED;;;;;;;;;GASG;AACI,KAAK,UAAU,aAAa,CACjC,IAAgC,EAChC,OAAe;IAEf,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YAClC,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC;YAC1B,IAAI,KAAK,GAAG,OAAO,EAAE,CAAC;gBACpB,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;gBACtB,OAAO,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;YACxD,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;IAC7B,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAC3C,CAAC;AA7BD,sCA6BC;AAED;;8CAE8C;AAC9C,SAAgB,aAAa,CAAC,KAAiB;IAC7C,OAAO,IAAI,cAAc,CAAa;QACpC,KAAK,CAAC,UAAU;YACd,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC1B,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAPD,sCAOC;AAED,+EAA+E;AAC/E,SAAgB,iBAAiB,CAAC,OAAe,EAAE,KAAc;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,+BAAoB,CAC5B,GAAG,OAAO,6CAA6C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,cAAc;YACxF,wFAAwF;YACxF,qFAAqF,CACxF,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AATD,8CASC"}

package/dist/artifacts/types.js

@@ -25,11 +25,19 @@
  * `put · head · get · delete · list`. The moment this port grows `query()` or
  * `transform()` we are building a database — compute belongs to the code leg,
  * and that refusal is written here so a future round can be refused by
- * citation. No streaming members either: an in-memory adapter must never fake
- * a stream (streaming is a later, feature-detected addition — not Phase 1).
+ * citation.
  *
  * `head` earns its place because it IS the render-by-ref decision: a consumer
  * picks what to do from `kind` and `bytes` without paying for the payload.
+ *
+ * ── …and two OPTIONAL ones (9.25.0) ─────────────────────────────────────────
+ * `putStream?` / `getStream?` are feature-detected members, not a sixth and
+ * seventh verb: a store that cannot move a payload without holding it whole
+ * LEAVES THEM ABSENT, and a consumer that calls one it did not detect gets a
+ * type error rather than a runtime surprise. An adapter must never fake a
+ * stream over bytes it already holds — a fake stream is an accepted-and-
+ * silently-wrong promise about memory. See {@link ArtifactStreamPutInput} for
+ * the two things streaming costs you (a stated `bytes`, and no digest).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InvalidArtifactError = exports.ArtifactIntegrityError = exports.UnknownParentRefError = void 0;

package/dist/artifacts/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/artifacts/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;AA2KH,wEAAwE;AAExE;;;;;GAKG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IACrC,IAAI,GAAG,wBAAiC,CAAC;IAClD,0CAA0C;IACjC,UAAU,CAAyB;IAE5C,YAAY,UAAkC;QAC5C,KAAK,CACH,uCAAuC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAClF,oFAAoF;YACpF,qFAAqF;YACrF,wFAAwF,CAC3F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAfD,sDAeC;AAED;;;;;GAKG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IACtC,IAAI,GAAG,wBAAiC,CAAC;IACzC,GAAG,CAAc;IAC1B,gCAAgC;IACvB,QAAQ,CAAS;IAC1B,uDAAuD;IAC9C,MAAM,CAAS;IAExB,YAAY,GAAgB,EAAE,QAAgB,EAAE,MAAc;QAC5D,KAAK,CACH,oBAAoB,GAAG,8DAA8D;YACnF,oBAAoB,QAAQ,cAAc,MAAM,mCAAmC;YACnF,sFAAsF;YACtF,+EAA+E;YAC/E,2BAA2B,CAC9B,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AArBD,wDAqBC;AAED;;;;GAIG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,sBAA+B,CAAC;IAEhD,YAAY,MAAc;QACxB,KAAK,CAAC,4BAA4B,MAAM,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAPD,oDAOC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/artifacts/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;;;AA6OH,wEAAwE;AAExE;;;;;GAKG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IACrC,IAAI,GAAG,wBAAiC,CAAC;IAClD,0CAA0C;IACjC,UAAU,CAAyB;IAE5C,YAAY,UAAkC;QAC5C,KAAK,CACH,uCAAuC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAClF,oFAAoF;YACpF,qFAAqF;YACrF,wFAAwF,CAC3F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAfD,sDAeC;AAED;;;;;GAKG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IACtC,IAAI,GAAG,wBAAiC,CAAC;IACzC,GAAG,CAAc;IAC1B,gCAAgC;IACvB,QAAQ,CAAS;IAC1B,uDAAuD;IAC9C,MAAM,CAAS;IAExB,YAAY,GAAgB,EAAE,QAAgB,EAAE,MAAc;QAC5D,KAAK,CACH,oBAAoB,GAAG,8DAA8D;YACnF,oBAAoB,QAAQ,cAAc,MAAM,mCAAmC;YACnF,sFAAsF;YACtF,+EAA+E;YAC/E,2BAA2B,CAC9B,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AArBD,wDAqBC;AAED;;;;GAIG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,sBAA+B,CAAC;IAEhD,YAAY,MAAc;QACxB,KAAK,CAAC,4BAA4B,MAAM,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAPD,oDAOC"}

package/dist/core/Agent.js

@@ -26,6 +26,8 @@ const skillBrains_js_1 = require("./agent/skillBrains.js");
 const conventions_js_1 = require("../conventions.js");
 const pause_js_1 = require("./pause.js");
 const placement_js_1 = require("../artifacts/placement.js");
+const recordingArtifact_js_1 = require("../artifacts/recordingArtifact.js");
+const recordRun_js_1 = require("../recorders/observability/recordRun.js");
 const CredentialConsentRequiredError_js_1 = require("../identity/CredentialConsentRequiredError.js");
 const ContextRecorder_js_1 = require("../recorders/core/ContextRecorder.js");
 const ContextEvaluatedRecorder_js_1 = require("../recorders/core/ContextEvaluatedRecorder.js");
@@ -237,6 +239,13 @@ class Agent extends RunnerBase_js_1.RunnerBase {
     /** The placement threshold (9.22.0) — the operator's ref-ing dial from the
      *  object form of AgentOptions.artifacts. Only ever set beside a store. */
     artifactPlacement;
+    /** Recordings-as-artifacts (9.26.0) — the operator's dial from the object
+     *  form of AgentOptions.artifacts. Only ever set beside a store; absent
+     *  means no recorder is ever attached and no run is ever recorded. */
+    artifactRecordings;
+    /** The repeated-call nudge (9.26.0) — `false` only when the operator turned
+     *  it off. See AgentOptions.repeatedCallNudge. */
+    repeatedCallNudge;
     /** What a run does when a declared credential needs 3LO consent (8.6.0).
      *  Default `'pause'`. See AgentOptions.onAuthorizationRequired. */
     onAuthorizationRequired;
@@ -514,6 +523,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         this.observerDeliveryOptions = opts.observerDeliveryOptions;
         if (opts.credentials)
             this.credentialProvider = opts.credentials;
+        // Kept only when it says something: `undefined` and `true` are the same
+        // default, and storing `true` would make the thread-when-off rule below
+        // read as a coincidence.
+        if (opts.repeatedCallNudge === false)
+            this.repeatedCallNudge = false;
         // The claim-check seam (9.21.0). One store per agent, attached at
         // construction — idempotent by shape: there is no second door to attach a
         // competing one through, so "one per agent" is a fact of the type rather
@@ -537,6 +551,16 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 if (opts.artifacts.placement !== undefined) {
                     this.artifactPlacement = opts.artifacts.placement;
                 }
+                // The recordings dial (9.26.0). `true` and `{ … }` normalize to ONE
+                // shape here, so every downstream reader asks a single question
+                // ("is there a recordings option?") rather than re-deriving the union.
+                if (opts.artifacts.recordings === true) {
+                    this.artifactRecordings = {};
+                }
+                else if (typeof opts.artifacts.recordings === 'object' &&
+                    opts.artifacts.recordings !== null) {
+                    this.artifactRecordings = opts.artifacts.recordings;
+                }
             }
             else {
                 this.artifactStore = opts.artifacts;
@@ -629,6 +653,134 @@ class Agent extends RunnerBase_js_1.RunnerBase {
     getArtifactStore() {
         return this.artifactStore;
     }
+    /**
+     * Start recording this run — or do nothing at all (9.26.0).
+     *
+     * Zero-cost when unused is not a claim here, it is the control flow: with
+     * `recordings` unset this returns `undefined` before touching the agent, so
+     * no listener is subscribed, no boundary recorder is attached, and the run
+     * is byte-identical to every earlier release.
+     *
+     * It is deliberately the SAME `recordRun` a consumer would call by hand.
+     * Nothing about this feature is a second recording implementation — the
+     * three connections that a hand-rolled version gets wrong (attach,
+     * subscribe, getCommitCount) are wired in exactly one place in this package,
+     * and this is a caller of it.
+     */
+    startRunRecording() {
+        if (this.artifactRecordings === undefined || this.artifactStore === undefined)
+            return undefined;
+        return (0, recordRun_js_1.recordRun)(this);
+    }
+    /**
+     * File the finished recording into the artifact store.
+     *
+     * ── When ────────────────────────────────────────────────────────────────
+     * After the answer is composed, and only for a run that COMPLETED. A pause
+     * is not a finished run (the turn continues, and the resume mints its own);
+     * a throw never reaches here at all.
+     *
+     * ── Why it is awaited ───────────────────────────────────────────────────
+     * The answer is final before this begins and this cannot change it — but
+     * `run()` does return after the write rather than before, and that is a
+     * choice rather than an oversight. A fire-and-forget write is a recording
+     * lost whenever the process exits with the reply, which is precisely the
+     * serverless deployment that wants recordings most. The cost is one store
+     * write per turn, stated on the option.
+     *
+     * ── Why it can never fail the run ───────────────────────────────────────
+     * A full store, an unserializable snapshot, a bucket that 500s — none of
+     * them are facts about the ANSWER, which is already correct and already
+     * paid for. Turning "your recording was not filed" into "your request
+     * failed" would be the library deciding that its observability matters more
+     * than the user's turn. So every failure degrades to today's path: the
+     * answer is returned unchanged and the reason lands on the record as
+     * `agentfootprint.artifacts.refused`, where a sink can count it.
+     *
+     * The recording is FROZEN before the mint, so it can never contain the
+     * `artifacts.minted` event describing itself.
+     */
+    async fileRunRecording(recorder, outcome) {
+        const store = this.artifactStore;
+        if (recorder === undefined || store === undefined || this.artifactRecordings === undefined) {
+            return;
+        }
+        if ((0, pause_js_1.isPaused)(outcome))
+            return;
+        const runId = this.currentRunContext?.runId;
+        let input;
+        try {
+            input = (0, recordingArtifact_js_1.recordingPutInput)(recorder.toRecording(), {
+                ...(runId !== undefined && { runId }),
+                ...(this.artifactRecordings.label !== undefined && {
+                    label: this.artifactRecordings.label,
+                }),
+            });
+        }
+        catch (err) {
+            this.reportRecordingRefused(err, 'invalid-input');
+            return;
+        }
+        try {
+            const result = await store.put(this.runArtifactScope(), input);
+            // Sweeps ride the put result, so retention that evicted an older
+            // recording to make room says so on the record — the same law a tool's
+            // own mint follows.
+            for (const swept of result.swept) {
+                this.emit('agentfootprint.artifacts.expired', {
+                    ref: swept.ref,
+                    reason: swept.reason,
+                    kind: swept.kind,
+                    bytes: swept.bytes,
+                });
+            }
+            this.emit('agentfootprint.artifacts.minted', {
+                ref: result.meta.ref,
+                kind: result.meta.kind,
+                mediaType: result.meta.mediaType,
+                bytes: result.meta.bytes,
+                ...(result.meta.label !== undefined && { label: result.meta.label }),
+                ...(result.meta.expiresAt !== undefined && { expiresAt: result.meta.expiresAt }),
+                ...(result.meta.origin !== undefined && { origin: result.meta.origin }),
+            });
+        }
+        catch (err) {
+            this.reportRecordingRefused(err, 'invalid-input');
+        }
+    }
+    /** One refusal fact for a recording that could not be filed. The message is
+     *  the store's own, which never carries a payload — only what went wrong. */
+    reportRecordingRefused(err, reason) {
+        this.emit('agentfootprint.artifacts.refused', {
+            op: 'put',
+            reason,
+            detail: err instanceof Error ? err.message : String(err),
+        });
+    }
+    /**
+     * The run's artifact scope, read from the finished run's own state.
+     *
+     * The SAME tuple `ctx.artifacts` bound during the run (`scope.runIdentity`,
+     * composed by seed from the caller's identity or derived from the session).
+     * Read rather than recomposed: a second derivation here could disagree with
+     * the one the run's tools used, and a recording filed in a different scope
+     * from the artifacts it describes is a recording nobody can find.
+     */
+    runArtifactScope() {
+        const identity = this.getLastSnapshot()?.sharedState
+            ?.runIdentity;
+        if (identity === undefined) {
+            // No state to read means no run happened, which this path cannot reach —
+            // but a scope is required and inventing a tenant would be worse than a
+            // conversation id that names the run itself.
+            return { conversationId: this.currentRunContext?.runId ?? 'unknown' };
+        }
+        return {
+            conversationId: identity.conversationId,
+            ...(identity.tenant !== undefined && { tenant: identity.tenant }),
+            ...(identity.principal !== undefined && { principal: identity.principal }),
+        };
+    }
     /**
      * The footprintjs `RuntimeSnapshot` from the most recent `run()` /
      * `resume()`. Feeds Lens's Trace tab (ExplainableShell `runtimeSnapshot`
@@ -854,6 +1006,12 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // so a continued turn stays in the namespace it started in.
         this.lastRunIdentity =
             runInput.identity ?? options?.identity ?? (continued ? continued.identity : undefined);
+        // Recordings-as-artifacts (9.26.0). BEFORE `createExecutor`, because
+        // `attach()` collects recorders for the executor that has not been built
+        // yet — a recording started one line later would be missing its
+        // boundaries, which is the failure mode `recordRun` exists to prevent.
+        // Returns `undefined` (and touches nothing) unless the dial is on.
+        const recording = this.startRunRecording();
         // (helper used in the catch block below — module-private function
         // declared at file end via hoisting)
         const executor = this.createExecutor(options);
@@ -895,6 +1053,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 this.lastRunAnswer = finalized;
             this.recordPendingQuestion(finalized);
             await this.endRunToolSessions(finalized);
+            // The answer is FINISHED before this line and cannot be changed by it.
+            // See `fileRunRecording` for why the write is awaited rather than left
+            // in flight, and why it can never fail the run.
+            await this.fileRunRecording(recording, finalized);
             return finalized;
         }
         catch (cause) {
@@ -955,6 +1117,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             throw cause;
         }
         finally {
+            // Always released: a recording left subscribed would keep listening
+            // through the next run and grow a tail nobody reads.
+            recording?.stop();
             stopTracking();
             this.inFlightRunId = undefined;
             // `seed` consumes the restored conversation on its way past. A run that
@@ -1203,6 +1368,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // `checkpoint.sharedState` (and nested subflow states) automatically
         // on a fresh executor's `resume()`. No need to retain a paused
         // executor between run/resume.
+        // Recorded on the same terms a fresh run is (9.26.0) — and the recording
+        // covers the RESUMED run, which is what the recorder saw. A turn that
+        // paused and resumed is two runs, and each mints its own recording when
+        // (and only when) it completes.
+        const recording = this.startRunRecording();
         const executor = this.createExecutor(options);
         this.inFlightRunId = this.currentRunContext.runId;
         this.lastRunAnswer = undefined;
@@ -1217,6 +1387,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // AGAIN has asked a new one, and that one is outstanding from here.
             this.recordPendingQuestion(finalized);
             await this.endRunToolSessions(finalized);
+            await this.fileRunRecording(recording, finalized);
             return finalized;
         }
         catch (cause) {
@@ -1224,6 +1395,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             throw cause;
         }
         finally {
+            recording?.stop();
             this.inFlightRunId = undefined;
         }
     }
@@ -2516,6 +2688,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             ...(this.maxToolResultChars !== undefined && {
                 maxToolResultChars: this.maxToolResultChars,
             }),
+            // The repeated-call nudge (9.26.0). Threaded ONLY when switched off —
+            // the VALUE-conditional pattern, so an agent on the default hands the
+            // handler exactly the deps object it always did.
+            ...(this.repeatedCallNudge === false && { repeatedCallNudge: false }),
             // Skill-graph read_skill gate: bound the model's read_skill jumps to the
             // reachable set from the current cursor. Undefined → gate off (back-compat).
             ...(this.skillGraphReachable && {