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

package/dist/regenerate/conformance-agents.d.ts

@@ -0,0 +1,405 @@
+import type { AgentSession, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type ScriptRun, type TestScripts } from "./test-scripts.ts";
+import type { JobCases } from "./drift.ts";
+/**
+ * The agents a conformance run needs beside the one that writes the tests.
+ *
+ * The conformance tests are rendered apart from the code, in their own folder, by an agent
+ * that may read the code but writes only tests. Before it starts, an explorer reads the code and
+ * writes down how the built software is invoked from outside. When the harness's run of the suite
+ * fails, a judge reads both, against the spec, and says which is wrong: the code goes to a coding
+ * agent, which works in the code folder and may read the tests, the tests go back to
+ * their author.
+ */
+/** What the explorer, the judge and the coding agent are told the spec says. */
+export interface SpecContext {
+    moduleName: string;
+    /** The spec, as its agents are shown it: the definitions, the reqs, the functional specs. */
+    text: string;
+}
+/**
+ * What an explorer hands the author of the conformance tests: how the software is built and run, how each functionality is reached from outside,
+ * what it needs around it, and a plan for the tests.
+ */
+export interface Exploration {
+    buildAndRun: string;
+    /**
+     * How the conformance tests, run by the project's conformance testing script, reach it: what the
+     * script builds or installs and where, the coordinates, paths or classes the tests depend on or
+     * start, and whether they start it themselves.
+     */
+    testsReachIt: string;
+    interfaces: Array<{
+        module: string;
+        frid: string;
+        how: string;
+    }>;
+    environment: string;
+    plan: Array<{
+        module: string;
+        frid: string;
+        tests: string;
+    }>;
+    other?: string;
+}
+/** An exploration as the test author, and the judge, read it. */
+export declare function explorationText(exploration: Exploration, replies?: string[]): string;
+/**
+ * What an exploration lacks for the conformance tests to be written from it alone, or nothing when
+ * it is whole: how to build and run it, and - for every functionality the tests are for - how it
+ * is reached and what to test.
+ */
+/**
+ * How many tool calls the agents with one thing to decide may make before they are told to decide:
+ * the explorer its account, the reviewer its review, the judge its verdict. Past twice that, the turn
+ * is stopped. A judge that reads 40 files has read enough; one that has not decided by then is going
+ * round in a circle.
+ */
+export declare const EXPLORER_CALLS = 40;
+export declare const REVIEWER_CALLS = 40;
+export declare const JUDGE_CALLS = 30;
+/** How long an exploration may be: the interface, not the code. Longer is sent back to be cut down. */
+export declare const MAX_EXPLORATION_CHARS = 12000;
+/** How many times the explorer may hand an exploration over: each ends its turn, and is checked. */
+export declare const EXPLORATION_SUBMISSIONS = 3;
+export declare function explorationProblems(exploration: Exploration | undefined, scope: ConflictScope, moduleName: string, 
+/** The functionalities whose acceptance tests the plan has to carry out, and how many each has. */
+acceptance?: Array<{
+    module: string;
+    frid: string;
+    count: number;
+}>): string[];
+/**
+ * How the built software is invoked from outside, and a plan for its conformance tests, as an agent
+ * that explored the code writes it - everything the tests' author works
+ * from. Checked before it is used: it has to cover every functionality the tests are for, and is sent
+ * back until it does. What the explorer wrote in its replies goes with an account it never completed.
+ */
+export declare function exploreInvocation(options: {
+    buildDir: string;
+    spec: SpecContext;
+    /** The functionalities of the codebase, and the one under test - none for a spec change. */
+    scope: ConflictScope;
+    /** The project's conformance testing script: how the tests are built and run, and so how they reach the software. */
+    testingScripts?: ShownScript[];
+    /**
+     * Asked again: the tests written from the last account keep failing the same way, most likely for
+     * something they need of the software that it left out. The failing run, as the harness saw it.
+     */
+    question?: {
+        failure: string;
+        account: string;
+    };
+    /** The functionalities whose acceptance tests the plan has to carry out, and how many each has. */
+    acceptance?: Array<{
+        module: string;
+        frid: string;
+        count: number;
+    }>;
+    label: string;
+    model?: string;
+    onDelta?: (delta: string) => void;
+}): Promise<string>;
+/** The codebase's last complete exploration, and the files of the code changed since - added, changed or removed. */
+export declare function previousExploration(buildDir: string): {
+    account: string;
+    changed: string[];
+} | undefined;
+/** How many questions the test author may put to the explorer in one conformance run, and how long an answer may be. */
+export declare const EXPLORER_QUESTIONS = 3;
+/**
+ * The test author's question to the explorer, answered: a fresh explorer, in the code's folder - it reads the
+ * code and runs it, and changes nothing - given what was handed over so far and the question, answering in words.
+ */
+export declare function answerAsExplorer(options: {
+    buildDir: string;
+    spec: SpecContext;
+    /** What the explorer handed over: the account the tests are written from. */
+    account: string;
+    question: string;
+    label: string;
+    model?: string;
+    onDelta?: (delta: string) => void;
+}): Promise<string>;
+/** ask_explorer, for the conformance agent: a question about the software, answered by the explorer. */
+export declare function createAskExplorerTool(options: {
+    ask: (question: string) => Promise<string>;
+    questions?: number;
+}): ToolDefinition;
+export declare function explorePrompt(buildDir: string, spec: SpecContext, scope: ConflictScope, testingScripts?: ShownScript[], question?: {
+    failure: string;
+    account: string;
+}, previous?: {
+    account: string;
+    changed: string[];
+}): string;
+/** A review's word for a problem, as one of the two: "missing" (and anything starting so), else "bad". */
+export declare function reviewKind(word: string): "missing" | "bad";
+/** What the review found wrong with the tests: which file and test, whether something is missing or bad, and exactly what. */
+export interface ReviewProblem {
+    file: string;
+    test?: string;
+    kind: "missing" | "bad";
+    what: string;
+    /**
+     * The functionality is not yet tested, black box: a test or an acceptance test missing or cut down,
+     * the software mocked or reached other than from outside, a test that cannot fail or skips what it
+     * checks. Never let go. Anything else is a way to make good tests better.
+     */
+    blocking?: boolean;
+}
+/**
+ * The review gate, after the conformance suite and the unit tests pass: do the tests this run added
+ * or changed test the software black box, and do the acceptance tests do what the spec says - every
+ * step, every expectation. Passing tests prove nothing when they assert nothing, mock the software
+ * they test, or skip what the spec asks for. It reads the tests and the code and changes neither.
+ * No verdict is no pass: a gate that cannot say yes stays shut.
+ */
+export interface TestReviewer {
+    /** One review: what it is shown (`testReviewRequest`), and its verdict. No verdict is no pass. */
+    review(request: string): Promise<{
+        pass: boolean;
+        problems: ReviewProblem[];
+    }>;
+    dispose(): void;
+}
+/**
+ * The reviewer, one session for the whole conformance run: a review after the first starts from what it already
+ * read and raised. Its task is its instructions; each review is shown the diff of the tests - the whole of what the
+ * run wrote first, what changed since after - and the conformance agent's account of it.
+ */
+export declare function createTestReviewer(options: {
+    /** What the work does to each functional spec (work.ts): a mechanical job is held only to that. */
+    cases?: JobCases;
+    buildDir: string;
+    conformanceDir: string;
+    spec: SpecContext;
+    /** The functionality under test - or, for a spec change, those it touches - with their acceptance tests. */
+    functionalities: Array<{
+        frid: string;
+        acceptanceTests: string[];
+    }>;
+    forChange?: boolean;
+    invocation: string;
+    label: string;
+    model?: string;
+    onDelta?: (delta: string) => void;
+}): Promise<TestReviewer>;
+/** The reviewer's task, for its instructions: word for word through every review of the run. */
+export declare function testReviewTask(options: {
+    /** What the work does to each functional spec (work.ts): a mechanical job is held only to that. */
+    cases?: JobCases;
+    buildDir: string;
+    conformanceDir: string;
+    spec: SpecContext;
+    functionalities: Array<{
+        frid: string;
+        acceptanceTests: string[];
+    }>;
+    forChange?: boolean;
+    invocation: string;
+}): string;
+/** What one review of the tests is shown: the whole of what the run wrote first; after that, what changed since. */
+export declare function testReviewRequest(options: {
+    /** First review: the tests the run wrote (`workDiff`). After it: the diff since the last review (`diffSinceSnapshot`). */
+    diff: string;
+    /** The test files this run added or changed, relative to the tests folder. */
+    changed: string[];
+    account: string;
+    /** The problems of the last review the conformance agent was given - given, this is a review after it. */
+    earlier?: ReviewProblem[];
+    /** What the arbiter let go of the last review. */
+    letGo?: ReviewProblem[];
+}): string;
+/** The review's problems, for the conformance agent to fix. */
+export declare function reviewFeedbackPrompt(problems: ReviewProblem[]): string;
+export type Culprit = "code" | "tests" | "spec" | "environment";
+/** One thing the judge found, and where: a file it opened, `testing script`, or `failing run`. */
+export interface Evidence {
+    source: string;
+    shows: string;
+}
+/**
+ * A script of a conformance run as the explorer and the judge are shown it: its path, how it is run, its text. The
+ * conformance testing script, and the prepare script before it where the project has one.
+ */
+export interface ShownScript {
+    path: string;
+    runs: string;
+    content: string;
+    /** The prepare script: run on the build before every run of the conformance testing script. */
+    prepare?: boolean;
+}
+/**
+ * The tests' fix for a failure did not make it go away: the verdict that sent it to them, and what they changed. The judge
+ * is asked again, now whether the failure is the code's rather than the tests'.
+ */
+export interface Escalation {
+    reason: string;
+    changed: string[];
+}
+/** A functionality, by the module it is in and its id there: a conflict can cross modules. */
+export interface FunctionalityRef {
+    module: string;
+    frid: string;
+}
+/** "billing 4": a functionality as the judge and the person read it. */
+export declare function refLabel(ref: FunctionalityRef): string;
+export interface Verdict {
+    culprit: Culprit;
+    reason: string;
+    /** For code: the specification's words the code does not meet, as the judge quoted them. */
+    specSays?: string;
+    /** For code: it is wrong because it hides why the software failed. */
+    causeHidden?: boolean;
+    /** For code: the conformance testing script's own words for what it needs of the build, as the judge quoted them. */
+    scriptNeeds?: string;
+    /** What the judge found itself, each with where: a file it opened, the testing script, or the failing run. */
+    evidence?: Evidence[];
+    /** For a spec conflict: the two functionalities that cannot both hold - in this module, or in one it requires. */
+    functionalities?: FunctionalityRef[];
+}
+/**
+ * Which functionalities a spec conflict may name: this module's, and those of the modules it
+ * requires - its codebase holds them all, and so does its conformance suite. A functionality's
+ * conformance run can only raise one with the functionality it tests - a conflict between two
+ * earlier ones would have come up when the later of them was tested. A spec diff's run may name any two.
+ */
+export interface ConflictScope {
+    functionalities: FunctionalityRef[];
+    /** The functionality under test, which every conflict raised must include. None for a spec diff. */
+    tested?: FunctionalityRef;
+}
+/** A conflict's functionalities as the judge gave them, tidied: trimmed, and each once. */
+export declare function conflictRefs(given: Array<{
+    module?: string;
+    id?: string;
+    frid?: string;
+}> | undefined): FunctionalityRef[];
+/** Why a spec conflict cannot be raised as given, or nothing when it can. */
+export declare function specConflictProblem(functionalities: FunctionalityRef[] | undefined, scope: ConflictScope): string | undefined;
+/** The two functionalities of a spec conflict, in a fixed order: the same conflict, however it was named. */
+export declare function conflictKey(functionalities: FunctionalityRef[]): string;
+export declare function sortedRefs(functionalities: FunctionalityRef[]): FunctionalityRef[];
+/** How many times a spec conflict between the same two functionalities is raised before it counts. */
+export declare const SPEC_CONFLICT_RAISES = 3;
+/**
+ * How many times, one after the other, the run's environment is judged what is wrong before it counts: once more
+ * than once, so a second judge of a new run - the tests checked in between - has to agree.
+ */
+export declare const ENVIRONMENT_RAISES = 2;
+/**
+ * Why a verdict that the code is wrong cannot be taken as it is, or nothing when it can. The code is
+ * wrong only against what the specification says - so the judge quotes it, and the quote has to be
+ * in the specification - or when it hides why the software failed. A test asserting what the
+ * specification leaves open is the test's mistake, however plausible the assertion.
+ */
+export declare function unfoundedCodeVerdict(verdict: Verdict, specText: string, scriptText?: string): string | undefined;
+/**
+ * Why a verdict's evidence cannot be taken as it is, or nothing when it can. Asked to weigh an escalation, the judge has
+ * to rest its verdict on what it found itself: each piece of evidence from a file it opened, the testing script or the
+ * failing run - and at least one not the run alone, which every judge before it read too. What the explorer's account
+ * says is not evidence: it was written before the run, and may be wrong.
+ */
+export declare function unfoundedEvidence(evidence: Evidence[] | undefined, opened: (path: string) => boolean): string | undefined;
+export declare function judgeFailure(options: {
+    buildDir: string;
+    conformanceDir: string;
+    spec: SpecContext;
+    run: ScriptRun;
+    invocation: string;
+    scope: ConflictScope;
+    /** The working notes, whose pitfalls hold the attempts made at this failure so far. */
+    notes: string;
+    /** The conformance testing script, word for word: what the run does, and what it needs of the build. */
+    testingScripts?: ShownScript[];
+    /** The tests' fix did not make this failure go away: is it the code's? */
+    escalation?: Escalation;
+    label: string;
+    model?: string;
+    onDelta?: (delta: string) => void;
+}): Promise<Verdict>;
+export declare function judgePrompt(options: {
+    buildDir: string;
+    conformanceDir: string;
+    spec: SpecContext;
+    run: ScriptRun;
+    invocation: string;
+    scope: ConflictScope;
+    notes: string;
+    testingScripts?: ShownScript[];
+    escalation?: Escalation;
+}): string;
+/**
+ * For the judge, of a run the time limit stopped: what kept it from finishing - something that hangs, the code's or a
+ * test's, or a suite that is only slow, which no agent can give more time.
+ */
+export declare function timedOutBlock(run: Pick<ScriptRun, "timeoutMs" | "elapsedMs">): string[];
+/**
+ * The coding agent a conformance run sends the code to, when the judge says the code is wrong: it
+ * works in the code folder, may read the tests but never changes them, and keeps the unit
+ * tests passing.
+ * Made the first time it is needed, and kept for the rest of the run: each fix after the first starts from what the
+ * ones before it tried. Its task is its instructions; its work is compacted as it gets longer.
+ */
+export declare function createCodeFixer(options: {
+    buildDir: string;
+    /** The conformance tests: it reads them, and never changes them. */
+    conformanceDir?: string;
+    label: string;
+    model?: string;
+    /** The specification it fixes the code to: in its task. */
+    spec: SpecContext;
+    /** Its own tools beyond the file tools: running the unit tests, its notes. */
+    tools: ToolDefinition[];
+    toolNames: string[];
+    /** The harness's own run its environment reports are checked against. */
+    checkEnvironment?: {
+        run: () => Promise<{
+            exitCode: number;
+            output: string;
+        }>;
+        script: string;
+    };
+    /** The testing scripts its fixes are run by - the prepare, conformance and unit ones - word for word, in its task. */
+    testingScripts?: {
+        scripts: TestScripts;
+        root: string;
+    };
+}): Promise<AgentSession>;
+/**
+ * The code fixer's task, for its instructions: whose code it is, the specification, and how a fix is made. It stays
+ * word for word through every fix of the run; each failure comes as a message (`codeFixPrompt`).
+ */
+export declare function codeFixerTask(options: {
+    buildDir: string;
+    conformanceDir?: string;
+    spec: SpecContext;
+}): string;
+/** One failure for the code fixer: the run, and why the code is what is wrong. */
+export declare function codeFixPrompt(options: {
+    run: ScriptRun;
+    reason: string;
+}): string;
+/**
+ * An escalated failure for the code fixer: the tests were fixed for it and it did not go away, and the judge found it
+ * the code's. It is handed the conformance testing script's error, the tests as they stand and the judge's evidence.
+ */
+export declare function escalatedFixPrompt(options: {
+    run: ScriptRun;
+    reason: string;
+    evidence: Evidence[];
+    tests: Array<{
+        path: string;
+        content: string;
+    }>;
+}): string;
+/** The run's environment judged what is wrong: the conformance agent checks the tests do not cause it, and changes nothing when they do not. */
+export declare function environmentCheckPrompt(options: {
+    run: ScriptRun;
+    reason: string;
+}): string;
+export declare function testsFixPrompt(options: {
+    run: ScriptRun;
+    reason: string;
+}): string;

package/dist/regenerate/conformance.d.ts

@@ -0,0 +1,189 @@
+import { ACCEPTANCE_TESTS, type MarshalledPlainSource } from "../plain/spec.ts";
+import { type BuildingSpec } from "./activity.ts";
+import type { JobCases } from "./drift.ts";
+import { type ScriptRun, failureSignature, STUCK_ROUNDS } from "./test-scripts.ts";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Evidence, type ReviewProblem } from "./conformance-agents.ts";
+import { type TestRemoval, type TestRun } from "./testing.ts";
+/**
+ * A module's conformance tests: one directory, `plain_modules/<module>/tests`, organised
+ * however the tests are best organised. It holds the tests of the modules it requires too,
+ * copied up with their code, so running it is the regression suite of the whole chain.
+ */
+export declare function conformanceDirFor(moduleName: string, root?: string): string;
+export interface RenderConformanceTestsOptions {
+    /** What the job does to each functional spec (work.ts): its agents are told case by case. */
+    cases?: JobCases;
+    plainFile: string;
+    frid?: string;
+    templateDirs?: string[];
+    /** The rendered code under test. Must exist and be non-empty. */
+    buildDir?: string;
+    /** Where the tests are written. Defaults to `<cwd>/plain_modules/<module>/tests`. */
+    conformanceDir?: string;
+    onDelta?: (delta: string) => void;
+    onRun?: (command: string, exitCode: number) => void;
+    /** Rounds of fixing a failing run before giving up. */
+    maxRounds?: number;
+    /** "provider/model-id". Omitted: whatever pi is configured to use. */
+    model?: string;
+    /** The judge's and the test review's model. Omitted: the project's judge-model, else `model`. */
+    judgeModel?: string;
+    dryRun?: boolean;
+    /** Update the tests for a spec change, given as a diff, rather than for one functionality. */
+    diff?: string;
+    /** That change section by section, as the agents are shown it in place of the diff. */
+    change?: string;
+    /**
+     * The spec as parsed when that change was written. A change rendered from a queue runs after
+     * later ones went into the file, so the file is not what this change is about.
+     */
+    spec?: {
+        moduleName: string;
+        tree: MarshalledPlainSource;
+    };
+    /**
+     * This is a later step of work already under way, whose changes are not committed yet - a
+     * spec diff's conformance step - so the module is not put back to its last commit first.
+     */
+    continuing?: boolean;
+}
+export interface RenderConformanceTestsResult {
+    moduleName: string;
+    frid: string;
+    buildDir: string;
+    conformanceDir: string;
+    prompt: string;
+    response: string;
+    files: string[];
+    runs: TestRun[];
+    /** Whether the harness's own run of the whole suite passed - and the unit tests, when the code changed. */
+    passed: boolean;
+    /** How many times the harness ran the conformance testing script: the rounds it judged. */
+    rounds?: number;
+    /** Whether the agent changed the code to make the tests pass. */
+    codeChanged: boolean;
+    /**
+     * The code and the tests as they were at the harness's last green run - the whole suite and the unit tests passing -
+     * file by file: what is still as it was then needs no run of the whole suite again.
+     */
+    green?: {
+        code: Map<string, string>;
+        tests: Map<string, string>;
+    };
+    /** Conformance tests that went missing mid-run and had to be justified. */
+    testRemovals: TestRemoval[];
+    /**
+     * The spec contradicts itself: two functionalities that cannot both hold, raised by the judge
+     * the times it takes to count. The run stopped on it - nothing in the code or the tests can fix it.
+     */
+    specConflict?: {
+        functionalities: Array<{
+            module: string;
+            frid: string;
+        }>;
+        reason: string;
+    };
+    /**
+     * The run failed the same way, judged the same way, round after round - and again after the
+     * explorer was asked what the tests lacked. It stopped rather than spend its attempts on it.
+     */
+    stuck?: {
+        failure: string;
+        rounds: number;
+        error: string;
+        times: number;
+        changedNothing?: boolean;
+    };
+    /**
+     * The run's environment is what is wrong - a credential missing or rejected, say - judged so ENVIRONMENT_RAISES
+     * times in a row: only the person can fix it, so the run stopped.
+     */
+    environment?: {
+        reason: string;
+        times: number;
+    };
+    /**
+     * The tests' fix for a failure did not make it go away, the judge found it the code's and escalated it to the coding
+     * agent - and the run still failed the same way after the code's fix too: why the judge found it the code's, on what
+     * evidence, and the error the run stopped on.
+     */
+    escalation?: {
+        reason: string;
+        evidence: Evidence[];
+        error: string;
+        failure: string;
+        changedNothing?: boolean;
+    };
+    /** The tests were sent back to be written and labelled, and never were: what was missing the last time. */
+    unlabelled?: string[];
+    /** The tests were optimised as far as REVIEW_ROUNDS reviews could take them: what the last one still suggested. */
+    reviewWaived?: ReviewProblem[];
+    /** The suite passed, but the tests never passed review: what the review last found. */
+    review?: Array<{
+        file: string;
+        test?: string;
+        kind: "missing" | "bad";
+        what: string;
+    }>;
+}
+/**
+ * Write black-box conformance tests for one functionality of a .plain specification.
+ *
+ * Runs after the functionality has been rendered: the build directory is the subject,
+ * and this refuses to start without one.
+ */
+export declare function renderConformanceTests(options: RenderConformanceTestsOptions): Promise<RenderConformanceTestsResult>;
+/**
+ * Why conformance tests did not land, in a line. Tests sent back to be labelled and never labelled may well pass: the
+ * line says so, rather than that they failed.
+ */
+export declare function notLandedWhy(what: string, unlabelled?: string[]): string;
+/**
+ * The functionalities a spec change touches - its functional spec, or one of its acceptance tests,
+ * has a line the change adds or removes - with their acceptance tests: what a spec diff's
+ * conformance run labels, checks and reviews, as a functionality's run does for its one.
+ */
+export declare function touchedFunctionalities(tree: MarshalledPlainSource, frids: string[], diff: string): Array<{
+    frid: string;
+    acceptanceTests: string[];
+}>;
+/** From the how-manieth review that sends the tests back the arbiter weighs each one (see arbiter.ts). */
+export declare const REVIEW_ROUNDS = 1;
+/** How many times the tests are sent back to be written and labelled before the run stops. */
+export declare const LABEL_ASKS = 3;
+/** How many times a code fix that does not build or pass its unit tests goes back to the coding agent before the suite runs again. */
+export declare const FIX_UNIT_CHECKS = 3;
+/** How many times an agent runs the conformance suite in a turn before its turn ends and the harness takes over. */
+export declare const RUNS_PER_TURN = 3;
+/**
+ * A testing script tool an agent may call so many times a turn. The last allowed call ends its turn
+ * with the result - the harness then runs the suite itself and judges what is wrong - so an agent
+ * cannot spend its turn rerunning a failure it cannot fix. `newTurn` starts the count again.
+ */
+export declare function turnLimited(tool: ToolDefinition, limit: number): {
+    tool: ToolDefinition;
+    newTurn: () => void;
+};
+export { failureSignature, STUCK_ROUNDS };
+/** How many fixes in a row that change no file - the code's or the tests' - is nothing changing. */
+export declare const IDLE_FIXES = 2;
+/**
+ * The code's own build files, at the top of its folder, as they are - read by the harness, for the
+ * author of the conformance tests, who cannot read the code. They are interface, not implementation:
+ * what a separate test project has to point at - the name, the coordinates, the version.
+ */
+export declare function buildManifests(buildDir: string): Array<{
+    path: string;
+    content: string;
+}>;
+/** What a failing run failed with, in one line as it said it: its first line that says what went wrong. */
+export declare function failureLine(run: ScriptRun): string;
+/**
+ * The functional spec a conformance run writes tests for, for the person watching: which one of how
+ * many, and its text as the spec has it, with its acceptance tests after it.
+ */
+export declare function buildingSpec(moduleName: string, frid: string, total: number, specifications: {
+    "functional specs": string[];
+    [ACCEPTANCE_TESTS]?: string[];
+}): BuildingSpec;

package/dist/regenerate/conversation-writes.d.ts

@@ -0,0 +1,10 @@
+/** The conversation is about to write these files: call what it returns once it has. */
+export declare function conversationWriting(paths: string[]): () => void;
+/** The conversation starts a command of its own: call what it returns once it has ended. */
+export declare function conversationCommand(): () => void;
+/** The conversation's turn is over: nothing of its is in progress any more. */
+export declare function conversationSettled(): void;
+/** Whether the conversation may have written this file after `since` - a write of its to it, or a command of its own. */
+export declare function writtenByConversation(path: string, since: number): boolean;
+/** For tests: forget everything. */
+export declare function resetConversationWrites(): void;

package/dist/regenerate/credentials.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Credentials are the person's: no agent writes them. A run that needs one and does not have it is told
+ * so - by its judge, to the person - rather than given one an agent made up, which every later run then
+ * fails on without anyone seeing why.
+ *
+ * A credential file is a `.env` or one of its variants (`.env.local`, `.env.test`); a template of one -
+ * `.env.example`, `.env.sample`, `.env.template`, `.env.dist` - holds no secret and is not one.
+ */
+export declare function isCredentialFile(path: string): boolean;
+/** What an agent is told when it tries to write one. */
+export declare function credentialRefusal(path: string): string;
+/** The credential files under `roots`, with what each holds: what an agent's command is checked against. */
+export declare function credentialFiles(roots: string[]): Map<string, string>;
+/**
+ * Undo what a command did to the credential files under `roots`, from what they held before it: one it made is
+ * removed, one it changed or removed is put back. Says which it put back.
+ */
+export declare function restoreCredentialFiles(before: Map<string, string>, roots: string[]): string[];

package/dist/regenerate/debug-log.d.ts

@@ -0,0 +1,54 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+/**
+ * Every render agent's whole conversation, streamed to a file of its own as it happens - always.
+ *
+ * A job's transcript keeps a tool call's arguments to 600 characters and its result to 2000, and only while pi is
+ * running. When an agent goes wrong, what it was actually
+ * given and what actually came back is what there is to go on. So each agent a render starts -
+ * coding, conformance, repair, the spec-steps planner - writes everything to `.turri/debug/`
+ * in the project: the system prompt, every prompt, its replies and thinking as they stream, every
+ * tool call with its arguments and its whole result, each response's stop reason and usage, and the
+ * provider's retries and errors.
+ *
+ * Each event is on disk the moment it arrives, so a crashed or killed run leaves its log up to
+ * the moment it stopped, and `tail -f` follows an agent live. The folder is in the project, not in
+ * `plain_modules`, so no agent can read another's log. A log that cannot be written is given up
+ * on, never allowed to fail the render.
+ */
+/** `.turri/debug` in the project: beside `plain_modules`, never inside it. */
+export declare function debugDir(project: string): string;
+/**
+ * Where the log of an agent working in `cwd` goes: always outside what that agent can reach. In
+ * `plain_modules`, or in the project that holds it, that is the project's; an explicit build
+ * folder elsewhere is its own fence (see `modulesRootOf`), so its logs go beside it, not in it.
+ */
+export declare function debugDirFor(cwd: string): string;
+/** The part of a pi session a debug log reads. */
+export interface DebuggedSession {
+    subscribe(listener: (event: AgentSessionEvent) => void): () => void;
+    readonly model?: {
+        provider?: string;
+        id?: string;
+    } | undefined;
+    readonly thinkingLevel?: string;
+    readonly systemPrompt?: string;
+    readonly sessionFile?: string | undefined;
+}
+export interface DebugLog {
+    readonly file: string;
+    /** A prompt the agent is sent, whole. */
+    prompt(text: string): void;
+    /** Something the harness has to say about the turn: that it ended, and how. */
+    note(line: string): void;
+}
+/** The debug log a session is streaming to, if it has one. */
+export declare function debugLogOf(session: object): DebugLog | undefined;
+/**
+ * Start streaming a session to a log of its own. `label` says what the agent is - `app 3 coding
+ * agent` - and names the file.
+ */
+export declare function startDebugLog(session: DebuggedSession, options: {
+    cwd: string;
+    label: string;
+    tools?: string[];
+}): DebugLog | undefined;