@north-light/sdk 0.0.0 → 0.3.415

package/dist/testing/cloud.js

@@ -0,0 +1,914 @@
+// FakeCloud: a fake crouter directory and runtime behind one `fetch`, for testing an app's real `OAuth2Client` and
+// `Crouter`. Routing, the call logs, intercepts, users and every runtime operation an app may call.
+import { RUNTIME_VERSION_HEADER, minimumRuntimeRefusal, MINIMUM_RUNTIME_VERSION_HEADER } from '@north-light/api';
+import { covers } from '@north-light/identity';
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import { exportJWK, generateKeyPair } from 'jose';
+import { Crouter } from '../client.js';
+import { MemoryConnectionStore, OAuth2Client } from '../oauth/index.js';
+import { SDK_VERSION } from '../version.js';
+import { RunNotices, SigningKey } from './notices.js';
+import { FakeRun } from './run.js';
+import { UserState, normalizeScopes } from './users.js';
+import { FakeRefused, decodeUnsigned, envelopeBody, fakeError, integerParam, invalid, isFakeError, jsonAnswer, notFound, objectBody, refuse, requestedScopes, sha256Hex, unsignedJwt, waitSeconds, } from './wire.js';
+const ROUTES = [
+    ['GET', /^\/v1\/grant$/, 'grant.get'],
+    ['POST', /^\/v1\/runs$/, 'run.start'],
+    ['GET', /^\/v1\/runs$/, 'run.list'],
+    ['GET', /^\/v1\/runs\/([^/]+)$/, 'run.get'],
+    ['DELETE', /^\/v1\/runs\/([^/]+)$/, 'run.delete'],
+    ['POST', /^\/v1\/runs\/([^/]+)\/messages$/, 'run.message'],
+    ['GET', /^\/v1\/runs\/([^/]+)\/events$/, 'run.events'],
+    ['POST', /^\/v1\/runs\/([^/]+)\/interrupt$/, 'run.interrupt'],
+    ['POST', /^\/v1\/runs\/([^/]+)\/cancel$/, 'run.cancel'],
+    ['POST', /^\/v1\/runs\/([^/]+)\/rename$/, 'run.rename'],
+    ['GET', /^\/v1\/runs\/([^/]+)\/trace$/, 'trace.get'],
+    ['GET', /^\/v1\/questions\/([^/]+)$/, 'question.get'],
+    ['POST', /^\/v1\/questions\/([^/]+)\/answer$/, 'question.answer'],
+    ['GET', /^\/v1\/memory$/, 'memory.list'],
+    ['GET', /^\/v1\/memory\/document$/, 'memory.get'],
+    ['GET', /^\/v1\/providers\/tools$/, 'provider.tools'],
+    ['GET', /^\/v1\/providers\/([^/]+)\/tools$/, 'provider.tools'],
+    ['POST', /^\/v1\/provider\/call$/, 'provider.call'],
+    ['GET', /^\/v1\/profiles$/, 'profile.list'],
+];
+const DIRECTORY_OPS = new Set(['directory.discovery', 'directory.token', 'directory.jwks']);
+const RUN_OPS = new Set(['run.get', 'run.delete', 'run.message', 'run.events', 'run.interrupt', 'run.cancel', 'run.rename', 'trace.get']);
+const ACT_OPS = new Set(['run.start', 'run.message']);
+/** The served memory body cap (`MEMORY_BODY_MAX_BYTES`, src/daemon/api/handlers/memory.ts). */
+const MEMORY_BODY_MAX_BYTES = 1024 * 1024;
+const MEMORY_NAME = /^[A-Za-z0-9_-]+(\/[A-Za-z0-9_-]+)*$/;
+const PROVIDER_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const unreachable = () => new TypeError('fetch failed');
+const aborted = (signal) => signal.reason ?? new DOMException('This operation was aborted', 'AbortError');
+/** Race `promise` with `signal`. */
+function withSignal(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(aborted(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(aborted(signal));
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => { signal.removeEventListener('abort', onAbort); resolve(value); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+}
+/** A fake crouter cloud: the directory (discovery, refresh, JWKS) and each person's runtime, behind `fetch`. */
+export class FakeCloud {
+    /** Pass to `OAuth2Client` (and `verifyRunNotice`) as `fetch`. Unique per cloud. */
+    fetch;
+    issuer;
+    clientId;
+    /** Every runtime request, in order. */
+    calls = [];
+    /** Every directory request, in order. */
+    directoryCalls = [];
+    /** Every run-notice attempt, in order. */
+    notices;
+    /** What responders threw. */
+    responderErrors = [];
+    runs;
+    providers;
+    options;
+    clock;
+    users = new Map();
+    handles = new Map();
+    allRuns = [];
+    providerDefs = new Map();
+    intercepts = [];
+    gates = new Set();
+    responder = null;
+    key = new SigningKey();
+    runNotices;
+    host;
+    /** Superseded refresh tokens → owner, for `refresh_token_reused`. */
+    superseded = new Map();
+    tokenSerial = 0;
+    refreshSerial = 0;
+    runSerial = 0;
+    constructor(options) {
+        if (!options || typeof options.clientId !== 'string' || !options.clientId)
+            throw new TypeError('FakeCloud needs a clientId');
+        this.options = options;
+        this.clock = options.clock ?? { now: () => Date.now() };
+        this.clientId = options.clientId;
+        this.issuer = (options.issuer ?? 'https://directory.test').replace(/\/$/, '');
+        this.runNotices = new RunNotices(options.runNotice, this.key, {
+            issuer: this.issuer, clientId: this.clientId, runtimeId: options.runtimeId ?? 'runtime:test', runtimeClientId: options.runtimeClientId ?? 'runtime-client',
+        }, (userId) => this.users.get(userId)?.active === true, this.clock);
+        this.notices = this.runNotices.records;
+        const grantee = `app:${this.clientId}`;
+        this.host = {
+            grantee,
+            streamIdleMs: options.streamIdleMs ?? 60_000,
+            now: () => this.clock.now(),
+            grantActive: (userId) => this.users.get(userId)?.active === true,
+            appended: (run) => this.runNotices.appended(run),
+            streamOpened: (run) => this.runNotices.streamOpened(run),
+            deleted: (run) => {
+                const user = this.users.get(run.userId);
+                if (user)
+                    for (const [key, entry] of user.idempotency)
+                        if (entry.runId === run.id)
+                            user.idempotency.delete(key);
+                this.runNotices.forget(run);
+            },
+        };
+        const allRuns = this.allRuns;
+        this.runs = { get all() { return allRuns; }, respond: (fn) => { this.responder = fn; } };
+        this.providers = { define: (provider, definition) => {
+                if (!PROVIDER_ID.test(provider) || provider === 'crtr')
+                    throw new TypeError(`invalid provider id ${provider}`);
+                this.providerDefs.set(provider, definition);
+            } };
+        this.fetch = (input, init) => this.route(input, init);
+    }
+    /** A `FakeError` envelope for intercepts, `failNext` and provider handlers. `retryable` defaults to `status === 503`. */
+    static error(input) {
+        return fakeError(input);
+    }
+    /** The `directory.token` subset of `directoryCalls`. */
+    get refreshes() { return this.directoryCalls.filter((call) => call.op === 'directory.token'); }
+    /** That user's handle, created on first use. */
+    user(userId) {
+        let handle = this.handles.get(userId);
+        if (handle)
+            return handle;
+        const state = this.state(userId);
+        const cloud = this;
+        const runs = { get all() { return state.runs; }, respond: (fn) => { state.responder = fn; } };
+        handle = {
+            id: userId,
+            grant: {
+                get state() { return state.dto(); },
+                set(patch) { state.apply(patch); state.rev++; state.wakeHolds(); },
+                setup(provider, setupState, options = {}) {
+                    const dependency = {
+                        state: setupState, ...(options.message === undefined ? {} : { message: options.message }),
+                        next: options.next ?? `${cloud.issuer}/connect/setup/${provider}?client_id=${cloud.clientId}`,
+                    };
+                    state.dependencies = { ...state.dependencies, [provider]: dependency };
+                    state.wakeHolds();
+                },
+                sync() { },
+                revoke(code = 'grant_revoked') { state.revoke(code); },
+                restore(patch = {}) {
+                    state.apply(patch);
+                    state.active = true;
+                    state.refusal = null;
+                    state.rev++;
+                    state.wakeHolds();
+                },
+            },
+            refuse(code) {
+                state.refusal = code === 'ok' ? null : code;
+                if (code !== 'ok')
+                    state.minSerial = cloud.tokenSerial + 1;
+            },
+            expireTokens() { state.minSerial = cloud.tokenSerial + 1; },
+            get reads() { return cloud.calls.filter((call) => call.userId === userId && call.op === 'grant.get'); },
+            get holding() { return state.holds.size; },
+            runs,
+            memory: {
+                put(doc) {
+                    if (!MEMORY_NAME.test(doc.name))
+                        throw new TypeError(`invalid memory document name ${doc.name}`);
+                    state.putMemory(doc);
+                },
+                remove(name) { state.memory.delete(name); },
+            },
+        };
+        this.handles.set(userId, handle);
+        return handle;
+    }
+    /**
+     * Make `userId`'s grant active and save a stored connection for them in `store`, with its access token expired so
+     * the first call refreshes through the directory. Default scopes: `crtr:llm`, `crtr:act`.
+     */
+    async connect(store, userId, options = {}) {
+        const handle = this.user(userId);
+        const state = this.state(userId);
+        this.activateState(state, options);
+        state.refreshToken ??= this.newRefreshToken(userId);
+        await store.save({ userId, runtimeUrl: this.runtimeUrlFor(userId), refreshToken: state.refreshToken, grantId: state.grantId, accessToken: '', accessTokenExpiresAt: 0 });
+        return handle;
+    }
+    activateState(state, options) {
+        if (!state.active) {
+            state.active = true;
+            state.refusal = null;
+            state.rev++;
+            state.resolvedScopes = normalizeScopes(options.scopes ?? ['crtr:llm', 'crtr:act']);
+            if (options.dependencies)
+                state.dependencies = { ...options.dependencies };
+            state.wakeHolds();
+        }
+        else if (options.scopes || options.dependencies) {
+            state.apply({ ...(options.scopes ? { resolved_scopes: options.scopes } : {}), ...(options.dependencies ? { dependencies: options.dependencies } : {}) });
+            state.rev++;
+            state.wakeHolds();
+        }
+    }
+    /**
+     * Make `userId`'s grant active with no stored connection, for an app that mints a per-user runtime token through
+     * the directory's `client_credentials` grant. Default scopes: `crtr:llm`, `crtr:act`.
+     */
+    activate(userId, options = {}) {
+        const handle = this.user(userId);
+        const state = this.state(userId);
+        this.activateState(state, options);
+        state.refreshToken ??= this.newRefreshToken(userId);
+        return handle;
+    }
+    /**
+     * A real `Crouter` on `userId`'s runtime with a fresh access token and no refresh: refusals never reach it. For
+     * code whose production signature takes a `Crouter`; an app that goes through `OAuth2Client` tests through it.
+     */
+    crouter(userId) {
+        const state = this.users.get(userId);
+        if (!state?.refreshToken)
+            throw new Error(`${userId} is not connected: call cloud.connect first`);
+        return new Crouter({ baseURL: this.runtimeUrlFor(userId), token: this.accessToken(state), fetch: this.fetch });
+    }
+    /** Run `fn` before `op`. `times` defaults to Infinity. `user` filters runtime operations and `directory.token`. */
+    intercept(op, fn, options = {}) {
+        if (options.user !== undefined && (op === 'directory.discovery' || op === 'directory.jwks'))
+            throw new TypeError(`${op} carries no user; drop the user filter`);
+        const entry = { op, fn, user: options.user, remaining: options.times ?? Infinity };
+        this.intercepts.push(entry);
+        return () => { this.intercepts = this.intercepts.filter((other) => other !== entry); };
+    }
+    /** Answer the next `times` (default 1) matching requests with `answer`. */
+    failNext(op, answer, options = {}) {
+        if (DIRECTORY_OPS.has(op) && isFakeError(answer))
+            throw new TypeError(`${op} cannot answer an envelope: use a status or 'unreachable'${op === 'directory.token' ? ', and user.refuse for refusals' : ''}`);
+        this.intercept(op, () => answer, { ...options, times: options.times ?? 1 });
+    }
+    /** Hold every matching request until `release()`, which frees them all and removes the gate. */
+    gate(op, options = {}) {
+        let open;
+        const opened = new Promise((resolve) => { open = resolve; });
+        const remove = this.intercept(op, () => opened, options);
+        const release = () => { remove(); this.gates.delete(release); open(); };
+        this.gates.add(release);
+        return release;
+    }
+    /** Clear runs, calls, intercepts (gates are released), responders, memory, idempotency keys and notices. Grants
+     *  and refresh-token chains stay, so stored connections remain valid. */
+    reset() {
+        for (const release of [...this.gates])
+            release();
+        this.intercepts = [];
+        for (const run of this.allRuns)
+            run.delete();
+        this.allRuns.length = 0;
+        for (const user of this.users.values()) {
+            user.runs.length = 0;
+            user.responder = null;
+            user.memory.clear();
+            user.idempotency.clear();
+        }
+        this.responder = null;
+        this.calls.length = 0;
+        this.directoryCalls.length = 0;
+        this.responderErrors.length = 0;
+        this.runNotices.reset();
+    }
+    /** The exact error the SDK raises when the directory refuses a refresh with `code` (`refusalOf(e)` is set). */
+    async refusalError(code) {
+        const probe = new FakeCloud({ clientId: this.clientId, issuer: this.issuer, runtimeUrl: this.runtimeUrlFor('user:refused') });
+        const store = new MemoryConnectionStore();
+        const user = await probe.connect(store, 'user:refused');
+        user.refuse(code);
+        const { privateKey } = await generateKeyPair('ES256', { extractable: true });
+        const oauth = new OAuth2Client({
+            clientId: this.clientId, privateKey: await exportJWK(privateKey), redirectUri: 'https://app.test/callback',
+            issuer: this.issuer, store, fetch: probe.fetch,
+        });
+        try {
+            await (await oauth.client('user:refused')).grant.get();
+        }
+        catch (error) {
+            return error;
+        }
+        throw new Error(`refusalError: the refresh was not refused with ${code}`);
+    }
+    // ---- routing ---------------------------------------------------------------------------------------------------
+    state(userId) {
+        let state = this.users.get(userId);
+        if (!state) {
+            state = new UserState(userId, this.clientId, (user) => { for (const run of user.runs)
+                if (!run.deleted)
+                    run.revokeStreams(); }, this.clock);
+            this.users.set(userId, state);
+        }
+        return state;
+    }
+    runtimeUrlFor(userId) {
+        const option = this.options.runtimeUrl ?? 'https://runtime.test';
+        return (typeof option === 'function' ? option(userId) : option).replace(/\/$/, '');
+    }
+    isRuntimeOrigin(origin, sub) {
+        const option = this.options.runtimeUrl ?? 'https://runtime.test';
+        if (typeof option === 'string')
+            return new URL(option).origin === origin;
+        if (sub !== null && new URL(option(sub)).origin === origin)
+            return true;
+        return [...this.users.keys()].some((id) => new URL(option(id)).origin === origin);
+    }
+    headers() { return { [RUNTIME_VERSION_HEADER]: this.options.runtimeVersion ?? SDK_VERSION }; }
+    async route(input, init) {
+        const request = new Request(input, init);
+        const signal = init?.signal ?? (input instanceof Request ? input.signal : null);
+        if (signal?.aborted)
+            throw aborted(signal);
+        const url = new URL(request.url);
+        if (url.href.startsWith(`${this.issuer}/`))
+            return this.directory(url, request, signal);
+        const claims = decodeUnsigned((request.headers.get('authorization') ?? '').replace(/^Bearer\s+/i, ''));
+        const sub = typeof claims?.['sub'] === 'string' ? claims['sub'] : null;
+        if (!this.isRuntimeOrigin(url.origin, sub))
+            throw new Error(`FakeCloud: no fake serves ${request.method} ${url.href}`);
+        return this.runtime(url, request, signal, claims, sub);
+    }
+    async runIntercepts(op, call, signal) {
+        for (const entry of [...this.intercepts]) {
+            const matches = entry.op === op || (entry.op === '*' && !DIRECTORY_OPS.has(op));
+            if (!matches || (entry.user !== undefined && entry.user !== call.userId) || entry.remaining <= 0)
+                continue;
+            entry.remaining--;
+            if (entry.remaining <= 0)
+                this.intercepts = this.intercepts.filter((other) => other !== entry);
+            const answer = await withSignal(Promise.resolve(entry.fn(call)), signal);
+            if (answer !== undefined)
+                return answer;
+        }
+        return undefined;
+    }
+    // ---- directory ---------------------------------------------------------------------------------------------------
+    async directory(url, request, signal) {
+        const path = url.href.slice(this.issuer.length);
+        let op;
+        if (request.method === 'GET' && path === '/.well-known/openid-configuration')
+            op = 'directory.discovery';
+        else if (request.method === 'POST' && path === '/token')
+            op = 'directory.token';
+        else if (request.method === 'GET' && path === '/.well-known/jwks.json')
+            op = 'directory.jwks';
+        else
+            throw new Error(`FakeCloud: the fake directory does not serve ${request.method} ${url.href}`);
+        const params = op === 'directory.token' ? new URLSearchParams(await request.text()) : null;
+        const presented = params?.get('refresh_token') ?? '';
+        const credentials = params?.get('grant_type') === 'client_credentials';
+        const owner = op === 'directory.token' && credentials ? params.get('sub') || null
+            : op === 'directory.token' ? [...this.users.values()].find((user) => user.refreshToken === presented)?.id ?? this.superseded.get(presented) ?? null : null;
+        const call = { op, userId: owner, answer: 'ok', at: this.clock.now() };
+        this.directoryCalls.push(call);
+        const scripted = await this.runIntercepts(op, call, signal);
+        if (scripted !== undefined) {
+            if (isFakeError(scripted))
+                throw new TypeError(`${op} cannot answer an envelope: use a status or 'unreachable'`);
+            call.answer = scripted;
+            if (scripted === 'unreachable')
+                throw unreachable();
+            return Response.json(op === 'directory.token' ? { error: 'temporarily_unavailable' } : {}, { status: scripted });
+        }
+        if (op === 'directory.discovery') {
+            const template = this.options.accountAppUriTemplate === undefined ? `${this.issuer}/account/apps/{client_id}` : this.options.accountAppUriTemplate;
+            return Response.json({
+                issuer: this.issuer, authorization_endpoint: `${this.issuer}/authorize`, token_endpoint: `${this.issuer}/token`,
+                jwks_uri: `${this.issuer}/.well-known/jwks.json`, token_endpoint_auth_methods_supported: ['private_key_jwt'],
+                ...(template === null ? {} : { account_app_uri_template: template }),
+            });
+        }
+        if (op === 'directory.jwks')
+            return Response.json(await this.key.jwks());
+        return credentials ? this.mint(params, call) : this.refresh(params, presented, call);
+    }
+    /** `grant_type=client_credentials` + `sub`: the directory's per-user runtime-token mint. The client assertion is not verified. */
+    mint(params, call) {
+        const sub = params.get('sub');
+        if (!sub) {
+            call.answer = 400;
+            return Response.json({ error: 'unauthorized_client' }, { status: 400 });
+        }
+        const user = this.users.get(sub);
+        const refused = (description, answer) => { call.answer = answer; return Response.json({ error: 'invalid_grant', error_description: description }, { status: 400 }); };
+        if (user?.refusal)
+            return refused(user.refusal, user.refusal);
+        if (!user?.active)
+            return refused('no active grant', 'grant_revoked');
+        return Response.json({ access_token: this.accessToken(user, 600), token_type: 'Bearer', expires_in: 600, runtimeUrl: this.runtimeUrlFor(user.id) });
+    }
+    refresh(params, presented, call) {
+        const refused = (code) => { call.answer = code; return Response.json({ error: 'invalid_grant', error_description: code }, { status: 400 }); };
+        if (params.get('grant_type') !== 'refresh_token') {
+            call.answer = 400;
+            return Response.json({ error: 'unsupported_grant_type' }, { status: 400 });
+        }
+        if (call.userId === null)
+            return refused('grant_revoked');
+        const user = this.state(call.userId);
+        if (user.refreshToken !== presented)
+            return refused('refresh_token_reused');
+        if (user.refusal)
+            return refused(user.refusal);
+        this.superseded.set(presented, user.id);
+        user.refreshToken = this.newRefreshToken(user.id);
+        return Response.json({
+            access_token: this.accessToken(user), token_type: 'Bearer', expires_in: 3600,
+            refresh_token: user.refreshToken, runtimeUrl: this.runtimeUrlFor(user.id),
+        });
+    }
+    newRefreshToken(userId) { return `rt-${++this.refreshSerial}-${userId}`; }
+    accessToken(user, ttlSeconds = 3600) {
+        const now = Math.floor(this.clock.now() / 1000);
+        return unsignedJwt({ sub: user.id, grant: user.grantId, exp: now + ttlSeconds, iat: now, rev: user.rev, serial: ++this.tokenSerial });
+    }
+    // ---- runtime -----------------------------------------------------------------------------------------------------
+    async runtime(url, request, signal, claims, sub) {
+        const route = ROUTES.find(([method, pattern]) => method === request.method && pattern.test(url.pathname));
+        if (!route)
+            return jsonAnswer(envelopeBody(fakeError({ status: 404, code: 'not_found', message: 'unknown operation' })), 404, this.headers());
+        const [, pattern, op] = route;
+        const segment = pattern.exec(url.pathname)?.[1];
+        const id = segment === undefined ? undefined : decodeURIComponent(segment);
+        let body = null;
+        let badJson = false;
+        if (request.method === 'POST') {
+            const text = await request.text();
+            if (text) {
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    badJson = true;
+                }
+            }
+        }
+        const user = sub !== null ? this.users.get(sub) : undefined;
+        const runId = RUN_OPS.has(op) ? id : undefined;
+        const questionId = op === 'question.get' || op === 'question.answer' ? id : null;
+        const questionRun = questionId === null ? undefined : user?.runs.find((run) => !run.deleted && run.questions.has(questionId));
+        const call = {
+            userId: user ? user.id : null, op, runId: runId ?? questionRun?.id ?? null, questionId, method: request.method, path: url.pathname,
+            query: Object.fromEntries(url.searchParams), body, idempotencyKey: request.headers.get('idempotency-key'), status: null, at: this.clock.now(),
+        };
+        this.calls.push(call);
+        const answer = (status, payload) => { call.status = status; return jsonAnswer(payload, status, this.headers()); };
+        const fail = (error) => answer(error.status, envelopeBody(error, runId));
+        const scripted = await this.runIntercepts(op, call, signal);
+        if (scripted !== undefined) {
+            if (scripted === 'unreachable')
+                throw unreachable();
+            if (typeof scripted === 'number')
+                return fail(fakeError({ status: scripted, code: scripted >= 500 ? 'server_error' : 'invalid_request', message: `scripted ${scripted}`, retryable: false }));
+            return fail(scripted);
+        }
+        const minimum = minimumRuntimeRefusal(request.headers.get(MINIMUM_RUNTIME_VERSION_HEADER) ?? undefined, this.options.runtimeVersion ?? SDK_VERSION);
+        if (minimum) {
+            const error = fakeError({ status: minimum.status, code: minimum.code, message: minimum.message, ...(minimum.status === 426 ? { details: minimum.details } : { param: minimum.param }), origin: minimum.status === 426 ? 'router' : 'runtime', retryable: false });
+            call.status = error.status;
+            // A router refusal names no runtime release.
+            return error.status === 426 ? jsonAnswer(envelopeBody(error), 426, {}) : fail(error);
+        }
+        try {
+            if (!user?.refreshToken || claims === null)
+                throw refuse(401, 'unauthorized', 'a directory access token is required');
+            if (typeof claims['serial'] !== 'number' || claims['serial'] < user.minSerial)
+                throw refuse(401, 'unauthorized', 'invalid directory access token');
+            if (!user.active)
+                throw refuse(401, 'grant_revoked', 'grant is not active');
+            if (ACT_OPS.has(op) && !user.scopeStrings().some((scope) => covers(scope, 'crtr:act')))
+                throw refuse(403, 'scope_missing', 'missing scope crtr:act');
+            if (badJson)
+                throw invalid('invalid JSON body');
+            if (op === 'run.events') {
+                const run = this.ownedRun(user, id);
+                const raw = request.headers.get('last-event-id') ?? url.searchParams.get('after');
+                const after = integerParam(raw, 'after', 0, Number.MAX_SAFE_INTEGER, 0);
+                if (after > run.latestSequence)
+                    throw invalid('cursor is beyond the run', 'after');
+                const earliest = run.earliestSequence;
+                if (after < run.latestSequence && (earliest === null || after < earliest - 1)) {
+                    throw refuse(409, 'stream_gap', 'events have expired', { details: { earliest_sequence: earliest, latest_sequence: run.latestSequence } });
+                }
+                call.status = 200;
+                return new Response(run.openStream(after, signal), { status: 200, headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', ...this.headers() } });
+            }
+            const result = await this.handle(op, user, id, url.searchParams, body, call.idempotencyKey, signal, claims);
+            return answer(result.status, result.body);
+        }
+        catch (error) {
+            if (error instanceof FakeRefused)
+                return fail(error.error);
+            if (isFakeError(error))
+                return fail(error);
+            throw error;
+        }
+    }
+    ownedRun(user, id) {
+        const run = user.runs.find((candidate) => candidate.id === id);
+        if (!run || run.deleted)
+            throw notFound();
+        return run;
+    }
+    respond(run, kind, messages) {
+        const responder = this.users.get(run.userId)?.responder ?? this.responder;
+        if (!responder)
+            return;
+        setImmediate(() => {
+            try {
+                Promise.resolve(responder({ run, kind, messages })).catch((error) => { this.responderErrors.push(error); });
+            }
+            catch (error) {
+                this.responderErrors.push(error);
+            }
+        });
+    }
+    idempotencyKey(raw) {
+        if (raw === null)
+            return null;
+        if (raw.length < 1 || raw.length > 255)
+            throw invalid('Idempotency-Key must be 1 to 255 characters');
+        return raw;
+    }
+    async handle(op, user, id, query, body, rawKey, signal, claims) {
+        switch (op) {
+            case 'grant.get': return this.grantGet(user, query, signal, claims);
+            case 'run.start': return this.runStart(user, body, rawKey);
+            case 'run.list': {
+                const status = query.get('status');
+                if (status && !['running', 'waiting_on_user', 'idle', 'settled'].includes(status))
+                    throw invalid('invalid status', 'status');
+                let after;
+                const rawAfter = query.get('after');
+                if (rawAfter) {
+                    try {
+                        const parsed = JSON.parse(Buffer.from(rawAfter, 'base64url').toString());
+                        if (typeof parsed.activity !== 'string' || typeof parsed.id !== 'string')
+                            throw new Error('invalid');
+                        after = { activity: parsed.activity, id: parsed.id };
+                    }
+                    catch {
+                        throw invalid('invalid list cursor', 'after');
+                    }
+                }
+                const limit = integerParam(query.get('limit'), 'limit', 1, 100, 50);
+                const rows = user.runs.filter((run) => !run.deleted)
+                    .sort((a, b) => (a.lastActivityAt === b.lastActivityAt ? (a.id < b.id ? 1 : -1) : a.lastActivityAt < b.lastActivityAt ? 1 : -1))
+                    .filter((run) => !after || run.lastActivityAt < after.activity || (run.lastActivityAt === after.activity && run.id < after.id))
+                    .filter((run) => !status || run.status === status);
+                const page = rows.slice(0, limit);
+                const last = page.at(-1);
+                return { status: 200, body: { runs: page.map((run) => run.toObject()), next: rows.length > limit && last ? Buffer.from(JSON.stringify({ activity: last.lastActivityAt, id: last.id })).toString('base64url') : null } };
+            }
+            case 'run.get': {
+                const wait = waitSeconds(query);
+                const run = this.ownedRun(user, id);
+                await run.waitResting(wait, signal);
+                return { status: 200, body: this.ownedRun(user, id).toObject() };
+            }
+            case 'run.message': return this.runMessage(user, this.ownedRun(user, id), body, rawKey);
+            case 'run.interrupt': {
+                const run = this.ownedRun(user, id);
+                const params = objectBody(body ?? {});
+                if (params['children'] !== undefined && params['children'] !== 'stop' && params['children'] !== 'continue')
+                    throw invalid('invalid children', 'children');
+                return { status: 200, body: run.toObject() };
+            }
+            case 'run.cancel': {
+                const run = this.ownedRun(user, id);
+                const params = objectBody(body ?? {});
+                if (params['keep_schedules'] !== undefined && typeof params['keep_schedules'] !== 'boolean')
+                    throw invalid('invalid keep_schedules', 'keep_schedules');
+                if (!run.outcome)
+                    run.settle({ failure: 'canceled' });
+                return { status: 200, body: run.toObject() };
+            }
+            case 'run.rename': {
+                const run = this.ownedRun(user, id);
+                const params = objectBody(body);
+                for (const field of Object.keys(params))
+                    if (field !== 'name')
+                        throw invalid(`unknown field ${field}`, field);
+                const name = params['name'];
+                if (typeof name !== 'string' || !name.trim() || name.length > 200)
+                    throw invalid('name must be a non-empty string of at most 200 characters', 'name');
+                run.name = name.trim();
+                return { status: 200, body: run.toObject() };
+            }
+            case 'run.delete': {
+                const run = this.ownedRun(user, id);
+                run.delete();
+                return { status: 200, body: { run_id: run.id, uploads_pending: 0 } };
+            }
+            case 'trace.get': {
+                const format = query.get('format');
+                if (format && format !== 'entries')
+                    throw invalid('unknown trace format', 'format');
+                const run = this.ownedRun(user, id);
+                return { status: 200, body: { run_id: run.id, latest_sequence: run.latestSequence, nodes: [] } };
+            }
+            case 'question.get': {
+                const { run, question } = this.question(user, id);
+                return { status: 200, body: run.questionObject(question) };
+            }
+            case 'question.answer': {
+                const { run, question } = this.question(user, id);
+                const current = run.questionObject(question);
+                if (current['status'] !== 'open')
+                    throw refuse(409, 'run_settled', `question ${question} is already ${String(current['status'])}`, { details: { state: current['status'] } });
+                const responses = body && typeof body === 'object' && !Array.isArray(body) ? body['responses'] : undefined;
+                if (!responses || typeof responses !== 'object' || Array.isArray(responses))
+                    throw invalid('responses must be an object keyed by slot id', 'responses');
+                run.answer(question, responses);
+                return { status: 200, body: { question_id: question, status: 'answered', answer: responses } };
+            }
+            case 'memory.list': return { status: 200, body: this.memoryList(user, query) };
+            case 'memory.get': {
+                this.memoryStore(query);
+                const name = query.get('name');
+                if (name === null)
+                    throw invalid('name is required', 'name');
+                if (!MEMORY_NAME.test(name))
+                    throw invalid('name must be segments of letters, digits, `_` or `-` joined by `/`', 'name');
+                const doc = user.memory.get(name);
+                if (!doc || !this.memoryVisible(user, doc))
+                    throw refuse(404, 'not_found', 'no memory document by that name');
+                // The served body is capped at 1 MiB on a whole UTF-8 character (`memoryGet`); `size` stays the full length.
+                const full = Buffer.from(doc.body, 'utf8');
+                let end = Math.min(full.length, MEMORY_BODY_MAX_BYTES);
+                while (end < full.length && end > 0 && (full[end] & 0xc0) === 0x80)
+                    end--;
+                return { status: 200, body: { ...memoryItem(doc), body: full.subarray(0, end).toString('utf8'), size: full.length, truncated: end < full.length, grantee: null } };
+            }
+            case 'provider.tools': return this.providerTools(user, id);
+            case 'provider.call': return this.providerCall(user, body, signal);
+            case 'profile.list': return { status: 200, body: { profiles: [{ profile_id: 'default', name: 'default', grantee: this.host.grantee, default_kind: 'general', default: true }] } };
+            default: throw notFound('unknown operation');
+        }
+    }
+    async grantGet(user, query, signal, claims) {
+        const wait = waitSeconds(query);
+        const since = query.get('since');
+        if (since !== null && !/^[A-Za-z0-9_-]{1,64}$/.test(since))
+            throw invalid('invalid since', 'since');
+        if (wait && since !== null && user.version() === since) {
+            await new Promise((resolve, reject) => {
+                const hold = { wake: () => { if (user.version() !== since)
+                        finish(); } };
+                const finish = () => { clearTimeout(timer); user.holds.delete(hold); signal?.removeEventListener('abort', onAbort); resolve(); };
+                const onAbort = () => { clearTimeout(timer); user.holds.delete(hold); reject(aborted(signal)); };
+                const timer = setTimeout(finish, wait * 1000);
+                user.holds.add(hold);
+                if (signal?.aborted)
+                    onAbort();
+                else
+                    signal?.addEventListener('abort', onAbort, { once: true });
+            });
+            if (!user.active)
+                throw refuse(401, 'grant_revoked', 'grant is not active');
+        }
+        return { status: 200, body: user.dto(typeof claims['exp'] === 'number' ? claims['exp'] : undefined) };
+    }
+    runStart(user, body, rawKey) {
+        const params = objectBody(body);
+        for (const field of ['mode', 'parent', 'fork_from', 'node_id', 'env', 'tools', 'system_prompt'])
+            if (params[field] !== undefined)
+                throw refuse(403, 'owner_only', `${field} is owner-only`, { param: field });
+        for (const field of ['payer', 'model', 'model_policy', 'deadline', 'kind'])
+            if (params[field] !== undefined)
+                throw invalid(`${field} is not available`, field);
+        for (const field of Object.keys(params))
+            if (!['prompt', 'scopes', 'metadata', 'profile', 'isolated', 'cwd', 'worktree', 'output_schema', 'message'].includes(field))
+                throw invalid(`unknown field ${field}`, field);
+        if (params['profile'] !== undefined && (typeof params['profile'] !== 'string' || !params['profile']))
+            throw invalid('profile must be a profile id', 'profile');
+        if (params['isolated'] !== undefined && typeof params['isolated'] !== 'boolean')
+            throw invalid('isolated must be a boolean', 'isolated');
+        if (params['cwd'] !== undefined && (params['isolated'] !== true || typeof params['cwd'] !== 'string' || !params['cwd']))
+            throw invalid('cwd is available only for an isolated run and must be an absolute path inside its root folder', 'cwd');
+        if (params['worktree'] !== undefined && params['isolated'] !== true)
+            throw invalid('worktree is not available', 'worktree');
+        if (params['isolated'] === true && params['worktree'] !== undefined)
+            throw invalid('worktree is unavailable for an isolated run', 'worktree');
+        if (typeof params['prompt'] !== 'string' || !params['prompt'].trim())
+            throw invalid('prompt is required', 'prompt');
+        if (params['message'] !== undefined && (typeof params['message'] !== 'string' || !params['message'].trim()))
+            throw invalid('message must be a non-empty string', 'message');
+        const metadata = params['metadata'] === undefined ? {} : objectBody(params['metadata']);
+        if (Buffer.byteLength(JSON.stringify(metadata)) > 4096)
+            throw invalid('metadata exceeds 4 KB', 'metadata');
+        const outputSchema = params['output_schema'];
+        if (outputSchema !== undefined) {
+            if (!outputSchema || typeof outputSchema !== 'object' || Array.isArray(outputSchema))
+                throw invalid('output_schema must be a JSON Schema object', 'output_schema');
+            if (Buffer.byteLength(JSON.stringify(outputSchema)) > 256 * 1024)
+                throw invalid('output_schema exceeds 256 KB', 'output_schema');
+        }
+        const scopes = requestedScopes(user.scopeStrings(), params['scopes'], this.host.grantee);
+        // `startRun` (core/runs/operations.ts) refuses an isolated run without the root launcher before the idempotency replay.
+        if (params['isolated'] === true && this.options.isolatedRuns === 'unavailable')
+            throw refuse(503, 'isolated_unavailable', 'isolated runs require the Linux root launcher', { param: 'isolated' });
+        const key = this.idempotencyKey(rawKey);
+        const message = params['message'];
+        const hash = sha256Hex(JSON.stringify({
+            prompt: params['prompt'], scopes, metadata, profile: params['profile'], isolated: params['isolated'], cwd: params['cwd'],
+            ...(outputSchema === undefined ? {} : { output_schema: outputSchema }), ...(message === undefined ? {} : { message }),
+        }));
+        if (key !== null) {
+            const entry = user.idempotent(key);
+            if (entry) {
+                if (entry.hash !== hash)
+                    throw refuse(409, 'idempotency_conflict', 'key used with a different request');
+                return { status: entry.status, body: structuredClone(entry.body) };
+            }
+        }
+        const runId = `run-${this.runSerial + 1}`;
+        // `startRun` checks an isolated run's `cwd` after the replay: it must be absolute and inside the run's root folder,
+        // `<apps root>/<app>/nodes/<run id>`, and a guest's apps root is `/apps`.
+        if (params['isolated'] === true && params['cwd'] !== undefined) {
+            const cwd = params['cwd'];
+            const beneath = posix.relative(this.isolatedRoot(runId), posix.resolve('/', cwd));
+            if (!cwd.startsWith('/') || beneath === '..' || beneath.startsWith('../') || posix.isAbsolute(beneath))
+                throw invalid('cwd must be inside the isolated root node folder', 'cwd');
+        }
+        this.runSerial++;
+        const run = new FakeRun(runId, user.id, params, key, this.host, metadata, scopes);
+        user.runs.push(run);
+        this.allRuns.push(run);
+        run.emit('run.started', { scopes, payer: 'user', usage: { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, cost_usd: 0 } });
+        const accepted = message === undefined ? undefined : run.accept(message, false, key);
+        const response = {
+            run_id: run.id, node_id: run.id, grantee: this.host.grantee, grant: user.grantId, rev: user.rev, scopes, payer: 'user',
+            status: 'running', created_at: run.createdAt, metadata, sequence_number: 0,
+            ...(accepted ? { message: { run_id: run.id, message_id: accepted.message_id, sequence_number: accepted.sequence_number } } : {}),
+        };
+        if (key !== null)
+            user.idempotency.set(key, { hash, runId: run.id, status: 201, body: structuredClone(response), createdAt: this.clock.now() });
+        this.respond(run, 'start', accepted ? [accepted] : []);
+        return { status: 201, body: response };
+    }
+    /** An isolated run's root folder on a guest (`appSpace(app).nodes/<run id>`, apps root `/apps`). */
+    isolatedRoot(runId) { return `/apps/${this.clientId}/nodes/${runId}`; }
+    runMessage(user, run, body, rawKey) {
+        const params = objectBody(body);
+        const text = params['message'];
+        if (typeof text !== 'string' || !text.trim())
+            throw invalid('message is required', 'message');
+        if (params['start_turn'] !== undefined && typeof params['start_turn'] !== 'boolean')
+            throw invalid('start_turn must be a boolean', 'start_turn');
+        const startTurn = params['start_turn'] ?? true;
+        const key = this.idempotencyKey(rawKey);
+        const hash = sha256Hex(JSON.stringify(['run.message', run.id, text, startTurn]));
+        if (key !== null) {
+            const entry = user.idempotent(key);
+            if (entry) {
+                if (entry.hash !== hash)
+                    throw refuse(409, 'idempotency_conflict', 'key used with a different request');
+                return { status: entry.status, body: structuredClone(entry.body) };
+            }
+        }
+        const reason = run.outcome?.reason;
+        if (reason === 'canceled' || reason === 'deadline_exceeded')
+            throw refuse(409, 'run_settled', 'canceled run cannot receive a message');
+        if (run.outcome && startTurn)
+            run.reopen();
+        const accepted = run.accept(text, startTurn, key);
+        const response = { run_id: run.id, message_id: accepted.message_id, sequence_number: accepted.sequence_number };
+        if (key !== null)
+            user.idempotency.set(key, { hash, runId: run.id, status: 202, body: structuredClone(response), createdAt: this.clock.now() });
+        if (startTurn)
+            this.respond(run, 'message', [accepted]);
+        return { status: 202, body: response };
+    }
+    question(user, questionId) {
+        const run = user.runs.find((candidate) => !candidate.deleted && candidate.questions.has(questionId));
+        if (!run)
+            throw refuse(404, 'not_found', 'question not found');
+        return { run, question: questionId };
+    }
+    memoryStore(query) {
+        const value = query.get('store');
+        if (value === null)
+            throw invalid('store is required', 'store');
+        if (value !== 'user')
+            throw invalid('store must be "user"', 'store');
+    }
+    memoryVisible(user, doc) {
+        return doc.privacy === 'public' || user.scopeStrings().some((scope) => covers(scope, 'crtr:memory:manage:user'));
+    }
+    memoryList(user, query) {
+        this.memoryStore(query);
+        const path = query.get('path');
+        if (path !== null && !MEMORY_NAME.test(path))
+            throw invalid('path must be name segments of letters, digits, `_` or `-` joined by `/`', 'path');
+        const kind = query.get('kind');
+        if (kind !== null && kind !== 'knowledge' && kind !== 'preference')
+            throw invalid('kind must be knowledge or preference', 'kind');
+        const raw = query.get('limit');
+        if (raw !== null && (!/^(0|[1-9]\d*)$/.test(raw) || Number(raw) < 1 || Number(raw) > 100))
+            throw invalid('limit must be an integer from 1 to 100', 'limit');
+        const limit = raw === null ? 50 : Number(raw);
+        const filter = createHash('sha256').update(JSON.stringify(['user', path, kind])).digest('base64url').slice(0, 16);
+        let after = null;
+        const cursor = query.get('cursor');
+        if (cursor !== null) {
+            try {
+                if (!/^[A-Za-z0-9_-]+$/.test(cursor))
+                    throw new Error('not base64url');
+                const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+                if (typeof value.n !== 'string' || !MEMORY_NAME.test(value.n) || value.f !== filter)
+                    throw new Error('mismatch');
+                after = value.n;
+            }
+            catch {
+                throw invalid('cursor is not the next_cursor of a previous page with the same store, path and kind', 'cursor');
+            }
+        }
+        const prefix = path === null ? null : `${path}/`;
+        const visible = [...user.memory.values()]
+            .filter((doc) => (kind === null || doc.kind === kind) && (prefix === null || doc.name.startsWith(prefix)) && (after === null || doc.name > after) && this.memoryVisible(user, doc))
+            .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        const page = visible.slice(0, limit);
+        const more = visible.length > limit;
+        return { items: page.map(memoryItem), next_cursor: more ? Buffer.from(JSON.stringify({ n: page.at(-1).name, f: filter }), 'utf8').toString('base64url') : null };
+    }
+    providerEntry(user, id, definition) {
+        const held = user.scopeStrings();
+        if (!held.some((scope) => scope.startsWith(`${id}:`)))
+            return null;
+        const displayName = definition.displayName ?? id;
+        if (definition.status && definition.status !== 'available') {
+            return { provider: id, display_name: displayName, status: definition.status, ...(definition.error ? { error: definition.error } : {}), groups: [], commands: [] };
+        }
+        const groups = new Map();
+        for (const [tool, spec] of Object.entries(definition.tools)) {
+            const group = spec.group ?? tool;
+            if (!held.includes(`${id}:${group}`))
+                continue;
+            const description = spec.description ?? tool;
+            groups.set(group, [...(groups.get(group) ?? []), { tool, description, summary: description, params: [], output: [] }]);
+        }
+        if (groups.size === 0)
+            return null;
+        return { provider: id, display_name: displayName, status: 'available', major: 1, groups: [...groups].map(([group, leaves]) => ({ group, leaves })), commands: [] };
+    }
+    providerTools(user, provider) {
+        if (provider !== undefined && (!PROVIDER_ID.test(provider) || provider === 'crtr'))
+            throw invalid('provider must be a provider id', 'provider');
+        const ids = [...this.providerDefs.keys()].sort();
+        const candidates = provider === undefined ? ids : ids.filter((id) => id === provider);
+        const visible = candidates.map((id) => this.providerEntry(user, id, this.providerDefs.get(id))).filter((entry) => entry !== null);
+        if (provider !== undefined) {
+            if (visible.length === 0)
+                throw refuse(404, 'not_found', `provider "${provider}" is not available`);
+            return { status: 200, body: visible[0] };
+        }
+        return { status: 200, body: { providers: visible } };
+    }
+    async providerCall(user, body, signal) {
+        const params = objectBody(body);
+        const provider = params['provider'];
+        if (typeof provider !== 'string' || !PROVIDER_ID.test(provider) || provider === 'crtr')
+            throw invalid('provider must be a provider id', 'provider');
+        const tool = params['tool'];
+        if (typeof tool !== 'string' || !tool.trim())
+            throw invalid('tool must be a non-empty string', 'tool');
+        const args = params['arguments'] ?? {};
+        if (!args || typeof args !== 'object' || Array.isArray(args))
+            throw invalid('arguments must be an object', 'arguments');
+        const definition = this.providerDefs.get(provider);
+        // The daemon installs a missing bundle on the first call (`ensureProviderBundle`) and answers any failure to do so,
+        // including a directory that serves no such provider, as a retryable `provider_unavailable` (core/providers/call.ts).
+        if (!definition)
+            throw refuse(503, 'provider_unavailable', `provider "${provider}" unavailable: bundle installation pending`);
+        if (definition.status && definition.status !== 'available') {
+            throw refuse(503, 'provider_unavailable', `provider "${provider}" unavailable: ${definition.error ?? 'bundle installation pending'}`);
+        }
+        const spec = definition.tools[tool.trim()];
+        if (!spec)
+            throw refuse(404, 'not_found', `tool "${tool}" is not in provider "${provider}"`, { param: 'tool' });
+        const scope = `${provider}:${spec.group ?? tool.trim()}`;
+        if (!user.scopeStrings().includes(scope))
+            throw refuse(403, 'scope_missing', `missing scope ${scope}`, { scope });
+        try {
+            const result = await spec.handler({ userId: user.id, arguments: args, signal });
+            return { status: 200, body: result ?? {} };
+        }
+        catch (error) {
+            if (isFakeError(error) || error instanceof FakeRefused)
+                throw error;
+            throw refuse(502, 'provider_error', error instanceof Error ? error.message : String(error), { origin: 'provider', retryable: false });
+        }
+    }
+}
+function memoryItem(doc) {
+    const cut = doc.name.lastIndexOf('/');
+    return {
+        name: doc.name, folder: cut < 0 ? '' : doc.name.slice(0, cut), kind: doc.kind, preview: doc.preview, summary: doc.summary,
+        privacy: doc.privacy, revision: doc.revision, created_at: doc.created_at, updated_at: doc.updated_at,
+    };
+}