@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/kernel/auth/crypto.js

@@ -3,6 +3,7 @@ import { base64ToBytes, bytesToBase64 } from '../util/base64.js';
 export function toBase64Url(bytes) {
     return bytesToBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
+/** Decodes base64url text into bytes. */
 export function fromBase64Url(base64url) {
     let base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
     while (base64.length % 4 !== 0) {
@@ -21,7 +22,7 @@ export function generateCodeVerifier(length = 64) {
         throw new RangeError(`Invalid PKCE code_verifier length: ${length}. RFC 7636 Section 4.1 requires length between 43 and 128 characters.`);
     }
     const validChars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
-    const maxValid = 256 - (256 % validChars.length); // 198 (66 * 3): rejecting above it removes modulo bias
+    const maxValid = 256 - (256 % validChars.length); // why: 198 (66 * 3): rejecting above it removes modulo bias
     let verifier = '';
     const buffer = new Uint8Array(length * 2);
     while (verifier.length < length) {
@@ -93,7 +94,7 @@ async function openBytes(parts, secret, scheme) {
 }
 const STATE_SCHEME = {
     info: STATE_CONTEXT,
-    label: 'OAuth state secret', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    label: 'OAuth state secret', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     associatedData: ENVELOPE_VERSION,
 };
 /** Encrypted, not only signed: the state crosses the browser and the server, and the PKCE verifier must stay secret. */
@@ -101,10 +102,11 @@ export async function sealStatePayload(payload, secret) {
     const envelope = await sealBytes(JSON.stringify(payload), secret, STATE_SCHEME);
     return [ENVELOPE_VERSION, envelope].join('.');
 }
+/** Opens a sealed PKCE state; throws when the secret or the seal is wrong. */
 export async function unsealStatePayload(sealed, secret) {
     const [version, ...parts] = sealed.split('.');
     if (version !== ENVELOPE_VERSION || parts.length !== 3) {
-        throw new Error('Invalid sealed state format'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error('Invalid sealed state format'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const plaintext = await openBytes(parts, secret, STATE_SCHEME);
     if (plaintext === null) {
@@ -112,23 +114,23 @@ export async function unsealStatePayload(sealed, secret) {
     }
     const payload = JSON.parse(plaintext);
     if (!Array.isArray(payload.scopes)) {
-        throw new Error('Invalid sealed state format'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error('Invalid sealed state format'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     if (Date.now() > payload.expiresAt) {
-        throw new Error('OAuth state has expired'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error('OAuth state has expired'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return payload;
 }
 function secretScheme(keyVersion, binding) {
     return {
         info: SEAL_CONTEXT,
-        label: 'Secret sealing key', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        label: 'Secret sealing key', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         associatedData: JSON.stringify([ENVELOPE_VERSION, keyVersion, binding]),
     };
 }
 function assertKeyVersion(keyVersion) {
     if (!Number.isSafeInteger(keyVersion) || keyVersion < 0) {
-        throw new RangeError(`Key version must be a non-negative integer; got ${keyVersion}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new RangeError(`Key version must be a non-negative integer; got ${keyVersion}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
 }
 /**
@@ -142,16 +144,16 @@ export async function sealSecret(input) {
     const envelope = await sealBytes(input.plaintext, input.key, scheme);
     return [ENVELOPE_VERSION, String(input.keyVersion), envelope].join('.');
 }
-/** Opens what `sealSecret` sealed; throws when the envelope, key version or binding does not match. */
+/** Opens what `sealSecret` sealed; throws when the envelope, key version, or binding does not match. */
 export async function openSecret(input) {
     const [version, keyVersionText, ...parts] = input.sealed.split('.');
     const keyVersion = Number(keyVersionText);
     if (version !== ENVELOPE_VERSION || parts.length !== 3 || !/^\d+$/.test(keyVersionText ?? '')) {
-        throw new Error('Invalid sealed secret format'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error('Invalid sealed secret format'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const key = input.keys[keyVersion];
     if (key === undefined) {
-        throw new Error(`No key for sealed secret key version ${keyVersion}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`No key for sealed secret key version ${keyVersion}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const plaintext = await openBytes(parts, key, secretScheme(keyVersion, input.binding));
     if (plaintext === null) {

package/esm/src/kernel/auth/oauth.d.ts

@@ -3,7 +3,7 @@ import type { AuthorizationServerMetadata, CreatePkceFlowOptions, ExchangePkceCo
 export declare function discoverResourceMetadata(resourceUrl: string, transport?: OAuthTransportOptions): Promise<ProtectedResourceMetadata | undefined>;
 /** A non-OK URL moves on to the next; metadata that answers but fails validation is refused outright. */
 export declare function discoverAuthServerMetadata(issuer: string, transport?: OAuthTransportOptions): Promise<AuthorizationServerMetadata>;
-/** Stateless: the verifier, expected issuer, token endpoint and resource are sealed into `state`. */
+/** Stateless: the verifier, expected issuer, token endpoint, and resource are sealed into `state`. */
 export declare function createOAuthPkceFlow(options: CreatePkceFlowOptions): Promise<PkceFlowResult>;
 /** RFC 9207 §2.4: `iss` is required when the server advertises it, and byte-exact (no URL normalization). */
 export declare function validateIssuer(expectedIssuer: string, receivedIss: string | undefined, issRequired: boolean): void;
@@ -12,6 +12,7 @@ export declare function validateIssuer(expectedIssuer: string, receivedIss: stri
  * and a valid `iss` (RFC 9207); posts to the token endpoint sealed in `state`, never a caller's.
  */
 export declare function exchangeOAuthPkce(options: ExchangePkceCodeOptions): Promise<ExchangePkceCodeResult>;
+/** Exchanges a refresh token for new tokens at the token endpoint; both the endpoint and the resource must be https URLs. */
 export declare function refreshOAuthToken(options: RefreshOAuthTokenOptions): Promise<ExchangePkceCodeResult>;
 /** RFC 8707: the same origin, and the resource's path or below it. */
 export declare function tokenAudienceCovers(resource: string, url: URL): boolean;

package/esm/src/kernel/auth/oauth.js

@@ -14,17 +14,17 @@ function oauthFetch(url, init, transport) {
 /** RFC 8414 §2, RFC 9728 §1.2, OAuth 2.1 §1.5: an absolute `https` URL without a fragment. */
 function httpsUrl(value, what) {
     if (typeof value !== 'string') {
-        throw new Error(`OAuth ${what} is missing`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`OAuth ${what} is missing`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     let url;
     try {
         url = new URL(value);
     }
     catch {
-        throw new Error(`OAuth ${what} "${value}" is not a URL`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`OAuth ${what} "${value}" is not a URL`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     if (url.protocol !== 'https:' || url.hash) {
-        throw new Error(`OAuth ${what} "${value}" must be an https URL without a fragment`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`OAuth ${what} "${value}" must be an https URL without a fragment`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return url;
 }
@@ -40,7 +40,7 @@ function assertRedirectUri(value) {
         url = new URL(value);
     }
     catch {
-        throw new Error(`OAuth redirect_uri "${value}" is not an absolute URI`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`OAuth redirect_uri "${value}" is not an absolute URI`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const scheme = url.protocol.slice(0, -1);
     const allowed = scheme === 'https' ||
@@ -50,12 +50,12 @@ function assertRedirectUri(value) {
         throw new Error(`OAuth redirect_uri "${value}" must be https, http on loopback, or a reverse-domain app scheme, without a fragment`);
     }
 }
-/** RFC 6749 §3.3: a scope token is one or more printable ASCII characters other than space, `"` and `\`. */
+/** RFC 6749 §3.3: a scope token is one or more printable ASCII characters other than space, `"`, and `\`. */
 const SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
 function assertScopeTokens(scopes) {
     for (const scope of scopes) {
         if (!SCOPE_TOKEN.test(scope)) {
-            throw new Error(`OAuth scope "${scope}" is not a single RFC 6749 scope token`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            throw new Error(`OAuth scope "${scope}" is not a single RFC 6749 scope token`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
     }
 }
@@ -80,7 +80,7 @@ function assertAuthorizationParams(params) {
 /** A client id that is a URL is a Client ID Metadata Document, which is served over https. */
 function assertClientId(clientId) {
     if (clientId.length === 0) {
-        throw new Error('OAuth client_id is missing'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error('OAuth client_id is missing'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     if (/^https?:/i.test(clientId))
         httpsUrl(clientId, 'client_id');
@@ -95,14 +95,14 @@ function stringList(data, field) {
     if (value === undefined)
         return undefined;
     if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string')) {
-        throw new Error(`OAuth metadata "${field}" must be a list of strings`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`OAuth metadata "${field}" must be a list of strings`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return value;
 }
 async function metadataObject(response, url) {
     const data = await response.json();
     if (!isRecord(data)) {
-        throw new Error(`OAuth metadata at ${url} is not a JSON object`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`OAuth metadata at ${url} is not a JSON object`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return data;
 }
@@ -173,7 +173,7 @@ function authServerMetadataUrls(issuer) {
 export async function discoverAuthServerMetadata(issuer, transport = {}) {
     const issuerUrl = httpsUrl(issuer, 'issuer');
     if (issuerUrl.search) {
-        throw new Error(`OAuth issuer "${issuer}" must not have a query`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`OAuth issuer "${issuer}" must not have a query`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     for (const url of authServerMetadataUrls(issuerUrl)) {
         const response = await oauthFetch(url, { headers: { Accept: 'application/json' } }, transport);
@@ -183,7 +183,7 @@ export async function discoverAuthServerMetadata(issuer, transport = {}) {
         }
         return parseAuthServerMetadata(await metadataObject(response, url), issuer, url);
     }
-    throw new Error(`Failed to discover authorization server metadata for "${issuer}"`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    throw new Error(`Failed to discover authorization server metadata for "${issuer}"`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
 }
 /** A resource that publishes no metadata is its own authorization server. */
 async function discoverEndpoints(resourceServerUrl, transport) {
@@ -200,14 +200,14 @@ async function discoverEndpoints(resourceServerUrl, transport) {
         issParameterSupported: asMeta.authorization_response_iss_parameter_supported === true,
     };
 }
-/** Stateless: the verifier, expected issuer, token endpoint and resource are sealed into `state`. */
+/** Stateless: the verifier, expected issuer, token endpoint, and resource are sealed into `state`. */
 export async function createOAuthPkceFlow(options) {
     const endpoints = options.preResolved ?? (await discoverEndpoints(options.resourceServerUrl, options));
     httpsUrl(endpoints.issuer, 'issuer');
     const authUrl = httpsUrl(endpoints.authorizationEndpoint, 'authorization_endpoint');
     const tokenEndpoint = httpsUrl(endpoints.tokenEndpoint, 'token_endpoint').href;
     const { issuer } = endpoints;
-    // RFC 8707 audience: always the resource the flow is for; discovery required its metadata to match.
+    // why: RFC 8707 audience: always the resource the flow is for; discovery required its metadata to match.
     httpsUrl(options.resourceServerUrl, 'resource');
     const resource = options.resourceServerUrl;
     assertClientId(options.clientId);
@@ -218,7 +218,7 @@ export async function createOAuthPkceFlow(options) {
         assertAuthorizationParams(options.authorizationParams);
     const ttl = options.stateTtlMs ?? 10 * 60 * 1000;
     if (!Number.isFinite(ttl) || ttl <= 0) {
-        throw new RangeError(`OAuth stateTtlMs must be a positive number of milliseconds; got ${ttl}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new RangeError(`OAuth stateTtlMs must be a positive number of milliseconds; got ${ttl}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const sessionBinding = await sessionBindingDigest(options.sessionBinding);
     const codeVerifier = generateCodeVerifier();
@@ -259,7 +259,7 @@ export async function createOAuthPkceFlow(options) {
 /** SHA-256 of the host's session binding, so the raw value never enters the state. */
 async function sessionBindingDigest(binding) {
     if (binding.length === 0) {
-        throw new Error('OAuth sessionBinding must be a non-empty value tied to the user session'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error('OAuth sessionBinding must be a non-empty value tied to the user session'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(binding));
     return toBase64Url(new Uint8Array(digest));
@@ -306,26 +306,26 @@ async function tokenErrorText(response) {
 }
 function parseTokenResponse(data, tokenEndpoint) {
     const fail = (why) => {
-        throw new Error(`Token response from ${tokenEndpoint} ${why}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`Token response from ${tokenEndpoint} ${why}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     };
     if (!isRecord(data)) {
-        return fail('is not a JSON object'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return fail('is not a JSON object'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const tokens = data;
     if (typeof tokens.access_token !== 'string' || tokens.access_token.length === 0) {
-        fail('has no access_token'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        fail('has no access_token'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     if (typeof tokens.token_type !== 'string' || tokens.token_type.toLowerCase() !== 'bearer') {
-        fail(`has token_type "${String(tokens.token_type)}", not Bearer`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        fail(`has token_type "${String(tokens.token_type)}", not Bearer`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const expiresIn = tokens.expires_in;
     if (expiresIn !== undefined &&
         (typeof expiresIn !== 'number' || !Number.isFinite(expiresIn) || expiresIn < 0)) {
-        fail('has an expires_in that is not a number of seconds'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        fail('has an expires_in that is not a number of seconds'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     for (const field of ['refresh_token', 'scope']) {
         if (tokens[field] !== undefined && typeof tokens[field] !== 'string') {
-            fail(`has a ${field} that is not a string`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            fail(`has a ${field} that is not a string`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
     }
     return tokens;
@@ -365,7 +365,7 @@ async function requestToken(transport, grant, params, requested, previous) {
         body: body.toString(),
     }, transport);
     if (!response.ok) {
-        const failed = previous ? 'Token refresh failed' : 'Token exchange failed'; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        const failed = previous ? 'Token refresh failed' : 'Token exchange failed'; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         throw new Error(`${failed} at ${grant.tokenEndpoint} (HTTP ${response.status})${await tokenErrorText(response)}`);
     }
     const tokens = parseTokenResponse(await response.json(), grant.tokenEndpoint);
@@ -407,6 +407,7 @@ export async function exchangeOAuthPkce(options) {
         code_verifier: state.codeVerifier,
     }, state.scopes);
 }
+/** Exchanges a refresh token for new tokens at the token endpoint; both the endpoint and the resource must be https URLs. */
 export function refreshOAuthToken(options) {
     httpsUrl(options.tokenEndpoint, 'token_endpoint');
     httpsUrl(options.resource, 'resource');

package/esm/src/kernel/auth/typed-secret.js

@@ -6,7 +6,7 @@ import { TheoremError } from '../../guardrails/error.js';
 export function credentialFromTypedSecret(authType, secret) {
     const value = typeof secret === 'string' ? secret.trim() : '';
     if (!value) {
-        throw new TheoremError('request', 'A typed credential must be a non-empty string'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new TheoremError('request', 'A typed credential must be a non-empty string'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     if (authType === 'bearer')
         return { type: 'bearer', token: value };
@@ -17,7 +17,7 @@ export function credentialFromTypedSecret(authType, secret) {
 /** `auth` is absent on any gate other than sign-in, which takes no key. */
 export function credentialForSignInGate(auth, secret) {
     if (!auth) {
-        throw new TheoremError('request', 'a typed credential answers only a sign-in gate'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new TheoremError('request', 'a typed credential answers only a sign-in gate'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return { slot: auth.slot, credential: credentialFromTypedSecret(auth.authType, secret) };
 }

package/esm/src/kernel/auth/types.d.ts

@@ -23,6 +23,7 @@ export interface AuthorizationServerMetadata {
     client_id_metadata_document_supported?: boolean;
     [key: string]: unknown;
 }
+/** The tokens an OAuth server returns. */
 export interface OAuthTokens {
     access_token: string;
     token_type?: string;
@@ -31,6 +32,7 @@ export interface OAuthTokens {
     scope?: string;
     [key: string]: unknown;
 }
+/** An OAuth sign-in a tool authenticates with. */
 export interface OAuth2Credential {
     type: 'oauth2';
     issuer: string;
@@ -44,16 +46,21 @@ export interface OAuth2Credential {
     clientId: string;
     scope?: string;
 }
+/** A bearer token a tool authenticates with. */
 export interface BearerCredential {
     type: 'bearer';
     token: string;
 }
+/** An API key a tool authenticates with. */
 export interface ApiKeyCredential {
     type: 'api_key';
     key: string;
+    /** The header the key goes in; a tool whose `auth.queryParam` puts it in the URL ignores it. */
     headerName?: string;
+    /** Text put before the key in the header; ignored as `headerName` is. */
     headerPrefix?: string;
 }
+/** Any credential a tool can authenticate with. */
 export type ToolCredential = OAuth2Credential | BearerCredential | ApiKeyCredential;
 /** Every discovery and token request clears the network policy and never follows a redirect. */
 export interface OAuthTransportOptions {
@@ -63,6 +70,7 @@ export interface OAuthTransportOptions {
     resolveHost?: ResolveHost;
     fetchFn?: typeof fetch;
 }
+/** The endpoints of an OAuth authorization server. */
 export interface OAuthEndpoints {
     issuer: string;
     authorizationEndpoint: string;
@@ -70,6 +78,7 @@ export interface OAuthEndpoints {
     /** RFC 9207: authorization responses without `iss` are then refused. */
     issParameterSupported?: boolean;
 }
+/** Options for starting a PKCE authorization. */
 export interface CreatePkceFlowOptions extends OAuthTransportOptions {
     /**
      * An https URL (e.g. the MCP server) and the token's audience (RFC 8707). Without
@@ -103,6 +112,7 @@ export interface CreatePkceFlowOptions extends OAuthTransportOptions {
      */
     authorizationParams?: Readonly<Record<string, string>>;
 }
+/** A started PKCE authorization: the URL to send the user to and the values to keep. */
 export interface PkceFlowResult {
     authorizationUrl: string;
     state: string;
@@ -110,6 +120,7 @@ export interface PkceFlowResult {
     issuer: string;
     resource: string;
 }
+/** Options for trading an authorization code for tokens. */
 export interface ExchangePkceCodeOptions extends OAuthTransportOptions {
     code: string;
     state: string;
@@ -123,10 +134,12 @@ export interface ExchangePkceCodeOptions extends OAuthTransportOptions {
     /** A confidential client's secret, sent in the token request body (RFC 6749 §2.3.1); never stored. */
     clientSecret?: string;
 }
+/** The tokens and credential a PKCE exchange yields. */
 export interface ExchangePkceCodeResult {
     tokens: OAuthTokens;
     credential: OAuth2Credential;
 }
+/** Options for refreshing an OAuth access token. */
 export interface RefreshOAuthTokenOptions extends OAuthTransportOptions {
     refreshToken: string;
     tokenEndpoint: string;

package/esm/src/kernel/checkpoint.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { type JsonValue } from './json.js';
+import type { TurnHistoryMessage } from './turn-events.js';
+/**
+ * A protocol's saved continuation, and what it was saved for. It is used only when the next call
+ * goes to the same protocol, provider registration, connection, model, key slot, and keyed options.
+ */
+export interface ProviderCheckpoint {
+    protocol: string;
+    provider: string;
+    /** The protocol's `continuation.version` the data was written under. */
+    version: number;
+    apiId: string;
+    /** The slot whose key the saved state belongs to. */
+    keySlot?: string;
+    /** Hash of the provider's connection and the options the protocol keys its state on. */
+    compatibilityKey: string;
+    coveredHistoryLength: number;
+    coveredHistoryHash: string;
+    data: JsonValue;
+    /** The wire's own id for each Theorem call id the saved state holds, sent back in its place. */
+    wireCallIds?: Record<string, string>;
+}
+export declare const providerCheckpointSchema: z.ZodType<ProviderCheckpoint>;
+/** Why a saved continuation was dropped and the conversation sent from the transcript. */
+export type ProviderStateRebuilt = 'provider_changed' | 'model_changed' | 'connection_changed' | 'key_changed' | 'history_changed' | 'version_changed';
+export interface ProviderWarning {
+    code: 'provider_state_rebuilt';
+    reason: ProviderStateRebuilt;
+}
+export declare const providerWarningSchema: z.ZodType<ProviderWarning>;
+export interface ProviderContinuationPolicy {
+    /**
+     * Who holds the conversation a checkpoint continues. `'host'` (unset) passes the covered
+     * history back with the checkpoint. `'provider'` passes the checkpoint alone: the provider's
+     * stored conversation is the history, and a turn that goes elsewhere needs the host's history.
+     * `'stateless'` keeps no conversation: a request that carries history or a checkpoint is refused,
+     * and completion carries no checkpoint.
+     */
+    history?: 'host' | 'stateless' | 'provider';
+}
+export declare const providerContinuationSchema: z.ZodType<ProviderContinuationPolicy>;
+export declare function historyHash(history: readonly TurnHistoryMessage[]): Promise<string>;

package/esm/src/kernel/checkpoint.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { jsonValueSchema } from './json.js';
+export const providerCheckpointSchema = z.strictObject({
+    protocol: z.string().min(1),
+    provider: z.string().min(1),
+    version: z.number().int().positive(),
+    apiId: z.string().min(1),
+    keySlot: z.string().min(1).optional(),
+    compatibilityKey: z.string(),
+    coveredHistoryLength: z.number().int().nonnegative(),
+    coveredHistoryHash: z.string(),
+    data: jsonValueSchema,
+    wireCallIds: z.record(z.string().min(1), z.string().min(1)).optional(),
+});
+export const providerWarningSchema = z.strictObject({
+    code: z.literal('provider_state_rebuilt'),
+    reason: z.enum([
+        'provider_changed',
+        'model_changed',
+        'connection_changed',
+        'key_changed',
+        'history_changed',
+        'version_changed',
+    ]),
+});
+export const providerContinuationSchema = z.strictObject({
+    history: z.enum(['host', 'stateless', 'provider']).optional(),
+});
+export async function historyHash(history) {
+    const stable = (value) => {
+        if (Array.isArray(value))
+            return value.map(stable);
+        if (value && typeof value === 'object') {
+            const ordered = {};
+            for (const key of Object.keys(value).sort())
+                ordered[key] = stable(value[key]);
+            return ordered;
+        }
+        return value;
+    };
+    const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(stable(history.map((message) => {
+        const canonicalText = (text) => message.role === 'user'
+            ? (text.match(/^<user_data>\n([\s\S]*)\n<\/user_data>$/)?.[1] ?? text)
+            : text;
+        const parts = [
+            ...(message.content === undefined
+                ? []
+                : [{ type: 'text', text: canonicalText(message.content) }]),
+            ...(message.parts ?? []).map((part) => part.type === 'text' ? { ...part, text: canonicalText(part.text) } : part),
+        ];
+        const { content: _content, parts: _parts, ...rest } = message;
+        return { ...rest, ...(parts.length ? { parts } : {}) };
+    })))));
+    let hex = '';
+    for (const byte of new Uint8Array(hash))
+        hex += byte.toString(16).padStart(2, '0');
+    return hex;
+}

package/esm/src/kernel/default-scope.d.ts

@@ -1,34 +1,72 @@
 import type { TraceSink } from '../observability/trace-sink.js';
 import type { RunDecisionOptions } from './engine/decision.js';
+import type { RunEmbeddingOptions } from './engine/embedding.js';
 import type { RunSessionOptions } from './engine/session/mod.js';
+import type { Protocol } from './protocols/protocol.js';
+import type { Provider, RegisteredProvider, Registration } from './protocols/provider.js';
+import type { ProviderHostOptions } from './protocols/runtime.js';
 import type { ProfileDefinition } from './registry/profiles.js';
 import { defaultKernelScope as scope } from './scope.js';
-import type { InvokeToolRequest, RegisteredTool, ToolDefinitionInput } from './tools/types.js';
-import type { CompactHistoryRequest, CompactionResult, DecisionRequest, DecisionResult, LiveSession, ModelProvider, Profile, ProjectedProfile, SessionRequest, StructuredSpec, TurnEvent, TurnRequest } from './types.js';
+import type { ToolCallResult, ToolStepCallResult } from './tools/run.js';
+import type { InvokeToolRequest, InvokeToolStepRequest, RegisteredTool, ToolDefinitionInput } from './tools/types.js';
+import type { CompactHistoryRequest, CompactionResult, DecisionRequest, DecisionResult, EmbeddingRequest, EmbeddingResult, LiveSession, Profile, ProjectedProfile, SessionRequest, StructuredSpec, TurnEvent, TurnRequest } from './types.js';
 /** Register or replace a tool in the default scope. */
 declare function registerTool<TIn, TOut>(def: ToolDefinitionInput<TIn, TOut>): RegisteredTool<TIn, TOut>;
+/** Register or replace several tools in the default scope. */
 declare function registerTools(defs: ToolDefinitionInput[]): RegisteredTool[];
+/** The default scope's tool `name`, or `undefined`. */
 declare function getTool(name: string): RegisteredTool | undefined;
+/** The default scope's tool `name`; throws when there is none. */
 declare function requireTool(name: string): RegisteredTool;
+/** True when the default scope has a tool `name`. */
 declare function hasTool(name: string): boolean;
+/** Every tool in the default scope. */
 declare function listTools(): RegisteredTool[];
+/** Remove every tool from the default scope. */
 declare function resetTools(): void;
 /** Define, validate, and register a profile in the default scope. */
 declare function registerProfile(profile: Profile | ProfileDefinition): void;
+/** Define, validate, and register several profiles in the default scope. */
 declare function registerProfiles(profiles: Array<Profile | ProfileDefinition>): void;
 /** The default scope's profile `id`; throws when there is none. */
 declare function getProfile(id: string): Profile;
+/** True when the default scope has a profile `id`. */
 declare function hasProfile(id: string): boolean;
+/** Every profile in the default scope. */
 declare function listProfiles(): Profile[];
+/** Remove every profile from the default scope. */
 declare function clearProfiles(): void;
+/** Register a structured-output schema in the default scope under `id`. */
 declare function registerStructured(id: string, spec: StructuredSpec): void;
 /** The default scope's schema `id`; throws when there is none. */
 declare function getStructured(id: string): StructuredSpec;
-declare function runTurn(req: TurnRequest, provider: ModelProvider, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/** Run one turn of a profile in the default scope, streaming its events. */
+declare function runTurn(req: TurnRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/** Open a live session for a live profile in the default scope. */
 declare function runSession(req: SessionRequest, options: RunSessionOptions, sinkOverride?: TraceSink): Promise<LiveSession>;
-declare function compactHistory(req: CompactHistoryRequest, provider: ModelProvider, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
+/** Compact a conversation history with the model, or `undefined` when there is nothing to compact. */
+declare function compactHistory(req: CompactHistoryRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
+/** Run a held tool call in the default scope, streaming the events of the turn it resumes. */
 declare function invokeTool(request: InvokeToolRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/** Run the host's calls as one step in the default scope, streaming each call's events as they come. */
+declare function invokeToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/** Run one tool call in the default scope to its end: how it settled, with every event it emitted. */
+declare function runTool(request: InvokeToolRequest, sinkOverride?: TraceSink): Promise<ToolCallResult>;
+/** Run the host's calls as one step in the default scope, giving each call's end as it settles. */
+declare function runToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<ToolStepCallResult>;
+/** Resolve a turn request in the default scope: its profile, model, and generation settings. */
 declare function resolveTurn(req: TurnRequest): ReturnType<typeof scope.resolveTurn>;
+/** Each model of profile `id` in the default scope that cannot run a plain turn on its provider, and why. */
+/** The profile `id` projected for a client, with server-only fields removed. */
 declare function projectProfile(id: string): ProjectedProfile;
+/** Answer a decision request with the profile's model in the default scope. */
 declare function runDecision(request: DecisionRequest, options: RunDecisionOptions): Promise<DecisionResult>;
-export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runSession, runTurn, };
+/** Create vectors for one or more inputs in the default scope. */
+declare function runEmbedding(request: EmbeddingRequest, options?: RunEmbeddingOptions): Promise<EmbeddingResult>;
+export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, invokeToolStep, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runEmbedding, runSession, runTool, runToolStep, runTurn, };
+/** Registers a provider in the default scope, with this project's connection and key slots. */
+export declare function registerProvider<C, K>(provider: Provider<C, K>, registration?: Registration<C>): RegisteredProvider;
+export declare function getProvider(id: string): RegisteredProvider | undefined;
+export declare function listProviders(): RegisteredProvider[];
+/** Every protocol the default scope's providers serve. */
+export declare function listProtocols(): Protocol[];