agentfootprint 9.24.0 → 9.26.0

package/dist/types/artifacts/gcsArtifacts.d.ts

@@ -0,0 +1,143 @@
+/**
+ * artifacts/gcsArtifacts — the claim-check store in a Cloud Storage bucket.
+ *
+ * The same five verbs, the same laws, a different vendor's client. Read
+ * `objectStore.ts` first for the laws both object adapters obey; read
+ * `s3Artifacts.ts` beside this one to see what is genuinely per-vendor rather
+ * than per-implementation. Three things really are different here, and each
+ * one changes what an operator pays:
+ *
+ *   1. **A listing carries the metadata.** `bucket.getFiles()` hands back File
+ *      objects with their metadata already populated — creation time, size AND
+ *      the custom entry holding the ticket. So `list()` is ONE call per page
+ *      and needs no per-row read, where the S3 adapter must HEAD each row it
+ *      returns. Same port, same promise, cheaper here; said out loud because
+ *      "the cloud adapters behave identically" is true of the CONTRACT and not
+ *      of the bill.
+ *   2. **A bigger metadata budget.** Custom metadata is capped at 8 KiB
+ *      (keys and values together), against 2 KB on the other column. The
+ *      ticket is checked against it at put and refused by name, so the cap is
+ *      a stated limit and not a surprise from the service.
+ *   3. **The client has no command objects.** Methods hang off a chain —
+ *      `storage.bucket(b).file(k).save(...)` — which is why this column's pin
+ *      test asserts a METHOD CHAIN rather than a set of command names.
+ *
+ * ── The object key ──────────────────────────────────────────────────────────
+ * `[<prefix>/]<tenant>/<principal>/<conversation>/<ref>`, scope-partitioned by
+ * `scopePath.ts` — the same percent-encoding law as the directory adapter, so
+ * a tenant of literally `'..'` is a NAME here too. A ref alone opens nothing:
+ * a wrong scope computes a different object name, the service answers 404, and
+ * the caller reads `null`.
+ *
+ * ── What a 404 is allowed to mean here ──────────────────────────────────────
+ * A missing object and a missing bucket look the SAME on this column
+ * (`code: 404`, reason `notFound`, differing only in prose this adapter will
+ * not parse). So the split is made by the call instead: only a read of one
+ * named object may read a 404 as "not there". A 404 from a save or a listing
+ * is not an answer to anything the caller asked — it goes through the
+ * sanitizer, because nothing downstream converts it and the client's own text
+ * for it carries the object name.
+ *
+ * ── Retention, and the operator's bulk tool ─────────────────────────────────
+ * `ttlMs` stamps `expiresAt` AT MINT (stated, never sprung); expiry is
+ * enforced on READ and the expired object is deleted on the way past; budgets
+ * evict oldest-first (an object store has no cheap read-recency). A put SCANS
+ * the scope only when a byte/count budget is configured — with no budget there
+ * is nothing to plan, and a put stays a single upload.
+ *
+ * Reclaiming what nobody reads again is **Object Lifecycle Management**, the
+ * operator's bulk tool. This adapter does not create rules: a lifecycle rule
+ * is a cost and compliance decision that belongs to your infrastructure.
+ * Align it like this:
+ *
+ * ```jsonc
+ * // Delete objects 7 days after creation. Keep the rule LONGER than the
+ * // store's ttlMs, never shorter: `expiresAt` is the promise printed on the
+ * // ticket, and a lifecycle rule that deletes first makes a live ticket
+ * // resolve to null BEFORE the time it stated. Longer, and lifecycle is what
+ * // it should be — the backstop for what the store's own sweep never
+ * // revisited.
+ * { "lifecycle": { "rule": [
+ *     { "action": { "type": "Delete" },
+ *       "condition": { "age": 7, "matchesPrefix": ["artifacts/"] } }
+ * ]}}
+ * ```
+ *
+ * ── Lazy peer dependency ────────────────────────────────────────────────────
+ * `@google-cloud/storage` is an OPTIONAL peer dependency, required at
+ * CONSTRUCTION (the sqliteSessions law): importing the barrel costs a browser
+ * bundle nothing, and a missing install refuses where the config was written.
+ * Pass `storage` to share the client your app already built.
+ *
+ * ── Status ──────────────────────────────────────────────────────────────────
+ * Contract-shaped and tested; awaiting field use. The method chain it calls is
+ * pinned against the really-installed package by
+ * `test/adapters/google/google-surface-pin.test.ts`; the behavior is proved
+ * against an emulation double that speaks the same chain. No live call has
+ * been made from this repository.
+ */
+/// <reference types="node" />
+import { type ArtifactRetention } from './retention.js';
+import { type ArtifactStore } from './types.js';
+/** One object's metadata, as this adapter reads it. */
+export interface GcsFileMetadataLike {
+    readonly size?: string | number;
+    readonly timeCreated?: string;
+    readonly contentType?: string;
+    /** The custom entries — where the ticket rides. */
+    readonly metadata?: Record<string, unknown>;
+}
+/** One object handle, as this adapter calls it. */
+export interface GcsFileLike {
+    /** Populated by a listing; a File built by `bucket.file()` may not have it. */
+    readonly name?: string;
+    readonly metadata?: GcsFileMetadataLike;
+    save(data: Uint8Array | string, options?: unknown): Promise<unknown>;
+    download(options?: unknown): Promise<[Uint8Array]>;
+    getMetadata(options?: unknown): Promise<[GcsFileMetadataLike, unknown?]>;
+    delete(options?: unknown): Promise<unknown>;
+    createReadStream(options?: unknown): NodeJS.ReadableStream;
+    createWriteStream(options?: unknown): NodeJS.WritableStream;
+}
+/** One bucket handle, as this adapter calls it. */
+export interface GcsBucketLike {
+    file(name: string): GcsFileLike;
+    getFiles(query?: unknown): Promise<[GcsFileLike[], unknown?, unknown?]>;
+}
+/** The client, as this adapter calls it. */
+export interface GcsStorageLike {
+    bucket(name: string): GcsBucketLike;
+}
+/** The module shape this adapter loads. */
+export interface GcsSdkModule {
+    readonly Storage?: new (config: Record<string, unknown>) => GcsStorageLike;
+}
+/** Options for {@link gcsArtifacts}. */
+export interface GcsArtifactsOptions {
+    /** The bucket. It must already exist — this library never creates one. */
+    readonly bucket: string;
+    /** Object-name prefix inside the bucket, so a bucket can be shared. */
+    readonly prefix?: string;
+    /** Project id for the client this factory builds. Ignored when `storage` is
+     *  passed — that client's configuration is yours. */
+    readonly projectId?: string;
+    /** Your own pre-built client; configuration and credentials stay yours. */
+    readonly storage?: GcsStorageLike;
+    /** Retention dials. Budgets evict OLDEST-first (no cheap read-recency). */
+    readonly retention?: ArtifactRetention;
+    /** @internal Test seam — the SDK module, injected. */
+    readonly _sdk?: GcsSdkModule;
+    /** @internal Test seam — a client injected past the SDK entirely. */
+    readonly _storage?: GcsStorageLike;
+    /** @internal Test seam — the clock. Defaults to `Date.now`. */
+    readonly _now?: () => number;
+}
+/**
+ * An artifact store in a Cloud Storage bucket.
+ *
+ * @example
+ *   const store = gcsArtifacts({ bucket: 'my-agent-artifacts', prefix: 'artifacts' });
+ *   const agent = Agent.create({ provider, artifacts: store });
+ */
+export declare function gcsArtifacts(options: GcsArtifactsOptions): ArtifactStore;
+//# sourceMappingURL=gcsArtifacts.d.ts.map

package/dist/types/artifacts/gcsArtifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcsArtifacts.d.ts","sourceRoot":"","sources":["../../../src/artifacts/gcsArtifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;;AAwBH,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAUL,KAAK,aAAa,EAGnB,MAAM,YAAY,CAAC;AAapB,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IACxC,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IACnD,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACzE,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,gBAAgB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC;IAC3D,iBAAiB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC;CAC7D;AAED,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACzE;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC;CACrC;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,cAAc,CAAC;CAC5E;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;yDACqD;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IACvC,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,MAAM,CAAC;CAC9B;AAsDD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAgRxE"}

package/dist/types/artifacts/index.d.ts

@@ -9,14 +9,18 @@
  * (`present`), and the placement threshold (`placement`). See README.md in
  * this folder for the one-job map and the import direction.
  */
-export { ArtifactIntegrityError, InvalidArtifactError, UnknownParentRefError, type ArtifactListOptions, type ArtifactListResult, type ArtifactMeta, type ArtifactOrigin, type ArtifactPutResult, type ArtifactRecord, type ArtifactRef, type ArtifactScope, type ArtifactStore, type ArtifactSweepReason, type PutArtifactInput, type SweptArtifact, } from './types.js';
+export { ArtifactIntegrityError, InvalidArtifactError, UnknownParentRefError, type ArtifactListOptions, type ArtifactListResult, type ArtifactMeta, type ArtifactOrigin, type ArtifactPutResult, type ArtifactRecord, type ArtifactRef, type ArtifactScope, type ArtifactStore, type ArtifactStreamPutInput, type ArtifactStreamRecord, type ArtifactSweepReason, type PutArtifactInput, type SweptArtifact, } from './types.js';
 export { ARTIFACT_REF_PREFIX, isArtifactRef, mintArtifactRef } from './naming.js';
 export { type ArtifactRetention } from './retention.js';
 export { inMemoryArtifacts, DEFAULT_IN_MEMORY_ARTIFACT_RETENTION, type InMemoryArtifacts, type InMemoryArtifactsOptions, } from './inMemoryArtifacts.js';
 export { fileArtifacts, UnreadableArtifactFileError, type FileArtifactsOptions, } from './fileArtifacts.js';
 export { sqliteArtifacts, UnreadableArtifactStoreError, type SqliteArtifacts, type SqliteArtifactsOptions, } from './sqliteArtifacts.js';
+export { s3Artifacts, type S3ArtifactsOptions } from './s3Artifacts.js';
+export { gcsArtifacts, type GcsArtifactsOptions } from './gcsArtifacts.js';
+export { assertStreamBytes, bytesAsStream, canGetArtifactStream, canPutArtifactStream, canStreamArtifacts, collectStream, type GetStreamingArtifactStore, type PutStreamingArtifactStore, type StreamingArtifactStore, } from './streaming.js';
 export { bindArtifacts, unconfiguredArtifacts, type ArtifactEventFact, type ArtifactEventSink, type ArtifactOp, type ArtifactRefusalReason, type BindArtifactsOptions, type ToolArtifactPutInput, type ToolArtifacts, } from './capability.js';
 export { assertToolWants, resolveToolWants, wantsNeedsStoreRefusal, type ToolWants, type WantsRefusal, type WantsResolution, } from './wants.js';
 export { PRESENT_TOOL_NAME, presentArtifact, type PresentOutcome, type PresentSnapshot, type PresentedResult, } from './present.js';
+export { recordingPutInput, RECORDING_ARTIFACT_KIND, RECORDING_MEDIA_TYPE, UnserializableRecordingError, type RecordingMintFacts, } from './recordingArtifact.js';
 export { assertArtifactPlacement, isPlacedToolResult, placedResultKind, placedToolResult, type ArtifactPlacement, type PlacedToolResult, } from './placement.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/artifacts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,oCAAoC,EACpC,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,EACb,2BAA2B,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,oCAAoC,EACpC,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,EACb,2BAA2B,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,4BAA4B,EAC5B,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/types/artifacts/objectStore.d.ts

@@ -0,0 +1,167 @@
+/**
+ * artifacts/objectStore — the half every REMOTE OBJECT adapter shares.
+ *
+ * Two adapters put artifacts in somebody else's bucket. They speak different
+ * SDKs and dispatch different operations, and that is exactly where a vendor
+ * belongs — but the laws they follow must not fork, so the laws live here:
+ *
+ *   1. **The payload is the object body, and it is the CANONICAL BYTES** —
+ *      the same bytes `meta.bytes` counts and a digest covers. Not a JSON
+ *      envelope wrapping base64: a stored report should be downloadable with
+ *      the vendor's own console and be the report. That choice is also what
+ *      makes `getStream` possible at all — a body you have to parse is a body
+ *      you cannot stream.
+ *   2. **The meta rides as ONE object-metadata entry** ({@link ARTIFACT_META_KEY}),
+ *      an ASCII-safe JSON envelope. One key, one truth: a "helpful" second
+ *      copy of `kind` in a sibling field is a second thing that can disagree.
+ *      ASCII because user metadata travels as an HTTP header on at least one
+ *      of these services — a label with an em-dash in it must not be
+ *      mangled at the transport — and JSON-with-escapes rather than base64
+ *      because an operator reading the console should be able to SEE what the
+ *      ticket says.
+ *   3. **The metadata budget is checked at put and REFUSED by name.** Both
+ *      services cap user metadata (the caps differ; each adapter states its
+ *      own). A refusal that names the field to shorten beats a vendor's
+ *      "MetadataTooLarge" at document 400, and beats silent truncation
+ *      always.
+ *   4. **Missing means null; unreadable means an error.** A 404 is the
+ *      port's deliberate "no data" ambiguity — but only when the call ASKED
+ *      ABOUT ONE OBJECT. A write and a listing do not ask that question, so a
+ *      404 from one of them is the service saying something else entirely (the
+ *      bucket does not exist, the endpoint is wrong); nobody downstream turns
+ *      it into `null`, so letting it past the sanitizer hands the caller the
+ *      SDK's own text — which contains the object key. That is what
+ *      {@link NotFoundMeaning} makes each call site declare, and why the
+ *      default is the safe one. Anything else — denied, throttled, a network
+ *      failure — is NOT "no data" either, and answering `null` for it would
+ *      report an empty scope over objects that exist. Each adapter maps its
+ *      own SDK's missing-object shape; everything else raises through
+ *      {@link objectSdkFailure}.
+ *   5. **Listings order by the SERVICE's own creation time**, which comes back
+ *      free on a listing, and page by offset over that sorted list. The port
+ *      promises newest-first ACROSS pages; a bucket's key order is
+ *      lexicographic, so a cursor that was the service's own continuation
+ *      token would page in the wrong order and call it paging.
+ *
+ * Nothing in this file imports an SDK, names a vendor, or knows a wire
+ * format. It is the part of an object adapter that can be unit-tested with
+ * nothing but strings.
+ */
+import type { PayloadShape } from './payload.js';
+import { type ArtifactListOptions, type ArtifactListResult, type ArtifactMeta } from './types.js';
+/** The single object-metadata key that carries the ticket. */
+export declare const ARTIFACT_META_KEY = "af-artifact";
+/**
+ * Encode a ticket for the object's metadata, refusing one that will not fit.
+ *
+ * @param meta    the minted ticket.
+ * @param shape   how the payload must be rebuilt from the body's bytes.
+ * @param budget  the service's user-metadata cap, in bytes.
+ * @param adapter the factory name, for the refusal.
+ * @throws InvalidArtifactError when the encoded ticket exceeds the budget —
+ *         naming the fields that are big enough to be the reason.
+ */
+export declare function encodeArtifactMetaValue(meta: ArtifactMeta, shape: PayloadShape, budget: number, adapter: string): string;
+/**
+ * Read a ticket back off an object's metadata.
+ *
+ * `undefined` for anything this runtime must not interpret: no entry (not
+ * ours — a foreign object in a shared bucket is left alone), unparseable, a
+ * newer envelope version, or a ref that is not a minted ref. Refusing to
+ * interpret is the point: a half-read ticket would be a confident description
+ * of the wrong thing.
+ */
+export declare function decodeArtifactMetaValue(value: unknown): {
+    readonly meta: ArtifactMeta;
+    readonly shape: PayloadShape;
+} | undefined;
+/** Case-insensitive lookup in a metadata bag. At least one of these services
+ *  lower-cases user-metadata keys in transit, so the key written and the key
+ *  read back are not guaranteed to be the same string. */
+export declare function readMetadataEntry(bag: Record<string, unknown> | undefined, key: string): unknown;
+/** Has the calendar passed this ticket? The one expiry predicate both object
+ *  adapters use, so "expired" cannot mean two things. */
+export declare function isExpiredMeta(meta: ArtifactMeta, now: number): boolean;
+/**
+ * Re-raise a failed SDK call WITHOUT its text (the `sdkFailure` law, applied
+ * to object storage).
+ *
+ * A cloud SDK reports transport and validation failures by echoing request
+ * detail into the message: the bucket, the KEY — which here contains the
+ * tenant, the principal and the conversation id — and sometimes a signed URL
+ * or a header the request carried. This library then hands that string to the
+ * LLM as a tool result, puts it on the commit log, and ships it to every sink
+ * attached. One echo and the scope tuple is in the conversation.
+ *
+ * So the text does not come through. What does is the part that is both safe
+ * and actionable: which operation failed, the exception's NAME, and the HTTP
+ * status. The original is deliberately NOT attached as `cause` — a cause
+ * travels into every serializer that walks own properties, which would undo
+ * all of this in one `JSON.stringify`.
+ */
+export declare function objectSdkFailure(adapter: string, operation: string, err: unknown): Error;
+/**
+ * What a "not found" from ONE call is allowed to mean.
+ *
+ * The distinction is not academic: it decides whether an SDK error object
+ * leaves this library intact.
+ *
+ * • `'missing-object'` — the call named one object and asked whether it is
+ *   there. Not-found is the port's deliberate "no data", so the SDK's own
+ *   error travels back to the CALL SITE, which immediately converts it to
+ *   `null`/`undefined`. It never leaves the adapter, so its text never reaches
+ *   an event, a log, or a model.
+ *
+ * • `'not-an-answer'` — the call asked no such question (it wrote, or it
+ *   listed). A not-found here means something the caller did not ask about is
+ *   wrong — most often that the bucket itself is not there — and NOTHING
+ *   downstream is waiting to convert it. It goes through
+ *   {@link objectSdkFailure} like every other failure.
+ *
+ * This is the DEFAULT for exactly that reason: a call site that says nothing
+ * gets the sanitizer. Leaking has to be typed out on purpose, next to the
+ * `catch` that proves the error is caught.
+ */
+export type NotFoundMeaning = 'missing-object' | 'not-an-answer';
+/**
+ * The one gate every object adapter runs its SDK failures through.
+ *
+ * Returns what to throw — the sanitized error for anything the caller is not
+ * standing by to interpret, the original ONLY for a genuine missing object at
+ * a call site that declared it asks about one, and our own refusals verbatim
+ * (an {@link InvalidArtifactError} is this library's sentence, already written
+ * for a human, and re-wrapping it would replace a teaching refusal with a
+ * transport complaint).
+ *
+ * Built once per adapter so the vendor's not-found detection is bound in one
+ * place: two call sites in the same adapter cannot end up disagreeing about
+ * what "missing" looks like.
+ *
+ * @param adapter        the factory name, for the message.
+ * @param isMissingObject the adapter's own reading of its SDK's
+ *                       "no such object" — the one genuinely per-vendor part.
+ */
+export declare function objectFailurePolicy(adapter: string, isMissingObject: (err: unknown) => boolean): (operation: string, err: unknown, meaning: NotFoundMeaning) => unknown;
+/** One row of a scope listing, before the tickets are paged. */
+export interface ObjectListingRow {
+    readonly meta: ArtifactMeta;
+    /** The service's own creation time for the object (ms). The sort key —
+     *  see law 5 in the module header. */
+    readonly serviceCreatedAt: number;
+}
+/**
+ * The port's paging law over a scope's rows: newest first, offset cursor.
+ *
+ * Sorted by the SERVICE's creation time (falling back to the ticket's own
+ * `createdAt` when a listing did not carry one), ties broken by ref so two
+ * objects written in the same millisecond still page deterministically.
+ */
+export declare function pageObjectListing(rows: readonly ObjectListingRow[], options: ArtifactListOptions | undefined): ArtifactListResult;
+/** The offset a cursor names. Total: a cursor this store did not mint reads
+ *  as "start at the beginning" rather than as an error — a caller cannot
+ *  learn anything about another scope by guessing one. */
+export declare function decodeOffsetCursor(cursor: string | undefined): number;
+/** Validate a bucket name option at construction — the same shape of refusal
+ *  every adapter here gives for a missing required option. */
+export declare function assertBucketOption(adapter: string, option: string, value: unknown): string;
+//# sourceMappingURL=objectStore.d.ts.map

package/dist/types/artifacts/objectStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectStore.d.ts","sourceRoot":"","sources":["../../../src/artifacts/objectStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAEpB,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAyB/C;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAwBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,GACb;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAAG,SAAS,CAgB3E;AAED;;0DAE0D;AAC1D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAShG;AAED;yDACyD;AACzD,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,KAAK,CAwBxF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAEjE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,GACzC,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAMxE;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;0CACsC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,gBAAgB,EAAE,EACjC,OAAO,EAAE,mBAAmB,GAAG,SAAS,GACvC,kBAAkB,CAYpB;AAED;;0DAE0D;AAC1D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIrE;AAED;8DAC8D;AAC9D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAU1F"}

package/dist/types/artifacts/payload.d.ts

@@ -29,16 +29,48 @@
 export declare function canonicalPayloadBytes(data: unknown): Uint8Array;
 /** Payload size in bytes — UTF-8 for text/JSON, byteLength for binary. */
 export declare function measureArtifactBytes(data: unknown): number;
+/**
+ * Which of the three payload shapes a value is. The durable envelope carries
+ * it, and so does an object store's metadata — the canonical bytes alone
+ * cannot say whether `"7"` was the string `'7'` or the JSON number `7`, and a
+ * store that guessed would hand back a different value than it was given.
+ */
+export type PayloadShape = 'text' | 'binary' | 'json';
+/** The shape a payload will be stored under. Total: everything that is not a
+ *  string or a `Uint8Array` rides as JSON (and is refused at measure/encode if
+ *  JSON cannot carry it). */
+export declare function payloadShapeOf(data: unknown): PayloadShape;
+/**
+ * Rebuild a payload from its CANONICAL BYTES and its shape — the read half of
+ * `canonicalPayloadBytes`, for stores that hold the bytes themselves (an
+ * object body, a stream) rather than the text envelope.
+ *
+ * Round-trip law: `decodeCanonicalPayload(payloadShapeOf(x),
+ * canonicalPayloadBytes(x))` equals `x` for every payload this library
+ * accepts — which is what lets `bytes`, the digest, and the stored object all
+ * be the same bytes in every adapter.
+ */
+export declare function decodeCanonicalPayload(shape: PayloadShape, bytes: Uint8Array): unknown;
 /** `sha-256:<hex>` over the canonical bytes. */
 export declare function computeArtifactDigest(data: unknown): Promise<string>;
-/** How a payload rides a file or a SQL TEXT column. One shape, two adapters. */
+/** How a payload rides a file or a SQL TEXT column. One shape, two adapters.
+ *
+ *  `'external'` (9.25.0) is the STREAMED case and exists only where a store
+ *  can hold bytes beside the envelope: the payload is not in `value` at all —
+ *  `value` names the sibling file that holds it, and the artifact reads back
+ *  as binary. Only `fileArtifacts` writes it; `decodeArtifactData` refuses it
+ *  by name, because a decoder that cannot reach the bytes must not pretend. */
 export interface EncodedPayload {
-    readonly shape: 'text' | 'binary' | 'json';
-    /** `text`: the string. `binary`: base64. `json`: the JSON serialization. */
+    readonly shape: PayloadShape | 'external';
+    /** `text`: the string. `binary`: base64. `json`: the JSON serialization.
+     *  `external`: the name of the sibling file holding the raw bytes. */
     readonly value: string;
 }
 /** Encode for durable storage. Validates exactly as `measure` does. */
 export declare function encodeArtifactData(data: unknown): EncodedPayload;
-/** Decode what {@link encodeArtifactData} wrote. Total over its own output. */
+/** Decode what {@link encodeArtifactData} wrote. Total over its own output;
+ *  an `'external'` envelope is the one thing it refuses, by name — the bytes
+ *  live beside the envelope and only the adapter that wrote them can reach
+ *  them. */
 export declare function decodeArtifactData(encoded: EncodedPayload): unknown;
 //# sourceMappingURL=payload.d.ts.map

package/dist/types/artifacts/payload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../src/artifacts/payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAuB/D;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAE1D;AAED,gDAAgD;AAChD,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAS1E;AAID,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAKhE;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CASnE"}
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../src/artifacts/payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAuB/D;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAE1D;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtD;;6BAE6B;AAC7B,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAI1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAStF;AAED,gDAAgD;AAChD,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAS1E;AAID;;;;;;+EAM+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,CAAC;IAC1C;0EACsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAKhE;AAED;;;YAGY;AACZ,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAenE"}

package/dist/types/artifacts/recordingArtifact.d.ts

@@ -0,0 +1,77 @@
+/**
+ * artifacts/recordingArtifact — a finished run, checked into the store like any
+ * other payload.
+ *
+ * `recordRun` has produced `{ snapshot, events, structure }` since 8.x and the
+ * lens family has consumed exactly that shape since. What nobody shipped was
+ * the boring half in between: WHERE a completed run's recording goes so a
+ * screen can ask for it later. Every deployment that wanted the Lens over the
+ * wire wrote the same twenty lines — record the run, serialize it, put it
+ * somewhere with a key, hand the key to the frontend — and each one wrote a
+ * slightly different, slightly wrong version of retention and scoping.
+ *
+ * All four of those problems already have an answer in this package: the
+ * artifact store IS a keyed payload store with scope isolation, retention and
+ * a read-only wire. So a recording is simply an artifact of kind
+ * `'recording/run'`, and the wire ops that already redeem claim tickets serve
+ * it with **zero new operations** — `{ op: 'artifact-get', ref }` returns the
+ * recording, and the frontend does what it always did with the bytes.
+ *
+ * ── Why the payload is TEXT and not an object ───────────────────────────────
+ * The recording is minted as its JSON text — the same bytes
+ * `JSON.stringify(recorder.toRecording())` produces, which is precisely what
+ * `observeRecording(JSON.parse(text))` consumes on the viewer side. Two
+ * reasons, and both are about not lying:
+ *
+ *   • `recordRun` states that `snapshot` and `structure` are the runner's OWN
+ *     objects, held by reference. An in-process store handed those would keep
+ *     a live view into a finished run's state — the artifact would silently
+ *     change if anything touched it. Serializing detaches it, once, here.
+ *   • A recording that cannot be serialized cannot be delivered over any wire
+ *     either, so failing at the mint is failing at the honest moment rather
+ *     than at whatever reads it next.
+ */
+import type { PutArtifactInput } from './types.js';
+/** The consumer vocabulary a run recording is stored under. One kind, exact
+ *  match — the same rule every `wants` declaration is judged by. */
+export declare const RECORDING_ARTIFACT_KIND = "recording/run";
+/** The media type a recording is minted with. */
+export declare const RECORDING_MEDIA_TYPE = "application/json";
+/** What a recording mint needs to know beyond the recording itself. */
+export interface RecordingMintFacts {
+    /** The run this recording is OF — stamped on `origin.runId`, which is the
+     *  join back to the trace. */
+    readonly runId?: string;
+    /**
+     * The operator's label, when they set one.
+     *
+     * Used VERBATIM when present: an operator who named their recordings meant
+     * that name, and a library that decorated it would be overruling them. The
+     * consequence is worth stating — a static label repeats on every run, and
+     * what distinguishes two recordings is the ref and `origin.runId`, never the
+     * label. With no label the composed one names the run, which is the most
+     * useful honest sentence available at mint time.
+     */
+    readonly label?: string;
+}
+/**
+ * Raised when a recording could not be turned into bytes.
+ *
+ * Its own class because the CALLER's answer differs from every other mint
+ * failure: a full store is retryable and a cyclic snapshot is not.
+ */
+export declare class UnserializableRecordingError extends Error {
+    readonly code: "ERR_UNSERIALIZABLE_RECORDING";
+    constructor(detail: string);
+}
+/**
+ * Turn one finished recording into the `put` input that stores it.
+ *
+ * Pure: no store, no events, no agent. The caller owns WHEN this happens (after
+ * the answer is composed) and what to do when it fails.
+ *
+ * @throws UnserializableRecordingError when the recording cannot be
+ *   JSON-serialized — a cyclic object in a snapshot, most likely.
+ */
+export declare function recordingPutInput(recording: unknown, facts?: RecordingMintFacts): PutArtifactInput;
+//# sourceMappingURL=recordingArtifact.d.ts.map

package/dist/types/artifacts/recordingArtifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordingArtifact.d.ts","sourceRoot":"","sources":["../../../src/artifacts/recordingArtifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;oEACoE;AACpE,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AAEvD,iDAAiD;AACjD,eAAO,MAAM,oBAAoB,qBAAqB,CAAC;AAEvD,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC;kCAC8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,iCAA2C;gBAE5C,MAAM,EAAE,MAAM;CAS3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,OAAO,EAClB,KAAK,GAAE,kBAAuB,GAC7B,gBAAgB,CAiBlB"}