@turri-dev/cli 0.1.16-next.ce2cd46 → 0.1.17-next.1ecfd4f

package/dist/host-session.d.ts

@@ -0,0 +1,51 @@
+import { type AgentSession, type ExtensionFactory, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { AskUserIO } from "./ask.ts";
+import type { ChatInfo, TurriHost } from "./chats.ts";
+import type { JobRegistry } from "./regenerate/jobs.ts";
+import type { WorkLoop } from "./regenerate/loop.ts";
+/**
+ * turri's session for a host that runs its chats itself - a desktop app, an editor: the chats, each a pi session with
+ * turri in it, on one job registry and work loop. The host shows each chat in its own way - subscribes to its session,
+ * prompts it - and tells turri which one its person looks at (`focus`): a pulse a closed chat asked for is reported
+ * there.
+ */
+export interface TurriOptions extends Omit<TurriHost, "dialogs"> {
+    /** pi's folder - its settings, models and credentials. Default: pi's own (`~/.pi/agent`). */
+    agentDir?: string;
+    /** Where the chats' conversations are saved. Default: pi's own folder for this project. */
+    sessionDir?: string;
+    /** The host's own extensions, built into every chat after turri's. */
+    extensions?: ExtensionFactory[];
+    /** The dialogs a chat's questions are put in - ask_user's, a skill's interview, a review gate's - by the chat's id. */
+    dialogs?: (chat: string) => AskUserIO | undefined;
+    /** What a chat's other UI calls - its notices, its working line - come to, by the chat's id. */
+    uiContext?: (chat: string) => ExtensionUIContext | undefined;
+    /** Reopen the chats of the last session here that has ended, in their order - as `turri --continue` does. */
+    restore?: boolean;
+}
+export interface Turri {
+    /** The session's job registry: every pulse any chat starts. */
+    readonly jobs: JobRegistry;
+    /** The session's work loop - once a chat is open: what each codebase has planned, and why. */
+    readonly loop: WorkLoop;
+    /** The chats, in their order. */
+    chats(): ChatInfo[];
+    /** A chat's pi session: to subscribe to, prompt and abort. */
+    session(id: string): AgentSession | undefined;
+    /** A fresh chat - or the saved one `sessionFile` is. At most nine are open. */
+    openChat(options?: {
+        sessionFile?: string;
+    }): Promise<ChatInfo & {
+        session: AgentSession;
+    }>;
+    /** A chat closed: its turn stopped, its conversation deleted - its pulses run on. */
+    closeChat(id: string): Promise<void>;
+    /** The chat the person looks at now. */
+    focus(id: string): void;
+    /** Told when a chat is opened, closed, renamed, or starts or stops working. */
+    onChats(listener: (chats: ChatInfo[]) => void): () => void;
+    /** Every chat let go, and what activate started stopped. */
+    dispose(): Promise<void>;
+}
+/** turri's session in a host, in the process's working folder - the project's. */
+export declare function createTurri(options?: TurriOptions): Promise<Turri>;

package/dist/host-session.js

@@ -0,0 +1,58 @@
+import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager } from "@earendil-works/pi-coding-agent";
+import { lastRun } from "./chat-records.js";
+import { createTurriCore, sessionLoop } from "./extension.js";
+import { stopDeployed } from "./regenerate/release.js";
+/** turri's session in a host, in the process's working folder - the project's. */
+export async function createTurri(options = {}) {
+    const { dialogs, uiContext, extensions = [], agentDir = getAgentDir(), sessionDir, restore, ...host } = options;
+    const core = createTurriCore(host, { persist: true, ...(dialogs !== undefined ? { dialogs } : {}) });
+    const cwd = core.cwd;
+    core.setDriver({
+        async create(chat, sessionFile) {
+            const resourceLoader = new DefaultResourceLoader({ cwd, agentDir, extensionFactories: [core.extension, ...extensions] });
+            await resourceLoader.reload();
+            const sessionManager = sessionFile !== undefined ? SessionManager.open(sessionFile, sessionDir) : SessionManager.create(cwd, sessionDir);
+            const { session } = await createAgentSession({ cwd, agentDir, resourceLoader, sessionManager });
+            chat.session = session;
+            await session.bindExtensions({ uiContext: uiContext?.(chat.id), mode: "tui" });
+        },
+        async dispose(chat) {
+            const session = chat.session;
+            if (session === undefined)
+                return;
+            try {
+                await session.abort();
+            }
+            finally {
+                session.dispose();
+            }
+        },
+    });
+    if (restore === true) {
+        const saved = lastRun(cwd);
+        if (saved !== undefined)
+            await core.restore(saved);
+        const first = core.chats()[0];
+        if (first !== undefined)
+            await core.show(first.id);
+    }
+    return {
+        jobs: core.jobs,
+        get loop() {
+            return sessionLoop(core);
+        },
+        chats: () => core.chats(),
+        session: (id) => core.session(id),
+        async openChat(asked = {}) {
+            const chat = await core.open(asked);
+            return { ...chat, session: core.session(chat.id) };
+        },
+        closeChat: (id) => core.close(id),
+        focus: (id) => void core.show(id),
+        onChats: (listener) => core.onChats(() => listener(core.chats())),
+        async dispose() {
+            await core.dispose();
+            await stopDeployed();
+        },
+    };
+}

package/dist/host.d.ts

@@ -1,12 +1,13 @@
 /**
- * turri for a host that runs it itself - a desktop app, an editor - imported as `@turri-dev/cli/host`: the
- * conversation as pi's extension, with the host told of its jobs and asking its questions (createTurriExtension), and
+ * turri for a host that runs it itself - a desktop app, an editor - imported as `@turri-dev/cli/host`: the session and
+ * its chats, with the host told of its jobs and asking its questions (createTurri), and
  * what a host shows beside it - a spec parsed, checked and coloured, its concepts and links, the standard library, how
  * far each functional spec is built, the work a spec change would plan. It is turri's own code, as the terminal runs it; a 0.x release may change any of it.
  */
-export { createTurriExtension, type TurriHost } from "./extension.ts";
+export { createTurri, type Turri, type TurriOptions } from "./host-session.ts";
+export { MAX_CHATS, type ChatInfo, type ChatStatus, type TurriHost } from "./chats.ts";
 export type { AskUserIO } from "./ask.ts";
-/** pi itself, as turri's extension is built against it: a host makes its session with this one, not another copy. */
+/** pi itself, as turri is built against it: a host's own extensions and UI are made with this one, not another copy. */
 export * as pi from "@earendil-works/pi-coding-agent";
 export { configForSpec, debugMode, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf, type ProjectConfig } from "./config.ts";
 export { MODULES_DIR, projectDirOf, resolveTemplateDirs } from "./regenerate/paths.ts";

package/dist/host.js

@@ -1,12 +1,13 @@
 /**
- * turri for a host that runs it itself - a desktop app, an editor - imported as `@turri-dev/cli/host`: the
- * conversation as pi's extension, with the host told of its jobs and asking its questions (createTurriExtension), and
+ * turri for a host that runs it itself - a desktop app, an editor - imported as `@turri-dev/cli/host`: the session and
+ * its chats, with the host told of its jobs and asking its questions (createTurri), and
  * what a host shows beside it - a spec parsed, checked and coloured, its concepts and links, the standard library, how
  * far each functional spec is built, the work a spec change would plan. It is turri's own code, as the terminal runs it; a 0.x release may change any of it.
  */
-// The conversation.
-export { createTurriExtension } from "./extension.js";
-/** pi itself, as turri's extension is built against it: a host makes its session with this one, not another copy. */
+// The session and its chats.
+export { createTurri } from "./host-session.js";
+export { MAX_CHATS } from "./chats.js";
+/** pi itself, as turri is built against it: a host's own extensions and UI are made with this one, not another copy. */
 export * as pi from "@earendil-works/pi-coding-agent";
 // The project and its settings.
 export { configForSpec, debugMode, hasProjectConfig, modelSpec, projectModels, readProjectConfig, stacksOf } from "./config.js";

package/dist/identity.js

@@ -48,6 +48,11 @@ const IDENTITY_BEFORE = [
     "turri in the third person, as if it were someone else, and never tell the person to tell or ask turri something:",
     "they are talking to turri. What they should ask for, they ask you for, here.",
     "",
+    "The person may have several chats with you open on this project at once, this one among them. What regenerates is",
+    "the same in every chat: the pulses and their plan, steering, the engine's coding model and what activate started -",
+    "pulses lists every pulse, whichever chat asked for it, and you are told when one asked for here ends. What was said",
+    "in another chat is not in this one: when the person speaks of it, ask.",
+    "",
     "Your words, and the older ones for the same things - a project's AGENTS.md, a skill, notes or the person may use",
     "either, and they mean the same:",
     "- A pulse is one unit of work regenerating the code - a spec diff regenerated in a codebase, or its conformance",

package/dist/pi-launch.js

@@ -12,6 +12,9 @@ import { main, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { ProcessTerminal } from "@earendil-works/pi-tui";
 import "./terminal-images.js";
 import { resumeLine } from "./resume-line.js";
+import { lastRun } from "./chat-records.js";
+import { driveTerminal } from "./chat-terminal.js";
+import turri, { createTurriCore, processSession } from "./extension.js";
 /**
  * pi, started the way its own CLI starts it, for `turri`.
  *
@@ -21,6 +24,8 @@ import { resumeLine } from "./resume-line.js";
  * quiet every `pi` on the machine, so it is answered for this run instead. `--verbose` still shows it.
  */
 const args = process.argv.slice(2);
+/** Set by cli.ts when pi loads turri's extension itself - an older turri installed it into every pi. */
+const GLOBAL_EXTENSION = "TURRI_EXTENSION_IN_PI";
 if (!args.includes("--verbose")) {
     SettingsManager.prototype.getQuietStartup = () => true;
 }
@@ -42,4 +47,21 @@ process.stdout.write = ((chunk, ...rest) => write(typeof chunk === "string" ? re
 const setup = pathToFileURL(join(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "cli", "setup.js")).href;
 const { setupCli } = (await import(__rewriteRelativeImportExtension(setup)));
 setupCli();
-await main(args);
+// turri's session, with its chats: built into pi here, in this process, rather than loaded from a file - one session
+// the terminal's chats share (chats.ts). An older turri installed into every pi loads it itself: cli.ts says so, and
+// it is not built in twice.
+const extensionFactories = process.env[GLOBAL_EXTENSION] === "1" ? [] : [turri];
+// pi's terminal - not its print, json or rpc modes, nor a run given its input on stdin - holds several chats, and
+// records them for `turri --continue`, which opens them all again: the first as pi's own session, the rest beside it.
+const interactive = process.stdin.isTTY === true && !args.some((arg) => ["-p", "--print", "--mode", "--help", "-h", "--version", "-v", "--list-models"].includes(arg) || arg.startsWith("--mode="));
+if (interactive) {
+    let restore;
+    const asked = args.findIndex((arg) => arg === "--continue" || arg === "-c");
+    const saved = asked !== -1 ? lastRun(process.cwd()) : undefined;
+    if (saved !== undefined) {
+        args.splice(asked, 1, "--session", saved.chats[0].sessionFile);
+        restore = saved;
+    }
+    driveTerminal(processSession(() => createTurriCore({}, { persist: true })), restore !== undefined ? { restore } : {});
+}
+await main(args, { extensionFactories });

package/dist/regenerate/jobs.d.ts

@@ -31,6 +31,8 @@ export interface Job {
     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;
+    /** The chat it was asked for in (chat-scope.ts): the one told how it went. */
+    chat?: string;
     status: JobStatus;
     /** Monotonic start order. Two jobs can share a millisecond, so ordering uses this. */
     sequence: number;

package/dist/regenerate/jobs.js

@@ -6,6 +6,7 @@ import { addAgentReport, describeAgents, JobStoppedError, withActivity } from ".
 import { projectOfLanes, startJobLog } from "./job-log.js";
 import { firstLine, healing, record } from "./ledger.js";
 import { chosenStack, debugMode, withStack } from "../config.js";
+import { currentChat } from "../chat-scope.js";
 import { pulseEnded, pulseWrote } from "./pulse-files.js";
 const DEFAULT_TAIL_CHARS = 4000;
 const ACTIVITY_LINES = 10;
@@ -57,6 +58,7 @@ export function createJobRegistry(options) {
             // The stack chosen as it is queued - or pinned for the work that queues it - not as it starts: a job that waits
             // for a slot is built with the stack it was asked for, whatever is chosen meanwhile.
             const stack = chosenStack();
+            const chat = currentChat()?.id;
             const claimed = [...new Set(input.lanes ?? [])];
             const blockers = [
                 ...new Set(claimed
@@ -76,6 +78,7 @@ export function createJobRegistry(options) {
                 diff: input.diff,
                 model: input.model,
                 ...(stack !== undefined ? { stack } : {}),
+                ...(chat !== undefined ? { chat } : {}),
                 ...(input.follows !== undefined ? { follows: input.follows } : {}),
                 status: blockers.length > 0 || (limit !== undefined && active >= limit) ? "queued" : "running",
                 sequence: (sequence += 1),

package/dist/regenerate/ledger.d.ts

@@ -45,6 +45,11 @@ export type LedgerEvent = {
 } | {
     kind: "run.ended";
     ms: number;
+} | {
+    kind: "chat.opened";
+    reopened: boolean;
+} | {
+    kind: "chat.closed";
 } | {
     kind: "job.queued";
     jobKind: string;
@@ -213,6 +218,8 @@ export type LedgerEntry = LedgerEvent & {
     job?: string;
     module?: string;
     agent?: AgentRef;
+    /** The chat the work was asked for in, in a session of several (chat-scope.ts). */
+    chat?: string;
 };
 /** Where an event happened, when not where the code recording it runs: a job's own place is found by itself. */
 export interface LedgerPlace {

package/dist/regenerate/ledger.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, existsSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
+import { currentChat } from "../chat-scope.js";
 import { readProjectConfig } from "../config.js";
 import { turriIdentity } from "../environment.js";
 import { currentPlace, onModelEvent } from "./activity.js";
@@ -110,7 +111,13 @@ export function record(event, place = {}) {
         return;
     const job = place.job ?? here.job;
     const module = place.module ?? here.module;
-    write(run, resolve(project), event, { ...(job !== undefined ? { job } : {}), ...(module !== undefined ? { module } : {}), ...(place.agent !== undefined ? { agent: place.agent } : {}) });
+    const chat = currentChat()?.id;
+    write(run, resolve(project), event, {
+        ...(job !== undefined ? { job } : {}),
+        ...(module !== undefined ? { module } : {}),
+        ...(place.agent !== undefined ? { agent: place.agent } : {}),
+        ...(chat !== undefined ? { chat } : {}),
+    });
 }
 /**
  * Run a healer - the debugger, the diagnosis of a failed pulse - and record it: started, ended with what it found, or

package/dist/regenerate/test-scripts.d.ts

@@ -167,7 +167,7 @@ export declare function createScriptTool(options: {
     /** Watches the agent's runs for a loop: told once, then its turn is ended. */
     watch?: LoopWatch;
 }): import("@earendil-works/pi-coding-agent").ToolDefinition<Type.TObject<{}>, {
-    loop?: "warn" | "stop" | undefined;
+    loop?: "stop" | "warn" | undefined;
     command: string;
     exitCode: number;
 }, any> & import("@earendil-works/pi-coding-agent").ToolDefinition<any, any, any>;

package/dist/stacks.d.ts

@@ -1,7 +1,8 @@
 /**
  * Choosing a stack: `config.turri.<stack>.yaml` laid over `config.turri.yaml` for everything built from then on - a
  * backend's testing scripts, then a frontend's. `/stack` and the `stack` tool in the chat, `--stack <name>` on the
- * command line (cli.ts). The choice itself is kept in config.ts (`chooseStack`), for the session only.
+ * command line (cli.ts). The choice itself is kept in config.ts (`chooseStack`): in the chat it is made in, for that chat
+ * alone (chat-scope.ts), each new chat starting from `--stack`.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 /** The stacks of the projects here: the folder's own, and those of the projects one folder down (specs kept in plain/). */

package/dist/stacks.js

@@ -1,7 +1,8 @@
 /**
  * Choosing a stack: `config.turri.<stack>.yaml` laid over `config.turri.yaml` for everything built from then on - a
  * backend's testing scripts, then a frontend's. `/stack` and the `stack` tool in the chat, `--stack <name>` on the
- * command line (cli.ts). The choice itself is kept in config.ts (`chooseStack`), for the session only.
+ * command line (cli.ts). The choice itself is kept in config.ts (`chooseStack`): in the chat it is made in, for that chat
+ * alone (chat-scope.ts), each new chat starting from `--stack`.
  */
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
@@ -74,10 +75,10 @@ export function registerStacks(pi, cwd) {
         label: "Stack",
         description: "Choose the stack everything is built with from now on - the project's config.turri.yaml with the stack's " +
             "config.turri.<stack>.yaml over it: its testing scripts, toolchains, models - or none, the project's file alone. " +
-            "For the session; a pulse already running keeps the stack it started with. Without a name, says the stacks and the one chosen.",
+            "For this chat alone - each chat chooses its own; a pulse already running keeps the stack it started with. Without a name, says the stacks and the one chosen.",
         promptSnippet: "choose the stack - its testing scripts and settings - that everything is built with",
         promptGuidelines: [
-            "Switch the stack only when the user asks for it, and say which you chose. A module is built with the stack named after it by itself; to build one whose stack has another name, pass that stack as stack to regenerate, conform, glimpse or change_plain instead: it is pinned to that module's pulses, and the session's choice stays as it is.",
+            "Switch the stack only when the user asks for it, and say which you chose. A module is built with the stack named after it by itself; to build one whose stack has another name, pass that stack as stack to regenerate, conform, glimpse or change_plain instead: it is pinned to that module's pulses, and this chat's choice stays as it is.",
         ],
         parameters: Type.Object({
             name: Type.Optional(Type.String({ description: "The stack to choose, or none. Omitted: the stacks there are, and the one chosen" })),

package/docs/README.md

@@ -16,6 +16,7 @@ turri is the first coding agent with the power of regenerative software: [\*\*\*
 | what my machine needs, and why a check failed | [installation](installation.md) |
 | what turri needs of this machine, and what `turri doctor` checks | [installation](installation.md#what-turri-doctor-checks) |
 | how to start a project, or add a feature, in a conversation | [using](using.md#in-a-conversation) |
+| how to have several chats open at once, and reopen them | [chats](chats.md) |
 | which model codes, and how to change it | [using](using.md#choosing-a-model), [the project config](config.md#models) |
 | what `config.turri.yaml` can set, and what happens without it | [the project config](config.md) |
 | how a backend and a frontend on different stacks share one project | [the project config](config.md#stacks) |
@@ -31,7 +32,7 @@ turri is the first coding agent with the power of regenerative software: [\*\*\*
 | 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) |
+| how a desktop app or an editor runs turri's chats itself | [running turri in a host](hosting.md) |
 | where the code for something lives | [development](development.md#layout) |
 
 ## All pages
@@ -40,6 +41,7 @@ turri is the first coding agent with the power of regenerative software: [\*\*\*
 | --- | --- |
 | [Installation](installation.md) | doctor, what turri needs of this machine, turri and `pi`, environment variables |
 | [Using turri](using.md) | the conversation, the tools, background jobs, choosing a model, module history, the command line |
+| [Chats](chats.md) | several chats in one session: what each keeps and what they share, `/chat` and its keys, `turri --continue` and `.turri/chats.json` |
 | [The project config](config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: where they are read from, every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](deploy.md) | trying what is built: dist/<module>, the last commit, starting it on your machine, `turri release` |
 | [Running unattended](headless.md) | regenerating overnight or in CI: before you leave it, the command, the results, resuming, rebuilding one functionality |
@@ -49,5 +51,5 @@ turri is the first coding agent with the power of regenerative software: [\*\*\*
 | [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 |
+| [Running turri in a host](hosting.md) | `@turri-dev/cli/host`: the session and its chats in a host's own windows - their jobs, their questions - and what a host shows beside them |
 | [Development](development.md) | tests, the source layout, known edges |

package/docs/chats.md

@@ -0,0 +1,73 @@
+# Chats
+
+One `turri` is one session on one project, and a session holds up to nine chats: conversations with turri side by side, each working while you look at another. Ask one chat to regenerate the backend and open another to talk the frontend's \*\*\*plain through; the first goes on with its turn, its tools and its pulses meanwhile.
+
+## What each chat keeps, and what they share
+
+Each chat has its own:
+
+- **history** - what was said in it, and nothing said in another; a chat asked about another's says so and asks;
+- **turns** - a hidden chat keeps working, and starts a turn of its own when a pulse it asked for ends;
+- **model and thinking level** - [pi](https://pi.dev)'s `/model`, and `/turri-config harness-model` in that chat;
+- **stack** - `/stack` and the chat's `stack` tool choose it for that chat alone; a new chat starts with `--stack`'s, or none (see [stacks](config.md#stacks));
+- **questions** - what it asks waits in it until you look at it.
+
+The session's, shared by every chat:
+
+- **the pulses and their plan** - one job registry and one work loop on the project: a pulse any chat starts is in every chat's side panel and `pulses`, and two chats asking for the same module get one plan, not two;
+- **the coding model** chosen with `engine` or `--coding-model`, and `parallel-jobs`;
+- **steering** - what `steer` was told, every plan follows;
+- **conformance** chosen with `conform`, module by module;
+- **what `activate` started** - it runs until turri ends or `/halt activated <name>`, whatever chats are opened or closed;
+- **the ledger** - one run, each event with the id of the chat its work was asked for in (`chat`), and `chat.opened` and `chat.closed` as they happen.
+
+A pulse's end is told to the chat that asked for it, shown or not - its agent reacts to it there; the chat's mark in the strip says it has something new. When that chat has been closed, the chat shown is told. Closing a chat stops its turn, never its pulses.
+
+## In the terminal
+
+| | |
+| --- | --- |
+| `/chat new`, `alt+n` | a fresh chat, with the session's settings and an empty history, shown at once |
+| `/chat 2`, `alt+2` | chat 2, shown - `alt+1` … `alt+9` |
+| `/chat close`, `alt+w` | the chat shown, closed - and the next one shown; `/chat close 3` closes chat 3 |
+| `/chat` | a list of the chats, to pick one - or a new one |
+| `/new` | the same as `/chat new` |
+| `/resume` | a saved chat, opened as a chat of its own beside the others - or shown, when it is open |
+
+A line above the editor names each chat once there are two, a `│` between them: its number, its title - "new chat" until something is said in it, then its first message, until `/name` gives it one - and, after it, what it is doing: a spinner while it works, `?` while a question waits in it, `•` when it said something since you last looked. The chat shown is in the accent colour.
+
+On macOS, `alt` is Option (⌥), and reaches turri only when the terminal sends Option as Meta - otherwise ⌥N is the dead key for ñ and ⌥1 types `¡`, and nothing reaches turri. turri says so as a session's second chat opens. To turn it on: Ghostty, `macos-option-as-alt = true` in its config; iTerm2, Profiles → Keys → Left Option key: Esc+; Terminal.app, Profiles → Keyboard → Use Option as Meta key; Kitty, `macos_option_as_alt yes`; WezTerm, `send_composed_key_when_left_alt_is_pressed = false`. `/chat` works without it.
+
+- **A hidden chat's questions** wait until you show it, then come up one after another. What it says in passing is said as you show it; what it keeps on the screen - a skill's progress, the job panel - is put back each time; what you had typed in its editor and not sent is still there.
+- **The side panel** (`ctrl+h`) is the session's, not a chat's: docked beside the chat or over it, it stays as another chat is shown, and opening it from any chat finds it as it was left.
+- **A long command** - `/regenerate`, planning a module from scratch - does its work in the background once it is under way: the chat, and switching to another, stay free while the planner plans.
+- **The last chat** is not closed: `/quit` leaves turri.
+- **`/fork`** and **`/reload`** work on the chat shown, as [pi](https://pi.dev)'s do: the chat's history forked, or turri's extension rebuilt in it.
+- **A chat shown mid-turn** draws its reply as far as it is written, and follows it from there.
+
+## Coming back
+
+`turri --continue` (`-c`) opens every chat of the last session here again, in their order - the first shown, the others beside it. A plain `turri` starts with one fresh chat and deletes nothing: the chats of the sessions before stay on disk, and `--continue` opens the most recent one's - the last session that recorded a chat.
+
+turri records which chats are open in `.turri/chats.json` - a run a session, each chat with its title and [pi](https://pi.dev)'s saved conversation - and keeps it from piling up:
+
+- **a chat closed** is gone: out of the record, its conversation deleted - it cannot be resumed;
+- **a chat nothing was said in** is never recorded;
+- **a session's chats** are kept until five newer sessions have recorded theirs, then deleted with their record;
+- a session still running is never reopened by another turri.
+
+In [debug mode](config.md#debug-mode) nothing is deleted. The `engine`'s choices come back too: the coding model a reopened chat chose, when it is newer than the session's.
+
+## Where there is one chat
+
+[pi](https://pi.dev)'s print, json and rpc modes - `turri -p "…"`, `--mode json`, `--mode rpc` - and a `turri` given its input on stdin have one chat and record none. So does `npm run chat`, pi with turri's extension loaded from its file. The command line's `turri regenerate`, `conform` and the rest have no chat.
+
+## In a host
+
+A host - turri's desktop app - runs the same session with `createTurri`, opening, closing and showing chats in its own windows: see [running turri in a host](hosting.md#the-session-in-a-host).
+
+## How it works
+
+`src/chats.ts` is the session: its chats, their status, which chat a pulse is reported to, and the record (`src/chat-records.ts`). turri's extension is built into each chat's [pi](https://pi.dev) session and links itself to its chat; every tool, command and handler it registers runs inside the chat's scope (`src/chat-scope.ts`), which carries the chat's id - onto the pulses it queues and the ledger's events - and its stack.
+
+In the terminal (`src/chat-terminal.ts`), [pi](https://pi.dev)'s screen shows one session at a time, and replaces it - disposing the old one - on `/new` and `/resume`. turri instead puts the chosen chat's live session in pi's runtime and has the screen drawn from it again, nothing disposed. A hidden chat draws on a stand-in for the screen (`src/chat-ui.ts`) that holds its dialogs, notices and widgets until it is shown. pi has no hooks for this: its classes are patched where `pi-launch.ts` starts it, and `tests/chat-terminal.test.ts` checks they still have what is patched.

package/docs/config.md

@@ -241,11 +241,11 @@ coding-model:
 
 Which stack builds a module, first match wins:
 
-- **The one a call names.** `regenerate`, `conform`, `glimpse` and `change_plain` take a `stack`; the chat's model passes it for a module whose stack has a name of its own, leaving the session's choice as it is.
+- **The one a call names.** `regenerate`, `conform`, `glimpse` and `change_plain` take a `stack`; the chat's model passes it for a module whose stack has a name of its own, leaving the chat's choice as it is.
 - **The stack named after the module** - `config.turri.backend.yaml` builds `backend.plain` - with nothing to choose or pass. Name each stack after the module it builds, and a backend and a frontend are each built with their own, side by side - in the chat, in a brood as each change is written, and on the command line.
-- **The one chosen for the session** - in the chat, with `/stack` - a list of the project's stacks and none - or `/stack backend`, `/stack none`. The chat's model has a `stack` tool too, and switches the stack when you ask it to. `/stack` alone says which is chosen now. On the command line, with `--stack <name>` on any command - `turri regenerate`, `conform`, `change-plain`, `glimpse`, `release`, `cultivate` - and on `turri --stack backend` for the chat; or with `TURRI_STACK` in the environment.
+- **The one chosen in the chat** - each [chat](chats.md) its own - with `/stack` - a list of the project's stacks and none - or `/stack backend`, `/stack none`. The chat's model has a `stack` tool too, and switches the stack when you ask it to. `/stack` alone says which is chosen now. On the command line, with `--stack <name>` on any command - `turri regenerate`, `conform`, `change-plain`, `glimpse`, `release`, `cultivate` - and on `turri --stack backend` for the chat; or with `TURRI_STACK` in the environment.
 
-The choice lasts for the session only: nothing remembers it, and turri started again has none chosen. A stack the project has no file for is refused, with the stacks it has. With none chosen, `config.turri.yaml` alone is used.
+A chat's choice is its own, and lasts while it is open: a new chat starts with `--stack`'s, or none, and nothing remembers it - turri started again has none chosen. A stack the project has no file for is refused, with the stacks it has. With none chosen, `config.turri.yaml` alone is used.
 
 How a stack's config is made:
 

package/docs/development.md

@@ -33,7 +33,10 @@ The workflow signs in to npm with npm's trusted publishing (OIDC), not a token:
 | `bin/turri.mjs` | the launcher: checks the Node version, then loads `src/cli.ts` |
 | `src/cli.ts` | the `turri` command and its subcommands |
 | `src/setup.ts`, `src/doctor-tool.ts`, `src/environment.ts`, `src/stack.ts` | `turri doctor` and the chat's `doctor` tool, and what they check - this machine, and in a project what its modules need of it |
-| `src/extension.ts` | the [pi](https://pi.dev) extension: every tool and command the conversation has |
+| `src/extension.ts` | the [pi](https://pi.dev) extension: every tool and command the conversation has - and `createTurriCore`, the session it is built into |
+| `src/chats.ts`, `src/chat-scope.ts`, `src/chat-records.ts` | the session's [chats](chats.md): which chat a pulse is told to, each chat's scope - its id and stack - and `.turri/chats.json` |
+| `src/chat-terminal.ts`, `src/chat-ui.ts`, `src/chat-commands.ts` | the terminal's chats: [pi](https://pi.dev)'s screen switched between live sessions, a hidden chat's stand-in for it, `/chat` and its keys |
+| `src/host-session.ts` | `createTurri`, the session for a host |
 | `src/skill.ts` | parses `SKILL.md` into steps and gates |
 | `src/graph.ts` | compiles a skill into a LangGraph `StateGraph`: step -> gate -> route |
 | `src/judge.ts` | runs independent judges, applies the quorum, builds the critique |

package/docs/hosting.md

@@ -1,6 +1,6 @@
 # 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 \*\*\*plain description. It imports turri from npm as `@turri-dev/cli/host`.
+`turri` runs its chats in a terminal. A host - a desktop app, an editor - can run the same session itself, its chats in its own windows, and show what turri's terminal would draw in its own way: the jobs, the questions, the \*\*\*plain description. It imports turri from npm as `@turri-dev/cli/host`.
 
 ## What the host entry gives
 
@@ -8,8 +8,9 @@
 
 | export | what it is |
 | --- | --- |
-| `createTurriExtension(host)` | turri's conversation as an extension of [pi](https://pi.dev)'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](https://pi.dev) itself, as turri's extension is built against it. Make the session with this one - `pi.createAgentSession`, `pi.DefaultResourceLoader` - not another copy. |
+| `createTurri(options)` | a turri session: its [chats](chats.md), each a [pi](https://pi.dev) session with every tool, slash command, rule and skill the terminal has, on one job registry and work loop. The host opens, closes and shows them, is told of their jobs and asks their questions - see [the session in a host](#the-session-in-a-host). |
+| `MAX_CHATS`, `ChatInfo`, `ChatStatus` | the most chats a session has open - nine - and what the host is told of each. |
+| `pi` | [pi](https://pi.dev) itself, as turri is built against it. Make the host's own extensions and UI with this one, not another copy. |
 | `readProjectConfig`, `projectModels`, `modelSpec`, `configForSpec`, `hasProjectConfig`, `stacksOf` | the project's settings, as [config.turri.yaml](config.md) has them. |
 | `configSettings`, `currentValue`, `readConfigText`, `overriddenBy`, `EFFECT_TEXT` | every setting of config.turri.yaml as [/turri-config](config.md#changing-it-from-the-chat) knows it - its key, what it does, its kind (a yes or no, one of a few words, a number, a model, a list, a path, a budget), its words or the values offered first, what it is unset and when a change takes effect - and what the file has now (`currentValue(readConfigText(dir), key)`), and what wins over it. Change one as the person would, by sending `/turri-config <key> <value>` to the chat: turri checks it and writes it with the file's comments kept. |
 | `debugMode` | whether turri keeps, in a project, what it writes only for debugging it - `debug:`, or `TURRI_DEBUG` over it (see [debug mode](config.md#debug-mode)). |
@@ -67,36 +68,42 @@ const checks = await doctor({ dir: project, env: engineEnv });
 
 What matters only in a terminal - `turri` on the PATH, a plain `pi` an older turri made load turri - is left to `turri doctor`.
 
-## The conversation in a host
+## The session 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
-      surface: SURFACE,            // the host's UI, in its own words, told to the model in place of the terminal's
-      systemPrompt: (prompt) => prompt, // the last word on the whole system prompt, each turn
-    }),
-  ],
+import { createTurri, pi } from "@turri-dev/cli/host";
+
+process.chdir(project);                // the session is the project's in the process's working folder
+const turri = await createTurri({
+  onJobChange: (job) => {},            // a job started, moved on, did something, or ended - any chat's
+  onPlanChange: () => {},              // what is planned changed with no job
+  dialogs: (chat) => ({ select, input }), // a chat's questions, put in the host's own dialogs
+  uiContext: (chat) => uiContext,      // a chat's other UI calls - notices, the working line
+  surface: SURFACE,                    // the host's UI, in its own words, told to the model in place of the terminal's
+  systemPrompt: (prompt) => prompt,    // the last word on the whole system prompt, each turn
+  extensions: [browser, terminal],     // the host's own extensions, built into every chat after turri's
+  restore: true,                       // reopen the last session's chats here, as `turri --continue` does
 });
-await loader.reload();
-const { session } = await pi.createAgentSession({ cwd, resourceLoader: loader });
-await session.bindExtensions({ uiContext, mode: "tui" });
+
+const chat = await turri.openChat();   // { id, title, status, shown, session }: a fresh chat, shown
+chat.session.subscribe((event) => {}); // pi's session: its events, prompt(), abort()
+await chat.session.prompt("add a cart to the shop");
+turri.focus(other.id);                 // the chat the person looks at now
+turri.chats();                         // [{ id, title, status: "idle" | "working" | "question" | "unread", shown }]
+turri.onChats((chats) => {});          // a chat opened, closed, renamed, working or done
+await turri.closeChat(chat.id);        // its turn stopped, its conversation deleted - its pulses run on
+turri.jobs;                            // the session's job registry: every pulse any chat started
+turri.loop;                            // its work loop, once a chat is open
+await turri.dispose();                 // every chat let go, what activate started stopped
 ```
 
-- **The jobs.** The pulses the conversation starts - its tools, `/regenerate`, a \*\*\*plain 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 chats.** Up to nine, each its own history, model, thinking level and stack, all on the session's one job registry and work loop - see [chats](chats.md). `openChat({ sessionFile })` reopens a saved one. A pulse's end is told to the chat that asked for it, its agent reacting there; to the chat `focus` last named when that one is closed. A chat is never hidden from turri's side: what the host does not show, it still runs, and its questions go to the host's dialogs at once - the host decides where they wait. `status` says a turn is running (`working`) or that it said something since it was last focused (`unread`).
+- **The record.** The chats are recorded in `.turri/chats.json` as the terminal records them, and `restore: true` reopens the last ended session's - without it, a host starts with none and deletes nothing. A chat closed is deleted; a session's chats are kept until five newer sessions have recorded theirs.
+- **The jobs.** The host is told of each job as it changes, and has the registry and the loop themselves, so it shows the very jobs the chats run. Its buttons are best a chat's commands - `session.prompt("/regenerate app.plain")` - so the plan is the chats'.
+- **The questions.** `dialogs(chat)` gives a chat's two dialogs: `select(title, options, context, at)` and `input(title, context)`, each resolving with the answer, or undefined when the person dismissed it. The chat's questions, a skill's interview and a review gate's escalation are put in them; without them, in the `uiContext`'s own dialogs.
 - **The surface.** What turri tells the model of where the person watches the work is the terminal's by default: regen, the side panel on `ctrl+h`, `/pulses`. In a host none of that is there, and the model would send the person to keys and panels that do not exist. `surface` is the host's own description of its UI - the views it has in place of the terminal's, what its marks and buttons mean, where questions appear - in its own words. Given, turri leaves every terminal instruction out of what the model is told and puts the surface in turri's identity, as a `<surface>` block, where the identity speaks of regen. It reaches the side questions and the tools' own words too: a pulse not found says the `pulses` tool lists them, not `/pulses`. Text only the person sees in the terminal - the job panel, the side panel - is the terminal's and stays as it is. Without `surface`, the prompt is the terminal's, byte for byte. What the conversation is to do once something is released belongs there too - open it in the host's preview, say what to test: after a pulse released under `release-after-pulse`, the conversation does what it was told to do once something is released.
 - **The system prompt.** `systemPrompt(prompt)` gets the whole system prompt for the turn - [pi](https://pi.dev)'s, turri's identity and blocks, the rules - after turri's own `before_agent_start` work, and returns what is sent. It is for what `surface` does not cover; to describe the UI, use `surface`, rather than words appended after turri's that contradict them.
-- **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](https://pi.dev)'s [SDK](https://github.com/earendil-works/pi) describes it.
+- **The mode.** Each chat is bound in [pi](https://pi.dev)'s `tui` mode: the work runs in the background and keeps the chat free, as the terminal does. Its other UI calls - its notices, its working line, a confirm - come to `uiContext(chat)`, as [pi](https://pi.dev)'s [SDK](https://github.com/earendil-works/pi) describes it.
 
 A surface for a desktop app might read:
 
@@ -135,7 +142,7 @@ concepts.find((concept) => concept.definition === "/…/base.plain:8");
 
 ## The ledger in a host
 
-The conversation's extension starts the ledger itself, in the folder the host made the session in - so a host that runs it there, the project's, needs nothing to have one: its pulses are recorded as `host` runs, and the conversation's `pulses` and `diagnose` already tell the model of earlier sessions' pulses. What the host can do with it is show it.
+`createTurri` starts the ledger itself, in the process's working folder - the project's - so a host needs nothing to have one: its pulses are recorded as `host` runs, each event with the chat its work was asked for in, and the chats' `pulses` and `diagnose` already tell the model of earlier sessions' pulses. What the host can do with it is show it.
 
 ```js
 import { onLedgerEvent, pulseView, readLedger, runViews } from "@turri-dev/cli/host";
@@ -153,7 +160,7 @@ const runs = runViews(projectDir);
 const view = pulseView("646d", readLedger(projectDir, { job: "646d" }));
 
 // Earlier sessions' pulses as jobs, to list beside this session's - none this session's registry knows.
-const { jobs, more } = earlierPulses(ledgerProjects(projectDir), new Set(registry.list().map((job) => job.id)));
+const { jobs, more } = earlierPulses(ledgerProjects(projectDir), new Set(turri.jobs.list().map((job) => job.id)));
 ```
 
 - **Live.** `onLedgerEvent(listener)` is told every event as turri records it, with the project it is about, until what it returns is called; a listener that throws misses that event and nothing else. It is the pulse's own detail - its stages, test runs, verdicts, refusals - where `onJobChange` is the job as a whole.