nexus-ai-pro 2.2.0 → 2.3.0

package/dist-cjs/server/auth.js

@@ -0,0 +1,402 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwtError = void 0;
+exports.createJwtVerifier = createJwtVerifier;
+exports.jwtAuth = jwtAuth;
+exports.hashApiKey = hashApiKey;
+exports.apiKeyAuth = apiKeyAuth;
+exports.trustedProxyAuth = trustedProxyAuth;
+exports.anyAuth = anyAuth;
+const tenant_js_1 = require("../utils/tenant.js");
+class JwtError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'JwtError';
+    }
+}
+exports.JwtError = JwtError;
+const HMAC = ['HS256', 'HS384', 'HS512'];
+const ASYMMETRIC = [
+    'RS256',
+    'RS384',
+    'RS512',
+    'PS256',
+    'PS384',
+    'PS512',
+    'ES256',
+    'ES384',
+    'ES512',
+    'EdDSA',
+];
+function cryptoParams(alg) {
+    const bits = alg.slice(2);
+    const hash = `SHA-${bits === 'DSA' ? '512' : bits}`;
+    switch (alg.slice(0, 2)) {
+        case 'HS':
+            return { importAs: { name: 'HMAC', hash }, verifyAs: { name: 'HMAC' } };
+        case 'RS':
+            return { importAs: { name: 'RSASSA-PKCS1-v1_5', hash }, verifyAs: { name: 'RSASSA-PKCS1-v1_5' } };
+        case 'PS':
+            return { importAs: { name: 'RSA-PSS', hash }, verifyAs: { name: 'RSA-PSS', saltLength: Number(bits) / 8 } };
+        case 'ES': {
+            const namedCurve = bits === '512' ? 'P-521' : `P-${bits}`;
+            return { importAs: { name: 'ECDSA', namedCurve }, verifyAs: { name: 'ECDSA', hash } };
+        }
+        default:
+            return { importAs: { name: 'Ed25519' }, verifyAs: { name: 'Ed25519' } };
+    }
+}
+function jwkFits(jwk, alg) {
+    if (jwk.alg && jwk.alg !== alg && !(alg === 'EdDSA' && jwk.alg === 'Ed25519'))
+        return false;
+    if (jwk.use && jwk.use !== 'sig')
+        return false;
+    if (jwk.key_ops && !jwk.key_ops.includes('verify'))
+        return false;
+    if (alg.startsWith('RS') || alg.startsWith('PS'))
+        return jwk.kty === 'RSA';
+    if (alg.startsWith('ES')) {
+        const curve = alg === 'ES512' ? 'P-521' : `P-${alg.slice(2)}`;
+        return jwk.kty === 'EC' && jwk.crv === curve;
+    }
+    if (alg === 'EdDSA')
+        return jwk.kty === 'OKP' && jwk.crv === 'Ed25519';
+    return false;
+}
+function createJwtVerifier(options) {
+    const sources = [options.secret, options.publicKey, options.jwks].filter((source) => source !== undefined);
+    if (sources.length !== 1) {
+        throw new TypeError('createJwtVerifier() needs exactly one of secret, publicKey, or jwks');
+    }
+    if (options.jwks !== undefined && options.audience === undefined) {
+        throw new TypeError('A key set signs tokens for every application its provider serves: set audience, or audience: false to accept any');
+    }
+    const allowed = new Set((options.algorithms ?? (options.secret !== undefined ? HMAC : ASYMMETRIC)).filter((alg) => options.secret !== undefined ? HMAC.includes(alg) : ASYMMETRIC.includes(alg)));
+    if (allowed.size === 0)
+        throw new TypeError('None of the algorithms given can be used with this kind of key');
+    const now = options.now ?? Date.now;
+    const tolerance = options.clockToleranceSec ?? 60;
+    const subtle = globalThis.crypto.subtle;
+    const imported = new Map();
+    const importOnce = (cacheKey, load) => {
+        let key = imported.get(cacheKey);
+        if (!key) {
+            key = load();
+            key.catch(() => imported.delete(cacheKey));
+            imported.set(cacheKey, key);
+        }
+        return key;
+    };
+    let keySet = options.jwks !== undefined && typeof options.jwks === 'object' && !(options.jwks instanceof URL)
+        ? { keys: options.jwks.keys, fetchedAt: Number.POSITIVE_INFINITY }
+        : undefined;
+    let lastUnknownFetch = Number.NEGATIVE_INFINITY;
+    let inFlight;
+    const refresh = () => {
+        if (inFlight)
+            return inFlight;
+        const fetcher = options.fetch ?? globalThis.fetch;
+        inFlight = (async () => {
+            const response = await fetcher(String(options.jwks), { headers: { accept: 'application/json' } });
+            if (!response.ok)
+                throw new JwtError('JWT_KEY', `The key set answered ${response.status}`);
+            const body = (await response.json());
+            if (!Array.isArray(body.keys))
+                throw new JwtError('JWT_KEY', 'The key set has no keys');
+            keySet = { keys: body.keys, fetchedAt: now() };
+            imported.clear();
+        })().finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
+    const keyFor = async (header, alg) => {
+        const { importAs } = cryptoParams(alg);
+        if (options.secret !== undefined) {
+            const raw = typeof options.secret === 'string' ? new TextEncoder().encode(options.secret) : options.secret;
+            return importOnce(`secret:${alg}`, () => subtle.importKey('raw', raw, importAs, false, ['verify']));
+        }
+        if (options.publicKey !== undefined) {
+            const key = options.publicKey;
+            if (typeof key === 'object' && 'type' in key && 'algorithm' in key)
+                return key;
+            if (typeof key === 'string') {
+                return importOnce(`pem:${alg}`, () => subtle.importKey('spki', pemToDer(key), importAs, false, ['verify']));
+            }
+            if (!jwkFits(key, alg))
+                throw new JwtError('JWT_KEY', `The key cannot verify ${alg}`);
+            return importOnce(`jwk:${alg}`, () => subtle.importKey('jwk', key, importAs, false, ['verify']));
+        }
+        const remote = typeof options.jwks === 'string' || options.jwks instanceof URL;
+        const cacheMs = options.jwksCacheMs ?? 10 * 60_000;
+        if (remote && (!keySet || now() - keySet.fetchedAt > cacheMs))
+            await refresh();
+        const find = () => keySet?.keys.filter((jwk) => (header.kid === undefined || jwk.kid === header.kid) && jwkFits(jwk, alg)) ?? [];
+        let matches = find();
+        if (matches.length === 0 && remote && now() - lastUnknownFetch >= (options.jwksCooldownMs ?? 30_000)) {
+            lastUnknownFetch = now();
+            await refresh();
+            matches = find();
+        }
+        const [jwk] = matches;
+        if (!jwk || (header.kid === undefined && matches.length > 1)) {
+            throw new JwtError('JWT_KEY', header.kid ? `No key "${header.kid}" for ${alg}` : `No single key for ${alg}`);
+        }
+        return importOnce(`jwks:${jwk.kid ?? ''}:${alg}`, () => subtle.importKey('jwk', jwk, importAs, false, ['verify']));
+    };
+    return {
+        async verify(token) {
+            const parts = token.split('.');
+            if (parts.length !== 3 || parts.some((part) => !/^[A-Za-z0-9_-]*$/.test(part)) || !parts[2]) {
+                throw new JwtError('JWT_MALFORMED', 'The token is not a signed JWT');
+            }
+            const [encodedHeader, encodedPayload, encodedSignature] = parts;
+            const header = decodeJson(encodedHeader, 'header');
+            const payload = decodeJson(encodedPayload, 'payload');
+            if (typeof header.alg !== 'string' || !allowed.has(header.alg)) {
+                throw new JwtError('JWT_ALGORITHM', `The algorithm "${String(header.alg)}" is not accepted`);
+            }
+            if (header.crit !== undefined)
+                throw new JwtError('JWT_MALFORMED', 'The token has critical headers this verifier does not understand');
+            const alg = header.alg;
+            const key = await keyFor(header, alg).catch((error) => {
+                throw error instanceof JwtError ? error : new JwtError('JWT_KEY', `No usable key for ${alg}`);
+            });
+            const valid = await subtle
+                .verify(cryptoParams(alg).verifyAs, key, base64UrlBytes(encodedSignature), new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`))
+                .catch(() => false);
+            if (!valid)
+                throw new JwtError('JWT_SIGNATURE', 'The signature does not match');
+            checkClaims(payload, options, now() / 1000, tolerance);
+            return { header, payload };
+        },
+    };
+}
+function checkClaims(payload, options, seconds, tolerance) {
+    const numeric = (name) => {
+        const value = payload[name];
+        if (value !== undefined && typeof value !== 'number')
+            throw new JwtError('JWT_CLAIM', `"${name}" is not a number`);
+        return value;
+    };
+    const exp = numeric('exp');
+    const nbf = numeric('nbf');
+    const iat = numeric('iat');
+    if (exp === undefined && options.requireExpiry !== false)
+        throw new JwtError('JWT_CLAIM', 'The token has no expiry');
+    if (exp !== undefined && seconds >= exp + tolerance)
+        throw new JwtError('JWT_EXPIRED', 'The token has expired');
+    if (nbf !== undefined && seconds + tolerance < nbf)
+        throw new JwtError('JWT_NOT_YET_VALID', 'The token is not valid yet');
+    if (options.maxAgeSec !== undefined) {
+        if (iat === undefined)
+            throw new JwtError('JWT_CLAIM', 'The token has no issue time');
+        if (seconds - iat > options.maxAgeSec + tolerance)
+            throw new JwtError('JWT_TOO_OLD', 'The token is too old');
+    }
+    if (options.issuer !== undefined) {
+        const issuers = typeof options.issuer === 'string' ? [options.issuer] : options.issuer;
+        if (typeof payload.iss !== 'string' || !issuers.includes(payload.iss)) {
+            throw new JwtError('JWT_ISSUER', 'The token is from another issuer');
+        }
+    }
+    if (options.audience !== undefined && options.audience !== false) {
+        const wanted = typeof options.audience === 'string' ? [options.audience] : options.audience;
+        const audiences = typeof payload.aud === 'string' ? [payload.aud] : Array.isArray(payload.aud) ? payload.aud : [];
+        if (!audiences.some((audience) => wanted.includes(audience))) {
+            throw new JwtError('JWT_AUDIENCE', 'The token is for another audience');
+        }
+    }
+    for (const claim of options.requiredClaims ?? []) {
+        if (payload[claim] === undefined)
+            throw new JwtError('JWT_CLAIM', `The token has no "${claim}" claim`);
+    }
+}
+function jwtAuth(options) {
+    const verifier = createJwtVerifier(options);
+    const read = options.token ?? bearerToken;
+    return async (request) => {
+        const token = read(request);
+        if (token?.split('.').length !== 3)
+            return undefined;
+        let payload;
+        try {
+            payload = (await verifier.verify(token)).payload;
+        }
+        catch (error) {
+            if (!(error instanceof JwtError))
+                throw error;
+            const description = error.message.replace(/["\\]/g, "'");
+            return refuse(401, error.message, `Bearer error="invalid_token", error_description="${description}"`);
+        }
+        try {
+            const principal = options.principal
+                ? await options.principal(payload, request)
+                : principalFromClaims(payload, options.claims);
+            if (!principal)
+                return refuse(403, 'The token is valid, but not for this server');
+            return { method: 'jwt', claims: payload, ...principal };
+        }
+        catch (error) {
+            return refuse(403, error instanceof Error ? error.message : String(error));
+        }
+    };
+}
+function principalFromClaims(payload, names = {}) {
+    const subject = claimAt(payload, names.subject ?? 'sub');
+    const tenant = claimAt(payload, names.tenant ?? 'tenant_id');
+    const roles = listOf(claimAt(payload, names.roles ?? 'roles'));
+    const scopes = listOf(names.scopes ? claimAt(payload, names.scopes) : (payload.scope ?? payload.scp));
+    return {
+        ...(typeof subject === 'string' ? { userId: subject } : {}),
+        ...(typeof tenant === 'string' ? { tenantId: (0, tenant_js_1.assertTenantId)(tenant) } : {}),
+        ...(roles ? { roles } : {}),
+        ...(scopes ? { scopes } : {}),
+    };
+}
+async function hashApiKey(key) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(key));
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+function apiKeyAuth(options) {
+    if (!options.keys && !options.lookup)
+        throw new TypeError('apiKeyAuth() needs keys, a lookup, or both');
+    const header = options.header?.toLowerCase();
+    return async (request) => {
+        const key = header
+            ? (request.headers.get(header) ?? undefined)
+            : (request.headers.get('x-api-key') ?? bearerToken(request));
+        if (!key)
+            return undefined;
+        if (options.prefix ? !key.startsWith(options.prefix) : /^[\w-]+\.[\w-]+\.[\w-]+$/.test(key))
+            return undefined;
+        const hash = await hashApiKey(key);
+        const known = Object.hasOwn(options.keys ?? {}, hash) ? options.keys?.[hash] : undefined;
+        const principal = known ?? (await options.lookup?.(hash, request));
+        if (!principal)
+            return refuse(401, 'The API key is not valid', 'Bearer error="invalid_token"');
+        if (principal.tenantId !== undefined)
+            (0, tenant_js_1.assertTenantId)(principal.tenantId);
+        return { method: 'api-key', ...principal };
+    };
+}
+function trustedProxyAuth(options) {
+    if (!options.secret && !options.trust) {
+        throw new TypeError('trustedProxyAuth() needs a secret or a trust check: otherwise anyone who sets the headers is trusted');
+    }
+    const names = {
+        user: 'x-forwarded-user',
+        tenant: 'x-forwarded-tenant',
+        roles: 'x-forwarded-roles',
+        scopes: 'x-forwarded-scopes',
+        ...options.headers,
+    };
+    const separator = options.separator ?? ',';
+    const list = (value) => value
+        ?.split(separator)
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return async (request) => {
+        if (options.secret && !sameText(request.headers.get(options.secret.header) ?? '', options.secret.value)) {
+            return undefined;
+        }
+        if (options.trust && !(await options.trust(request)))
+            return undefined;
+        const user = request.headers.get(names.user);
+        if (!user)
+            return undefined;
+        const tenant = request.headers.get(names.tenant);
+        if (tenant && !/^[A-Za-z0-9_-]{1,128}$/.test(tenant))
+            return refuse(403, `"${tenant}" is not a valid tenant id`);
+        const roles = list(request.headers.get(names.roles));
+        const scopes = list(request.headers.get(names.scopes));
+        return {
+            method: 'proxy',
+            userId: user,
+            ...(tenant ? { tenantId: tenant } : {}),
+            ...(roles?.length ? { roles } : {}),
+            ...(scopes?.length ? { scopes } : {}),
+        };
+    };
+}
+function anyAuth(...hooks) {
+    return async (request) => {
+        let refusal;
+        for (const hook of hooks) {
+            const result = await hook(request);
+            if (result instanceof Response)
+                refusal ??= result;
+            else if (result)
+                return result;
+        }
+        return refusal;
+    };
+}
+function bearerToken(request) {
+    const match = /^Bearer\s+(\S+)\s*$/i.exec(request.headers.get('authorization') ?? '');
+    return match?.[1];
+}
+function refuse(status, message, challenge) {
+    return new Response(JSON.stringify({ error: { code: status === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN', message } }), {
+        status,
+        headers: {
+            'content-type': 'application/json; charset=utf-8',
+            ...(challenge ? { 'www-authenticate': challenge } : {}),
+        },
+    });
+}
+function sameText(left, right) {
+    let difference = left.length ^ right.length;
+    const length = Math.max(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        difference |= (left.charCodeAt(index) || 0) ^ (right.charCodeAt(index) || 0);
+    }
+    return difference === 0;
+}
+function base64UrlBytes(text) {
+    const base64 = text
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(text.length / 4) * 4, '=');
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+function decodeJson(part, what) {
+    try {
+        const value = JSON.parse(new TextDecoder().decode(base64UrlBytes(part)));
+        if (value && typeof value === 'object' && !Array.isArray(value))
+            return value;
+    }
+    catch {
+    }
+    throw new JwtError('JWT_MALFORMED', `The token's ${what} is not a JSON object`);
+}
+function pemToDer(pem) {
+    const body = pem.replace(/-----(?:BEGIN|END) PUBLIC KEY-----/g, '').replace(/\s+/g, '');
+    if (!body || pem.includes('PRIVATE KEY'))
+        throw new JwtError('JWT_KEY', 'The public key is not a PEM public key');
+    return base64UrlBytes(body.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')).buffer;
+}
+function claimAt(payload, path) {
+    if (path in payload)
+        return payload[path];
+    let current = payload;
+    for (const segment of path.split('.')) {
+        if (!current || typeof current !== 'object')
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function listOf(value) {
+    if (typeof value === 'string')
+        return value.split(/\s+/).filter(Boolean);
+    if (Array.isArray(value))
+        return value.filter((item) => typeof item === 'string');
+    return undefined;
+}

package/dist-cjs/store/memory.d.ts

@@ -20,6 +20,10 @@ export declare class MemoryStore implements Store {
     private readonly options;
     private readonly items;
     private readonly maxItems;
+    /** Whether any item was ever given a time to live; until one is, there is nothing to sweep. */
+    private expiring;
+    /** When expired items were last swept, in milliseconds. */
+    private sweptAt;
     private readonly now;
     constructor(options?: MemoryStoreOptions);
     /** Stores an item, keeping its original `createdAt` when it replaces one. */
@@ -42,5 +46,11 @@ export declare class MemoryStore implements Store {
     size(): number;
     private embed;
     private expired;
+    /**
+     * Drops expired items. Reads already skip them, so this only reclaims memory: it runs once any item
+     * has a time to live, and at most once a second, so a write stays constant-time however many items
+     * there are. A store that is full sweeps before it evicts, so a live item never makes way for an
+     * expired one.
+     */
     private sweep;
 }

package/dist-cjs/store/memory.js

@@ -11,6 +11,8 @@ class MemoryStore {
     options;
     items = new Map();
     maxItems;
+    expiring = false;
+    sweptAt = Number.NEGATIVE_INFINITY;
     now;
     constructor(options = {}) {
         this.options = options;
@@ -25,6 +27,8 @@ class MemoryStore {
         const timestamp = this.now().toISOString();
         const existing = this.items.get(id);
         const vector = await this.embed(value, options.index);
+        if (options.ttlMs !== undefined)
+            this.expiring = true;
         this.items.delete(id);
         this.items.set(id, {
             namespace: [...namespace],
@@ -106,6 +110,12 @@ class MemoryStore {
         return item.expiresAt !== undefined && Date.parse(item.expiresAt) <= this.now().getTime();
     }
     sweep() {
+        if (!this.expiring)
+            return;
+        const now = this.now().getTime();
+        if (now - this.sweptAt < 1_000 && this.items.size <= this.maxItems)
+            return;
+        this.sweptAt = now;
         for (const [id, item] of this.items)
             if (this.expired(item))
                 this.items.delete(id);

package/dist-cjs/types/graph.d.ts

@@ -8,6 +8,7 @@ import type { OperationLifecycleLike } from './lifecycle.js';
  * is, so a different process can pick it up.
  */
 import type { CacheAdapter } from '../cache/adapters.js';
+import type { Principal } from './principal.js';
 import type { Store } from './store.js';
 /** Entry sentinel. An edge from `START` names the first node. */
 export declare const START = "__start__";
@@ -243,6 +244,14 @@ export interface NodeOptions<S extends ChannelSchema = ChannelSchema> {
      * that are not.
      */
     idempotent?: boolean;
+    /**
+     * What the node does to the world, as capabilities: `payments:charge`, `network:api.stripe.com`,
+     * `filesystem:write`. Declared for the linter, which reports a node with effects that also
+     * interrupts, since the node runs again from the top when the answer comes.
+     */
+    effects?: readonly string[];
+    /** True when the node may call `context.interrupt()`. Declared for the linter. */
+    interrupts?: boolean;
     /**
      * Nodes this one may reach through `Send` or a `Command`. Declaring them keeps compile-time
      * reachability checks and diagrams exact, so a node reached only that way is not reported as
@@ -374,6 +383,8 @@ export interface NodeContext<S extends ChannelSchema> {
     readonly threadId: string;
     /** The tenant the run is for, when it has one. */
     readonly tenantId?: string;
+    /** Who the run is for, when it was started with a principal: the caller the server authenticated. */
+    readonly principal?: Readonly<Principal>;
     /** Identifies this task. Equal to `node` unless the task came from a `Send`. */
     readonly taskId: string;
     /** Input carried by a `Send`. Undefined for a node reached through an ordinary edge. */
@@ -577,6 +588,14 @@ export interface GraphRunOptions {
      * `tenantId` is refused before anything runs. A run without one carries on the thread's tenant.
      */
     tenantId?: string;
+    /**
+     * Who the run is for, such as the caller the server authenticated. Nodes read it as
+     * `context.principal`, and an agent hands it to every tool and middleware. Its `tenantId` is the
+     * run's tenant when `tenantId` is not given, and a run whose two tenants differ is refused. Its
+     * `userId` is recorded on every checkpoint as `metadata.userId`; the rest is never stored, so a
+     * resumed run carries the principal of whoever resumed it.
+     */
+    principal?: Principal;
     /** Overrides the compiled `maxConcurrency` for this run. */
     maxConcurrency?: number;
     /** Breakpoints for this run only, replacing the compiled ones. */
@@ -853,6 +872,10 @@ export interface GraphDescription {
         idempotent?: boolean;
         /** True when the node reuses results through `cache`. */
         cache?: boolean;
+        /** The capabilities its work uses, when it declares them. */
+        effects?: string[];
+        /** True when it declares that it may interrupt. */
+        interrupts?: boolean;
         /** The graph this node runs, when it is a compiled graph used through `asNode()`. */
         subgraph?: GraphDescription;
     }>;
@@ -876,6 +899,19 @@ export interface GraphDescription {
     checkpointer?: 'memory' | 'custom' | 'none';
     /** Tasks a superstep runs at once. */
     maxConcurrency?: number;
+    /** The tools the graph's nodes call, when it was compiled with them, as an agent is. */
+    tools?: GraphToolDescription[];
+}
+/** A tool a graph calls, as the linter reads it. */
+export interface GraphToolDescription {
+    /** The tool's name. */
+    name: string;
+    /** Its capabilities, when it declares a fixed list. */
+    capabilities?: string[];
+    /** True when it computes its capabilities from each call's arguments. */
+    dynamic?: boolean;
+    /** How its calls are approved: an interrupt for each, a permission policy, or not at all. */
+    approval: 'interrupt' | 'policy' | 'none';
 }
 /**
  * Options applied when a graph is compiled: stores, breakpoints, concurrency, retries, and failure
@@ -898,6 +934,8 @@ export interface CompileOptions {
     maxConcurrency?: number;
     /** Default retry policy for every node. A node's own policy wins. */
     retry?: RetryPolicy;
+    /** The tools the graph's nodes call, for `describe()` and the linter. `createAgent()` fills it. */
+    tools?: GraphToolDescription[];
     /**
      * Defaults for every node: a retry policy, timeouts, and an `onError`. A node's own options win,
      * field by field. `retry` here is the same as `compile({ retry })`, and wins over it.

package/dist-cjs/types/messages.d.ts

@@ -1,5 +1,7 @@
 import type { CacheTtl, ReasoningEffort } from './providers.js';
 import type { AssetInput } from './images.js';
+import type { Principal } from './principal.js';
+import type { Store } from './store.js';
 declare global {
     namespace NodeJS {
         /**
@@ -128,8 +130,19 @@ export interface ToolDefinition {
     description: string;
     /** JSON Schema for the arguments. */
     parameters: Record<string, unknown>;
-    /** Runs the tool, for the agent loop and executors that call tools automatically. */
-    execute?: (args: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Runs the tool, for the agent loop and executors that call tools automatically. An agent passes
+     * a `ToolContext` too: who the run is for, its thread and tenant, its signal, and its store.
+     */
+    execute?: (args: Record<string, unknown>, context?: ToolContext) => Promise<unknown>;
+    /**
+     * What the tool does to the world, as capabilities a permission policy decides on:
+     * `filesystem:read` or `filesystem:write` with an optional path, `network` with an optional host,
+     * `shell` with an optional command, `code`, or a name of the application's own such as `payments`.
+     * A function computes them from each call's arguments, so a policy sees the path, host, or command
+     * the call actually uses. Never sent to a model.
+     */
+    capabilities?: readonly string[] | ((args: Record<string, unknown>) => readonly string[]);
     /**
      * Ends a cacheable prefix after this tool. Only honored when the request sets
      * `cache.mode: 'explicit'` and the provider accepts caller-placed breakpoints.
@@ -145,6 +158,27 @@ export interface ToolDefinition {
 export type ToolChoice = 'auto' | 'none' | 'required' | {
     name: string;
 };
+/**
+ * What a tool receives besides its arguments when an agent runs it. Every field is optional: a tool
+ * run outside an agent, or by an executor given nothing, sees none of them.
+ */
+export interface ToolContext {
+    /** The model's id for this call. */
+    toolCallId?: string;
+    /** The thread the run belongs to. */
+    threadId?: string;
+    /** The tenant the run is for. */
+    tenantId?: string;
+    /**
+     * Who the run is for: the caller the server authenticated, with their roles and scopes, so a
+     * tool can act as that user and nobody else.
+     */
+    principal?: Readonly<Principal>;
+    /** Aborted when the run is cancelled or the step times out. A tool that waits should stop with it. */
+    signal?: AbortSignal;
+    /** Long-term memory. In a tenant's run, the tenant's view of it. */
+    store?: Store;
+}
 /** What a tool returned, correlated with the call that asked for it. */
 export interface ToolCallResult {
     /** The id of the call this answers. */

package/dist-cjs/types/principal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Who a request, a run, or a tool call is for.
+ *
+ * One shape everywhere: the server's authentication hook returns it, a run carries it, graph nodes
+ * and workflow steps read it, tools and middleware receive it, and a permission policy can decide on
+ * it. Its tenant scopes threads, runs, budgets, and the store.
+ */
+export interface Principal {
+    /** Isolates threads, runs, and cron jobs. Requests only ever see their own tenant's resources. */
+    tenantId?: string;
+    /** Who the caller is: a token's subject, a key's owner. Recorded on what they create. */
+    userId?: string;
+    /** What the caller may do. A route that names a scope refuses a principal without it. */
+    scopes?: readonly string[];
+    /** The caller's roles, for policies and tools that decide by role rather than by scope. */
+    roles?: readonly string[];
+    /** How the caller was authenticated: `jwt`, `api-key`, `proxy`, or a name of your own. */
+    method?: string;
+    /** The verified claims or attributes the principal was built from, for anything the fields above leave out. */
+    claims?: Readonly<Record<string, unknown>>;
+}

package/dist-cjs/types/principal.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/types/server.d.ts

@@ -6,15 +6,8 @@
  * graph thread, so state, interrupts, and history come from the checkpointer; and an assistant is
  * anything that can stream events for an input, which a compiled graph already does.
  */
-/** Who is making a request, as the server's authentication hook reports them. */
-export interface Principal {
-    /** Isolates threads, runs, and cron jobs. Requests only ever see their own tenant's resources. */
-    tenantId?: string;
-    /** Who the caller is, recorded on what they create. */
-    userId?: string;
-    /** What the caller may do. A route that names a scope refuses a principal without it. */
-    scopes?: readonly string[];
-}
+import type { Principal } from './principal.js';
+export type { Principal };
 /** Where a run stands, as the server reports it. */
 export type RunStatus = 'queued' | 'running' | 'awaiting_input' | 'succeeded' | 'failed' | 'cancelled' | 'expired';
 /** What happens when a run is requested for a thread that is already running one. */

package/dist-cjs/utils/tenant.d.ts

@@ -1,3 +1,4 @@
+import type { Principal } from '../types/principal.js';
 /**
  * The tenant id rule every scope shares. An id is letters, digits, `_`, and `-`, so it can never hold
  * the `/` a scoped name or key is built with: no tenant's prefix is a prefix of another's.
@@ -12,3 +13,13 @@ export declare class TenantIdError extends RangeError {
 export declare function assertTenantId(tenantId: string): string;
 /** @internal The prefix a tenant's names and keys carry in a shared store. */
 export declare function tenantPrefix(tenantId: string): string;
+/**
+ * Run options with the principal's tenant applied: the principal's `tenantId` becomes the run's when
+ * it has none, a run whose two tenants differ is refused, and the principal's `userId` is recorded
+ * in the run's metadata.
+ */
+export declare function withPrincipal<O extends {
+    tenantId?: string;
+    principal?: Principal;
+    metadata?: Record<string, unknown>;
+}>(runOptions: O): O;