@superpanel-sdk/runtime 0.5.0 → 0.7.0

package/dist/builder/typecheck.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { generateAll, generateCompany, listSequenceIds } from './codegen/generate.js';
+import { generateAll } from './codegen/generate.js';
 import { RUNTIME_PACKAGE, isCompanyApiFile } from './company-imports.js';
 /**
  * The TypeScript this runtime pins: the check never depends on whether, or which, `typescript` the repo
@@ -71,7 +71,7 @@ async function tsconfigImportIssue(tsc, root) {
     return null;
 }
 /**
- * The repository's type check, as `pnpm typecheck` runs it locally: `type:gen`, then `tsc --noEmit`
+ * The repository's type check, as `npm run typecheck` runs it locally: `type:gen`, then `tsc --noEmit`
  * with the repo's own `tsconfig.json`. With no sequence it writes only the root `__gen` (the local
  * `type:gen` needs a sequence). The compile runs it itself, so a type error blocks a release in every
  * environment; the platform never calls the repo's `typecheck` script.
@@ -83,10 +83,7 @@ export async function typecheckRepo(repoRoot, onLog) {
     }
     // type:gen first. A repository with no sequence still releases its company code (22 §11): only the
     // root __gen is written then, which its root code's `ctx.api.db` is typed by.
-    if (listSequenceIds(repoRoot).length > 0)
-        await generateAll(repoRoot);
-    else
-        await generateCompany(repoRoot);
+    await generateAll(repoRoot);
     const { version, tsc } = pinnedTypescript();
     onLog?.(`Type checking with TypeScript ${version}...`);
     // tsc names files relative to its working directory, which is the real path (macOS's /var is a link):

package/dist/builder/types.d.ts

@@ -2,6 +2,7 @@ import type { CaseOrchestratorManifest } from '../core/case-orchestrator/types.j
 import type { ScheduleManifest } from '../core/functions/schedules.js';
 import type { FunctionRegistry } from '../core/functions/types.js';
 import type { OfficeHours } from '../core/office-hours/index.js';
+import type { ActionParameters } from '../core/page/define.js';
 import type { CompiledExperiments, CompiledVariables } from '../core/sequence/index.js';
 import type { CompiledSlotSchema } from '../core/slot/types.js';
 export type RuntimePackageSource = 'local-file' | 'npm';
@@ -61,12 +62,15 @@ export type SequenceBuild = {
     contextPage: {
         code: string;
         channels: string[];
+        /** The functions' parameters, from their `args` types (38 §2.4): what a function button has filled. */
+        functions?: Record<string, {
+            parameters: ActionParameters;
+        }>;
+        /** The page's actions' parameters, from their `args` types (38 §2.9): what a page action button has filled. */
+        actions?: Record<string, {
+            parameters: ActionParameters;
+        }>;
     };
-    /**
-     * The sequence's recurring jobs (`sequences/<id>/schedules.ts`, 25 §6.4), by name; each one's code is
-     * `functions['schedule.<name>']`. Absent: none.
-     */
-    schedules?: ScheduleManifest;
 };
 /**
  * The company build (22-sequence-as-business-unit §4.1): one release compiles the whole repository
@@ -105,4 +109,36 @@ export type CompanyPart = {
 };
 /** Where company-level functions live, in place of a sequence's directory name. */
 export declare const COMPANY_SCOPE = "@company";
+/** The page script's name among its sequence's functions (its `functionKey`): reserved, no function takes it. */
+export declare const CONTEXT_PAGE_FUNCTION = "contextPage";
+/**
+ * The name the platform knows a piece of compiled company code by, wherever it runs: its scope (the
+ * sequence's directory name, or {@link COMPANY_SCOPE}), then its name. A Worker function is invoked
+ * by it (the company Worker's registry is keyed by it); the page script, run in the page sandbox, is
+ * `<sequence>/contextPage`. Directory names never contain `/` or `@`, so names of different scopes
+ * cannot meet.
+ */
+export declare function functionKey(scope: string, name: string): string;
+/**
+ * The file a piece of code's stack frames name, by its {@link functionKey}: its `//# sourceURL` in the
+ * company Worker, the file name the page sandbox runs it as. Its source map is found by that key.
+ */
+export declare function functionScriptFile(key: string): string;
+/**
+ * The source map of one compiled function or page script (v3, no `sourcesContent`): where a position
+ * in its `code` was in the company's own files, by path from the repository root. Every other source
+ * (the compile's entry, the runtime, dependencies) is `null`, the platform's code. Kept out of the
+ * build, which is read on every run: a failure's stack is turned into the company's with it.
+ */
+export type FunctionSourceMap = {
+    version: 3;
+    sources: Array<string | null>;
+    names: string[];
+    mappings: string;
+};
+/**
+ * Source maps of compiled code by its {@link functionKey}: a sequence's functions, events and page
+ * script (`<sequence>/contextPage`), the company's functions (`@company/<name>`).
+ */
+export type SourceMaps = Record<string, FunctionSourceMap>;
 //# sourceMappingURL=types.d.ts.map

package/dist/builder/types.js

@@ -1,3 +1,22 @@
 /** Where company-level functions live, in place of a sequence's directory name. */
 export const COMPANY_SCOPE = '@company';
+/** The page script's name among its sequence's functions (its `functionKey`): reserved, no function takes it. */
+export const CONTEXT_PAGE_FUNCTION = 'contextPage';
+/**
+ * The name the platform knows a piece of compiled company code by, wherever it runs: its scope (the
+ * sequence's directory name, or {@link COMPANY_SCOPE}), then its name. A Worker function is invoked
+ * by it (the company Worker's registry is keyed by it); the page script, run in the page sandbox, is
+ * `<sequence>/contextPage`. Directory names never contain `/` or `@`, so names of different scopes
+ * cannot meet.
+ */
+export function functionKey(scope, name) {
+    return `${scope}/${name}`;
+}
+/**
+ * The file a piece of code's stack frames name, by its {@link functionKey}: its `//# sourceURL` in the
+ * company Worker, the file name the page sandbox runs it as. Its source map is found by that key.
+ */
+export function functionScriptFile(key) {
+    return `fn/${key}.js`;
+}
 //# sourceMappingURL=types.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/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