agentfootprint 9.23.0 → 9.25.0

package/dist/artifacts/objectStore.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertBucketOption = exports.decodeOffsetCursor = exports.pageObjectListing = exports.objectFailurePolicy = exports.objectSdkFailure = exports.isExpiredMeta = exports.readMetadataEntry = exports.decodeArtifactMetaValue = exports.encodeArtifactMetaValue = exports.ARTIFACT_META_KEY = void 0;
+const naming_js_1 = require("./naming.js");
+const types_js_1 = require("./types.js");
+/** The single object-metadata key that carries the ticket. */
+exports.ARTIFACT_META_KEY = 'af-artifact';
+/** Envelope version. Bumped only for a change an older reader could not
+ *  survive; a newer number is refused, never half-read. */
+const META_FORMAT = 1;
+/**
+ * Every non-ASCII character as a `\uXXXX` escape, so the JSON is pure ASCII
+ * and survives a transport that only promises US-ASCII. `JSON.parse` reverses
+ * it exactly — the escape is part of JSON, not a private encoding.
+ */
+function asciiJson(value) {
+    return JSON.stringify(value).replace(/[\u007f-\uffff]/g, (char) => {
+        const code = char.charCodeAt(0).toString(16).padStart(4, '0');
+        return `\\u${code}`;
+    });
+}
+/**
+ * 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.
+ */
+function encodeArtifactMetaValue(meta, shape, budget, adapter) {
+    const envelope = { v: META_FORMAT, shape, meta };
+    const value = asciiJson(envelope);
+    // The key travels with the value; both count against the service's cap.
+    const size = exports.ARTIFACT_META_KEY.length + value.length;
+    if (size > budget) {
+        const suspects = [];
+        if (meta.label !== undefined && meta.label.length > 64) {
+            suspects.push(`label (${meta.label.length} chars)`);
+        }
+        if (meta.parentRefs !== undefined && meta.parentRefs.length > 4) {
+            suspects.push(`parentRefs (${meta.parentRefs.length} refs)`);
+        }
+        if (meta.kind.length > 64)
+            suspects.push(`kind (${meta.kind.length} chars)`);
+        throw new types_js_1.InvalidArtifactError(`${adapter}: the ticket does not fit this service's object-metadata budget ` +
+            `(${size} bytes encoded, budget ${budget}). The ticket travels AS object metadata, so ` +
+            `the payload size is irrelevant here — the description is what is too long` +
+            (suspects.length > 0 ? `; the length is in ${suspects.join(' and ')}` : '') +
+            `. Shorten the label, carry fewer parentRefs, or move the long prose into the payload ` +
+            `where size is what this store is for.`);
+    }
+    return value;
+}
+exports.encodeArtifactMetaValue = encodeArtifactMetaValue;
+/**
+ * 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.
+ */
+function decodeArtifactMetaValue(value) {
+    if (typeof value !== 'string' || value === '')
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    const envelope = parsed;
+    if (envelope === null || typeof envelope !== 'object')
+        return undefined;
+    if (typeof envelope.v !== 'number' || envelope.v > META_FORMAT)
+        return undefined;
+    const meta = envelope.meta;
+    if (meta === undefined || !(0, naming_js_1.isArtifactRef)(meta.ref))
+        return undefined;
+    const shape = envelope.shape;
+    if (shape !== 'text' && shape !== 'binary' && shape !== 'json')
+        return undefined;
+    return { meta: meta, shape };
+}
+exports.decodeArtifactMetaValue = decodeArtifactMetaValue;
+/** 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. */
+function readMetadataEntry(bag, key) {
+    if (bag === undefined || bag === null)
+        return undefined;
+    const direct = bag[key];
+    if (direct !== undefined)
+        return direct;
+    const wanted = key.toLowerCase();
+    for (const [name, value] of Object.entries(bag)) {
+        if (name.toLowerCase() === wanted)
+            return value;
+    }
+    return undefined;
+}
+exports.readMetadataEntry = readMetadataEntry;
+/** Has the calendar passed this ticket? The one expiry predicate both object
+ *  adapters use, so "expired" cannot mean two things. */
+function isExpiredMeta(meta, now) {
+    return meta.expiresAt !== undefined && meta.expiresAt <= now;
+}
+exports.isExpiredMeta = isExpiredMeta;
+/**
+ * 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`.
+ */
+function objectSdkFailure(adapter, operation, err) {
+    const e = err;
+    const name = typeof e?.name === 'string' && e.name.length > 0 ? e.name : 'an unnamed failure';
+    const status = typeof e?.$metadata?.httpStatusCode === 'number'
+        ? e.$metadata.httpStatusCode
+        : typeof e?.code === 'number'
+            ? e.code
+            : undefined;
+    return new Error(`[artifacts] ${adapter}: ${operation} failed — ${name}` +
+        (status !== undefined ? ` (HTTP ${status})` : '') +
+        `.\n  The SDK's own message is withheld: object-storage errors echo the bucket and the ` +
+        `object KEY, and the key carries this run's tenant/principal/conversation. Check the ` +
+        `service's own logs for the full exception. This is not "no data" — a missing object ` +
+        `answers null; this call did not get an answer at all.`);
+}
+exports.objectSdkFailure = objectSdkFailure;
+/**
+ * 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.
+ */
+function objectFailurePolicy(adapter, isMissingObject) {
+    return (operation, err, meaning) => {
+        if (err instanceof types_js_1.InvalidArtifactError)
+            return err;
+        if (meaning === 'missing-object' && isMissingObject(err))
+            return err;
+        return objectSdkFailure(adapter, operation, err);
+    };
+}
+exports.objectFailurePolicy = objectFailurePolicy;
+/**
+ * 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.
+ */
+function pageObjectListing(rows, options) {
+    const sorted = [...rows].sort((a, b) => b.serviceCreatedAt - a.serviceCreatedAt || (a.meta.ref < b.meta.ref ? -1 : 1));
+    const offset = decodeOffsetCursor(options?.cursor);
+    const limit = Math.max(1, Math.floor(options?.limit ?? 50));
+    const page = sorted.slice(offset, offset + limit);
+    const nextOffset = offset + page.length;
+    return {
+        artifacts: page.map((row) => row.meta),
+        ...(nextOffset < sorted.length && { cursor: String(nextOffset) }),
+    };
+}
+exports.pageObjectListing = pageObjectListing;
+/** 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. */
+function decodeOffsetCursor(cursor) {
+    if (cursor === undefined)
+        return 0;
+    const parsed = Number(cursor);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 0;
+}
+exports.decodeOffsetCursor = decodeOffsetCursor;
+/** Validate a bucket name option at construction — the same shape of refusal
+ *  every adapter here gives for a missing required option. */
+function assertBucketOption(adapter, option, value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(`[artifacts] ${adapter}({ ${option}: ${JSON.stringify(value)} }) names no bucket. ` +
+            `Give it the name of a bucket that already exists — this library never creates one: ` +
+            `a bucket carries region, lifecycle, encryption and access decisions that belong to ` +
+            `your infrastructure, not to a call in an agent.`);
+    }
+    return value;
+}
+exports.assertBucketOption = assertBucketOption;
+//# sourceMappingURL=objectStore.js.map

package/dist/artifacts/objectStore.js.map

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

package/dist/artifacts/payload.js

@@ -23,7 +23,7 @@
  * a claim check exists to prevent.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.decodeArtifactData = exports.encodeArtifactData = exports.computeArtifactDigest = exports.measureArtifactBytes = exports.canonicalPayloadBytes = void 0;
+exports.decodeArtifactData = exports.encodeArtifactData = exports.computeArtifactDigest = exports.decodeCanonicalPayload = exports.payloadShapeOf = exports.measureArtifactBytes = exports.canonicalPayloadBytes = void 0;
 const types_js_1 = require("./types.js");
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
@@ -59,6 +59,38 @@ function measureArtifactBytes(data) {
     return canonicalPayloadBytes(data).byteLength;
 }
 exports.measureArtifactBytes = measureArtifactBytes;
+/** 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). */
+function payloadShapeOf(data) {
+    if (data instanceof Uint8Array)
+        return 'binary';
+    if (typeof data === 'string')
+        return 'text';
+    return 'json';
+}
+exports.payloadShapeOf = payloadShapeOf;
+/**
+ * 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.
+ */
+function decodeCanonicalPayload(shape, bytes) {
+    switch (shape) {
+        case 'text':
+            return textDecoder.decode(bytes);
+        case 'binary':
+            return bytes;
+        case 'json':
+            return JSON.parse(textDecoder.decode(bytes));
+    }
+}
+exports.decodeCanonicalPayload = decodeCanonicalPayload;
 /** `sha-256:<hex>` over the canonical bytes. */
 async function computeArtifactDigest(data) {
     const bytes = canonicalPayloadBytes(data);
@@ -82,7 +114,10 @@ function encodeArtifactData(data) {
     return { shape: 'json', value: textDecoder.decode(canonicalPayloadBytes(data)) };
 }
 exports.encodeArtifactData = encodeArtifactData;
-/** 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. */
 function decodeArtifactData(encoded) {
     switch (encoded.shape) {
         case 'text':
@@ -91,6 +126,10 @@ function decodeArtifactData(encoded) {
             return fromBase64(encoded.value);
         case 'json':
             return JSON.parse(encoded.value);
+        case 'external':
+            throw new types_js_1.InvalidArtifactError(`the payload was streamed and lives beside the envelope ('${encoded.value}'), not in ` +
+                `it. Only the store that wrote it can read it back — read this artifact through ` +
+                `that store's get()/getStream(), never by decoding the envelope alone.`);
     }
 }
 exports.decodeArtifactData = decodeArtifactData;

package/dist/artifacts/payload.js.map

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