agentfootprint 9.46.3 → 9.48.0

package/dist/esm/recipes/provenance.js

@@ -0,0 +1,53 @@
+/**
+ * provenance — who registered this name.
+ *
+ * Pattern: a small value type + one formatter. Pure, no dependencies beyond
+ *          the recipe types.
+ * Role:    recipes/ layer. `AgentBuilder` records a {@link RecipeSource} beside
+ *          every tool name and injection id it takes, and reads it back when
+ *          two registrations collide.
+ * Emits:   N/A.
+ *
+ * ## Why provenance at all
+ *
+ * The builder has always refused a duplicate tool name — the model dispatches
+ * by name, so two tools called `search` is a coin flip. What it could not say
+ * was WHERE each one came from. With one recipe in the chain that answer stops
+ * being obvious ("I never registered a `search` tool") and with two it is
+ * unrecoverable without reading both recipes' source. A refusal that names both
+ * sides turns a hunt into a sentence.
+ *
+ * ## Three arms, because three things are true and one of them is "I do not know"
+ *
+ * `local` and `unattributed` are NOT the same fact, and collapsing them would
+ * make the refusal lie. `local` means: this builder watched you call
+ * `.tool()` / `.injection()` yourself. `unattributed` means: the name was
+ * already taken when the ledger was consulted and no source was recorded for
+ * it — the honest answer is that this builder does not know, and saying
+ * "you registered it" would send the reader to look in the one place it is not.
+ *
+ * The arm exists because there is more than one way into the injection list:
+ * `.injection()` is the funnel for the named flavors, and `.outputSchema()`
+ * mounts an instruction of its own. Both record a source today. A third site
+ * added later would not, and this arm is what keeps that omission honest
+ * instead of blaming the caller.
+ */
+/** The one `local` value. A frozen singleton — it carries no data. */
+export const LOCAL_SOURCE = Object.freeze({ kind: 'local' });
+/**
+ * Describe a source in a sentence fragment that reads inside a refusal.
+ *
+ * `undefined` is the unattributed case — see the header. It is a separate
+ * answer, never folded into `local`.
+ */
+export function describeRecipeSource(source) {
+    if (source === undefined) {
+        return ('an earlier registration with no recorded source (a builder method mounted it; ' +
+            'this builder did not attribute it)');
+    }
+    if (source.kind === 'local')
+        return 'this agent, directly';
+    const chain = [...source.stack].reverse().map((r) => `recipe '${r.id}' ${r.version}`);
+    return chain.join(' ← applied by ');
+}
+//# sourceMappingURL=provenance.js.map

package/dist/esm/recipes/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../../../src/recipes/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAeH,sEAAsE;AACtE,MAAM,CAAC,MAAM,YAAY,GAAiB,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAgB,EAAE,CAAC,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAgC;IACnE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,CACL,gFAAgF;YAChF,oCAAoC,CACrC,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,sBAAsB,CAAC;IAC3D,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACtF,OAAO,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;AACtC,CAAC"}

package/dist/esm/recipes/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * recipes/types — the declared unit of agent configuration.
+ *
+ * Pattern: a data DECLARATION over an existing fluent builder. No class, no
+ *          registry, no lifecycle. The repo's own instruction is that named
+ *          patterns are recipes over primitives rather than new machinery, and
+ *          this file is that instruction taken literally.
+ * Role:    recipes/ layer, pure. Nothing here imports the engine, a provider,
+ *          or a store — the only agentfootprint type it names is
+ *          {@link AgentBuilder}, and it names it as a TYPE.
+ * Emits:   N/A. `AgentBuilder.recipe()` records the row; `runManifest` reports
+ *          it.
+ *
+ * ## The gap this closes
+ *
+ * Every capability an agent needs already ships. What did not ship was a
+ * declared, versioned, inspectable unit of CONFIGURATION. So an agent's setup
+ * lived as prose in an example, was copy-pasted into an app, drifted there, and
+ * afterwards nothing on the run could say which composition produced the agent
+ * that answered. Two runs of "the support agent" could differ in every tool and
+ * every instruction and be indistinguishable on the record.
+ *
+ * A recipe is the missing noun: a name, a version, and a function that calls
+ * the builder methods that already exist.
+ *
+ * ```ts
+ * export const supportDesk = defineAgentRecipe({
+ *   id: 'support-desk',
+ *   version: '1.2.0',
+ *   description: 'Order lookup + refund policy, the way support runs it.',
+ *   configure: (agent) => {
+ *     agent.system('You answer support questions.').tool(lookupOrder);
+ *   },
+ * });
+ *
+ * const agent = Agent.create({ provider, model }).recipe(supportDesk).build();
+ * ```
+ *
+ * ## No lifecycle magic — stated here because it is the load-bearing limit
+ *
+ * A recipe composes CONFIGURATION and nothing else:
+ *
+ *   • nothing is registered anywhere — a recipe is not discovered, not looked
+ *     up by name, and not resolved from a registry. You import the object and
+ *     hand it to `.recipe()`. There is no global map to go stale, and no
+ *     "which version of `support-desk` is installed" question;
+ *   • nothing is closable — a recipe holds no connection, no handle and no
+ *     process. It never gets a `close()`, a `dispose()` or a teardown hook,
+ *     and it is never awaited: `configure` is synchronous because `build()`
+ *     is (an `async configure` is refused by name rather than silently not
+ *     awaited);
+ *   • nothing is deferred — every call `configure` makes happens during
+ *     `.recipe()`, at the position in the chain where you wrote it. There is
+ *     no later phase in which a recipe acts, so a run's behaviour is decided
+ *     entirely by the builder calls you can read.
+ *
+ * That is deliberately thin. The thing being named is a COMPOSITION, and a
+ * composition that also owned a resource would be a component wearing a
+ * composition's name — the shape that makes "who closed the pool?" unanswerable
+ * two releases later.
+ */
+import type { AgentBuilder } from '../core/agent/AgentBuilder.js';
+/**
+ * A named, versioned composition over the agent builder.
+ *
+ * Build one with {@link defineAgentRecipe}, which validates every field and
+ * freezes the result. A hand-written object literal is accepted by
+ * `.recipe()` too — it runs the SAME validation — so a recipe cannot reach an
+ * agent without passing the checks; the factory only moves the refusal to the
+ * declaration, where the fix is.
+ */
+export interface AgentRecipe {
+    /**
+     * The composition's plain name — lower-case words joined by single hyphens
+     * (`support-desk`, `triage`, `refund-policy`).
+     *
+     * It carries NO version: `support-desk-2` is refused, because the version
+     * axis already exists as its own field and an id that encodes one produces
+     * two names for one composition, neither of which can be grouped on.
+     */
+    readonly id: string;
+    /**
+     * The composition's version, as SemVer 2.0.0 (`'1.2.0'`, `'2.0.0-rc.1'`).
+     *
+     * A version is what makes a recipe row on a run manifest worth reading: two
+     * runs of `support-desk` that answered differently are a mystery until the
+     * record says one was `1.2.0` and the other `1.3.0`.
+     */
+    readonly version: string;
+    /** What this composition is for, in one sentence. Optional, and never
+     *  reported on the wire — the manifest carries the id and the version only. */
+    readonly description?: string;
+    /**
+     * Apply the composition: call the builder methods this recipe stands for.
+     *
+     * Runs SYNCHRONOUSLY, exactly once, at the `.recipe()` call site. The return
+     * value is ignored — `AgentBuilder` is mutated in place and every method
+     * returns the same object — so `(agent) => agent.system('…').tool(t)` and a
+     * statement body are the same program.
+     */
+    configure(builder: AgentBuilder): void;
+}
+/**
+ * One applied recipe, as the run manifest reports it: the id and the version,
+ * never the description and never the function.
+ *
+ * The two stay SEPARATE FIELDS on purpose. A composed key (`'support-desk@1.2.0'`)
+ * would be one string that two different pairs could produce as soon as either
+ * half is allowed to contain the separator — the collision class this repo has
+ * fixed seven times. Nothing here ever joins them.
+ */
+export interface AppliedRecipe {
+    readonly id: string;
+    readonly version: string;
+}
+/**
+ * What happens when a recipe introduces a tool name or an injection id that is
+ * already taken.
+ *
+ * `'error'` is the only policy that exists, and it is the default. The
+ * alternatives a reader will reach for — skip the recipe's version, let it
+ * replace what is there, rename one automatically — are real designs, and none
+ * of them is implemented: each has to answer where the drop is RECORDED, and a
+ * conflict resolved silently is exactly the "accepted and quietly wrong" shape
+ * this library refuses. So an unimplemented policy is refused by name (see
+ * {@link resolveRecipeConflictPolicy}) rather than approximated by the one that
+ * ships.
+ */
+export type RecipeConflictPolicy = 'error';
+/** Options for `AgentBuilder.recipe(recipe, options)`. */
+export interface RecipeOptions {
+    /** See {@link RecipeConflictPolicy}. Default `'error'`. */
+    readonly conflict?: RecipeConflictPolicy;
+}

package/dist/esm/recipes/types.js

@@ -0,0 +1,63 @@
+/**
+ * recipes/types — the declared unit of agent configuration.
+ *
+ * Pattern: a data DECLARATION over an existing fluent builder. No class, no
+ *          registry, no lifecycle. The repo's own instruction is that named
+ *          patterns are recipes over primitives rather than new machinery, and
+ *          this file is that instruction taken literally.
+ * Role:    recipes/ layer, pure. Nothing here imports the engine, a provider,
+ *          or a store — the only agentfootprint type it names is
+ *          {@link AgentBuilder}, and it names it as a TYPE.
+ * Emits:   N/A. `AgentBuilder.recipe()` records the row; `runManifest` reports
+ *          it.
+ *
+ * ## The gap this closes
+ *
+ * Every capability an agent needs already ships. What did not ship was a
+ * declared, versioned, inspectable unit of CONFIGURATION. So an agent's setup
+ * lived as prose in an example, was copy-pasted into an app, drifted there, and
+ * afterwards nothing on the run could say which composition produced the agent
+ * that answered. Two runs of "the support agent" could differ in every tool and
+ * every instruction and be indistinguishable on the record.
+ *
+ * A recipe is the missing noun: a name, a version, and a function that calls
+ * the builder methods that already exist.
+ *
+ * ```ts
+ * export const supportDesk = defineAgentRecipe({
+ *   id: 'support-desk',
+ *   version: '1.2.0',
+ *   description: 'Order lookup + refund policy, the way support runs it.',
+ *   configure: (agent) => {
+ *     agent.system('You answer support questions.').tool(lookupOrder);
+ *   },
+ * });
+ *
+ * const agent = Agent.create({ provider, model }).recipe(supportDesk).build();
+ * ```
+ *
+ * ## No lifecycle magic — stated here because it is the load-bearing limit
+ *
+ * A recipe composes CONFIGURATION and nothing else:
+ *
+ *   • nothing is registered anywhere — a recipe is not discovered, not looked
+ *     up by name, and not resolved from a registry. You import the object and
+ *     hand it to `.recipe()`. There is no global map to go stale, and no
+ *     "which version of `support-desk` is installed" question;
+ *   • nothing is closable — a recipe holds no connection, no handle and no
+ *     process. It never gets a `close()`, a `dispose()` or a teardown hook,
+ *     and it is never awaited: `configure` is synchronous because `build()`
+ *     is (an `async configure` is refused by name rather than silently not
+ *     awaited);
+ *   • nothing is deferred — every call `configure` makes happens during
+ *     `.recipe()`, at the position in the chain where you wrote it. There is
+ *     no later phase in which a recipe acts, so a run's behaviour is decided
+ *     entirely by the builder calls you can read.
+ *
+ * That is deliberately thin. The thing being named is a COMPOSITION, and a
+ * composition that also owned a resource would be a component wearing a
+ * composition's name — the shape that makes "who closed the pool?" unanswerable
+ * two releases later.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/recipes/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/recipes/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG"}

package/dist/esm/recipes/version.d.ts

@@ -0,0 +1,38 @@
+/**
+ * version — is this string a version, or something that looks like one?
+ *
+ * Pattern: a total predicate + a refusal sentence. Pure, no dependencies.
+ * Role:    recipes/ layer. Used by `defineAgentRecipe` and by the same
+ *          validation `AgentBuilder.recipe()` runs on a hand-written literal.
+ * Emits:   N/A.
+ *
+ * ## Why strict SemVer, and why a near-miss is refused rather than repaired
+ *
+ * The version is the half of a recipe row that makes the other half worth
+ * reading: two runs of `support-desk` that behaved differently are a mystery
+ * until the record says `1.2.0` and `1.3.0`. That only works if every producer
+ * spells versions the same way, so the ones that would quietly break grouping
+ * are refused at the declaration:
+ *
+ *   `'1.2'`      two runs, `'1.2'` and `'1.2.0'`, that are the same version and
+ *                do not group together.
+ *   `'v1.2.3'`   the same, with a decoration that sorts differently.
+ *   `'1.02.3'`   leading zeros: `'1.02.3'` and `'1.2.3'` again split one arm.
+ *   `'latest'`   a RANGE, not a version — it names whatever was installed, so
+ *   `'^1.2.3'`   the row would describe a different composition each week and
+ *   `'1.x'`      say nothing about the run it is stamped on.
+ *
+ * None is repaired. Padding `'1.2'` to `'1.2.0'` would put a version on the
+ * record that the author never wrote, which is the one thing a manifest field
+ * may not do.
+ */
+/** Whether `value` is a SemVer 2.0.0 version string. Total: any input, no throw. */
+export declare function isSemverVersion(value: unknown): value is string;
+/**
+ * The sentence a bad version gets. Names the value, the grammar, and the
+ * specific mistake when the shape identifies one — a refusal that only says
+ * "invalid" makes the author guess which half was wrong.
+ *
+ * @param callSite - the API the author called, e.g. `defineAgentRecipe`.
+ */
+export declare function versionRefusal(callSite: string, value: unknown): string;

package/dist/esm/recipes/version.js

@@ -0,0 +1,84 @@
+/**
+ * version — is this string a version, or something that looks like one?
+ *
+ * Pattern: a total predicate + a refusal sentence. Pure, no dependencies.
+ * Role:    recipes/ layer. Used by `defineAgentRecipe` and by the same
+ *          validation `AgentBuilder.recipe()` runs on a hand-written literal.
+ * Emits:   N/A.
+ *
+ * ## Why strict SemVer, and why a near-miss is refused rather than repaired
+ *
+ * The version is the half of a recipe row that makes the other half worth
+ * reading: two runs of `support-desk` that behaved differently are a mystery
+ * until the record says `1.2.0` and `1.3.0`. That only works if every producer
+ * spells versions the same way, so the ones that would quietly break grouping
+ * are refused at the declaration:
+ *
+ *   `'1.2'`      two runs, `'1.2'` and `'1.2.0'`, that are the same version and
+ *                do not group together.
+ *   `'v1.2.3'`   the same, with a decoration that sorts differently.
+ *   `'1.02.3'`   leading zeros: `'1.02.3'` and `'1.2.3'` again split one arm.
+ *   `'latest'`   a RANGE, not a version — it names whatever was installed, so
+ *   `'^1.2.3'`   the row would describe a different composition each week and
+ *   `'1.x'`      say nothing about the run it is stamped on.
+ *
+ * None is repaired. Padding `'1.2'` to `'1.2.0'` would put a version on the
+ * record that the author never wrote, which is the one thing a manifest field
+ * may not do.
+ */
+/**
+ * The official SemVer 2.0.0 grammar (semver.org, "Backus–Naur Form Grammar for
+ * Valid SemVer Versions"), transcribed. Kept verbatim rather than loosened: a
+ * home-grown `\d+\.\d+\.\d+` would accept `01.2.3` and reject `1.0.0-rc.1`,
+ * which is wrong in both directions.
+ */
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+/** Whether `value` is a SemVer 2.0.0 version string. Total: any input, no throw. */
+export function isSemverVersion(value) {
+    return typeof value === 'string' && SEMVER.test(value);
+}
+/**
+ * The sentence a bad version gets. Names the value, the grammar, and the
+ * specific mistake when the shape identifies one — a refusal that only says
+ * "invalid" makes the author guess which half was wrong.
+ *
+ * @param callSite - the API the author called, e.g. `defineAgentRecipe`.
+ */
+export function versionRefusal(callSite, value) {
+    const shown = typeof value === 'string' ? `'${value}'` : `${typeof value}`;
+    return (`${callSite}: version ${shown} is not a version. A recipe's version must be SemVer 2.0.0 ` +
+        `— three dot-separated numbers, optionally a prerelease and build ('1.2.0', '2.0.0-rc.1', ` +
+        `'1.0.0+build.5').\n\n` +
+        `${diagnose(value)}\n\n` +
+        `Nothing is padded or stripped for you: the version is stamped on the run manifest, where ` +
+        `it is the field two runs are grouped by, and a value the author never wrote would group ` +
+        `runs that are not the same composition.`);
+}
+/** The specific mistake, when the shape names one. Falls back to the general rule. */
+function diagnose(value) {
+    if (typeof value !== 'string') {
+        return `A version is a string; this was ${value === null ? 'null' : typeof value}.`;
+    }
+    if (value.trim() === '')
+        return 'This one is empty.';
+    if (/^v/i.test(value)) {
+        return `Drop the leading '${value[0] ?? 'v'}' — SemVer carries no prefix ('1.2.0', not '${value}').`;
+    }
+    if (/^\d+\.\d+$/.test(value)) {
+        return (`This has two parts; SemVer has three. Did you mean '${value}.0'? Write it out — ` +
+            `'${value}' and '${value}.0' would be two labels for one composition.`);
+    }
+    if (/^\d+$/.test(value)) {
+        return `This is one number. Did you mean '${value}.0.0'?`;
+    }
+    if (/^[~^><=]/.test(value) || /\bx\b|\*/.test(value)) {
+        return (`This is a RANGE, not a version. A range names whatever happens to be installed, so the ` +
+            `manifest row would describe a different composition each week. Write the version this ` +
+            `recipe IS.`);
+    }
+    if (/^0\d|\.0\d/.test(value)) {
+        return `Numeric parts carry no leading zeros ('1.2.0', not '01.02.00').`;
+    }
+    return `Neither the numbers, the prerelease nor the build metadata matched the grammar.`;
+}
+//# sourceMappingURL=version.js.map

package/dist/esm/recipes/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../src/recipes/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,GACV,qLAAqL,CAAC;AAExL,oFAAoF;AACpF,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,KAAc;IAC7D,MAAM,KAAK,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,EAAE,CAAC;IAC3E,OAAO,CACL,GAAG,QAAQ,aAAa,KAAK,6DAA6D;QAC1F,2FAA2F;QAC3F,uBAAuB;QACvB,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM;QACxB,2FAA2F;QAC3F,0FAA0F;QAC1F,yCAAyC,CAC1C,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,mCAAmC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,GAAG,CAAC;IACtF,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,oBAAoB,CAAC;IACrD,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,qBACL,KAAK,CAAC,CAAC,CAAC,IAAI,GACd,+CAA+C,KAAK,KAAK,CAAC;IAC5D,CAAC;IACD,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,CACL,uDAAuD,KAAK,sBAAsB;YAClF,IAAI,KAAK,UAAU,KAAK,8CAA8C,CACvE,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,qCAAqC,KAAK,QAAQ,CAAC;IAC5D,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrD,OAAO,CACL,yFAAyF;YACzF,wFAAwF;YACxF,YAAY,CACb,CAAC;IACJ,CAAC;IACD,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,iEAAiE,CAAC;IAC3E,CAAC;IACD,OAAO,iFAAiF,CAAC;AAC3F,CAAC"}

package/dist/esm/recorders/observability/fileRecordingSink.d.ts

@@ -0,0 +1,104 @@
+/**
+ * fileRecordingSink — one archived run, one JSON file, in a directory.
+ *
+ * The destination that needs nothing installed: an incident can be inspected
+ * with `ls` and `cat`, and a run archive is a folder you can tar. It is also
+ * the reference implementation of {@link RecordingSink} — a sink is one method,
+ * and this file is what "implement the other ones like this" points at.
+ *
+ * ## The file name is a key, and keys must be injective
+ *
+ * `runId` becomes a file name, which makes `runId ↦ name` a mapping used as a
+ * key: two different runs landing on one name means one archive silently
+ * overwrites another, and the evidence is gone with no error anywhere. So the
+ * mapping is `runId + '.json'` — appending a constant suffix, which is
+ * injective — over a DOMAIN that is asserted rather than assumed, and anything
+ * outside it is refused by name.
+ *
+ * The domain is `[a-z0-9]` followed by `[a-z0-9._-]*`, and every exclusion is
+ * load-bearing:
+ *
+ *   • **no uppercase.** This is the one that looks like fussiness and is not.
+ *     macOS/APFS and Windows/NTFS are case-INSENSITIVE by default, so `run-A`
+ *     and `run-a` are two distinct strings that name ONE file. A mapping that
+ *     is injective as a string can still collide as a file name, which is
+ *     exactly the bug artifacts/scopePath.ts found on a stock Mac in 9.44.0 —
+ *     its conformance battery had pairs for separators, absence markers and
+ *     pre-escaped values, and no pair differing only in case. Excluding
+ *     uppercase from the domain means no two valid ids differ by case alone, so
+ *     there is nothing for a case-folding filesystem to fold together.
+ *   • **no `/` or `\`.** A separator inside a field is separator donation: an
+ *     id containing one would silently become a path with a directory hop.
+ *   • **no leading `.` or `-`.** A leading dot hides the archive from `ls`; a
+ *     leading dash is read as a flag by every CLI tool that would then handle
+ *     it. Both are enforced by the first-character class.
+ *   • **no bare `.` / `..`.** Path navigation, not names.
+ *   • **length capped.** `NAME_MAX` is 255 on the common filesystems and the
+ *     suffixes here add to it.
+ *   • **no Windows reserved device names.** `con`, `nul`, `com1` … are devices
+ *     with OR without an extension: `con.json` opens the console, not a file.
+ *
+ * Ids this library mints all satisfy it: `makeRunId()` produces
+ * `run-<epoch ms>-<seq>` and the footprintjs engine produces
+ * `<epoch ms>-<padded counter>`. The assertion is there for the ids a CALLER
+ * states, which is the case that is neither controlled nor rare.
+ *
+ * ## Atomic, so a reader never sees half an archive
+ *
+ * The bytes go to a temporary file in the same directory and are then renamed
+ * into place. `rename` within one filesystem is atomic, so a crash mid-write
+ * leaves a `.tmp` nobody reads rather than a truncated `.json` that parses as
+ * far as it got — a half-written archive is the one failure a bug report cannot
+ * survive, because it looks like evidence.
+ *
+ * Writing the same `runId` twice REPLACES the file, atomically. That is the
+ * intended behaviour and worth stating: the run id is the archive's identity,
+ * so a second envelope for one run is a newer version of one archive (a partial
+ * crash dump later superseded by the finished run), not a second archive.
+ *
+ * Node-only. `node:fs` is reached through `lazyRequire`, the same law the other
+ * filesystem adapters follow, so importing the door costs a browser bundle
+ * nothing and constructing one where there is no filesystem refuses by name.
+ */
+import type { RecordingSink } from './recordingEnvelope.js';
+/**
+ * Raised when a run id cannot safely become a file name.
+ *
+ * Its own class because the fix is never a retry: the caller has to name the
+ * archive something a filesystem can hold one-to-one.
+ */
+export declare class UnsafeRecordingIdError extends Error {
+    readonly code: "ERR_UNSAFE_RECORDING_ID";
+    readonly runId: string;
+    constructor(runId: string, reason: string);
+}
+/**
+ * The mapping under test: one run id → one file name, injectively.
+ *
+ * Exported so the collision battery can drive the mapping directly rather than
+ * inferring it from files on a disk.
+ *
+ * @throws {UnsafeRecordingIdError} for any id outside the safe domain.
+ */
+export declare function recordingFileName(runId: string): string;
+/** Options for {@link fileRecordingSink}. */
+export interface FileRecordingSinkOptions {
+    /** The archive directory. Created if missing, parents included. */
+    readonly directory: string;
+}
+/**
+ * A directory-backed recording sink — one JSON file per run, written atomically.
+ *
+ * @example
+ * ```ts
+ * const recorder = recordRun(agent);
+ * await agent.run({ message: 'hi' });
+ *
+ * await persistRecording(recorder, {
+ *   sink: fileRecordingSink({ directory: './run-archive' }),
+ *   run: { complete: true },
+ * });
+ * // → ./run-archive/run-1787093273110-1.json
+ * ```
+ */
+export declare function fileRecordingSink(options: FileRecordingSinkOptions): RecordingSink;