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

package/dist/stdlib.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The ***plain standard library, as the agents that write specs are told it: every stack's import name,
+ * its conformance template and what it is, and where the files are - read from `stdlib/` each time, so
+ * what they are told is what is there. Sorted, so the rules block it goes into is the same every turn and
+ * stays cached.
+ */
+export interface StdlibTemplate {
+    /** What a spec imports it as: `stdlib/backend/python-fastapi`. */
+    name: string;
+    description: string;
+    text: string;
+}
+export declare function stdlibTemplates(dir?: string): StdlibTemplate[];
+/** A stack to import - not a kind's `common`, not a conformance template, and not a language's. */
+export declare function isStack(template: StdlibTemplate): boolean;
+/** A stack's conformance template: `stdlib/backend/python-fastapi` has `stdlib/backend/conformance/python-fastapi`. */
+export declare function conformanceOf(stack: string): string;
+/**
+ * The catalogue appended to the stdlib rule: every stack with its conformance template and what it is, the
+ * shared templates, and the folder they are all in - an absolute path, so an agent reads the one it imports
+ * instead of looking for it. The text of each is not in it: there are too many to carry in every prompt.
+ */
+export declare function stdlibCatalogue(templates?: StdlibTemplate[], dir?: string): string;
+/** How many stacks the standard library has, for the banner. */
+export declare function stdlibStackCount(templates?: StdlibTemplate[]): number;
+/** The standard library as the person reads it, with `/stdlib`: each kind's stacks, what each is, and how to import one. */
+export declare function describeStdlib(templates?: StdlibTemplate[], dir?: string): string;

package/dist/terminal-images.d.ts

@@ -0,0 +1,2 @@
+/** What PI_IMAGE_PROTOCOL turri sets for this terminal: none where it shows no images, kitty for an iTerm2 that speaks it, else nothing. */
+export declare function imageProtocolFor(env?: NodeJS.ProcessEnv): "none" | "kitty" | undefined;

package/dist/tools.d.ts

@@ -0,0 +1,101 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import type { Questioning } from "./questioning.ts";
+/**
+ * Personal tools.
+ *
+ * `write_artifact` is the executor's only way to produce output: it can read the
+ * repo, but everything it makes lands in one sandboxed directory under a name the
+ * graph chose. That is what lets the gate know exactly what to review - there is
+ * no "find the thing the agent probably changed" step.
+ */
+export declare function createWriteArtifactTool(runDir: string): ToolDefinition<Type.TObject<{
+    path: Type.TString;
+    content: Type.TString;
+}>, {
+    path: string;
+    bytes: number;
+}, any> & ToolDefinition<any, any, any>;
+export declare const VerdictSchema: Type.TObject<{
+    verdict: Type.TUnion<[Type.TLiteral<"pass">, Type.TLiteral<"fail">]>;
+    violations: Type.TArray<Type.TObject<{
+        criterion: Type.TString;
+        evidence: Type.TString;
+        fix: Type.TString;
+    }>>;
+}>;
+export type Verdict = Static<typeof VerdictSchema>;
+/**
+ * The judge's only tool. Forcing the verdict through a schema is the difference
+ * between a decision the graph can branch on and a paragraph someone has to read.
+ * `terminate` stops the judge session as soon as the verdict lands.
+ */
+export declare function createVerdictTool(onVerdict: (v: Verdict) => void): ToolDefinition<Type.TObject<{
+    verdict: Type.TUnion<[Type.TLiteral<"pass">, Type.TLiteral<"fail">]>;
+    violations: Type.TArray<Type.TObject<{
+        criterion: Type.TString;
+        evidence: Type.TString;
+        fix: Type.TString;
+    }>>;
+}>, {
+    verdict: "pass" | "fail";
+    violations: {
+        fix: string;
+        evidence: string;
+        criterion: string;
+    }[];
+}, any> & ToolDefinition<any, any, any>;
+import { runAsk, type AskUser, type AskUserRequest } from "./ask.ts";
+import { type LiveReviewer } from "./review/live.ts";
+export type { AskUser, AskUserRequest };
+/**
+ * Lets a skill step put a question to the person running it.
+ *
+ * A gated skill otherwise runs to completion with nobody to ask, which is fine for work
+ * that is fully specified and useless for an interview. The harness still owns the
+ * sequence - the step decides what to ask, not whether the gate afterwards runs.
+ */
+/**
+ * `gate`, for an interview that holds its questions to rules - the questioning level's cap (questioning.ts), an answer
+ * written as a spec change before the next question: a question it refuses is not asked, and `confirms_phase` marks a
+ * phase's closing confirmation, which the cap never counts.
+ *
+ * `talks`: where the asker answers a person who chose "Chat about this" - `"reply"`, the conversation's agent, in its
+ * reply; `"context"`, a skill's agent, whose replies nobody sees, as the `context` of the question asked again. Such a
+ * choice is no answer: neither the cap nor `onAnswered` counts it.
+ */
+export declare function createAskUserTool(ask: AskUser, onAnswered?: (answer: string, confirmsPhase: boolean) => void, said?: () => string, gate?: Pick<Questioning, "refusal" | "answered">, talks?: "reply" | "context"): ToolDefinition<Type.TObject<{
+    confirms_phase?: Type.TOptional<Type.TBoolean> | undefined;
+    question: Type.TString;
+    options: Type.TOptional<Type.TArray<Type.TString>>;
+    multi_select: Type.TOptional<Type.TBoolean>;
+    context: Type.TOptional<Type.TString>;
+    free_form: Type.TOptional<Type.TBoolean>;
+}>, {
+    question: string;
+    answer: string;
+}, any> & ToolDefinition<any, any, any>;
+export { runAsk };
+/** Ends the questions of a phase the questioning level caps: what is left, the agent decides itself. */
+export declare function createEndQuestionsTool(questioning: Pick<Questioning, "end">): ToolDefinition<Type.TObject<{}>, {}, any> & ToolDefinition<any, any, any>;
+/**
+ * Everything the reviewer has to say since the last tool call.
+ *
+ * It rides along on the tool results the interviewer is already getting, so a finding
+ * lands between two questions without the interviewer having to remember to go looking
+ * for one.
+ */
+export declare function reviewNote(liveReview: LiveReviewer | undefined): string;
+export type { LiveReviewer };
+/**
+ * With a live reviewer, a way to answer the reviewer's questions. How the builds stand, a skill reads with the
+ * conversation's own drift (loop-tools.ts), the reviewer's findings riding along on it (`withReviewNote`).
+ */
+export declare function createReviewTools(liveReview?: LiveReviewer): (ToolDefinition<Type.TObject<{
+    question_id: Type.TString;
+    answer: Type.TString;
+}>, {
+    accepted: boolean;
+}, any> & ToolDefinition<any, any, any>)[];
+/** A tool whose every result carries what the reviewer has said since the last one. */
+export declare function withReviewNote(tool: ToolDefinition<any, any, any>, liveReview: LiveReviewer | undefined): ToolDefinition<any, any, any>;

package/dist/validate-cli.d.ts

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

package/docs/README.md

@@ -31,6 +31,7 @@ turri implements regenerative software: the \*\*\*plain specs are the durable de
 | what the agents can and cannot reach | [the sandbox](sandbox.md) |
 | how skill review gates and judges work | [skills and gates](skills-and-gates.md) |
 | how the parser matches the reference implementation | [the \*\*\*plain parser](parser.md) |
+| how a desktop app or an editor runs turri's conversation itself | [running turri in a host](hosting.md) |
 | where the code for something lives | [development](development.md#layout) |
 
 ## All pages
@@ -48,4 +49,5 @@ turri implements regenerative software: the \*\*\*plain specs are the durable de
 | [Skills and gates](skills-and-gates.md) | the gate syntax, what the harness enforces, what a step can do, the rules, trying the gates |
 | [The \*\*\*plain parser](parser.md) | the TypeScript port, `turri validate`, inheritance, the iterator, fidelity |
 | [Theming](theming.md) | the turri themes, contrast, backgrounds, the font |
+| [Running turri in a host](hosting.md) | `@turri-dev/cli/host`: the conversation in a host's own window - its jobs, its questions - and what a host shows beside it |
 | [Development](development.md) | tests, the source layout, known edges |

package/docs/hosting.md

@@ -0,0 +1,52 @@
+# Running turri in a host
+
+`turri` runs its conversation in a terminal. A host - a desktop app, an editor - can run the same conversation itself, in its own window, and show what turri's terminal would draw in its own way: the jobs, the questions, the spec. It imports turri from npm as `@turri-dev/cli/host`.
+
+## What the host entry gives
+
+`@turri-dev/cli/host` is turri's compiled code (`dist/host.js`, with its types) - the conversation and what a host shows beside it:
+
+| export | what it is |
+| --- | --- |
+| `createTurriExtension(host)` | turri's conversation as an extension of pi's: every tool, slash command, rule and skill the terminal has. The host is told of its jobs and asks its questions - see below. |
+| `pi` | pi itself, as turri's extension is built against it. Make the session with this one - `pi.createAgentSession`, `pi.DefaultResourceLoader` - not another copy. |
+| `readProjectConfig`, `projectModels`, `modelSpec`, `configForSpec`, `hasProjectConfig`, `stacksOf` | the project's settings, as [config.turri.yaml](config.md) has them. |
+| `initConfig(dir, { vendor, bedrock, force })`, `VENDORS`, `BEDROCK_REGIONS`, `BEDROCK_DEFAULT`, `bedrockModels` | a project's first config.turri.yaml, as `turri init-config` writes it: the host asks which vendor's models - `VENDORS` has each one's label and its two models, `BEDROCK_REGIONS` where Bedrock serves each maker's - and `initConfig` writes it, saying what it did. One already there keeps everything but its two models. |
+| `checkPlainFile`, `plainFileParser`, `resolveTemplateDirs`, `iterateFunctionalSpecs`, `FUNCTIONAL_REQUIREMENTS` | a spec checked and parsed, its functional specs one by one - as `turri validate` reads it. |
+| `highlightLines`, `roleOf` | a spec's lines coloured by turri's own \*\*\*plain grammar. |
+| `functionalityCompletion`, `createWorkLoop`, `createJobRegistry`, `promptOf`, `describeModules` | how far each functional spec is built, and - on a loop of the host's own with `dryRun` - the work a spec change would plan, as `turri glimpse` does. |
+| `onModelEvent`, `describeTurnIncident` | a provider failing and waited out, a turn turri ended itself. |
+| `sweepOrphanedGroups` | stop what a turri killed outright left running, before anything starts. |
+
+It is turri's own code, as the terminal runs it: a 0.x release may change any of it.
+
+## The conversation in a host
+
+```js
+import { createTurriExtension, pi } from "@turri-dev/cli/host";
+
+const loader = new pi.DefaultResourceLoader({
+  cwd,
+  agentDir: pi.getAgentDir(),
+  extensionFactories: [
+    createTurriExtension({
+      onJobs: (jobs) => {},        // the conversation's job registry: every pulse it starts
+      onWorkLoop: (loop) => {},    // its work loop, once work is first asked for
+      onJobChange: (job) => {},    // a job started, moved on, did something, or ended
+      onPlanChange: () => {},      // what is planned changed with no job
+      dialogs: { select, input },  // ask_user's questions, put in the host's own dialogs
+    }),
+  ],
+});
+await loader.reload();
+const { session } = await pi.createAgentSession({ cwd, resourceLoader: loader });
+await session.bindExtensions({ uiContext, mode: "tui" });
+```
+
+- **The jobs.** The pulses the conversation starts - its tools, `/regenerate`, a spec change - run in its own job registry and work loop, the project's one. The host is handed both as they are made, and told of each job as it changes, so it shows the very jobs the conversation runs. Its buttons are best the conversation's commands - `session.prompt("/regenerate app.plain")` - so there is never a second loop on the same project.
+- **The questions.** `dialogs` is `ask_user`'s two dialogs: `select(title, options, context, at)` and `input(title, context)`, each resolving with the answer, or undefined when the person dismissed it. Given, the conversation's questions and a skill's interview are put in them; without it, in the terminal's own dialog.
+- **The mode.** `mode: "tui"` runs the work in the background and keeps the conversation free, as the terminal does; `rpc`, `json` and `print` wait for each job. The extension's other UI calls - its notices, its working line, a confirm - come to the host's `uiContext`, as pi's [SDK](https://github.com/earendil-works/pi) describes it.
+
+## Running it
+
+The host entry is compiled JavaScript, so any Node from 22.19 runs it - Electron's own included; nothing strips types. It finds turri's own folders - `genome/`, `stdlib/`, `.pi/` - beside `dist/` in the package, wherever npm installed it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.6",
+  "version": "0.1.7-next.eb57c34",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -16,6 +16,13 @@
   "bin": {
     "turri": "bin/turri.mjs"
   },
+  "exports": {
+    "./host": {
+      "types": "./dist/host.d.ts",
+      "import": "./dist/host.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "cultivate": "tsx src/cultivate-cli.ts",
     "typecheck": "tsc --noEmit",