@north-light/sdk 0.0.0 → 0.3.414

package/dist/testing/index.d.ts

@@ -0,0 +1,5 @@
+export { FakeCloud } from './cloud.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,3 @@
+// `@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';

package/dist/testing/notices.d.ts

@@ -0,0 +1,70 @@
+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;
+    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);
+    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,205 @@
+// 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;
+    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) {
+        this.options = options;
+        this.key = key;
+        this.identity = identity;
+        this.grantActive = grantActive;
+    }
+    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: Date.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(Date.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,172 @@
+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;
+    /** 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 {};