@itookit/dsht 0.3.7 → 0.5.1

package/dist/controller/loop.js

@@ -0,0 +1,378 @@
+/** Longest evidence line and finding kept from a verdict, so untrusted model output stays bounded. */
+const MAX_EVIDENCE_CHARS = 600;
+const MAX_FINDING_CHARS = 300;
+const MAX_FINDINGS = 8;
+/** Longest reason a verifier may give for stopping early. */
+const MAX_REASON_CHARS = 300;
+/** Consecutive attempts on one step that may fail to improve the score before the run stops.
+ *
+ * One plateau can be verifier jitter, so it is tolerated; two in a row mean the retry is not
+ * converging. Set to 1 to stop on the first non-improvement (which includes a strict decrease).
+ */
+const STALL_STREAK = 2;
+/** Apply a protocol's defaults and reject a range that cannot run.
+ * @param protocol - Protocol being started.
+ * @param options - Flags exactly as parsed, absent when the operator omitted them.
+ * @returns The resolved limits, or undefined when `to < from`.
+ */
+export function resolveLoop(protocol, options) {
+    const from = options.from ?? 1;
+    const to = options.to ?? protocol.steps;
+    const score = options.score ?? protocol.defaultScore ?? 8;
+    const tries = options.tries ?? protocol.defaultTries ?? 10;
+    if (to < from)
+        return undefined;
+    return { from, to, score, tries };
+}
+/** Whether a run's rounds cover the whole record rather than a selected range.
+ *
+ * Only this case may report more than "the rounds that ran passed": the last round is then the
+ * record's consolidation round, and the verifier is handed every earlier round to re-check.
+ * @param from - First step of the run.
+ * @param to - Last step of the run.
+ * @param steps - Steps the protocol defines.
+ * @returns True when the run starts at the first round and ends at the last one.
+ */
+export function coversWholeProtocol(from, to, steps) {
+    return from === 1 && to === steps;
+}
+/** How to describe the rounds a finished run covered.
+ *
+ * `passed` only ever claims the rounds that ran, so the snapshot carries this phrase and every place
+ * that reports a pass says it too: a pass over the whole record and a pass over a selected range
+ * must not read the same.
+ * @param progress - Run limits and the protocol's total round count.
+ * @returns One phrase, e.g. `rounds 1–10/10` or `rounds 1–3/10 · selected range`.
+ */
+function loopScope(progress) {
+    const { from, to, total } = progress;
+    const label = from === to ? `round ${from}/${total}` : `rounds ${from}–${to}/${total}`;
+    return coversWholeProtocol(from, to, total) ? label : `${label} · selected range`;
+}
+/** Read the result out of the last block of one reply.
+ *
+ * The block must be in the assistant's text, not reasoning, and this takes the last one so a reply
+ * that quotes its verifier still reports its own verdict. A missing, malformed or foreign block is
+ * undefined; a valid block with no usable field is an empty result, which counts as a failed attempt.
+ * @param text - One turn's assistant text.
+ * @param protocol - Protocol whose marker and kind identify the block.
+ * @returns The reported score and verdict, or undefined when the reply carries no valid block.
+ */
+export function parseLoopResult(text, protocol) {
+    let body;
+    const segments = text.split('```');
+    // Fenced blocks are the odd-indexed segments: prose, block, prose, block, …
+    for (let index = 1; index < segments.length; index += 2) {
+        const segment = segments[index];
+        const newline = segment.indexOf('\n');
+        if ((newline === -1 ? segment : segment.slice(0, newline)).trim() !== protocol.marker)
+            continue;
+        body = newline === -1 ? '' : segment.slice(newline + 1);
+    }
+    if (body === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(body.trim());
+        if (parsed.kind !== protocol.kind)
+            return undefined;
+        return readResultFields(parsed);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Validate the score and verdict of one decoded result object.
+ *
+ * Shared with the forked verifier's verdict file, so a score means the same thing however it
+ * travelled: an out-of-range or unknown field is absent rather than a value the loop would trust.
+ * @param parsed - Decoded object expected to carry `score` and `status`.
+ * @returns The usable fields; an empty result when the object carried none, and `undefined` when it
+ *   claimed an early stop that breaks the rules — such a claim is not a verdict at all, so the
+ *   caller reports verification as unusable instead of guessing what was meant.
+ */
+export function readResultFields(parsed) {
+    const fields = parsed;
+    const score = typeof fields.score === 'number' ? fields.score : Number(fields.score);
+    const status = fields.status === 'done' || fields.status === 'retry' || fields.status === 'blocked' || fields.status === 'abstained'
+        ? fields.status : undefined;
+    const rawFindings = fields.top_findings;
+    const findings = Array.isArray(rawFindings)
+        ? rawFindings.filter((item) => typeof item === 'string' && item.trim() !== '')
+            .slice(0, MAX_FINDINGS).map(item => item.slice(0, MAX_FINDING_CHARS))
+        : [];
+    const text = (value, limit) => typeof value === 'string' && value.trim() !== '' ? value.slice(0, limit) : undefined;
+    const evidence = text(fields.evidence, MAX_EVIDENCE_CHARS);
+    const reason = text(fields.reason, MAX_REASON_CHARS);
+    const needs = text(fields.needs, MAX_REASON_CHARS);
+    // An advisory line that never changes control: "nothing to change here" is an explanation, not a
+    // shortcut past the rounds that have not run yet.
+    const explanation = text(fields.explanation, MAX_EVIDENCE_CHARS);
+    const hasScore = Number.isFinite(score) && score >= 0 && score <= 10;
+    // `blocked` is a fact about the task, so it is the one field that can override the score; the
+    // model's own `status` is kept only as an explanation, never as the run's state.
+    const blocked = fields.blocked === true || status === 'blocked';
+    const abstained = status === 'abstained';
+    const base = {
+        ...(hasScore ? { score } : {}),
+        ...(status === undefined ? {} : { status }),
+        ...(explanation === undefined ? {} : { explanation }),
+        ...(findings.length === 0 ? {} : { findings }),
+        ...(evidence === undefined ? {} : { evidence }),
+    };
+    // An early stop is a claim about the task, so it is validated as a whole and never partially
+    // honored: exactly one of "proved impossible" and "cannot judge", a reason a reader can act on,
+    // no score for `abstained` to hide behind, and an `exit_reason` label that agrees with the flags.
+    const claims = blocked || abstained || fields.exit_reason !== undefined;
+    if (!claims)
+        return base;
+    if (reason === undefined || blocked === abstained || hasScore)
+        return undefined;
+    const exitReason = abstained ? 'needs-human' : 'cannot-fix';
+    if (fields.exit_reason !== undefined && fields.exit_reason !== exitReason)
+        return undefined;
+    return { ...base, ...(blocked ? { blocked: true } : {}), ...(abstained ? { abstained: true } : {}),
+        exitReason, reason, ...(abstained && needs !== undefined ? { needs } : {}) };
+}
+/** Assistant text of the turn that just finished: from the last user/context row to the end.
+ * @param messages - Projected conversation messages.
+ * @returns The assistant text, empty when the turn produced none.
+ */
+export function latestAssistantText(messages) {
+    const parts = [];
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message.role === 'You' || message.role === 'Context')
+            break;
+        if (message.role === 'Assistant')
+            parts.unshift(message.text);
+    }
+    return parts.join('\n');
+}
+/** One run of the loop: which step and attempt is in flight, and what happens next.
+ *
+ * No I/O: the controller sends the prompt this returns and feeds back the parsed score, which keeps
+ * the state machine trivially testable and identical for every protocol.
+ */
+export class ScoredLoop {
+    runId;
+    sessionId;
+    protocol;
+    limits;
+    step;
+    attempt = 1;
+    best = 0;
+    noProgress = 0;
+    phase = 'running';
+    awaiting = false;
+    /** What the live run is waiting on; only the controller's own sends and verdicts set it. */
+    activity;
+    /** Why the run stopped; set once, together with a terminal phase. */
+    terminalReason;
+    noteText;
+    interaction;
+    exit;
+    /** When this run began, so a reader can clock it even while no host turn is running. */
+    startedAt = Date.now();
+    constructor(runId, sessionId, protocol, limits) {
+        this.runId = runId;
+        this.sessionId = sessionId;
+        this.protocol = protocol;
+        this.limits = limits;
+        this.step = limits.from;
+    }
+    /** Snapshot the UI renders; the loop keeps the authoritative numbers. */
+    get progress() {
+        const stepLabel = this.protocol.stepLabel?.(this.step);
+        return { runId: this.runId, title: this.protocol.title, startedAt: this.startedAt, ...this.limits, total: this.protocol.steps, scope: loopScope({ ...this.limits, total: this.protocol.steps }),
+            step: this.step, attempt: this.attempt, best: this.best, phase: this.phase, active: this.active,
+            // Activity describes a run that is working: a paused run waits for a person, not for the host.
+            ...(this.phase !== 'running' || this.activity === undefined ? {} : { activity: this.activity }),
+            ...(this.terminalReason === undefined ? {} : { terminalReason: this.terminalReason }),
+            ...(stepLabel === undefined ? {} : { stepLabel }),
+            ...(this.noteText === undefined ? {} : { note: this.noteText }),
+            ...(this.interaction === undefined ? {} : { interaction: this.interaction }),
+            ...(this.exit === undefined ? {} : { exit: this.exit }) };
+    }
+    /** Attach one line about the attempt just decided, shown until the next verdict replaces it.
+     * @param text - Note to show, or an empty string to clear it.
+     */
+    note(text) { this.noteText = text === '' ? undefined : text; }
+    /** Whether the run still owns its session: it may send, settle — or be answered.
+     *
+     * A paused run counts: it is not finished, so a new run must not silently replace it (§8.3.1). What
+     * it is *not* doing is working; `activity` is absent while it waits.
+     */
+    get active() {
+        return this.phase === 'running' || (this.phase === 'needs-human' && this.terminalReason === undefined);
+    }
+    /** Whether this run has sent any prompt yet, so `intro` knows the opening one is still owed. */
+    briefed = false;
+    /** Whether a prompt was sent and its reply is still outstanding. */
+    get settled() { return this.awaiting; }
+    /** The opening prompt; the caller sends it and then calls `sent()`. */
+    start() { return this.protocol.brief(this.limits, this.step, this.attempt); }
+    /** The opening prompt, when this run has not sent one yet; undefined once it has.
+     *
+     * A record that verifies first never sends its brief at the start — it checks the artifact instead —
+     * so the first work message after a failed check has to be the brief. A follow-up would open with
+     * "read the results and opinions above" and refer to a previous version, and neither exists on the
+     * first work turn; the round's own checklist only reaches the agent through this prompt.
+     */
+    intro() {
+        return this.briefed ? undefined : this.protocol.brief(this.limits, this.step, this.attempt);
+    }
+    /** The prompt that asks for work on the step in flight: the owed brief, else the follow-up. */
+    workPrompt() {
+        return this.intro() ?? this.protocol.followUp(this.limits, this.step, this.attempt);
+    }
+    /** Record that the outstanding prompt reached the host. */
+    sent() { this.awaiting = true; this.activity = 'turn'; this.briefed = true; }
+    /** Record that this attempt is judged by a forked verifier instead of the session's own turn. */
+    verifying() { this.awaiting = true; this.activity = 'verify'; }
+    /** Record that the turn ended and its result is being read, which is neither work nor a verdict. */
+    settling() { this.activity = 'settle'; }
+    /** Consume one finished attempt.
+     * @param result - Parsed result, or undefined when the reply carried no usable block.
+     * @returns What the loop does next.
+     */
+    settle(result) {
+        this.awaiting = false;
+        this.activity = 'settle';
+        // A verifier that cannot judge asks for a person. The run pauses rather than ending: the operator
+        // can answer it (`/loop answer`) or end it (`/loop abort`), and no attempt is consumed either way.
+        if (result?.abstained === true) {
+            this.pause({ kind: 'verdict', text: result.reason ?? 'the verifier needs a person',
+                ...(result.needs === undefined ? {} : { needs: result.needs }) });
+            return { kind: 'needs-human' };
+        }
+        // A verifier that proved the task impossible ends the run instead of burning the budget.
+        // Either spelling ends the run: `blocked` is the fact, `status` the legacy way of saying it.
+        if (result?.blocked === true || result?.status === 'blocked') {
+            this.phase = 'blocked';
+            this.terminalReason = 'blocked';
+            if (result.reason !== undefined)
+                this.exit = { reason: result.reason };
+            return { kind: 'blocked' };
+        }
+        const score = result?.score;
+        const previousBest = this.best;
+        if (score !== undefined) {
+            if (score > previousBest)
+                this.noProgress = 0;
+            else if (this.attempt > 1)
+                this.noProgress += 1;
+            this.best = Math.max(this.best, score);
+        }
+        if (score !== undefined && score >= this.limits.score) {
+            if (this.step >= this.limits.to) {
+                this.phase = 'passed';
+                this.terminalReason = 'pass';
+                return { kind: 'passed' };
+            }
+            this.step += 1;
+            this.attempt = 1;
+            this.best = 0;
+            this.noProgress = 0;
+            return { kind: 'continue', prompt: this.workPrompt() };
+        }
+        // Retries that keep not improving are not converging: spending the rest of the step's budget on
+        // them only reaches the same conclusion later, so the run stops and says so.
+        if (this.noProgress >= STALL_STREAK) {
+            this.phase = 'stalled';
+            this.terminalReason = 'stalled';
+            return { kind: 'stalled' };
+        }
+        // A missing or low score is a failed attempt and costs one from the step's budget.
+        this.attempt += 1;
+        if (this.attempt > this.limits.tries) {
+            this.phase = 'exhausted';
+            this.terminalReason = 'exhausted';
+            return { kind: 'exhausted' };
+        }
+        return { kind: 'continue', prompt: this.workPrompt() };
+    }
+    /** Stop the run; a cancelled run never sends again.
+     * @param reason - Who ended it, so a cancellation is not confused with a verdict.
+     */
+    cancel(reason = 'user-cancelled') {
+        this.phase = 'cancelled';
+        this.awaiting = false;
+        this.activity = undefined;
+        this.interaction = undefined;
+        this.terminalReason = reason;
+    }
+    /** End the run because independent verification was impossible.
+     *
+     * Deliberately not a verdict: no attempt is consumed, so the run stops on an infrastructure
+     * failure instead of pretending the reviewer produced nothing.
+     * @param reason - Which verification failure ended it.
+     */
+    unavailable(reason = 'verifier-unavailable') {
+        this.phase = 'unavailable';
+        this.awaiting = false;
+        this.activity = undefined;
+        this.interaction = undefined;
+        this.terminalReason = reason;
+    }
+    /** End the run because the whole-run deadline expired.
+     *
+     * A budget stop, not a verdict: it bounds the sum of all steps, attempts and verifier retries, so
+     * no attempt is consumed and `best` is untouched.
+     */
+    deadline() {
+        this.phase = 'deadline';
+        this.awaiting = false;
+        this.activity = undefined;
+        this.interaction = undefined;
+        this.terminalReason = 'deadline';
+    }
+    /** Pause the run because a judgment asked for a person.
+     *
+     * Deliberately not terminal: no `terminalReason` is written, so the run still owns its session and
+     * the progress line can offer `/loop answer` or `/loop abort` instead of a summary.
+     * @param request - What is being asked, and what the answer has to supply.
+     */
+    pause(request) {
+        this.phase = 'needs-human';
+        this.awaiting = false;
+        this.activity = undefined;
+        this.interaction = request;
+    }
+    /** Resume a paused run after the operator supplied what the judgment was missing.
+     *
+     * No attempt is consumed: the answer only adds a condition, and the current artifact is judged again
+     * under a new verification identity. The attempt counts as outstanding, so that verdict may decide it.
+     */
+    resume(activity = 'verify') {
+        this.phase = 'running';
+        this.awaiting = true;
+        this.activity = activity;
+        this.interaction = undefined;
+        this.noteText = undefined;
+    }
+    /** The prompt that asks again with the operator's addition.
+     *
+     * Used when no forked verifier judges this run: the answer becomes the next attempt's instruction
+     * instead of a condition for a judgment, and asking again costs no attempt by itself.
+     * @param answer - What the operator supplied.
+     * @returns The prompt to send.
+     */
+    answerPrompt(answer) {
+        return `${this.protocol.followUp(this.limits, this.step, this.attempt)}\n\n## 操作者的补充判断\n${answer}`;
+    }
+    /** End the run because the request cannot be answered from here.
+     *
+     * Used for the cases the operator cannot unblock through this client — a verifier child whose own
+     * session asked a question, or a prompt the host refused to accept — as opposed to `pause`, where
+     * `/loop answer` supplies what the judgment was missing. No attempt is consumed in either case.
+     * @param request - The approval or question the host is waiting for, or a verdict's request.
+     * @param reason - Which kind of human request this is.
+     */
+    human(request, reason = 'verifier-needs-human') {
+        this.phase = 'needs-human';
+        this.awaiting = false;
+        this.activity = undefined;
+        this.terminalReason = reason;
+        this.interaction = request;
+    }
+}

package/dist/controller/prompts.d.ts

@@ -0,0 +1,54 @@
+import type { SavedPrompt } from '../contracts.ts';
+/** Largest single saved prompt; a shortcut is meant to be reusable, not a document store. */
+export declare const MAX_PROMPT_CHARS: number;
+/** Most saved prompts one client keeps. */
+export declare const MAX_SAVED_PROMPTS = 500;
+/** Read and persist shortcut prompts; an absent path keeps them in memory for this run.
+ *
+ * Mutations are queued: a save, edit or delete computes and writes inside the queue, so two rapid
+ * commands can never interleave their writes and leave the file disagreeing with the list.
+ */
+export declare class PromptStore {
+    readonly path?: string | undefined;
+    private items;
+    private loaded;
+    /** Tail of the mutation queue; the next operation starts only after the previous one settled. */
+    private queue;
+    /** Last read or write failure, shown by the saved-prompt picker. */
+    error: string | undefined;
+    constructor(path?: string | undefined);
+    /** Entries in the order they were saved, oldest first. */
+    get list(): readonly SavedPrompt[];
+    /** Read the file once; a missing file is simply an empty list.
+     *
+     * A malformed document leaves the list empty and is reported through `error` rather than thrown,
+     * because a broken shortcuts file must not stop the client from starting.
+     * @returns Whether the result differs from the empty default, so a caller knows to republish.
+     */
+    load(): Promise<boolean>;
+    /** Add one prompt; a text already saved is returned instead of duplicated.
+     * @param value - Prompt text exactly as the user typed it.
+     * @returns The saved entry.
+     */
+    save(value: string): Promise<SavedPrompt>;
+    /** Replace one saved prompt's text.
+     * @param id - Entry identity.
+     * @param value - Replacement text.
+     * @returns False when the entry no longer exists.
+     */
+    update(id: string, value: string): Promise<boolean>;
+    /** Drop one saved prompt.
+     * @param id - Entry identity.
+     * @returns False when it was already gone.
+     */
+    remove(id: string): Promise<boolean>;
+    /** Queue one operation behind everything already queued, whether or not the last one failed.
+     * @param task - Operation to run when it reaches the head of the queue.
+     * @returns The operation's own result or failure.
+     */
+    private enqueue;
+    /** Apply a new list, restoring the previous one when the write fails, so memory follows the file. */
+    private commit;
+    /** Rewrite the file atomically, creating its directory on first use. */
+    private persist;
+}

package/dist/controller/prompts.js

@@ -0,0 +1,162 @@
+/** User-saved shortcut prompts, persisted in one private JSON file.
+ *
+ * The list belongs to the operator rather than to a session or a host, so it survives session
+ * switches, reconnects and machine restarts. Without a configured path the list still works for the
+ * current run, which is what tests and `--help` runs use.
+ */
+import { randomUUID } from 'node:crypto';
+import { dirname } from 'node:path';
+import { ensureDirectory, readText, writePrivateFile } from "../storage/index.js";
+import { errorText } from "../transport/wire.js";
+/** Largest single saved prompt; a shortcut is meant to be reusable, not a document store. */
+export const MAX_PROMPT_CHARS = 8 * 1024;
+/** Most saved prompts one client keeps. */
+export const MAX_SAVED_PROMPTS = 500;
+/** On-disk shape this build writes. */
+const FILE_VERSION = 1;
+/** Read and persist shortcut prompts; an absent path keeps them in memory for this run.
+ *
+ * Mutations are queued: a save, edit or delete computes and writes inside the queue, so two rapid
+ * commands can never interleave their writes and leave the file disagreeing with the list.
+ */
+export class PromptStore {
+    path;
+    items = [];
+    loaded = false;
+    /** Tail of the mutation queue; the next operation starts only after the previous one settled. */
+    queue = Promise.resolve();
+    /** Last read or write failure, shown by the saved-prompt picker. */
+    error;
+    constructor(path) {
+        this.path = path;
+    }
+    /** Entries in the order they were saved, oldest first. */
+    get list() { return this.items; }
+    /** Read the file once; a missing file is simply an empty list.
+     *
+     * A malformed document leaves the list empty and is reported through `error` rather than thrown,
+     * because a broken shortcuts file must not stop the client from starting.
+     * @returns Whether the result differs from the empty default, so a caller knows to republish.
+     */
+    async load() {
+        return this.enqueue(async () => {
+            if (this.path === undefined || this.loaded)
+                return false;
+            this.loaded = true;
+            try {
+                const raw = await readText(this.path);
+                if (raw === undefined)
+                    return false;
+                this.items = promptsFrom(JSON.parse(raw));
+                this.error = undefined;
+                return this.items.length > 0;
+            }
+            catch (error) {
+                this.error = `Saved prompts could not be read: ${errorText(error)}`;
+                return true;
+            }
+        });
+    }
+    /** Add one prompt; a text already saved is returned instead of duplicated.
+     * @param value - Prompt text exactly as the user typed it.
+     * @returns The saved entry.
+     */
+    async save(value) {
+        return this.enqueue(async () => {
+            const text = checked(value);
+            const existing = this.items.find(item => item.text === text);
+            if (existing)
+                return existing;
+            if (this.items.length >= MAX_SAVED_PROMPTS)
+                throw new Error(`Saved prompts are limited to ${MAX_SAVED_PROMPTS} entries`);
+            const prompt = { id: randomUUID(), text };
+            await this.commit([...this.items, prompt]);
+            return prompt;
+        });
+    }
+    /** Replace one saved prompt's text.
+     * @param id - Entry identity.
+     * @param value - Replacement text.
+     * @returns False when the entry no longer exists.
+     */
+    async update(id, value) {
+        return this.enqueue(async () => {
+            const text = checked(value);
+            if (!this.items.some(item => item.id === id))
+                return false;
+            await this.commit(this.items.map(item => item.id === id ? { id, text } : item));
+            return true;
+        });
+    }
+    /** Drop one saved prompt.
+     * @param id - Entry identity.
+     * @returns False when it was already gone.
+     */
+    async remove(id) {
+        return this.enqueue(async () => {
+            const next = this.items.filter(item => item.id !== id);
+            if (next.length === this.items.length)
+                return false;
+            await this.commit(next);
+            return true;
+        });
+    }
+    /** Queue one operation behind everything already queued, whether or not the last one failed.
+     * @param task - Operation to run when it reaches the head of the queue.
+     * @returns The operation's own result or failure.
+     */
+    enqueue(task) {
+        const run = this.queue.then(task, task);
+        this.queue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** Apply a new list, restoring the previous one when the write fails, so memory follows the file. */
+    async commit(items) {
+        const previous = this.items;
+        this.items = items;
+        try {
+            await this.persist();
+            this.error = undefined;
+        }
+        catch (error) {
+            this.items = previous;
+            throw error;
+        }
+    }
+    /** Rewrite the file atomically, creating its directory on first use. */
+    async persist() {
+        if (this.path === undefined)
+            return;
+        await ensureDirectory(dirname(this.path));
+        await writePrivateFile(this.path, `${JSON.stringify({ version: FILE_VERSION, prompts: this.items }, null, 2)}\n`);
+    }
+}
+/** Trim and bound one submitted prompt.
+ * @param value - Raw text after the command.
+ * @returns The text to store.
+ */
+function checked(value) {
+    const text = value.trim();
+    if (!text)
+        throw new Error('Type a prompt after /prompt');
+    if (text.length > MAX_PROMPT_CHARS)
+        throw new Error(`A saved prompt is limited to ${MAX_PROMPT_CHARS} characters`);
+    return text;
+}
+/** Validate the stored document, skipping entries this build cannot use.
+ * @param raw - Parsed JSON document.
+ * @returns The saved prompts, in file order.
+ */
+function promptsFrom(raw) {
+    const document = raw;
+    if (!document || typeof document !== 'object' || !Array.isArray(document.prompts))
+        throw new Error('unsupported prompts file');
+    const out = [];
+    for (const entry of document.prompts) {
+        const item = entry;
+        if (!item || typeof item !== 'object' || typeof item.id !== 'string' || typeof item.text !== 'string' || !item.text.trim())
+            continue;
+        out.push({ id: item.id, text: item.text });
+    }
+    return out;
+}

package/dist/controller/trace-log.d.ts

@@ -0,0 +1,45 @@
+import { type ObjectValue } from '../transport/wire.ts';
+/** The index the newest `keep` lines start at, moved forward past any split lifecycle span.
+ *
+ * A span opened before the cut and closed after it would be kept as a close without its begin, so the
+ * cut moves to just after that close and the check repeats: the newly dropped region may itself open a
+ * span that closes later. A span whose close never appears cannot be split, so it does not move the
+ * cut — that is the in-flight command the file exists to show.
+ * @param lines - Every line this process appended, oldest first.
+ * @param keep - How many of the newest lines the caller wants to keep.
+ * @returns Index of the first line to keep; always at most `lines.length - keep`.
+ */
+export declare function compactCut(lines: readonly string[], keep?: number): number;
+/** Serialized append-only trace; the file holds at most `KEEP_EVENTS` lines, fewer when a lifecycle span would be split.
+ *
+ * Writes are chained rather than awaited by the caller, because transitions are published from
+ * synchronous state updates. A failed write is remembered and reported on the next event instead of
+ * throwing into the controller.
+ */
+export declare class TraceLog {
+    readonly path: string | undefined;
+    private queue;
+    private lines;
+    private directoryEnsured;
+    /** Last write failure, when the log stopped growing. */
+    error: string | undefined;
+    constructor(path: string | undefined);
+    /** Append one event; an absent path makes this a no-op. */
+    record(event: ObjectValue): void;
+    /** Wait for queued writes, so a shutdown does not lose the last events. */
+    settle(): Promise<void>;
+    /** Write one line, then bound the file when the cap is reached. */
+    private append;
+    /** Rewrite the file with the header and the newest kept lines, bounding its size.
+     *
+     * Older runs are not read back: `lines` is what this process appended, which bounds both the file
+     * and the read that rewrites it. The cut is pairing-aware, so a kept `begin` is never orphaned from
+     * its close and a kept close never loses its begin.
+     */
+    private compact;
+}
+/** Read a trace back, so a test or a diagnostic tool can assert what was recorded.
+ * @param path - Trace file to read.
+ * @returns Every non-empty line, oldest first.
+ */
+export declare function readTrace(path: string): Promise<string[]>;