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

package/dist/config.d.ts

@@ -0,0 +1,321 @@
+/**
+ * The project's `config.turri.yaml`, at its root - the folder that holds `plain_modules` - or, before it had one, its `config.yaml`.
+ *
+ * One file for what a project says about how it is built:
+ *
+ * ```yaml
+ * module: prism_cli.plain                                   # what `turri regenerate` builds by default
+ * harness-model:                                            # the model you chat with in `turri`
+ *   model: anthropic/claude-opus-5-5
+ *   thinking: high
+ * coding-model:                                             # the rendering agents (default: harness-model)
+ *   model: google/gemini-3.1-flash
+ *   thinking: medium
+ * judge-model:                                              # the judge and the test review (default: coding-model)
+ *   model: google/gemini-3.1-pro
+ * conformance-tests: chosen                                 # all, chosen (those with acceptance tests, and those the chooser picks after each pulse), module (the chooser picks, and plans, once the module is regenerated) or false (default: false)
+ * conformance-budget: 30%                                   # under chosen or module: how many functional specs a module may have chosen, beside those with acceptance tests - a count or a share (default: no limit)
+ * review: false                                             # review the code and its tests once they pass (default: true)
+ * mutation-testing: false                                   # give the coding agent and the reviewer can_it_fail (default: true)
+ * allow-to-stop-jobs: false                                 # stop a running job the spec moved on from (default: true)
+ * release-after-pulse: true                                 # release what each pulse lands, as its last stage, before the next pulse (default: false)
+ * rules-off: [integrations]                                 # ***plain rules to leave out of the prompts, by name (default: none)
+ * unittests-script: test_scripts/run_unittests.sh           # the testing scripts - see test-scripts.ts
+ * conformance-tests-script: test_scripts/run_conformance_tests.sh
+ * prepare-environment-script: test_scripts/prepare_environment.sh  # optional: run before the conformance testing script - see test-scripts.ts
+ * testing-scripts-run-on: in-place                         # what the testing scripts run on: in-place (default), or copy - see test-scripts.ts
+ * turn-limit: 150                                           # seconds each turn of an agent a render starts has (default: 120; 0 for none)
+ * models:                                                   # each agent role's own model, thinking and turn limit - see AGENT_ROLES
+ *   default: amazon-bedrock/global.openai.gpt-6-luna         #   every role not named
+ *   coding: { model: amazon-bedrock/eu.anthropic.claude-sonnet-5, thinking: high, turn-limit: 150 }
+ *   explorer: google/gemini-3.1-flash-lite
+ * ```
+ *
+ * `models:` names a model, a thinking level and a turn limit per agent role (AGENT_ROLES), each falling back as
+ * roleModel says: a role it does not name takes `default`, and what an entry leaves out it takes from there too.
+ * `harness-model`, `coding-model` and `judge-model` are the same as `models: chat`, `coding` and `judge`, which win
+ * over them. The turn limit is the role's own, else `default`'s, else `turn-limit:`, else two minutes - the
+ * config is the only place it is set.
+ *
+ * Each model is a model reference and a thinking level (off, minimal, low, medium, high, xhigh, max),
+ * either of which may be left out; a bare string is the model alone. What a model leaves out it takes
+ * from the one it inherits: judge-model from coding-model, coding-model from harness-model. They are
+ * defaults: `--harness-model` / `--coding-model` / `--judge-model` on the command line win over them,
+ * and so does a model chosen during the conversation (pi's /model, engine). `model:` is read
+ * as `coding-model`, which it was before there were two.
+ *
+ * Keys are written with dashes; underscores are read the same (`conformance_tests`). Keys it
+ * does not know - another tool's `config.yaml`, read while it is the old file, may carry several - are ignored, and so is a value of
+ * the wrong type. Everything is optional, and what is given on the command line wins.
+ *
+ * A project whose parts do not share a stack - a Python backend and a React frontend beside each other - keeps a
+ * stack's own settings in `config.turri.<stack>.yaml` beside `config.turri.yaml`: `config.turri.backend.yaml` for the
+ * stack `backend` - its testing scripts, its toolchains. A stack is chosen, never worked out: `/stack` in the chat,
+ * `--stack <name>` (or `TURRI_STACK`) on the command line. With one chosen, everything turri builds from then on is
+ * built with `config.turri.yaml` and the stack's file over it, key by key - a model it names takes what it leaves out
+ * from the project's - and a pulse already running keeps the stack it started with. With none, `config.turri.yaml`
+ * alone. `module:` and `harness-model:` are the project's alone - there is one conversation - and are not read from a
+ * stack's file.
+ */
+/** turri's settings for a project, in a file of its own: a `config.yaml` beside it may be another tool's. */
+export declare const CONFIG_FILE = "config.turri.yaml";
+/**
+ * Where turri's settings were before they had a file of their own. A project with no `config.turri*.yaml` yet is read
+ * from it - and a `config.<name>.yaml` beside it as the stack `<name>` - and turri never writes it: the first setting
+ * turri writes copies them to the new names (`adoptLegacyConfig`), and from then on the old files are not read.
+ */
+export declare const LEGACY_CONFIG_FILE = "config.yaml";
+/** A stack's config file's name: `config.turri.backend.yaml` for the stack `backend`. */
+export declare function stackConfigFile(stack: string): string;
+/** Whether a folder's settings are still in the old files: a config.yaml or a config.<stack>.yaml, and no config.turri*.yaml. */
+export declare function usesLegacyConfig(root: string): boolean;
+/** The file the project's settings are read from, by name: config.turri.yaml, or config.yaml while the folder has only the old files. */
+export declare function projectConfigFile(root: string): string;
+/** The file a stack's settings are read from, by name - the old name while the folder has only the old files. */
+export declare function stackConfigFileIn(root: string, stack: string): string;
+/** Whether a folder holds a project's settings: a config.turri.yaml, a stack's file, or the old files. */
+export declare function hasProjectConfig(root: string): boolean;
+/** The stacks a project folder has files for, by name. */
+export declare function stacksOf(root: string): string[];
+/**
+ * Before turri first writes a setting in a folder whose settings are still in the old files: config.yaml copied to
+ * config.turri.yaml, and each config.<stack>.yaml to config.turri.<stack>.yaml, so nothing is lost when the old files
+ * stop being read. The old files are left as they are. Gives back the files written, by name.
+ */
+export declare function adoptLegacyConfig(root: string, options?: {
+    projectFile?: boolean;
+}): string[];
+/** The stack chosen now - `/stack`, `--stack`, `TURRI_STACK` - or, inside a pulse, the one it started with. */
+export declare function chosenStack(): string | undefined;
+/** Choose the stack everything is built with from now on - or none, the project's config alone. Kept in TURRI_STACK. */
+export declare function chooseStack(stack: string | undefined): void;
+/** Run `work` with `stack` as the one chosen, whatever is chosen meanwhile: a pulse keeps the stack it started with. */
+export declare function withStack<T>(stack: string | undefined, work: () => T): T;
+/** Whether a stack is pinned here - named by the call that asked for the work, or kept by the pulse it runs in. */
+export declare function stackPinned(): boolean;
+/**
+ * The stack a module is built with: the one pinned - named by the call, or kept by the pulse - else the stack named
+ * after the module, config.turri.backend.yaml for backend.plain, else the one chosen for the session; none, when none
+ * of them is.
+ */
+export declare function stackForModule(plainFile: string): string | undefined;
+/** The words that choose no stack: the project's config alone. */
+export declare const NO_STACK: string[];
+/**
+ * The stack `name` names for the project at `root` - undefined for none - refused when the project has no file for
+ * it, with the stacks it has.
+ */
+export declare function stackNamed(root: string, name: string): string | undefined;
+/** The stack a project folder is built with now: the one chosen, when the folder has a file for it. */
+export declare function stackOf(root: string): string | undefined;
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** A model, and how hard it thinks - either may be left to the one it inherits from. */
+export interface ModelChoice {
+    /** "provider/model-id". */
+    model?: string;
+    thinking?: ThinkingLevel;
+}
+/**
+ * The agents turri starts, by what they do - each can be given its own model, thinking and turn limit (`models:`).
+ * The code fixer of a conformance run and the repair agent are coding agents; the unit-test and conformance arbiters
+ * are both `arbiter`.
+ */
+export declare const AGENT_ROLES: readonly ["chat", "chooser", "planner", "diagnosis", "release", "coding", "conformance", "explorer", "reviewer", "test-reviewer", "judge", "arbiter", "debugger"];
+export type AgentRole = (typeof AGENT_ROLES)[number];
+/**
+ * How hard each role thinks when nothing names a level - not the config's `models:`, nor a `:level` on the model it is
+ * given. The agents that do the work - write the code and the tests, explore, release - think little: they work from a
+ * spec that leaves little to guess, and every turn of theirs is many. The ones that judge - review, weigh, plan, find a
+ * cause - think more: a wrong call there costs pulses. The conversation keeps its own level, pi's.
+ */
+export declare const ROLE_THINKING: Partial<Record<AgentRole, ThinkingLevel>>;
+/** A role's model and thinking, and how long each of its turns may take, in seconds - each may be left out. */
+export interface RoleChoice extends ModelChoice {
+    turnLimit?: number;
+}
+/**
+ * A model choice as the one string every agent is given, in pi's own form: "provider/id", with
+ * ":level" when it names how hard to think - ":level" alone for the default model thinking so.
+ */
+export declare function modelSpec(choice: ModelChoice | undefined): string | undefined;
+/** A model spec back into its model and thinking level - "provider/id:high", "provider/id", ":high". */
+export declare function splitModelSpec(spec: string | undefined): ModelChoice;
+/**
+ * A model spec's model alone, its thinking left behind: what a judging role falls back on when it runs on the coding
+ * model - the model, not how hard the coding agent was told to think. Its role's level (ROLE_THINKING) applies instead.
+ */
+export declare function modelOnly(spec: string | undefined): ModelChoice;
+/** A choice with what it leaves out taken from the one it inherits from - or that one, when it is not given at all. */
+export declare function inheritModel(own: ModelChoice | undefined, from: ModelChoice | undefined): ModelChoice | undefined;
+/**
+ * The three models as they hold: the judge inherits from the coding model, the coding model from the harness model -
+ * `models:` over them: `chat` over harness-model, `coding` over coding-model, `judge` over judge-model, and `default`
+ * between the harness model and the rest.
+ */
+export declare function projectModels(config: Pick<ProjectConfig, "harnessModel" | "codingModel" | "judgeModel" | "models">): {
+    harness?: ModelChoice;
+    coding?: ModelChoice;
+    judge?: ModelChoice;
+};
+/**
+ * What the config itself says a role runs on - its own entry, the legacy key that names it (judge-model for the judge
+ * and the test review), then `default` (the chat's side: the chat's model instead) - or nothing when it says nothing
+ * of it, and the role runs on what it is given: the job's model, which the command line and the conversation choose.
+ * The coding role always runs on what it is given: its config is already in it (projectModels).
+ */
+export declare function roleModel(config: Pick<ProjectConfig, "harnessModel" | "judgeModel" | "models">, role: AgentRole): ModelChoice | undefined;
+/** How long each turn of a role's agents may take, in milliseconds: its own, `default`'s, `turn-limit:`'s - or undefined, the harness's default. */
+export declare function roleTurnLimitMs(config: Pick<ProjectConfig, "models" | "turnLimit">, role: AgentRole | undefined): number | undefined;
+export interface ProjectConfig {
+    /** The .plain file the module command builds when it is given none. */
+    module?: string;
+    /** The model `turri` starts with: the one the person talks to. */
+    harnessModel?: ModelChoice;
+    /** The model the rendering agents run on - every render, conformance, repair and spec change. Unset: the harness model. */
+    codingModel?: ModelChoice;
+    /**
+     * The model of the agents that give a verdict in a conformance run - the judge, which says whether
+     * the code, the tests or the spec is wrong, and the test review. Unset: the coding model.
+     */
+    judgeModel?: ModelChoice;
+    /**
+     * Whether conformance tests are written and run, and for what. true (`all`): every functional spec the code is built
+     * from. "chosen": the ones with acceptance tests, and those the chooser picks from what each code pulse regenerated, as
+     * the pulse ends. "module": the same, but the chooser is asked once, when the whole module is regenerated - what to test,
+     * and in which pulses. Under both, those the person asks for with conform too, and a choice is kept once its tests land.
+     * false: none, unless the person asks. Unset: none, as with false.
+     */
+    conformanceTests?: boolean | "chosen" | "module";
+    /**
+     * Under `conformance-tests: chosen`: how many of a module's functional specs may be chosen for conformance tests, beside
+     * those with acceptance tests - a count, or a share of the module's functional specs (rounded up, at least one).
+     * Every choice for the module counts, whenever it was made; the person's own conform is not limited. Unset: no limit.
+     */
+    conformanceBudget?: {
+        count: number;
+    } | {
+        share: number;
+    };
+    /**
+     * Whether the code and its unit tests - and the conformance tests - are reviewed once they pass: two reviews at
+     * most, the second weighed by the arbiter. false: the work goes on once its tests pass. Unset: false.
+     */
+    review?: boolean;
+    /**
+     * Whether the coding agent and the reviewer have can_it_fail: a bug put in the code for one run of the unit tests,
+     * to see that a test catches it - on a copy, or in place and put back after. Unset: true.
+     */
+    mutationTesting?: boolean;
+    /**
+     * Whether turri stops a running job the spec has moved on from - a spec change, or a file it links edited - and
+     * regenerates the spec as it now is instead. false: the job runs to its end and lands what it was regenerating, and
+     * what changed since is regenerated on top of it by the next job: something lands as soon as it can, the software
+     * evolving job by job. The person's own halt stops a job either way. Unset: true.
+     */
+    allowToStopJobs?: boolean;
+    /**
+     * Whether every pulse that lands code releases it as its last stage, before the module's next pulse starts - an agent
+     * looking for the project's release guidance as the chat does, and doing what it says. Unset: false.
+     */
+    releaseAfterPulse?: boolean;
+    /** Path from the root to the unit testing script. */
+    unittestsScript?: string;
+    /** Path from the root to the conformance testing script. */
+    conformanceTestsScript?: string;
+    /** Run on the build before every conformance testing script run: `<script> <build folder>`. */
+    prepareEnvironmentScript?: string;
+    /**
+     * What the testing scripts run on, on this machine: the code in place (the default) - as for an integration whose
+     * scripts merge it into a host codebase - or a fresh copy of the code.
+     */
+    testingScriptsRunOn?: "copy" | "in-place";
+    /** How many jobs run at once in the chat - modules that share nothing build side by side up to it. Unset: from the machine's memory. */
+    parallelJobs?: number;
+    /**
+     * The ***plain authoring rules (genome/rules/<name>.md) left out of the conversation's prompt and every spec-writing
+     * agent's, by name: a rule a project's own skills or AGENTS.md replace. The project's alone.
+     */
+    rulesOff?: string[];
+    /**
+     * Tokens of conversation - what an agent has done, past its instructions - after which an agent that keeps its
+     * session through a job is compacted between turns. The project's alone. Unset: 100k.
+     */
+    compactAt?: number;
+    /** The most functional specs the planner puts in one pulse. Unset: 3. A stack's file wins. */
+    maxSpecsPerPulse?: number;
+    /** The most lines of spec - its functional specs and the definitions they bring - in one pulse; past it, split. Unset: 120. */
+    maxLinesPerPulse?: number;
+    /**
+     * What passes through to the agents' commands beside the scrubbed environment: every variable of the dotenv `files`
+     * (paths from the project root), and the `vars` named, from the environment turri was started in. A module's own are
+     * added to the project's.
+     */
+    agentEnv?: {
+        files: string[];
+        vars: string[];
+    };
+    /**
+     * Folders of this machine an agent's commands may read beside the system's and the toolchains turri finds itself: a
+     * toolchain installed somewhere unusual. A module's own are added to the project's.
+     */
+    toolchains?: string[];
+    /** Each agent role's own model, thinking and turn limit; `default` for every role not named. */
+    models?: Partial<Record<AgentRole | "default", RoleChoice>>;
+    /** Seconds each turn of an agent a render starts has, for every role without its own. Unset: 120. 0: none. */
+    turnLimit?: number;
+}
+/** The config keys, as written in the file. */
+export declare const CONFIG_KEYS: {
+    readonly module: "module";
+    readonly harnessModel: "harness-model";
+    readonly codingModel: "coding-model";
+    readonly judgeModel: "judge-model";
+    readonly conformanceTests: "conformance-tests";
+    readonly conformanceBudget: "conformance-budget";
+    readonly review: "review";
+    readonly mutationTesting: "mutation-testing";
+    readonly allowToStopJobs: "allow-to-stop-jobs";
+    readonly releaseAfterPulse: "release-after-pulse";
+    readonly unittestsScript: "unittests-script";
+    readonly conformanceTestsScript: "conformance-tests-script";
+    readonly prepareEnvironmentScript: "prepare-environment-script";
+    readonly testingScriptsRunOn: "testing-scripts-run-on";
+    readonly parallelJobs: "parallel-jobs";
+    readonly rulesOff: "rules-off";
+    readonly compactAt: "compact-at";
+    readonly maxSpecsPerPulse: "max-specs-per-pulse";
+    readonly maxLinesPerPulse: "max-lines-per-pulse";
+    readonly agentEnv: "agent-env";
+    readonly toolchains: "toolchains";
+    readonly models: "models";
+    readonly turnLimit: "turn-limit";
+};
+/** Whether `conformance-tests:` turns the conformance tests on: all (true), chosen or module. Not set, they are off, as with false. */
+export declare function conformanceSwitchedOn(setting: ProjectConfig["conformanceTests"]): boolean;
+/** When the chooser decides which functional specs get conformance tests: after each code pulse, once the module is regenerated, or never - every one, or none. */
+export declare function choosingWhen(setting: ProjectConfig["conformanceTests"]): "pulse" | "module" | undefined;
+/** How many functional specs a module of `count` may have chosen under a budget: the count, or the share rounded up - at least one. */
+export declare function budgetFor(budget: NonNullable<ProjectConfig["conformanceBudget"]>, count: number): number;
+/**
+ * The project's config - with a stack's over it, when one is named - or nothing of it when there is no file or it does
+ * not parse.
+ */
+export declare function readProjectConfig(root: string, stack?: string): ProjectConfig;
+/**
+ * What a command's own options say of the config's keys - `turri regenerate --harness-model`, `--coding-model`,
+ * `--judge-model`, `--conformance-tests`, `--review`, `--mutation-testing` - read as if the file had them: each takes its key's value, and
+ * every key keeps its place in the order, so a run is the same as one with them in config.turri.yaml - a `models:`
+ * entry still winning over `harness-model`, `coding-model` or `judge-model`. A headless run needs no config file
+ * edited. Never set in the conversation.
+ */
+type RunOverrides = Partial<Pick<ProjectConfig, "harnessModel" | "codingModel" | "judgeModel" | "conformanceTests" | "review" | "mutationTesting">>;
+/** Read a command's options as the config's keys for the rest of this process. */
+export declare function overrideConfig(overrides: RunOverrides): void;
+/** `--conformance-tests <value>`: the config's own values - all (or true), chosen, module, false. Undefined for anything else. */
+export declare function conformanceOption(value: string): ProjectConfig["conformanceTests"] | undefined;
+/** `--review <value>`, `--mutation-testing <value>`: the config's own, true or false. Undefined for anything else. */
+export declare function booleanOption(value: string): boolean | undefined;
+/** The config a spec is built with: its project's, with its module's stack over it (`stackForModule`). */
+export declare function configForSpec(plainFile: string): ProjectConfig;
+export {};

package/dist/conform-cli.d.ts

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

package/dist/cultivate-cli.d.ts

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

package/dist/drift-cli.d.ts

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

package/dist/environment.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What turri needs from the machine it runs on, found out without changing anything.
+ *
+ * Kept free of heavy imports so the CLI can ask these questions before it has loaded pi - and so `turri doctor` can report a missing piece instead of crashing on it.
+ */
+export declare const PACKAGE_ROOT: string;
+export declare const AGENT_DIR: string;
+/** The oldest Node that runs .ts files by itself, which is how turri runs. */
+export declare const MIN_NODE: readonly [22, 19];
+export declare function nodeVersionOk(version?: string): boolean;
+/** Whether a command runs at all. */
+export declare function runs(command: string, args?: string[]): boolean;
+/** The global pi extension file that loads turri into every `pi`, if there is one. */
+export declare function globalExtensionFile(): string | undefined;
+export declare function extensionInstalledGlobally(): boolean;
+export declare function themeFiles(): string[];
+/**
+ * Are this project's themes already installed globally?
+ *
+ * Passing --theme as well would make pi load each of them twice and report a collision
+ * on startup - the global copy wins and the project copy is skipped, which is noise
+ * about a duplicate we created ourselves.
+ */
+export declare function themesInstalledGlobally(): boolean;
+/** Where `turri` on the PATH points, if it is on the PATH at all. */
+export declare function turriOnPath(): string | undefined;
+/** The version of the pi turri runs on, as Node finds it - undefined when it is not installed. */
+export declare function piVersion(): string | undefined;
+/**
+ * What `turri --version` prints: turri's version - from a clone, its commit too, as the banner says it - and pi's
+ * beside it. pi's own `--version` says only pi's, which read as turri's.
+ */
+export declare function versionLine(identity?: ReturnType<typeof turriIdentity>, pi?: string | null): string;
+/** turri's version, and the commit when it runs from a clone. */
+export declare function turriIdentity(): {
+    version: string | null;
+    git_commit: string | null;
+    git_dirty: boolean | null;
+};

package/dist/extension.d.ts

@@ -0,0 +1,147 @@
+import "./terminal-images.ts";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { stackOnMachine } from "./stack.ts";
+import { createAskUserTool } from "./tools.ts";
+import { fromWorkingDir } from "./loop-tools.ts";
+import { type WorkLoop } from "./regenerate/loop.ts";
+import { type AskUser, type AskUserIO } from "./ask.ts";
+import { type Job, type JobRegistry } from "./regenerate/jobs.ts";
+/**
+ * Puts a skill step's question to the person, when there is one to ask.
+ *
+ * A skill runs inside one tool call, in its own session, so its dialogs are not
+ * conversation turns and nothing it asks would otherwise reach the transcript. Every
+ * exchange is therefore reported back, so the interview is visible while it happens and
+ * survives in the tool's result afterwards.
+ */
+export declare function askUserVia(ctx: ExtensionContext, onExchange: (question: string, answer: string, said?: string) => void, 
+/** Given, "/btw ..." typed as an answer is a side question: answered with this, and the question asked again. */
+aside?: (question: string) => Promise<string>, 
+/** A host's own dialogs (TurriHost.dialogs), the question put in them instead of the terminal's. */
+dialogs?: AskUserIO): AskUser;
+/**
+ * ask_user, for the conversation's agent too - the same dialog a skill's interview uses: options to
+ * 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 declare function chatAskUserTool(dialogs?: AskUserIO): ReturnType<typeof createAskUserTool>;
+/**
+ * What a host that runs turri's conversation itself - a desktop app, an editor - is told and asked, where the terminal
+ * would draw: the conversation's jobs and its work loop as they are made and as they change, and the dialogs its
+ * questions are put to the person in. A host gives the extension `createTurriExtension(host)`; `turri` gives it none.
+ */
+export interface TurriHost {
+    /** The conversation's job registry, as the extension makes it: every pulse the conversation starts is in it. */
+    onJobs?(jobs: JobRegistry): void;
+    /** The conversation's work loop, once work is first asked for: what each codebase has planned, and why. */
+    onWorkLoop?(loop: WorkLoop): void;
+    /** A job started, moved to another stage, did something, or ended. */
+    onJobChange?(job: Job): void;
+    /** What is planned changed with no job - a module being planned, or planned. */
+    onPlanChange?(): void;
+    /** The dialogs ask_user puts its questions in - the conversation's and a skill's interview - instead of the terminal's. */
+    dialogs?: AskUserIO;
+}
+/** turri's conversation as an extension of pi's, for a host that runs it itself: see TurriHost. */
+export declare function createTurriExtension(host?: TurriHost): (pi: ExtensionAPI) => void;
+declare const _default: (pi: ExtensionAPI) => void;
+export default _default;
+/**
+ * What a slash command showed the person: kept in the chat, where they read it, and put in the conversation as well -
+ * unseen there - so that when they speak of it next ("fix it"), the agent knows what they saw. A command runs outside
+ * the agent's turns, and a notification is gone in seconds and reaches no model.
+ */
+export declare function shownAfterCommand(pi: ExtensionAPI, ctx: ExtensionContext, command: string, text: string, level: NonNullable<CommandOutcome["level"]>, 
+/** The command is in the chat already, above it (echoCommand): the text alone. */
+echoed?: boolean): void;
+export declare const COMMAND_OUTCOME = "turri_command_outcome";
+interface CommandOutcome {
+    command: string;
+    /** None: the command itself, as the person typed it. */
+    text?: string;
+    level?: "info" | "warning" | "error";
+    echoed?: boolean;
+}
+/**
+ * What the person typed, put in the chat the moment they send it - before the command does anything - and drawn before
+ * it goes on: a command's work can hold the event loop (a long requires chain parsed), and the chat stays as it was
+ * until it lets go. What the command says comes under it.
+ */
+export declare function echoCommand(pi: ExtensionAPI, command: string): Promise<void>;
+/** Until the TUI has drawn what was just put in the chat. */
+export declare const nextFrame: () => Promise<void>;
+/**
+ * The module a /regenerate's first words name, and the words after it - all of them when none is named. A name typed
+ * with spaces for its underscores - "d365_function executor" - is the module d365_function_executor: the most words
+ * that name one win.
+ */
+export declare function moduleNamedFirst(cwd: string, words: string[]): {
+    named?: string;
+    rest: string[];
+};
+/**
+ * How many jobs the chat runs at once: `parallel-jobs:` in the session folder's config.turri.yaml - the only place it
+ * is set - else half this machine's cores, between one and four.
+ */
+export declare function parallelJobs(cwd: string): number;
+/** The project's own files and a digest of each - not plain_modules, dependencies, or turri's and git's folders. */
+export declare function projectFiles(root: string): Map<string, string>;
+/** The files added, changed or removed between two digests of the project. */
+export declare function changedFiles(before: Map<string, string>, after: Map<string, string>): string[];
+/**
+ * This machine, for the chat's agent, read afresh every turn: which wall is up under the agents' commands, whether the
+ * machine has the toolchains the project's modules name, and what in its testing scripts it lacks - for the person to
+ * install or fix; the agents install nothing. `modules`: what the modules need, when it is known already - working it
+ * out parses every spec of the project.
+ */
+export declare function machineBlock(cwd: string, modules?: ReturnType<typeof stackOnMachine>): string;
+/**
+ * What the project's modules need of this machine, kept between turns - working it out parses every spec, seconds on a
+ * project of long requires chains, and a message is never kept waiting for it. Worked out once the chat is up, and again
+ * when a turn has settled and a spec changed since: a turn is told what was known last, at most a turn behind.
+ */
+export declare function machineNeeds(cwd: string, work?: (cwd: string) => ReturnType<typeof stackOnMachine>): {
+    /** What is known - worked out now only when nothing is yet. */
+    now(): ReturnType<typeof stackOnMachine>;
+    /** Worked out again, if a spec changed - once the chat has drawn what it is drawing. */
+    refreshSoon(): void;
+};
+/**
+ * The project's config.turri.yaml, for the chat's agent: what it says, and what that means for the
+ * tools - so a question about the project's settings is answered from the file, not from the
+ * tools' defaults.
+ */
+export declare function projectConfigBlock(root: string): string;
+export { fromWorkingDir };
+/**
+ * What the agent is to do with a job that just ended, unasked: what the project's guidance says to do then, or else say
+ * in a line or two what ended - the person saw it end already, in the transcript.
+ */
+export declare const JOB_FINISHED_REACTION: string;
+/**
+ * A skill's question as the transcript keeps it: who asked, what it said before asking - a brief to confirm, the choices
+ * it weighed, shown in the dialog that is gone once answered - the question, and the answer.
+ */
+export declare function exchangeLines(data: Exchange, fg: (color: "muted" | "text" | "dim" | "accent", text: string) => string): string[];
+export interface Exchange {
+    skill: string;
+    /** What the skill's agent said before asking - a brief to confirm, the choices it weighed: shown in the dialog, kept here. */
+    said?: string;
+    question: string;
+    answer: string;
+}
+/**
+ * The name on the door.
+ *
+ * Pi's own startup header is a built-in component an extension cannot replace, so this
+ * adds a wordmark of its own at the top of the session. `turri` starts pi without
+ * its header (see pi-launch.ts), leaving only this one.
+ */
+/**
+ * The ***plain rules as the conversation has them in its system prompt, every turn - the standard library's
+ * inventory among them, in its rule, so the conversation knows what a spec can import from the start.
+ */
+export declare function chatRulesBlock(rules?: {
+    name: string;
+    content: string;
+}[]): string;

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())