@crouter/sdk 0.3.377

package/dist/oauth/index.js

@@ -0,0 +1,377 @@
+import { calculateJwkThumbprint, decodeJwt, decodeProtectedHeader, exportJWK, importJWK, importPKCS8, SignJWT } from 'jose';
+import { JwksCache, parseScope, verifyIdToken } from '@crouter/identity';
+import { APIError, CrouterError, mapError } from '../errors.js';
+import { Crouter } from '../client.js';
+/** Refresh refusals the app must answer by reconnecting; each latches the connected client (SDK-AUTH-17). */
+const reconnectCodes = new Set(['grant_revoked', 'grant_removed', 'grant_suspended', 'refresh_token_expired', 'refresh_token_reused']);
+const refusals = {
+    grant_removed: 'removed', grant_suspended: 'paused',
+    refresh_token_expired: 'reconnect', refresh_token_reused: 'reconnect', grant_revoked: 'reconnect',
+};
+/** What a refused refresh means (`RefreshRefusal`), or `null` when `error` is not the directory refusing one.
+ *  Takes any error a connected client or `refresh` threw; only `APIError` with `origin: 'directory'` counts. */
+export function refreshRefusal(error) {
+    if (!(error instanceof APIError) || error.origin !== 'directory')
+        return null;
+    return Object.hasOwn(refusals, error.code) ? refusals[error.code] : null;
+}
+export class MemoryConnectionStore {
+    connections = new Map();
+    locks = new Map();
+    savedAt = new Map();
+    async load(userId) { return this.connections.get(userId) ?? null; }
+    async save(connection) {
+        this.connections.set(connection.userId, connection);
+        this.savedAt.set(connection.userId, Date.now());
+    }
+    async listStale(before) {
+        return [...this.connections.values()].filter((connection) => (this.savedAt.get(connection.userId) ?? Infinity) < before.getTime());
+    }
+    async lock(userId, fn) {
+        const prior = this.locks.get(userId);
+        let release;
+        const done = new Promise((resolve) => { release = resolve; });
+        this.locks.set(userId, done);
+        await prior;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+            if (this.locks.get(userId) === done)
+                this.locks.delete(userId);
+        }
+    }
+}
+/** The `profile` claims a verified ID token carries, each only when present: use it on `Connection.idToken` after `verifyIdToken` for a sign-in that requested runtime scopes (`exchangeCode`), as `exchangeIdentity` does for a sign-in-only one. */
+export function profileFromClaims(claims) {
+    const text = (value) => typeof value === 'string' && value !== '' ? value : undefined;
+    const [name, givenName, familyName, picture] = [text(claims.name), text(claims.given_name), text(claims.family_name), httpsUrl(claims.picture)];
+    return { ...(name ? { name } : {}), ...(givenName ? { givenName } : {}), ...(familyName ? { familyName } : {}), ...(picture ? { picture } : {}) };
+}
+/** `value` when it is a string parsing as an `https:` URL, else undefined: a `picture` claim is rendered as an image source, so no other scheme gets through. */
+function httpsUrl(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    try {
+        return new URL(value).protocol === 'https:' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const assertionType = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
+export class OAuth2Client {
+    options;
+    issuer;
+    fetcher;
+    jwks;
+    discoveryPromise;
+    inFlight = new Map();
+    constructor(options) {
+        this.options = options;
+        if (!options.issuer || !options.issuer.trim())
+            throw new CrouterError('OAuth2Client requires an issuer');
+        this.issuer = options.issuer;
+        this.fetcher = options.fetch ?? fetch;
+    }
+    discovery() {
+        this.discoveryPromise ??= (async () => {
+            const response = await this.fetcher(`${this.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`);
+            if (!response.ok)
+                throw new CrouterError(`Directory discovery failed: ${response.status}`);
+            const value = await response.json();
+            if (!value.authorization_endpoint || !value.token_endpoint || !value.jwks_uri)
+                throw new CrouterError('Directory discovery has missing endpoints');
+            return value;
+        })();
+        return this.discoveryPromise;
+    }
+    /** Start a sign-in. When `scopes` includes `openid` the result carries the `nonce` to pass to the exchange; with literal scopes its type is `string`.
+     * `prompt: 'consent'` makes the directory show its consent screen even when the person already approved these scopes. */
+    async authorizeUrl({ scopes, state, codeVerifier, prompt }) {
+        for (const scope of scopes) {
+            if (scope === 'openid' || scope === 'email' || scope === 'profile')
+                continue;
+            try {
+                parseScope(scope);
+            }
+            catch {
+                throw new APIError(400, 'invalid_scope', `Unsupported scope: ${scope}`);
+            }
+        }
+        const verifier = codeVerifier ?? randomBase64url(32);
+        const nonce = scopes.includes('openid') ? randomBase64url(32) : undefined;
+        const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+        const challenge = base64url(new Uint8Array(hash));
+        const url = new URL((await this.discovery()).authorization_endpoint);
+        url.search = new URLSearchParams({
+            client_id: this.options.clientId, response_type: 'code', redirect_uri: this.options.redirectUri,
+            scope: scopes.join(' '), state, code_challenge: challenge, code_challenge_method: 'S256',
+            ...(nonce ? { nonce } : {}), ...(prompt === undefined ? {} : { prompt }),
+        }).toString();
+        return { url: url.href, codeVerifier: verifier, state, ...(nonce ? { nonce } : {}) };
+    }
+    /**
+     * Finish a sign-in that asked for runtime scopes and return the person's `Connection`. A sign-in-only
+     * request (`openid`, `openid email`, `openid profile`, or `openid email profile`) gets no connection from the directory; finish it with
+     * `exchangeIdentity`, which this method names when it receives such a response.
+     */
+    async exchangeCode({ code, codeVerifier, state, expectedState, nonce }) {
+        assertState(state, expectedState);
+        const response = await this.tokenResponse({ grant_type: 'authorization_code', code, redirect_uri: this.options.redirectUri, code_verifier: codeVerifier });
+        if (response.refresh_token === undefined && response.runtimeUrl === undefined && typeof response.id_token === 'string') {
+            throw new CrouterError('The directory answered a sign-in-only request (openid, optionally with email and profile) with an identity and no connection; finish a sign-in-only request with exchangeIdentity(), not exchangeCode()', 'oauth_exchange_mismatch');
+        }
+        const connection = this.connectionFrom(response);
+        if (connection.idToken) {
+            const claims = await this.verifyIdToken(connection.idToken, { nonce });
+            if (typeof claims.nonce !== 'string' || claims.nonce !== nonce)
+                throw new CrouterError('ID token nonce is missing or does not match', 'id_token_invalid');
+        }
+        return connection;
+    }
+    /**
+     * Finish a sign-in-only request (`authorizeUrl` with scopes `openid` or `openid email`) and return the
+     * person's verified identity. There is no connection, refresh token, or runtime access on this path.
+     * `nonce` is the value `authorizeUrl` returned and is required. A response without an ID token, or with
+     * one that fails verification, throws `id_token_invalid`; a response carrying a runtime connection (the
+     * request asked for runtime scopes) throws `oauth_exchange_mismatch` and must be finished with `exchangeCode`.
+     */
+    async exchangeIdentity({ code, codeVerifier, state, expectedState, nonce }) {
+        assertState(state, expectedState);
+        if (typeof nonce !== 'string' || !nonce)
+            throw new CrouterError('exchangeIdentity requires the nonce authorizeUrl returned', 'oauth_nonce_missing');
+        const response = await this.tokenResponse({ grant_type: 'authorization_code', code, redirect_uri: this.options.redirectUri, code_verifier: codeVerifier });
+        if (response.refresh_token !== undefined || response.runtimeUrl !== undefined) {
+            throw new CrouterError('The directory answered with a runtime connection, so the request asked for runtime scopes; finish it with exchangeCode(), or request only openid or openid email for a sign-in-only visitor', 'oauth_exchange_mismatch');
+        }
+        if (typeof response.id_token !== 'string' || !response.id_token)
+            throw new CrouterError('Directory returned no ID token for a sign-in-only request', 'id_token_invalid');
+        const claims = await this.verifyIdToken(response.id_token, { nonce });
+        return {
+            sub: claims.sub,
+            ...(typeof claims['email'] === 'string' ? { email: claims['email'] } : {}),
+            ...(typeof claims['email_verified'] === 'boolean' ? { emailVerified: claims['email_verified'] } : {}),
+            ...profileFromClaims(claims),
+            claims,
+        };
+    }
+    /** Refresh a store's idle connections once. The app owns scheduling; failures remain visible to its worker,
+     *  each with `reason` set when the directory refused that connection's refresh (see `RefreshRefusal`). */
+    async refreshIdleConnections(store, { olderThanMs }) {
+        if (!store.listStale)
+            throw new CrouterError('ConnectionStore.listStale(before) is required to refresh idle connections');
+        if (!Number.isFinite(olderThanMs) || olderThanMs <= 0)
+            throw new CrouterError('olderThanMs must be a positive number');
+        const stale = await store.listStale(new Date(Date.now() - olderThanMs));
+        let refreshed = 0;
+        const failures = [];
+        for (const connection of stale) {
+            try {
+                // refresh() holds the cross-process store lock and reloads before rotating.
+                const current = await this.refresh(connection, store);
+                if (current.refreshToken !== connection.refreshToken)
+                    refreshed++;
+            }
+            catch (error) {
+                failures.push({ userId: connection.userId, error, reason: refreshRefusal(error) });
+            }
+        }
+        return { refreshed, failures };
+    }
+    async refresh(connection, store) {
+        const existing = this.inFlight.get(connection.userId);
+        if (existing)
+            return existing;
+        const rotate = async () => {
+            const stored = await store?.load(connection.userId);
+            if (stored && stored.refreshToken !== connection.refreshToken)
+                return stored;
+            const updated = this.connectionFrom(await this.tokenResponse({ grant_type: 'refresh_token', refresh_token: connection.refreshToken }), connection);
+            await store?.save(updated);
+            return updated;
+        };
+        const pending = store?.lock ? store.lock(connection.userId, rotate) : rotate();
+        this.inFlight.set(connection.userId, pending);
+        try {
+            return await pending;
+        }
+        finally {
+            this.inFlight.delete(connection.userId);
+        }
+    }
+    client(connection, store) {
+        let current = connection;
+        let revoked;
+        const refresh = async (force) => {
+            if (revoked)
+                throw revoked;
+            if (!force && current.accessToken && current.accessTokenExpiresAt - Date.now() > 30_000)
+                return;
+            try {
+                current = await this.refresh(current, store);
+            }
+            catch (error) {
+                if (error instanceof APIError && reconnectCodes.has(error.code))
+                    revoked = error;
+                throw error;
+            }
+        };
+        return new Crouter({
+            baseURL: connection.runtimeUrl,
+            tokenSource: async () => { await refresh(false); return current.accessToken; },
+            onUnauthorized: async () => { await refresh(true); },
+        });
+    }
+    /** Verify an ID token: ES256 signature against the discovered JWKS, `iss`, `aud` = client id, `exp`, and `nonce` when given. A token that fails any check throws `id_token_invalid`; a JWKS that can't be fetched or is malformed rethrows that error. */
+    async verifyIdToken(idToken, { nonce } = {}) {
+        const discovery = await this.discovery();
+        this.jwks ??= new JwksCache(this.issuer, this.fetcher, discovery.jwks_uri);
+        const invalid = (reason) => new CrouterError(`ID token failed verification: ${reason}`, 'id_token_invalid');
+        try {
+            decodeProtectedHeader(idToken);
+        }
+        catch {
+            throw invalid('it is not a signed JWT');
+        }
+        let claims;
+        try {
+            claims = await verifyIdToken({ token: idToken, jwks: this.jwks, issuer: this.issuer, audience: this.options.clientId });
+        }
+        catch (error) {
+            // A token that fails verification is id_token_invalid; a JWKS that cannot be fetched or is malformed is the
+            // directory's fault, not the token's, and is rethrown as is. jose's token errors (bad signature, wrong iss/aud,
+            // expired, no matching key) carry an ERR_J* code; ERR_JWKS_INVALID and ERR_JWKS_TIMEOUT describe the key set.
+            // The identity package's own checks throw "Invalid ID token …". Duck-typed, since jose may be a separate copy.
+            const joseCode = error?.code;
+            const message = error instanceof Error ? error.message : String(error);
+            const keySetFault = joseCode === 'ERR_JWKS_INVALID' || joseCode === 'ERR_JWKS_TIMEOUT';
+            if ((typeof joseCode === 'string' && joseCode.startsWith('ERR_J') && !keySetFault) || /^Invalid ID token/.test(message))
+                throw invalid(message);
+            throw error;
+        }
+        if (nonce !== undefined && claims.nonce !== nonce)
+            throw new CrouterError('ID token nonce is missing or does not match', 'id_token_invalid');
+        return claims;
+    }
+    async revoke(connection) {
+        const metadata = await this.discovery();
+        if (!metadata.revocation_endpoint)
+            return false;
+        await this.post(metadata.revocation_endpoint, { token: connection.refreshToken, token_type_hint: 'refresh_token' }, true);
+        return true;
+    }
+    async tokenResponse(params) {
+        const metadata = await this.discovery();
+        if (!metadata.token_endpoint_auth_methods_supported?.includes('private_key_jwt'))
+            throw new CrouterError('Directory does not support private_key_jwt');
+        return await this.post(metadata.token_endpoint, params);
+    }
+    connectionFrom(response, previous) {
+        if (typeof response.access_token !== 'string' || typeof response.refresh_token !== 'string')
+            throw new CrouterError('Directory returned an invalid token response');
+        const claims = decodeJwt(response.access_token);
+        const runtimeUrl = typeof response.runtimeUrl === 'string' && response.runtimeUrl ? response.runtimeUrl : previous?.runtimeUrl;
+        if (typeof claims.sub !== 'string' || typeof claims.grant !== 'string' || typeof claims.exp !== 'number' || !runtimeUrl) {
+            throw new CrouterError('Directory returned an incomplete connection');
+        }
+        const idToken = typeof response.id_token === 'string' ? response.id_token : previous?.idToken;
+        return {
+            userId: claims.sub, runtimeUrl, refreshToken: response.refresh_token,
+            grantId: claims.grant,
+            accessToken: response.access_token, accessTokenExpiresAt: claims.exp * 1_000,
+            ...(idToken ? { idToken } : {}),
+        };
+    }
+    async post(endpoint, values, revocation = false) {
+        const key = this.options.privateKey;
+        if (typeof key !== 'string' && key.alg !== undefined && key.alg !== 'ES256' && key.alg !== 'RS256')
+            throw new CrouterError('privateKey must use ES256 or RS256');
+        let alg;
+        let imported;
+        if (typeof key === 'string') {
+            try {
+                imported = await importPKCS8(key, 'ES256');
+                alg = 'ES256';
+            }
+            catch {
+                imported = await importPKCS8(key, 'RS256');
+                alg = 'RS256';
+            }
+        }
+        else {
+            alg = key.alg === 'RS256' || key.kty === 'RSA' ? 'RS256' : 'ES256';
+            imported = await importJWK(key, alg);
+        }
+        const kid = this.options.keyId ?? (typeof key === 'string' ? undefined : key.kid);
+        for (let attempt = 0;; attempt++) {
+            const now = Math.floor(Date.now() / 1000);
+            const assertion = await new SignJWT({})
+                .setProtectedHeader({ alg, typ: 'JWT', ...(kid ? { kid } : {}) })
+                .setIssuer(this.options.clientId).setSubject(this.options.clientId).setAudience(endpoint)
+                .setIssuedAt(now).setExpirationTime(now + 60).setJti(crypto.randomUUID()).sign(imported);
+            const response = await this.fetcher(endpoint, {
+                method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({ ...values, client_id: this.options.clientId, client_assertion_type: assertionType, client_assertion: assertion }),
+            });
+            if (revocation && response.ok)
+                return undefined;
+            const payload = await response.json();
+            if (response.ok)
+                return payload;
+            const refusal = payload;
+            // invalid_grant carries the directory's reason as its error_description; a reason it does not name is grant_revoked.
+            const description = refusal.error_description ?? '';
+            const code = refusal.error === 'invalid_grant'
+                ? description === 'runtime_provisioning' || reconnectCodes.has(description) ? description : 'grant_revoked'
+                : refusal.error === 'invalid_client' ? 'unauthorized' : 'invalid_request';
+            const reconnect = reconnectCodes.has(code);
+            if (code === 'runtime_provisioning' && attempt < 2) {
+                const retryAfter = refusal.retry_after_s ?? Number(response.headers.get('retry-after'));
+                const delay = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1_000 : 500 * 2 ** attempt * (0.5 + Math.random());
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            const message = refusal.error_description ?? refusal.error ?? 'Directory token request failed';
+            const keyHint = code === 'unauthorized' ? await describeSigningKey(key, kid) : undefined;
+            // mapError gives the refusal its status class (401 → AuthenticationError) as errors.md documents.
+            throw mapError(new APIError(code === 'runtime_provisioning' ? 503 : reconnect || code === 'unauthorized' ? 401 : response.status, code, keyHint ? `${message}: ${keyHint.hint}` : message, code === 'invalid_request' ? { oauth_error: refusal.error }
+                : keyHint ? { oauth_error: 'invalid_client', kid: keyHint.kid, ...(keyHint.thumbprint ? { key_thumbprint: keyHint.thumbprint } : {}) } : undefined, response.headers, { origin: 'directory', type: code === 'runtime_provisioning' ? 'server_error' : code === 'invalid_request' ? 'invalid_request_error' : 'authentication_error',
+                retryable: code === 'runtime_provisioning', user_action: reconnect ? 'reconnect' : undefined }));
+        }
+    }
+}
+/**
+ * Name the key an `invalid_client` refusal rejected, so a developer who switched key files before
+ * uploading the public JWK sees which key the SDK signed with and where it must be registered.
+ */
+async function describeSigningKey(key, kid) {
+    const question = "is this key's public JWK registered on the app's Sign-in tab in the console?";
+    if (kid)
+        return { kid, hint: `the directory rejected the client assertion signed with key id (kid) "${kid}"; ${question}` };
+    // An assertion without a kid: the console lists such a key by its RFC 7638 thumbprint.
+    let thumbprint;
+    try {
+        thumbprint = typeof key === 'string'
+            ? await calculateJwkThumbprint(await exportJWK(await importPKCS8(key, 'ES256', { extractable: true }).catch(() => importPKCS8(key, 'RS256', { extractable: true }))), 'sha256')
+            : await calculateJwkThumbprint(key, 'sha256');
+    }
+    catch {
+        thumbprint = undefined;
+    }
+    const named = thumbprint ? `signed without a kid by the key whose thumbprint is "${thumbprint}"` : 'signed without a kid';
+    return { kid: null, ...(thumbprint ? { thumbprint } : {}), hint: `the directory rejected the client assertion ${named}; ${question}` };
+}
+// expectedState is the state saved by the app at authorizeUrl(), not a value from the callback.
+function assertState(state, expectedState) {
+    if (!state || !expectedState || state !== expectedState)
+        throw new CrouterError('OAuth state is missing or does not match', 'oauth_state_mismatch');
+}
+function randomBase64url(length) { return base64url(crypto.getRandomValues(new Uint8Array(length))); }
+function base64url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}

package/dist/oauth/keygen.d.ts

@@ -0,0 +1,18 @@
+import { type JWK } from 'jose';
+/** Make an app signing key and the public JWK to register in the directory. */
+export declare function generateKeyPair(): Promise<{
+    privateJwk: JWK;
+    publicJwk: JWK;
+    kid: string;
+}>;
+/** Check that `value` (a JWK object or its JSON text) is a private signing key with a `kid`, and return it as
+ *  `OAuth2Options.privateKey` takes it. `source` names where it came from in the error, e.g. a file path. */
+export declare function parsePrivateJwk(value: string | JWK, source?: string): JWK & {
+    d: string;
+    kid: string;
+};
+/** Read a private JWK file, such as the one `crouter-sdk keygen` writes, and check it as `parsePrivateJwk` does. Node only. */
+export declare function privateKeyFromFile(path: string): Promise<JWK & {
+    d: string;
+    kid: string;
+}>;

package/dist/oauth/keygen.js

@@ -0,0 +1,46 @@
+import { calculateJwkThumbprint, exportJWK, generateKeyPair as generateSigningKeyPair } from 'jose';
+import { CrouterError } from '../errors.js';
+/** Make an app signing key and the public JWK to register in the directory. */
+export async function generateKeyPair() {
+    const keys = await generateSigningKeyPair('ES256', { extractable: true });
+    const publicKey = await exportJWK(keys.publicKey);
+    const kid = await calculateJwkThumbprint(publicKey, 'sha256');
+    const properties = { kid, alg: 'ES256', use: 'sig' };
+    return {
+        privateJwk: { ...await exportJWK(keys.privateKey), ...properties },
+        publicJwk: { ...publicKey, ...properties },
+        kid,
+    };
+}
+const keygenHint = 'make one with: pnpm exec crouter-sdk keygen';
+/** Check that `value` (a JWK object or its JSON text) is a private signing key with a `kid`, and return it as
+ *  `OAuth2Options.privateKey` takes it. `source` names where it came from in the error, e.g. a file path. */
+export function parsePrivateJwk(value, source = 'The key') {
+    let key = value;
+    if (typeof value === 'string') {
+        try {
+            key = JSON.parse(value);
+        }
+        catch {
+            throw new CrouterError(`${source} is not JSON; it must hold a private JWK with a kid (${keygenHint}).`);
+        }
+    }
+    if (!key || typeof key !== 'object' || Array.isArray(key) || typeof key.d !== 'string' || !key.d
+        || typeof key.kid !== 'string' || !key.kid) {
+        throw new CrouterError(`${source} must hold a private JWK with a kid (${keygenHint}).`);
+    }
+    return key;
+}
+/** Read a private JWK file, such as the one `crouter-sdk keygen` writes, and check it as `parsePrivateJwk` does. Node only. */
+export async function privateKeyFromFile(path) {
+    const load = new Function('specifier', 'return import(specifier)');
+    const { readFile } = await load('node:fs/promises');
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw new CrouterError(`${path} could not be read (${error instanceof Error ? error.message : String(error)}); it must hold a private JWK with a kid (${keygenHint}).`);
+    }
+    return parsePrivateJwk(text, path);
+}

package/dist/resources/activity.d.ts

@@ -0,0 +1,22 @@
+import type { NodeStreamEvent } from './node-stream.js';
+/** One tool call rendered as an activity step. */
+export interface ActivityStep {
+    /** The tool call's id, stable across its status changes. */
+    id: string;
+    /** Tool name, e.g. `bash` or `read`. */
+    tool: string;
+    /** The daemon's one-line summary of the call. */
+    summary: string;
+    /** What `describe` returned for this call, for display. */
+    label: string;
+    /** Where the call stands. */
+    status: 'running' | 'done' | 'failed';
+}
+/** Turn a streamed tool call into a label, or return null to omit it. */
+export type DescribeTool = (tool: string, summary: string) => string | null;
+/** Plain labels for the tools every node can use. */
+export declare const describeToolDefault: DescribeTool;
+/** Yield an immutable activity snapshot after every streamed tool-call change. */
+export declare function followActivity(stream: AsyncIterable<NodeStreamEvent>, options?: {
+    describe?: DescribeTool;
+}): AsyncGenerator<ActivityStep[]>;

package/dist/resources/activity.js

@@ -0,0 +1,43 @@
+/** Plain labels for the tools every node can use. */
+export const describeToolDefault = (tool) => {
+    switch (tool) {
+        case 'bash': return 'running bash';
+        case 'read': return 'reading';
+        case 'write': return 'writing';
+        case 'edit': return 'editing';
+        default: return tool;
+    }
+};
+/** Yield an immutable activity snapshot after every streamed tool-call change. */
+export async function* followActivity(stream, options = {}) {
+    const describe = options.describe ?? describeToolDefault;
+    const steps = [];
+    const byId = new Map();
+    for await (const event of stream) {
+        if (event.type === 'node.tool_call.started') {
+            const label = describe(event.tool, event.summary);
+            if (label === null || byId.has(event.tool_call_id))
+                continue;
+            const step = {
+                id: event.tool_call_id,
+                tool: event.tool,
+                summary: event.summary,
+                label,
+                status: 'running',
+            };
+            byId.set(step.id, step);
+            steps.push(step);
+            yield snapshot(steps);
+        }
+        else if (event.type === 'node.tool_call.completed') {
+            const step = byId.get(event.tool_call_id);
+            if (step === undefined || step.status !== 'running')
+                continue;
+            step.status = event.status === 'ok' ? 'done' : 'failed';
+            yield snapshot(steps);
+        }
+    }
+}
+function snapshot(steps) {
+    return steps.map((step) => ({ ...step }));
+}

package/dist/resources/attachments.d.ts

@@ -0,0 +1,15 @@
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+/** A short-lived signed link to an uploaded file's stored bytes. */
+export interface AttachmentLink {
+    url: string;
+    expires_at: string;
+}
+/** Links to files a run received as attachments (app listener only). */
+export declare class Attachments {
+    private readonly request;
+    constructor(request: Request);
+    /** A signed download link for the upload fetched to `path`, an absolute path under a run's
+     *  `attachments/` folder. A path with no recorded upload, or in a run the caller cannot read, is `not_found`. */
+    link(path: string, options?: RequestOptions): Promise<AttachmentLink>;
+}

package/dist/resources/attachments.js

@@ -0,0 +1,13 @@
+import { withQuery } from './request.js';
+/** Links to files a run received as attachments (app listener only). */
+export class Attachments {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    /** A signed download link for the upload fetched to `path`, an absolute path under a run's
+     *  `attachments/` folder. A path with no recorded upload, or in a run the caller cannot read, is `not_found`. */
+    link(path, options) {
+        return this.request('GET', withQuery('/v1/attachments/link', { path }), undefined, options);
+    }
+}

package/dist/resources/bash.d.ts

@@ -0,0 +1,9 @@
+import { type BashRunDTO, type BashRunParams } from '@crouter/api';
+import type { RequestOptions } from '../types.js';
+import type { Request } from './request.js';
+export declare class Bash {
+    private readonly request;
+    private readonly defaultTimeout;
+    constructor(request: Request, defaultTimeout: number);
+    run(params: BashRunParams, options?: RequestOptions): Promise<BashRunDTO>;
+}

package/dist/resources/bash.js

@@ -0,0 +1,15 @@
+import { routes } from '@crouter/api';
+const DEFAULT_TIMEOUT_SECONDS = 60;
+const TIMEOUT_ALLOWANCE_MS = 15_000;
+export class Bash {
+    request;
+    defaultTimeout;
+    constructor(request, defaultTimeout) {
+        this.request = request;
+        this.defaultTimeout = defaultTimeout;
+    }
+    run(params, options) {
+        const requiredTimeout = (params.timeout_s ?? DEFAULT_TIMEOUT_SECONDS) * 1000 + TIMEOUT_ALLOWANCE_MS;
+        return this.request('POST', routes.bash(), params, { ...options, timeout: Math.max(options?.timeout ?? this.defaultTimeout, requiredTimeout) });
+    }
+}

package/dist/resources/canvas/history.d.ts

@@ -0,0 +1,11 @@
+import { type HistoryGrepQuery, type HistoryGrepResultDTO, type HistoryReadQuery, type HistoryReadResultDTO, type HistorySearchQuery, type HistorySearchResultDTO, type HistoryStatsQuery, type HistoryStatsResultDTO } from '@crouter/api';
+import type { RequestOptions } from '../../types.js';
+import type { Request } from '../request.js';
+export declare class CanvasHistory {
+    private readonly request;
+    constructor(request: Request);
+    search(body: HistorySearchQuery, options?: RequestOptions): Promise<HistorySearchResultDTO>;
+    grep(body: HistoryGrepQuery, options?: RequestOptions): Promise<HistoryGrepResultDTO>;
+    read(query: HistoryReadQuery, options?: RequestOptions): Promise<HistoryReadResultDTO>;
+    stats(body: HistoryStatsQuery, options?: RequestOptions): Promise<HistoryStatsResultDTO>;
+}

package/dist/resources/canvas/history.js

@@ -0,0 +1,20 @@
+import { routes, } from '@crouter/api';
+import { withQuery } from '../request.js';
+export class CanvasHistory {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    search(body, options) {
+        return this.request('POST', routes.canvasHistorySearch(), body, options);
+    }
+    grep(body, options) {
+        return this.request('POST', routes.canvasHistoryGrep(), body, options);
+    }
+    read(query, options) {
+        return this.request('GET', withQuery(routes.canvasHistoryRead(), query), undefined, options);
+    }
+    stats(body, options) {
+        return this.request('POST', routes.canvasHistoryStats(), body, options);
+    }
+}

package/dist/resources/canvas.d.ts

@@ -0,0 +1,19 @@
+import { type AttentionCountsDTO, type AttentionCountsRequest, type AttentionDTO, type DashboardDTO, type DashboardQuery, type PruneRequest, type PruneResultDTO, type RosterDTO, type SnapshotDTO, type WatchRequest, type WatchResultDTO, type UnwatchQuery, type UnwatchResultDTO } from '@crouter/api';
+import type { RequestOptions } from '../types.js';
+import { CanvasHistory } from './canvas/history.js';
+import type { Request } from './request.js';
+export declare class Canvas {
+    private readonly request;
+    readonly history: CanvasHistory;
+    constructor(request: Request);
+    attention(options?: RequestOptions): Promise<AttentionDTO>;
+    attentionCounts(body: AttentionCountsRequest, options?: RequestOptions): Promise<AttentionCountsDTO>;
+    snapshot(options?: RequestOptions): Promise<SnapshotDTO>;
+    roster(options?: RequestOptions): Promise<RosterDTO>;
+    dashboard(query?: DashboardQuery, options?: RequestOptions): Promise<DashboardDTO>;
+    /** Watch an object; `watcher` makes a custom object the receiver instead of the caller's node. */
+    watch(ref: string, body?: WatchRequest, options?: RequestOptions): Promise<WatchResultDTO>;
+    /** Remove a watch. `watcher` identifies the custom object whose watch is removed. */
+    unwatch(ref: string, query?: UnwatchQuery, options?: RequestOptions): Promise<UnwatchResultDTO>;
+    prune(body: PruneRequest, options?: RequestOptions): Promise<PruneResultDTO>;
+}