@turri-dev/cli 0.1.3-next.04c4f71 → 0.1.3-next.162a2c3

package/dist/regenerate-cli.js

@@ -19,7 +19,7 @@ its conformance tests too when they are on.
   --start-over             start over, without asking, a codebase regenerated without a module it now requires -
                            with no terminal to ask and without it, the run stops there
   --from-scratch           delete the module's code and conformance tests (its lineage keeps them) and regenerate all of it
-  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner, the conformance chooser, a diagnosis
+  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner and the conformance chooser
   --coding-model <p/id>    its coding-model, --model too: the agents that build; p/id:level for how hard a model thinks
   --judge-model <p/id>     its judge-model: the judge and the test review
   --review <true|false>    its review: whether the code and its tests are reviewed once they pass

package/dist/resume-line.js

@@ -0,0 +1,4 @@
+/** 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 function resumeLine(text) {
+    return text.replace(/^((?:\x1b\[[0-9;]*m)*To resume this session:(?:\x1b\[[0-9;]*m)*\s+)pi(?= )/m, "$1turri");
+}

package/dist/spec-tools.js

@@ -1,8 +1,8 @@
-import { readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, relative, resolve } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { IMPORT_DIRECTIVE, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata } from "./plain/parser.js";
+import { plainFileParser } from "./plain/parser.js";
+import { importingModules, isImportModule } from "./regenerate/requires.js";
 import { resolveTemplateDirs } from "./regenerate/paths.js";
 import { applySpecDiff, plainFilesOf, revertSpecDiff } from "./regenerate/regenerate.js";
 import { MissingFunctionalitiesError } from "./plain/errors.js";
@@ -62,24 +62,12 @@ export function createSpecDiffTools(options) {
             // file that cannot be parsed. A module with no functional specs yet is not broken. An import
             // module - definitions only, say - is not a module of its own: it is parsed as the modules
             // that import it read it, the one the change is built for among them.
-            const importers = (file) => {
-                const name = basename(file, ".plain");
-                const dir = dirname(resolve(cwd, file));
-                return readdirSync(dir)
-                    .filter((entry) => entry.endsWith(".plain"))
-                    .map((entry) => join(dir, entry))
-                    .filter((path) => {
-                    try {
-                        return (readPlainSourceMetadata(readFileSync(path, "utf8")).metadata[IMPORT_DIRECTIVE] ?? []).includes(name);
-                    }
-                    catch {
-                        return false;
-                    }
-                });
-            };
-            const imported = importedNames(resolveTemplateDirs(resolve(cwd, params.plain_file)));
             const toParse = [
-                ...new Set([params.plain_file, ...touched].flatMap((file) => imported.has(basename(file, ".plain")) ? importers(file).filter((path) => !imported.has(basename(path, ".plain"))) : [resolve(cwd, file)])),
+                ...new Set([params.plain_file, ...touched].flatMap((file) => {
+                    const path = resolve(cwd, file);
+                    const importing = isImportModule(path) ? importingModules(path) : [];
+                    return importing.length > 0 ? importing : [path];
+                })),
             ];
             for (const path of toParse) {
                 const file = relative(cwd, path);
@@ -129,27 +117,3 @@ export function createSpecDiffTools(options) {
         },
     };
 }
-/** The module names some .plain file in these folders imports: import modules, not codebases. */
-export function importedNames(dirs) {
-    const names = new Set();
-    for (const dir of dirs) {
-        let entries;
-        try {
-            entries = readdirSync(dir).filter((name) => name.endsWith(PLAIN_SOURCE_FILE_EXTENSION));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            try {
-                const imports = readPlainSourceMetadata(readFileSync(join(dir, entry), "utf8")).metadata[IMPORT_DIRECTIVE];
-                for (const name of imports ?? [])
-                    names.add(name);
-            }
-            catch {
-                // A file that does not read imports nothing.
-            }
-        }
-    }
-    return names;
-}

package/docs/config.md

@@ -122,7 +122,7 @@ models:                              # each agent role's model, thinking and tur
 | key | what it sets | left out |
 | --- | --- | --- |
 | `module` | the `.plain` file `turri regenerate` and the chat's `regenerate` build when none is named, from the project root | a file has to be named |
-| `harness-model` | the model `turri` starts on - the one you talk to - the one that diagnoses a job that failed for good, and, in the conversation, the planner that cuts the work into jobs (on whatever model the chat is on when it plans); under `turri regenerate`, the planner too | pi's configured model |
+| `harness-model` | the model `turri` starts on - the one you talk to - and, in the conversation, the planner that cuts the work into jobs (on whatever model the chat is on when it plans); under `turri regenerate`, the planner too | pi's configured model |
 | `coding-model` | every render: functionalities, spec diffs, conformance tests, repairs, planning spec diffs, the explorer | `harness-model` |
 | `judge-model` | the judge and the test review of a conformance run | `coding-model` |
 | `conformance-tests` | `all` (or `true`): conformance tests for every functional spec of every module with test reqs, written once each module's code is built, before anything is built on it. `chosen`: for the functional specs chosen - every one with acceptance tests, and those the chooser picks as each code pulse ends, from what that pulse regenerated. `module`: the same, but the chooser is asked once, when the whole module is regenerated, and plans the conformance pulses too. Under both, the choice is made inside the pulse, before anything is built on the module, and the pulse's report says what was chosen and why; those the person asks for with `conform` are written too; once chosen, a functional spec keeps them, and they are rewritten when it changes - see [who chooses, and when](regenerating.md#conformance-tests-in-the-work-loop). `false`: none written, and none of the existing ones run - until the conversation asks with `conform` | `false` |
@@ -158,7 +158,8 @@ wrong type, as if it were not there. `model:`, from before there were separate m
 | --- | --- |
 | `default` | every role not named below - but the conversation's side |
 | `chat` | `turri`'s model - the same as `harness-model`, which it wins over |
-| `chooser`, `planner`, `diagnosis` | the conversation's side: the conformance chooser of `turri regenerate`, the planner's agents, the diagnosis of a failed job. Unnamed, the chat's model |
+| `chooser`, `planner` | the conversation's side: the conformance chooser of `turri regenerate`, the planner's agents. Unnamed, the chat's model |
+| `diagnosis` | the diagnosis of a job that failed for good: why it did not land, and what to do. Unnamed, the coding model the job ran on, thinking medium |
 | `release` | `turri release`'s agent and release-after-pulse's: it follows steps - a script, a start command - so it runs on the coding model, thinking low |
 | `coding` | the coding agent, the code fixer of a conformance run and the repair agent - the same as `coding-model`, which it wins over. `--model` on the command line, or a model chosen in the conversation (`engine`), wins over both |
 | `conformance` | the conformance agent |

package/docs/headless.md

@@ -81,7 +81,7 @@ Useful options - `turri regenerate --help` lists all of them:
 
 | | |
 | --- | --- |
-| `--harness-model <provider/id>` | `harness-model`: the planner, the conformance chooser, the diagnosis of a failed pulse |
+| `--harness-model <provider/id>` | `harness-model`: the planner and the conformance chooser |
 | `--coding-model <provider/id>` | `coding-model` (`--model` too): the agents that build - with `:level` for how hard it thinks (`provider/id:high`); not given, the harness model's |
 | `--judge-model <provider/id>` | `judge-model`: the judge and the test review; not given, the coding model |
 | `--conformance-tests <all\|chosen\|module\|false>` | `conformance-tests`, with its values (`true` is `all`) |
@@ -151,7 +151,7 @@ changes meaning or goes; new fields may appear in the same version. Paths in `pu
   "conformance_tests": "all",                                                       // all | chosen | module | false
   "review": false,
   "models": {
-    "harness": { "model": "…", "thinking": "medium" },  // the planner, the chooser, the diagnosis
+    "harness": { "model": "…", "thinking": "medium" },  // the planner, the chooser
     "coding":  { "model": "…", "thinking": "low" },
     "judge":   { "model": "…", "thinking": "medium" },
     "observed": { "coding": ["provider/id:low"], "planner": ["provider/id:medium"] }  // what each role really ran on

package/docs/regenerating.md

@@ -112,6 +112,10 @@ the planner's, the spec-steps agent's, the conformance agents' - is laid out in
 A module that `requires` another inherits its functional specs; one that `import`s another
 inherits its definitions, implementation reqs and test reqs.
 
+An import module - one a `.plain` file imports, or one kept in a `template/` folder - is no codebase of its own. A
+change to it is built in the modules that import it, through any import modules between, whose code is started; when
+none is, nothing is built, and the change goes in with the first of them built.
+
 Template search order: the plain file's own directory, then a sibling `template/`, then
 `--template-dir`, then `PLAIN_TEMPLATE_DIRS`.
 
@@ -160,6 +164,10 @@ runs the unit testing script itself**, and only that run counts (see
   tried. An agent circles a cause it has not thought of - an in-memory database every connection opens
   empty, a test runner that leaves the code off its path - and this is the way out. The rounds go on as
   before, up to 20; should the same failure come round three times again, the debugger looks again.
+  **A run the time limit stopped** is looked at by the debugger at once, told how long the run had and that the limit
+  stopped it: it finds what hangs - the root cause and the fix, as above - or that nothing does, the run getting on up
+  to the limit and needing more time than a test run may take. Then the pulse stops, rolled back and not retried, and
+  the person is told to raise `TURRI_COMMAND_TIMEOUT` or make the suite faster.
 - **It goes round in circles in its own runs.** An agent stuck on a failure can try the same few changes in
   turn - three signatures of a stand-in function, say - and run the tests after each, dozens of times in one
   turn. Its own `run_unit_tests` runs are watched (`createLoopWatch` in `test-scripts.ts`): the code folder back
@@ -262,7 +270,8 @@ Passing unit tests prove only what they check, and a coding agent is quick to wr
 next to nothing - that a function exists, that a result is not empty, that a status is 200 - or code
 that no test reaches. So, with `review: true` in the [config](config.md), once the unit testing script
 passes a reviewer on the judge model reads what the work wrote, beside the spec, and changes nothing. It
-reviews both halves. The review is off by default - `review: false`, or the key left out - and so is the
+reviews both halves, with the unit testing script word for word in its prompt: a test the script never reaches is
+not run, and checks nothing. The review is off by default - `review: false`, or the key left out - and so is the
 conformance tests' review: the work goes on once its tests pass.
 
 - **The code.** Every behaviour, edge case, validation rule and error the spec states for this work
@@ -499,8 +508,9 @@ testing script, stops before it starts and says which skill adds it.
 `prepare-environment-script:` in the config, else the one `prepare_environment*.sh` at the root, else in
 `test_scripts/` - on the build, before every run of the conformance testing script: the harness's own, and the agents'
 `run_conformance_tests`. Both get the same build folder - the code in place, or the same fresh copy - so what it sets up
-for that build, the conformance testing script finds. With conformance off it is not run. The conformance agents are
-shown it, before the conformance testing script.
+for that build, the conformance testing script finds. With conformance off it is not run. Every agent shown the
+conformance testing script - the explorer, the conformance agent, the judge, the code fixer and the repair agent - is
+shown it too, before the conformance testing script.
 
 **Where they run.** On this machine, as you would run them: unfenced - no sandbox, no command check, no audit - in
 your own environment with this machine's toolchains, turri's model providers' API keys alone left out. They are yours,
@@ -832,7 +842,8 @@ coding agent that fixes the code is told the same of the tests: it can read them
 Before the test author starts, an explorer - an agent in
 the code's folder with the file tools alone: it reads the code, runs nothing and changes nothing - hands over everything
 the author needs, in parts: how to build and run it; how the conformance tests reach it as the project's
-conformance testing script runs them - the explorer is given the script, and says what it builds or
+conformance testing script runs them - the explorer is given the script, and the prepare script before it where there
+is one, and says what they build or
 installs and what the tests depend on or start (a package, a module, an entry point, by its exact name);
 how each functionality is reached from outside
 (the command, or the route, method and the request and response fields); what it needs around it; and
@@ -906,10 +917,17 @@ agent is told that a failure of the software itself - it does not build or start
 spec says it must not - is not the tests' to work around. When it fails, a judge - an agent that reads
 the code and the tests, changes neither, and holds both to the spec - decides which is wrong. It has the
 file tools and the web (`web_search`, `web_fetch`), to look up what a service the code calls answers - no shell: it
-judges from the code, the tests, the spec and the failing run's output, and its file tools write nothing:
+judges from the code, the tests, the spec, the conformance testing script word for word and the failing run's output,
+and its file tools write nothing. The explorer's account of how the code is invoked is in its prompt too, marked as
+written before the run and possibly wrong: the judge checks what it uses of it against the script and the files, and
+gives in `evidence` what it found itself. The script is fixed - neither agent can change it - so it is never the
+culprit: what it does with the tests, the tests fit; what it needs of the build, the code provides.
 
 - **the code:** the coding agent - in the code's folder, reading the tests but never changing them - fixes it,
-  and keeps its unit tests passing;
+  and keeps its unit tests passing. The judge quotes the spec's own words the code does not meet, or the testing
+  script's for what it needs of the build (`script_needs`: a build output, an entry point, a module) - each checked
+  by the harness against the text it quotes. The acceptance tests are in that text, labelled as their tests are:
+  for a spec change, those of every functional spec it touches, not only the last one's;
 - **the tests:** the conformance agent corrects them to what the spec says;
 - **the spec:** two functional specs cannot both hold, whatever the code does;
 - **the environment:** neither the code nor the tests can fix it - only the person can, in what the run is given:
@@ -951,16 +969,41 @@ spending the rest of its 20 attempts on it. Two failures are the same once what
 taken out of their lines - numbers, times, paths, colour codes, and the ids a service makes up for each
 response, a UUID or a correlation id. Nothing changes either when the agent sent to fix the code or the tests
 changes no file: two such fixes in a row, and the run stops. The conformance agent has the testing script in its prompt,
-and is told to fit the tests' own build to it.
+and is told to fit the tests' own build to it. The code fixer has the testing scripts its fixes are run by - the
+conformance testing script, the prepare script before it, and the unit testing script - word for word in its task:
+what the conformance testing script needs of the build, it reads there, not only in the judge's quote of it.
+
+**Escalation.** A failure judged the tests' goes to the conformance agent first: it owns the tests. When the run then
+fails the same way - the fix changed nothing, or nothing that mattered - the judge is asked again, now whether the
+failure belongs to the code rather than the tests: the run failing on something the code is meant to produce (a build
+output, an entry point, a module the testing script needs), or the tests running and the behaviour itself being
+wrong. Its verdict, either way, has to rest on evidence it gathered: each piece from a file it opened (the harness
+keeps track of what it read, listed and searched), the testing script or the failing run - and not the run alone.
+A verdict without it is sent back; a verdict of code still without it is taken as the tests'. Judged the tests'
+again, the failure stays with the conformance agent, and a fix that changes nothing counts towards stopping as
+before. Judged the code's, it is escalated to the coding agent, handed the script's error, the conformance tests as
+they stand and the judge's reason and evidence (`the script runs dist/cli.js; the build emits dist/src/cli.js`). Its
+fix has to build and pass the unit tests, then the suite runs again. Should the run still fail the same way - or the
+fix change nothing - the run stops there, with the judge's reasoning and evidence in what the person is told. Each of
+these runs is one of the run's 20 attempts, so a failure neither agent can fix stops in three of them.
 
 Every attempt is written into the working notes' pitfalls by the harness as cause and effect - what
 the run failed with, how it was judged, and which files the agent sent to fix it changed; the next
 attempt's line says what came of it - and each judge reads them first, so it does not send a
 failure the way that already failed. A run that does not pass is undone whole, its notes with it.
 
-Then the suite runs again. A run stopped by its time limit goes back to the conformance agent without a judge: the
-tests' environment is its. So does a run that exits 80 - the tests pass and only their static checks do not (see
-[the static checks](#the-static-checks)): the findings are the tests'. A run whose script cannot find its
+Then the suite runs again. A run that exits 80 goes back to the conformance agent without a judge - the tests pass and
+only their static checks do not (see [the static checks](#the-static-checks)): the findings are the tests'.
+
+**Timing.** Every run is shown to the judge, the debugger and whoever fixes it with how long it ran against its time
+limit (`runTiming` in `test-scripts.ts`): `This run ended on its own - exit 1, after 37.2s of the 120.0s a test run
+may take`, or `The time limit stopped this run: it had run 120.0s of the 120.0s ...` - so none takes a run that
+ended on its own for one the limit stopped, or the other way. A run the time limit stopped is judged like any other,
+and the judge is told what keeps a run from finishing: the code hangs (it waits on input, keeps a server in the
+foreground, never exits) - the code's; a test waits for what never comes - the tests'; or nothing hangs, the output
+showing the run getting on up to the limit, and it needs more time than a test run may take - the environment. That
+verdict stops the pulse at once, rolled back and not retried, and the person is told to raise `TURRI_COMMAND_TIMEOUT`
+or make the suite faster - no agent can give a run more time. A run whose script cannot find its
 toolchain stops the pulse instead - see [when the environment lacks something](#when-the-environment-lacks-something).
 Unit tests failing after the suite passes go to the coding agent. It goes round up to 20 times; still failing, the work is undone.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.3-next.04c4f71",
+  "version": "0.1.3-next.162a2c3",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -33,8 +33,8 @@
     "grammar:sync": "node scripts/sync-plyn-grammar.mjs"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "^1.1.0",
-    "@earendil-works/pi-tui": "^1.1.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0",
     "@langchain/langgraph": "1.4.15",
     "gray-matter": "^4.0.3",
     "js-yaml": "^5.4.2",