@turri-dev/cli 0.1.6 → 0.1.7-next.eb57c34

package/dist/release-agent.d.ts

@@ -0,0 +1,26 @@
+import { type DeployState } from "./release-tools.ts";
+/**
+ * What the project says of itself, for the agent to find release guidance in: its AGENTS.md and its skills
+ * (`.agents/skills`, `.pi/skills`, `.claude/skills`), where turri runs and in the host codebase - once each, whole.
+ */
+export declare function projectNotes(dirs: string[]): string[];
+export interface ReleaseAgentInput {
+    plainFile: string;
+    /** Where turri runs. */
+    cwd: string;
+    /** The agent's model: the harness model. */
+    model?: string;
+    /** What release has shipped and been told this conversation - shared with the chat's release. */
+    state: DeployState;
+    inModule?: string;
+    /** What the person said of how to release it. */
+    guidance?: string;
+    /** Released as a pulse's last stage: what the pulse landed. The agent releases only when the guidance says to. */
+    afterPulse?: {
+        moduleName: string;
+        subject: string;
+    };
+    onDelta?: (delta: string) => void;
+}
+/** Run the release agent to its end; its last reply. */
+export declare function runReleaseAgent(input: ReleaseAgentInput): Promise<string>;

package/dist/release-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/release-tools.d.ts

@@ -0,0 +1,38 @@
+import { type Deployment } from "./regenerate/release.ts";
+import type { JobRegistry } from "./regenerate/jobs.ts";
+import type { WorkLoop } from "./regenerate/loop.ts";
+/**
+ * The tools that put a module out for the person to try, and start it: the conversation's, and the
+ * one-off agent's of `turri release`. The harness does the parts that must hold - exporting the
+ * last commit, owning what it starts - and the agent the rest: reading the code to see how it runs,
+ * installing what it needs, starting it, and telling the person where to find it. Nothing is put to
+ * the person: a release does everything itself.
+ */
+export interface DeployState {
+    /** The last deploy: where what is started runs from. */
+    current?: Deployment;
+    /** The last release of each module in this conversation, by module: the commit it shipped. */
+    released: Map<string, Deployment>;
+    /** The guidance each module was last released with, by module: what a release after a pulse is told the person said. */
+    guidance: Map<string, string>;
+}
+export declare function createDeployState(): DeployState;
+/** What the agent is to do once the code is in dist - in the deploy tool's answer, and the CLI agent's prompt. */
+export declare function deployGuide(dir: string): string;
+/**
+ * What the agent is to do on a guided release: the code is in dist, as on any release, and the guidance takes it on from
+ * there. The rules of a release to dist hold here too: what keeps running started with activate, and the built code never
+ * edited - and nothing put to the person.
+ */
+export declare function guidedGuide(deployment: Deployment, guidance: string): string;
+export declare function createDeployTools(options: {
+    cwd: string;
+    state: DeployState;
+    /** The spec deploy takes when it is given none: the project's module. */
+    defaultPlainFile: () => string | undefined;
+    /** The pulses halt stops as well - the conversation's. */
+    jobs?: JobRegistry;
+    /** The work loop whose modules halt halts by a planned row or a name - the conversation's, once it has one. */
+    workLoop?: () => WorkLoop | undefined;
+}): import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>[];
+export declare const DEPLOY_TOOLS: string[];

package/dist/resume-line.d.ts

@@ -0,0 +1,2 @@
+/** pi's line on the way out that says how to resume the session, with turri in place of pi as the command to run. */
+export declare function resumeLine(text: string): string;

package/dist/review/live.d.ts

@@ -0,0 +1,72 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { ContinuousSpec } from "../skill.ts";
+import { type Verdict } from "../tools.ts";
+/**
+ * Review that runs beside the interview instead of after it.
+ *
+ * The interviewer writes a functional spec, queues it, and asks the next question. A
+ * reviewer wakes on that same tick, reads what is now on disk, and either says nothing or
+ * reports what is wrong with it. Findings come back through the next tool result the
+ * interviewer gets, so they arrive between questions - the user is never left waiting on a
+ * review, and a spec that is wrong is caught before four more are built on top of it.
+ *
+ * Two rules keep this honest:
+ *
+ * - The reviewer is read-only. It reports; the interviewer owns the file. Two agents
+ *   editing the same `.plain` mid-interview would produce a file neither of them wrote.
+ * - Passes are serial and coalesced. Ten specs written while one pass runs produce one
+ *   further pass, not ten, and no two reviewers ever read the file at once.
+ */
+export interface LiveFinding {
+    /** What was under review when this was found. */
+    scope: string;
+    criterion: string;
+    evidence: string;
+    fix: string;
+}
+/** Something the reviewer cannot settle from the files alone. */
+export interface LiveQuestion {
+    id: string;
+    scope: string;
+    question: string;
+}
+export interface LiveReviewer {
+    /** Something was written. Schedules a pass; returns immediately. */
+    notice(scope: string): void;
+    /** Findings not yet handed to the interviewer. Draining marks them delivered. */
+    take(): LiveFinding[];
+    /** Questions the reviewer wants the user to answer, if any. */
+    takeQuestions(): LiveQuestion[];
+    /** Hands the user's answer back, to be carried into the next pass. */
+    reply(questionId: string, answer: string): boolean;
+    /** Waits for any pass in flight plus one final pass. Used by the phase gate. */
+    settle(): Promise<{
+        clean: boolean;
+        findings: LiveFinding[];
+    }>;
+    /** Everything found this phase, delivered or not. */
+    history(): LiveFinding[];
+    passes(): number;
+}
+interface LiveVerdict extends Verdict {
+    question?: string;
+}
+/** One review pass. Replaceable so the loop around it can be tested without a model. */
+export type JudgePass = (prompt: string) => Promise<LiveVerdict | undefined>;
+export declare function createLiveReviewer(opts: {
+    cwd: string;
+    spec: ContinuousSpec;
+    rubric: string;
+    /** Auth and the default model come from the session running the interview. */
+    executor?: AgentSession;
+    defaultModel?: string;
+    /** Called when a pass finishes, for the progress display. */
+    onPass?: (result: {
+        scope: string;
+        findings: number;
+    }) => void;
+    judge?: JudgePass;
+}): LiveReviewer;
+export declare function describeFindings(findings: LiveFinding[]): string;
+export declare function describeQuestions(questions: LiveQuestion[]): string;
+export {};

package/dist/rules.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The ***plain authoring rules.
+ *
+ * These are loaded in full into every session's system prompt. They are large - around
+ * 40k tokens - and that is the deliberate trade: a rule the model has to decide to go and
+ * read is a rule it can skip, and these govern every spec this project writes.
+ */
+export declare function loadRules(rulesDir: string, off?: readonly string[]): Array<{
+    name: string;
+    content: string;
+}>;
+/** The block appended to the system prompt. Identical every turn, so it stays cacheable. */
+export declare function renderRulesBlock(rules: Array<{
+    name: string;
+    content: string;
+}>): string;
+export declare function rulesSummary(rules: Array<{
+    name: string;
+    content: string;
+}>): string;

package/dist/run-report.d.ts

@@ -0,0 +1,88 @@
+import type { Job } from "./regenerate/jobs.ts";
+/**
+ * A headless run's report: one JSON file, `turri regenerate --report <file>`, saying what the run did - how it ended,
+ * what it spent, which pulses landed, how many functional specs are completed - for a benchmark or CI to read rather
+ * than the log. See docs/headless.md for every field.
+ *
+ * Written when the run starts, again as each pulse ends, and last as the process exits - however it exits: done, a
+ * pulse failed, a crash, a signal. A process killed outright (SIGKILL) leaves the one written as the last pulse ended.
+ * Each write is atomic: the file is written beside it and renamed over it, so a reader never sees half of one.
+ */
+export declare const REPORT_SCHEMA_VERSION = 1;
+/** What the usage of some model calls adds up to, as the report gives it. */
+export interface UsageTotals {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+    cost_usd: number;
+    /** Model responses. */
+    llm_calls: number;
+    /** Requests of the harness's to an agent, each as many calls as it takes. */
+    agent_turns: number;
+    compactions: number;
+    /** Turns the provider failed for a moment, waited out and tried again. */
+    provider_retries: number;
+    /** Requests the provider sent nothing back on for a long while. */
+    provider_stalls: number;
+    /** Turns turri ended itself - the agent going round in a circle, its time up - and carried on from. */
+    turns_stopped: number;
+    /** How long the models took to answer, added up - from each request to its response's end. */
+    model_seconds: number;
+}
+export type RunStatus = "running" | "completed" | "incomplete" | "failed" | "interrupted" | "crashed" | "dry_run";
+/** How each codebase the run regenerates in stands, as the run ends. */
+export interface ModuleState {
+    module: string;
+    state: "complete" | "incomplete" | "halted" | "start_over_needed" | "running";
+    why?: string;
+}
+export interface CompletionCounts {
+    codebase: string;
+    modules: Array<{
+        module: string;
+        specified: number;
+        completed: number;
+        conformanceTested: number;
+        incomplete: string[];
+    }>;
+}
+/** What the report is made from, read each time it is written. Each is asked in a try: one that fails leaves its part out. */
+export interface ReportSources {
+    jobs: () => Job[];
+    modules?: () => ModuleState[];
+    completion?: () => CompletionCounts[];
+    /** Done once, as the process exits, before the last write: the code exported into --build-dir. */
+    atExit?: () => Record<string, unknown> | undefined;
+}
+export interface RunReporter {
+    attach(sources: ReportSources): void;
+    /** How the run ended, as it decides: written as the process exits. A signal or a crash after it wins. */
+    end(status: Exclude<RunStatus, "running">, error?: string): void;
+    /** The run crashed: written as the process exits. */
+    crashed(error: unknown): void;
+    write(): void;
+    /** The report as it would be written now. */
+    build(exitCode?: number): Record<string, unknown>;
+}
+export interface RunReportOptions {
+    file: string;
+    command: string[];
+    specFile: string;
+    projectDir: string;
+    buildDir?: string;
+    conformanceTests: string;
+    /** Whether the code and its tests are reviewed once they pass. */
+    review?: boolean;
+    /** Whether the coding agent and the reviewer had can_it_fail. */
+    mutationTesting?: boolean;
+    models: Record<"harness" | "coding" | "judge", {
+        model?: string;
+        thinking?: string;
+    }>;
+    /** Not given: the process's exit is listened for. Tests write the last report themselves. */
+    onExit?: false;
+}
+/** Write a file whole or not at all: beside it first, then renamed over it. */
+export declare function writeAtomically(file: string, text: string): void;
+export declare function startRunReport(options: RunReportOptions): RunReporter;

package/dist/screen-padding.d.ts

@@ -0,0 +1,28 @@
+import { type Component } from "@earendil-works/pi-tui";
+/**
+ * Room around the whole of turri's screen: a row above and below, two columns either side - a cell is about twice as
+ * tall as it is wide.
+ *
+ * pi draws its screen one of two ways, and each is padded as it is drawn: full screen (pi's default), a layout - its
+ * root put in the middle of blank rows and columns; the regular screen, the lines its render gives - asked for in fewer
+ * columns, indented, with blank lines above and below. Overlays are laid over the whole terminal, so one that should
+ * keep to the padding is given it as its margin.
+ */
+export declare const SCREEN_PADDING: {
+    readonly top: 1;
+    readonly right: 2;
+    readonly bottom: 1;
+    readonly left: 2;
+};
+/** The columns inside the padding. */
+export declare function paddedColumns(columns: number): number;
+/** The rows inside the padding. */
+export declare function paddedRows(rows: number): number;
+/** What a layout root pads - the root itself when it is not padded. */
+export declare function unpadded(root: Component): Component;
+/**
+ * pi's screen drawn inside the padding, from its next frame - and every layout root it is given after, so the chat
+ * narrowed beside the docked panel (`narrowChat`) is padded too. Once a screen: pi starts a new one when it changes how
+ * it draws, which is padded when it is passed in.
+ */
+export declare function padScreen(tui: object): void;

package/dist/self-invocation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Keeping the conversation's agent on its own tools.
+ *
+ * The agent has a shell, and turri has a command line - so it can build a module by
+ * running `turri regenerate` through bash, or start another pi with `pi -p`. That run is a
+ * second, headless turri: outside this conversation's job queue, its panel and
+ * `/halt`, on whatever model the command line picks, fighting the conversation's own jobs for
+ * the same build directories. It is never the right call unless the person asked for the
+ * command line, so the harness refuses it and names the tool to use instead.
+ */
+/**
+ * What a shell command would run of turri or pi itself, if anything: the subcommand,
+ * or "pi" for another pi. `turri validate`, `drift` and `lineage` are not in it - they start no
+ * agent - and neither are setup and doctor.
+ */
+export declare function selfInvocation(command: string): string | undefined;
+/**
+ * Whether the person's message asks for the command line: it says so, or names the command.
+ * Read from their own words only - an agent that decided on its own does not get through.
+ */
+export declare function askedForCommandLine(message: string): boolean;
+/** What the agent is told when the call is refused. */
+export declare function refusal(what: string): string;
+/** The instruction that goes into the conversation's system prompt. */
+export declare const TOOLS_NOT_CLI: string;

package/dist/setup.d.ts

@@ -0,0 +1,43 @@
+import { type Wall } from "./regenerate/os-sandbox.ts";
+import { type ModelAccess } from "./model-check.ts";
+/**
+ * `turri doctor`: whether this machine is ready for turri.
+ *
+ * It looks: Node, a bash to run commands with, which wall is up under the agents' commands - Seatbelt, bubblewrap, or
+ * the command check and the audit alone - and, in a project, whether this machine has the toolchains its modules'
+ * implementation reqs name and what its testing scripts run, and whether each model its config names answers with this
+ * machine's credentials - one short request a model (model-check.ts). It changes one thing, asked first: a plain `pi`
+ * that an older turri made load turri too is put back to plain pi.
+ */
+type Level = "ok" | "missing" | "limited" | "info";
+export interface Check {
+    level: Level;
+    name: string;
+    detail: string;
+    /** More about it, a line each, shown under the detail. */
+    more?: string[];
+    /** What to run or do about it. */
+    fix?: string;
+}
+/** bash: every agent command and every testing script runs with it, on every platform. */
+export declare function checkShell(found?: boolean, platform?: NodeJS.Platform): Check;
+/** git: each module's history, which every pulse starts from and lands in, and the spec diffs the work is planned from. */
+export declare function checkGit(found?: boolean): Check;
+/** Which wall is up under the agents' commands, and - where none starts - why, and how to give it one. */
+export declare function checkSandbox(wall?: Wall, platform?: NodeJS.Platform): Check;
+/**
+ * In a project: each module's toolchains, as its implementation reqs name them, against this machine's PATH; and each
+ * testing script against this machine - a program it names that is not here, a toolchain it runs that is not on the
+ * PATH. Nothing outside a project.
+ */
+export declare function checkProject(project: string, machine?: {
+    has?: (command: string) => boolean;
+    exists?: (path: string) => boolean;
+}): Check[];
+/**
+ * In a project: each model its config names - with the stack chosen, that stack's over it - tried with one short
+ * request. A model that answers is ready; one that does not says what the provider said, and what to do about it.
+ */
+export declare function checkProjectModels(project: string, access?: ModelAccess): Promise<Check[]>;
+export declare function main(args: string[]): Promise<number>;
+export {};

package/dist/skill-progress.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A skill's run as one line above the input: every phase by name, in order - the ones done ticked, the one it is in
+ * marked, the rest to come - and where that is, phase 2 of 4. `brood` and `spawn` take many turns of
+ * questions and spec changes; without it, nothing on the screen says how far through they are.
+ *
+ *   brood       ✓ intent ━━━━ ⠋ stack ──── ○ testing ──── ○ product       phase 2 of 4
+ *                 stack - the language, frameworks, storage and architecture
+ *
+ * The second line says what the phase it is in does: a phase's name alone - `groundwork` - says little to someone
+ * who has not read the skill.
+ *
+ * A skill of one phase, or none, has nothing to be partway through: its line is the spinner and its name alone.
+ *
+ *   ⠋ add-test-requirement
+ */
+export interface SkillProgress {
+    /** The skill's name. */
+    skill: string;
+    /** Its phases, in order: the `###` headings under its `## Steps`. */
+    phases: string[];
+    /** The phase it is in, by its place in `phases`; -1 before the first has started. */
+    current: number;
+    /** The attempt at the current phase - more than 1 after a gate sent it back. */
+    attempt: number;
+    /** The spinner's frame, for the phase it is in. */
+    frame: string;
+    /** What the phase it is in does, in a line - from the skill's `metadata.phases`. */
+    about?: string;
+}
+export interface ProgressStyle {
+    heading(text: string): string;
+    done(text: string): string;
+    now(text: string): string;
+    muted(text: string): string;
+}
+/**
+ * The line across `width`: the skill's name at the left edge, where it is at the right edge, and between them its
+ * phases, centred in the whole width across its share of it, the joins stretched to fill it - clear of both ends. Too
+ * narrow for that, compact from the left, the phases first, as many as fit.
+ */
+export declare function skillProgressLine(progress: SkillProgress, width: number, style?: ProgressStyle): string;
+/**
+ * The line under it: the phase it is in, and what that phase does - centred under the phases, cut short where it
+ * does not fit. Nothing before the first phase starts, or for a phase the skill does not describe.
+ */
+export declare function skillAboutLine(progress: SkillProgress, width: number, style?: ProgressStyle): string | undefined;

package/dist/skill.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The gate syntax.
+ *
+ * Everything below lives under `metadata:` in SKILL.md frontmatter, which the
+ * Agent Skills spec reserves for arbitrary key-values. A harness that does not
+ * understand it ignores it and the skill degrades to plain prose. Ours parses
+ * it and turns each gate into an edge in the graph, so the gate is enforced by
+ * code rather than by the model deciding to honour a paragraph.
+ */
+export type OnFail = "retry" | "escalate" | "abort";
+export type Quorum = "all" | "majority" | "any";
+export interface ReviewSpec {
+    /** Path to the rubric, relative to the skill directory. */
+    rubric: string;
+    /** Independent judge sessions. Separate sessions, not n samples of one. */
+    judges: number;
+    /** "provider/model-id". Omitted: same model as the executor. */
+    model?: string;
+    /**
+     * Read-only tools the judges may use.
+     *
+     * A rubric that checks what is on disk needs to look at the disk. Judges get nothing by
+     * default, so a gate has to ask for this explicitly, and should ask only for tools that
+     * cannot change anything.
+     */
+    judgeTools: string[];
+    quorum: Quorum;
+    onFail: OnFail;
+    maxRetries: number;
+}
+/**
+ * A reviewer that runs while the step is still running.
+ *
+ * A gate at the end of a phase only finds a problem once the whole phase is written, and
+ * in a phase that builds as it goes that is far too late: functionality 7 is already built
+ * on top of the mistake in functionality 3. A continuous reviewer watches the work as it
+ * lands and reports between questions, so the interview never blocks on it and the final
+ * gate normally has nothing left to find.
+ *
+ * It only works for a step that *adds*: every pass reviews what appeared since the last
+ * clean one, and earlier work is not rewritten underneath it.
+ */
+export interface ContinuousSpec {
+    /** Rubric for the live pass. Checks what is on disk, not the phase record. */
+    rubric: string;
+    /** Judges per pass. One by default: this runs many times, the final gate runs once. */
+    judges: number;
+    model?: string;
+    judgeTools: string[];
+}
+export interface GateSpec {
+    /** Name of the step this gate guards. */
+    after: string;
+    review: ReviewSpec;
+    /** Reviews the work as it is written, rather than waiting for the step to end. */
+    continuous?: ContinuousSpec;
+}
+export interface StepSpec {
+    name: string;
+    /** Prose under the step's heading - this is what the executor is told to do. */
+    instructions: string;
+    /** What the step does, in a short line for the person - shown under the skill's progress while it runs. */
+    about?: string;
+    gate?: GateSpec;
+}
+export interface Skill {
+    name: string;
+    description: string;
+    dir: string;
+    allowedTools: string[];
+    steps: StepSpec[];
+    /**
+     * Whether `write_spec_diff` needs an answer from the user between two new changes - one answer,
+     * one change, as an interview writes them. `metadata.paced: false` turns it off, for a skill that
+     * writes the specs on its own.
+     */
+    paced: boolean;
+    /**
+     * The phases the questioning level caps (`metadata.questioning`, questioning.ts): when there are any, the harness asks
+     * the level first, and each of them asks at most as many questions as it allows. Empty: no level is asked.
+     */
+    questioning: string[];
+    /**
+     * The steps where each answer is a spec change (`metadata.spec-diff-per-answer`): the next question waits until the
+     * last answer is written with `write_spec_diff`, and changes the agent decides itself need no answer before them.
+     */
+    diffPerAnswer: string[];
+}
+export declare function loadSkill(skillDir: string): Skill;
+export declare function readRubric(skill: Skill, review: {
+    rubric: string;
+}): string;
+/**
+ * The status line while a skill runs: which phase, and how far through the skill it is.
+ * The phase is counted from 1 and includes the one in progress, so "3 of 6" means two are
+ * done. A retry after a failed gate says so - the same phase twice is not progress.
+ */
+export declare function skillStatus(skill: Pick<Skill, "name" | "steps">, step: string, attempt: number): string;

package/dist/skills.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Where skills are found: turri's own, in `genome/skills/` of this package, and the project's - `.turri/skills/` and
+ * `.agents/skills/` in the project's folder, a folder a skill with its SKILL.md, in the format of turri's own. A
+ * project's skill is run the same way: its steps, its gates and judges, the tools its frontmatter names.
+ *
+ * A name is one skill: turri's own come first, then `.turri/skills/`, then `.agents/skills/`, and a skill whose name is
+ * taken already is left out and said to be - a project's `brood` never quietly stands in for turri's.
+ */
+import { type Skill } from "./skill.ts";
+/** A project's skill folders, in the order they are read, relative to the project. */
+export declare const PROJECT_SKILL_DIRS: string[];
+export interface FoundSkill extends Skill {
+    /** turri's own, or the project's - then where in it, relative to the project: ".agents/skills/release-notes". */
+    origin: "turri" | {
+        project: string;
+    };
+}
+export interface SkillCatalogue {
+    skills: FoundSkill[];
+    /** Skills that did not parse, by where they are: a name for turri's own, the folder for a project's. */
+    pending: string[];
+    /** A project's skills left out because the name is taken, and by what. */
+    shadowed: string[];
+}
+/** Every skill turri can run in `projectDir`: its own from `packageRoot`, then the project's. */
+export declare function discoverSkills(packageRoot: string, projectDir: string | undefined): SkillCatalogue;
+/** A skill's line in cultivate's list: a project's says so, and where it is. */
+export declare function catalogueLine(skill: FoundSkill): string;
+/** What is said under the list about the skills it leaves out. */
+export declare function leftOutNote(catalogue: SkillCatalogue): string;

package/dist/spec-diff-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spec-tools.d.ts

@@ -0,0 +1,36 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type WorkLoop } from "./regenerate/loop.ts";
+import { type LiveReviewer } from "./tools.ts";
+/** Whether a question has been answered since the last new spec change was written. */
+export interface SpecPace {
+    /** A question was answered; `owesChange` false for one no change comes from - a phase's confirmation, a dismissal. */
+    answered(owesChange?: boolean): void;
+    /** Whether an answer has come since the last change, and is not written yet. */
+    owed(): boolean;
+}
+type AnyTool = ToolDefinition<any, any, any>;
+/**
+ * Writing a spec change as a diff, and building it, as one step.
+ *
+ * In an interview whose unit of work is a spec change, every change is meant to be built the
+ * moment it is written. Left to two tool calls - change the file, then start the render - the
+ * second is the one that gets forgotten, and nothing notices. So the diff is applied and its
+ * build queued in the same call: a change cannot reach the specs without its render being
+ * started. A new change needs an answer since the last one; a correction does not.
+ */
+export declare function createSpecDiffTools(options: {
+    loop: WorkLoop;
+    cwd: string;
+    liveReview?: LiveReviewer;
+    /** One new change per answer (the default); false, for a skill that writes the specs on its own. */
+    paced?: boolean;
+    /**
+     * Whether the phase the interview is in lets a change come without an answer before it: one where each answer owes a
+     * change instead (`owed`, refused a next question until it is written), and the agent writes what it decides itself.
+     */
+    free?: () => boolean;
+}): {
+    tools: AnyTool[];
+    pace: SpecPace;
+};
+export {};

package/dist/stack.d.ts

@@ -0,0 +1,58 @@
+/**
+ * What a project's specs need of this machine: the toolchains its implementation reqs name, and whether the machine
+ * has them - the agents use this machine's toolchains and install none.
+ *
+ * The implementation reqs say what the code is written in and built with - "Python 3.12 and FastAPI", "a React app
+ * built with Vite", "Java 21 with Spring Boot". This reads them, and says which toolchain each needs and by which word -
+ * a hint for the person, not a verdict: a req can name a technology it does not use.
+ */
+/** A toolchain the reqs name: its name, the commands any one of which shows it is there, and the words that named it. */
+export interface StackNeed {
+    toolchain: string;
+    commands: string[];
+    words: string[];
+}
+/** The toolchains a text of implementation reqs names. */
+export declare function stackOf(text: string): StackNeed[];
+/** The implementation reqs of every module in a project's folder, as the parser has them - imports in. */
+export declare function projectImplementationReqs(project: string): Array<{
+    module: string;
+    reqs: string[];
+}>;
+/** What a project's modules need of this machine, and which of it the machine lacks. */
+export declare function stackOnMachine(project: string, has?: (command: string) => boolean): Array<{
+    module: string;
+    needs: StackNeed[];
+    missing: StackNeed[];
+}>;
+/**
+ * The standard library's languages, and what builds and tests their stacks here - every command needed. Python's stacks
+ * run through uv, which fetches Python itself; TypeScript's through npm; Java's through the Maven or Gradle wrapper,
+ * which needs only Java.
+ */
+export declare const STDLIB_LANGUAGES: Array<{
+    language: string;
+    commands: string[];
+}>;
+/** Which of the standard library's languages this machine can build and test now, and which it lacks a command of. */
+export declare function languagesOnMachine(has?: (command: string) => boolean): {
+    ready: typeof STDLIB_LANGUAGES;
+    missing: typeof STDLIB_LANGUAGES;
+};
+/**
+ * What a spec-writing agent and the conversation are told of this machine before a stack is chosen: the languages it
+ * can build now. The agents install nothing, so a stack in a language the machine lacks stops at its first build -
+ * offering one is offering a project that cannot be regenerated here until the person installs it.
+ */
+export declare function toolchainsBlock(has?: (command: string) => boolean): string;
+/**
+ * What in a testing script this machine does not have: a program named by a whole path that is not there - a
+ * macOS-only `/usr/libexec/java_home` on Linux - and a toolchain it runs that is not on the PATH. The script is the
+ * person's: this is for them to fix, before an agent ever sees it fail.
+ */
+export declare function scriptAgainstMachine(text: string, machine?: {
+    has?: (command: string) => boolean;
+    exists?: (path: string) => boolean;
+}): string[];
+/** A testing script's text, or nothing when it cannot be read. */
+export declare function readScript(path: string): string | undefined;

package/dist/stacks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Choosing a stack: `config.turri.<stack>.yaml` laid over `config.turri.yaml` for everything built from then on - a
+ * backend's testing scripts, then a frontend's. `/stack` and the `stack` tool in the chat, `--stack <name>` on the
+ * command line (cli.ts). The choice itself is kept in config.ts (`chooseStack`), for the session only.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** The stacks of the projects here: the folder's own, and those of the projects one folder down (specs kept in plain/). */
+export declare function knownStacks(root: string): string[];
+/** Choose `name` - or none - among the stacks here, and say what is chosen now; a stack the project has no file for is refused. */
+export declare function switchStack(root: string, name: string | undefined): string;
+/** /stack and the chat's stack tool. */
+export declare function registerStacks(pi: ExtensionAPI, cwd: string): void;