@superpanel-sdk/runtime 0.5.0 → 0.7.0

package/dist/cli/serve/index.js

@@ -1,15 +1,18 @@
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { cancel, isCancel, select } from '@clack/prompts';
 import chokidar from 'chokidar';
-import { compileAll, compileCompanyMetadataFromRepo, compileCompanyPart, runtimePackageSource, runtimePackageVersion, } from '../../builder/compile/compile-sequence.js';
+import { compileAll, compileCompanyPart, runtimePackageSource, runtimePackageVersion, } from '../../builder/compile/compile-sequence.js';
 import { withCompanyImportGraph } from '../../builder/company-import-graph.js';
 import { findTsModule, requireCompanyResolveModule, requireResolveModule } from '../../builder/paths.js';
 import { listSequenceIds, loadCompanyWebhook, loadSequenceCaseOrchestrator, WEBHOOK_MODULE, loadCompanyResolver, loadSequenceResolver, loadSequenceEvents, loadSequenceFunctions, } from '../../builder/load.js';
 import { loadSchedules } from '../../builder/schedules.js';
-import { ORCHESTRATOR_CONTACTS_FUNCTION, ORCHESTRATOR_FUNCTION } from '../../core/case-orchestrator/types.js';
+import { loadOnError } from '../../builder/errors.js';
+import { ORCHESTRATOR_FUNCTION } from '../../core/case-orchestrator/types.js';
 import { WEBHOOK_RECEIVED_FUNCTION } from '../../core/functions/events.js';
 import { COMPANY_RESOLVE_FUNCTION, RESOLVE_FUNCTION } from '../../core/party/types.js';
-import { COMPANY_SCOPE } from '../../builder/types.js';
+import { COMPANY_SCOPE, } from '../../builder/types.js';
+import { realPath } from '../../builder/company-imports.js';
 import { createSourceComputeHost } from '../../compute-host/source-compute-host.js';
 import { formatRuntimeVersion } from '../../fn-context/rpc/request-id.js';
 import { encodeOverlayMessage, OVERLAY_REPLACED_CLOSE_CODE, parseOverlayMessage, } from '../../dev-overlay/protocol.js';
@@ -67,22 +70,18 @@ async function loadOne(repoRoot, sequenceId, generation) {
             throw new Error(`Failed to compile sequence ${sequenceId}`);
         }
         const sequenceDir = path.join(repoRoot, 'sequences', sequenceId);
+        // A sequence without `functions/` has none (76 §5.5), as the compile above takes it.
         const functionsPath = findTsModule(sequenceDir, 'functions');
-        if (!functionsPath) {
-            throw new Error(`No functions module for sequence ${sequenceId}`);
-        }
         const caseOrchestratorPath = findTsModule(sequenceDir, 'orchestrator');
-        const authored = await loadSequenceFunctions(functionsPath);
+        const authored = functionsPath ? await loadSequenceFunctions(functionsPath) : {};
         const functions = {
             ...authored,
-            [RESOLVE_FUNCTION]: await loadSequenceResolver(requireResolveModule(sequenceDir, sequenceId)),
-            ...(caseOrchestratorPath ? await caseOrchestratorFunctions(caseOrchestratorPath) : {}),
-            // The jobs of its schedules.ts run here too while serving (25 §6.4).
-            ...(await loadSchedules(sequenceDir, `sequences/${sequenceId}/schedules.ts`))?.functions,
+            [RESOLVE_FUNCTION]: (await loadSequenceResolver(requireResolveModule(sequenceDir, sequenceId))),
+            ...(caseOrchestratorPath ? { [ORCHESTRATOR_FUNCTION]: await loadSequenceCaseOrchestrator(caseOrchestratorPath) } : {}),
         };
         const eventsPath = findTsModule(sequenceDir, 'events');
         const events = eventsPath ? await loadSequenceEvents(eventsPath) : {};
-        return { build: compiled.build, functions, events, generation };
+        return { build: compiled.build, sourceMaps: compiled.sourceMaps, functions, events, generation };
     });
 }
 export async function loadCompany(repoRoot) {
@@ -90,23 +89,15 @@ export async function loadCompany(repoRoot) {
         const webhookPath = findTsModule(repoRoot, WEBHOOK_MODULE);
         return {
             part: await compileCompanyPart(repoRoot, { includeCode: false }),
-            companyMetadata: await compileCompanyMetadataFromRepo(repoRoot),
             functions: {
-                [COMPANY_RESOLVE_FUNCTION]: await loadCompanyResolver(requireCompanyResolveModule(repoRoot)),
-                ...(webhookPath ? { [WEBHOOK_RECEIVED_FUNCTION]: await loadCompanyWebhook(webhookPath) } : {}),
-                ...(await loadSchedules(repoRoot, 'schedules.ts'))?.functions,
+                [COMPANY_RESOLVE_FUNCTION]: (await loadCompanyResolver(requireCompanyResolveModule(repoRoot))),
+                ...(webhookPath ? { [WEBHOOK_RECEIVED_FUNCTION]: (await loadCompanyWebhook(webhookPath)) } : {}),
+                ...(await loadSchedules(repoRoot))?.functions,
+                ...(await loadOnError(repoRoot))?.functions,
             },
         };
     });
 }
-/** orchestrator.ts's two functions, as the build names them. */
-async function caseOrchestratorFunctions(path) {
-    const { orchestrator, contacts } = await loadSequenceCaseOrchestrator(path);
-    return {
-        [ORCHESTRATOR_FUNCTION]: { kind: 'orchestrator', main: orchestrator },
-        [ORCHESTRATOR_CONTACTS_FUNCTION]: { kind: 'orchestrator', main: contacts },
-    };
-}
 /** The repository's sequences, compiled; a listed sequence missing from the repository is left out. */
 async function loadSequences(repoRoot, sequenceIds, generation) {
     return withCompanyImportGraph(repoRoot, async () => {
@@ -209,7 +200,54 @@ export function pushOverlay(ws, company, sequences, generation) {
         company: company.part,
         sequences: Object.fromEntries([...sequences].map(([sequenceId, sequence]) => [sequenceId, sequence.build])),
     };
-    send(ws, { type: 'overlay', generation, build, companyMetadata: company.companyMetadata });
+    const sourceMaps = Object.assign({}, ...[...sequences.values()].map((sequence) => sequence.sourceMaps));
+    send(ws, { type: 'overlay', generation, build, sourceMaps });
+}
+/** A stack frame as V8 prints it: `at name (file:line:col)` or `at file:line:col`. */
+const STACK_FRAME = /^\s*at (?:(.*?) \()?(.+?):(\d+):(\d+)\)?$/;
+/**
+ * What the company is shown of a failed function's stack (the backend's company logs): the error's first
+ * line and the frames of the repository's own files, by their path from its root. tsx runs the original
+ * files, so their lines are already the company's. Undefined when no frame is the repository's.
+ */
+export function repositoryStack(error, repoRoot) {
+    if (!(error instanceof Error) || !error.stack)
+        return undefined;
+    const lines = error.stack.split('\n');
+    const firstFrame = lines.findIndex((line) => /^\s*at /.test(line));
+    if (firstFrame === -1)
+        return undefined;
+    const roots = [...new Set([path.resolve(repoRoot), realPath(repoRoot)])];
+    const frames = lines.slice(firstFrame).flatMap((line) => {
+        const frame = STACK_FRAME.exec(line);
+        const file = frame ? repositoryFile(frame[2], roots) : null;
+        if (!frame || !file)
+            return [];
+        return [`    at ${frame[1] ? `${frame[1]} (` : ''}${file}:${frame[3]}:${frame[4]}${frame[1] ? ')' : ''}`];
+    });
+    return frames.length > 0 ? [...lines.slice(0, firstFrame), ...frames].join('\n') : undefined;
+}
+/** A frame's file as a path from the repository root; null outside its own files (node_modules included). */
+function repositoryFile(location, roots) {
+    let file = location;
+    if (file.startsWith('file://')) {
+        try {
+            // The import graph stamps the URLs it loads (`?spgen=…`).
+            file = fileURLToPath(file.replace(/[?#].*$/, ''));
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!path.isAbsolute(file))
+        return null;
+    for (const root of roots) {
+        const relative = path.relative(root, file);
+        if (relative && !relative.startsWith('..') && !path.isAbsolute(relative) && !relative.split(path.sep).includes('node_modules')) {
+            return relative.split(path.sep).join('/');
+        }
+    }
+    return null;
 }
 function closeDetail(event) {
     return event.reason ? `${event.code} ${event.reason}` : String(event.code);
@@ -318,7 +356,12 @@ function waitAuthOk(ws) {
         ws.addEventListener('close', onClose);
     });
 }
-function attachExecuteHandler(ws, find, rpcUrl) {
+/**
+ * Runs each `execute` the backend sends, unless its deadline has passed: the backend has then reported
+ * it as failed (a paused process, a laptop that slept), and running it would repeat its effects when
+ * the call is retried. One already started is not interrupted.
+ */
+export function attachExecuteHandler(ws, find, rpcUrl, repoRoot) {
     ws.addEventListener('message', (event) => {
         void (async () => {
             let message;
@@ -331,6 +374,22 @@ function attachExecuteHandler(ws, find, rpcUrl) {
             }
             if (message.type !== 'execute')
                 return;
+            const lateMs = Date.now() - message.deadline;
+            if (lateMs > 0) {
+                send(ws, {
+                    type: 'execute.result',
+                    requestId: message.requestId,
+                    ok: false,
+                    error: `expired: the backend stopped waiting ${lateMs} ms ago, so it was not run`,
+                    notStarted: true,
+                });
+                logger.warn('execute skipped: it arrived after the backend stopped waiting', {
+                    sequenceId: message.sequenceId,
+                    name: message.name,
+                    lateMs,
+                });
+                return;
+            }
             const loaded = find(message.sequenceId);
             if (!loaded) {
                 const error = `unknown sequence ${message.sequenceId}`;
@@ -339,6 +398,7 @@ function attachExecuteHandler(ws, find, rpcUrl) {
                     requestId: message.requestId,
                     ok: false,
                     error,
+                    notStarted: true,
                 });
                 logger.error('execute failed', { sequenceId: message.sequenceId, name: message.name, error });
                 return;
@@ -350,18 +410,21 @@ function attachExecuteHandler(ws, find, rpcUrl) {
             }
             catch (error) {
                 const text = error instanceof Error ? error.message : String(error);
+                const stack = repositoryStack(error, repoRoot);
                 send(ws, {
                     type: 'execute.result',
                     requestId: message.requestId,
                     ok: false,
                     error: text,
+                    ...(stack ? { stack } : {}),
+                    ...(error instanceof Error && error.name === 'PlatformUnavailableError' ? { platform: true } : {}),
                 });
                 logger.error('execute failed', {
                     sequenceId: message.sequenceId,
                     name: message.name,
                     durationMs: Date.now() - started,
                     error: text,
-                });
+                }, ...(stack ? [`\n${stack}`] : []));
                 return;
             }
             send(ws, { type: 'execute.result', requestId: message.requestId, ok: true, result });
@@ -611,7 +674,7 @@ export async function runServe(repoRoot, options = {}) {
             const authOk = waitAuthOk(ws);
             send(ws, { type: 'auth', token: authorization.token, environment });
             await authOk;
-            attachExecuteHandler(ws, find, rpcUrl);
+            attachExecuteHandler(ws, find, rpcUrl, repoRoot);
             attachNoticeHandler(ws);
             pushOverlay(ws, company, sequences, generation);
             delayMs = 500;
@@ -647,4 +710,80 @@ export async function runServe(repoRoot, options = {}) {
         delayMs = Math.min(delayMs * 2, 5_000);
     }
 }
+/**
+ * The repository served on `environmentId` as `serve` serves it, once (no file watch, no reconnect): its
+ * code loaded through the company import graph (an import the compile refuses fails here), pushed, and
+ * every function the environment runs meanwhile run here. Resolves once the environment took it.
+ */
+export async function openOverlay(repoRoot, options) {
+    if (listSequenceIds(repoRoot).length === 0)
+        throw new Error(`No sequences found under ${path.join(repoRoot, 'sequences')}`);
+    const company = await loadCompany(repoRoot);
+    const sequences = await loadSequences(repoRoot, listSequenceIds(repoRoot), 1);
+    const runtimeSource = runtimePackageSource(repoRoot);
+    const find = (scope) => {
+        if (scope === COMPANY_SCOPE)
+            return { functions: company.functions, events: {}, runtimeVersion: runtimePackageVersion(), runtimeSource };
+        const loaded = sequences.get(scope);
+        return loaded
+            ? { functions: loaded.functions, events: loaded.events, runtimeVersion: loaded.build.engineVersion, runtimeSource: loaded.build.runtimeSource }
+            : undefined;
+    };
+    const ws = new WebSocket(overlayWebSocketUrl(options.backendUrl));
+    try {
+        await waitOpen(ws);
+        const authOk = waitAuthOk(ws);
+        send(ws, { type: 'auth', token: options.token, environment: options.environmentId });
+        await authOk;
+    }
+    catch (error) {
+        ws.close();
+        throw error;
+    }
+    attachExecuteHandler(ws, find, overlayRpcUrl(options.backendUrl), repoRoot);
+    attachNoticeHandler(ws);
+    // Served once the backend says so (`overlay.ok`): a call made before could still run the release.
+    const served = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('the environment did not take the code within 60 s')), 60_000);
+        ws.addEventListener('message', (event) => {
+            try {
+                const message = parseOverlayMessage(String(event.data));
+                if (message.type === 'overlay.ok' && message.generation === 1) {
+                    clearTimeout(timer);
+                    resolve();
+                }
+                else if (message.type === 'auth.error') {
+                    clearTimeout(timer);
+                    reject(new Error(`serve: ${message.error}`));
+                }
+            }
+            catch {
+                // not a message of ours
+            }
+        });
+        ws.addEventListener('close', () => {
+            clearTimeout(timer);
+            reject(new Error('the environment closed the connection before it took the code'));
+        });
+    });
+    pushOverlay(ws, company, sequences, 1);
+    try {
+        await served;
+    }
+    catch (error) {
+        ws.close();
+        throw error;
+    }
+    return {
+        sequences: [...sequences.keys()],
+        close: async () => {
+            if (ws.readyState === WebSocket.CLOSED)
+                return;
+            await new Promise((resolve) => {
+                ws.addEventListener('close', () => resolve(), { once: true });
+                ws.close();
+            });
+        },
+    };
+}
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,105 @@
+import type { PageChannel } from '../../core/page/define.js';
+export type TurnSummary = {
+    id: string;
+    seq: number;
+    runId: string;
+    callId: string | null;
+    instanceId: string;
+    /** customer | assistant | silence | wrap_up | run */
+    kind: string;
+    channel: string;
+    heard: string | null;
+    said: string[];
+    /** The model's thought at each step: what it heard, what it does, what comes next. */
+    thoughts: string[];
+    actions: Array<{
+        key: string;
+        name: string;
+        kind: string;
+        status: string;
+        args: unknown;
+        result: unknown;
+        error: string | null;
+    }>;
+    writes: Array<{
+        rowId: string;
+        table: string;
+        field: string;
+        value: unknown;
+        state: string | null;
+    }>;
+    outcome: string | null;
+    error: string | null;
+    startedAt: string;
+    endedAt: string | null;
+    /** Whether its snapshot is still kept (30 days). */
+    snapshot: boolean;
+};
+export type TurnRecord = TurnSummary & {
+    format: 1;
+    sequence: string;
+    steps: Array<{
+        thought: string | null;
+        say: string;
+        actions: unknown[];
+        outcomes: Array<{
+            action: string;
+            status: string;
+            detail?: string;
+        }>;
+    }>;
+    platformRules: string;
+};
+export type TurnSnapshot = {
+    pages: Array<{
+        seq: number;
+        step: number;
+        auto: boolean;
+        text: string;
+    }>;
+    data: Record<string, Array<Record<string, unknown>>>;
+    context: Record<string, unknown> | null;
+    history: unknown;
+    start: unknown;
+};
+export type TurnRead = {
+    turn: TurnRecord;
+    snapshot: TurnSnapshot | null;
+};
+export type TurnsQuery = {
+    instanceId?: string;
+    runId?: string;
+    callId?: string;
+    since?: string;
+    limit?: number;
+};
+/** POST to an exec route with the run token; the backend's error as the message. */
+export declare function postExec<T>(backendUrl: string, runToken: string, what: string, body: unknown): Promise<T>;
+/** The turn's directory: `turn.json`, `page/<n>.txt`, `data.json`, `context.json`, `history.json`, `start.json`. */
+export declare function writeTurnExport(dir: string, read: TurnRead): string;
+/** A turn's directory read back. Its snapshot is null when it was exported after the snapshot was dropped. */
+export declare function readTurnExport(dir: string): TurnRead;
+/** One line: where it is in the run, who spoke, what was said, what it did. */
+export declare function formatTurnLine(turn: TurnSummary): string;
+/** The channel of a page a turn's context names. */
+export declare function channelOf(turn: TurnRecord): PageChannel;
+type TurnsOptions = {
+    env?: string;
+    instance?: string;
+    call?: string;
+    run?: string;
+    since?: string;
+    limit?: number;
+    json?: boolean;
+    url?: string;
+};
+/** `turns`: the turns, one line each (or one JSON each with `--json`). */
+export declare function runTurns(repoRoot: string, options: TurnsOptions): Promise<void>;
+/** `turns export <turnId>`: the turn written to `.superpanel/turns/<turnId>/`; prints the directory. */
+export declare function runTurnExport(repoRoot: string, turnId: string, options: {
+    env?: string;
+    url?: string;
+    out?: string;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/turns/index.js

@@ -0,0 +1,128 @@
+/**
+ * `turns`: the turns of a case, a run or a call in a non-prod environment (68 §7.4), one line each, and
+ * `turns export <turnId>`: one turn written to `.superpanel/turns/<turnId>/` (its record and snapshot),
+ * which `fromTurn` reads back for `renderPage`. The same files an integration test's `exportTurn` writes.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { loadCachedServeAuthorization, resolveBackendUrl } from '../auth/auth.js';
+import { apiUrl, requestJson } from '../auth/http.js';
+import { requestExecRun } from '../exec/session.js';
+import { timeOf } from '../logs/index.js';
+/** POST to an exec route with the run token; the backend's error as the message. */
+export async function postExec(backendUrl, runToken, what, body) {
+    const { response, payload } = await requestJson(apiUrl(backendUrl, `cli-auth/exec/${what}`), {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${runToken}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok)
+        throw new Error(`${what}: ${payload.error ?? `the backend answered ${response.status}`}`);
+    return payload;
+}
+/** The turn's directory: `turn.json`, `page/<n>.txt`, `data.json`, `context.json`, `history.json`, `start.json`. */
+export function writeTurnExport(dir, read) {
+    mkdirSync(dir, { recursive: true });
+    const json = (name, value) => writeFileSync(path.join(dir, name), `${JSON.stringify(value, null, 2)}\n`);
+    json('turn.json', read.turn);
+    if (read.snapshot) {
+        mkdirSync(path.join(dir, 'page'), { recursive: true });
+        for (const page of read.snapshot.pages)
+            if (!page.auto)
+                writeFileSync(path.join(dir, 'page', `${page.seq}.txt`), page.text);
+        json('data.json', read.snapshot.data);
+        json('context.json', read.snapshot.context);
+        json('history.json', read.snapshot.history);
+        json('start.json', read.snapshot.start);
+    }
+    return dir;
+}
+/** A turn's directory read back. Its snapshot is null when it was exported after the snapshot was dropped. */
+export function readTurnExport(dir) {
+    const file = (name) => path.join(dir, name);
+    if (!existsSync(file('turn.json')))
+        throw new Error(`${dir}: no turn.json (export a turn with \`turns export <turnId>\`)`);
+    const turn = JSON.parse(readFileSync(file('turn.json'), 'utf8'));
+    if (turn.format !== 1)
+        throw new Error(`${dir}: turn.json format ${String(turn.format)}; this runtime reads format 1`);
+    if (!existsSync(file('data.json')))
+        return { turn, snapshot: null };
+    const json = (name) => JSON.parse(readFileSync(file(name), 'utf8'));
+    const pages = existsSync(file('page'))
+        ? readdirSync(file('page'))
+            .filter((name) => /^\d+\.txt$/.test(name))
+            .map((name) => ({ seq: Number(name.slice(0, -4)), step: 0, auto: false, text: readFileSync(path.join(file('page'), name), 'utf8') }))
+            .sort((a, b) => a.seq - b.seq)
+        : [];
+    return {
+        turn,
+        snapshot: {
+            pages,
+            data: json('data.json'),
+            context: json('context.json'),
+            history: json('history.json'),
+            start: json('start.json'),
+        },
+    };
+}
+const clip = (text, max = 80) => {
+    const one = (text ?? '').replace(/\s+/g, ' ').trim();
+    return one.length > max ? `${one.slice(0, max - 1)}…` : one;
+};
+/** One line: where it is in the run, who spoke, what was said, what it did. */
+export function formatTurnLine(turn) {
+    const parts = [`#${turn.seq} ${turn.kind}`, turn.id];
+    if (turn.heard)
+        parts.push(`heard "${clip(turn.heard)}"`);
+    if (turn.said.length)
+        parts.push(`said "${clip(turn.said.join(' '))}"`);
+    if (turn.actions.length)
+        parts.push(`did ${turn.actions.map((a) => `${a.key}:${a.status}`).join(', ')}`);
+    if (turn.writes.length)
+        parts.push(`wrote ${turn.writes.map((w) => `${w.table}.${w.field}`).join(', ')}`);
+    if (turn.outcome && turn.outcome !== 'done')
+        parts.push(turn.outcome);
+    if (turn.error)
+        parts.push(`error: ${clip(turn.error)}`);
+    return parts.join('  ');
+}
+/** The channel of a page a turn's context names. */
+export function channelOf(turn) {
+    return turn.channel === 'call' || turn.channel === 'sms' || turn.channel === 'email' ? turn.channel : 'call';
+}
+async function execToken(repoRoot, options) {
+    const backendUrl = resolveBackendUrl(repoRoot, options.url);
+    const authorization = await loadCachedServeAuthorization(backendUrl);
+    if (!authorization)
+        throw new Error('not logged in: run `superpanel-sdk-runtime login` first');
+    const run = await requestExecRun(backendUrl, authorization.token, options.env ?? 'sandbox', undefined);
+    return { backendUrl, runToken: run.runToken };
+}
+/** `turns`: the turns, one line each (or one JSON each with `--json`). */
+export async function runTurns(repoRoot, options) {
+    if (!options.instance && !options.call && !options.run)
+        throw new Error('turns: name the case (--instance), the call (--call) or the run (--run)');
+    const { backendUrl, runToken } = await execToken(repoRoot, options);
+    const since = timeOf(options.since);
+    const { turns } = await postExec(backendUrl, runToken, 'turns', {
+        ...(options.instance ? { instanceId: options.instance } : {}),
+        ...(options.call ? { callId: options.call } : {}),
+        ...(options.run ? { runId: options.run } : {}),
+        ...(since ? { since } : {}),
+        ...(options.limit ? { limit: options.limit } : {}),
+    });
+    if (!turns.length)
+        console.error('no turns');
+    for (const turn of turns)
+        console.log(options.json ? JSON.stringify(turn) : formatTurnLine(turn));
+}
+/** `turns export <turnId>`: the turn written to `.superpanel/turns/<turnId>/`; prints the directory. */
+export async function runTurnExport(repoRoot, turnId, options) {
+    const { backendUrl, runToken } = await execToken(repoRoot, options);
+    const read = await postExec(backendUrl, runToken, 'turns/read', { turnId });
+    const dir = writeTurnExport(path.resolve(repoRoot, options.out ?? path.join('.superpanel', 'turns', turnId)), read);
+    if (!read.snapshot)
+        console.error(`turn ${turnId}: its snapshot is no longer kept (30 days); only turn.json was written`);
+    console.log(dir);
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/turns/run.d.ts

@@ -0,0 +1,13 @@
+export type TurnCliOptions = {
+    env?: string;
+    url?: string;
+    from?: string;
+    instance?: string;
+    channel?: 'sms' | 'email' | 'call';
+    say?: string;
+    caller?: string;
+    repeat?: number;
+    json?: boolean;
+};
+export declare function runTurnCli(repoRoot: string, options: TurnCliOptions): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/turns/run.js

@@ -0,0 +1,57 @@
+/**
+ * `superpanel-sdk-runtime turn` (68 §8.1): one turn as a shadow, from the command line — on a case now, or
+ * from a turn that ran (its id or its exported directory), with this repository's code serving the
+ * environment while it runs. Each run's words, buttons, writes and functions, one block per run.
+ */
+import { connect } from '../../testing.js';
+function describe(run, n) {
+    const lines = [`── run ${n}`];
+    for (const thought of run.turns.flatMap((t) => t.thoughts ?? []))
+        lines.push(`  (thought) ${thought}`);
+    for (const said of run.said)
+        lines.push(`AI: ${said}`);
+    if (run.outcome && run.outcome.kind !== 'reply')
+        lines.push(`ended: ${run.outcome.kind}${'reason' in run.outcome ? ` (${run.outcome.reason})` : ''}`);
+    for (const action of run.actions)
+        lines.push(`  ${action.name}: ${action.status}${action.error ? ` (${action.error})` : ''}`);
+    for (const write of run.writes)
+        lines.push(`  wrote ${write.table}.${write.field} = ${JSON.stringify(write.value)}${write.state && write.state !== 'filled' ? ` (${write.state})` : ''}`);
+    for (const event of run.events)
+        lines.push(`  on the line: ${JSON.stringify(event)}`);
+    for (const call of run.functions)
+        lines.push(`  function ${call.name}: ${call.how}${call.error ? ` (${call.error})` : ''}`);
+    for (const warning of run.warnings)
+        lines.push(`  ! ${warning}`);
+    return lines.join('\n');
+}
+export async function runTurnCli(repoRoot, options) {
+    if (!options.from && !options.instance)
+        throw new Error('turn: --from <turnId|dir>, or --instance <case id> with --say');
+    const sandbox = await connect({ env: options.env ?? 'sandbox', repoRoot, ...(options.url ? { url: options.url } : {}) });
+    let result;
+    try {
+        result = await sandbox.turn({
+            ...(options.from ? { from: options.from } : {}),
+            ...(options.instance ? { instanceId: options.instance } : {}),
+            ...(options.channel ? { channel: options.channel } : {}),
+            ...(options.say ? { say: options.say } : {}),
+            ...(options.caller ? { caller: options.caller } : {}),
+            ...(options.repeat ? { repeat: options.repeat } : {}),
+        });
+    }
+    finally {
+        await sandbox.close();
+    }
+    if (options.json) {
+        for (const run of result.runs)
+            console.log(JSON.stringify(run));
+    }
+    else {
+        if (result.from)
+            console.log(`from turn ${result.from.turnId} (${result.from.kind})${result.from.heard ? `: "${result.from.heard}"` : ''}`);
+        result.runs.forEach((run, i) => console.log(describe(run, i + 1)));
+        console.log('(a shadow: nothing was kept, sent or booked)');
+    }
+    process.exit(0);
+}
+//# sourceMappingURL=run.js.map