agentfootprint 9.25.0 → 9.26.0

package/dist/esm/adapters/identity/jwks.js

@@ -0,0 +1,249 @@
+/**
+ * jwksIdentity — verify the caller's bearer token against a published key set.
+ *
+ * Pattern: Adapter (GoF) over `jose`, behind the vendor-neutral
+ *          {@link IdentityVerifier} port.
+ * Role:    the ONE identity verifier this release ships. It covers cloud IdPs
+ *          and on-prem ones with the same code, because JWKS is the same
+ *          protocol in both: a URL that publishes signing keys, and tokens
+ *          signed by one of them.
+ * Emits:   nothing. The door that called it reports the refusal — by CLASS.
+ *
+ * ── What it checks, and what it refuses to pretend to check ─────────────────
+ * Signature (against the key the token's `kid` names, fetched and cached from
+ * `jwksUrl`), `iss`, `aud`, `exp` and `nbf`. That is the whole list, and it is
+ * the whole list on purpose:
+ *
+ *   • **It is not an authorization decision.** A verified token proves WHO, not
+ *     WHAT-THEY-MAY-DO. Roles and claims come back on the result so your own
+ *     policy can decide; this adapter never reads them.
+ *   • **It does not check revocation.** A JWT is valid until it expires, and no
+ *     amount of key fetching changes that. Short lifetimes are the answer; an
+ *     adapter that implied otherwise would be selling a guarantee the protocol
+ *     does not make.
+ *   • **`alg: none` cannot get through**, because a JWKS resolver has no key for
+ *     it — verified against the real library rather than assumed (see the pin
+ *     test). Neither can a token signed with an algorithm outside `algorithms`.
+ *
+ * ── The token never comes back out ──────────────────────────────────────────
+ * Every failure is re-raised as {@link IdentityNotVerifiedError} carrying only
+ * the CLASS — `expired`, `wrong-audience`, `wrong-issuer`, `not-yet-valid`,
+ * `unverifiable`. The library's own message is dropped, and the original is
+ * deliberately NOT attached as `cause`: a cause travels into every serializer
+ * that walks own properties, and one `JSON.stringify` would undo all of this.
+ * (The `sdkFailure` law, applied to a credential rather than to a cloud SDK.)
+ *
+ * A key set this adapter could not FETCH is a different fact and gets a
+ * different class: {@link VerifierUnavailableError}, which the host answers 503
+ * rather than 401. Your IdP being down is not the caller presenting a bad
+ * token, and telling every client to re-authenticate against an unreachable
+ * provider is the wrong instruction at the worst moment.
+ *
+ * @example
+ *   const host = await standingAgent({
+ *     agent, sessions, host: nodeHost({ port: 8080 }),
+ *     identity: { verify: jwksIdentity({
+ *       jwksUrl:  'https://idp.example.com/.well-known/jwks.json',
+ *       issuer:   'https://idp.example.com/',
+ *       audience: 'my-api',
+ *     }).verify },
+ *   });
+ */
+import { IdentityNotVerifiedError, VerifierUnavailableError } from '../../hosting/errors.js';
+import { lazyRequire } from '../../lib/lazyRequire.js';
+/** Raised when a token must be verified and `jose` is not installed. */
+export class MissingJwksSupportError extends Error {
+    code = 'ERR_MISSING_JWKS_SUPPORT';
+    constructor() {
+        super('jwksIdentity requires the `jose` peer dependency.\n' +
+            '  Install:  npm install jose\n' +
+            '  Or pass `backend` to jwksIdentity() if your bundler resolves it statically.');
+        this.name = 'MissingJwksSupportError';
+    }
+}
+/** The asymmetric families. See {@link JwksIdentityOptions.algorithms}. */
+const DEFAULT_ALGORITHMS = [
+    'RS256',
+    'RS384',
+    'RS512',
+    'PS256',
+    'PS384',
+    'PS512',
+    'ES256',
+    'ES384',
+    'ES512',
+];
+/**
+ * `jose`'s stable error codes → this library's failure vocabulary.
+ *
+ * Mapped by CODE STRING rather than by `instanceof`, and that is the load-
+ * bearing choice: the error classes are not on `jose`'s main entry point (they
+ * live under `jose/errors`), the codes are documented as stable, and a string
+ * comparison survives a duplicated copy of the library in a `node_modules` tree
+ * — which `instanceof` famously does not.
+ *
+ * Every code is one this adapter has SEEN the installed library produce; the
+ * pin test reproduces each one against the real package.
+ */
+function classOf(err) {
+    const e = err;
+    const code = typeof e?.code === 'string' ? e.code : undefined;
+    switch (code) {
+        case 'ERR_JWT_EXPIRED':
+            return 'expired';
+        case 'ERR_JWT_CLAIM_VALIDATION_FAILED': {
+            const claim = typeof e?.claim === 'string' ? e.claim : undefined;
+            if (claim === 'aud')
+                return 'wrong-audience';
+            if (claim === 'iss')
+                return 'wrong-issuer';
+            if (claim === 'nbf')
+                return 'not-yet-valid';
+            return 'unverifiable';
+        }
+        case 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED':
+        case 'ERR_JWKS_NO_MATCHING_KEY':
+        case 'ERR_JWKS_MULTIPLE_MATCHING_KEYS':
+        case 'ERR_JWS_INVALID':
+        case 'ERR_JWT_INVALID':
+        case 'ERR_JWK_INVALID':
+        case 'ERR_JWKS_INVALID':
+        case 'ERR_JOSE_ALG_NOT_ALLOWED':
+        case 'ERR_JOSE_NOT_SUPPORTED':
+            return 'unverifiable';
+        case 'ERR_JWKS_TIMEOUT':
+            return 'keys-unavailable';
+        default:
+            // No JOSE code at all. A key-set fetch that failed surfaces here as the
+            // runtime's own `TypeError: fetch failed` — an outage on THIS side, and
+            // answering it 401 would send every client to re-authenticate against a
+            // provider that is already down.
+            return code === undefined ? 'keys-unavailable' : 'unverifiable';
+    }
+}
+/** Roles out of a claim, read leniently and never invented. */
+function rolesOf(value) {
+    if (Array.isArray(value)) {
+        const roles = value.filter((v) => typeof v === 'string' && v.length > 0);
+        return roles.length > 0 ? roles : undefined;
+    }
+    if (typeof value === 'string' && value.trim().length > 0) {
+        // The `scope` convention: one space-delimited string.
+        const roles = value.trim().split(/\s+/);
+        return roles.length > 0 ? roles : undefined;
+    }
+    return undefined;
+}
+export function jwksIdentity(options) {
+    const { jwksUrl } = options;
+    if (typeof jwksUrl !== 'string' || jwksUrl.trim().length === 0) {
+        throw new TypeError(`[identity] jwksIdentity({ jwksUrl: ${JSON.stringify(jwksUrl)} }) needs the URL your ` +
+            `identity provider publishes its signing keys at — usually ` +
+            `'<issuer>/.well-known/jwks.json'.`);
+    }
+    let url;
+    try {
+        url = new URL(jwksUrl);
+    }
+    catch {
+        throw new TypeError(`[identity] jwksIdentity({ jwksUrl: '${jwksUrl}' }) is not an absolute URL. Key sets are ` +
+            `fetched over the network, so a relative path has nothing to resolve against.`);
+    }
+    if (emptyName(options.issuer)) {
+        throw new TypeError(`[identity] jwksIdentity needs an \`issuer\`. A verifier that accepted any issuer would ` +
+            `accept a token minted by anybody who publishes a key set — which is not verification, ` +
+            `it is a signature check with no opinion about who signed.`);
+    }
+    if (emptyName(options.audience)) {
+        throw new TypeError(`[identity] jwksIdentity needs an \`audience\` — this API's name at your identity ` +
+            `provider. Without it a token minted for a DIFFERENT service verifies here, which is ` +
+            `the confused-deputy shape: a valid credential, honoured by the wrong door.`);
+    }
+    const userIdClaim = options.userIdClaim ?? 'sub';
+    const rolesClaim = options.rolesClaim ?? 'roles';
+    const algorithms = options.algorithms ?? DEFAULT_ALGORITHMS;
+    /** The key-set resolver, built once and reused — `jose` caches inside it. */
+    let resolver;
+    const getResolver = () => (resolver ??= (async () => {
+        const jose = options.backend ?? (await loadJose());
+        const keys = jose.createRemoteJWKSet(url, {
+            ...(options.cacheMaxAgeMs !== undefined && { cacheMaxAge: options.cacheMaxAgeMs }),
+            ...(options.fetchTimeoutMs !== undefined && { timeoutDuration: options.fetchTimeoutMs }),
+        });
+        return { jose, keys };
+    })().catch((err) => {
+        // A failed BUILD is not cached — a bundler hiccup or a transient import
+        // failure must not permanently poison the verifier.
+        resolver = undefined;
+        throw err;
+    }));
+    return {
+        async verify(token) {
+            const { jose, keys } = await getResolver();
+            let payload;
+            try {
+                const verified = await jose.jwtVerify(token, keys, {
+                    issuer: options.issuer,
+                    audience: options.audience,
+                    algorithms: algorithms,
+                    ...(options.clockToleranceSeconds !== undefined && {
+                        clockTolerance: options.clockToleranceSeconds,
+                    }),
+                });
+                payload = verified.payload;
+            }
+            catch (err) {
+                const failure = classOf(err);
+                // The one place the two shapes diverge: an unreachable key set is this
+                // deployment's outage (503), everything else is the caller's token
+                // (401). Neither carries the token, the claims, or the library's text.
+                if (failure === 'keys-unavailable') {
+                    throw new VerifierUnavailableError('jwksIdentity', 'its key set could not be fetched');
+                }
+                throw new IdentityNotVerifiedError(failure, false);
+            }
+            const userId = payload[userIdClaim];
+            if (typeof userId !== 'string' || userId.length === 0) {
+                // A perfectly valid token that does not say who it is about. Refused
+                // rather than served anonymously: "verified, subject unknown" is a
+                // state nothing downstream could act on honestly.
+                throw new IdentityNotVerifiedError('unverifiable', false);
+            }
+            const roles = rolesOf(payload[rolesClaim]);
+            return {
+                userId,
+                ...(roles !== undefined && { roles }),
+                claims: payload,
+            };
+        },
+    };
+}
+function emptyName(value) {
+    if (typeof value === 'string')
+        return value.trim().length === 0;
+    if (Array.isArray(value))
+        return value.length === 0 || value.some((v) => typeof v !== 'string');
+    return true;
+}
+/**
+ * Load `jose`, or refuse by name.
+ *
+ * `jose` v6 is ESM-only, so a dynamic import is tried first and the CJS require
+ * is the fallback — one of the two works on every runtime this package
+ * supports. (The `unpdf` loader's shape, for the same reason.)
+ */
+async function loadJose() {
+    try {
+        const spec = 'jose';
+        return (await import(spec));
+    }
+    catch {
+        try {
+            return lazyRequire('jose');
+        }
+        catch {
+            throw new MissingJwksSupportError();
+        }
+    }
+}
+//# sourceMappingURL=jwks.js.map

package/dist/esm/adapters/identity/jwks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.js","sourceRoot":"","sources":["../../../../src/adapters/identity/jwks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAE7F,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAwEvD,wEAAwE;AACxE,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACvC,IAAI,GAAG,0BAAmC,CAAC;IAEpD;QACE,KAAK,CACH,qDAAqD;YACnD,gCAAgC;YAChC,+EAA+E,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,kBAAkB,GAAsB;IAC5C,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;CACR,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,SAAS,OAAO,CACd,GAAY;IAQZ,MAAM,CAAC,GAAG,GAA6D,CAAC;IACxE,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,iBAAiB;YACpB,OAAO,SAAS,CAAC;QACnB,KAAK,iCAAiC,CAAC,CAAC,CAAC;YACvC,MAAM,KAAK,GAAG,OAAO,CAAC,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;YACjE,IAAI,KAAK,KAAK,KAAK;gBAAE,OAAO,gBAAgB,CAAC;YAC7C,IAAI,KAAK,KAAK,KAAK;gBAAE,OAAO,cAAc,CAAC;YAC3C,IAAI,KAAK,KAAK,KAAK;gBAAE,OAAO,eAAe,CAAC;YAC5C,OAAO,cAAc,CAAC;QACxB,CAAC;QACD,KAAK,uCAAuC,CAAC;QAC7C,KAAK,0BAA0B,CAAC;QAChC,KAAK,iCAAiC,CAAC;QACvC,KAAK,iBAAiB,CAAC;QACvB,KAAK,iBAAiB,CAAC;QACvB,KAAK,iBAAiB,CAAC;QACvB,KAAK,kBAAkB,CAAC;QACxB,KAAK,0BAA0B,CAAC;QAChC,KAAK,wBAAwB;YAC3B,OAAO,cAAc,CAAC;QACxB,KAAK,kBAAkB;YACrB,OAAO,kBAAkB,CAAC;QAC5B;YACE,wEAAwE;YACxE,wEAAwE;YACxE,wEAAwE;YACxE,iCAAiC;YACjC,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,cAAc,CAAC;IACpE,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,SAAS,OAAO,CAAC,KAAc;IAC7B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACtF,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzD,sDAAsD;QACtD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACxC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,SAAS,CACjB,sCAAsC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,yBAAyB;YACpF,4DAA4D;YAC5D,mCAAmC,CACtC,CAAC;IACJ,CAAC;IACD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,SAAS,CACjB,uCAAuC,OAAO,4CAA4C;YACxF,8EAA8E,CACjF,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,SAAS,CACjB,yFAAyF;YACvF,wFAAwF;YACxF,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CACjB,mFAAmF;YACjF,sFAAsF;YACtF,4EAA4E,CAC/E,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,KAAK,CAAC;IACjD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC;IACjD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC;IAE5D,6EAA6E;IAC7E,IAAI,QAAmE,CAAC;IACxE,MAAM,WAAW,GAAG,GAAkD,EAAE,CACtE,CAAC,QAAQ,KAAK,CAAC,KAAK,IAAI,EAAE;QACxB,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC;QACnD,MAAM,IAAI,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,EAAE;YACxC,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;YAClF,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;SACzF,CAAC,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACxB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACjB,wEAAwE;QACxE,oDAAoD;QACpD,QAAQ,GAAG,SAAS,CAAC;QACrB,MAAM,GAAG,CAAC;IACZ,CAAC,CAAC,CAAC,CAAC;IAEN,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,KAAa;YACxB,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;YAC3C,IAAI,OAAgC,CAAC;YACrC,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE;oBACjD,MAAM,EAAE,OAAO,CAAC,MAA2B;oBAC3C,QAAQ,EAAE,OAAO,CAAC,QAA6B;oBAC/C,UAAU,EAAE,UAAsB;oBAClC,GAAG,CAAC,OAAO,CAAC,qBAAqB,KAAK,SAAS,IAAI;wBACjD,cAAc,EAAE,OAAO,CAAC,qBAAqB;qBAC9C,CAAC;iBACH,CAAC,CAAC;gBACH,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;YAC7B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;gBAC7B,uEAAuE;gBACvE,mEAAmE;gBACnE,uEAAuE;gBACvE,IAAI,OAAO,KAAK,kBAAkB,EAAE,CAAC;oBACnC,MAAM,IAAI,wBAAwB,CAAC,cAAc,EAAE,kCAAkC,CAAC,CAAC;gBACzF,CAAC;gBACD,MAAM,IAAI,wBAAwB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACrD,CAAC;YACD,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;YACpC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACtD,qEAAqE;gBACrE,mEAAmE;gBACnE,kDAAkD;gBAClD,MAAM,IAAI,wBAAwB,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;YAC5D,CAAC;YACD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;YAC3C,OAAO;gBACL,MAAM;gBACN,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;gBACrC,MAAM,EAAE,OAAO;aAChB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,KAA6C;IAC9D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC;IAChE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;IAChG,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,QAAQ;IACrB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,CAAC;QACpB,OAAO,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAA2B,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,CAAC;YACH,OAAO,WAAW,CAAc,MAAM,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,uBAAuB,EAAE,CAAC;QACtC,CAAC;IACH,CAAC;AACH,CAAC"}

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

@@ -712,6 +712,60 @@ export interface CodeRunner {
         readonly signal?: AbortSignal;
     }): Promise<CodeSession>;
 }
+/**
+ * The environment variable an executing snippet reads its staged inputs from —
+ * a JSON object mapping each input's NAME to the path it landed at.
+ *
+ * Part of {@link CodeSession.stageInputs}'s contract rather than one adapter's
+ * convention, and named here so an adapter uses the constant instead of
+ * retyping the string. It is what makes model-written code portable across
+ * backends: the code reads one variable, and every adapter that stages inputs
+ * fills it the same way.
+ */
+export declare const STAGED_INPUTS_ENV = "AF_STAGED_INPUTS";
+/**
+ * One payload staged INTO a code session before code runs (9.26.0).
+ *
+ * `name` is the file name the caller wants it under — the tool derives it from
+ * the declared argument (`dataset` → `dataset.json`), so the model can be told
+ * the name in a static description. An adapter may sanitize it (a name is
+ * caller data landing in a filesystem) but must not rename it beyond
+ * recognition, because the manifest is keyed by what it was ASKED for.
+ */
+export interface CodeInput {
+    /**
+     * The MANIFEST KEY — what the executing code looks this input up by. The
+     * tool uses the declared argument name (`dataset`), so a static description
+     * can tell the model exactly what to look up before any session exists.
+     */
+    readonly name: string;
+    /**
+     * The file name to write it under, when it should differ from `name` — the
+     * tool derives one from the artifact's media type (`dataset` +
+     * `application/json` → `dataset.json`) so an interpreter's own loader sees a
+     * familiar extension. Defaults to `name`.
+     *
+     * A separate field precisely so the manifest KEY and the on-disk NAME cannot
+     * drift: the code looks up what it was told to look up, whatever the file
+     * ended up being called.
+     */
+    readonly fileName?: string;
+    /** The bytes. A string is written as UTF-8 text; a `Uint8Array` verbatim. */
+    readonly data: string | Uint8Array;
+    /** The producer's own statement about the payload, when it has one. */
+    readonly mediaType?: string;
+}
+/** Where one staged input actually landed. */
+export interface StagedCodeInput {
+    /** The name it was asked for — the manifest key the code looks up. */
+    readonly name: string;
+    /** The path the executing code opens. Absolute, or relative to the session's
+     *  working directory: whichever it is, it is what the manifest carries and
+     *  what the code should use verbatim. */
+    readonly path: string;
+    /** How many bytes landed. */
+    readonly bytes: number;
+}
 /** One live session. `stop()` is idempotent and tolerates "already gone". */
 export interface CodeSession {
     /** The backend's own id for this session, when it has one. */
@@ -722,6 +776,35 @@ export interface CodeSession {
         readonly timeoutMs?: number;
         readonly signal?: AbortSignal;
     }): Promise<CodeResult>;
+    /**
+     * OPTIONAL (9.26.0) — put payloads INTO the session, so code can read data
+     * that never travelled through the context window.
+     *
+     * ── Why it is a new member rather than an argument to `execute` ──────────
+     * The port's only input was the code STRING, and 9.22.0 stated the honest
+     * consequence rather than working around it: pushing a resolved artifact
+     * through that door would mean inlining megabytes into an argv, in
+     * language-specific quoting, past operating-system argument limits. This is
+     * the session file-write verb that note said it was waiting for.
+     *
+     * ── The contract, which is two promises not one ─────────────────────────
+     *  1. The payloads are written where the session's code can read them, and
+     *     the returned {@link StagedCodeInput.path} is what the code opens.
+     *  2. Every later `execute` on this session exposes the manifest as the
+     *     {@link STAGED_INPUTS_ENV} environment variable — a JSON object of
+     *     `name → path`. That second promise is what makes the model's code
+     *     portable: it reads one variable, on every backend that stages.
+     *
+     * Staged inputs live as long as the SESSION and are released by `stop()`.
+     *
+     * ── Absent, never faked ─────────────────────────────────────────────────
+     * A backend that cannot write into its own session LEAVES THIS ABSENT.
+     * Feature-detect with `canStageCodeInputs(session)`; `codeRunnerTool`
+     * refuses by name when a tool declares artifact inputs and the runner cannot
+     * carry them, because running the code without the data it declared would be
+     * the accepted-and-silently-wrong failure.
+     */
+    stageInputs?(inputs: readonly CodeInput[]): Promise<readonly StagedCodeInput[]>;
     /**
      * Release the session.
      *
@@ -731,6 +814,9 @@ export interface CodeSession {
      */
     stop(): Promise<void>;
 }
+/** Can this session accept staged inputs? The feature-detection law: read the
+ *  member, never assume it from the adapter's name. */
+export declare function canStageCodeInputs(session: CodeSession): session is CodeSession & Required<Pick<CodeSession, 'stageInputs'>>;
 /** What one execution produced. */
 export interface CodeResult {
     /** Did the code run to completion without an error exit? */

package/dist/esm/adapters/types.js

@@ -35,4 +35,20 @@ export function checkerGoverns(checker, capability) {
         return true;
     return checker.governs?.includes(capability) === true;
 }
+/**
+ * The environment variable an executing snippet reads its staged inputs from —
+ * a JSON object mapping each input's NAME to the path it landed at.
+ *
+ * Part of {@link CodeSession.stageInputs}'s contract rather than one adapter's
+ * convention, and named here so an adapter uses the constant instead of
+ * retyping the string. It is what makes model-written code portable across
+ * backends: the code reads one variable, and every adapter that stages inputs
+ * fills it the same way.
+ */
+export const STAGED_INPUTS_ENV = 'AF_STAGED_INPUTS';
+/** Can this session accept staged inputs? The feature-detection law: read the
+ *  member, never assume it from the adapter's name. */
+export function canStageCodeInputs(session) {
+    return typeof session.stageInputs === 'function';
+}
 //# sourceMappingURL=types.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA+GH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAikBH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAsC,EACtC,UAAgC;IAEhC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AACxD,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA+GH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAwB,MAAM,CAAC,MAAM,CAAC;IAC5E,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAikBH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAsC,EACtC,UAAgC;IAEhC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,UAAU,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AACxD,CAAC;AAqDD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAgGpD;uDACuD;AACvD,MAAM,UAAU,kBAAkB,CAChC,OAAoB;IAEpB,OAAO,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC;AACnD,CAAC"}

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

@@ -21,4 +21,5 @@ export { assertStreamBytes, bytesAsStream, canGetArtifactStream, canPutArtifactS
 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';

package/dist/esm/artifacts/index.js

@@ -20,5 +20,6 @@ export { assertStreamBytes, bytesAsStream, canGetArtifactStream, canPutArtifactS
 export { bindArtifacts, unconfiguredArtifacts, } from './capability.js';
 export { assertToolWants, resolveToolWants, wantsNeedsStoreRefusal, } from './wants.js';
 export { PRESENT_TOOL_NAME, presentArtifact, } from './present.js';
+export { recordingPutInput, RECORDING_ARTIFACT_KIND, RECORDING_MEDIA_TYPE, UnserializableRecordingError, } from './recordingArtifact.js';
 export { assertArtifactPlacement, isPlacedToolResult, placedResultKind, placedToolResult, } from './placement.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,GAetB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAElF,OAAO,EACL,iBAAiB,EACjB,oCAAoC,GAGrC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,EACb,2BAA2B,GAE5B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,4BAA4B,GAG7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAA2B,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,YAAY,EAA4B,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,GAId,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,EACb,qBAAqB,GAQtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GAIvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,eAAe,GAIhB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GAGjB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,GAetB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAElF,OAAO,EACL,iBAAiB,EACjB,oCAAoC,GAGrC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,EACb,2BAA2B,GAE5B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,4BAA4B,GAG7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAA2B,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,YAAY,EAA4B,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,GAId,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,EACb,qBAAqB,GAQtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GAIvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,eAAe,GAIhB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,4BAA4B,GAE7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GAGjB,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1,76 @@
+/**
+ * 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;

package/dist/esm/artifacts/recordingArtifact.js

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+/** The consumer vocabulary a run recording is stored under. One kind, exact
+ *  match — the same rule every `wants` declaration is judged by. */
+export const RECORDING_ARTIFACT_KIND = 'recording/run';
+/** The media type a recording is minted with. */
+export const RECORDING_MEDIA_TYPE = 'application/json';
+/**
+ * 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 class UnserializableRecordingError extends Error {
+    code = 'ERR_UNSERIALIZABLE_RECORDING';
+    constructor(detail) {
+        super(`[artifacts] the run recording could not be serialized (${detail}), so it was not ` +
+            `stored. A recording that JSON cannot carry could not be delivered over any wire ` +
+            `either — this fails at the mint rather than at whatever tried to read it. The run ` +
+            `itself is unaffected: its answer was already composed before this was attempted.`);
+        this.name = 'UnserializableRecordingError';
+    }
+}
+/**
+ * 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 function recordingPutInput(recording, facts = {}) {
+    let text;
+    try {
+        text = JSON.stringify(recording) ?? '';
+    }
+    catch (err) {
+        throw new UnserializableRecordingError(err instanceof Error ? err.message : String(err));
+    }
+    if (text === '') {
+        throw new UnserializableRecordingError('it serializes to nothing');
+    }
+    return {
+        kind: RECORDING_ARTIFACT_KIND,
+        mediaType: RECORDING_MEDIA_TYPE,
+        data: text,
+        label: facts.label ?? (facts.runId !== undefined ? `run ${facts.runId}` : 'run recording'),
+        ...(facts.runId !== undefined && { origin: { runId: facts.runId } }),
+    };
+}
+//# sourceMappingURL=recordingArtifact.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recordingArtifact.js","sourceRoot":"","sources":["../../../src/artifacts/recordingArtifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH;oEACoE;AACpE,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAe,CAAC;AAEvD,iDAAiD;AACjD,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AAoBvD;;;;;GAKG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAC5C,IAAI,GAAG,8BAAuC,CAAC;IAExD,YAAY,MAAc;QACxB,KAAK,CACH,0DAA0D,MAAM,mBAAmB;YACjF,kFAAkF;YAClF,oFAAoF;YACpF,kFAAkF,CACrF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAkB,EAClB,QAA4B,EAAE;IAE9B,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,4BAA4B,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,4BAA4B,CAAC,0BAA0B,CAAC,CAAC;IACrE,CAAC;IACD,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,SAAS,EAAE,oBAAoB;QAC/B,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC;QAC1F,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;KACrE,CAAC;AACJ,CAAC"}