@north-light/sdk 0.0.0 → 0.3.415

package/dist/testing/conformance/index.d.ts

@@ -0,0 +1,2 @@
+export { IDEMPOTENCY_WINDOW_MS, keyedWriteScenarios } from './keyed-write.js';
+export type { AcceptedMessage, KeyedWriteCaller, KeyedWriteFailure, KeyedWriteScenario, KeyedWriteTarget } from './keyed-write.js';

package/dist/testing/conformance/index.js

@@ -0,0 +1,3 @@
+// `@north-light/sdk/testing/conformance`: executable scenarios that hold a test double of the crouter runtime to the
+// daemon's real behaviour. Framework-agnostic: they assert with `node:assert/strict` and run under any test runner.
+export { IDEMPOTENCY_WINDOW_MS, keyedWriteScenarios } from './keyed-write.js';

package/dist/testing/conformance/keyed-write.d.ts

@@ -0,0 +1,43 @@
+/** How long a kept key replays, in ms. A record of this age or older reads as absent. Equal to the daemon's constant. */
+export declare const IDEMPOTENCY_WINDOW_MS = 86400000;
+/** A message the run accepted, in acceptance order. */
+export interface AcceptedMessage {
+    id: string;
+    text: string;
+}
+/** What a target's `classify` makes of a thrown error. */
+export type KeyedWriteFailure = 'idempotency_conflict' | 'run_settled' | 'other';
+/**
+ * One caller on the target: a person using an app, with keys of their own. The daemon scopes a key to the app (the
+ * grantee), so two callers that must not share keys are different apps there; on a target scoped by person they are
+ * different people. Every write carries an `Idempotency-Key`.
+ */
+export interface KeyedWriteCaller {
+    /** Start a run; returns the run id. */
+    start(key: string, prompt: string): Promise<string>;
+    /** A message that starts a turn; returns the message id. */
+    message(runId: string, key: string, text: string): Promise<string>;
+    /** A message with `start_turn: false`; returns the message id. */
+    note(runId: string, key: string, text: string): Promise<string>;
+    /** Cancel the run. */
+    cancel(runId: string): Promise<void>;
+    /** The messages the run accepted, in order. A start without `message` contributes none. */
+    accepted(runId: string): Promise<AcceptedMessage[]>;
+}
+/** What a runtime double (or the daemon) supplies; the scenarios call nothing else. */
+export interface KeyedWriteTarget {
+    /** A new, independent caller that shares no keys with any other: one the target has never seen, with an active grant. */
+    user(): Promise<KeyedWriteCaller> | KeyedWriteCaller;
+    /** Make every stored key `ms` older: advance the target's clock, or backdate the records. A target on the real clock
+     *  keeps running while a scenario does, so K4 stops a minute short of the window instead of one ms short; a target
+     *  on a manual clock proves the exact boundary in its own test. */
+    age(ms: number): Promise<void> | void;
+    /** Map the target's thrown error. */
+    classify(error: unknown): KeyedWriteFailure;
+}
+export interface KeyedWriteScenario {
+    /** `K1 …`: stable, unique, safe to use as a test title. */
+    name: string;
+    run(target: KeyedWriteTarget): Promise<void>;
+}
+export declare const keyedWriteScenarios: KeyedWriteScenario[];

package/dist/testing/conformance/keyed-write.js

@@ -0,0 +1,124 @@
+// Keyed-write scenarios K1–K8: the idempotent accept of `run.start` and `run.message`, as the daemon defines it
+// (core/runs/operations.ts). Scope is (grantee, key); the two operations share one key space; the request hash
+// covers the operation and its target; a record at least `IDEMPOTENCY_WINDOW_MS` old reads as absent.
+import assert from 'node:assert/strict';
+/** How long a kept key replays, in ms. A record of this age or older reads as absent. Equal to the daemon's constant. */
+export const IDEMPOTENCY_WINDOW_MS = 86_400_000;
+async function failure(target, attempt) {
+    const settled = await Promise.allSettled([attempt]);
+    const [result] = settled;
+    assert.equal(result.status, 'rejected', 'the write was expected to fail but was accepted');
+    return target.classify(result.reason);
+}
+/** How far short of the window K4's first leg stops: more than a real-clock target can run during the scenario. */
+const SHORT_OF_WINDOW_MS = 60_000;
+const ids = (messages) => messages.map((message) => message.id);
+/** A fresh run for a scenario to write to: its own caller and a start key unique to the scenario. */
+async function fresh(target, label) {
+    const caller = await target.user();
+    return { caller, runId: await caller.start(`${label}-start`, `${label} prompt`) };
+}
+export const keyedWriteScenarios = [
+    {
+        name: 'K1 an equal key replays the first answer',
+        async run(target) {
+            const caller = await target.user();
+            const first = await caller.start('k1-start', 'hello');
+            assert.equal(await caller.start('k1-start', 'hello'), first, 'a repeated start returns the same run id');
+            const m1 = await caller.message(first, 'k1-msg', 'one');
+            assert.equal(await caller.message(first, 'k1-msg', 'one'), m1, 'a repeated message returns the same message id');
+            assert.deepEqual(await caller.accepted(first), [{ id: m1, text: 'one' }]);
+        },
+    },
+    {
+        name: 'K2 a key reused with another request is idempotency_conflict',
+        async run(target) {
+            const { caller, runId } = await fresh(target, 'k2');
+            const m1 = await caller.message(runId, 'k2-msg', 'one');
+            assert.equal(await failure(target, caller.message(runId, 'k2-msg', 'other')), 'idempotency_conflict');
+            assert.equal(await failure(target, caller.start('k2-start', 'another prompt')), 'idempotency_conflict');
+            assert.deepEqual(await caller.accepted(runId), [{ id: m1, text: 'one' }], 'the refused write accepted nothing');
+        },
+    },
+    {
+        name: 'K3 concurrent equal-key writes are accepted once',
+        async run(target) {
+            const { caller, runId } = await fresh(target, 'k3');
+            const messages = await Promise.all([1, 2, 3].map(() => caller.message(runId, 'k3-msg', 'same')));
+            assert.equal(new Set(messages).size, 1, 'three concurrent messages return one message id');
+            assert.deepEqual(await caller.accepted(runId), [{ id: messages[0], text: 'same' }]);
+            const starts = await Promise.all([1, 2, 3].map(() => caller.start('k3-concurrent-start', 'same prompt')));
+            assert.equal(new Set(starts).size, 1, 'three concurrent starts return one run id');
+        },
+    },
+    {
+        name: 'K4 a key expires after the window',
+        async run(target) {
+            const { caller, runId } = await fresh(target, 'k4');
+            const m1 = await caller.message(runId, 'k4-msg', 'one');
+            await target.age(IDEMPOTENCY_WINDOW_MS - SHORT_OF_WINDOW_MS);
+            assert.equal(await caller.message(runId, 'k4-msg', 'one'), m1, 'a key short of the window still replays');
+            assert.equal((await caller.accepted(runId)).length, 1);
+            await target.age(SHORT_OF_WINDOW_MS);
+            const m2 = await caller.message(runId, 'k4-msg', 'one');
+            assert.notEqual(m2, m1, 'a key at the window reads as absent: the write is accepted anew');
+            assert.deepEqual(ids(await caller.accepted(runId)), [m1, m2]);
+        },
+    },
+    {
+        name: 'K5 a replay after cancel returns the original; a new write is run_settled',
+        async run(target) {
+            for (const kind of ['message', 'note']) {
+                const { caller, runId } = await fresh(target, `k5-${kind}`);
+                const write = (key) => (kind === 'message' ? caller.message(runId, key, 'text') : caller.note(runId, key, 'text'));
+                const first = await write('k5-key');
+                await caller.cancel(runId);
+                assert.equal(await write('k5-key'), first, `a ${kind} key replays its original after cancel`);
+                assert.equal(await failure(target, write('k5-new')), 'run_settled', `a new ${kind} key on a canceled run`);
+                assert.deepEqual(await caller.accepted(runId), [{ id: first, text: 'text' }], 'nothing new was accepted');
+            }
+        },
+    },
+    {
+        name: 'K6 a key is bound to its operation',
+        async run(target) {
+            const { caller, runId } = await fresh(target, 'k6');
+            assert.equal(await failure(target, caller.message(runId, 'k6-start', 'x')), 'idempotency_conflict', 'a start key presented to message');
+            const m1 = await caller.message(runId, 'k6-msg', 'same text');
+            assert.equal(await failure(target, caller.note(runId, 'k6-msg', 'same text')), 'idempotency_conflict', 'a message key presented to note');
+            const n1 = await caller.note(runId, 'k6-note', 'same text');
+            assert.equal(await failure(target, caller.message(runId, 'k6-note', 'same text')), 'idempotency_conflict', 'a note key presented to message');
+            assert.deepEqual(ids(await caller.accepted(runId)), [m1, n1], 'only the first writes were accepted');
+        },
+    },
+    {
+        name: 'K7 keys are scoped to the grantee',
+        async run(target) {
+            const a = await target.user();
+            const b = await target.user();
+            const runA = await a.start('k7-start', 'a prompt');
+            const m1 = await a.message(runA, 'k7-msg', 'text');
+            const runB = await b.start('k7-start', 'b prompt');
+            assert.notEqual(runB, runA, "B's start under A's key is a new run, not a conflict");
+            const m2 = await b.message(runB, 'k7-msg', 'text');
+            assert.deepEqual(await b.accepted(runB), [{ id: m2, text: 'text' }]);
+            assert.deepEqual(await a.accepted(runA), [{ id: m1, text: 'text' }], "B's writes did not touch A's run");
+        },
+    },
+    {
+        name: 'K8 concurrent notes, and a note against a message, are accepted once',
+        async run(target) {
+            const { caller, runId } = await fresh(target, 'k8');
+            const notes = await Promise.all([1, 2, 3].map(() => caller.note(runId, 'k8-note', 'noted')));
+            assert.equal(new Set(notes).size, 1, 'three concurrent notes return one message id');
+            assert.deepEqual(await caller.accepted(runId), [{ id: notes[0], text: 'noted' }]);
+            const pair = await Promise.allSettled([caller.message(runId, 'k8-pair', 'same'), caller.note(runId, 'k8-pair', 'same')]);
+            const accepted = pair.filter((result) => result.status === 'fulfilled');
+            const refused = pair.filter((result) => result.status === 'rejected');
+            assert.equal(accepted.length, 1, 'exactly one of the pair is accepted');
+            assert.equal(refused.length, 1);
+            assert.equal(target.classify(refused[0].reason), 'idempotency_conflict', 'the other is idempotency_conflict');
+            assert.equal((await caller.accepted(runId)).length, 2, 'the note and one of the pair');
+        },
+    },
+];

package/dist/testing/index.d.ts

@@ -0,0 +1,7 @@
+export { FakeCloud } from './cloud.js';
+export { manualClock } from './clock.js';
+export type { ManualClock } from './clock.js';
+export type { FakeAnswer, FakeCall, FakeCloudOptions, FakeDirectoryCall, FakeDirectoryOp, FakeInterceptOp, FakeOp, FakeProvider, FakeRuns, FakeToolHandler, Intercept, } from './cloud.js';
+export type { FakeRun, FakeRunEnding, FakeRunMessage, FakeRunParams, FakeQuestion } from './run.js';
+export type { FakeNotice, RunNoticeOptions } from './notices.js';
+export type { FakeMemoryDoc, FakeRefusalCode, FakeScope, FakeUser, GrantPatch, Responder, ResponderInput } from './users.js';

package/dist/testing/index.js

@@ -0,0 +1,4 @@
+// `@north-light/sdk/testing`: a fake crouter cloud (directory + runtime) your real `OAuth2Client` and `Crouter` talk to
+// through `fetch`. Node-only; no test framework. See docs/sdk/testing.md.
+export { FakeCloud } from './cloud.js';
+export { manualClock } from './clock.js';

package/dist/testing/notices.d.ts

@@ -0,0 +1,76 @@
+import { type JWK } from 'jose';
+import type { FakeRun } from './run.js';
+/** One notice attempt (`cloud.notices`). */
+export interface FakeNotice {
+    runId: string;
+    userId: string;
+    /** 1–3. */
+    attempt: number;
+    /** Whether this request followed a 401 within the same attempt. */
+    remint: boolean;
+    latestSequence: number;
+    /** The decoded token payload. */
+    claims: Record<string, unknown>;
+    /** The app's status, or null when `deliver` threw. */
+    status: number | null;
+    /** The thrown message, or null. */
+    error: string | null;
+    at: number;
+}
+export interface RunNoticeOptions {
+    /** The app's registered `run_notice_url`: the token's `aud` and the POST target. */
+    url: string;
+    /** The app's route handler. */
+    deliver: (request: Request) => Promise<Response>;
+    /** Waits before attempts 2 and 3 (daemon: `[3_000, 5_000]`). Default `[0, 0]`. */
+    retryWaitsMs?: number[];
+    /** Gap after a delivered notice (daemon: 5_000). Default 0. */
+    ackGapMs?: number;
+    /** Gap after a dropped notice (daemon: 60_000). Default 0. */
+    failGapMs?: number;
+}
+/** The cloud's one ES256 key: unique `kid` per instance. */
+export declare class SigningKey {
+    readonly kid: string;
+    private key;
+    private load;
+    jwks(): Promise<{
+        keys: JWK[];
+    }>;
+    sign(claims: Record<string, unknown>): Promise<string>;
+}
+/** The outbox: owed, coalesced, retried and re-minted as the daemon's. */
+export declare class RunNotices {
+    private readonly options;
+    private readonly key;
+    private readonly identity;
+    /** Whether the run's person holds an active grant: a revoked grant has no notice target (`runNoticeTarget`). */
+    private readonly grantActive;
+    /** Token claims and records read this clock; the outbox's gaps and retries stay on real timers. */
+    private readonly clock;
+    private readonly states;
+    readonly records: FakeNotice[];
+    constructor(options: RunNoticeOptions | undefined, key: SigningKey, identity: {
+        issuer: string;
+        clientId: string;
+        runtimeId: string;
+        runtimeClientId: string;
+    }, 
+    /** Whether the run's person holds an active grant: a revoked grant has no notice target (`runNoticeTarget`). */
+    grantActive: (userId: string) => boolean, 
+    /** Token claims and records read this clock; the outbox's gaps and retries stay on real timers. */
+    clock: {
+        now(): number;
+    });
+    private state;
+    /** An open stream satisfies anything owed; closing it with the log ahead of what it wrote owes a notice. */
+    streamOpened(run: FakeRun): (lastWritten: number) => void;
+    appended(run: FakeRun): void;
+    forget(run: FakeRun): void;
+    reset(): void;
+    private owe;
+    private schedule;
+    private deliver;
+    private attempt;
+    private mint;
+}

package/dist/testing/notices.js

@@ -0,0 +1,209 @@
+// Runtime→app run notices, mirroring `RunNoticeOutbox` (src/daemon/run-notices.ts) rule for rule, and the
+// cloud's ES256 signing key that mints their tokens and is served as the directory JWKS.
+import { randomBytes, randomUUID } from 'node:crypto';
+import { SignJWT, decodeJwt, exportJWK, generateKeyPair } from 'jose';
+/** The daemon's per-attempt bound (`RUN_NOTICE_ATTEMPT_TIMEOUT_MS`, src/daemon/run-notices.ts). */
+const ATTEMPT_TIMEOUT_MS = 10_000;
+let keySerial = 0;
+/** The cloud's one ES256 key: unique `kid` per instance. */
+export class SigningKey {
+    kid = `fake-${++keySerial}-${randomBytes(4).toString('hex')}`;
+    key;
+    load() {
+        this.key ??= (async () => {
+            const { privateKey, publicKey } = await generateKeyPair('ES256', { extractable: true });
+            const jwk = await exportJWK(publicKey);
+            return { privateKey: privateKey, jwk: { ...jwk, kid: this.kid, alg: 'ES256', use: 'sig' } };
+        })();
+        return this.key;
+    }
+    async jwks() { return { keys: [(await this.load()).jwk] }; }
+    async sign(claims) {
+        const { privateKey } = await this.load();
+        return new SignJWT(claims).setProtectedHeader({ alg: 'ES256', typ: 'at+jwt', kid: this.kid }).sign(privateKey);
+    }
+}
+class Fault extends Error {
+    retryable;
+    constructor(retryable, message) {
+        super(message);
+        this.retryable = retryable;
+    }
+}
+/** The outbox: owed, coalesced, retried and re-minted as the daemon's. */
+export class RunNotices {
+    options;
+    key;
+    identity;
+    grantActive;
+    clock;
+    states = new Map();
+    records = [];
+    constructor(options, key, identity, 
+    /** Whether the run's person holds an active grant: a revoked grant has no notice target (`runNoticeTarget`). */
+    grantActive, 
+    /** Token claims and records read this clock; the outbox's gaps and retries stay on real timers. */
+    clock) {
+        this.options = options;
+        this.key = key;
+        this.identity = identity;
+        this.grantActive = grantActive;
+        this.clock = clock;
+    }
+    state(run) {
+        let state = this.states.get(run);
+        if (!state) {
+            state = { streams: 0, owed: false, inFlight: false, nextAllowedAt: 0 };
+            this.states.set(run, state);
+        }
+        return state;
+    }
+    /** An open stream satisfies anything owed; closing it with the log ahead of what it wrote owes a notice. */
+    streamOpened(run) {
+        const state = this.state(run);
+        state.streams++;
+        state.owed = false;
+        state.nextAllowedAt = 0;
+        if (state.timer) {
+            clearTimeout(state.timer);
+            state.timer = undefined;
+        }
+        let released = false;
+        return (lastWritten) => {
+            if (released)
+                return;
+            released = true;
+            state.streams--;
+            if (state.streams === 0 && run.latestSequence > lastWritten && !run.deleted)
+                this.owe(run);
+            else if (state.streams === 0 && !state.owed && !state.inFlight)
+                this.forget(run);
+        };
+    }
+    appended(run) {
+        if (!this.options)
+            return;
+        if (this.state(run).streams > 0)
+            return;
+        this.owe(run);
+    }
+    forget(run) {
+        const state = this.states.get(run);
+        if (state?.timer)
+            clearTimeout(state.timer);
+        this.states.delete(run);
+    }
+    reset() {
+        for (const state of this.states.values())
+            if (state.timer)
+                clearTimeout(state.timer);
+        this.states.clear();
+        this.records.length = 0;
+    }
+    owe(run) {
+        if (!this.options || !this.grantActive(run.userId))
+            return;
+        const state = this.state(run);
+        state.owed = true;
+        this.schedule(run, state);
+    }
+    schedule(run, state) {
+        if (!state.owed || state.inFlight || state.timer || state.streams > 0)
+            return;
+        state.timer = setTimeout(() => { state.timer = undefined; void this.deliver(run, state); }, Math.max(0, state.nextAllowedAt - Date.now()));
+        state.timer.unref?.();
+    }
+    async deliver(run, state) {
+        const options = this.options;
+        if (!state.owed || state.inFlight || state.streams > 0 || run.deleted)
+            return;
+        if (!this.grantActive(run.userId)) {
+            state.owed = false;
+            this.forget(run);
+            return;
+        }
+        state.owed = false;
+        state.inFlight = true;
+        const latest = run.latestSequence;
+        const waits = options.retryWaitsMs ?? [0, 0];
+        let delivered = false;
+        let satisfied = false;
+        for (let attempt = 1;; attempt++) {
+            try {
+                await this.attempt(run, attempt, latest);
+                delivered = true;
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof Fault) || !error.retryable)
+                    break;
+                const wait = waits[attempt - 1];
+                if (wait === undefined)
+                    break;
+                await new Promise((resolve) => setTimeout(resolve, wait));
+                if (state.streams > 0) {
+                    satisfied = true;
+                    break;
+                }
+            }
+        }
+        state.inFlight = false;
+        const now = Date.now();
+        if (!delivered && !satisfied)
+            state.nextAllowedAt = now + (options.failGapMs ?? 0);
+        else if (delivered && state.streams === 0)
+            state.nextAllowedAt = now + (options.ackGapMs ?? 0);
+        if (state.owed)
+            this.schedule(run, state);
+        else if (state.streams === 0 && this.states.get(run) === state && !state.timer && now >= state.nextAllowedAt)
+            this.states.delete(run);
+    }
+    async attempt(run, attempt, latest) {
+        const options = this.options;
+        for (let remint = false;; remint = true) {
+            const token = await this.mint(run);
+            const record = { runId: run.id, userId: run.userId, attempt, remint, latestSequence: latest, claims: decodeJwt(token), status: null, error: null, at: this.clock.now() };
+            this.records.push(record);
+            let response;
+            // Each request is bounded as the daemon's (`RUN_NOTICE_ATTEMPT_TIMEOUT_MS`): a hung handler is a retryable failure.
+            const signal = AbortSignal.timeout(ATTEMPT_TIMEOUT_MS);
+            let timer;
+            try {
+                response = await Promise.race([
+                    options.deliver(new Request(options.url, {
+                        method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+                        body: JSON.stringify({ run_id: run.id, latest_sequence: latest }), signal,
+                    })),
+                    new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`no answer within ${ATTEMPT_TIMEOUT_MS}ms`)), ATTEMPT_TIMEOUT_MS); timer.unref?.(); }),
+                ]);
+            }
+            catch (error) {
+                record.error = error instanceof Error ? error.message : String(error);
+                throw new Fault(true, record.error);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            record.status = response.status;
+            if (response.status >= 200 && response.status < 300)
+                return;
+            if (response.status === 401) {
+                if (!remint)
+                    continue;
+                throw new Fault(true, 'unauthorized after re-mint');
+            }
+            if (response.status >= 500)
+                throw new Fault(true, `status ${response.status}`);
+            throw new Fault(false, `status ${response.status}`);
+        }
+    }
+    mint(run) {
+        const now = Math.floor(this.clock.now() / 1000);
+        const app = `app:${this.identity.clientId}`;
+        return this.key.sign({
+            iss: this.identity.issuer, aud: this.options.url, sub: run.userId, grantee: app, client_id: this.identity.runtimeClientId,
+            scope: 'crtr:run_notice', initiating_app: app, act: { sub: this.identity.runtimeId, act: { sub: app } },
+            iat: now, exp: now + 300, jti: randomUUID(),
+        });
+    }
+}

package/dist/testing/run.d.ts

@@ -0,0 +1,174 @@
+import type { DeclinedResultDTO, RunActivityDTO, RunEvent, RunEventFields, RunEventType, RunOutcomeDTO, RunQuestionSlotDTO, RunStatusDTO, TurnErrorDTO } from '@north-light/api';
+/** What a FakeRun needs from the cloud that owns it. */
+export interface RunHost {
+    readonly grantee: string;
+    readonly streamIdleMs: number;
+    /** The cloud's clock, in ms: every timestamp the run writes reads it. */
+    now(): number;
+    /** Whether the run owner's grant is active now. */
+    grantActive(userId: string): boolean;
+    /** An event was appended (run-notice outbox). */
+    appended(run: FakeRun): void;
+    /** A stream opened; the returned function is called with the last sequence it wrote when it closes. */
+    streamOpened(run: FakeRun): (lastWritten: number) => void;
+    /** The run was deleted: drop its idempotency keys. */
+    deleted(run: FakeRun): void;
+}
+/** One message the run accepted (`run.start` `message` or `run.message`). */
+export interface FakeRunMessage {
+    message_id: string;
+    text: string;
+    start_turn: boolean;
+    sequence_number: number;
+    idempotencyKey: string | null;
+    delivered: boolean;
+}
+/** The `run.start` body as the fake received it. */
+export interface FakeRunParams {
+    prompt: string;
+    message?: string;
+    scopes?: string[];
+    isolated?: boolean;
+    /** An isolated run's working folder, when the app named one. */
+    cwd?: string;
+    output_schema?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    profile?: string;
+}
+/** How `settle` ends a run. */
+export type FakeRunEnding = {
+    result: unknown;
+} | {
+    declined: DeclinedResultDTO;
+} | {
+    failure: 'canceled' | 'deadline_exceeded';
+} | {
+    runtimeError: string;
+};
+/** A question `ask` opens; defaults to one text slot `answer`. */
+export interface FakeQuestion {
+    title: string;
+    subtitle?: string;
+    steps?: number;
+    slots?: RunQuestionSlotDTO[];
+    provider?: string;
+    tool?: string;
+}
+interface OpenQuestion {
+    question_id: string;
+    title: string;
+    subtitle?: string;
+    steps: number;
+    slots: RunQuestionSlotDTO[];
+    status: 'open' | 'answered' | 'canceled';
+    answer?: Record<string, unknown>;
+}
+/** `activity.tool.summary` as the daemon writes it: a command's first line, else a path; null otherwise. */
+export declare function toolCallSummary(args: unknown): string | null;
+/** One run the app started, and the test's handle on it. */
+export declare class FakeRun {
+    readonly id: string;
+    readonly userId: string;
+    private readonly host;
+    private readonly metadata;
+    readonly scopes: string[] | null;
+    /** The run's start-time body, as received. */
+    readonly params: FakeRunParams;
+    /** The `Idempotency-Key` of the start, or null. */
+    readonly idempotencyKey: string | null;
+    /** Every message the run accepted; the start's `message` is the first, with `start_turn: false`. */
+    readonly messages: FakeRunMessage[];
+    name: string;
+    readonly createdAt: string;
+    lastActivityAt: string;
+    /** Kept events (`expireEvents` drops the oldest). */
+    private log;
+    private sequence;
+    private outcomeValue;
+    private resultValue;
+    private hasResult;
+    private settledAt;
+    private turnError;
+    private rested;
+    private answered;
+    private override;
+    private messageSerial;
+    private outcomeRevision;
+    private finalReport;
+    readonly questions: Map<string, OpenQuestion>;
+    private readonly streams;
+    private readonly waiters;
+    deleted: boolean;
+    constructor(id: string, userId: string, params: FakeRunParams, idempotencyKey: string | null, host: RunHost, metadata: Record<string, unknown>, scopes: string[] | null);
+    /** Every kept event, in order. */
+    get events(): readonly RunEvent[];
+    get latestSequence(): number;
+    get earliestSequence(): number | null;
+    get outcome(): RunOutcomeDTO | undefined;
+    get result(): unknown;
+    get lastTurnError(): TurnErrorDTO | undefined;
+    /** Messages not yet delivered to a turn (the start's `message` included). */
+    get pending(): FakeRunMessage[];
+    get pendingQuestionIds(): string[];
+    /** The run status, derived as the daemon's `runStatus` derives it. */
+    get status(): RunStatusDTO;
+    /** What the root is doing, derived from the event log as `runActivity` derives it with no open streaming block. */
+    get activity(): RunActivityDTO | null;
+    /** `run.get`'s body. */
+    toObject(): Record<string, unknown>;
+    /** Append any run event; `nodeId` defaults to the root (another id is a child node's event). */
+    emit<T extends RunEventType>(type: T, fields: RunEventFields<T>, { nodeId }?: {
+        nodeId?: string;
+    }): RunEvent;
+    /** One turn answering `text`: turn started, `chunks` deltas, text done, turn completed. Delivers `messageIds`
+     *  (default: every pending message). */
+    reply(text: string, { chunks, messageIds }?: {
+        chunks?: number;
+        messageIds?: string[];
+    }): void;
+    /** The same turn ending in error: `last_turn_error` set, status idle. */
+    failTurn({ code, message, messageIds }: {
+        code: TurnErrorDTO['code'];
+        message: string;
+        messageIds?: string[];
+    }): void;
+    /** Fake-only: status `running` with `activity` overridden until the next appended event. */
+    setActivity(activity: RunActivityDTO, { at }?: {
+        at?: string | Date | number;
+    }): void;
+    /** The run goes idle without a new turn (it stopped without submitting); undelivered start-turn mail is consumed. */
+    idle(): void;
+    /** Record the run's ending and emit `node.settled`. */
+    settle(ending: FakeRunEnding): void;
+    /** Open a question: a `waiting_on_user` event; the run waits on the user between turns. Returns its id. */
+    ask(question: FakeQuestion): string;
+    /** Delete the run as the runtime does: reads answer 404, streams close, its idempotency keys are dropped. */
+    delete(): void;
+    /** Idle-close every open stream now. */
+    closeIdle(): void;
+    /** Drop kept events up to `upTo` (event expiry; makes `stream_gap` reachable). */
+    expireEvents(upTo: number): void;
+    /** Record an accepted message; returns it. */
+    accept(text: string, startTurn: boolean, idempotencyKey: string | null): FakeRunMessage;
+    /** Clear a non-canceled ending so a start-turn message runs it again (`commitReopenResident`). */
+    reopen(): void;
+    /** The app answered a question. */
+    answer(questionId: string, responses: Record<string, unknown>): void;
+    questionObject(questionId: string): Record<string, unknown> | undefined;
+    /** Resolves when the run rests (`idle`, `waiting_on_user`, `settled`), is deleted, `seconds` pass, or `signal` aborts. */
+    waitResting(seconds: number, signal?: AbortSignal | null): Promise<void>;
+    /** The SSE body after `after`, as `streamRunEvents` writes it. Validation happens before the caller calls this. */
+    openStream(after: number, signal?: AbortSignal | null): ReadableStream<Uint8Array>;
+    /** The grant went inactive: every open stream gets the 401 `grant_revoked` error frame. */
+    revokeStreams(): void;
+    get openStreams(): number;
+    /** Notify held reads that state changed. */
+    wake(): void;
+    private assertLive;
+    private turnOpen;
+    private everStartedTurn;
+    private turnsStarted;
+    private turn;
+    private append;
+}
+export {};