@turri-dev/cli 0.1.6-next.336dd6e → 0.1.7-next.9aec40e

package/dist/regenerate/debugger.d.ts

@@ -0,0 +1,31 @@
+import { type ScriptRun } from "./test-scripts.ts";
+export interface DebugInput {
+    /** The codebase: what it reads. */
+    buildDir: string;
+    /** The failing run, as the harness saw it. */
+    failure: string;
+    /** How many times in a row it has failed this way. */
+    times: number;
+    /** What the change is meant to do: the spec as the coding agent has it. */
+    task: string;
+    /** The testing script that decides pass or fail, with its path: how the tests are run, and where. */
+    script?: string;
+    /** How the failing run ended against its time limit: how long it took, and whether the limit stopped it. */
+    run?: Pick<ScriptRun, "exitCode" | "timedOut" | "timeoutMs" | "elapsedMs">;
+    label: string;
+    model?: string;
+    onDelta?: (delta: string) => void;
+}
+export interface Diagnosis {
+    rootCause: string;
+    fix: string;
+    /**
+     * The run the time limit stopped hangs on nothing: it was making progress up to the limit and needs more time than a
+     * test run may take - which no agent can give it. Taken only of a run the limit stopped.
+     */
+    tooSlow?: boolean;
+}
+/** The debugger's account, as the coding agent is given it. */
+export declare function diagnosisText(diagnosis: Diagnosis): string;
+/** Have a fresh agent find why the unit tests keep failing the same way: its root cause and fix, or undefined when it found none. */
+export declare function debugFailure(input: DebugInput): Promise<Diagnosis | undefined>;

package/dist/regenerate/delivery.d.ts

@@ -0,0 +1,6 @@
+/** What every job that lands code ends with: the person can try it now, by asking. */
+export declare const TRY_IT_LINE = "Want to try it? Just ask me - I'll set it up from what's built so far.";
+/** The same for a command-line run, which has no one to ask: the command that does it. */
+export declare function tryItCommand(plainFile: string): string;
+/** A job's report, ending with how to try what it built when it landed. */
+export declare function withTryItLine(report: string, landed: boolean): string;

package/dist/regenerate/diagnose-job.d.ts

@@ -0,0 +1,2 @@
+import { type Job } from "./jobs.ts";
+export declare function whyFailed(job: Job): string;

package/dist/regenerate/diagnose.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Why a job failed twice, and what has to be done about it - worked out by an agent that can read
+ * everything the job depended on: the project's specs, code, tests and testing scripts, the job's
+ * log and its agents' logs, and turri itself - its source, its skills and its rules. Read only.
+ *
+ * A job is retried once; failing again, it and every job queued behind it fail, and this is what the
+ * person is told: not the last stage it reached, but the cause, and whose it is to fix.
+ */
+export interface Diagnosis {
+    whatHappened: string;
+    cause: string;
+    /** Where the fix belongs: the spec, the environment, the code, or turri itself. */
+    whose: "spec" | "environment" | "code" | "harness";
+    todo: string[];
+}
+/** How many tool calls the diagnosis may make before it is told to decide. */
+export declare const DIAGNOSIS_CALLS = 40;
+export declare function describeDiagnosis(diagnosis: Diagnosis): string;
+export declare function diagnoseFailure(options: {
+    /** The job, as it is listed: its kind and what it was asked to do. */
+    job: {
+        id: string;
+        kind: string;
+        summary: string;
+    };
+    /** What each attempt ended with - its report or its error. */
+    failures: string[];
+    /** The project: its specs, config, testing scripts and plain_modules. */
+    projectDir: string;
+    /** turri's own folder: its source, skills, rules and docs. */
+    harnessDir: string;
+    /** The job's own log, when it has one. */
+    jobLog?: string;
+    model?: string;
+}): Promise<Diagnosis | undefined>;
+export declare function diagnosisPrompt(options: {
+    job: {
+        id: string;
+        kind: string;
+        summary: string;
+    };
+    failures: string[];
+    projectDir: string;
+    harnessDir: string;
+    jobLog?: string;
+}): string;

package/dist/regenerate/diff-view.d.ts

@@ -0,0 +1,61 @@
+import { type PlainRole } from "../plain/highlight.ts";
+/**
+ * A spec diff as the panels show it: each line's ***plain highlighted as plyn highlights it
+ * (`plain/highlight.ts`), an added line on a green band and a removed one on a red, the band the width
+ * of the panel - as an editor shows a diff. Each file is named once, quietly, above its hunks - not
+ * git's headers - and a hunk header is a quiet rule between hunks.
+ */
+/** How a diff is painted: ***plain's colours, and the fills of added and removed lines (`plain-palette.ts`). */
+export interface DiffPaint {
+    /** A piece of ***plain, by what it is. */
+    syntax(role: PlainRole, text: string): string;
+    /** The +/- in front of an added or removed line. */
+    added(text: string): string;
+    removed(text: string): string;
+    /** A whole added or removed row, padded to the width: its band. */
+    addedBand(text: string): string;
+    removedBand(text: string): string;
+    muted(text: string): string;
+}
+/** Painted with nothing: the text as it is, for where there are no colours. */
+export declare const PLAIN_PAINT: DiffPaint;
+/**
+ * Where the lines of a diff are in the .plain files: by a line's place in the diff, the file it is in and its
+ * line there. Only lines that are in a file - added and unchanged ones; a removed line is in none now.
+ */
+export type DiffWhere = Record<number, {
+    file: string;
+    line: number;
+    section?: string;
+}>;
+/**
+ * Place a spec diff's lines in the .plain files they come from - `files`, the module's and every one it
+ * reads, named as they are to be shown. A spec diff is of the spec as read, the files it imports laid into
+ * it, so its own line numbers are not the file's: each line is found where it is written, the file a line
+ * before it was found in first, from there on, and each place once.
+ */
+export declare function locateDiffLines(diff: string, files: Array<{
+    name: string;
+    text: string;
+}>): DiffWhere;
+/** A file's part of a spec diff, as the panels show it: its name, what it adds and takes out, and its rows. */
+export interface DiffFile {
+    file: string;
+    added: number;
+    removed: number;
+    rows: string[];
+}
+/**
+ * A spec diff, file by file: each file's lines together, however the diff has them - a spec diff is of the
+ * spec as read, so what one file holds can come in more than one place - the file being rendered first,
+ * the rest by name. Each line is in the file it is placed in (`where`); a line placed nowhere - a removed
+ * one, or one written other than it reads - goes with the line placed before it, else the one after it,
+ * else the file the diff's own header names. The file being rendered is the one the diff's header names.
+ */
+export declare function diffFiles(diff: string, width: number, paint?: DiffPaint, where?: DiffWhere): DiffFile[];
+/** A file's header: its name, and what it adds and takes out. `open`, with the mark of a group that opens and closes. */
+export declare function fileHeader(file: DiffFile, paint: DiffPaint, open?: boolean): string;
+/** Where a spec diff's lines go that are in none of the spec's files as they are written. */
+export declare const NOT_FOUND = "not found in the spec's files";
+/** The diff's lines, at most `width` wide: every file, each under its header - for a view that opens none and closes none. */
+export declare function diffView(diff: string, width: number, paint?: DiffPaint, where?: DiffWhere): string[];

package/dist/regenerate/drift.d.ts

@@ -0,0 +1,84 @@
+import { type MarshalledPlainSource } from "../plain/spec.ts";
+import { type Chosen } from "./records.ts";
+import { type SpecChange } from "./spec-steps.ts";
+/**
+ * The work, derived from the records - see docs/regenerating.md. Nothing here is stored: what is left
+ * to build is the difference between what a record says is built and what the spec says now, worked
+ * out again whenever either changes.
+ *
+ * - Code work: from the code record to the spec as the code sees it.
+ * - Conformance work: from the tests record to what the conformance tests are to be written for now -
+ *   the chosen functional specs the code is built from.
+ *
+ * A job is a set of those changes. What it tells its agents follows from the functional specs it
+ * touches - its cases - and a running job is stopped once the spec no longer wants what it makes.
+ */
+/** Everything left to build in the code: from what the code record says it is built from, to the spec now. */
+export declare function codeWork(record: MarshalledPlainSource | null, spec: MarshalledPlainSource): SpecChange[];
+/** Everything left to do in the conformance tests: from what the tests record says they are written for, to what they are to be now. */
+export declare function conformanceWork(tests: MarshalledPlainSource | null, code: MarshalledPlainSource | null, spec: MarshalledPlainSource, chosen?: Chosen): SpecChange[];
+/**
+ * A functional spec a job touches: its number - in the spec after the job, or, taken out, before it - its first line,
+ * and the module it belongs to: each module numbers its own from 1, so a number alone can mean two.
+ */
+export interface TouchedSpec {
+    frid: string;
+    text: string;
+    module?: string;
+}
+/**
+ * What a job does to the functional specs, and so what its agents are told:
+ *
+ * - fresh: the module requires none and nothing is built - the project is set up first.
+ * - add: functional specs that are new.
+ * - patch: functional specs changed - their text, their acceptance tests, or a concept they use: a
+ *   change to what is built, never built again from scratch.
+ * - again: functional specs marked to regenerate again (`regenerate` with functionalities named): their code is built, and is regenerated again - rewritten
+ *   or started over, doing what the spec says now - with what it replaces taken out. A functional spec of a module
+ *   this one requires, regenerated again here, is one too.
+ * - delete: functional specs taken out.
+ * - mechanical: none of those - only reqs, or definitions no functional spec uses. Existing tests may
+ *   change only mechanically, and no new ones are written.
+ *
+ * A job can hold several of add, patch and delete at once: its prompt has a section for each.
+ */
+export interface JobCases {
+    fresh: boolean;
+    add: TouchedSpec[];
+    patch: TouchedSpec[];
+    again: TouchedSpec[];
+    delete: TouchedSpec[];
+    mechanical: boolean;
+}
+/**
+ * Every concept a functional spec uses: those its text names, and those their definitions name in
+ * turn, as far as it goes.
+ */
+export declare function conceptsUsed(markdown: string, definitions: Array<{
+    markdown: string;
+}>): Set<string>;
+/**
+ * The cases of a job: `before` is the tree it starts from - the record, or what the jobs ahead of it
+ * leave - and `changes` the changes it makes, found from `before`. `fresh`: the module requires none
+ * and nothing is built.
+ *
+ * A functional spec is patched when its item changed, or when a concept it uses - as the spec after
+ * the job defines it, or as it was defined before - is defined anew, changed or taken out by the job.
+ * `module`: the module whose codebase it is - its own functional specs are that module's.
+ */
+export declare function casesOf(before: MarshalledPlainSource, changes: SpecChange[], options?: {
+    fresh?: boolean;
+    module?: string;
+}): JobCases;
+/**
+ * Whether a running job may finish: every change it makes is still part of the work as it is now -
+ * both measured from the same record, which nothing changes while the job runs. When one is not, the
+ * job is making something the spec no longer wants, and it is stopped and rolled back.
+ */
+/**
+ * Why a running job is no longer wanted, in a line: the files it links that hold something else now - the commonest
+ * cause, a resource edited while the job regenerated from it - else the items whose text changed under it, by section
+ * and place.
+ */
+export declare function whyNotWanted(running: SpecChange[], work: SpecChange[]): string;
+export declare function stillWanted(running: SpecChange[], work: SpecChange[]): boolean;

package/dist/regenerate/engine.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which model the agents of a job run on.
+ *
+ * By default, whatever the conversation is using. The person can say otherwise - "render spec
+ * changes with Gemini Flash" - for one kind of work or for all of it, and that holds for the
+ * rest of the session, for jobs started from a tool call and for jobs a skill queues alike. A
+ * single tool call can also name a model for itself alone.
+ *
+ * A name is resolved strictly. pi's own pattern matching picks its best guess and says nothing
+ * - "gpt-5" becomes a Bedrock model with no credentials, "flash" a GLM one - and a job on a
+ * guessed model is worse than a question. So an exact id is taken as it is, a looser name is
+ * taken only when it fits exactly one model that has credentials, and anything else comes back
+ * as a short list to ask the person about.
+ */
+/** The part of pi's model registry this needs. */
+export interface ModelCatalog {
+    getAll(): ReadonlyArray<CatalogModel>;
+    hasConfiguredAuth(model: CatalogModel): boolean;
+}
+export interface CatalogModel {
+    provider: string;
+    id: string;
+    name?: string;
+}
+export type ModelResolution = {
+    ok: true;
+    model: string;
+    name: string;
+} | {
+    ok: false;
+    message: string;
+    candidates: string[];
+};
+/** Resolve what the person called a model to one this machine can run, or say why not. */
+export declare function resolveModel(query: string, catalog: ModelCatalog): ModelResolution;
+/** The resolution as text for the agent: the model, or why not and what to ask. */
+export declare function describeResolution(resolution: ModelResolution): string;
+/** Kinds of work a model can be chosen for. */
+export type RenderWork = "spec_changes" | "functionalities";
+export declare const WORK_LABEL: Record<RenderWork | "all", string>;
+/** The models chosen in this session, by kind of work. Unset: the project's, or the conversation's model. */
+export type ModelChoices = Partial<Record<RenderWork | "all", string>>;
+/** The model a job of this kind runs on: chosen for it, chosen for everything, or the chat's. */
+export declare function modelFor(choices: ModelChoices, work: RenderWork, chat: string | undefined): string | undefined;
+/**
+ * Where each kind of work runs now, in a line each: chosen in this session, or the default coding
+ * model - from `--coding-model` or config.turri.yaml, said which - or the conversation's.
+ */
+export declare function describeChoices(choices: ModelChoices, chat: string | undefined, project?: {
+    model: string;
+    from: string;
+}): string;

package/dist/regenerate/environment-error.d.ts

@@ -0,0 +1,136 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+/**
+ * When the machine lacks what the work needs - a toolchain, a system library, a credential - no agent can fix it, and
+ * none tries: the pulse stops and is rolled back, the module's later pulses wait, and the person is told what is
+ * missing, how to fix it, and how to run it again. Raised two ways: an agent calls `report_environment_error`, which
+ * ends its turn - its reason goes to the person as it is; or the harness finds it itself - a testing script that cannot
+ * find its toolchain, a credential `agent-env:` names that is not there - and works out at once what to do about it.
+ */
+export declare class EnvironmentError extends Error {
+    /** The module whose pulse stopped. */
+    readonly moduleName: string;
+    /** What the environment lacks. */
+    readonly missing: string;
+    /** What needs it. */
+    readonly neededBy: string;
+    /** What showed it: the command, the output. */
+    readonly shownBy?: string;
+    /** How to fix it, when it is known. */
+    fix?: string;
+    /** Who found it: an agent, or the harness. */
+    readonly source: "agent" | "harness";
+    /**
+     * Nothing is missing: what the agent could not reach is on this machine, and turri's own sandbox kept it from it - the
+     * files it named, and the toolchain folder that holds them, for `toolchains:` to let the agents read.
+     */
+    readonly sandbox?: SandboxGap;
+    constructor(details: {
+        moduleName: string;
+        missing: string;
+        neededBy: string;
+        shownBy?: string;
+        fix?: string;
+        source: "agent" | "harness";
+        sandbox?: SandboxGap;
+    });
+}
+/** Files on this machine turri's sandbox kept an agent from, and the toolchain folder that holds them. */
+export interface SandboxGap {
+    paths: string[];
+    folder: string;
+    /**
+     * What the sandbox refused: reading - a toolchain outside what it lets the agents read, which `toolchains:` fixes - or
+     * writing, which no line of config allows: a lock file a build tool takes as it runs, a cache it fills.
+     */
+    access: "read" | "write";
+    /** The first path is a lock file - `gradle.lock`, `bin/cache/lockfile`, `*.lck`. */
+    lock?: boolean;
+}
+/**
+ * What an agent reported the machine lacks, read for what it says of turri's own sandbox: a file it names that is on
+ * this machine - outside the project and the system's folders, which the sandbox already lets it read - is not missing,
+ * the sandbox hid it. A version manager's Node under ~/.local/share/mise, say, whose npm the agent could not open. Then
+ * the stop is the sandbox's, and the fix is a line of config - `toolchains:` - not an install.
+ */
+export declare function sandboxGapOf(text: string, options?: {
+    project?: string;
+    exists?: (path: string) => boolean;
+    platform?: NodeJS.Platform;
+}): SandboxGap | undefined;
+/**
+ * What the person is told, in the chat, at the end of `turri regenerate`, and in the job's log. `rerun`: the command that runs
+ * the work again, as the pulse knows it - the spec the person ran; without it, the module's own spec by its name.
+ */
+export declare function describeEnvironmentError(error: EnvironmentError, rerun?: string): string;
+/** The name agents know the tool by - their wall text names it. */
+export declare const ENVIRONMENT_ERROR_TOOL = "report_environment_error";
+/** An agent's report that the machine lacks something. */
+export interface EnvironmentReport {
+    missing: string;
+    neededBy: string;
+    shownBy?: string;
+}
+/** Whether a report stands - the pulse stops - or not, and what the agent is told then. */
+export type ReportVerdict = {
+    stands: true;
+} | {
+    stands: false;
+    reply: string;
+};
+/**
+ * An agent's report checked against the harness's own run of the testing script - on this machine, outside the agent's
+ * sandbox, the run that decides whether the work is done. Its shell runs behind walls the script does not: what fails
+ * there may run here. The script passing, the machine has what the work needs: the report does not stand, and the agent
+ * goes on. The script not finding its toolchain, it stands. Failing otherwise, the agent is shown the run once - a
+ * report made again after it stands.
+ */
+export declare function checkAgainstScript(run: () => Promise<{
+    exitCode: number;
+    output: string;
+}>, script: string): (report: EnvironmentReport) => Promise<ReportVerdict>;
+/**
+ * `report_environment_error`: an agent that finds the machine lacking what the work needs says so, and its turn ends.
+ * `record` is told what it reported; whoever asked the turn stops the pulse with it. With `check`, the report is checked
+ * first: one that does not stand is not recorded, and the agent is told why and goes on.
+ */
+export declare function environmentErrorTool(record: (report: EnvironmentReport) => void, check?: (report: EnvironmentReport) => Promise<ReportVerdict>): ToolDefinition;
+/**
+ * A testing script that cannot find its toolchain: the machine lacks it, and no change to the code or the tests would
+ * pass the script - so it is the environment's, found by the harness. `missing` is what the run's output named.
+ */
+export declare function toolchainError(missing: {
+    command?: string;
+}, details: {
+    moduleName: string;
+    script: string;
+    kind: "unit" | "conformance";
+}): EnvironmentError;
+/**
+ * A testing script the time limit stopped while it was still making progress - judged so by the judge or the debugger,
+ * from where its output stops: nothing hangs, the suite needs more time than a test run may take. No agent can give it
+ * that, so the pulse stops and the person is told how to.
+ */
+export declare function timeLimitError(run: {
+    timeoutMs: number;
+    elapsedMs?: number;
+}, details: {
+    moduleName: string;
+    script: string;
+    kind: "unit" | "conformance";
+    reason: string;
+}): EnvironmentError;
+/** The harness's run of a testing script, when it could not find its toolchain: the error that stops the pulse. */
+export declare function missingToolchainError(run: {
+    exitCode: number;
+    output: string;
+}, details: {
+    moduleName: string;
+    script: string;
+    kind: "unit" | "conformance";
+}): EnvironmentError | undefined;
+/**
+ * Before a pulse in `moduleDir` starts any agent: a credential `agent-env:` names that is not there stops it - every
+ * command that needs it would fail, and no agent may make one up. Nothing when all are there, or the folder is no
+ * module's.
+ */
+export declare function missingCredentials(moduleDir: string): EnvironmentError | undefined;

package/dist/regenerate/job-log.d.ts

@@ -0,0 +1,28 @@
+import type { TranscriptEntry } from "./activity.ts";
+/**
+ * A job's whole transcript streamed to a file as it happens: the harness's
+ * stages, the functional spec or the diff it builds, and every one of its agents, in order - what it
+ * was asked, what it thought and wrote, each tool call and its result, whole, not clipped as the
+ * screen clips them - and how the job ended.
+ *
+ * In `.turri/jobs/` in the project, one file per job, beside the per-agent logs in
+ * `.turri/debug/`. Outside `plain_modules`, so no agent reads it. A log that cannot be
+ * written is given up on, never allowed to fail the job.
+ */
+export interface JobLog {
+    readonly file: string;
+    entry(entry: TranscriptEntry): void;
+    /** A line about the machinery under the work (activity.ts `reportNote`): which walls are up, what a command had put back. */
+    note(line: string): void;
+    /** `agents`: a line per agent - its turns, compactions and cost. */
+    end(status: string, report: string | undefined, agents?: string[]): void;
+}
+/** The folder a job's log goes in: the project of the first module it writes, from its lanes. */
+export declare function jobLogDir(lanes: string[]): string | undefined;
+export declare function startJobLog(job: {
+    id: string;
+    kind: string;
+    summary: string;
+    model?: string;
+    diff?: string;
+}, lanes: string[]): JobLog | undefined;

package/dist/regenerate/job-panel.d.ts

@@ -0,0 +1,122 @@
+import { type Color } from "@earendil-works/pi-tui";
+import { type Job } from "./jobs.ts";
+/**
+ * The live panel above the editor while background work runs.
+ *
+ * One block per running job: what it is and how long it has been going, the stage it is
+ * at, what is happening this second, and the last things its agents did. What waits is not
+ * in it - the side panel lists the queue. It disappears when nothing is running - the finished
+ * job announces itself in the transcript instead.
+ *
+ * It is drawn as a component rather than handed over as lines, because pi cuts a list of
+ * lines off at ten. Instead it sizes itself: compact by default, and the agents' trace in full
+ * while tool output is expanded - pi's own ctrl+o, which the person already uses to see more of
+ * what the agent did. What finished stays counted either way: the side panel lists it.
+ */
+export declare const JOB_PANEL_KEY = "turri-jobs";
+/**
+ * The key that opens the side panel on its jobs, and goes back to it. Not ctrl+j: a terminal without the Kitty keyboard
+ * protocol sends ctrl+j as a line feed - what it sends for shift+enter too, and what a dialog reads as enter - so it
+ * would answer a question, and take a new line from the editor. ctrl+h is the byte old terminals sent for backspace;
+ * every terminal now sends backspace as DEL, which pi never takes for ctrl+h, so it is free - in pi, and in a dialog.
+ */
+export declare const PANEL_KEY = "ctrl+h";
+/**
+ * Each key in the line under the panel - ctrl+o, ctrl+h - breathes until it is first pressed: fully there, a little
+ * faint, and back, so it reads as something to press, not as text. Once every BREATH_MS, redrawn every BREATH_TICK_MS
+ * while the panel shows and a key still breathes, at most BREATH_FADE of the way from the text's colour to the dim one.
+ * Pressed once, it stays still for the rest of the process; the other breathes on.
+ */
+export declare const BREATH_MS = 2400;
+/** The keys of the line, by what they do: pressed once, each stops breathing. */
+export type PanelKey = "trace" | "peek";
+/** A key of the line was pressed - ctrl+o, or the side panel opened: it stops breathing. */
+export declare function keyPressed(key: PanelKey): void;
+export declare function breathes(key: PanelKey): boolean;
+/** For tests: every key breathing again. */
+export declare function resetKeysForTests(): void;
+/** How faint a breathing key is at `now`: 0, fully there, at the start of each breath, BREATH_FADE halfway through. */
+export declare function breath(now: number): number;
+export declare function spinner(now: number): string;
+/**
+ * What finished, a line a module - its name, then its pulses oldest first - fitted to `width` from the left: the
+ * newest that fit, the rest counted as earlier. The side panel lists every one.
+ */
+export declare function finishedLines(finished: Job[], width: number | undefined, marks?: MarkPaint): string[];
+/** A pulse that ran to its end and whose build did not pass - stopped at a gate - is not a success. */
+export declare function didNotPass(job: Job): boolean;
+/** How a finished pulse's mark is coloured: green it passed, red it failed or did not pass, amber it was stopped. */
+export interface MarkPaint {
+    success(text: string): string;
+    error(text: string): string;
+    warning(text: string): string;
+}
+/** A finished pulse's mark, in the colour of how it ended. */
+export declare function finishedMark(job: Job, paint?: MarkPaint): string;
+/** What a pulse cost, as its line says it: " · $0.12", or nothing when the price is not known. */
+export declare function pulseCost(job: Job): string;
+/**
+ * One line saying what a spec change does: the files, the lines added and removed, and the
+ * first line it adds - usually the concept or the functional spec it is about.
+ */
+/** How a diff is coloured: added lines green, removed lines red. Plain when there is no theme. */
+export interface DiffStyle {
+    added(text: string): string;
+    removed(text: string): string;
+}
+export declare function summarizeDiff(diff: string, style?: DiffStyle): string;
+/** The lines of a diff worth reading in a panel: the hunks, not the headers. */
+/**
+ * A line of the panel wrapped to its width, its continuations under its text: indented as far as it is,
+ * and past the rule of a diff box when it is in one.
+ */
+export declare function wrapKeepingIndent(line: string, width: number): string[];
+/** A diff's colours for the +/- alone, when there is nothing to highlight with. */
+export interface PanelOptions {
+    /** Everything, rather than the compact view. */
+    expanded?: boolean;
+    now?: number;
+    width?: number;
+    /** The lines of help about ctrl+o and the side panel - left out where they do not apply, as in the side panel itself. */
+    hints?: boolean;
+    /** How the finished pulses' marks are coloured. */
+    marks?: MarkPaint;
+    /** How each key of the line is painted - breathing until it is pressed, in the TUI. */
+    keys?: (key: PanelKey, text: string) => string;
+}
+export declare function jobPanelLines(jobs: Job[], options?: PanelOptions): string[];
+interface Redrawable {
+    requestRender(): void;
+}
+/** What of pi's theme the panel paints with: the diff's colours and bands, and ***plain's colours in it. */
+interface PanelTheme {
+    fg(color: "toolDiffAdded" | "toolDiffRemoved" | "success" | "error" | "warning", text: string): string;
+    /** Whether it is made for a dark or a light surface, and how many colours the terminal has: the diff's palette. */
+    appearance?: "dark" | "light";
+    getColorMode?(): string;
+    /** Each token's concrete colour - what the line of keys breathes between. */
+    colors?: Readonly<Record<string, Color>>;
+}
+/**
+ * The keys of the line, painted at `now`'s breath: one not pressed yet in the text's colour mixed toward the dim one, one
+ * pressed as it is. Plain where the theme has no colours to mix.
+ */
+export declare function breathing(theme: PanelTheme, now: number): (key: PanelKey, text: string) => string;
+/** The parts of pi's TUI the panel needs: enough to draw, redraw, and ask about ctrl+o. */
+export interface PanelUI {
+    setWidget(key: string, content: ((tui: Redrawable, theme: PanelTheme) => {
+        render(width: number): string[];
+        invalidate(): void;
+    }) | undefined, options?: {
+        placement?: "aboveEditor" | "belowEditor";
+    }): void;
+    getToolsExpanded(): boolean;
+}
+export interface JobPanel {
+    /** Where to draw. Until this is set there is no UI, and the panel does nothing. */
+    attach(ui: PanelUI): void;
+    /** Redraw soon, e.g. because a job changed. */
+    refresh(): void;
+}
+export declare function createJobPanel(list: () => Job[]): JobPanel;
+export {};

package/dist/regenerate/jobs-tree.d.ts

@@ -0,0 +1,71 @@
+import { type Job } from "./jobs.ts";
+import type { TranscriptStyle } from "./transcript-view.ts";
+/**
+ * The side panel's Jobs view: the queue as a tree, read one job at a time.
+ *
+ * Three sections - running, queued, finished - each opened and closed on its own, and under them one line per job:
+ * its module, its time and its cost. A job opened shows all of what it builds - the diff, or the spec - and, running,
+ * what it is doing; finished, what went on in it. So what is planned can be read without every diff on the screen at once.
+ *
+ * A cursor moves over the sections and the jobs; it stays on its row, whatever moves under it - a job that finishes
+ * leaves its row to the one after it. A job opened stays open while it stays where it is: moving to another section
+ * it closes, and turns up there collapsed. The state is the conversation's, kept while the panel is closed.
+ */
+export type JobSection = "running" | "queued" | "finished";
+export declare const SECTIONS: JobSection[];
+export interface JobsTreeState {
+    /** Which sections are open. */
+    open: Record<JobSection, boolean>;
+    /** The jobs opened, by id, and the section each was opened in. */
+    openJobs: Map<string, JobSection>;
+    /** The files of each job's diff opened or closed by hand, by job and file: the rest as they start - the file being rendered open, the others closed. */
+    openFiles: Map<string, Map<string, boolean>>;
+    /** The row the cursor is on. */
+    cursor: number;
+    /** The first line shown. */
+    top: number;
+}
+export declare function createJobsTreeState(): JobsTreeState;
+export declare function sectionOf(job: Job): JobSection;
+export type TreeRow = {
+    kind: "section";
+    section: JobSection;
+    count: number;
+} | {
+    kind: "job";
+    section: JobSection;
+    job: Job;
+} | {
+    kind: "file";
+    section: JobSection;
+    job: Job;
+    file: string;
+    first: boolean;
+};
+/** The rows, top to bottom: each section's header, and its jobs when it is open - finished ones newest first. */
+/** The pulse list put on one pulse: its section open, the pulse opened - its stages, its agents, its log - and the cursor on it. */
+export declare function selectJob(jobs: Job[], state: JobsTreeState, id: string): boolean;
+export declare function jobsTreeRows(jobs: Job[], state: JobsTreeState): TreeRow[];
+/** The rows as lines, the cursor's marked, and where each row starts - for scrolling to it. */
+export declare function jobsTreeLines(jobs: Job[], state: JobsTreeState, width: number, style: TranscriptStyle): {
+    lines: string[];
+    rowStarts: number[];
+    rows: TreeRow[];
+};
+/** Keep the cursor's row in sight: scroll only as far as that takes. */
+export declare function keepCursorInView(state: {
+    cursor: number;
+    top: number;
+}, rowStarts: number[], lineCount: number, height: number): void;
+/** Scroll the view by lines, the cursor coming along to the first row in sight. */
+export declare function scrollTree(state: {
+    cursor: number;
+    top: number;
+}, by: number, rowStarts: number[], lineCount: number, height: number): void;
+export type TreeAction = {
+    kind: "none";
+} | {
+    kind: "handled";
+};
+/** A key in the Jobs view, and what it does to the tree. */
+export declare function treeKey(state: JobsTreeState, rows: TreeRow[], key: "up" | "down" | "toggle" | "open" | "close" | "openAll" | "closeAll"): TreeAction;