@north-light/sdk 0.0.0 → 0.3.414

package/dist/testing/run.js

@@ -0,0 +1,429 @@
+import { envelopeBody, fakeError, nowIso } from './wire.js';
+const usage = () => ({ input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, cost_usd: 0 });
+const SUMMARY_MAX = 120;
+const KEEPALIVE_MS = 15_000;
+const BACKLOG_MAX_EVENTS = 1000;
+const BACKLOG_MAX_BYTES = 32 * 1024 * 1024;
+const SUBMIT_RESULT_TOOL = 'submit_result';
+/** `activity.tool.summary` as the daemon writes it: a command's first line, else a path; null otherwise. */
+export function toolCallSummary(args) {
+    if (!args || typeof args !== 'object')
+        return null;
+    const fields = args;
+    const raw = [fields['command'], fields['file_path'], fields['path']].find((value) => typeof value === 'string' && value.trim() !== '');
+    if (raw === undefined)
+        return null;
+    const line = raw.trim().split('\n')[0].trim();
+    return line.length > SUMMARY_MAX ? `${line.slice(0, SUMMARY_MAX - 1)}…` : line;
+}
+let entrySerial = 0;
+const entryId = () => `entry-${++entrySerial}`;
+/** One run the app started, and the test's handle on it. */
+export class FakeRun {
+    id;
+    userId;
+    host;
+    metadata;
+    scopes;
+    /** The run's start-time body, as received. */
+    params;
+    /** The `Idempotency-Key` of the start, or null. */
+    idempotencyKey;
+    /** Every message the run accepted; the start's `message` is the first, with `start_turn: false`. */
+    messages = [];
+    name;
+    createdAt;
+    lastActivityAt;
+    /** Kept events (`expireEvents` drops the oldest). */
+    log = [];
+    sequence = 0;
+    outcomeValue;
+    resultValue;
+    hasResult = false;
+    settledAt;
+    turnError;
+    rested = false;
+    answered = false;
+    override;
+    messageSerial = 0;
+    outcomeRevision = 0;
+    finalReport;
+    questions = new Map();
+    streams = new Set();
+    waiters = new Set();
+    deleted = false;
+    constructor(id, userId, params, idempotencyKey, host, metadata, scopes) {
+        this.id = id;
+        this.userId = userId;
+        this.host = host;
+        this.metadata = metadata;
+        this.scopes = scopes;
+        this.params = params;
+        this.idempotencyKey = idempotencyKey;
+        this.name = id;
+        this.createdAt = nowIso();
+        this.lastActivityAt = this.createdAt;
+    }
+    // ---- reads ---------------------------------------------------------------------------------------------------
+    /** Every kept event, in order. */
+    get events() { return this.log; }
+    get latestSequence() { return this.sequence; }
+    get earliestSequence() { return this.log[0]?.sequence_number ?? null; }
+    get outcome() { return this.outcomeValue; }
+    get result() { return this.resultValue; }
+    get lastTurnError() { return this.turnError; }
+    /** Messages not yet delivered to a turn (the start's `message` included). */
+    get pending() { return this.messages.filter((message) => !message.delivered); }
+    get pendingQuestionIds() { return [...this.questions.values()].filter((q) => q.status === 'open').map((q) => q.question_id); }
+    /** The run status, derived as the daemon's `runStatus` derives it. */
+    get status() {
+        if (this.outcomeValue)
+            return 'settled';
+        if (this.override || this.turnOpen() || this.answered || !this.rested || this.messages.some((m) => m.start_turn && !m.delivered))
+            return 'running';
+        return this.pendingQuestionIds.length ? 'waiting_on_user' : 'idle';
+    }
+    /** What the root is doing, derived from the event log as `runActivity` derives it with no open streaming block. */
+    get activity() {
+        if (this.status !== 'running')
+            return null;
+        if (this.override)
+            return this.override;
+        const turns = this.log.filter((e) => e.node_id === this.id && (e.type === 'node.turn.started' || e.type === 'node.turn.completed'));
+        const turn = turns.at(-1);
+        if (!turn)
+            return this.everStartedTurn() ? { phase: 'between_turns' } : { phase: 'starting' };
+        if (turn.type === 'node.turn.completed')
+            return { phase: 'between_turns' };
+        const calls = this.log.filter((e) => e.node_id === this.id && e.sequence_number > turn.sequence_number &&
+            (e.type === 'node.tool_call.started' || e.type === 'node.tool_call.completed'));
+        const done = new Set(calls.filter((c) => c.type === 'node.tool_call.completed').map((c) => c.tool_call_id));
+        const running = calls.filter((c) => c.type === 'node.tool_call.started' && !done.has(c.tool_call_id)).at(-1);
+        if (running) {
+            if (running.name === SUBMIT_RESULT_TOOL)
+                return { phase: 'submitting_result' };
+            return { phase: 'tool', tool: { name: running.name, summary: toolCallSummary(running.arguments ?? null) } };
+        }
+        return { phase: 'thinking' };
+    }
+    /** `run.get`'s body. */
+    toObject() {
+        const status = this.status;
+        return {
+            run_id: this.id, name: this.name, status,
+            ...(this.outcomeValue ? { outcome: this.outcomeValue } : {}),
+            ...(this.outcomeValue && this.hasResult ? { result: this.resultValue } : {}),
+            // `last_report` is the newest report body (`runObject`); a scripted ending writes no report, so it is absent.
+            pending_question_ids: status === 'settled' ? [] : this.pendingQuestionIds,
+            ...(this.turnError ? { last_turn_error: this.turnError } : {}),
+            usage: usage(), payer: 'user', scopes: this.scopes, metadata: this.metadata, created_at: this.createdAt,
+            ...(this.settledAt ? { settled_at: this.settledAt } : {}),
+            latest_sequence: this.sequence, last_activity_at: this.lastActivityAt, activity: this.activity,
+        };
+    }
+    // ---- scripting -------------------------------------------------------------------------------------------------
+    /** Append any run event; `nodeId` defaults to the root (another id is a child node's event). */
+    emit(type, fields, { nodeId } = {}) {
+        this.assertLive();
+        return this.append(type, fields, nodeId);
+    }
+    /** One turn answering `text`: turn started, `chunks` deltas, text done, turn completed. Delivers `messageIds`
+     *  (default: every pending message). */
+    reply(text, { chunks = 2, messageIds } = {}) {
+        this.turn(messageIds, (ids) => {
+            for (const piece of split(text, chunks))
+                this.append('node.output_text.delta', { delta: piece });
+            this.append('node.output_text.done', { text, stop_reason: 'stop', entry_id: entryId() });
+            this.turnError = undefined;
+            return { stop_reason: 'stop', ids };
+        });
+    }
+    /** The same turn ending in error: `last_turn_error` set, status idle. */
+    failTurn({ code, message, messageIds }) {
+        this.turn(messageIds, (ids) => {
+            this.append('node.output_text.done', { text: '', stop_reason: 'error', entry_id: entryId() });
+            this.turnError = { code, message };
+            return { stop_reason: 'error', ids, error: { code, message } };
+        });
+    }
+    /** Fake-only: status `running` with `activity` overridden until the next appended event. */
+    setActivity(activity, { at } = {}) {
+        this.assertLive();
+        this.override = activity;
+        this.lastActivityAt = at === undefined ? nowIso() : new Date(at).toISOString();
+        this.wake();
+    }
+    /** The run goes idle without a new turn (it stopped without submitting); undelivered start-turn mail is consumed. */
+    idle() {
+        this.assertLive();
+        this.rested = true;
+        this.answered = false;
+        this.override = undefined;
+        for (const message of this.messages)
+            if (message.start_turn)
+                message.delivered = true;
+        this.lastActivityAt = nowIso();
+        this.wake();
+    }
+    /** Record the run's ending and emit `node.settled`. */
+    settle(ending) {
+        this.assertLive();
+        if (this.outcomeValue)
+            throw new Error(`run ${this.id} is already settled`);
+        const settledAt = nowIso();
+        const base = { node_id: this.id, revision: ++this.outcomeRevision, settled_at: settledAt, structured_result: null, detail: null };
+        let outcome;
+        this.hasResult = false;
+        if ('result' in ending) {
+            this.finalReport = `${this.id}/reports/final`;
+            outcome = { ...base, final_report: this.finalReport, structured_result: ending.result ?? null, kind: 'result', reason: 'finalized', declined: null };
+            this.resultValue = ending.result;
+            this.hasResult = ending.result !== undefined;
+        }
+        else if ('declined' in ending) {
+            this.finalReport = `${this.id}/reports/final`;
+            outcome = { ...base, final_report: this.finalReport, kind: 'failure', reason: 'declined', declined: ending.declined, details: ending.declined };
+        }
+        else if ('failure' in ending) {
+            outcome = { ...base, final_report: null, kind: 'failure', reason: ending.failure, declined: null };
+        }
+        else {
+            outcome = { ...base, final_report: null, kind: 'failure', reason: 'runtime_error', declined: null, details: { crouter_reason: ending.runtimeError } };
+        }
+        this.outcomeValue = outcome;
+        this.settledAt = settledAt;
+        this.override = undefined;
+        for (const question of this.questions.values())
+            if (question.status === 'open')
+                question.status = 'canceled';
+        this.append('node.settled', { outcome, usage: usage(), ...(this.hasResult ? { result: this.resultValue } : {}) });
+    }
+    /** Open a question: a `waiting_on_user` event; the run waits on the user between turns. Returns its id. */
+    ask(question) {
+        this.assertLive();
+        const id = `question-${this.id}-${this.questions.size + 1}`;
+        const slots = question.slots ?? [{ id: 'answer', kind: 'text', step: 0, config: {} }];
+        const steps = question.steps ?? 1;
+        this.questions.set(id, { question_id: id, title: question.title, ...(question.subtitle === undefined ? {} : { subtitle: question.subtitle }), steps, slots, status: 'open' });
+        this.rested = true;
+        this.append('waiting_on_user', {
+            question_id: id, initiating_app: this.host.grantee, title: question.title,
+            ...(question.subtitle === undefined ? {} : { subtitle: question.subtitle }),
+            ...(question.provider === undefined ? {} : { provider: question.provider }),
+            ...(question.tool === undefined ? {} : { tool: question.tool }),
+            steps, slots,
+        });
+        return id;
+    }
+    /** Delete the run as the runtime does: reads answer 404, streams close, its idempotency keys are dropped. */
+    delete() {
+        if (this.deleted)
+            return;
+        this.deleted = true;
+        // The listener's next read finds no run: open streams get the 404 error frame, then close.
+        for (const stream of [...this.streams])
+            stream.error(fakeError({ status: 404, code: 'not_found', message: 'run not found' }));
+        this.host.deleted(this);
+        this.wake();
+    }
+    /** Idle-close every open stream now. */
+    closeIdle() { for (const stream of [...this.streams])
+        stream.idle(); }
+    /** Drop kept events up to `upTo` (event expiry; makes `stream_gap` reachable). */
+    expireEvents(upTo) { this.log = this.log.filter((event) => event.sequence_number > upTo); }
+    // ---- runtime side (used by the fake runtime) ---------------------------------------------------------------------
+    /** Record an accepted message; returns it. */
+    accept(text, startTurn, idempotencyKey) {
+        const message_id = `msg-${this.id}-${++this.messageSerial}`;
+        const event = this.append('node.message.accepted', { message_id, start_turn: startTurn });
+        const message = { message_id, text, start_turn: startTurn, sequence_number: event.sequence_number, idempotencyKey, delivered: false };
+        this.messages.push(message);
+        this.wake();
+        return message;
+    }
+    /** Clear a non-canceled ending so a start-turn message runs it again (`commitReopenResident`). */
+    reopen() {
+        this.outcomeValue = undefined;
+        this.resultValue = undefined;
+        this.hasResult = false;
+        this.settledAt = undefined;
+    }
+    /** The app answered a question. */
+    answer(questionId, responses) {
+        const question = this.questions.get(questionId);
+        question.status = 'answered';
+        question.answer = responses;
+        this.answered = true;
+        this.append('question.answered', { question_id: questionId, answer: responses });
+    }
+    questionObject(questionId) {
+        const q = this.questions.get(questionId);
+        if (!q)
+            return undefined;
+        return {
+            question_id: q.question_id, initiating_app: this.host.grantee, title: q.title, ...(q.subtitle === undefined ? {} : { subtitle: q.subtitle }),
+            steps: q.steps, slots: q.slots, run_id: this.id, node_id: this.id, status: q.status, ...(q.answer ? { answer: q.answer } : {}),
+        };
+    }
+    /** Resolves when the run rests (`idle`, `waiting_on_user`, `settled`), is deleted, `seconds` pass, or `signal` aborts. */
+    async waitResting(seconds, signal) {
+        const resting = () => this.deleted || this.status !== 'running';
+        if (!seconds || resting())
+            return;
+        await new Promise((resolve, reject) => {
+            const finish = () => { clearTimeout(timer); this.waiters.delete(check); signal?.removeEventListener('abort', onAbort); resolve(); };
+            const check = () => { if (resting())
+                finish(); };
+            const onAbort = () => { clearTimeout(timer); this.waiters.delete(check); reject(signal.reason ?? new DOMException('aborted', 'AbortError')); };
+            const timer = setTimeout(finish, seconds * 1000);
+            this.waiters.add(check);
+            if (signal?.aborted)
+                onAbort();
+            else
+                signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    /** The SSE body after `after`, as `streamRunEvents` writes it. Validation happens before the caller calls this. */
+    openStream(after, signal) {
+        const encoder = new TextEncoder();
+        let position = after;
+        let closed = false;
+        let release = () => { };
+        let idleTimer;
+        let keepalive;
+        let controllerRef;
+        const write = (text) => { if (!closed) {
+            try {
+                controllerRef.enqueue(encoder.encode(text));
+            }
+            catch { /* reader gone */ }
+        } };
+        const stream = {
+            push: (event) => {
+                if (closed || event.sequence_number <= position)
+                    return;
+                write(`id: ${event.sequence_number}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`);
+                position = event.sequence_number;
+                lastMove = Date.now();
+            },
+            idle: () => { write('event: idle\ndata: {}\n\n'); stream.end(); },
+            error: (error) => { write(`event: error\ndata: ${JSON.stringify(envelopeBody(error, this.id))}\n\n`); stream.end(); },
+            end: () => {
+                if (closed)
+                    return;
+                closed = true;
+                this.streams.delete(stream);
+                if (idleTimer)
+                    clearInterval(idleTimer);
+                if (keepalive)
+                    clearInterval(keepalive);
+                signal?.removeEventListener('abort', stream.end);
+                release(position);
+                try {
+                    controllerRef.close();
+                }
+                catch { /* already closed */ }
+            },
+        };
+        let lastMove = Date.now();
+        return new ReadableStream({
+            start: (controller) => {
+                controllerRef = controller;
+                write(': connected\n\n');
+                this.streams.add(stream);
+                release = this.host.streamOpened(this);
+                // A reader this far behind is dropped rather than replayed (`readRunEvents`/`streamRunEvents`).
+                const backlog = this.log.filter((event) => event.sequence_number > after);
+                if (backlog.length > BACKLOG_MAX_EVENTS || backlog.reduce((bytes, event) => bytes + encoder.encode(JSON.stringify(event)).byteLength, 0) > BACKLOG_MAX_BYTES) {
+                    stream.error(fakeError({ status: 503, code: 'stream_dropped', message: 'stream reader fell behind', details: { last_sequence: after }, retryable: true }));
+                    return;
+                }
+                for (const event of backlog)
+                    stream.push(event);
+                if (closed)
+                    return;
+                if (!this.host.grantActive(this.userId)) {
+                    stream.error(fakeError({ status: 401, code: 'grant_revoked', message: 'grant is not active' }));
+                    return;
+                }
+                const idleMs = this.host.streamIdleMs;
+                idleTimer = setInterval(() => {
+                    if (closed)
+                        return;
+                    if (this.status === 'running') {
+                        lastMove = Date.now();
+                        return;
+                    }
+                    if (Date.now() - lastMove >= idleMs)
+                        stream.idle();
+                }, Math.max(5, Math.min(1000, Math.floor(idleMs / 4))));
+                idleTimer.unref?.();
+                keepalive = setInterval(() => write(': keepalive\n\n'), KEEPALIVE_MS);
+                keepalive.unref?.();
+                if (signal?.aborted)
+                    stream.end();
+                else
+                    signal?.addEventListener('abort', stream.end, { once: true });
+            },
+            cancel: () => stream.end(),
+        });
+    }
+    /** The grant went inactive: every open stream gets the 401 `grant_revoked` error frame. */
+    revokeStreams() {
+        for (const stream of [...this.streams])
+            stream.error(fakeError({ status: 401, code: 'grant_revoked', message: 'grant is not active' }));
+    }
+    get openStreams() { return this.streams.size; }
+    /** Notify held reads that state changed. */
+    wake() { for (const waiter of [...this.waiters])
+        waiter(); }
+    // ---- internals -------------------------------------------------------------------------------------------------
+    assertLive() { if (this.deleted)
+        throw new Error(`run ${this.id} was deleted`); }
+    turnOpen() {
+        const turn = this.log.filter((e) => e.node_id === this.id && (e.type === 'node.turn.started' || e.type === 'node.turn.completed')).at(-1);
+        return turn?.type === 'node.turn.started';
+    }
+    everStartedTurn() { return this.turnsStarted > 0; }
+    turnsStarted = 0;
+    turn(messageIds, body) {
+        this.assertLive();
+        if (this.outcomeValue)
+            throw new Error(`run ${this.id} is settled; message it first to reopen`);
+        const delivering = messageIds === undefined ? this.pending : this.messages.filter((m) => messageIds.includes(m.message_id));
+        const ids = messageIds ?? delivering.map((m) => m.message_id);
+        const text = delivering.length ? delivering.map((m) => m.text).join('\n\n') : this.turnsStarted === 0 ? this.params.prompt : '';
+        this.turnsStarted++;
+        this.append('node.turn.started', { input: { text, message_ids: ids }, entry_id: entryId() });
+        for (const message of delivering)
+            message.delivered = true;
+        const ending = body(ids);
+        this.rested = true;
+        this.answered = false;
+        // The status the run reads once this turn is closed (`run_status` is written as the turn ends).
+        const status = this.messages.some((m) => m.start_turn && !m.delivered) ? 'running' : this.pendingQuestionIds.length ? 'waiting_on_user' : 'idle';
+        this.append('node.turn.completed', {
+            message_ids: ending.ids, run_status: status, stop_reason: ending.stop_reason,
+            ...(ending.error ? { error: ending.error } : {}), entry_id: entryId(),
+        });
+    }
+    append(type, fields, nodeId) {
+        const event = { ...fields, type, run_id: this.id, node_id: nodeId ?? this.id, sequence_number: ++this.sequence, ts: nowIso(), metadata: this.metadata };
+        this.log.push(event);
+        this.override = undefined;
+        this.lastActivityAt = event.ts;
+        for (const stream of [...this.streams])
+            stream.push(event);
+        this.host.appended(this);
+        this.wake();
+        return event;
+    }
+}
+function split(text, chunks) {
+    const count = Math.max(1, Math.min(chunks, Math.max(1, text.length)));
+    const size = Math.ceil(text.length / count);
+    const pieces = [];
+    for (let i = 0; i < count; i++)
+        pieces.push(text.slice(i * size, (i + 1) * size));
+    return pieces.filter((piece, i) => piece !== '' || i === 0);
+}

package/dist/testing/users.d.ts

@@ -0,0 +1,121 @@
+import type { GrantGetDTO, ProviderDependency, SetupState } from '@north-light/api';
+import type { FakeRun } from './run.js';
+/** The directory's reasons for refusing a refresh token (the SDK's refusal table). */
+export type FakeRefusalCode = 'grant_removed' | 'grant_suspended' | 'refresh_token_expired' | 'refresh_token_reused' | 'grant_revoked';
+/** What a run's responder receives. */
+export interface ResponderInput {
+    run: FakeRun;
+    /** `start` after `run.start`; `message` after a `run.message` with `start_turn` true. */
+    kind: 'start' | 'message';
+    /** The messages that request accepted (a start without `message` has none). */
+    messages: FakeRun['messages'][number][];
+}
+/** Called after the fake answered a `run.start`, or a `run.message` with `start_turn` true; never for a replay. */
+export type Responder = (input: ResponderInput) => void | Promise<void>;
+/** A scope the grant holds: a string is `mode: 'always'`. */
+export type FakeScope = string | {
+    scope: string;
+    mode: 'always' | 'ask';
+};
+/** A document in the person's memory. */
+export interface FakeMemoryDoc {
+    name: string;
+    body: string;
+    privacy?: 'public' | 'friends' | 'private';
+    kind?: 'knowledge' | 'preference';
+    created_at?: string;
+    updated_at?: string;
+    summary?: string | null;
+    preview?: string;
+    revision?: number;
+}
+export type StoredMemoryDoc = Required<Omit<FakeMemoryDoc, 'summary'>> & {
+    summary: string | null;
+};
+interface Hold {
+    wake(): void;
+}
+/** One entry of the per-user idempotency map (the daemon's `idempotency_keys` row). */
+export interface IdempotencyEntry {
+    hash: string;
+    runId: string;
+    status: number;
+    body: unknown;
+}
+export declare const normalizeScopes: (scopes: readonly FakeScope[]) => GrantGetDTO["resolved_scopes"];
+/** Internal per-user state. */
+export declare class UserState {
+    readonly id: string;
+    readonly clientId: string;
+    private readonly onRevoke;
+    active: boolean;
+    rev: number;
+    resolvedScopes: GrantGetDTO['resolved_scopes'];
+    spendCap: number | null;
+    dependencies: Record<string, ProviderDependency>;
+    /** The directory's answer to this user's refreshes: null is `ok`. */
+    refusal: FakeRefusalCode | null;
+    /** The valid refresh token, or null before the first connect. */
+    refreshToken: string | null;
+    /** Access tokens with a serial below this answer 401 `unauthorized`. */
+    minSerial: number;
+    readonly grantId: string;
+    readonly runs: FakeRun[];
+    responder: Responder | null;
+    readonly memory: Map<string, StoredMemoryDoc>;
+    readonly idempotency: Map<string, IdempotencyEntry>;
+    readonly holds: Set<Hold>;
+    constructor(id: string, clientId: string, onRevoke: (user: UserState) => void);
+    dto(exp?: number): GrantGetDTO | null;
+    version(): string | null;
+    /** The scopes the runtime authorizes with: only `always` ones (`activeRecord`, core/grants/mirror.ts). An `ask`
+     *  scope is listed on the grant but grants nothing until the person approves it. */
+    scopeStrings(): string[];
+    wakeHolds(): void;
+    apply(patch: GrantPatch): void;
+    revoke(code: FakeRefusalCode): void;
+    putMemory(doc: FakeMemoryDoc): void;
+}
+/** `grant.set` / `grant.restore` patch. */
+export interface GrantPatch {
+    dependencies?: Record<string, ProviderDependency>;
+    resolved_scopes?: FakeScope[];
+    spend_cap?: number | null;
+}
+/** The test's handle on one person. */
+export interface FakeUser {
+    readonly id: string;
+    readonly grant: {
+        /** The current `GrantGetDTO`, or null when the grant is inactive. */
+        readonly state: GrantGetDTO | null;
+        /** Merge any of `dependencies`, `resolved_scopes`, `spend_cap`; `rev` +1. Wakes held reads. */
+        set(patch: GrantPatch): void;
+        /** Set one provider dependency without a `rev` bump; `version` changes. Wakes held reads. */
+        setup(provider: string, state: SetupState, options?: {
+            message?: string;
+            next?: string;
+        }): void;
+        /** A grant sync with unchanged content: nothing changes, no held read wakes. */
+        sync(): void;
+        /** The grant goes inactive; the directory refuses refreshes with `code`. */
+        revoke(code?: FakeRefusalCode): void;
+        /** Active again at `rev` +1; the directory answers `ok`. */
+        restore(patch?: GrantPatch): void;
+    };
+    /** The directory refuses each refresh with `code` (`'ok'` clears it); tokens issued before now answer 401 `unauthorized`. */
+    refuse(code: FakeRefusalCode | 'ok'): void;
+    /** Tokens issued before now answer 401 `unauthorized`, forcing a refresh; the directory's answer is unchanged. */
+    expireTokens(): void;
+    /** This user's `grant.get` calls. */
+    readonly reads: import('./cloud.js').FakeCall[];
+    /** `grant.get` reads held right now. */
+    readonly holding: number;
+    /** This user's runs (`runs.all`, in start order); `runs.respond(fn)` overrides the cloud's responder for this user
+     *  (null clears it). The same shape as `cloud.runs`. */
+    readonly runs: import('./cloud.js').FakeRuns;
+    readonly memory: {
+        put(doc: FakeMemoryDoc): void;
+        remove(name: string): void;
+    };
+}
+export {};

package/dist/testing/users.js

@@ -0,0 +1,70 @@
+import { grantVersion, nowIso } from './wire.js';
+export const normalizeScopes = (scopes) => scopes.map((scope) => (typeof scope === 'string' ? { scope, mode: 'always' } : { scope: scope.scope, mode: scope.mode }));
+/** Internal per-user state. */
+export class UserState {
+    id;
+    clientId;
+    onRevoke;
+    active = false;
+    rev = 0;
+    resolvedScopes = [];
+    spendCap = null;
+    dependencies = {};
+    /** The directory's answer to this user's refreshes: null is `ok`. */
+    refusal = null;
+    /** The valid refresh token, or null before the first connect. */
+    refreshToken = null;
+    /** Access tokens with a serial below this answer 401 `unauthorized`. */
+    minSerial = 0;
+    grantId;
+    runs = [];
+    responder = null;
+    memory = new Map();
+    idempotency = new Map();
+    holds = new Set();
+    constructor(id, clientId, onRevoke) {
+        this.id = id;
+        this.clientId = clientId;
+        this.onRevoke = onRevoke;
+        this.grantId = `grant-${id.replace(/^user:/, '')}`;
+    }
+    dto(exp = Math.floor(Date.now() / 1000) + 3600) {
+        if (!this.active)
+            return null;
+        const body = {
+            sub: this.id, grantee: `app:${this.clientId}`, client_id: this.clientId, grant: this.grantId, exp, rev: this.rev,
+            resolved_scopes: this.resolvedScopes, spend_cap: this.spendCap, payer: 'user', dependencies: this.dependencies,
+        };
+        return { ...body, version: grantVersion(body) };
+    }
+    version() { return this.active ? this.dto().version : null; }
+    /** The scopes the runtime authorizes with: only `always` ones (`activeRecord`, core/grants/mirror.ts). An `ask`
+     *  scope is listed on the grant but grants nothing until the person approves it. */
+    scopeStrings() { return this.resolvedScopes.filter((entry) => entry.mode === 'always').map((entry) => entry.scope); }
+    wakeHolds() { for (const hold of [...this.holds])
+        hold.wake(); }
+    apply(patch) {
+        if (patch.resolved_scopes !== undefined)
+            this.resolvedScopes = normalizeScopes(patch.resolved_scopes);
+        if (patch.spend_cap !== undefined)
+            this.spendCap = patch.spend_cap;
+        if (patch.dependencies !== undefined)
+            this.dependencies = { ...patch.dependencies };
+    }
+    revoke(code) {
+        this.active = false;
+        this.refusal = code;
+        this.wakeHolds();
+        this.onRevoke(this);
+    }
+    putMemory(doc) {
+        const existing = this.memory.get(doc.name);
+        const now = nowIso();
+        this.memory.set(doc.name, {
+            name: doc.name, body: doc.body, privacy: doc.privacy ?? 'public', kind: doc.kind ?? 'knowledge',
+            created_at: doc.created_at ?? existing?.created_at ?? now, updated_at: doc.updated_at ?? now,
+            summary: doc.summary ?? null, preview: doc.preview ?? doc.body.slice(0, 200),
+            revision: doc.revision ?? (existing ? existing.revision + 1 : 1),
+        });
+    }
+}