@turri-dev/cli 0.1.6-next.336dd6e → 0.1.7-next.8f13f3a

package/dist/regenerate/jobs.d.ts

@@ -0,0 +1,186 @@
+import { type AgentTally, type BuildingSpec, type SpecConflict, type TranscriptEntry, type UsageReport } from "./activity.ts";
+/**
+ * Background jobs for conversation mode.
+ *
+ * Rendering a functionality takes minutes, and a tool's `execute` blocks the agent loop
+ * for as long as it runs - which means the person cannot say anything until it finishes.
+ * A job starts the work detached and hands back an id immediately, so the conversation
+ * carries on while the agents work.
+ */
+export type JobStatus = "queued" | "running" | "succeeded" | "failed" | "stopped";
+export interface Job {
+    id: string;
+    kind: string;
+    /** One line describing what was asked for. */
+    summary: string;
+    /** The module it works in, for a job that regenerates one: what a finished job is listed as. */
+    module?: string;
+    /** Its number among its module's pulses, from 1 - as regen numbers them. */
+    pulse?: number;
+    /** What it regenerates, in a few words: its plan's title. */
+    title?: string;
+    /** The spec change a render spec diff job renders, as its diff. Shown while it waits and runs. */
+    diff?: string;
+    /** Where its diff's lines are in the .plain files - their files and line numbers there - when they could be placed. */
+    diffWhere?: import("./diff-view.ts").DiffWhere;
+    /** For a conformance job: the render job it is the conformance of. */
+    follows?: string;
+    /** A note on it, for the person: why it did not run, or what became of it. */
+    note?: string;
+    /** "provider/model-id" its agents run on, when known. */
+    model?: string;
+    /** The stack it is built with - its config.turri.<stack>.yaml over config.turri.yaml - as chosen when it was queued. */
+    stack?: string;
+    status: JobStatus;
+    /** Monotonic start order. Two jobs can share a millisecond, so ordering uses this. */
+    sequence: number;
+    queuedAt: number;
+    /** When the work itself began - after any wait in the queue. */
+    startedAt: number;
+    /** A row of the work loop's, not a pulse: its module's work being planned into pulses now, since then. */
+    planning?: {
+        since: number;
+    };
+    /** While queued: the jobs it is waiting for. */
+    waitingOn: string[];
+    finishedAt?: number;
+    /** Tail of the streamed output, bounded so a long run cannot get longer without limit. */
+    tail: string;
+    /** The stage the work is at, as the work itself last reported it. */
+    stage?: string;
+    /** The functional spec it is building now, when it builds one. */
+    building?: BuildingSpec;
+    /** The most recent things the agents did, newest last. */
+    activity: string[];
+    /** What is happening right now, and since when. */
+    now?: {
+        label: string;
+        since: number;
+    };
+    /** Every model response its agents have had, added up. */
+    usage: UsageReport;
+    /**
+     * Queued again as another job - the one it names - to come after jobs added ahead of it: it never ran, and is not
+     * announced or listed as a job of its own.
+     */
+    replacedBy?: string;
+    /** Each of its agents: turns, compactions and what it cost - a row per agent, in the order they first worked. */
+    agents: AgentTally[];
+    /** The whole conversation of its agents, oldest dropped first past a size limit. */
+    transcript: TranscriptEntry[];
+    /** It failed, and failed again when retried - or a job ahead of it did: the queue behind it fails too. */
+    failedForGood?: boolean;
+    /** Its whole transcript, on disk: `.turri/jobs/` in the project. */
+    logFile?: string;
+    /** Why it failed for good, and what to do, as the diagnosis found. */
+    diagnosis?: string;
+    /** It stopped because the environment lacks something: what the person is told. */
+    environment?: string;
+    /** What to tell the agent when it asks how the job went. */
+    report?: string;
+    /** The spec contradicts itself, as its conformance run found: for the person to decide. */
+    specConflict?: SpecConflict;
+    /** What to tell the person when it lands, if shorter than the report. */
+    announce?: string;
+    error?: string;
+    details?: unknown;
+}
+export interface JobOutcome {
+    report: string;
+    /**
+     * What the person is shown when the job lands. The report is written for the agent and
+     * can carry detail it needs and the person does not; omitted, the report is shown.
+     */
+    announce?: string;
+    details?: unknown;
+}
+export interface StartJobInput {
+    kind: string;
+    summary: string;
+    /** The module it works in, for a job that regenerates one. */
+    module?: string;
+    /** Its number among its module's pulses, from 1. */
+    pulse?: number;
+    /** What it regenerates, in a few words. */
+    title?: string;
+    /** For a render spec diff job: the diff, to show in the panel and the transcript. */
+    diff?: string;
+    /** "provider/model-id" its agents run on, to show where the job is shown. */
+    model?: string;
+    /** For a conformance job: the render it is the conformance of. */
+    follows?: string;
+    /**
+     * What the job writes, e.g. a module's directory. Two jobs sharing a lane never run at
+     * the same time: the later one queues until the earlier one settles, whatever started
+     * them. Jobs with no lanes in common run side by side.
+     */
+    lanes?: string[];
+    /** The command that runs the work again - `turri regenerate <the spec>` - for a message that stops it. */
+    rerun?: string;
+    run: (onDelta: (delta: string) => void) => Promise<JobOutcome>;
+}
+export interface JobRegistry {
+    start(input: StartJobInput): Job;
+    /** How many jobs may run at once from now on - undefined for no limit. Raised, jobs waiting for a slot start. */
+    setMaxRunning(count: number | undefined): void;
+    /**
+     * Stop a job. A queued one never starts; a running one has its agent's turn aborted and
+     * ends as stopped. Returns the job, or undefined when there is no such job or it has
+     * already finished.
+     */
+    stop(id: string, reason?: string): Job | undefined;
+    get(id: string): Job | undefined;
+    list(): Job[];
+    /** Something shown with the jobs changed, though no job did - a plan begun or made: what shows them redraws. */
+    notify?(): void;
+    /** Resolves when the job settles. Used by callers that asked to wait. */
+    wait(id: string): Promise<Job>;
+}
+/** What a stopped job says when the person stopped it. */
+export declare const STOPPED_ON_REQUEST = "Stopped on request.";
+export declare function createJobRegistry(options?: {
+    onFinish?: (job: Job) => void;
+    /** A job started, moved to another stage, or did something. */
+    onChange?: (job: Job) => void;
+    /** Something shown with the jobs changed, no job with it - see `notify`. */
+    onNotify?: () => void;
+    tailChars?: number;
+    /**
+     * How many times a job that fails - its work throws, or reports it did not pass - is run again.
+     * Given, a job that fails that many times more fails for good: it is diagnosed, and every job
+     * queued behind it fails without running. Not given, a failure is reported and the queue goes on.
+     */
+    retries?: number;
+    /** Why a job failed for good, and what to do: for the person, with both failures. */
+    diagnose?: (job: Job, failures: string[], jobLog?: string) => Promise<string | undefined>;
+    /**
+     * How many jobs may run at once. Jobs whose lanes are free still wait for a slot past it - each
+     * module's jobs build and test on this machine, and ten modules at once would ask for more than it
+     * has. Not given: no limit.
+     */
+    maxRunning?: number;
+}): JobRegistry;
+export declare function formatDuration(job: Job): string;
+/** "42s", "3m 12s", "1h 5m": how long something has run. */
+export declare function formatElapsed(ms: number): string;
+/**
+ * What a pulse is called wherever it is shown in a line: its module, kind and number - `shorty · regenerate pulse 3`,
+ * `shorty · conformance pulse 6` - never what it regenerates, which is the agents' words and long. A job of no module,
+ * what was asked for.
+ */
+export declare function pulseName(job: Job): string;
+/** What the agent is told when it checks on a job. */
+export declare function describeJob(job: Job): string;
+/**
+ * Whether a tool should block rather than hand back a job id.
+ *
+ * Background only makes sense where the session outlives the turn. In print, json and rpc
+ * modes the process ends as soon as the answer is written, taking any detached work with
+ * it, so those wait unless told otherwise.
+ */
+export declare function shouldWait(mode: string, wait: boolean | undefined): boolean;
+/**
+ * How many jobs run at once when nothing says: half this machine's cores, at least one and at most four - a pulse's
+ * builds and tests run here, beside the person's own work.
+ */
+export declare function defaultParallelJobs(cores?: number): number;

package/dist/regenerate/lanes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What a job on this spec may write, as lanes for the job registry.
+ *
+ * A module's directory holds its code and its conformance tests, and building a module can
+ * build everything it requires first - so the lanes are every module in the requires chain.
+ * That is more than a single functionality touches, and deliberately so: two jobs that
+ * might write the same directory wait for each other, and a wait costs minutes where a
+ * collision costs the build.
+ *
+ * The module's own folder is a lane whatever the spec says at the moment it is read. A spec with
+ * no functional specs yet - the scaffold a new project starts with - or one that does not parse
+ * names no chain, and a job queued then must still wait for, and be waited for by, every other
+ * job on that module: two that claimed different lanes for the same folder ran side by side and
+ * wrote over each other.
+ */
+export declare function moduleLanes(plainFile: string, buildRoot?: string): string[];

package/dist/regenerate/lineage.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Version history for each module's generated code and tests.
+ *
+ * A module folder - `plain_modules/<module>`, holding `code/` and `tests/` - is a git
+ * repository whose git directory is `.plaingit` rather than `.git`. Everything git does
+ * works as usual; the name is what keeps it from being an embedded repository inside the
+ * project's own, so the generated code stays plain files to the outer repo. Only the harness
+ * writes it: the agents' fences cover `code/` and `tests/`, and `.plaingit` sits beside them.
+ *
+ * A commit is made after every step that changes the module - a render, a regeneration, a
+ * conformance run, a regression repair, a spec change, a start from the module below - with
+ * a message saying what it was. History is a record of the work, never a gate on it: a git
+ * failure is swallowed, not raised.
+ */
+export declare const HISTORY_DIR = ".plaingit";
+/** The module folder a build or tests directory belongs to. */
+export declare function moduleDirOf(dir: string): string;
+/**
+ * Commit whatever the step changed in the module folder that `dir` - its build or its tests
+ * directory - belongs to. Nothing changed, nothing is committed. Returns the commit, if any.
+ */
+export declare function recordHistory(dir: string, subject: string, body?: string): string | undefined;
+/**
+ * The notes the harness writes once a pulse has ended, committed - or the next pulse, putting the module back to its last
+ * commit, would take them away. Into the pulse's own commit when it landed one - `landedSince` (ms), when it started - so
+ * the history keeps a commit a pulse; a commit of their own otherwise - a pulse rolled back leaves its line, and nothing
+ * else.
+ */
+export declare function commitNotes(dir: string, file: string, subject: string, landedSince?: number): void;
+export declare function resetToLastCommit(dir: string): string[];
+/**
+ * Where a unit of work started: each module folder it writes, at the commit it was at. A unit
+ * either lands whole - committed, its tree recorded - or is undone whole (`abandonWork`), so the
+ * code, its tests and the tree they were built from never disagree.
+ */
+export interface WorkStart {
+    modules: Array<{
+        moduleDir: string;
+        commit: string;
+    }>;
+}
+/**
+ * The start of every unit of work that writes a module's code or tests: each module folder it
+ * writes back at its last commit - saying so when that undid anything - and that commit kept, to
+ * go back to if the work fails. A module with no commit yet is given one first, so there always
+ * is one.
+ */
+export declare function startWork(dirs: string[], moduleName: string): WorkStart;
+/**
+ * Where work already under way is now, to go back to if what comes next fails - without
+ * putting anything back first: what is uncommitted belongs to the work that is under way.
+ */
+export declare function markWork(dirs: string[]): WorkStart;
+/**
+ * Undo a unit of work that failed: every module folder it wrote back at the commit it started
+ * from - its changes, the files it added and any commit it made since, gone. What history does
+ * not track stays: installed dependencies, caches.
+ */
+export declare function abandonWork(start: WorkStart | undefined, moduleName: string, why: string): void;
+/**
+ * A file of a module as its last commit has it - `file` relative to `dir`, its build or its tests
+ * folder - or undefined when there is no history, no commit, or the file is not in it.
+ */
+export declare function committedText(dir: string, file: string): string | undefined;
+/**
+ * Commit these paths of a module, and nothing else of it - removed, added or changed. Whatever else is in the folder,
+ * uncommitted - what an interrupted job left - stays as it is, for the next unit of work to put back. Returns the commit.
+ */
+export declare function commitPaths(moduleDir: string, paths: string[], subject: string): string | undefined;
+/** Bring a history's exclude list up to the one it is made with now. */
+export declare function refreshExcludes(moduleDir: string): void;
+/** The current commit of a module's history, if it has one. */
+export declare function head(dir: string): string | undefined;
+/** The module's history, newest first, one line per commit. */
+export declare function historyLog(dir: string, limit?: number): string;
+/** One commit in full: its message and what it changed. */
+export declare function historyShow(dir: string, commit: string): string;
+/**
+ * What the work under way changed in `dir` - the code folder, or the tests folder - since the module's last
+ * commit: a unified diff of every file changed, and every new file whole. Every unit of work starts from that
+ * commit, so this is exactly what its agents wrote. Lockfiles and the harness's own files are left out. Empty when
+ * there is no history, or nothing changed.
+ */
+export declare function workDiff(dir: string): string;
+/**
+ * The work in `dir` as it is now - the code folder, or the tests folder - as a git tree, without a commit and without
+ * touching the module's index: what a review saw, so the next review is shown only what changed since. Undefined
+ * when there is no history.
+ */
+export declare function workSnapshot(dir: string): string | undefined;
+/**
+ * What changed in `dir` since a snapshot of it (`workSnapshot`): a unified diff of every file changed, added or
+ * removed since, as `workDiff` shows the whole work. Empty when nothing changed, or there is no history.
+ */
+export declare function diffSinceSnapshot(dir: string, snapshot: string): string;

package/dist/regenerate/list-arguments.d.ts

@@ -0,0 +1,21 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+/**
+ * A tool argument that is a list of objects - submit_exploration's `interfaces` and `plan`, a reviewer's `problems` - is
+ * the shape a small model gets wrong most: it sends the list as JSON text, each entry as JSON text, or writes it inside
+ * another argument's text as `</tests_reach_it><plan>[...]</plan>`. The validator's answer - "plan.0: must be object" -
+ * does not say what it wants, and the model makes the same call again until its turn is stopped.
+ *
+ * So before the arguments are checked, what plainly means the list is taken as the list; and what cannot be is refused
+ * with what is wanted, in words and with an example. For every tool an agent is given (createExecutor), in one place.
+ */
+interface Schema {
+    type?: string;
+    properties?: Record<string, Schema>;
+    items?: Schema;
+    required?: string[];
+}
+/** The arguments with their lists made lists where they plainly are; refused, saying what is wanted, where they are not. */
+export declare function prepareListArguments(toolName: string, schema: Schema, raw: unknown): unknown;
+/** The tools, each that takes a list of objects preparing its arguments so before they are checked. */
+export declare function withListArguments(tools: ToolDefinition[]): ToolDefinition[];
+export {};