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

package/dist/extension.js

@@ -80,8 +80,17 @@ const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
  */
 export function askUserVia(ctx, onExchange, 
 /** Given, "/btw ..." typed as an answer is a side question: answered with this, and the question asked again. */
-aside) {
+aside, 
+/** A host's own dialogs (TurriHost.dialogs), the question put in them instead of the terminal's. */
+dialogs) {
     return async (request) => {
+        if (dialogs !== undefined) {
+            const asking = (asked) => runAsk(asked, dialogs);
+            const bare = { ...request, said: undefined };
+            const answer = aside !== undefined ? await askWithAsides(bare, asking, aside) : await asking(bare);
+            onExchange(request.question, answer, [request.context, request.said].map((part) => part?.trim() ?? "").filter((part) => part !== "").join("\n\n") || undefined);
+            return answer;
+        }
         if (!ctx.hasUI) {
             return "No user is available to answer. Decide yourself, and say in your report what you assumed.";
         }
@@ -156,9 +165,9 @@ function hookPeekKey(ctx) {
  * pick from, several at once, "Something else…" to type instead, "Chat about this" to talk it over in
  * the chat first - so a question with a handful of answers is picked, not typed.
  */
-export function chatAskUserTool() {
+export function chatAskUserTool(dialogs) {
     let conversation;
-    const tool = createAskUserTool((request) => (conversation !== undefined ? askUserVia(conversation, () => { })(request) : Promise.resolve("No user is available to answer.")), undefined, undefined, undefined, "reply");
+    const tool = createAskUserTool((request) => (conversation !== undefined ? askUserVia(conversation, () => { }, undefined, dialogs)(request) : Promise.resolve("No user is available to answer.")), undefined, undefined, undefined, "reply");
     return {
         ...tool,
         promptGuidelines: [
@@ -171,7 +180,14 @@ export function chatAskUserTool() {
         },
     };
 }
-export default function (pi) {
+/** The host each conversation's jobs report to, for the work loop made for them later. */
+const hosts = new WeakMap();
+/** turri's conversation as an extension of pi's, for a host that runs it itself: see TurriHost. */
+export function createTurriExtension(host = {}) {
+    return (pi) => turriExtension(pi, host);
+}
+export default createTurriExtension();
+function turriExtension(pi, host) {
     dropNoise();
     const cwd = process.cwd();
     // turri's own skills, and the project's - .turri/skills, .agents/skills (skills.ts).
@@ -189,7 +205,10 @@ export default function (pi) {
     const deployState = createDeployState();
     const jobs = createJobRegistry({
         // The loop's plan changed - a module being planned, or planned: the live panel shows it at once.
-        onNotify: () => panel.refresh(),
+        onNotify: () => {
+            panel.refresh();
+            host.onPlanChange?.();
+        },
         // A job that fails is run once more; failing again, it and every job behind it fail, and the
         // harness - which can read the skills, the rules, the code, the tests and turri itself -
         // works out why, and what has to be done.
@@ -208,9 +227,13 @@ export default function (pi) {
             });
             return diagnosis !== undefined ? describeDiagnosis(diagnosis) : undefined;
         },
-        onChange: () => panel.refresh(),
+        onChange: (job) => {
+            panel.refresh();
+            host.onJobChange?.(job);
+        },
         onFinish: (job) => {
             panel.refresh();
+            host.onJobChange?.(job);
             // Queued again as another job: that one says how it went.
             if (job.replacedBy !== undefined)
                 return;
@@ -236,6 +259,8 @@ export default function (pi) {
             }, { triggerTurn: true, deliverAs: "followUp" });
         },
     });
+    hosts.set(jobs, host);
+    host.onJobs?.(jobs);
     // The ***plain rules go into the system prompt in full, every turn. The block is
     // identical each time, so it sits inside the cached prefix rather than invalidating it.
     // With them, the instruction to do turri's work with its tools rather than its command
@@ -375,7 +400,7 @@ export default function (pi) {
     registerBranding(pi, discoveredSkills);
     registerInterviewLog(pi);
     registerJobTools(pi, jobs, cwd);
-    registerCheckPlain(pi, cwd);
+    registerCheckPlain(pi, cwd, host.dialogs);
     registerRegenerate(pi, cwd, jobs);
     registerDrift(pi, cwd, jobs);
     registerGlimpse(pi, cwd, jobs);
@@ -549,7 +574,7 @@ export default function (pi) {
                     push(`  Q: ${question}`);
                     push(`  A: ${answer}`);
                     recordExchange(pi, { skill: skill.name, question, answer, ...(said !== undefined && said.trim() !== "" ? { said: said.trim() } : {}) });
-                }, (question) => askOnTheSide(pi, ctx, cwd, jobs, question)),
+                }, (question) => askOnTheSide(pi, ctx, cwd, jobs, question), host.dialogs),
                 model: conversationModel(ctx),
                 // Renders queued by a step land in the same registry as everything else, so
                 // pulses sees them without knowing a skill started them.
@@ -1326,6 +1351,7 @@ function workLoopFor(jobs, cwd, ctx) {
         });
         shared = { loop, from };
         workLoops.set(jobs, shared);
+        hosts.get(jobs)?.onWorkLoop?.(loop);
     }
     shared.from.ctx = ctx;
     return shared.loop;
@@ -1932,9 +1958,9 @@ function jobLines(all) {
  * so it needs no external tool, no API key and no credits - and it is the only honest way
  * to answer "is this spec valid?" without generating anything.
  */
-function registerCheckPlain(pi, cwd) {
+function registerCheckPlain(pi, cwd, dialogs) {
     pi.registerTool(checkPlainTool(cwd));
-    pi.registerTool(chatAskUserTool());
+    pi.registerTool(chatAskUserTool(dialogs));
     // The web, for the conversation too - a library's documentation, an API, an error; curl is its
     // bash. Run here, like the rendering agents' (see render/web.ts).
     for (const tool of createWebTools())

package/dist/genome.d.ts

@@ -0,0 +1,62 @@
+import { type Reporter } from "./graph.ts";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Skill } from "./skill.ts";
+import { type AskUser } from "./tools.ts";
+import type { JobRegistry } from "./regenerate/jobs.ts";
+import type { WorkLoop } from "./regenerate/loop.ts";
+export interface EscalationRequest {
+    step: string;
+    artifact: string;
+    critique: string;
+    question: string;
+}
+export interface RunSkillResult {
+    skill: Skill;
+    ok: boolean;
+    artifacts: Record<string, string>;
+    /** The last step's artifact - what the caller usually wants. */
+    output: string;
+}
+/**
+ * Run one skill to completion. The only entry point: the CLI and the Pi extension
+ * both go through here, so a skill behaves identically whether a human launched it
+ * or a conversational agent decided to.
+ */
+export declare function runSkill(opts: {
+    skillDir: string;
+    cwd: string;
+    runDir: string;
+    report: Reporter;
+    /** Called when a gate cannot be satisfied. Return true to accept the artifact anyway. */
+    escalate: (request: EscalationRequest) => Promise<boolean>;
+    /** Lets a step interview the user. Omitted: the skill runs with nobody to ask. */
+    askUser?: AskUser;
+    /** "provider/model-id" for the executor and the judges. Omitted: pi's default. */
+    model?: string;
+    /** Lets steps build functionalities in the background while the interview continues. */
+    renderQueue?: WorkLoop;
+    /** What the user has already said, so the skill does not re-ask it. */
+    context?: string;
+    /** Pick up the run of this skill that was interrupted here, rather than start a new one. */
+    resume?: boolean;
+    /**
+     * Tools the conversation's agent has that the skill's agent needs as well, because the person
+     * talks to the skill's agent while it runs - choosing the render model, for one.
+     */
+    sharedTools?: ToolDefinition[];
+    /**
+     * The conversation's tools that act on the work loop (loop-tools.ts): drift, for every skill with the loop - how its
+     * builds stand - and regenerate and halt for a skill that names them in its allowed-tools.
+     */
+    loopTools?: ToolDefinition[];
+    /** The jobs the render queue runs, for a skill that waits for its builds and reads what they recorded. */
+    jobs?: JobRegistry;
+}): Promise<RunSkillResult>;
+/** Whether there is a run of this skill here that was interrupted, and could be resumed. */
+export declare function interruptedRun(runDir: string, skillName: string): {
+    step?: string;
+    updatedAt: string;
+} | undefined;
+/** Human-readable one-liner per step, for logs and tool output. */
+export declare function describeGates(skill: Skill): string[];
+export type { Reporter };

package/dist/graph.d.ts

@@ -0,0 +1,52 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { type LiveReviewer } from "./review/live.ts";
+import { type Skill } from "./skill.ts";
+export type Decision = "advance" | "retry" | "escalate" | "abort";
+export declare const GenomeState: import("@langchain/langgraph").AnnotationRoot<{
+    artifacts: import("@langchain/langgraph").BaseChannel<Record<string, string>, Record<string, string> | import("@langchain/langgraph").OverwriteValue<Record<string, string>>, unknown>;
+    attempts: import("@langchain/langgraph").BaseChannel<Record<string, number>, Record<string, number> | import("@langchain/langgraph").OverwriteValue<Record<string, number>>, unknown>;
+    /** Judge feedback for the step currently being retried. */
+    critique: import("@langchain/langgraph").BaseChannel<string, string | import("@langchain/langgraph").OverwriteValue<string>, unknown>;
+    decision: import("@langchain/langgraph").BaseChannel<Decision, Decision | import("@langchain/langgraph").OverwriteValue<Decision>, unknown>;
+}>;
+export type GenomeStateType = typeof GenomeState.State;
+export interface Reporter {
+    step(name: string, attempt: number): void;
+    artifact(path: string, body: string): void;
+    gate(name: string, judges: number): void;
+    /** One continuous-review pass finished while the step was still running. */
+    livePass?(step: string, scope: string, findings: number): void;
+    /** The continuous reviewer's closing word, read at the gate. */
+    liveReview?(name: string, passes: number, findings: number): void;
+    judge(index: number, model: string, verdict: string, violations: number): void;
+    outcome(name: string, decision: Decision, critique: string): void;
+    /** One thing the skill's agent just did - a tool call, as one short line - for a view of it while it works. */
+    activity?(line: string): void;
+    /** The skill's agent's words as they stream, from the start of each reply: `fresh` when a new one begins. */
+    said?(delta: string, fresh: boolean): void;
+}
+/** How many times a step whose turn ends on a question in its reply is sent back to carry on. */
+export declare const QUESTION_NUDGES = 2;
+/** Whether a reply ends on a question: its last line, its markdown left aside, ends with a question mark. */
+export declare function endsOnQuestion(reply: string): boolean;
+export declare function compileSkill(opts: {
+    skill: Skill;
+    cwd: string;
+    runDir: string;
+    executor: AgentSession;
+    report: Reporter;
+    /** Default model for the judges, when a gate does not name one of its own. */
+    model?: string;
+    /** What the user has already said, carried in from the conversation that started this. */
+    context?: string;
+    /** Reviewers already reading along, by step name. Their findings gate the step too. */
+    liveReviewers?: Map<string, LiveReviewer>;
+    /** Start at this step instead of the first: a resumed run, picking up where it stopped. */
+    startAt?: string;
+    /** Called as each step starts, with the state it starts from - what a resumed run restores. */
+    onStepStart?: (step: string, state: GenomeStateType) => void;
+    /** Called once a step is reported started, before its agent is prompted: the harness's own question goes here. */
+    beforeStep?: (step: string) => Promise<void>;
+    /** What the harness tells the agent as a step starts, beside its instructions - the questioning level, say. */
+    stepNote?: (step: string) => string | undefined;
+}): any;

package/dist/host.d.ts

@@ -0,0 +1,20 @@
+/**
+ * turri for a host that runs it itself - a desktop app, an editor - imported as `@turri-dev/cli/host`: the
+ * conversation as pi's extension, with the host told of its jobs and asking its questions (createTurriExtension), and
+ * what a host shows beside it - a spec parsed, checked and coloured, how far each functional spec is built, the work a
+ * spec change would plan. It is turri's own code, as the terminal runs it; a 0.x release may change any of it.
+ */
+export { createTurriExtension, type TurriHost } from "./extension.ts";
+export type { AskUserIO } from "./ask.ts";
+/** pi itself, as turri's extension is built against it: a host makes its session with this one, not another copy. */
+export * as pi from "@earendil-works/pi-coding-agent";
+export { configForSpec, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf, type ProjectConfig } from "./config.ts";
+export { MODULES_DIR, projectDirOf, resolveTemplateDirs } from "./regenerate/paths.ts";
+export { checkPlainFile, type CheckResult } from "./plain/check.ts";
+export { plainFileParser } from "./plain/parser.ts";
+export { FUNCTIONAL_REQUIREMENTS, iterateFunctionalSpecs } from "./plain/spec.ts";
+export { highlightLines, roleOf, type PlainRole } from "./plain/highlight.ts";
+export { createWorkLoop, describeModules, functionalityCompletion, promptOf, type DriftReport, type ModuleStatus, type WorkLoop } from "./regenerate/loop.ts";
+export { createJobRegistry, defaultParallelJobs, type Job, type JobRegistry } from "./regenerate/jobs.ts";
+export { describeTurnIncident, onModelEvent, type TranscriptEntry } from "./regenerate/activity.ts";
+export { sweepOrphanedGroups } from "./regenerate/shell.ts";

package/dist/host.js

@@ -0,0 +1,23 @@
+/**
+ * turri for a host that runs it itself - a desktop app, an editor - imported as `@turri-dev/cli/host`: the
+ * conversation as pi's extension, with the host told of its jobs and asking its questions (createTurriExtension), and
+ * what a host shows beside it - a spec parsed, checked and coloured, how far each functional spec is built, the work a
+ * spec change would plan. It is turri's own code, as the terminal runs it; a 0.x release may change any of it.
+ */
+// The conversation.
+export { createTurriExtension } from "./extension.js";
+/** pi itself, as turri's extension is built against it: a host makes its session with this one, not another copy. */
+export * as pi from "@earendil-works/pi-coding-agent";
+// The project and its settings.
+export { configForSpec, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf } from "./config.js";
+export { MODULES_DIR, projectDirOf, resolveTemplateDirs } from "./regenerate/paths.js";
+// A spec: parsed, checked, coloured.
+export { checkPlainFile } from "./plain/check.js";
+export { plainFileParser } from "./plain/parser.js";
+export { FUNCTIONAL_REQUIREMENTS, iterateFunctionalSpecs } from "./plain/spec.js";
+export { highlightLines, roleOf } from "./plain/highlight.js";
+// The work: what is built, what is left, and the jobs that build it.
+export { createWorkLoop, describeModules, functionalityCompletion, promptOf } from "./regenerate/loop.js";
+export { createJobRegistry, defaultParallelJobs } from "./regenerate/jobs.js";
+export { describeTurnIncident, onModelEvent } from "./regenerate/activity.js";
+export { sweepOrphanedGroups } from "./regenerate/shell.js";

package/dist/identity.d.ts

@@ -0,0 +1,2 @@
+/** Who the conversation's agent is: turri, and what it does - first, so it speaks as turri, in the first person. */
+export declare const TURRI_IDENTITY: string;

package/dist/init-config.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `turri init-config`: a project's first config.turri.yaml - the two models, a strong one to talk to and a smaller one to
+ * write the code - so a new project starts with a choice that works rather than an empty file. It asks which vendor's
+ * models you use and fills in theirs. Every other setting is written out with the value turri uses for it (DEFAULTS),
+ * so the file says how the project is built; the optional ones, which have no value of their own - the testing
+ * scripts, `module`, `judge-model`, `models` - are there commented out, with an example. docs/config.md has them all.
+ *
+ * Then it says what to do next: where the file is - turri reads it from that folder and the folders below it, nowhere
+ * else - and how to sign in to the vendor so pi, which turri runs on, can reach the models.
+ *
+ * Amazon Bedrock serves Anthropic's and OpenAI's models in a geography each - an inference profile, `eu.`, `us.`,
+ * `global.` - so it asks which of the two, and where. A config.turri.yaml already there keeps everything but the two models; a new one takes
+ * from a config.yaml beside it the keys turri reads too.
+ */
+/** A vendor whose models the quick start config is filled in with. */
+export type Vendor = "anthropic" | "openai" | "google" | "amazon-bedrock" | "other";
+/** Whose models Amazon Bedrock serves here. */
+export type BedrockMaker = "anthropic" | "openai";
+/** Amazon Bedrock's choice: whose models, and the geography of the inference profile they run in. */
+export interface BedrockChoice {
+    maker: BedrockMaker;
+    region: string;
+}
+/** The geographies Bedrock serves each maker's two models in, as pi knows them - the first the default. */
+export declare const BEDROCK_REGIONS: Record<BedrockMaker, string[]>;
+/** Bedrock's models for a maker in a geography: Opus 5.5 and Haiku 5.5, or GPT-6 Astra and Luna. */
+export declare function bedrockModels(choice: BedrockChoice): {
+    harness: string;
+    coding: string;
+    strong: string;
+};
+/** Bedrock's default: Anthropic's models, anywhere. */
+export declare const BEDROCK_DEFAULT: BedrockChoice;
+interface VendorPreset {
+    label: string;
+    /** The model you talk to: it writes the specs and plans the work. */
+    harness: string;
+    /** The smaller, cheaper one that writes the code. */
+    coding: string;
+    /** A strong model for the commented-out judge, reviewer and debugger examples. */
+    strong: string;
+    /** The environment variables pi reads the vendor's keys from - pi's own names (pi.dev, providers). */
+    keys: Array<{
+        vendor: string;
+        variable: string;
+    }>;
+}
+export declare const VENDORS: Record<Vendor, VendorPreset>;
+/**
+ * A config.turri.yaml with its two models set to these lines, and nothing else changed: each key's line - and the lines
+ * indented under it, when it is written as a block - replaced where it is, or put at the top when it is not there.
+ */
+export declare function withModels(text: string, lines: [string, string]): string;
+/**
+ * What turri does with each setting the config leaves out, written into the quick start config so it says so. They
+ * must stay what the code falls back to - tests/init-config.test.ts holds them to the constants they mirror.
+ */
+export declare const DEFAULTS: {
+    readonly conformanceTests: false;
+    readonly review: false;
+    readonly mutationTesting: true;
+    readonly allowToStopJobs: true;
+    readonly releaseAfterPulse: false;
+    readonly testingScriptsRunOn: "in-place";
+    readonly turnLimit: 120;
+    readonly compactAt: 100000;
+    readonly maxSpecsPerPulse: 3;
+    readonly maxLinesPerPulse: 120;
+};
+/** How many pulses run at once without a setting: half this machine's cores, one to four - as regenerate/jobs.ts has it. */
+export declare function defaultParallel(cores?: number): number;
+/** The quick start config.turri.yaml for a vendor's models - for Bedrock, the maker and geography chosen. */
+export declare function quickStartConfig(vendor?: Vendor, bedrock?: BedrockChoice): string;
+/** The quick start config for the mix of vendors: what turri wrote before it asked. */
+export declare const QUICK_START_CONFIG: string;
+/** A vendor from what was typed: its number in the list, or its name. */
+export declare function vendorOf(answer: string): Vendor | undefined;
+/** Bedrock's maker from what was typed: its number - 1 Anthropic, 2 OpenAI - or its name. */
+export declare function bedrockMakerOf(answer: string): BedrockMaker | undefined;
+/** A geography the maker's models are served in, from what was typed: its number in the list, or its name. */
+export declare function bedrockRegionOf(maker: BedrockMaker, answer: string): string | undefined;
+/**
+ * What a config.yaml in `folder` says that turri reads too - another tool's testing scripts, say - by turri's names
+ * (`template_dir` read as `template-dir`), in the file's order; and the keys it leaves, turri reading none of them. The
+ * two models are the vendor's, so they are not taken.
+ */
+export declare function sharedWithLegacy(folder: string): {
+    carried: Array<[string, unknown]>;
+    left: string[];
+};
+/**
+ * Write the quick start config.turri.yaml in `dir`, with what a config.yaml beside it says that turri reads too. One already
+ * there keeps everything but its two models, which are set to the vendor's - `force` writes the whole of it again. Says
+ * what it did.
+ */
+export declare function initConfig(dir: string, options?: {
+    force?: boolean;
+    vendor?: Vendor;
+    bedrock?: BedrockChoice;
+}): {
+    written: boolean;
+    message: string;
+};
+/** `turri init-config [--vendor <vendor>] [--maker <maker>] [--region <geography>] [--force] [folder]`. */
+export declare function main(args: string[]): Promise<number>;
+export {};

package/dist/jellyfish.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The jellyfish turri is named after, in pixels: a pink bell, an orange gut, neon tentacles coming apart into code at
+ * their tips - the design system's colours, swimming a stroke a loop. Drawn at two sizes from one design: the banner's
+ * pictures are rendered from the large one (scripts/jellyfish-frames.mjs writes assets/jellyfish/), and where a terminal
+ * shows no images the small one is drawn here in half blocks, two pixels a cell - drawn at its size, not shrunk, so no
+ * pixel of it is lost.
+ */
+/** What a pixel is: the bell, its glint and shine, the gut, the underside, a tentacle, an oral arm, a tip fading. */
+type Pixel = "p" | "h" | "w" | "o" | "e" | "N" | "n" | "l" | "g";
+/** The pixels' colours on a dark background and a light one - the tentacles darker on light, where neon does not show. */
+export declare const JELLYFISH_COLOURS: Record<"dark" | "light", Record<Pixel, string>>;
+export declare const JELLYFISH_WIDTH: number;
+export declare const JELLYFISH_HEIGHT: number;
+/** The large jellyfish's frames, a stroke: what the pictures are rendered from. */
+export declare const JELLYFISH_FRAMES: string[][];
+/** The small jellyfish's frames, a stroke: what a terminal without images draws, in half blocks. */
+export declare const JELLYFISH_TEXT_FRAMES: string[][];
+/** How long each frame shows. */
+export declare const JELLYFISH_FRAME_MS = 250;
+/**
+ * A frame drawn in half blocks for a terminal that shows no images: two pixels a cell, the upper one the text's colour
+ * and the lower one the background's, in as many colours as the terminal has: a column a pixel, a row every two.
+ */
+export declare function halfBlocks(pixels: string[], appearance: "dark" | "light", truecolor: boolean): string[];
+export {};

package/dist/judge.d.ts

@@ -0,0 +1,25 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { type Verdict } from "./tools.ts";
+import type { ReviewSpec } from "./skill.ts";
+export interface JudgeResult {
+    index: number;
+    model: string;
+    verdict: Verdict | undefined;
+}
+export interface GateOutcome {
+    passed: boolean;
+    results: JudgeResult[];
+    /** Feedback handed back to the executor on retry. Empty when the gate passed. */
+    critique: string;
+}
+export declare function runGate(opts: {
+    cwd: string;
+    review: ReviewSpec;
+    rubric: string;
+    artifactPath: string;
+    artifact: string;
+    executor: AgentSession;
+    /** Used when the gate does not name a model - normally the conversation's. */
+    defaultModel?: string;
+    onJudgeStart?: (index: number, model: string) => void;
+}): Promise<GateOutcome>;

package/dist/lineage-cli.d.ts

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

package/dist/loop-cli.d.ts

@@ -0,0 +1,34 @@
+import { type DriftReport, type ModuleStatus, type WorkLoop } from "./regenerate/loop.ts";
+import { type ModuleState } from "./run-report.ts";
+/**
+ * What every command that builds - `turri regenerate`, `conform`, `spec-diff` - does around its own
+ * request of the work loop, as the chat does it: the project's models, a job that fails run once more and, failing again,
+ * diagnosed, a line as each job starts and ends; then the loop run until nothing more can start, how each job ended,
+ * and exit 1 when any failed or a module is not complete. With `dryRun`, the work is planned and the prompt of the first job each codebase would
+ * start printed, and nothing runs.
+ */
+export declare function runLoop(options: {
+    plainFile: string;
+    /** Where the code is exported to as the run ends, however it ends: the furthest-built codebase's last commit. */
+    buildDir?: string;
+    /** The run report's file (`--report`): see run-report.ts. */
+    report?: string;
+    /** The command, as the report gives it: its name and its arguments. */
+    command?: string[];
+    dryRun?: boolean;
+    /** Start over, unasked, a codebase that has to be on a module it now requires (`--start-over`). */
+    startOver?: boolean;
+    /** The request: bring up, regenerate, conformance. */
+    ask: (loop: WorkLoop) => Promise<ModuleStatus[]>;
+}): Promise<never>;
+/** How each codebase stands, from what is left to regenerate there. */
+export declare function moduleStates(reports: DriftReport[]): ModuleState[];
+/**
+ * The options every command that regenerates takes for a headless run: `--report` and `--build-dir`, and the config's
+ * own keys (configKeyOptions) - `--harness-model`, `--coding-model` (`--model`), `--judge-model`, `--review`, `--mutation-testing` and, where
+ * `conformance` is true, `--conformance-tests` - read as if config.turri.yaml had them. Exits on a value it cannot read.
+ */
+export declare function headlessOptions(options: Record<string, string | undefined>, conformance: boolean): {
+    report?: string;
+    buildDir?: string;
+};

package/dist/loop-tools.d.ts

@@ -0,0 +1,80 @@
+import { type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { type ModuleStatus, type WorkLoop } from "./regenerate/loop.ts";
+import type { RenderWork } from "./regenerate/engine.ts";
+import { type JobRegistry } from "./regenerate/jobs.ts";
+/**
+ * The tools that act on the work loop - `regenerate`, `drift` and `halt` - defined once, for the conversation and for the
+ * skills alike: a skill that regenerates what a spec holds, or reads how far it is regenerated, uses the conversation's
+ * own tools, on the conversation's loop, never copies of them.
+ */
+type AnyTool = ToolDefinition<any, any, any>;
+/** How the queue is to be planned, for the work this call queues - see regenerate/steer.ts. */
+export declare const GUIDANCE_PARAM: Type.TOptional<Type.TString>;
+export declare const WORKING_DIR_PARAM: Type.TOptional<Type.TString>;
+export declare const MODEL_PARAM: Type.TOptional<Type.TString>;
+export declare const STACK_PARAM: Type.TOptional<Type.TString>;
+/**
+ * Why a module asked for with no stack named cannot be built: a project of stacks where it has no stack of its own and
+ * none is chosen, and config.turri.yaml alone names no unit testing script - every pulse would stop for want of one.
+ * The stacks and the script each names, and what to do. Undefined when it can be built.
+ */
+export declare function stacklessBuild(plainFile: string): string | undefined;
+/**
+ * `work` with the stack a call names chosen for it - or, none named, as it is: each module is then built with its own
+ * (`stackForModule`). A module that could not be built that way is refused before anything is planned (`stacklessBuild`).
+ */
+export declare function withCallStack<T>(plainFile: string, named: string | undefined, work: () => T): T;
+export declare const WAIT_PARAM: Type.TOptional<Type.TBoolean>;
+/**
+ * A render tool's arguments as if turri had been started in `working_dir`: the .plain file
+ * and the build folder made absolute from there, and that folder as `base`.
+ */
+export declare function fromWorkingDir<T extends {
+    working_dir?: string;
+    plain_file?: string;
+    build_dir?: string;
+}>(cwd: string, params: T): T & {
+    base: string;
+};
+/** What the loop is doing for a spec's modules, for the conversation - and, waiting, how each module ended. */
+export declare function loopReply(loop: WorkLoop, statuses: ModuleStatus[], wait: boolean): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        jobIds: string[];
+    };
+}>;
+/** Halt a pulse by its id, or the start of it: what it was, and what moves up behind it. `reason`: why, kept with it. */
+export declare function stopJob(jobs: JobRegistry, named: string, reason?: string, loop?: WorkLoop): string;
+export interface LoopToolsOptions {
+    /** Where turri was started: the folder plain_file and working_dir are relative to. */
+    cwd: string;
+    /** The pulses `halt` stops. Without them - the release agent's - it stops only what activate started. */
+    jobs?: JobRegistry;
+    /** The work loop the tools act on - the conversation's, for a call in it. */
+    loop?: (ctx: ExtensionContext) => WorkLoop;
+    /** The model a pulse of this call regenerates on: the one named, or the one chosen for the work. Default: the one named. */
+    model?: (ctx: ExtensionContext, plainFile: string, named?: string, work?: RenderWork) => string | undefined;
+    /** Whether a call waits for its work to finish, given what it asked. Default: only when it asked to. */
+    wait?: (ctx: ExtensionContext, asked?: boolean) => boolean;
+}
+/** Whether a /regenerate's words ask for the module from scratch: its code deleted, and all of it regenerated again. */
+export declare function asksFromScratch(words: string): boolean;
+/** Whether a /regenerate asking for its module from scratch asks for its whole requires chain with it. */
+export declare function asksWholeChain(words: string): boolean;
+/** regenerate: regenerate a module's code up to its spec as it is now. */
+export declare function regenerateTool(options: LoopToolsOptions & {
+    loop: (ctx: ExtensionContext) => WorkLoop;
+}): AnyTool;
+/** drift: what is left to regenerate - planning nothing, starting nothing. */
+export declare function driftTool(options: LoopToolsOptions & {
+    loop: (ctx: ExtensionContext) => WorkLoop;
+}): AnyTool;
+/** halt: stop a pulse, or what activate started. */
+export declare function haltTool(options: Pick<LoopToolsOptions, "jobs"> & {
+    workLoop?: () => WorkLoop | undefined;
+}): AnyTool;
+export {};

package/dist/mature-tools.d.ts

@@ -0,0 +1,53 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Job, type JobRegistry } from "./regenerate/jobs.ts";
+/**
+ * The tools a skill that matures a spec works with, besides the conversation's regenerate, drift and halt: wait for
+ * the builds, and read back where the spec left the agents to decide.
+ *
+ * A render that passes can still have been built on a guess: where the spec is silent, the agent
+ * decides, and says so in the working notes' assumptions. Those, the pitfalls, a failed job's
+ * diagnosis and a spec that contradicts itself are what the spec should have said - and a skill
+ * reading them can write it in, so the next build does not have to guess.
+ */
+type AnyTool = ToolDefinition<any, any, any>;
+/** What a maturing skill found: where it came from, and what it says. */
+export interface SpecFinding {
+    id: string;
+    kind: "assumption" | "pitfall" | "diagnosis" | "conflict";
+    /** The module whose codebase it came from, or the job it came from. */
+    where: string;
+    text: string;
+}
+/** A time as the notes stamp their lines: "2026-09-28 17:40". */
+export declare function noteStamp(date: Date): string;
+/**
+ * What the agents and the harness recorded since `since`: the assumptions and pitfalls in every
+ * codebase's working notes, the diagnosis of every job that failed for good, and every spec that
+ * contradicts itself.
+ */
+export declare function collectFindings(options: {
+    project: string;
+    jobs: Job[];
+    since: Date;
+}): Omit<SpecFinding, "id">[];
+/** Why a build is struggling: a key for what kind of struggle it is - handed out once each - and what it says. */
+export interface Struggle {
+    key: string;
+    why: string;
+}
+/** How long a build may run before it counts as struggling on its length alone. */
+export declare const LONG_BUILD_MS: number;
+/**
+ * Whether a running build is struggling, and how: sent back four times or more in one loop, five
+ * setbacks or more, a spec conflict raised, a failure being run again, or running far longer than a
+ * build should. Each kind comes once per build - a round count again only every four rounds more.
+ */
+export declare function struggling(job: Job, now?: number): Struggle | undefined;
+export declare function createMatureTools(options: {
+    jobs: JobRegistry;
+    cwd: string;
+    startedAt?: Date;
+}): AnyTool[];
+/** The names of the maturing tools, as a skill's allowed-tools names them: its own - it regenerates, halts and reads drift with the conversation's (loop-tools.ts). */
+export declare const MATURE_TOOLS: string[];
+export {};