@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/cli/auth/http.js

@@ -0,0 +1,27 @@
+import { toHttpUrl } from './backend-url.js';
+export function apiUrl(backendUrl, path) {
+    const url = toHttpUrl(backendUrl);
+    url.pathname = `/api/${path.replace(/^\//, '')}`;
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+export async function requestJson(url, init) {
+    const response = await fetch(url, { ...init, signal: AbortSignal.timeout(15_000) });
+    const payload = (await response.json().catch(() => ({})));
+    return { response, payload };
+}
+export async function postJson(url, body) {
+    return requestJson(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+}
+export async function getJson(url, token) {
+    return requestJson(url, {
+        method: 'GET',
+        headers: { Authorization: `Bearer ${token}` },
+    });
+}
+//# sourceMappingURL=http.js.map

package/dist/cli/auth/index.d.ts

@@ -0,0 +1,10 @@
+export declare function runLogin(repoRoot: string, options: {
+    url?: string;
+}): Promise<void>;
+export declare function runLogout(repoRoot: string, options: {
+    url?: string;
+}): Promise<void>;
+export declare function runWhoami(repoRoot: string, options: {
+    url?: string;
+}): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/auth/index.js

@@ -0,0 +1,27 @@
+import { authorizeServe, cacheServeAuthorization, readServeAuthorizationStatus, removeCachedServeAuthorization, resolveBackendUrl, } from './auth.js';
+export async function runLogin(repoRoot, options) {
+    const backendUrl = resolveBackendUrl(repoRoot, options.url);
+    const authorization = await authorizeServe(backendUrl);
+    await cacheServeAuthorization(backendUrl, authorization);
+    console.log(`Logged in as ${authorization.user.email}`);
+}
+export async function runLogout(repoRoot, options) {
+    const backendUrl = resolveBackendUrl(repoRoot, options.url);
+    const removed = await removeCachedServeAuthorization(backendUrl);
+    console.log(removed ? `Logged out of ${backendUrl}` : `Not logged in to ${backendUrl}`);
+}
+export async function runWhoami(repoRoot, options) {
+    const backendUrl = resolveBackendUrl(repoRoot, options.url);
+    const status = await readServeAuthorizationStatus(backendUrl);
+    if (!status.loggedIn) {
+        console.log(`Not logged in to ${backendUrl}`);
+        return;
+    }
+    console.log(`Backend:  ${backendUrl}`);
+    console.log(`User:     ${status.authorization.user.email}`);
+    console.log(`Company:  ${status.authorization.companyId}`);
+    console.log(status.expired
+        ? `Session:  expired at ${new Date(status.expiresAt).toISOString()} (run "login" again)`
+        : `Session:  valid until ${new Date(status.expiresAt).toISOString()}`);
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/auth/progress.d.ts

@@ -0,0 +1,12 @@
+export type ProgressIndicator = {
+    start(message: string): void;
+    stop(message: string): void;
+    error(message: string): void;
+};
+/**
+ * A spinner on an interactive terminal; a single echoed start message otherwise. `stop`/`error`
+ * are spinner-only cosmetic detail — dropped silently when there's no spinner, since the CLI's
+ * top-level handler already prints failures for non-interactive runs.
+ */
+export declare function progressIndicator(): ProgressIndicator;
+//# sourceMappingURL=progress.d.ts.map

package/dist/cli/auth/progress.js

@@ -0,0 +1,15 @@
+import { spinner } from '@clack/prompts';
+/**
+ * A spinner on an interactive terminal; a single echoed start message otherwise. `stop`/`error`
+ * are spinner-only cosmetic detail — dropped silently when there's no spinner, since the CLI's
+ * top-level handler already prints failures for non-interactive runs.
+ */
+export function progressIndicator() {
+    const s = process.stdout.isTTY === true ? spinner() : null;
+    return {
+        start: (message) => (s ? s.start(message) : console.log(message)),
+        stop: (message) => s?.stop(message),
+        error: (message) => s?.error(message),
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/cli/auth/serve-login.d.ts

@@ -0,0 +1,8 @@
+import { type ServeAuthorization } from './auth.js';
+/** A fresh browser login, cached for the next run (a cache write failure only warns). */
+export declare function loginServe(backendUrl: string, options?: {
+    openBrowser?: boolean;
+}): Promise<ServeAuthorization>;
+/** Drops a token the backend rejected from the cache, so the next run logs in again. */
+export declare function forgetServeAuthorization(backendUrl: string, authorization: ServeAuthorization): Promise<void>;
+//# sourceMappingURL=serve-login.d.ts.map

package/dist/cli/auth/serve-login.js

@@ -0,0 +1,24 @@
+import { getLogger } from '../../logger.js';
+import { authorizeServe, cacheServeAuthorization, clearCachedServeAuthorization, } from './auth.js';
+const logger = getLogger(['runtime', 'auth']);
+/** A fresh browser login, cached for the next run (a cache write failure only warns). */
+export async function loginServe(backendUrl, options = {}) {
+    const authorization = await authorizeServe(backendUrl, options);
+    try {
+        await cacheServeAuthorization(backendUrl, authorization);
+    }
+    catch (error) {
+        logger.warn('could not cache serve authorization', error);
+    }
+    return authorization;
+}
+/** Drops a token the backend rejected from the cache, so the next run logs in again. */
+export async function forgetServeAuthorization(backendUrl, authorization) {
+    try {
+        await clearCachedServeAuthorization(backendUrl, authorization.token);
+    }
+    catch (error) {
+        logger.warn('could not clear cached serve authorization', error);
+    }
+}
+//# sourceMappingURL=serve-login.js.map

package/dist/cli/calls/index.d.ts

@@ -0,0 +1,177 @@
+/**
+ * An integration test's calls in text (68 §4): a test customer calls one of the environment's simulated
+ * lines and talks in text, through the backend's `cli-auth/exec/call/*`. What the AI says comes back as
+ * text, what it does on the line (a keypad, a transfer, a voicemail) as an event the test answers. And the
+ * customer's side (68 §5.2): their texts and emails in, what the environment sent them, a call ringing them.
+ */
+import type { TurnSummary } from '../turns/index.js';
+export type TextCallEvent = {
+    kind: 'keypad';
+    key: string;
+    say: string;
+    digits: string[];
+} | {
+    kind: 'transfer';
+    to: string;
+    mode: string;
+    say: string;
+    language?: string;
+} | {
+    kind: 'voicemail';
+    text: string;
+} | {
+    kind: 'language';
+    language: string;
+} | {
+    kind: 'listen';
+    ms: number;
+} | {
+    kind: 'far_end';
+    farEnd: string;
+    decision: string;
+};
+export type TextCallEnd = {
+    /** `ai`: the AI ended it; `hangup`: the test did; `transfer`: a person took it; `no-answer` / `busy`: a call to them not taken. */
+    by: 'ai' | 'hangup' | 'transfer' | 'no-answer' | 'busy';
+    /** The Orchestrator, run once the call's `call.ended` was handled: its status and the follow-ups it booked. */
+    orchestrator: {
+        status: string;
+        failureCode?: string;
+        scheduled: unknown[];
+        cancelled: unknown[];
+    } | null;
+};
+/** What a step of the call came to. */
+export type TextCallStep = {
+    callId: string;
+    /** What the AI said, in order. */
+    said: string[];
+    /** What it did on the line that a voice service would have done. */
+    events: TextCallEvent[];
+    /** The turns this step ran: what was heard, said, pressed and written. */
+    turns: TurnSummary[];
+    /** How the call ended, when it ended in this step. */
+    ended: TextCallEnd | null;
+};
+/** An open call in text. */
+export type TextCall = {
+    callId: string;
+    /** The opening: what the AI said first. */
+    opening: TextCallStep;
+    /** The customer says `text`; the AI's turn on it. */
+    say(text: string): Promise<TextCallStep>;
+    /** The customer presses `value` for the keypad asked for (`key`: the last `keypad` event's when left out). */
+    press(value: string, key?: string): Promise<TextCallStep>;
+    /** The transfer asked for: `answered` (the person took it; the call ends for the AI) or `failed` (the AI goes on). */
+    transfer(outcome: 'answered' | 'failed'): Promise<TextCallStep>;
+    /** The customer hangs up: the wrap-up, `call.ended` and the Orchestrator run. */
+    hangup(): Promise<TextCallStep>;
+    /** Whether the call has ended. */
+    readonly ended: boolean;
+};
+type Post = <T>(what: string, body: unknown) => Promise<T>;
+/** A test customer's number: North America's fictional range, the half simulated lines never take. */
+export declare function testCustomerPhone(): string;
+/** A test customer's email address: on the reserved `.test` domain, where simulated mailboxes write. */
+export declare function testCustomerEmail(): string;
+/** Opens a call from `from` to the simulated line `to`, and the object to go on with it. */
+export declare function openTextCall(post: Post, input: {
+    from: string;
+    to: string;
+}): Promise<TextCall>;
+/** What a simulated line or mailbox sent a test customer, or a call ringing them. */
+export type InboxItem = {
+    kind: 'sms';
+    id: string;
+    from: string;
+    line: string | null;
+    body: string;
+    at: string;
+} | {
+    kind: 'email';
+    id: string;
+    from: string;
+    mailbox: string | null;
+    subject: string;
+    body: string;
+    threadId: string | null;
+    at: string;
+} | {
+    kind: 'call';
+    id: string;
+    from: string;
+    line: string | null;
+    at: string;
+    status: 'ringing';
+};
+/** What a text or an email from a test customer came to: the run's turns, and what came back to them. */
+export type SentResult = {
+    /** `debounce: 'real'`: stored and queued; the worker runs it once the texts stop coming, the reply comes to the inbox. */
+    queued?: boolean;
+    turns: TurnSummary[];
+    replies: InboxItem[];
+    orchestrator: TextCallEnd['orchestrator'];
+};
+/**
+ * A test customer (68 §5.2): a number and an address no carrier or provider has. They text and email the
+ * environment's simulated lines and mailboxes, find what it sent them in their inbox, and answer or let
+ * ring the calls it makes to them, as a person would, whenever the environment gets to it.
+ */
+export type TestCustomer = {
+    phone: string;
+    email: string;
+    /**
+     * They text the simulated line `to` (its name or number, `Main line` when left out); the run it started,
+     * now. `debounce: 'real'`: as a carrier's text, handled by the worker once their texts stop coming for
+     * 15 s (several in a row are one batch, one run): it returns at once (`queued`), the reply comes to
+     * `next('sms')`.
+     */
+    text(body: string, options?: {
+        to?: string;
+        orchestrator?: 'now' | 'debounced';
+        debounce?: 'skip' | 'real';
+    }): Promise<SentResult>;
+    /** They email the simulated mailbox `to` (its name or address, `Support` when left out); `threadId` (an inbox email's) replies in its thread. */
+    sendEmail(input: {
+        body: string;
+        subject?: string;
+        to?: string;
+        threadId?: string | null;
+        orchestrator?: 'now' | 'debounced';
+    }): Promise<SentResult>;
+    /** What was sent to them since `since` (ISO; since this object was made when left out), oldest first, ringing calls included. */
+    inbox(since?: string): Promise<InboxItem[]>;
+    /**
+     * Waits for the next thing of `kind` sent to them that this object has not handed out yet (a scheduled text
+     * coming due, a call ringing): checked every 2 s, until `timeoutMs` (60 s when left out), then it fails.
+     */
+    next<K extends InboxItem['kind']>(kind: K, options?: {
+        timeoutMs?: number;
+        match?: (item: Extract<InboxItem, {
+            kind: K;
+        }>) => boolean;
+    }): Promise<Extract<InboxItem, {
+        kind: K;
+    }>>;
+    /** They pick up a call ringing them: `as` a person (the AI opens), or their voicemail, a screener, a menu. */
+    answer(call: {
+        id: string;
+    } | string, options?: {
+        as?: 'human' | 'voicemail' | 'screening' | 'ivr';
+        said?: string;
+        orchestrator?: 'now' | 'debounced';
+    }): Promise<TextCall>;
+    /** They let it ring (`no-answer`) or are busy: the attempt ends as a carrier would end it, the Orchestrator runs. */
+    decline(call: {
+        id: string;
+    } | string, options?: {
+        status?: 'no-answer' | 'busy';
+        orchestrator?: 'now' | 'debounced';
+    }): Promise<TextCallStep>;
+};
+export declare function testCustomer(post: Post, input?: {
+    phone?: string;
+    email?: string;
+}): TestCustomer;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/calls/index.js

@@ -0,0 +1,96 @@
+/** A test customer's number: North America's fictional range, the half simulated lines never take. */
+export function testCustomerPhone() {
+    // Area codes in use: a number of an unassigned one (889) is not taken as a phone number at all.
+    const codes = ['206', '212', '213', '303', '305', '312', '404', '415', '503', '512', '602', '617', '702', '713', '808', '917'];
+    const npa = codes[Math.floor(Math.random() * codes.length)];
+    const xx = 50 + Math.floor(Math.random() * 50);
+    return `+1${npa}55501${xx}`;
+}
+/** A test customer's email address: on the reserved `.test` domain, where simulated mailboxes write. */
+export function testCustomerEmail() {
+    return `c-${Math.random().toString(36).slice(2, 10)}@customers.sim.test`;
+}
+/** Opens a call from `from` to the simulated line `to`, and the object to go on with it. */
+export async function openTextCall(post, input) {
+    const opening = await post('call/open', input);
+    if (!opening.callId) {
+        throw new Error(`call: the line did not take it (no route, or resolve declined); the caller heard: ${opening.said.join(' ') || 'nothing'}`);
+    }
+    return textCall(post, opening);
+}
+function textCall(post, opening) {
+    let ended = opening.ended !== null;
+    let keypad = [...opening.events].reverse().find((e) => e.kind === 'keypad')?.key;
+    const step = async (what, body) => {
+        if (ended)
+            throw new Error(`call ${opening.callId}: it has ended`);
+        const result = await post(`call/${what}`, { callId: opening.callId, ...body });
+        ended = result.ended !== null;
+        keypad = [...result.events].reverse().find((e) => e.kind === 'keypad')?.key ?? keypad;
+        return result;
+    };
+    return {
+        callId: opening.callId,
+        opening,
+        say: (text) => step('say', { text }),
+        press: (value, key) => {
+            const asked = key ?? keypad;
+            if (!asked)
+                throw new Error(`call ${opening.callId}: no keypad was asked for; name its key`);
+            return step('press', { key: asked, value });
+        },
+        transfer: (outcome) => step('transfer', { outcome }),
+        hangup: () => step('hangup', {}),
+        get ended() {
+            return ended;
+        },
+    };
+}
+export function testCustomer(post, input = {}) {
+    const phone = input.phone ?? testCustomerPhone();
+    const email = input.email ?? testCustomerEmail();
+    const madeAt = new Date(Date.now() - 1_000).toISOString();
+    const handedOut = new Set();
+    const inbox = async (since) => (await post('sim/inbox', { phone, email, since: since ?? madeAt })).items;
+    const idOf = (call) => (typeof call === 'string' ? call : call.id);
+    const customer = {
+        phone,
+        email,
+        text: (body, options = {}) => post('sim/sms', {
+            from: phone,
+            to: options.to ?? 'Main line',
+            body,
+            ...(options.orchestrator ? { orchestrator: options.orchestrator } : {}),
+            ...(options.debounce ? { debounce: options.debounce } : {}),
+        }),
+        sendEmail: (mail) => post('sim/email', {
+            from: email,
+            to: mail.to ?? 'Support',
+            body: mail.body,
+            ...(mail.subject !== undefined ? { subject: mail.subject } : {}),
+            ...(mail.threadId ? { threadId: mail.threadId } : {}),
+            ...(mail.orchestrator ? { orchestrator: mail.orchestrator } : {}),
+        }),
+        inbox,
+        async next(kind, options = {}) {
+            const deadline = Date.now() + (options.timeoutMs ?? 60_000);
+            for (;;) {
+                const found = (await inbox()).find((item) => item.kind === kind && !handedOut.has(item.id) && (!options.match || options.match(item)));
+                if (found) {
+                    handedOut.add(found.id);
+                    return found;
+                }
+                if (Date.now() >= deadline)
+                    throw new Error(`${phone} / ${email}: no ${kind} came within ${options.timeoutMs ?? 60_000} ms`);
+                await new Promise((resolve) => setTimeout(resolve, 2_000));
+            }
+        },
+        async answer(call, options = {}) {
+            const opening = await post('call/answer', { callId: idOf(call), ...options });
+            return textCall(post, opening);
+        },
+        decline: (call, options = {}) => post('call/decline', { callId: idOf(call), ...options }),
+    };
+    return customer;
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/compile/index.js

@@ -1,6 +1,9 @@
 import path from 'node:path';
 import { compileAll } from '../../builder/compile/compile-sequence.js';
+import { typecheckRepo } from '../../builder/typecheck.js';
 export async function runCompile(repoRoot, options = {}) {
+    // The same type check as a release, before any build is written: a type error blocks both.
+    await typecheckRepo(repoRoot, (text) => console.log(text));
     const results = await compileAll(repoRoot, {
         sequenceIds: options.sequenceId ? [options.sequenceId] : undefined,
     });

package/dist/cli/config.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const COMPANY_REPO_CONFIG_PATH = ".superpanel/config.json";
+declare const companyRepoConfigSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    backendUrl: z.ZodString;
+}, z.core.$strict>;
+export type CompanyRepoConfig = z.infer<typeof companyRepoConfigSchema>;
+export declare function readCompanyRepoConfig(repoRoot: string): CompanyRepoConfig | undefined;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/cli/config.js

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { toHttpUrl } from './auth/backend-url.js';
+export const COMPANY_REPO_CONFIG_PATH = '.superpanel/config.json';
+const companyRepoConfigSchema = z
+    .object({
+    version: z.literal(1),
+    backendUrl: z
+        .string()
+        .trim()
+        .min(1)
+        .refine((value) => {
+        try {
+            toHttpUrl(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, 'must be a valid HTTP or HTTPS URL'),
+})
+    .strict();
+export function readCompanyRepoConfig(repoRoot) {
+    const file = path.join(repoRoot, COMPANY_REPO_CONFIG_PATH);
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+        if (code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${COMPANY_REPO_CONFIG_PATH} is not valid JSON`);
+    }
+    const result = companyRepoConfigSchema.safeParse(value);
+    if (!result.success) {
+        const details = result.error.issues
+            .map((issue) => `${issue.path.join('.') || 'config'}: ${issue.message}`)
+            .join('; ');
+        throw new Error(`${COMPANY_REPO_CONFIG_PATH} has an invalid Superpanel configuration (${details})`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/debug/index.d.ts

@@ -0,0 +1,31 @@
+import type { ApiCall } from '../exec/trace.js';
+import type { LogLine } from '../logs/index.js';
+import { type TurnSummary } from '../turns/index.js';
+/** The case ids in a request or an answer: every `instanceId`, and a started instance's `id`. */
+export declare function casesIn(value: unknown, into: Set<string>, depth?: number): void;
+export type DebugSources = {
+    /** A case's timeline and turns (`exec/debug`). */
+    caseDebug(instanceId: string): Promise<{
+        timeline: Array<{
+            at: string;
+            kind: string;
+            text: string;
+            [key: string]: unknown;
+        }>;
+        turns: TurnSummary[];
+    }>;
+    /** One turn, with what it began with (`readTurn`). */
+    readTurn(turnId: string): Promise<unknown>;
+    /** The repository's log lines on a case since a time. */
+    logs(instanceId: string, since: string): Promise<LogLine[]>;
+};
+export type DebugTest = {
+    name: string;
+    error: unknown;
+    startedAt: string;
+    cases: string[];
+    calls: ApiCall[];
+};
+/** Writes the package; its directory. Never throws: a package that could not be read says so in its summary. */
+export declare function writeDebugPackage(root: string, test: DebugTest, sources: DebugSources): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/debug/index.js

@@ -0,0 +1,119 @@
+/**
+ * A test's debug package (68 §9): when an integration test fails (or every test, with `debug: 'always'`),
+ * everything that can be seen of the cases it touched is written next to the repository, under
+ * `.superpanel/tests/<run>/<test>/`, for a person or an agent to read with `grep` / `jq`:
+ *
+ *   summary.md      read this first: the failure, the cases, their turns, the commands to go on with
+ *   timeline.jsonl  the cases' timelines and turns, by time
+ *   turns/<n>.json  each turn: what was heard, said, pressed and written, and what it began with
+ *   logs.jsonl      what this repository's code logged on those cases
+ *   calls.jsonl     the `ctx.api` calls the test made
+ *
+ * The cases are the ones the test's requests named or were answered with (`instanceId`, a started
+ * instance): a test that makes its own contacts and cases (TESTING.md) finds all of its own.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { formatTurnLine } from '../turns/index.js';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The case ids in a request or an answer: every `instanceId`, and a started instance's `id`. */
+export function casesIn(value, into, depth = 0) {
+    if (!value || typeof value !== 'object' || depth > 6)
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value.slice(0, 200))
+            casesIn(item, into, depth + 1);
+        return;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if ((key === 'instanceId' || key === 'currentInstanceId') && typeof item === 'string' && UUID.test(item))
+            into.add(item);
+        else if (key === 'instance' && item && typeof item === 'object' && typeof item.id === 'string' && UUID.test(item.id))
+            into.add(item.id);
+        else
+            casesIn(item, into, depth + 1);
+    }
+}
+const slug = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80) || 'test';
+function messageOf(error) {
+    if (!error)
+        return '';
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/** Writes the package; its directory. Never throws: a package that could not be read says so in its summary. */
+export async function writeDebugPackage(root, test, sources) {
+    const dir = path.join(root, slug(test.name));
+    mkdirSync(path.join(dir, 'turns'), { recursive: true });
+    const problems = [];
+    const timeline = [];
+    const turns = [];
+    const logs = [];
+    for (const instanceId of test.cases) {
+        try {
+            const debug = await sources.caseDebug(instanceId);
+            for (const entry of debug.timeline)
+                timeline.push({ ...entry, source: 'timeline', instanceId });
+            for (const turn of debug.turns) {
+                turns.push(turn);
+                timeline.push({ at: turn.startedAt, source: 'turn', instanceId, kind: `turn:${turn.kind}`, text: formatTurnLine(turn) });
+            }
+        }
+        catch (error) {
+            problems.push(`case ${instanceId}: ${messageOf(error)}`);
+        }
+        try {
+            logs.push(...(await sources.logs(instanceId, test.startedAt)));
+        }
+        catch (error) {
+            problems.push(`logs of case ${instanceId}: ${messageOf(error)}`);
+        }
+    }
+    timeline.sort((a, b) => a.at.localeCompare(b.at));
+    for (const line of logs)
+        timeline.push({ at: line.at, source: 'log', instanceId: '', kind: `log:${line.level}`, text: line.message ?? '' });
+    timeline.sort((a, b) => a.at.localeCompare(b.at));
+    const ofTest = turns.filter((t) => t.startedAt >= test.startedAt);
+    for (const turn of ofTest.slice(-30)) {
+        try {
+            writeFileSync(path.join(dir, 'turns', `${String(turn.seq).padStart(3, '0')}-${turn.kind}-${turn.id.slice(0, 8)}.json`), `${JSON.stringify(await sources.readTurn(turn.id), null, 2)}\n`);
+        }
+        catch (error) {
+            problems.push(`turn ${turn.id}: ${messageOf(error)}`);
+        }
+    }
+    const jsonl = (rows) => rows.map((row) => JSON.stringify(row)).join('\n') + (rows.length ? '\n' : '');
+    writeFileSync(path.join(dir, 'timeline.jsonl'), jsonl(timeline));
+    writeFileSync(path.join(dir, 'logs.jsonl'), jsonl(logs));
+    writeFileSync(path.join(dir, 'calls.jsonl'), jsonl(test.calls));
+    const last = ofTest.at(-1) ?? turns.at(-1);
+    const summary = [
+        `# ${test.name}`,
+        '',
+        test.error ? `**Failed:** ${messageOf(test.error).trim()}` : '**Passed.**',
+        '',
+        `Started ${test.startedAt}. Cases: ${test.cases.length ? test.cases.map((id) => `\`${id}\``).join(', ') : 'none named by the test'}.`,
+        '',
+        '## Turns in this test',
+        '',
+        ...(ofTest.length ? ofTest.map((t) => `- ${formatTurnLine(t)}`) : ['- none']),
+        '',
+        '## Go on with',
+        '',
+        ...(last
+            ? [
+                `- the last turn, as it ran: \`npm run turns -- export ${last.id}\` (then \`renderPage(fromTurn(dir))\`)`,
+                `- again, on your code as it is now, 5 times, nothing kept: \`npm run turn -- --from ${last.id} --repeat 5\``,
+            ]
+            : []),
+        ...test.cases.map((id) => `- what the code logged on case ${id}: \`npm run logs -- --instance ${id} --since 2h\``),
+        '',
+        'Files: `timeline.jsonl` (by time: the cases\' timelines, turns, log lines), `turns/` (each turn whole), `logs.jsonl`, `calls.jsonl` (the test\'s `ctx.api` calls).',
+        ...(problems.length ? ['', '## Not read', '', ...problems.map((p) => `- ${p}`)] : []),
+        '',
+    ].join('\n');
+    writeFileSync(path.join(dir, 'summary.md'), summary);
+    return dir;
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/exec/index.d.ts

@@ -0,0 +1,39 @@
+import { traceApi, type ApiCall } from './trace.js';
+export { traceApi, type ApiCall };
+export type ExecOptions = {
+    env?: string;
+    instance?: string;
+    args?: string;
+    url?: string;
+    /** Print only the result's JSON (for a script or an agent). */
+    json?: boolean;
+};
+/** The run's outcome, as `result.json` keeps it and `--json` prints it. */
+export type ExecResult = {
+    ok: boolean;
+    file: string;
+    environment: {
+        id: string;
+        name: string;
+    };
+    instance: {
+        id: string;
+        sequence: string;
+    } | null;
+    startedAt: string;
+    durationMs: number;
+    /** `ctx.api` calls made, and how many of them failed. */
+    calls: {
+        total: number;
+        failed: number;
+    };
+    value?: unknown;
+    error?: {
+        message: string;
+        stack?: string;
+    };
+    /** Where the run's files are. */
+    dir: string;
+};
+export declare function runExec(repoRoot: string, file: string, options?: ExecOptions): Promise<ExecResult>;
+//# sourceMappingURL=index.d.ts.map