@turri-dev/cli 0.1.3 → 0.1.4-next.318a98a

package/README.md

@@ -27,7 +27,7 @@ npm install -g @turri-dev/cli # puts `turri` on your PATH
 turri doctor              # checks the machine
 ```
 
-To work on turri itself, run it from a clone instead - see [installation](docs/installation.md#from-a-clone).
+To follow `main` as it moves, or work on turri itself, run it [from a clone](#from-a-clone) instead.
 
 `doctor` checks for Node 22.19+, bash, the OS sandbox and a model provider for pi; in a project, the toolchains its
 modules need, what its testing scripts run against this machine, and that each model `config.turri.yaml` names
@@ -73,6 +73,27 @@ Rather not install Node and the rest? **turri** also runs in Docker, from one im
 
 Choosing models: [models](#models); what to do next: [use](#use).
 
+### From a clone
+
+In place of the npm package - for the latest of `main`, or to change turri itself:
+
+```bash
+git clone git@github.com:turri-oss/turri.git && cd turri
+npm install
+npm link        # puts `turri` on your PATH, pointing at this clone
+turri doctor
+```
+
+The clone runs its TypeScript sources directly, so there is nothing to build. When new commits land:
+
+```bash
+git pull
+npm install     # picks up any dependency that changed
+```
+
+A **turri** already running keeps the code it started with - start it again to run what you pulled. More in
+[installation](docs/installation.md#from-a-clone).
+
 ## Why
 
 In the age of coding agents, writing code is getting easy. The hard and important part is

package/dist/extension.js

@@ -548,7 +548,7 @@ export default function (pi) {
                 loopTools: [
                     regenerateTool({ cwd, jobs, loop: () => workLoopFor(jobs, cwd, ctx), model: (_skill, plainFile, named, work) => jobModel(ctx, work ?? "spec_changes", named, plainFile), wait: () => false }),
                     driftTool({ cwd, jobs, loop: () => workLoopFor(jobs, cwd, ctx) }),
-                    haltTool({ jobs }),
+                    haltTool({ jobs, workLoop: () => workLoops.get(jobs)?.loop }),
                     conformTool({ cwd, loop: () => workLoopFor(jobs, cwd, ctx), model: (_skill, plainFile, named) => jobModel(ctx, "spec_changes", named, plainFile), wait: () => false }),
                 ],
                 // The escalation becomes a real dialog in the TUI. Without dialog-capable
@@ -1419,25 +1419,37 @@ function registerJobTools(pi, jobs, cwd) {
     // The panel is compact and ctrl+o only lasts as long as the work does. This is the whole
     // list, finished jobs included, put in the transcript where it stays.
     pi.registerCommand("halt", {
-        description: "Halt a queued or running pulse, or what activate started: /halt [pulse id | activated <name>]",
+        description: "Halt a queued or running pulse, a module's planned pulses, or what activate started: /halt [pulse id | module | activated <name>]",
         handler: async (args, ctx) => {
             if (!ctx.hasUI)
                 return;
             const live = jobs.list().filter((job) => job.status === "running" || job.status === "queued");
             const deployed = runningDeployed();
+            const loop = workLoops.get(jobs)?.loop;
+            // A module's planned pulses, one line a module: halting one halts the module.
+            const plannedRows = loop?.planned() ?? [];
+            const planned = [...new Set(plannedRows.map((row) => row.module ?? ""))].filter((module) => module !== "");
             let id = args.trim();
             if (id === "") {
-                if (live.length === 0 && deployed.length === 0)
-                    return ctx.ui.notify("Nothing is regenerating or queued.", "info");
+                if (live.length === 0 && deployed.length === 0 && planned.length === 0)
+                    return ctx.ui.notify("Nothing is regenerating, queued or planned.", "info");
                 const label = (job) => `${job.id}  ${job.status.padEnd(8)} ${pulseName(job)}`;
-                const labels = [...live.map(label), ...deployed.map((item) => deployedLabel(item.name, item.url ?? item.command))];
+                const plannedLabel = (module) => {
+                    const rows = plannedRows.filter((row) => row.module === module);
+                    const waiting = rows.find((row) => row.id.endsWith("-waiting"));
+                    return `${module}  ${waiting !== undefined ? waiting.summary : `${rows.length} planned`} - halts the module`;
+                };
+                const labels = [...live.map(label), ...planned.map(plannedLabel), ...deployed.map((item) => deployedLabel(item.name, item.url ?? item.command))];
                 const picked = await ctx.ui.select("Halt which?", labels);
                 const job = live.find((candidate) => picked !== undefined && label(candidate) === picked);
+                const module = planned.find((name) => picked !== undefined && plannedLabel(name) === picked);
                 const server = deployed.find((item) => picked !== undefined && deployedLabel(item.name, item.url ?? item.command) === picked);
                 if (server !== undefined)
                     id = `activated ${server.name}`;
                 else if (job !== undefined)
                     id = job.id;
+                else if (module !== undefined)
+                    id = module;
                 else
                     return;
             }
@@ -1446,7 +1458,7 @@ function registerJobTools(pi, jobs, cwd) {
                 const stopped = await stopDeployed({ name });
                 return shownAfterCommand(pi, ctx, `/halt ${id}`, stopped.length > 0 ? `Halted ${stopped.join(", ")}.` : `Nothing activate started is running as ${name}.`, "info");
             }
-            ctx.ui.notify(stopJob(jobs, id), "info");
+            ctx.ui.notify(stopJob(jobs, id, undefined, loop), "info");
         },
     });
     // Debug mode, for the render agents started from now on - see debug-log.ts.
@@ -2037,6 +2049,7 @@ function registerDeploy(pi, cwd, jobs, state) {
         cwd,
         state,
         jobs,
+        workLoop: () => workLoops.get(jobs)?.loop,
         defaultPlainFile: () => readProjectConfig(cwd).module,
     });
     for (const tool of tools)

package/dist/genome.js

@@ -185,7 +185,7 @@ export async function runSkill(opts) {
     // Built renders were lost with the process; queue what the specs hold that is not built.
     if (resumed !== undefined && opts.renderQueue !== undefined) {
         for (const file of plainFilesIn(opts.cwd))
-            void opts.renderQueue.bringUp(file).catch(() => undefined);
+            void opts.renderQueue.bringUp(file, { specChange: true }).catch(() => undefined);
     }
     if (liveStep !== undefined && liveProxy !== undefined) {
         const continuous = liveStep.gate.continuous;

package/dist/loop-tools.js

@@ -70,7 +70,11 @@ export async function loopReply(loop, statuses, wait) {
     return { content: [{ type: "text", text }], details: { jobIds } };
 }
 /** 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 function stopJob(jobs, named, reason) {
+export function stopJob(jobs, named, reason, loop) {
+    // A planned row, or a module by its name: the module is halted - its rows are planned again from the spec each look.
+    const module = /^planned-/.test(named.trim()) || !jobs.list().some((job) => job.id.startsWith(named.trim())) ? loop?.halt(named, reason) : undefined;
+    if (module !== undefined)
+        return module;
     const matches = jobs.list().filter((job) => job.id.startsWith(named.trim()));
     if (matches.length === 0)
         return `No pulse ${named}. /pulses shows them.`;
@@ -188,7 +192,7 @@ export function driftTool(options) {
 }
 const ACTIVATED_PARAM = Type.Optional(Type.String({ description: 'What activate started, by name - or "all" for every one' }));
 const HALT_PULSE_PARAMS = Type.Object({
-    job_id: Type.Optional(Type.String({ description: "The pulse's id, or the start of it" })),
+    job_id: Type.Optional(Type.String({ description: "The pulse's id, or the start of it; a planned row's id (planned-<module>-...), or a module's name, halts the module" })),
     reason: Type.Optional(Type.String({ description: "Why it is halted, kept with it - what the spec now says that it did not, say" })),
     activated: ACTIVATED_PARAM,
 });
@@ -201,12 +205,21 @@ export function haltTool(options) {
         name: "halt",
         label: "Halt",
         description: jobs !== undefined
-            ? "Halt a pulse, or what activate started. A pulse: a queued one never starts, a running one has its agent stopped at once, " +
-                "and the pulses queued behind it move up - what a running pulse already changed is rolled back, and what it was regenerating " +
-                "counts as not regenerated. What activate started: the one named, or every one."
+            ? "Halt a pulse, a module's planned pulses, or what activate started. A pulse: a queued one never starts, a running one has its " +
+                "agent stopped at once, and the pulses queued behind it move up - what a running pulse already changed is rolled back, and what " +
+                "it was regenerating counts as not regenerated. A planned row (planned-<module>-...) or a module's name halts the module: its " +
+                "running pulse stopped, none of its planned pulses started, and the modules built on it waiting - until it is asked for again " +
+                "with regenerate; a spec change does not start it. A module whose .plain file is gone is dropped. What activate started: the " +
+                "one named, or every one."
             : "Stop what activate started: the one named, or every one.",
         promptSnippet: jobs !== undefined ? "halt a pulse, or what activate started" : "stop a deployed server, or all of them",
-        promptGuidelines: jobs !== undefined ? ["Halt a pulse only when the user asks, or your instructions say to. Name which one, and say which pulses were queued behind it - they will now run."] : [],
+        promptGuidelines: jobs !== undefined
+            ? [
+                "Halt a pulse only when the user asks, or your instructions say to. Name which one, and say which pulses were queued behind it - they will now run.",
+                "Halting a planned row halts its whole module - one planned pulse cannot be taken out alone, as the plan is made again from the spec. To build some of it later, or cut it differently, use steer; to drop work, change the spec.",
+                "A planned row for a module that is no longer in the project is halted the same way, and dropped.",
+            ]
+            : [],
         parameters: (jobs !== undefined ? HALT_PULSE_PARAMS : HALT_ACTIVATED_PARAMS),
         async execute(_id, params) {
             if (params.job_id === undefined && params.activated === undefined) {
@@ -214,7 +227,7 @@ export function haltTool(options) {
             }
             const lines = [];
             if (params.job_id !== undefined && jobs !== undefined)
-                lines.push(stopJob(jobs, params.job_id, params.reason));
+                lines.push(stopJob(jobs, params.job_id, params.reason, options.workLoop?.()));
             if (params.activated !== undefined) {
                 const stopped = await stopDeployed(params.activated === "all" ? {} : { name: params.activated });
                 lines.push(stopped.length > 0 ? `Halted ${stopped.join(", ")}.` : `Nothing activate started is running${params.activated === "all" ? "" : ` as ${params.activated}`}.`);

package/dist/regenerate/loop.js

@@ -378,6 +378,8 @@ export function createWorkLoop(options) {
             const waiting = (why) => ({ module: entry.moduleName, why: `waiting for ${entry.moduleName}: ${why}` });
             if (below.running !== undefined)
                 return waiting(below.running.planned.track === "conformance" ? "its conformance tests are being written" : "the code it is built on is not built yet");
+            if (below.held !== undefined)
+                return waiting("you halted it - nothing is built on it until it is asked for again");
             const spec = chainSpec(below.chain);
             if (codeWork(builtOf(below), spec.tree).length > 0)
                 return waiting("the code it is built on is not built yet");
@@ -486,6 +488,11 @@ export function createWorkLoop(options) {
     /** A dry run's first jobs, by codebase: what each would start. */
     const firsts = new Map();
     const startJob = (state, spec, from, planned) => {
+        // Halted while it was being planned: the plan is made, nothing starts.
+        if (state.held !== undefined) {
+            state.why = state.held.why;
+            return;
+        }
         const tip = tipEntry(state);
         if (options.dryRun === true) {
             firsts.set(tip.buildDir, { spec: planned.track === "conformance" ? spec : { ...spec, tree: planned.step.tree }, planned });
@@ -773,16 +780,37 @@ export function createWorkLoop(options) {
         }
         return states;
     };
+    /** A codebase the loop no longer looks after: nothing of it is shown, planned or waited for. */
+    const forget = (state) => {
+        const key = tipEntry(state).buildDir;
+        modules.delete(key);
+        order.splice(order.indexOf(key), 1);
+    };
     const lookAll = async () => {
+        // A .plain file taken out of the project is asked for no more, and a codebase whose module's file is gone is
+        // forgotten - nothing running there - rather than shown waiting for a plan it will never have.
+        for (const file of [...asked.keys()])
+            if (!existsSync(file))
+                asked.delete(file);
+        for (const key of [...order]) {
+            const state = modules.get(key);
+            if (state.running === undefined && !existsSync(tipEntry(state).plainFile))
+                forget(state);
+        }
         const now = active();
         looking = now;
         for (const key of order) {
             const state = modules.get(key);
-            // A codebase left behind - built on since - is not looked at, unless a job of it is still running.
+            // A codebase left behind - built on since - is not looked at, unless a job of it is still running; what it had
+            // planned, or waited for, is no longer shown.
             if (now.has(state) || state.running !== undefined)
                 await look(state);
-            else
+            else {
                 state.why = "left behind: the code is built on further up the chain, where changes to it are made";
+                state.waitsFor = undefined;
+                state.plan = undefined;
+                state.conformancePlan = undefined;
+            }
         }
     };
     const look = async (state) => {
@@ -793,6 +821,12 @@ export function createWorkLoop(options) {
         }
         catch (error) {
             state.why = `its spec does not parse: ${error instanceof Error ? error.message : String(error)}`;
+            // Not planned from a spec that does not parse: what it waited for, and the plan, were the spec's before.
+            state.waitsFor = undefined;
+            if (state.running === undefined) {
+                state.plan = undefined;
+                state.conformancePlan = undefined;
+            }
             return;
         }
         const specKey = keyOf(spec);
@@ -845,6 +879,11 @@ export function createWorkLoop(options) {
             return;
         }
         hashResources(state, spec);
+        if (state.held !== undefined) {
+            state.why = state.held.why;
+            state.waitsFor = undefined;
+            return;
+        }
         if (state.halted !== undefined) {
             if (state.halted.specKey === specKey) {
                 state.why = state.halted.why;
@@ -1005,14 +1044,18 @@ export function createWorkLoop(options) {
         return state;
     };
     const loop = {
-        async bringUp(plainFile, request = {}) {
+        async bringUp(plainFile, given = {}) {
+            const { specChange, ...request } = given;
             const files = codebasesOf(resolve(options.cwd, plainFile));
             for (const file of files)
                 asked.set(file, { ...asked.get(file), ...request });
             const states = withParseCache(() => files.flatMap((file) => chainsFor(file).flatMap((chain) => toBuild(chain).map((entry) => track(chain.slice(0, chain.indexOf(entry) + 1), file, request)))));
-            // Asked again, a halted codebase is tried again.
-            for (const state of states)
+            // Asked again, a halted codebase is tried again - one the person halted too, unless only its spec changed.
+            for (const state of states) {
                 state.halted = undefined;
+                if (specChange !== true)
+                    state.held = undefined;
+            }
             await tick();
             return [...new Set(states)].map(statusOf);
         },
@@ -1080,7 +1123,7 @@ export function createWorkLoop(options) {
                 report.scheduled = (state.scheduled ?? []).map((group) => ({ frids: group.specs.map((touched) => touched.frid), unbuilt: group.unbuilt }));
                 if (state.running !== undefined)
                     report.running = { jobId: state.running.jobId, title: state.running.planned.title };
-                const halted = state.halted?.why ?? state.conformanceHalted?.why;
+                const halted = state.held?.why ?? state.halted?.why ?? state.conformanceHalted?.why;
                 if (halted !== undefined)
                     report.why = halted;
                 if (state.startOver !== undefined)
@@ -1167,6 +1210,7 @@ export function createWorkLoop(options) {
                 }
                 state.conformanceHalted = undefined;
                 state.halted = undefined;
+                state.held = undefined;
             }
             await tick();
             return [...new Set(states)].map((state) => {
@@ -1209,6 +1253,50 @@ export function createWorkLoop(options) {
                     startAgain(entry, "asked to be regenerated from scratch");
             return loop.bringUp(plainFile, request);
         },
+        halt(target, reason) {
+            const named = target.trim();
+            // A planned row's module - the longest name its id starts with, as a name may hold a hyphen - or a module by its name.
+            const state = order
+                .map((key) => modules.get(key))
+                .filter((candidate) => {
+                const name = tipEntry(candidate).moduleName;
+                return named === name || named.startsWith(`planned-${name}-`);
+            })
+                .sort((a, b) => tipEntry(b).moduleName.length - tipEntry(a).moduleName.length)[0];
+            if (state === undefined)
+                return undefined;
+            const tip = tipEntry(state);
+            if (state.running === undefined && !existsSync(tip.plainFile)) {
+                forget(state);
+                asked.delete(tip.plainFile);
+                return `${tip.moduleName} is no longer in the project - ${basename(tip.plainFile)} is gone - so nothing was to be built there: it is dropped from the regeneration.`;
+            }
+            const planned = statusOf(state).planned.length;
+            const said = reason !== undefined && reason.trim() !== "" ? ` (${reason.trim()})` : "";
+            state.held = { why: `you halted it${said} - nothing runs here until it is asked for again` };
+            state.why = state.held.why;
+            state.waitsFor = undefined;
+            state.plan = undefined;
+            state.conformancePlan = undefined;
+            const running = state.running;
+            if (running !== undefined && running.stopping !== true) {
+                running.stopping = true;
+                options.registry.stop(running.jobId, `Halted by you${said}: what it had done is rolled back, and nothing more runs in ${tip.moduleName} until it is asked for again.`);
+            }
+            const above = order
+                .map((key) => modules.get(key))
+                .filter((other) => other !== state && looking.has(other) && other.chain.some((entry) => entry.buildDir === tip.buildDir))
+                .map((other) => tipEntry(other).moduleName);
+            void tick();
+            return [
+                `Halted ${tip.moduleName}${said}:`,
+                running !== undefined ? ` its running pulse ${running.jobId} is being stopped, and what it had done rolled back;` : "",
+                planned > 0 ? ` its ${planned} planned pulse${planned === 1 ? "" : "s"} will not start.` : " nothing more is planned there.",
+                " Pulses that landed stay.",
+                above.length > 0 ? ` ${above.join(", ")} ${above.length === 1 ? "waits" : "wait"} for it.` : "",
+                ` It runs again only when asked for - regenerate ${basename(tip.plainFile)} - a spec change does not start it.`,
+            ].join("");
+        },
         status() {
             return order.map((key) => statusOf(modules.get(key)));
         },

package/dist/release-tools.js

@@ -142,7 +142,7 @@ export function createDeployTools(options) {
         },
     });
     // The one halt: with the pulses in the conversation, and without them for the release agent.
-    const stopTool = haltTool(options.jobs !== undefined ? { jobs: options.jobs } : {});
+    const stopTool = haltTool(options.jobs !== undefined ? { jobs: options.jobs, ...(options.workLoop !== undefined ? { workLoop: options.workLoop } : {}) } : {});
     return [deploy, startTool, stopTool];
 }
 export const DEPLOY_TOOLS = ["release", "activate", "halt"];

package/dist/spec-tools.js

@@ -88,7 +88,8 @@ export function createSpecDiffTools(options) {
             owed = false;
             liveReview?.notice(`${params.plain_file}, after the change to ${touched.join(", ")}`);
             // In the files, the change is work: the loop works out what is left to build and plans it.
-            const statuses = await loop.bringUp(params.plain_file, params.guidance !== undefined ? { guidance: params.guidance } : {});
+            // A spec change, not a request: a module the person halted stays halted.
+            const statuses = await loop.bringUp(params.plain_file, { specChange: true, ...(params.guidance !== undefined ? { guidance: params.guidance } : {}) });
             const lines = [
                 result === "applied" ? `Applied the change to ${touched.join(", ")}.` : `The change to ${touched.join(", ")} was already applied.`,
                 `Building in the background:\n${describeModules(statuses)}\n`,

package/docs/installation.md

@@ -40,6 +40,9 @@ on npm runs JavaScript compiled from them instead (`npm run build`, into `dist/`
 before they pack), as Node runs no `.ts` file inside a `node_modules`. `bin/turri.mjs` runs `src/` where there is one,
 and `dist/` otherwise.
 
+To update, `git pull` and `npm install` - the second picks up a dependency that changed, pi's say. `npm link` needs
+running only once. A **turri** already running keeps the code it started with: start it again to run what you pulled.
+
 ## In Docker
 
 `docker/Dockerfile` builds an image with Node, git, bash, bubblewrap and **turri** linked; the agents' commands and the

package/docs/regenerating.md

@@ -380,6 +380,18 @@ halts its codebase: nothing more runs there until the spec changes or the module
 the command line, `turri regenerate` runs until nothing more can start, one line as each job starts and
 ends, and exits 1 when any failed.
 
+The person halts a module's planned work too: `halt` (and `/halt`) given a planned row - `planned-<module>-2`,
+`planned-<module>-waiting` - or the module's name. A module's pulses are planned again from its spec at every look, so
+one planned pulse cannot be taken out alone: the module is halted - its running pulse stopped and rolled back, none of
+its planned pulses started, the modules built on it waiting for it - and what landed stays. A halt the person asked for
+holds through spec changes - `write_spec_diff` brings the spec in without starting the module - until the module is
+asked for again (`regenerate`, `conform`). To build some of it later, or cut it differently, there is `steer`; to drop
+work, the spec.
+
+A module the loop looked after whose `.plain` file is gone is forgotten - no rows, nothing waited for - and a codebase
+left behind, or whose spec no longer parses, shows nothing planned: its plan, and what it waited for, were the spec's
+before.
+
 ### How the work is cut into jobs
 
 A job that renders the whole of a new spec is too big to build well, and a render per functional spec,

package/docs/using.md

@@ -58,7 +58,7 @@ where it stopped. A project can have skills of its own, in `.turri/skills/` or `
 | `validate` | validate a spec, regenerating nothing |
 | `engine` | show or choose the model the code is regenerated on - see [below](#choosing-a-model) |
 | `pulses` | the pulses - running, planned and finished - or one of them |
-| `halt` | halt a pulse, or what `activate` started |
+| `halt` | halt a pulse, a module's planned pulses, or what `activate` started |
 | `diagnose` | why a pulse did not land, from its transcript: how it ended, the stages that went wrong, the last failing test run, the last review, the tool calls that failed |
 | `lineage` | a module's lineage: what each regeneration and conformance run changed in it, and what it was regenerated from |
 | `cultivate` | run a gated skill, its steps and review gates enforced |
@@ -251,8 +251,9 @@ come waits for a free slot, and says so.
   Functionalities named after the module - `/regenerate shorty 3 5` - are regenerated though their spec did not
   change, on the model chosen for functionalities: as `turri regenerate shorty.plain 3 5` does, and the chat's
   `regenerate` with `functionalities`.
-- **`/halt <id>`** halts a pulse - a queued one never starts - and **`/halt activated <name>`** halts a
-  server `activate` started; it lists both when no id is given.
+- **`/halt <id>`** halts a pulse - a queued one never starts - **`/halt <module>`** (or a planned row's id) halts a
+  module's planned pulses until you ask for it again, a spec change not starting it, and **`/halt activated <name>`**
+  halts a server `activate` started; it lists all three when no id is given.
 - **What these commands show you, the chat knows.** What `/regenerate` and `/halt activated` tell you - a spec that
   does not parse, the pulses planned, a server halted - stays in the chat under the command, and since a slash command
   runs outside the conversation, it is put in the conversation as well: say "fix it" next and turri knows what you are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.3",
+  "version": "0.1.4-next.318a98a",
   "license": "MIT",
   "type": "module",
   "repository": {