agentfootprint 9.41.0 → 9.44.0

package/dist/lib/injection-engine/skillsFromDirRoutes.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * skillsFromDirRoutes — the `routes:` half of the on-disk runbook grammar.
+ *
+ * ## What a file may say about routing, and why it is this little
+ *
+ * `skillsFromDir` reads prose, `tools:` and `steps:` — everything about ONE
+ * skill — and stopped exactly where the value was supposed to start: the
+ * routing. A directory of runbooks still had to be hand-wired into a graph in
+ * code, which is the work the graph exists to remove.
+ *
+ * This module adds the missing key under the SAME security law the tools list
+ * follows: **the file PICKS, it never DEFINES.**
+ *
+ *   ---
+ *   name: billing
+ *   tools: lookup_order, issue_refund
+ *   routes:
+ *     - escalation: on issue_refund status=denied
+ *     - receipts: on issue_refund
+ *     - audit
+ *   ---
+ *
+ * A route names a SKILL ID and, optionally, a guard. Both halves are picks:
+ *
+ *   • the id is resolved against the skills THIS DIRECTORY declares — an id
+ *     nothing here declares is refused at load, by name, listing what is
+ *     available. Never a half-graph: one bad id fails the whole load, because
+ *     a graph missing one edge routes silently wrong, which is worse than a
+ *     graph that refuses to exist;
+ *   • the guard is one of the two DATA conditions a route already has
+ *     (`onToolReturn`, `onToolStatus`), and the tool it names must be one of
+ *     this file's own `tools:` — the same law `steps:` follows, for the same
+ *     reason (an edge out of this skill fires on this skill's work).
+ *
+ * Nothing is evaluated, imported or resolved as a path. The strings can only
+ * MATCH — against ids the loader already read off disk and against a closed
+ * status vocabulary.
+ *
+ * ## What a file CANNOT express, said plainly
+ *
+ * A `when:` predicate is CODE. There is no honest way for a markdown file to
+ * carry it: reading one would mean evaluating a string, which is the one thing
+ * this loader exists never to do. So the grammar has no `when` and no
+ * expression language of any kind — a conditional a file cannot express is a
+ * conditional that stays in code:
+ *
+ *   skillGraph({ skills, steps: [{ from: 'billing', to: 'escalation',
+ *                                  when: r => JSON.parse(r.result).tier > 2 }] });
+ *
+ * Anything that is not one of the three forms is refused with the whole grammar
+ * quoted, rather than half-understood by a parser inventing a mini-language.
+ *
+ * Zone: HOST (it belongs to the file loader). Pure over strings all the same —
+ * it reads no filesystem; `skillsFromDir.ts` hands it the parsed lines.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toGraphSteps = exports.readDeclaredRoutes = void 0;
+const toolOutcome_js_1 = require("./toolOutcome.js");
+/** The grammar, quoted back by every refusal — one string, so the three forms
+ *  can never be described two different ways. */
+const ROUTE_GRAMMAR = '  - <skill>                                  (no guard — a model edge: the graph draws it and ' +
+    'read_skill may take it)\n' +
+    "  - <skill>: on <tool_name>                  (this skill's own tool returned)\n" +
+    '  - <skill>: status=denied                   (a tool of this skill declared that outcome)\n' +
+    '  - <skill>: on <tool_name> status=denied,failure\n' +
+    `Statuses: ${toolOutcome_js_1.TOOL_RESULT_STATUSES.join(', ')}.`;
+/** `on <tool>`, `status=a,b`, or both in that order. Anything else is refused. */
+const GUARD_RE = /^(?:on\s+([A-Za-z0-9_-]+))?\s*(?:status=([A-Za-z,\s]+))?$/;
+/**
+ * Read one file's `routes:` items into declared routes, refusing every shape
+ * the grammar does not carry. Pure; every message names the file and the line,
+ * because "malformed routes" over a directory of forty runbooks has told the
+ * author nothing.
+ *
+ * @param items      the `routes:` block-list items, in file order.
+ * @param file       the path, quoted by every refusal.
+ * @param toolNames  this file's own `tools:` — a guard may only name one of
+ *                   them (undefined when the file declared no tools at all).
+ */
+function readDeclaredRoutes(items, file, toolNames) {
+    if (items.length === 0) {
+        throw new Error(`skillsFromDir: '${file}' declares 'routes' with no items. Say what you mean and omit ` +
+            `the key — a skill that routes nowhere is byte-identical to one that never heard of ` +
+            `routes. Otherwise:\nroutes:\n${ROUTE_GRAMMAR}`);
+    }
+    const declared = new Set(toolNames ?? []);
+    const seen = new Set();
+    return items.map((item) => {
+        if (item.key.length === 0) {
+            throw new Error(`skillsFromDir: '${file}' line ${item.line}: this route names no skill. Every route ` +
+                `is:\n${ROUTE_GRAMMAR}`);
+        }
+        if (seen.has(item.key)) {
+            throw new Error(`skillsFromDir: '${file}' line ${item.line}: routes to '${item.key}' twice. Two edges ` +
+                `between the same pair means the first one that fires wins and the second is dead ` +
+                `wiring — keep the guard you meant, and drop the other.`);
+        }
+        seen.add(item.key);
+        const guard = item.value?.trim() ?? '';
+        if (guard.length === 0)
+            return { to: item.key, line: item.line };
+        const parsed = GUARD_RE.exec(guard);
+        const toolName = parsed?.[1];
+        const statusList = parsed?.[2];
+        if (parsed === null || (toolName === undefined && statusList === undefined)) {
+            throw new Error(`skillsFromDir: '${file}' line ${item.line}: the route to '${item.key}' declares the ` +
+                `guard '${guard}', which this grammar cannot express. A SKILL.md PICKS, it never ` +
+                `DEFINES — a \`when\` predicate is code, and nothing in a SKILL.md is ever ` +
+                `evaluated, so the only guards a file can carry are the two DATA conditions a route ` +
+                `already has:\n${ROUTE_GRAMMAR}\nA conditional a file cannot express stays in code: ` +
+                `skillGraph({ skills, steps: [{ from: '<this skill>', to: '${item.key}', when: r => ` +
+                `… }] }).`);
+        }
+        if (toolName !== undefined && !declared.has(toolName)) {
+            throw new Error(`skillsFromDir: '${file}' line ${item.line}: the route to '${item.key}' fires on ` +
+                `'${toolName}', which is not in this file's 'tools'${toolNames === undefined ? ' (this file declares none)' : ` (${toolNames.join(', ')})`}. An edge out of this skill fires on THIS skill's work, so it may only name a tool ` +
+                `the skill carries — add it to 'tools:', fix the name, or declare this edge in code ` +
+                `where the whole agent's tools are in hand.`);
+        }
+        const statuses = (statusList ?? '')
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+        for (const status of statuses) {
+            if (!toolOutcome_js_1.TOOL_RESULT_STATUSES.includes(status)) {
+                throw new Error(`skillsFromDir: '${file}' line ${item.line}: the route to '${item.key}' names the ` +
+                    `status '${status}', which is not one this library has. The vocabulary is closed ` +
+                    `so both sides spell an outcome identically: ${toolOutcome_js_1.TOOL_RESULT_STATUSES.join(', ')}.`);
+            }
+        }
+        return {
+            to: item.key,
+            ...(toolName !== undefined && { onToolReturn: toolName }),
+            ...(statuses.length > 0 && { onToolStatus: statuses }),
+            line: item.line,
+        };
+    });
+}
+exports.readDeclaredRoutes = readDeclaredRoutes;
+/**
+ * Resolve one file's declared routes into graph steps, refusing an id no
+ * SKILL.md in the directory declares.
+ *
+ * The refusal lists what IS available and fails the whole load. A route to a
+ * name nothing declares is the one mistake that cannot be reported later: the
+ * loader would return a skill set the graph then wires with a missing edge, and
+ * a graph that silently does not route is exactly the failure the check-up
+ * exists to prevent. Half a graph is not a smaller version of the graph.
+ *
+ * @param from   the id of the skill whose file declared these routes.
+ * @param file   that skill's path, quoted by the refusal.
+ * @param known  every skill id the directory declared.
+ */
+function toGraphSteps(from, routes, file, known) {
+    return routes.map((route) => {
+        if (!known.has(route.to)) {
+            const available = [...known].sort().join(', ');
+            throw new Error(`skillsFromDir: '${file}' line ${route.line} routes to '${route.to}', which no ` +
+                `SKILL.md in this directory declares. A route NAMES a skill; a file can never ` +
+                `define one, so an unresolved id would leave you a graph with a missing edge that ` +
+                `nothing routes and nothing reports. Available skills: ${available}. Fix the name, ` +
+                `add the skill folder, or declare this edge in code.`);
+        }
+        return {
+            from,
+            to: route.to,
+            ...(route.onToolReturn !== undefined && { onToolReturn: route.onToolReturn }),
+            ...(route.onToolStatus !== undefined && { onToolStatus: route.onToolStatus }),
+        };
+    });
+}
+exports.toGraphSteps = toGraphSteps;
+//# sourceMappingURL=skillsFromDirRoutes.js.map

package/dist/lib/injection-engine/skillsFromDirRoutes.js.map

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

package/dist/lib/injection-engine/startRuleClaim.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * startRuleClaim — WHO CLAIMS A PHRASE. The one place that answers it.
+ *
+ * Two check-ups ask the same question of a graph's start rules and want
+ * opposite answers:
+ *
+ *   • `skillExamples.ts` declares a phrase and asserts THIS rule claims it;
+ *   • `skillNeverRoutes.ts` declares a phrase and asserts NO rule claims it.
+ *
+ * The question underneath is identical — run the compiled conditions over one
+ * concrete phrase, on the context a turn's first iteration really hands a start
+ * rule, and see who says yes. Two copies of that would drift the moment one of
+ * them learned something about the router the other did not, and the two would
+ * then disagree about the same graph. So it lives here, once, and the modules
+ * that report keep only their own sentences.
+ *
+ * Nothing here decides SEVERITY or writes a message — that is the reporting
+ * module's job, because the same "no" means different things to a positive and
+ * a negative assertion. This module only runs predicates and names conditions.
+ *
+ * Zone: PURE CORE (no engine, no loop). Pinned by
+ * `test/lib/injection-engine/skill-graph-fence.test.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claimLaws = exports.describeCondition = exports.COLD_CONTEXT_PHRASE = exports.coldContext = exports.runsOn = void 0;
+const skillMatch_js_1 = require("./skillMatch.js");
+/**
+ * Run one entry's condition over one phrase, on a COLD-START context — the
+ * context a turn's first iteration really hands a start rule: iteration 1, the
+ * phrase as `userMessage`, no history, no cursor, no tool results. A throw is
+ * reported as `'threw'` and treated as a no-match by every caller, which is
+ * exactly what the cursor resolver does with it at run time (so a claim made
+ * here stays true of the run).
+ *
+ * An entry with NO condition matches everything: that is the cold walk's law
+ * (`if (!e.when) return { to: e.id }`), not a shortcut.
+ */
+function runsOn(entry, phrase) {
+    if (entry.when === undefined)
+        return 'match';
+    try {
+        return entry.when(coldContext(phrase)) ? 'match' : 'no-match';
+    }
+    catch {
+        return 'threw';
+    }
+}
+exports.runsOn = runsOn;
+/** The one context every predicate in a phrase check is judged on. */
+function coldContext(userMessage) {
+    return { iteration: 1, userMessage, history: [], activatedInjectionIds: [] };
+}
+exports.coldContext = coldContext;
+/** The one context every predicate here is judged on, spelled out for the
+ *  reader of a message — a check that names its own inputs can be argued with;
+ *  one that hides them can only be guessed at. Kept as ONE string so every
+ *  message describes the SAME context {@link coldContext} really builds. */
+exports.COLD_CONTEXT_PHRASE = 'a COLD-START context (iteration 1, the phrase as `userMessage`, empty `history`, no ' +
+    'cursor and no activated injections)';
+/** How a rule's condition is named in a message: the data matcher quoted back,
+ *  the honest word for opaque code — or, for an entry that declares neither,
+ *  what having no condition MEANS. Naming a `when` predicate an unconditional
+ *  entry does not have is how a report describes a graph nobody wrote. */
+function describeCondition(entry) {
+    if (entry.match !== undefined)
+        return `its matcher \`${(0, skillMatch_js_1.plainMatchCaption)(entry.match)}\``;
+    return entry.when === undefined
+        ? 'declares no `match` and no `when`, so it claims every message'
+        : 'its `when` predicate';
+}
+exports.describeCondition = describeCondition;
+/** Build both laws' claim finders over one entry list, in declaration order. */
+function claimLaws(entries) {
+    const nonIntent = entries
+        .map((entry, index) => ({ entry, index }))
+        .filter(({ entry }) => entry.match?.kind !== 'intent');
+    const ruleClaimants = nonIntent.filter(({ entry }) => entry.when !== undefined);
+    return {
+        underColdWalk: (phrase) => nonIntent.find(({ entry }) => runsOn(entry, phrase) === 'match'),
+        underCascade: (phrase) => ruleClaimants.find(({ entry }) => runsOn(entry, phrase) === 'match'),
+    };
+}
+exports.claimLaws = claimLaws;
+//# sourceMappingURL=startRuleClaim.js.map

package/dist/lib/injection-engine/startRuleClaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startRuleClaim.js","sourceRoot":"","sources":["../../../src/lib/injection-engine/startRuleClaim.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAGH,mDAAyE;AAiBzE;;;;;;;;;;GAUG;AACH,SAAgB,MAAM,CAAC,KAAoB,EAAE,MAAc;IACzD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAC7C,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAPD,wBAOC;AAED,sEAAsE;AACtE,SAAgB,WAAW,CAAC,WAAmB;IAC7C,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,qBAAqB,EAAE,EAAE,EAAE,CAAC;AAC/E,CAAC;AAFD,kCAEC;AAED;;;4EAG4E;AAC/D,QAAA,mBAAmB,GAC9B,sFAAsF;IACtF,qCAAqC,CAAC;AAQxC;;;0EAG0E;AAC1E,SAAgB,iBAAiB,CAAC,KAAoB;IACpD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,iBAAiB,IAAA,iCAAiB,EAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;IAC1F,OAAO,KAAK,CAAC,IAAI,KAAK,SAAS;QAC7B,CAAC,CAAC,+DAA+D;QACjE,CAAC,CAAC,sBAAsB,CAAC;AAC7B,CAAC;AALD,8CAKC;AAwBD,gFAAgF;AAChF,SAAgB,SAAS,CAAC,OAAiC;IACzD,MAAM,SAAS,GAAG,OAAO;SACtB,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;SACzC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC;IACzD,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAChF,OAAO;QACL,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC;QAC3F,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC;KAC/F,CAAC;AACJ,CAAC;AATD,8BASC"}

package/dist/lib/injection-engine/toolOutcome.js

@@ -11,7 +11,7 @@
  * tool-effects module for one string union: the loop's vocabulary embedded
  * in the graph's contract, pointing the dependency the wrong way.
  *
- * So the six words moved DOWN here — a module with zero imports that both
+ * So the words moved DOWN here — a module with zero imports that both
  * sides read. `core/agent/toolEffects.ts` re-exports them under the same
  * names, so every existing import path is unchanged; that module remains
  * the owner of the ENVELOPE grammar (the two effect kinds, the recognizer,
@@ -30,5 +30,6 @@ exports.TOOL_RESULT_STATUSES = [
     'invalid',
     'partial',
     'pending',
+    'absent',
 ];
 //# sourceMappingURL=toolOutcome.js.map

package/dist/lib/injection-engine/toolOutcome.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolOutcome.js","sourceRoot":"","sources":["../../../src/lib/injection-engine/toolOutcome.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAUH,mEAAmE;AACtD,QAAA,oBAAoB,GAAgC;IAC/D,SAAS;IACT,SAAS;IACT,QAAQ;IACR,SAAS;IACT,SAAS;IACT,SAAS;CACV,CAAC"}
+{"version":3,"file":"toolOutcome.js","sourceRoot":"","sources":["../../../src/lib/injection-engine/toolOutcome.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AA0BH,mEAAmE;AACtD,QAAA,oBAAoB,GAAgC;IAC/D,SAAS;IACT,SAAS;IACT,QAAQ;IACR,SAAS;IACT,SAAS;IACT,SAAS;IACT,QAAQ;CACT,CAAC"}

package/dist/types/adapters/hosting/agentcore.d.ts

@@ -320,6 +320,14 @@ export type AgentCoreSessionsOptions = AgentCoreFileSessionsOptions | AgentCoreM
  * refused by name too (`UnreadableEnvelopeError`), never answered with a fresh
  * start. Only a session that was never written hydrates as `undefined`.
  *
+ * **The two modes differ on retention (9.42.0), and the difference is
+ * reported rather than smoothed over.** `'session-storage'` owns its file, so
+ * it implements the port's optional `retention()` as a sweep you call.
+ * `'memory'` appends events to a service whose expiry belongs to the memory
+ * resource an operator configured, and this shim has no delete on its surface
+ * — so it implements no retention member at all, and `sessionRetention()`
+ * refuses BY NAME rather than reporting a sweep that would delete nothing.
+ *
  * @example  Survive a stop/resume, no AWS SDK required
  *   agentCoreSessions({ store: 'session-storage' });
  *

package/dist/types/adapters/hosting/agentcore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentcore.d.ts","sourceRoot":"","sources":["../../../../src/adapters/hosting/agentcore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agentcore.d.ts","sourceRoot":"","sources":["../../../../src/adapters/hosting/agentcore.ts"],"names":[],"mappings":"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"}

package/dist/types/adapters/hosting/firestoreSessions.d.ts

@@ -11,9 +11,9 @@
  * containers, one conversation" answer Google has.
  *
  * ── The shape, said plainly ─────────────────────────────────────────────────
- * One collection. One document per session. Six fields:
+ * One collection. One document per session. Seven fields:
  *
- *   sessionId · format · savedAt · envelope · owner · messageCount
+ *   sessionId · format · savedAt · envelope · owner · messageCount · expiresAt
  *
  * That is the SQLite table, moved. It is deliberately the same shape, because
  * the two stores implement the same port under the same laws, and a reader who
@@ -95,6 +95,45 @@
  * in, and names those fields rather than restating the service's message — see
  * {@link firestoreFailure} for why no Google text is ever echoed here.
  *
+ * ── Retention: a SECOND timestamp, not a converted one (9.42.0) ─────────────
+ * A native Firestore TTL policy deletes a document when a field of type
+ * **Timestamp** is in the past. `savedAt` is a NUMBER — epoch milliseconds —
+ * so until this release an operator could not point a policy at this
+ * collection at all without a library change. The fix is a second field,
+ * `expiresAt`, written as a `Date` (the client stores one as a Timestamp) on
+ * every persist, holding `savedAt + expireAfterMs`. Give the store no
+ * `expireAfterMs` and the field is written as `null`, which a TTL policy
+ * ignores, and nothing about this release changes.
+ *
+ * **`savedAt` was NOT converted, and that is the load-bearing decision.** It is
+ * the ordering key of the composite index, the field the listing sorts by, and
+ * the first half of every cursor this store has ever minted (`<savedAt>:<docId>`,
+ * parsed with `parseFloat` and handed back to `startAfter` as a number).
+ * Converting it would have meant a new index, a new cursor grammar, and every
+ * pagination token issued by an earlier release becoming unreadable — but the
+ * decisive one is quieter: **Firestore's value ordering sorts by TYPE first.**
+ * Every number sorts before every timestamp. A collection holding old
+ * number-`savedAt` documents beside new timestamp-`savedAt` ones would list
+ * them in two blocks, all of one type then all of the other, with a person's
+ * conversations silently out of order by the type of the field rather than by
+ * when they were written. A second field costs one small write per turn and
+ * has no such shadow.
+ *
+ * So the migration consequence, plainly:
+ *
+ *   • **Every document already stored stays readable and listable.** Nothing
+ *     about `savedAt`, the index, the cursor or the query changed, and a
+ *     document written by 9.33–9.41 is read by this release unchanged.
+ *   • **Old documents do not start expiring.** They carry no `expiresAt`, and
+ *     a TTL policy ignores a document whose field is missing. A conversation
+ *     that is still being used gains one on its next turn; a conversation
+ *     nobody ever writes to again keeps living. If those matter, delete them
+ *     by hand once (a query on `savedAt` plus `forget`, or a `gcloud`
+ *     bulk-delete) — this adapter will not walk your collection behind your
+ *     back.
+ *   • **The policy is still yours to create.** `retention().enableWith` prints
+ *     the exact command with your collection and database in it.
+ *
  * ── The ceiling, since a store should name its own ──────────────────────────
  * A Firestore document is capped at 1 MiB. A conversation whose stored envelope
  * approaches that is refused BY NAME before the write
@@ -122,8 +161,29 @@
  * for it. So the write is a transaction.
  *
  * ── How much of this is verified ────────────────────────────────────────────
- * **Contract-shaped and tested. NOT field-validated.** Nothing here has been run
- * against a live Firestore by this repository.
+ * **Field-validated except the ownership refusal (2026-08).** An independent
+ * field trial ran THIS adapter against a real Firestore and exercised seven of
+ * its eight areas live: the round trip, the server-side indexed listing with
+ * its document-name tiebreak and real cursor, the missing-index refusal, the
+ * hashed document name, the size ceiling, ownership derived from the envelope,
+ * and `forget`.
+ *
+ * The eighth is named because under-claiming and over-claiming are the same
+ * defect: **the refusal of a turn signed by somebody else** — the
+ * `resolveSessionOwner` conflict this file's `persist` raises out of the
+ * transaction — was NOT exercised, because it did not exist when the trial
+ * ran. It is held by tests here, including the contested-write case of the
+ * shared conformance battery, and by nothing in the field. Two writers racing
+ * for one fresh session against a real Firestore, with the real client's
+ * transaction retry underneath, is exactly the shape a double models by
+ * assumption; the sibling Vertex adapter's equivalent was found in the field
+ * and not in a test suite.
+ *
+ * This section said "NOT field-validated. Nothing here has been run against a
+ * live Firestore" for two releases after that stopped being true. Under-claiming
+ * is the safe direction and it is still the same defect class the trials keep
+ * reporting: a status that does not track the evidence is a status nobody can
+ * use, whichever way it is wrong.
  *
  * The pin is the `firestoreSessions` row of `GOOGLE_SURFACE_PINS` in
  * `test/adapters/google/googlePin.ts`, asserted by
@@ -148,7 +208,8 @@
  * everywhere. That the row spells those members the way Google does is held by a
  * hand check against a real install, not by a test that runs here.
  *
- * The DESIGN is informed by an independent field trial of a different Firestore
+ * The DESIGN was informed, before any of that, by an EARLIER and separate trial
+ * of a DIFFERENT Firestore
  * session adapter, which ran against a real Firestore and passed eight ownership
  * and history checks — and whose own report named the defect this adapter does
  * not reproduce: that adapter read every document for one owner, sorted them in
@@ -158,7 +219,7 @@
  * real service; it proves nothing about this file's query, cursor, transaction
  * or index, because that adapter had none of them.
  */
-import type { SessionLifecycle } from '../../hosting/types.js';
+import type { SessionExpiryPolicy, SessionLifecycle } from '../../hosting/types.js';
 /** One document as it came back. `firestore.d.ts` line 1605. */
 export interface FirestoreDocumentSnapshotLike {
     /** A PROPERTY, not a method — `readonly exists: boolean`. */
@@ -282,6 +343,39 @@ export interface FirestoreSessionsOptions {
      * still loading the module?" is a fair question to have answered here.
      */
     readonly firestore?: FirestoreLike;
+    /**
+     * How long after its last turn a conversation should expire, in
+     * milliseconds. Omit and nothing expires (9.42.0).
+     *
+     * Setting it makes every write stamp {@link EXPIRES_AT_FIELD} —
+     * `savedAt + expireAfterMs`, as a timestamp — which is the field a **native
+     * Firestore TTL policy** reads. The policy itself is yours to enable, once,
+     * with the command {@link FirestoreSessions.retention} hands you; this store
+     * writes what it reads and never deletes a document on a clock of its own.
+     * Both halves are needed and neither is silent about the other: with no
+     * policy the field is inert data, and with no `expireAfterMs` the policy has
+     * nothing to act on.
+     *
+     * **The clock is the conversation's own `savedAt`, not this process's.** So
+     * the expiry is IDLE time: every turn pushes it out, and a conversation dies
+     * `expireAfterMs` after somebody last spoke, which is what a session
+     * retention rule almost always means. It also makes the stamp a pure
+     * function of the envelope — the same conversation stamps the same instant
+     * on any machine, whatever its clock says.
+     *
+     * **It does not reach backwards.** Documents written before this was
+     * configured carry no expiry field, and a TTL policy ignores a document
+     * whose field is missing — so old conversations expire only once they are
+     * written again. See the module header for what to do about the ones that
+     * never will be.
+     *
+     * Named `expireAfterMs` rather than `ttlMs` deliberately, even though the
+     * artifact stores in this package spell their dial the second way: theirs is
+     * stamped once at mint and measured from creation, and this one is measured
+     * from the LAST turn and moves on every write. One word for two clocks would
+     * be the cheaper name and the more expensive mistake.
+     */
+    readonly expireAfterMs?: number;
     /**
      * @internal Test seam only — the `@google-cloud/firestore` module, injected.
      * Lets the suite exercise every path (including the refusals) without a
@@ -292,6 +386,34 @@ export interface FirestoreSessionsOptions {
 }
 /** Where sessions live when the caller names no collection. */
 export declare const DEFAULT_SESSION_COLLECTION = "agentfootprint_sessions";
+/**
+ * The document field a native TTL policy is configured against (9.42.0).
+ *
+ * A SECOND field beside `savedAt`, never a change to it — see the module
+ * header for why converting the ordering key would have re-sorted every
+ * conversation already in the collection.
+ *
+ * Exported because an operator has to type this name into the console or the
+ * `gcloud` line, and a field name that lives only inside a string literal is a
+ * field name somebody will mistype at 2am.
+ */
+export declare const EXPIRES_AT_FIELD = "expiresAt";
+/**
+ * The one step that turns the TTL policy on, with this store's own collection
+ * and database already in it.
+ *
+ * One spelling, shared by the retention answer and the documentation that
+ * quotes it, for the same reason the missing-index refusal prints the whole
+ * `gcloud` line: the person reading it can fix this in sixty seconds, and only
+ * if nobody makes them go and look up the flags first.
+ *
+ * `--database` is always printed, including for `(default)`, where gcloud
+ * would have assumed it — a project may hold several databases, and a policy
+ * created on the wrong one leaves conversations living forever with nothing to
+ * suggest why. Single-quoted, because `(default)` is bare parentheses and a
+ * syntax error in every shell this will be pasted into.
+ */
+export declare function ttlPolicyCommand(collection: string, database?: string): string;
 /**
  * Firestore's hard ceiling on one document, in bytes. Not ours — the service's.
  *
@@ -321,6 +443,21 @@ export interface FirestoreSessions extends SessionLifecycle {
     readonly collection: string;
     /** Forget one session. A session that was never there is not an error. */
     forget(sessionId: string): Promise<void>;
+    /**
+     * How conversations here stop existing: **the backend does it**, on a native
+     * TTL policy an operator enables once, against {@link EXPIRES_AT_FIELD}
+     * (9.42.0).
+     *
+     * Narrowed from the port's optional member to a required one, and to the one
+     * arm this store can be: a caller holding a `FirestoreSessions` needs no
+     * feature check and no branch, and gets a compile error rather than a
+     * runtime surprise if they reach for a sweep that does not exist here.
+     *
+     * `active` says whether this store was built with `expireAfterMs` and is
+     * therefore stamping anything; `enableWith` is the exact command, with this
+     * store's collection and database already filled in.
+     */
+    retention(): SessionExpiryPolicy;
     /**
      * The document name one session id maps to — the sha-256 above.
      *
@@ -401,20 +538,31 @@ export declare class EnvelopeTooLargeError extends Error {
  * Conversations in Firestore — a fleet-shared session store with no instance to
  * run.
  *
- * **Status: contract-shaped and tested, NOT field-validated.** Every SDK member
- * it calls was read off a real install of `@google-cloud/firestore` 9.0.0 and
- * hand-verified there; the test that re-checks those names against the real
- * package SKIPS in this repository, because the package is deliberately not
- * installed here. What runs in CI is the dispatch pin. No test here pretends to
- * have reached Google. See the module header for the full account, and for what
- * a field trial of a DIFFERENT adapter did and did not establish about this
- * design.
+ * **Status: field-validated except the ownership refusal (2026-08).** An
+ * independent field trial ran this adapter against a real Firestore and
+ * exercised seven of its eight areas live — round trip, indexed and cursored
+ * listing, the missing-index refusal, the hashed document name, the size
+ * ceiling, derived ownership and `forget`. The eighth, the refusal of a turn
+ * signed by somebody ELSE, was added after the trial and is held by tests
+ * here and by nothing in the field. Every SDK member it calls was read off a
+ * real install of `@google-cloud/firestore` 9.0.0 and hand-verified there; the
+ * test that re-checks those names against the real package SKIPS in this
+ * repository, because the package is deliberately not installed here. What
+ * runs in CI is the dispatch pin. See the module header for the full account.
  *
  * @throws FirestoreIndexMissingError from `listByUser` until the composite index
  *   exists — see the module header for the exact index.
  * @throws EnvelopeTooLargeError from `persist` for a conversation above
  *   {@link FIRESTORE_MAX_ENVELOPE_BYTES}. Never truncated.
  *
+ * @example  Conversations that expire 30 days after their last turn
+ *   const sessions = firestoreSessions({
+ *     project: 'my-project',
+ *     expireAfterMs: 30 * 24 * 60 * 60 * 1000,
+ *   });
+ *   // Then, ONCE, as an operator — the store prints the exact command:
+ *   console.log(sessions.retention().enableWith);
+ *
  * @example  A standing agent whose conversations are shared across instances
  *   import { standingAgent, nodeHost } from 'agentfootprint/hosting';
  *   import { firestoreSessions } from 'agentfootprint/hosting';

package/dist/types/adapters/hosting/firestoreSessions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"firestoreSessions.d.ts","sourceRoot":"","sources":["../../../../src/adapters/hosting/firestoreSessions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"firestoreSessions.d.ts","sourceRoot":"","sources":["../../../../src/adapters/hosting/firestoreSessions.ts"],"names":[],"mappings":"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"}

package/dist/types/adapters/hosting/googleAgentEngine.d.ts

@@ -100,7 +100,7 @@
  * be read must never be answered with a fresh start — that failure is
  * indistinguishable, from the outside, from a brand-new user.
  */
-import type { CheckpointEnvelope, SessionLifecycle } from '../../hosting/types.js';
+import type { CheckpointEnvelope, SessionExpiryPolicy, SessionLifecycle } from '../../hosting/types.js';
 import { type AiPlatformConnection } from '../google/aiPlatform.js';
 /**
  * The `sessionState` key the envelope lives under.
@@ -195,6 +195,21 @@ export interface AgentEngineSessions extends SessionLifecycle {
     readonly parent: string;
     /** Forget one session. A session that was never there is not an error. */
     forget(sessionId: string): Promise<void>;
+    /**
+     * How conversations here stop existing: **the service does it**, on the
+     * `ttl` this store was built with (9.42.0).
+     *
+     * Narrowed from the port's optional member to a required one, and to the one
+     * arm this store can be — a caller holding an `AgentEngineSessions` needs no
+     * feature check, and reaching for a sweep that does not exist here is a
+     * compile error rather than a surprise at 3am.
+     *
+     * There is nothing to call and nothing for a cron job to do. `active` says
+     * whether a `ttl` was given at all; `enableWith` says what to pass and
+     * repeats the two facts a caller has to plan around — the service's 24-hour
+     * floor, and that the value is sent on CREATE only.
+     */
+    retention(): SessionExpiryPolicy;
     /**
      * Stop using this store. Idempotent, and **final** — reading or writing
      * afterwards refuses by name rather than quietly reconnecting, because a

package/dist/types/adapters/hosting/googleAgentEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"googleAgentEngine.d.ts","sourceRoot":"","sources":["../../../../src/adapters/hosting/googleAgentEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AAKH,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAGjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAUL,KAAK,oBAAoB,EAI1B,MAAM,yBAAyB,CAAC;AAIjC;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,WAAW,0BAA2B,SAAQ,oBAAoB;IACtE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,KAAK,MAAM,CAAC,CAAC;IACzF;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,6DAA6D;AAC7D,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,mBAAmB,CAkT5F"}
+{"version":3,"file":"googleAgentEngine.d.ts","sourceRoot":"","sources":["../../../../src/adapters/hosting/googleAgentEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AAKH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAGjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAUL,KAAK,oBAAoB,EAI1B,MAAM,yBAAyB,CAAC;AAIjC;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,WAAW,0BAA2B,SAAQ,oBAAoB;IACtE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,KAAK,MAAM,CAAC,CAAC;IACzF;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,6DAA6D;AAC7D,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;;;;;;;;;;;;;OAaG;IACH,SAAS,IAAI,mBAAmB,CAAC;IACjC;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,mBAAmB,CAiV5F"}