agentfootprint 9.20.0 → 9.22.0

package/dist/esm/artifacts/capability.d.ts

@@ -0,0 +1,93 @@
+/**
+ * artifacts/capability — `ctx.artifacts`, the scope-bound door a tool gets.
+ *
+ * Shaped exactly like `ctx.credentials`:
+ *   • ALWAYS present — with no store attached every method is a teaching
+ *     refusal naming how to attach one, so a tool can never silently
+ *     optional-chain past a store that is not there;
+ *   • fail-closed — the refusal throws; `ctx.hasArtifacts` is the fact to
+ *     branch on for an intentional degraded mode;
+ *   • scope composed by the FRAMEWORK from the run's identity/session — the
+ *     capability closes over it, so a tool cannot name, widen or replace the
+ *     scope it resolves under. The five verbs here take no scope argument on
+ *     purpose: that argument was already answered by whoever built the
+ *     context.
+ *
+ * Every hop lands on the record AS IT HAPPENS: this module reports facts to a
+ * neutral sink (a plain callback), and the tool-dispatch layer adapts that
+ * sink onto the typed event channel. Neutral so this folder never imports the
+ * event system or the agent — core wires artifacts, never the reverse.
+ */
+import { type ArtifactListOptions, type ArtifactListResult, type ArtifactMeta, type ArtifactOrigin, type ArtifactRecord, type ArtifactRef, type ArtifactScope, type ArtifactStore, type PutArtifactInput, type SweptArtifact } from './types.js';
+/** A tool's `put` — everything the caller owns EXCEPT `origin`, which the
+ *  framework stamps from the run's own facts (never invented, never spoofed). */
+export type ToolArtifactPutInput = Omit<PutArtifactInput, 'origin'>;
+/**
+ * The capability on `ctx.artifacts` — the store's five verbs with the scope
+ * already answered.
+ */
+export interface ToolArtifacts {
+    /** Store a payload under this run's scope; returns the claim ticket. */
+    put(input: ToolArtifactPutInput): Promise<ArtifactMeta>;
+    /** The ticket without the payload. `null` for missing-or-expired. */
+    head(ref: ArtifactRef): Promise<ArtifactMeta | null>;
+    /** Ticket + payload. `null` for missing-or-expired; a digest mismatch throws. */
+    get(ref: ArtifactRef): Promise<ArtifactRecord | null>;
+    /** Remove one artifact this scope holds. */
+    delete(ref: ArtifactRef): Promise<void>;
+    /** Page through this scope's tickets, newest first. */
+    list(options?: ArtifactListOptions): Promise<ArtifactListResult>;
+}
+/** Which door a refusal happened at — the five verbs, plus `'dispatch'`:
+ *  the framework's own resolution of a tool's declared `wants` (and the
+ *  `present` tool's argument checks) BEFORE execute. Not a sixth store verb
+ *  — a dispatch refusal is the tool-calls stage declining to run a tool
+ *  whose declared data could not be delivered. */
+export type ArtifactOp = 'put' | 'head' | 'get' | 'delete' | 'list' | 'dispatch';
+/** Why a verb refused (or answered "no data" on the record). */
+export type ArtifactRefusalReason = 'no-store' | 'missing-or-expired' | 'unknown-parent' | 'digest-mismatch' | 'invalid-input'
+/** A `wants` ref resolved, but to the wrong kind — the wrong parcel for
+ *  this ticket window (dispatch resolution only). */
+ | 'kind-mismatch';
+/** One thing that happened at this door — meta only, never payloads. */
+export type ArtifactEventFact = {
+    readonly type: 'minted';
+    readonly meta: ArtifactMeta;
+} | {
+    readonly type: 'resolved';
+    readonly ref: ArtifactRef;
+    readonly via: 'head' | 'get';
+    readonly kind: string;
+    readonly bytes: number;
+} | {
+    readonly type: 'expired';
+    readonly swept: SweptArtifact;
+} | {
+    readonly type: 'refused';
+    readonly op: ArtifactOp;
+    readonly reason: ArtifactRefusalReason;
+    readonly ref?: ArtifactRef;
+    readonly detail?: string;
+};
+/** Where facts go. The dispatch layer adapts this onto the typed events. */
+export type ArtifactEventSink = (fact: ArtifactEventFact) => void;
+/** What `bindArtifacts` needs beyond the store and the scope. */
+export interface BindArtifactsOptions {
+    /** Stamped onto every mint — the run's own facts, absent when unknown. */
+    readonly origin?: ArtifactOrigin;
+    /** Fact sink. Absent = silent binding (raw store semantics, no record). */
+    readonly onEvent?: ArtifactEventSink;
+}
+/**
+ * Bind a store to one run's scope — the framework's move, made where the
+ * scope is known and a tool cannot reach.
+ */
+export declare function bindArtifacts(store: ArtifactStore, scope: ArtifactScope, options?: BindArtifactsOptions): ToolArtifacts;
+/**
+ * The fail-closed capability used when NO store is attached. Every verb
+ * throws the same teaching refusal — loud, named, and on the record — so
+ * `ctx.artifacts` is never `undefined` and a missing store can never read as
+ * an empty one. Branch on `ctx.hasArtifacts` for an intentional no-store
+ * mode. (The `unconfiguredCredentialProvider` law, verb for verb.)
+ */
+export declare function unconfiguredArtifacts(onEvent?: ArtifactEventSink): ToolArtifacts;

package/dist/esm/artifacts/capability.js

@@ -0,0 +1,126 @@
+/**
+ * artifacts/capability — `ctx.artifacts`, the scope-bound door a tool gets.
+ *
+ * Shaped exactly like `ctx.credentials`:
+ *   • ALWAYS present — with no store attached every method is a teaching
+ *     refusal naming how to attach one, so a tool can never silently
+ *     optional-chain past a store that is not there;
+ *   • fail-closed — the refusal throws; `ctx.hasArtifacts` is the fact to
+ *     branch on for an intentional degraded mode;
+ *   • scope composed by the FRAMEWORK from the run's identity/session — the
+ *     capability closes over it, so a tool cannot name, widen or replace the
+ *     scope it resolves under. The five verbs here take no scope argument on
+ *     purpose: that argument was already answered by whoever built the
+ *     context.
+ *
+ * Every hop lands on the record AS IT HAPPENS: this module reports facts to a
+ * neutral sink (a plain callback), and the tool-dispatch layer adapts that
+ * sink onto the typed event channel. Neutral so this folder never imports the
+ * event system or the agent — core wires artifacts, never the reverse.
+ */
+import { ArtifactIntegrityError, InvalidArtifactError, UnknownParentRefError, } from './types.js';
+/**
+ * Bind a store to one run's scope — the framework's move, made where the
+ * scope is known and a tool cannot reach.
+ */
+export function bindArtifacts(store, scope, options = {}) {
+    const { origin, onEvent } = options;
+    const report = (fact) => {
+        onEvent?.(fact);
+    };
+    return {
+        async put(input) {
+            try {
+                // `origin` is the framework's field: whatever a caller managed to put
+                // there is discarded in favor of the run's own facts.
+                const result = await store.put(scope, {
+                    ...input,
+                    ...(origin !== undefined ? { origin } : {}),
+                });
+                for (const swept of result.swept)
+                    report({ type: 'expired', swept });
+                report({ type: 'minted', meta: result.meta });
+                return result.meta;
+            }
+            catch (err) {
+                if (err instanceof UnknownParentRefError) {
+                    report({ type: 'refused', op: 'put', reason: 'unknown-parent', detail: err.message });
+                }
+                else if (err instanceof InvalidArtifactError) {
+                    report({ type: 'refused', op: 'put', reason: 'invalid-input', detail: err.message });
+                }
+                throw err;
+            }
+        },
+        async head(ref) {
+            const meta = await store.head(scope, ref);
+            if (meta === null) {
+                report({ type: 'refused', op: 'head', reason: 'missing-or-expired', ref });
+                return null;
+            }
+            report({ type: 'resolved', ref: meta.ref, via: 'head', kind: meta.kind, bytes: meta.bytes });
+            return meta;
+        },
+        async get(ref) {
+            let record;
+            try {
+                record = await store.get(scope, ref);
+            }
+            catch (err) {
+                if (err instanceof ArtifactIntegrityError) {
+                    report({
+                        type: 'refused',
+                        op: 'get',
+                        reason: 'digest-mismatch',
+                        ref,
+                        detail: err.message,
+                    });
+                }
+                throw err;
+            }
+            if (record === null) {
+                report({ type: 'refused', op: 'get', reason: 'missing-or-expired', ref });
+                return null;
+            }
+            report({
+                type: 'resolved',
+                ref: record.meta.ref,
+                via: 'get',
+                kind: record.meta.kind,
+                bytes: record.meta.bytes,
+            });
+            return record;
+        },
+        delete(ref) {
+            return store.delete(scope, ref);
+        },
+        list(options) {
+            return store.list(scope, options);
+        },
+    };
+}
+/**
+ * The fail-closed capability used when NO store is attached. Every verb
+ * throws the same teaching refusal — loud, named, and on the record — so
+ * `ctx.artifacts` is never `undefined` and a missing store can never read as
+ * an empty one. Branch on `ctx.hasArtifacts` for an intentional no-store
+ * mode. (The `unconfiguredCredentialProvider` law, verb for verb.)
+ */
+export function unconfiguredArtifacts(onEvent) {
+    const refuse = (op, ref) => {
+        onEvent?.({ type: 'refused', op, reason: 'no-store', ...(ref !== undefined && { ref }) });
+        return Promise.reject(new Error(`No artifact store is attached, but this tool called ctx.artifacts.${op}(...). ` +
+            `Pass \`artifacts\` to Agent.create({ ..., artifacts }) — inMemoryArtifacts() for ` +
+            `an in-process store, fileArtifacts({ directory }) or sqliteArtifacts({ file }) for ` +
+            `one that survives a restart. A tool that intentionally supports running without a ` +
+            `store should branch on \`ctx.hasArtifacts\` instead of catching this.`));
+    };
+    return {
+        put: () => refuse('put'),
+        head: (ref) => refuse('head', ref),
+        get: (ref) => refuse('get', ref),
+        delete: (ref) => refuse('delete', ref),
+        list: () => refuse('list'),
+    };
+}
+//# sourceMappingURL=capability.js.map

package/dist/esm/artifacts/capability.js.map

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

package/dist/esm/artifacts/fileArtifacts.d.ts

@@ -0,0 +1,58 @@
+/**
+ * artifacts/fileArtifacts — the claim-check store in a directory.
+ *
+ * One machine, one directory, nothing to install: each artifact is one JSON
+ * envelope at `<dir>/<tenant>/<principal>/<conversation>/<ref>.json`, so an
+ * incident can be inspected with `ls` and `cat` — a store you cannot read
+ * with the tools already on the box is a store you debug by guessing.
+ *
+ * ── Scope-partitioned paths, structurally traversal-proof ──────────────────
+ * The path is built from two kinds of segment and both are closed:
+ *   • the ref — MINTED (`art_` + base62), and `isArtifactRef` is asserted
+ *     before any ref touches a path anyway, because "cannot happen" is a
+ *     claim, not a defence;
+ *   • the scope tuple — caller strings, so each segment is percent-encoded
+ *     before it becomes a directory name: `..`, `/` and `\` arrive as data
+ *     and land as literals, never as navigation.
+ *
+ * ── What this adapter does NOT know ────────────────────────────────────────
+ * A directory cannot cheaply know which artifact was READ last, so budget
+ * evictions here are oldest-first (by mint time) rather than the in-memory
+ * adapter's least-recently-used — stated here so nobody discovers it as a
+ * surprise under pressure. TTL expiry behaves identically everywhere.
+ *
+ * Node-only (`node:fs` via lazy require, the sqliteSessions law) — importing
+ * the barrel costs a browser bundle nothing; constructing one where there is
+ * no filesystem refuses by name.
+ */
+import { type ArtifactRetention } from './retention.js';
+import { type ArtifactStore } from './types.js';
+/** Options for {@link fileArtifacts}. */
+export interface FileArtifactsOptions {
+    /** The root directory. Created if missing, parents included. */
+    readonly directory: string;
+    /** Retention dials — all optional here: disk is a budget the operator
+     *  already owns. TTL is stamped at mint; budgets sweep oldest-first. */
+    readonly retention?: ArtifactRetention;
+    /** @internal Test seam — the clock. Defaults to `Date.now`. */
+    readonly _now?: () => number;
+}
+/**
+ * Raised when an artifact file EXISTS but this runtime cannot read it — a
+ * different fact from "no artifact", and only one of them is safe to answer
+ * with `null`. (The sqliteSessions law, per file.)
+ */
+export declare class UnreadableArtifactFileError extends Error {
+    readonly code: "ERR_UNREADABLE_ARTIFACT_FILE";
+    readonly file: string;
+    constructor(file: string, detail: string);
+}
+/**
+ * A directory-backed artifact store — durable across restarts, legible to a
+ * human, one file per artifact.
+ *
+ * @example
+ *   const store = fileArtifacts({ directory: './artifacts' });
+ *   const agent = Agent.create({ provider, artifacts: store });
+ */
+export declare function fileArtifacts(options: FileArtifactsOptions): ArtifactStore;

package/dist/esm/artifacts/fileArtifacts.js

@@ -0,0 +1,225 @@
+/**
+ * artifacts/fileArtifacts — the claim-check store in a directory.
+ *
+ * One machine, one directory, nothing to install: each artifact is one JSON
+ * envelope at `<dir>/<tenant>/<principal>/<conversation>/<ref>.json`, so an
+ * incident can be inspected with `ls` and `cat` — a store you cannot read
+ * with the tools already on the box is a store you debug by guessing.
+ *
+ * ── Scope-partitioned paths, structurally traversal-proof ──────────────────
+ * The path is built from two kinds of segment and both are closed:
+ *   • the ref — MINTED (`art_` + base62), and `isArtifactRef` is asserted
+ *     before any ref touches a path anyway, because "cannot happen" is a
+ *     claim, not a defence;
+ *   • the scope tuple — caller strings, so each segment is percent-encoded
+ *     before it becomes a directory name: `..`, `/` and `\` arrive as data
+ *     and land as literals, never as navigation.
+ *
+ * ── What this adapter does NOT know ────────────────────────────────────────
+ * A directory cannot cheaply know which artifact was READ last, so budget
+ * evictions here are oldest-first (by mint time) rather than the in-memory
+ * adapter's least-recently-used — stated here so nobody discovers it as a
+ * surprise under pressure. TTL expiry behaves identically everywhere.
+ *
+ * Node-only (`node:fs` via lazy require, the sqliteSessions law) — importing
+ * the barrel costs a browser bundle nothing; constructing one where there is
+ * no filesystem refuses by name.
+ */
+import { lazyRequire } from '../lib/lazyRequire.js';
+import { prepareArtifact } from './minting.js';
+import { isArtifactRef } from './naming.js';
+import { computeArtifactDigest, decodeArtifactData, encodeArtifactData, } from './payload.js';
+import { assertRetention, planRetention, } from './retention.js';
+import { ArtifactIntegrityError, InvalidArtifactError, } from './types.js';
+/** What one artifact file holds. `format` is bumped only for a change an
+ *  older reader could not survive; a newer number is refused, never half-read. */
+const FILE_FORMAT = 1;
+/**
+ * Raised when an artifact file EXISTS but this runtime cannot read it — a
+ * different fact from "no artifact", and only one of them is safe to answer
+ * with `null`. (The sqliteSessions law, per file.)
+ */
+export class UnreadableArtifactFileError extends Error {
+    code = 'ERR_UNREADABLE_ARTIFACT_FILE';
+    file;
+    constructor(file, detail) {
+        super(`[artifacts] the artifact file at '${file}' cannot be read: ${detail} ` +
+            `An unreadable artifact and a missing one are different facts — this refuses rather ` +
+            `than reporting "no data" over bytes that exist. Move the file aside to release the ref.`);
+        this.name = 'UnreadableArtifactFileError';
+        this.file = file;
+    }
+}
+/**
+ * A directory-backed artifact store — durable across restarts, legible to a
+ * human, one file per artifact.
+ *
+ * @example
+ *   const store = fileArtifacts({ directory: './artifacts' });
+ *   const agent = Agent.create({ provider, artifacts: store });
+ */
+export function fileArtifacts(options) {
+    const { directory, retention } = options;
+    if (typeof directory !== 'string' || directory.trim() === '') {
+        throw new TypeError(`[artifacts] fileArtifacts({ directory: ${JSON.stringify(directory)} }) names no ` +
+            `directory. Give it a path — it will be created if it does not exist.`);
+    }
+    assertRetention('fileArtifacts', retention);
+    const now = options._now ?? Date.now;
+    const fs = lazyRequire('node:fs');
+    const path = lazyRequire('node:path');
+    fs.mkdirSync(directory, { recursive: true });
+    /**
+     * One RAW tuple field → one directory name. Encoded from the FIELD, never
+     * from the joined namespace (a tenant containing '/' must not become two
+     * path segments), and with dots encoded too — `encodeURIComponent` leaves
+     * `.` alone, so a tenant of literally `'..'` would otherwise survive as a
+     * real parent-directory hop. After this, `..`, `/` and `\` are inert
+     * directory NAMES (`%2E%2E`, `%2F`, `%5C`). Empty fields collapse to `_`,
+     * mirroring `identityNamespace`'s stable layout.
+     */
+    const segment = (raw) => encodeURIComponent(raw === undefined || raw === '' ? '_' : raw).replace(/\./g, '%2E');
+    const scopeDir = (scope) => path.join(directory, segment(scope.tenant), segment(scope.principal), segment(scope.conversationId));
+    const fileFor = (scope, ref) => path.join(scopeDir(scope), `${ref}.json`);
+    const readEnvelope = (file) => {
+        let raw;
+        try {
+            raw = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            return undefined; // never written (or already swept) — the null case.
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new UnreadableArtifactFileError(file, 'it is not JSON.');
+        }
+        const candidate = parsed;
+        if (candidate === null ||
+            typeof candidate !== 'object' ||
+            typeof candidate.format !== 'number' ||
+            candidate.meta === undefined ||
+            candidate.payload === undefined) {
+            throw new UnreadableArtifactFileError(file, 'it is not an artifact envelope.');
+        }
+        if (candidate.format > FILE_FORMAT) {
+            throw new UnreadableArtifactFileError(file, `it was written with format ${candidate.format} and this runtime reads format ` +
+                `${FILE_FORMAT}; roll agentfootprint forward rather than half-read it.`);
+        }
+        return candidate;
+    };
+    /** Read a LIVE envelope; sweep the file when the calendar says it is gone. */
+    const liveEnvelope = (scope, ref) => {
+        if (!isArtifactRef(ref))
+            return undefined;
+        const file = fileFor(scope, ref);
+        const envelope = readEnvelope(file);
+        if (envelope === undefined)
+            return undefined;
+        if (envelope.meta.expiresAt !== undefined && envelope.meta.expiresAt <= now()) {
+            fs.rmSync(file, { force: true });
+            return undefined;
+        }
+        return envelope;
+    };
+    /** Every live meta in a scope (expired files swept as they are found). */
+    const scopeMetas = (scope) => {
+        const dir = scopeDir(scope);
+        let names;
+        try {
+            names = fs.readdirSync(dir);
+        }
+        catch {
+            return []; // scope never wrote anything.
+        }
+        const at = now();
+        const metas = [];
+        for (const name of names) {
+            if (!name.endsWith('.json'))
+                continue;
+            const ref = name.slice(0, -'.json'.length);
+            if (!isArtifactRef(ref))
+                continue; // not ours; leave foreign files alone.
+            const envelope = readEnvelope(path.join(dir, name));
+            if (envelope === undefined)
+                continue;
+            if (envelope.meta.expiresAt !== undefined && envelope.meta.expiresAt <= at) {
+                fs.rmSync(path.join(dir, name), { force: true });
+                continue;
+            }
+            metas.push(envelope.meta);
+        }
+        return metas;
+    };
+    return {
+        async put(scope, input) {
+            const at = now();
+            const { meta } = await prepareArtifact(input, (parent) => liveEnvelope(scope, parent) !== undefined, retention, at);
+            const rows = scopeMetas(scope).map((held) => ({
+                ref: held.ref,
+                kind: held.kind,
+                bytes: held.bytes,
+                ...(held.expiresAt !== undefined && { expiresAt: held.expiresAt }),
+                // A directory has no cheap read-recency; oldest-first is the stated law.
+                lastAccessedAt: held.createdAt,
+            }));
+            const plan = planRetention(rows, meta.bytes, retention, at);
+            if (plan.refusal !== undefined)
+                throw new InvalidArtifactError(plan.refusal);
+            for (const swept of plan.swept)
+                fs.rmSync(fileFor(scope, swept.ref), { force: true });
+            const envelope = {
+                format: FILE_FORMAT,
+                meta,
+                payload: encodeArtifactData(input.data),
+            };
+            fs.mkdirSync(scopeDir(scope), { recursive: true });
+            fs.writeFileSync(fileFor(scope, meta.ref), JSON.stringify(envelope));
+            return { meta, swept: plan.swept };
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async head(scope, ref) {
+            return liveEnvelope(scope, ref)?.meta ?? null;
+        },
+        async get(scope, ref) {
+            const envelope = liveEnvelope(scope, ref);
+            if (envelope === undefined)
+                return null;
+            const data = decodeArtifactData(envelope.payload);
+            if (envelope.meta.digest !== undefined) {
+                const actual = await computeArtifactDigest(data);
+                if (actual !== envelope.meta.digest) {
+                    throw new ArtifactIntegrityError(envelope.meta.ref, envelope.meta.digest, actual);
+                }
+            }
+            return { meta: envelope.meta, data };
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async delete(scope, ref) {
+            if (!isArtifactRef(ref))
+                return;
+            fs.rmSync(fileFor(scope, ref), { force: true });
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async list(scope, listOptions) {
+            const all = scopeMetas(scope).sort((a, b) => b.createdAt - a.createdAt || (a.ref < b.ref ? -1 : 1));
+            const offset = decodeCursor(listOptions?.cursor);
+            const limit = Math.max(1, Math.floor(listOptions?.limit ?? 50));
+            const page = all.slice(offset, offset + limit);
+            const nextOffset = offset + page.length;
+            return {
+                artifacts: page,
+                ...(nextOffset < all.length && { cursor: String(nextOffset) }),
+            };
+        },
+    };
+}
+function decodeCursor(cursor) {
+    if (cursor === undefined)
+        return 0;
+    const parsed = Number(cursor);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 0;
+}
+//# sourceMappingURL=fileArtifacts.js.map

package/dist/esm/artifacts/fileArtifacts.js.map

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

package/dist/esm/artifacts/inMemoryArtifacts.d.ts

@@ -0,0 +1,54 @@
+/**
+ * artifacts/inMemoryArtifacts — the claim-check store in a Map.
+ *
+ * For tests, local development, and single-process agents whose artifacts may
+ * die with the process. Exactly as durable as the process — which is the
+ * point of the port: swap the one argument for `fileArtifacts` or
+ * `sqliteArtifacts` and nothing else changes.
+ *
+ * ── Bounded, and counting its drops (the innerRunRecords laws) ─────────────
+ * A retained payload is retained memory, and an agent minting a dataset per
+ * turn for a week would otherwise pin every one of them — the failure would
+ * look like a leak rather than like a feature. So this adapter is ALWAYS
+ * bounded: it has a default byte budget and row budget per scope, an explicit
+ * retention only replaces those dials, and there is deliberately no spelling
+ * for "unbounded" here — a memory store without a ceiling is a leak wearing
+ * configuration. When the budget forces an eviction the least-recently-USED
+ * artifact leaves first (reading refreshes recency, so the dataset a chart is
+ * actively rendered from is not the next casualty), every eviction is
+ * reported by the `put` that caused it, and `dropped` COUNTS them — "we kept
+ * the last 200 of 340" is an answer a debugging session can act on; a
+ * silently missing ref is not.
+ */
+import { type ArtifactRetention } from './retention.js';
+import { type ArtifactStore } from './types.js';
+/** The always-on bounds. Override dials via `retention`; there is no "off". */
+export declare const DEFAULT_IN_MEMORY_ARTIFACT_RETENTION: Required<Pick<ArtifactRetention, 'maxBytesPerScope' | 'maxCountPerScope'>>;
+/** Options for {@link inMemoryArtifacts}. */
+export interface InMemoryArtifactsOptions {
+    /**
+     * Retention dials. Merged OVER the defaults — name a dial to change it;
+     * the byte and row budgets always exist (see the header for why).
+     */
+    readonly retention?: ArtifactRetention;
+    /** @internal Test seam — the clock. Defaults to `Date.now`. */
+    readonly _now?: () => number;
+}
+/** The in-memory store, plus the accounting a bounded store owes its owner. */
+export interface InMemoryArtifacts extends ArtifactStore {
+    /** Artifacts evicted by the byte/row budgets since construction (TTL expiry
+     *  is the calendar doing its job and is not counted here). Non-zero means
+     *  "resolve sooner, or raise the budget". */
+    readonly dropped: number;
+    /** The dials in force, defaults included. */
+    readonly retention: ArtifactRetention;
+}
+/**
+ * A bounded, drop-counting, per-scope-isolated artifact store in process
+ * memory.
+ *
+ * @example
+ *   const store = inMemoryArtifacts({ retention: { ttlMs: 15 * 60_000 } });
+ *   const agent = Agent.create({ provider, artifacts: store });
+ */
+export declare function inMemoryArtifacts(options?: InMemoryArtifactsOptions): InMemoryArtifacts;