agentfootprint 9.25.0 → 9.26.0

package/dist/adapters/types.js

@@ -14,7 +14,7 @@
  * these interfaces — never on concrete adapters.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkerGoverns = exports.DEFAULT_CARRIES_IN_MESSAGES = void 0;
+exports.canStageCodeInputs = exports.STAGED_INPUTS_ENV = exports.checkerGoverns = exports.DEFAULT_CARRIES_IN_MESSAGES = void 0;
 /**
  * The floor every known wire supports. Used for any provider that does not
  * declare `carriesInMessages` — a third-party adapter is assumed to carry
@@ -39,4 +39,21 @@ function checkerGoverns(checker, capability) {
     return checker.governs?.includes(capability) === true;
 }
 exports.checkerGoverns = checkerGoverns;
+/**
+ * The environment variable an executing snippet reads its staged inputs from —
+ * a JSON object mapping each input's NAME to the path it landed at.
+ *
+ * Part of {@link CodeSession.stageInputs}'s contract rather than one adapter's
+ * convention, and named here so an adapter uses the constant instead of
+ * retyping the string. It is what makes model-written code portable across
+ * backends: the code reads one variable, and every adapter that stages inputs
+ * fills it the same way.
+ */
+exports.STAGED_INPUTS_ENV = 'AF_STAGED_INPUTS';
+/** Can this session accept staged inputs? The feature-detection law: read the
+ *  member, never assume it from the adapter's name. */
+function canStageCodeInputs(session) {
+    return typeof session.stageInputs === 'function';
+}
+exports.canStageCodeInputs = canStageCodeInputs;
 //# sourceMappingURL=types.js.map

package/dist/adapters/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AA+GH;;;;GAIG;AACU,QAAA,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAikBH;;;;;;GAMG;AACH,SAAgB,cAAc,CAC5B,OAAsC,EACtC,UAAgC;IAEhC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AACxD,CAAC;AAPD,wCAOC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AA+GH;;;;GAIG;AACU,QAAA,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAikBH;;;;;;GAMG;AACH,SAAgB,cAAc,CAC5B,OAAsC,EACtC,UAAgC;IAEhC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AACxD,CAAC;AAPD,wCAOC;AAqDD;;;;;;;;;GASG;AACU,QAAA,iBAAiB,GAAG,kBAAkB,CAAC;AAgGpD;uDACuD;AACvD,SAAgB,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC;AACnD,CAAC;AAJD,gDAIC"}

package/dist/artifacts/index.js

@@ -11,7 +11,7 @@
  * this folder for the one-job map and the import direction.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.placedToolResult = exports.placedResultKind = exports.isPlacedToolResult = exports.assertArtifactPlacement = exports.presentArtifact = exports.PRESENT_TOOL_NAME = exports.wantsNeedsStoreRefusal = exports.resolveToolWants = exports.assertToolWants = exports.unconfiguredArtifacts = exports.bindArtifacts = exports.collectStream = exports.canStreamArtifacts = exports.canPutArtifactStream = exports.canGetArtifactStream = exports.bytesAsStream = exports.assertStreamBytes = exports.gcsArtifacts = exports.s3Artifacts = exports.UnreadableArtifactStoreError = exports.sqliteArtifacts = exports.UnreadableArtifactFileError = exports.fileArtifacts = exports.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION = exports.inMemoryArtifacts = exports.mintArtifactRef = exports.isArtifactRef = exports.ARTIFACT_REF_PREFIX = exports.UnknownParentRefError = exports.InvalidArtifactError = exports.ArtifactIntegrityError = void 0;
+exports.placedToolResult = exports.placedResultKind = exports.isPlacedToolResult = exports.assertArtifactPlacement = exports.UnserializableRecordingError = exports.RECORDING_MEDIA_TYPE = exports.RECORDING_ARTIFACT_KIND = exports.recordingPutInput = exports.presentArtifact = exports.PRESENT_TOOL_NAME = exports.wantsNeedsStoreRefusal = exports.resolveToolWants = exports.assertToolWants = exports.unconfiguredArtifacts = exports.bindArtifacts = exports.collectStream = exports.canStreamArtifacts = exports.canPutArtifactStream = exports.canGetArtifactStream = exports.bytesAsStream = exports.assertStreamBytes = exports.gcsArtifacts = exports.s3Artifacts = exports.UnreadableArtifactStoreError = exports.sqliteArtifacts = exports.UnreadableArtifactFileError = exports.fileArtifacts = exports.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION = exports.inMemoryArtifacts = exports.mintArtifactRef = exports.isArtifactRef = exports.ARTIFACT_REF_PREFIX = exports.UnknownParentRefError = exports.InvalidArtifactError = exports.ArtifactIntegrityError = void 0;
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "ArtifactIntegrityError", { enumerable: true, get: function () { return types_js_1.ArtifactIntegrityError; } });
 Object.defineProperty(exports, "InvalidArtifactError", { enumerable: true, get: function () { return types_js_1.InvalidArtifactError; } });
@@ -50,6 +50,11 @@ Object.defineProperty(exports, "wantsNeedsStoreRefusal", { enumerable: true, get
 var present_js_1 = require("./present.js");
 Object.defineProperty(exports, "PRESENT_TOOL_NAME", { enumerable: true, get: function () { return present_js_1.PRESENT_TOOL_NAME; } });
 Object.defineProperty(exports, "presentArtifact", { enumerable: true, get: function () { return present_js_1.presentArtifact; } });
+var recordingArtifact_js_1 = require("./recordingArtifact.js");
+Object.defineProperty(exports, "recordingPutInput", { enumerable: true, get: function () { return recordingArtifact_js_1.recordingPutInput; } });
+Object.defineProperty(exports, "RECORDING_ARTIFACT_KIND", { enumerable: true, get: function () { return recordingArtifact_js_1.RECORDING_ARTIFACT_KIND; } });
+Object.defineProperty(exports, "RECORDING_MEDIA_TYPE", { enumerable: true, get: function () { return recordingArtifact_js_1.RECORDING_MEDIA_TYPE; } });
+Object.defineProperty(exports, "UnserializableRecordingError", { enumerable: true, get: function () { return recordingArtifact_js_1.UnserializableRecordingError; } });
 var placement_js_1 = require("./placement.js");
 Object.defineProperty(exports, "assertArtifactPlacement", { enumerable: true, get: function () { return placement_js_1.assertArtifactPlacement; } });
 Object.defineProperty(exports, "isPlacedToolResult", { enumerable: true, get: function () { return placement_js_1.isPlacedToolResult; } });

package/dist/artifacts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,uCAkBoB;AAjBlB,kHAAA,sBAAsB,OAAA;AACtB,gHAAA,oBAAoB,OAAA;AACpB,iHAAA,qBAAqB,OAAA;AAgBvB,yCAAkF;AAAzE,gHAAA,mBAAmB,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,4GAAA,eAAe,OAAA;AAE5D,+DAKgC;AAJ9B,yHAAA,iBAAiB,OAAA;AACjB,4IAAA,oCAAoC,OAAA;AAItC,uDAI4B;AAH1B,iHAAA,aAAa,OAAA;AACb,+HAAA,2BAA2B,OAAA;AAG7B,2DAK8B;AAJ5B,qHAAA,eAAe,OAAA;AACf,kIAAA,4BAA4B,OAAA;AAI9B,mDAAwE;AAA/D,6GAAA,WAAW,OAAA;AACpB,qDAA2E;AAAlE,+GAAA,YAAY,OAAA;AACrB,+CAUwB;AATtB,iHAAA,iBAAiB,OAAA;AACjB,6GAAA,aAAa,OAAA;AACb,oHAAA,oBAAoB,OAAA;AACpB,oHAAA,oBAAoB,OAAA;AACpB,kHAAA,kBAAkB,OAAA;AAClB,6GAAA,aAAa,OAAA;AAKf,iDAUyB;AATvB,8GAAA,aAAa,OAAA;AACb,sHAAA,qBAAqB,OAAA;AASvB,uCAOoB;AANlB,2GAAA,eAAe,OAAA;AACf,4GAAA,gBAAgB,OAAA;AAChB,kHAAA,sBAAsB,OAAA;AAKxB,2CAMsB;AALpB,+GAAA,iBAAiB,OAAA;AACjB,6GAAA,eAAe,OAAA;AAKjB,+CAOwB;AANtB,uHAAA,uBAAuB,OAAA;AACvB,kHAAA,kBAAkB,OAAA;AAClB,gHAAA,gBAAgB,OAAA;AAChB,gHAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,uCAkBoB;AAjBlB,kHAAA,sBAAsB,OAAA;AACtB,gHAAA,oBAAoB,OAAA;AACpB,iHAAA,qBAAqB,OAAA;AAgBvB,yCAAkF;AAAzE,gHAAA,mBAAmB,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,4GAAA,eAAe,OAAA;AAE5D,+DAKgC;AAJ9B,yHAAA,iBAAiB,OAAA;AACjB,4IAAA,oCAAoC,OAAA;AAItC,uDAI4B;AAH1B,iHAAA,aAAa,OAAA;AACb,+HAAA,2BAA2B,OAAA;AAG7B,2DAK8B;AAJ5B,qHAAA,eAAe,OAAA;AACf,kIAAA,4BAA4B,OAAA;AAI9B,mDAAwE;AAA/D,6GAAA,WAAW,OAAA;AACpB,qDAA2E;AAAlE,+GAAA,YAAY,OAAA;AACrB,+CAUwB;AATtB,iHAAA,iBAAiB,OAAA;AACjB,6GAAA,aAAa,OAAA;AACb,oHAAA,oBAAoB,OAAA;AACpB,oHAAA,oBAAoB,OAAA;AACpB,kHAAA,kBAAkB,OAAA;AAClB,6GAAA,aAAa,OAAA;AAKf,iDAUyB;AATvB,8GAAA,aAAa,OAAA;AACb,sHAAA,qBAAqB,OAAA;AASvB,uCAOoB;AANlB,2GAAA,eAAe,OAAA;AACf,4GAAA,gBAAgB,OAAA;AAChB,kHAAA,sBAAsB,OAAA;AAKxB,2CAMsB;AALpB,+GAAA,iBAAiB,OAAA;AACjB,6GAAA,eAAe,OAAA;AAKjB,+DAMgC;AAL9B,yHAAA,iBAAiB,OAAA;AACjB,+HAAA,uBAAuB,OAAA;AACvB,4HAAA,oBAAoB,OAAA;AACpB,oIAAA,4BAA4B,OAAA;AAG9B,+CAOwB;AANtB,uHAAA,uBAAuB,OAAA;AACvB,kHAAA,kBAAkB,OAAA;AAClB,gHAAA,gBAAgB,OAAA;AAChB,gHAAA,gBAAgB,OAAA"}

package/dist/artifacts/recordingArtifact.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * artifacts/recordingArtifact — a finished run, checked into the store like any
+ * other payload.
+ *
+ * `recordRun` has produced `{ snapshot, events, structure }` since 8.x and the
+ * lens family has consumed exactly that shape since. What nobody shipped was
+ * the boring half in between: WHERE a completed run's recording goes so a
+ * screen can ask for it later. Every deployment that wanted the Lens over the
+ * wire wrote the same twenty lines — record the run, serialize it, put it
+ * somewhere with a key, hand the key to the frontend — and each one wrote a
+ * slightly different, slightly wrong version of retention and scoping.
+ *
+ * All four of those problems already have an answer in this package: the
+ * artifact store IS a keyed payload store with scope isolation, retention and
+ * a read-only wire. So a recording is simply an artifact of kind
+ * `'recording/run'`, and the wire ops that already redeem claim tickets serve
+ * it with **zero new operations** — `{ op: 'artifact-get', ref }` returns the
+ * recording, and the frontend does what it always did with the bytes.
+ *
+ * ── Why the payload is TEXT and not an object ───────────────────────────────
+ * The recording is minted as its JSON text — the same bytes
+ * `JSON.stringify(recorder.toRecording())` produces, which is precisely what
+ * `observeRecording(JSON.parse(text))` consumes on the viewer side. Two
+ * reasons, and both are about not lying:
+ *
+ *   • `recordRun` states that `snapshot` and `structure` are the runner's OWN
+ *     objects, held by reference. An in-process store handed those would keep
+ *     a live view into a finished run's state — the artifact would silently
+ *     change if anything touched it. Serializing detaches it, once, here.
+ *   • A recording that cannot be serialized cannot be delivered over any wire
+ *     either, so failing at the mint is failing at the honest moment rather
+ *     than at whatever reads it next.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordingPutInput = exports.UnserializableRecordingError = exports.RECORDING_MEDIA_TYPE = exports.RECORDING_ARTIFACT_KIND = void 0;
+/** The consumer vocabulary a run recording is stored under. One kind, exact
+ *  match — the same rule every `wants` declaration is judged by. */
+exports.RECORDING_ARTIFACT_KIND = 'recording/run';
+/** The media type a recording is minted with. */
+exports.RECORDING_MEDIA_TYPE = 'application/json';
+/**
+ * Raised when a recording could not be turned into bytes.
+ *
+ * Its own class because the CALLER's answer differs from every other mint
+ * failure: a full store is retryable and a cyclic snapshot is not.
+ */
+class UnserializableRecordingError extends Error {
+    code = 'ERR_UNSERIALIZABLE_RECORDING';
+    constructor(detail) {
+        super(`[artifacts] the run recording could not be serialized (${detail}), so it was not ` +
+            `stored. A recording that JSON cannot carry could not be delivered over any wire ` +
+            `either — this fails at the mint rather than at whatever tried to read it. The run ` +
+            `itself is unaffected: its answer was already composed before this was attempted.`);
+        this.name = 'UnserializableRecordingError';
+    }
+}
+exports.UnserializableRecordingError = UnserializableRecordingError;
+/**
+ * Turn one finished recording into the `put` input that stores it.
+ *
+ * Pure: no store, no events, no agent. The caller owns WHEN this happens (after
+ * the answer is composed) and what to do when it fails.
+ *
+ * @throws UnserializableRecordingError when the recording cannot be
+ *   JSON-serialized — a cyclic object in a snapshot, most likely.
+ */
+function recordingPutInput(recording, facts = {}) {
+    let text;
+    try {
+        text = JSON.stringify(recording) ?? '';
+    }
+    catch (err) {
+        throw new UnserializableRecordingError(err instanceof Error ? err.message : String(err));
+    }
+    if (text === '') {
+        throw new UnserializableRecordingError('it serializes to nothing');
+    }
+    return {
+        kind: exports.RECORDING_ARTIFACT_KIND,
+        mediaType: exports.RECORDING_MEDIA_TYPE,
+        data: text,
+        label: facts.label ?? (facts.runId !== undefined ? `run ${facts.runId}` : 'run recording'),
+        ...(facts.runId !== undefined && { origin: { runId: facts.runId } }),
+    };
+}
+exports.recordingPutInput = recordingPutInput;
+//# sourceMappingURL=recordingArtifact.js.map

package/dist/artifacts/recordingArtifact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordingArtifact.js","sourceRoot":"","sources":["../../src/artifacts/recordingArtifact.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;AAIH;oEACoE;AACvD,QAAA,uBAAuB,GAAG,eAAe,CAAC;AAEvD,iDAAiD;AACpC,QAAA,oBAAoB,GAAG,kBAAkB,CAAC;AAoBvD;;;;;GAKG;AACH,MAAa,4BAA6B,SAAQ,KAAK;IAC5C,IAAI,GAAG,8BAAuC,CAAC;IAExD,YAAY,MAAc;QACxB,KAAK,CACH,0DAA0D,MAAM,mBAAmB;YACjF,kFAAkF;YAClF,oFAAoF;YACpF,kFAAkF,CACrF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAZD,oEAYC;AAED;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAC/B,SAAkB,EAClB,QAA4B,EAAE;IAE9B,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,4BAA4B,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,4BAA4B,CAAC,0BAA0B,CAAC,CAAC;IACrE,CAAC;IACD,OAAO;QACL,IAAI,EAAE,+BAAuB;QAC7B,SAAS,EAAE,4BAAoB;QAC/B,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC;QAC1F,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;KACrE,CAAC;AACJ,CAAC;AApBD,8CAoBC"}

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 && {