@vzlentin/harness 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # harness
 
-Observable, persistent subagents on [Pi](https://github.com/earendil-works/pi)'s libraries and
+Observable, persistent (sub)agents on [Pi](https://github.com/earendil-works/pi)'s libraries and
 [pi-durable](https://www.npmjs.com/package/@earendil-works/pi-durable). Each subagent is a conversation in a durable
 host process. You can spawn it, check its status, wait for its answer, steer it, and talk to it live in Pi.
 
@@ -13,22 +13,23 @@ with `/login` in `pi`, or set the API key of the provider, such as `ANTHROPIC_AP
 npm install -g @vzlentin/harness
 ```
 
-This works with npm 11 and npm 12. It gives you the `harness` command, and a setup runs `pi install` on the `pi/`
-folder of the package, which adds the `subagent` tool, the `/subagent` and `/harness` commands and the subagents widget
-to Pi. Pi and the `harness` command use the same host. npm 12 runs no install script by default, so there the first
+This works with npm 11 and npm 12. It gives you the `harness` command, and a setup runs `pi install` on
+`npm:@vzlentin/pi-agents` at the same version, which adds the `subagent` tool, the `/subagent` and `/harness` commands
+and the subagents widget to Pi. Pi and the `harness` command use the same host. npm 12 runs no install script by default, so there the first
 `harness` command does the setup. When `pi` is not on your `PATH`, or the step fails, the setup prints the command to run later:
 
 ```sh
-pi install "$(realpath "$(npm root -g)/@vzlentin/harness/pi")"
+pi install "npm:@vzlentin/pi-agents@$(harness --version)"
 ```
 
-When you install with `--prefix`, give the same `--prefix` to `npm root -g`.
+With only Pi, run `pi install npm:@vzlentin/pi-agents` and start `pi`. The extension asks to install harness with
+`npm install -g`. Answer yes, then run `/reload`.
 
 ### Update and remove
 
 ```sh
-npm install -g @vzlentin/harness@latest
-pi remove "$(realpath "$(npm root -g)/@vzlentin/harness/pi")"    # first: npm runs no script on uninstall
+npm install -g @vzlentin/harness@latest    # the setup pins the extension to this version
+pi remove npm:@vzlentin/pi-agents    # npm runs no script on uninstall
 npm uninstall -g @vzlentin/harness
 ```
 
@@ -60,6 +61,7 @@ XDG_STATE_HOME=/tmp/harness-dev node src/cli.ts list
 `node src/cli.ts` runs the CLI of this checkout. Give it its own `XDG_STATE_HOME`, so its hosts do not share sockets and
 stores with the hosts of the installed `harness`.
 
-The checkout runs from its TypeScript source. The package contains `dist/`, the Pi extension in `pi/` and its
-`postinstall` script. Change `version` in `package.json` and push to `main`: CI publishes it. `npm run check` builds `dist/` too, before the type check. The extension imports `../dist/`, so to try the checkout's
-extension in Pi, run `npm run build`, then `pi install ./pi`, and build again after each change in `src/`.
+The checkout runs from its TypeScript source. The package contains `dist/` and its `postinstall` script. The Pi
+extension in `pi/` is the package `@vzlentin/pi-agents`. To release, merge the release PR `release: <version>` that CI keeps open: CI then publishes both packages at that version. `npm run check` builds `dist/` too, before the type check. The extension
+loads `dist/` of the global harness, so to try the checkout's extension in Pi, run `npm run build`, `npm link`, then
+`pi install ./pi`, and build again after each change in `src/`.

package/dist/children.d.ts

@@ -183,6 +183,11 @@ export type Children = {
     } | {
         readonly id: string;
     }, context: Context): Promise<Child | undefined>;
+    /**
+     * The lineage, conversation and state of the child with the conversation ID `id`, of any owner, without its owner
+     * operations. Nothing for a root, an unknown ID, or text that is not an ID.
+     */
+    inspect(place: Place, id: string, context: Context): Promise<Pick<Child, "lineage" | "conversation" | "state"> | undefined>;
     /** Where the conversation `id` sits in its tree; nothing for a root, or another conversation the library did not open. */
     lineage(store: Pick<Store, "snapshot">, id: string, context: Context): Promise<Lineage | undefined>;
     /**

package/dist/children.js

@@ -245,7 +245,8 @@ export function createChildren(durable) {
             },
         };
     }
-    const find = async (place, owner, which, context) => {
+    /** The child of a key or a conversation ID, of any owner, with its document. */
+    async function load(place, which, context) {
         const id = "key" in which
             ? (await place.store.snapshot(Keys, which.key, context))?.conversation
             : conversationIdOf(which.id);
@@ -255,15 +256,24 @@ export function createChildren(durable) {
         const conversation = await place.store.conversation(id, context);
         if (doc === undefined || conversation === undefined)
             return undefined;
-        if (!sameOwner(doc.owner, ownerState(owner)))
-            throw new Error(`The child ${id} belongs to another owner`);
-        return makeChild(place, id, lineageOf(doc), conversation);
+        return { child: makeChild(place, id, lineageOf(doc), conversation), owner: doc.owner };
+    }
+    const find = async (place, owner, which, context) => {
+        const loaded = await load(place, which, context);
+        if (loaded === undefined)
+            return undefined;
+        if (!sameOwner(loaded.owner, ownerState(owner))) {
+            throw new Error(`The child ${loaded.child.id} belongs to another owner`);
+        }
+        return loaded.child;
     };
+    const inspect = async (place, id, context) => (await load(place, { id }, context))?.child;
     return {
         extension,
         answerExtension: answers.extension,
         lineage,
         find,
+        inspect,
         turn,
         async open(place, owner, key, spec, context, setup) {
             const existing = await find(place, owner, { key }, context);

package/dist/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
 import { request } from "./client.js";
 import { piEnv } from "./herdr.js";
 import { piArgs } from "./mirror.js";
@@ -24,8 +27,10 @@ function usage() {
   harness stop <handle>
   harness list
   harness attach <handle>
+  harness attach --conversation <id>
   harness create <name> --cwd <dir>
   harness projects
+  harness --version
 Any command but harness <project> takes --project <name> before it; without it, the project is HARNESS_PROJECT, then the cwd.`);
 }
 function valueAfter(args, index, option) {
@@ -182,12 +187,17 @@ async function hostCommand(args, project) {
     await host.closed;
     process.exit(0);
 }
-/** Opens a child in Pi in this terminal. */
+/** Opens a child, or a conversation of the children library with `--conversation <id>`, in Pi in this terminal. */
 async function attachCommand(args) {
-    const [handle] = args;
-    if (args.length !== 1 || handle === undefined)
+    const [first, id] = args;
+    let ref;
+    if (args.length === 1 && first !== undefined && first !== "--conversation")
+        ref = { handle: first };
+    else if (args.length === 2 && first === "--conversation" && id)
+        ref = { conversation: id };
+    else
         usage();
-    await openInPi({ project: resolveProject(process.env, process.cwd()), handle });
+    await openInPi({ project: resolveProject(process.env, process.cwd()), ...ref });
 }
 /** Opens the agent of the project `name`, which is `main` or a project, in Pi in this terminal. */
 async function agentCommand(name, project) {
@@ -197,11 +207,12 @@ async function agentCommand(name, project) {
 }
 /**
  * Runs Pi in this terminal with a mirror session of `target` (see the Pi extension), and exits with its code. It starts
- * the host when none runs. A first watch fails before Pi starts for an unknown child and for a project agent without a
- * model.
+ * the host when none runs. A first watch fails before Pi starts for an unknown child, an unknown conversation and a
+ * project agent without a model.
  */
 async function openInPi(target) {
-    await request({ type: "watch", handle: target.handle }, { start: true, project: target.project });
+    const ref = target.conversation === undefined ? { handle: target.handle } : { conversation: target.conversation };
+    await request({ type: "watch", ...ref }, { start: true, project: target.project });
     const result = spawnSync("pi", piArgs(target), {
         stdio: "inherit",
         env: { ...piEnv(process.env), PATH: userPath() },
@@ -229,7 +240,14 @@ async function main() {
     // npm 12 runs no install script by default, so an installed CLI finishes the setup. A checkout runs `cli.ts`, and
     // the host starts from a command that already did it.
     if (import.meta.url.endsWith(".js") && command !== "host")
-        setupOnce(fileURLToPath(new URL("..", import.meta.url)));
+        setupOnce(fileURLToPath(new URL("..", import.meta.url)), "@vzlentin/pi-agents");
+    if (command === "--version") {
+        if (project !== undefined || args.length !== 0)
+            usage();
+        const json = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        process.stdout.write(`${Value.Parse(Type.Object({ version: Type.String() }), json).version}\n`);
+        return;
+    }
     if (command === "create")
         return createCommand(args);
     if (command === "projects")

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type Socket } from "node:net";
-import { type Replies, type Request, type WatchLine } from "./protocol.ts";
+import { type Replies, type Request, type Target, type WatchLine } from "./protocol.ts";
 /**
  * A connection to the host. Requests are answered in order, one reply line for each request line. After `watch`, the
  * event lines of the watch come between the replies.
@@ -17,10 +17,10 @@ export declare class Client {
         type: T;
     }>): Promise<Replies[T]>;
     /**
-     * Sends the `watch` request of `handle`. Its `lines` are the events of the watch, and end when the connection closes.
-     * Other requests can follow on this client. Call it once.
+     * Sends the `watch` request of `target`, a handle or a conversation ID. Its `lines` are the events of the watch, and
+     * end when the connection closes. Other requests can follow on this client. Call it once.
      */
-    watch(handle: string): Promise<Replies["watch"] & {
+    watch(target: string | Target): Promise<Replies["watch"] & {
         lines: AsyncIterable<WatchLine>;
     }>;
     close(): void;

package/dist/client.js

@@ -65,13 +65,14 @@ export class Client {
         return reply.promise;
     }
     /**
-     * Sends the `watch` request of `handle`. Its `lines` are the events of the watch, and end when the connection closes.
-     * Other requests can follow on this client. Call it once.
+     * Sends the `watch` request of `target`, a handle or a conversation ID. Its `lines` are the events of the watch, and
+     * end when the connection closes. Other requests can follow on this client. Call it once.
      */
-    async watch(handle) {
+    async watch(target) {
         const lines = new Readable({ objectMode: true, read() { } });
         this.#lines = lines;
-        const reply = await this.request({ type: "watch", handle });
+        const ref = target instanceof Object ? target : { handle: target };
+        const reply = await this.request({ type: "watch", ...ref });
         return { ...reply, lines };
     }
     close() {

package/dist/herdr.d.ts

@@ -18,6 +18,20 @@ export declare function herdr(args: readonly string[], env: NodeJS.ProcessEnv):
  * `herdr` call fails or gives no pane ID.
  */
 export declare function openChildTab(child: ChildInfo, env: NodeJS.ProcessEnv): Promise<void>;
+/**
+ * Opens the children library conversation `conversation` in Pi, on the project of `env` and this process's cwd: in a
+ * new pane to the right of the Herdr pane `place.pane`, or in a new tab of the Herdr workspace `place.workspace`. The
+ * pane or tab gets the key of the conversation as its label. For a conversation, `ChildInfo` gives the same ID in
+ * `handle` and in `conversation`. It rejects when a `herdr` call fails or gives no pane ID, and then makes no more
+ * calls.
+ */
+export declare function openConversationPane(conversation: ChildInfo, place: {
+    pane: string;
+    workspace?: never;
+} | {
+    workspace: string;
+    pane?: never;
+}, env: NodeJS.ProcessEnv): Promise<void>;
 /**
  * Reports the state of the agent `label` to the Herdr pane of `HARNESS_HERDR_PANE`, with the command that opens
  * `target` as the resume command. Both methods do nothing without that variable, so only a Pi that the CLI

package/dist/herdr.js

@@ -13,6 +13,8 @@ const HERDR_SOURCE = "custom:harness";
 const PANE_VARIABLE = "HARNESS_HERDR_PANE";
 /** The part of the output of `herdr tab create` that has the pane of the tab. */
 const TabCreated = Type.Object({ result: Type.Object({ root_pane: Type.Object({ pane_id: Type.String() }) }) });
+/** The part of the output of `herdr pane split` that has the new pane. */
+const PaneSplit = Type.Object({ result: Type.Object({ pane: Type.Object({ pane_id: Type.String() }) }) });
 /**
  * The words of the command that opens `target` in Pi, with this Node and this package's CLI, so it does not need the
  * CLI on PATH. Herdr wants a plain command name as the first word of a resume command, so it starts with `env`.
@@ -20,6 +22,24 @@ const TabCreated = Type.Object({ result: Type.Object({ root_pane: Type.Object({
 function openCommand(target) {
     return ["env", process.execPath, cliPath(), ...harnessArgs(target)];
 }
+/** The `--env` flags of `herdr` that give `XDG_STATE_HOME` and `XDG_CONFIG_HOME` of `env`, when they are set. */
+function envFlags(env) {
+    // The new pane must find the same host and projects as `statePaths()` in protocol.ts and `projectsPath()` in
+    // projects.ts.
+    const state = env.XDG_STATE_HOME;
+    const config = env.XDG_CONFIG_HOME;
+    return [
+        ...(state ? ["--env", `XDG_STATE_HOME=${state}`] : []),
+        ...(config ? ["--env", `XDG_CONFIG_HOME=${config}`] : []),
+    ];
+}
+/** Runs the command that opens `target` in Pi in the Herdr pane `pane`, with each word in single quotes. */
+async function runOpen(pane, target, env) {
+    const command = openCommand(target)
+        .map((word) => `'${word.replaceAll("'", "'\\''")}'`)
+        .join(" ");
+    await herdr(["pane", "run", pane, command], env);
+}
 /** Whether this process runs in a Herdr pane, also as the Pi that the CLI starts there. */
 export function inHerdr(env) {
     return Boolean(env.HERDR_ENV || env[PANE_VARIABLE]);
@@ -49,19 +69,56 @@ export function herdr(args, env) {
  */
 export async function openChildTab(child, env) {
     const project = resolveProject(env, process.cwd());
-    // The tab must find the same host and projects as `statePaths()` in protocol.ts and `projectsPath()` in projects.ts.
-    const state = env.XDG_STATE_HOME;
-    const config = env.XDG_CONFIG_HOME;
+    const created = await herdr(["tab", "create", "--cwd", child.cwd, "--label", childLabel(child), "--focus", ...envFlags(env)], env);
+    let output;
+    try {
+        output = JSON.parse(created);
+    }
+    catch {
+        output = undefined;
+    }
+    if (!Value.Check(TabCreated, output))
+        throw new Error(`herdr tab create gave no pane ID: ${created.trim()}`);
+    await runOpen(output.result.root_pane.pane_id, { project, handle: child.handle }, env);
+}
+/**
+ * Opens the children library conversation `conversation` in Pi, on the project of `env` and this process's cwd: in a
+ * new pane to the right of the Herdr pane `place.pane`, or in a new tab of the Herdr workspace `place.workspace`. The
+ * pane or tab gets the key of the conversation as its label. For a conversation, `ChildInfo` gives the same ID in
+ * `handle` and in `conversation`. It rejects when a `herdr` call fails or gives no pane ID, and then makes no more
+ * calls.
+ */
+export async function openConversationPane(conversation, place, env) {
+    const project = resolveProject(env, process.cwd());
+    const target = { project, conversation: conversation.handle };
+    const label = childLabel(conversation);
+    if (place.pane !== undefined) {
+        const split = await herdr(["pane", "split", place.pane, "--direction", "right", "--cwd", conversation.cwd, ...envFlags(env)], env);
+        let output;
+        try {
+            output = JSON.parse(split);
+        }
+        catch {
+            output = undefined;
+        }
+        if (!Value.Check(PaneSplit, output))
+            throw new Error(`herdr pane split gave no pane ID: ${split.trim()}`);
+        const pane = output.result.pane.pane_id;
+        await herdr(["pane", "rename", pane, label], env);
+        await runOpen(pane, target, env);
+        return;
+    }
     const created = await herdr([
         "tab",
         "create",
+        "--workspace",
+        place.workspace,
         "--cwd",
-        child.cwd,
+        conversation.cwd,
         "--label",
-        childLabel(child),
+        label,
         "--focus",
-        ...(state ? ["--env", `XDG_STATE_HOME=${state}`] : []),
-        ...(config ? ["--env", `XDG_CONFIG_HOME=${config}`] : []),
+        ...envFlags(env),
     ], env);
     let output;
     try {
@@ -72,11 +129,7 @@ export async function openChildTab(child, env) {
     }
     if (!Value.Check(TabCreated, output))
         throw new Error(`herdr tab create gave no pane ID: ${created.trim()}`);
-    const pane = output.result.root_pane.pane_id;
-    const command = openCommand({ project, handle: child.handle })
-        .map((word) => `'${word.replaceAll("'", "'\\''")}'`)
-        .join(" ");
-    await herdr(["pane", "run", pane, command], env);
+    await runOpen(output.result.root_pane.pane_id, target, env);
 }
 /**
  * Reports the state of the agent `label` to the Herdr pane of `HARNESS_HERDR_PANE`, with the command that opens

package/dist/host.js

@@ -9,16 +9,17 @@ import * as ai from "@earendil-works/pi-ai";
 import { CodemodeSandbox } from "@earendil-works/pi-codemode";
 import { getAgentDir, ProjectTrustStore, SettingsManager } from "@earendil-works/pi-coding-agent";
 import * as durable from "@earendil-works/pi-durable";
-import { AgentDoc, createRegistry, defineDoc, Harness, } from "@earendil-works/pi-durable";
+import { AgentDoc, createRegistry, Harness, } from "@earendil-works/pi-durable";
 import { createCodemodeExtension } from "@earendil-works/pi-durable/codemode";
 import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
 import { openNodeSqliteStorage } from "@earendil-works/pi-durable/storage/sqlite/node";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
-import { createChildren, resolveModel, } from "./children.js";
+import { resolveModel } from "./children.js";
 import { ChildContext } from "./context.js";
 import { loadEntries } from "./load-entries.js";
-import { AGENT_HANDLE, errorMessage, onLines, PROTOCOL_VERSION, RequestLine, } from "./protocol.js";
+import { errorMessage, onLines, PROTOCOL_VERSION, RequestLine, } from "./protocol.js";
+import { Children, childInfo, childOf, childRecord, childTarget, library, ownRecord, recordOf, target, } from "./targets.js";
 import { abortTask, startableTasks, startTask, taskInfo, waitTask } from "./tasks.js";
 import { subagentTool } from "./tool.js";
 import { viewChange } from "./view-change.js";
@@ -28,27 +29,6 @@ const IDLE_CHECK_MS = 60_000;
 const context = BACKGROUND_CONTEXT;
 /** The `detail` of a failed turn that is an error object. */
 const ErrorDetail = Type.Object({ message: Type.String() });
-/**
- * The children by handle, and the handle of each spawn request ID. Version 2 leaves each child's last request to the
- * children library; a store with version 1 has children that the library does not know.
- */
-const Children = defineDoc({
-    kind: "subagent.children",
-    version: 2,
-    scope: "session",
-    initial: () => ({ children: {}, requests: {} }),
-});
-/** The request ID of the project agent's newest input, which its `error` state comes from. */
-const AgentState = defineDoc({
-    kind: "harness.agent",
-    version: 1,
-    scope: "conversation",
-    history: "latest",
-    fork: "initial",
-    initial: () => ({ lastRequest: null }),
-});
-/** The children library, on this process's pi-durable. */
-const library = createChildren(durable);
 /**
  * Runs the host of `project` in this process: the store in `stateDir`, the children's models from `models`, the
  * project agent in `cwd`, and the socket. It is undefined when another host holds the lock.
@@ -267,7 +247,8 @@ async function handleRequest(request, handler) {
             }
         }
         case "input":
-            return sendTo(request, await target(handler, request.handle));
+            // A conversation takes input only while it works, so its input is always a steer.
+            return sendTo(request.conversation === undefined ? request : { ...request, followUp: false }, await target(handler, request));
         case "wait":
             return waitChild(request, handler);
         case "status":
@@ -279,7 +260,7 @@ async function handleRequest(request, handler) {
         case "watch":
             if (handler.connection === undefined)
                 throw new Error("A watch needs a connection");
-            return serveWatch(handler, request.handle, handler.connection);
+            return serveWatch(handler, request, handler.connection);
         case "start":
             // A child that a task opens without a model takes the project agent's, so the agent is set up first. Without
             // a model for the agent, the task still starts: its children may name their own.
@@ -483,70 +464,18 @@ async function markSent(harness, handle, requestId, add) {
     }, context);
 }
 async function abortChild(request, handler) {
-    const found = await target(handler, request.handle);
+    const found = await target(handler, request);
     // Without `background`, an abort of the project agent does not reach the anchors of the children, which keep running.
     await found.conversation.abort(context);
     return found.info();
 }
 async function configureChild(request, handler) {
-    const found = await target(handler, request.handle);
+    // Only the handle: the schema of `configure` does not refuse an extra `conversation` key.
+    const found = await target(handler, { handle: request.handle });
     const agent = await found.conversation.agent(context);
     await found.conversation.configure(resolveModel(handler.place.models, agent, request), context);
     return found.info();
 }
-/**
- * The conversation of `handle`, a child or the project agent, with its info, its input, and the record of a child.
- */
-async function target(handler, handle) {
-    if (handle !== AGENT_HANDLE)
-        return childTarget(handler, handle, await childRecord(handler.harness, handle));
-    const root = await handler.agent();
-    const { harness, place, project } = handler;
-    const turn = library.turn(place, root.id, root, async (readContext) => (await harness.snapshot(AgentState, root.id, readContext))?.lastRequest, async (tx, requestId) => {
-        (await tx.doc(AgentState, root.id)).lastRequest = requestId;
-    });
-    return {
-        conversation: root,
-        info: async () => ({
-            ...(await agentFields(root)),
-            handle,
-            name: `${project} agent`,
-            state: await turn.state(context),
-        }),
-        send: (input) => turn.send(input, context),
-        record: undefined,
-    };
-}
-/** The target of the child `handle`, whose record is `record`. */
-async function childTarget(handler, handle, record) {
-    const child = await childOf(handler, record);
-    return {
-        conversation: child.conversation,
-        info: () => childInfo(handler, handle, record),
-        send: (input) => child.send(input, context),
-        record,
-    };
-}
-async function childRecord(harness, handle) {
-    const state = await harness.snapshot(Children, context);
-    const record = recordOf(state, handle);
-    if (record === undefined)
-        throw new Error(`Unknown subagent: ${handle}`);
-    return record;
-}
-/** The record of `handle`, which must belong to `caller`. */
-async function ownRecord(harness, handle, caller) {
-    const record = await childRecord(harness, handle);
-    if (record.caller !== caller)
-        throw new Error(`Subagent ${handle} belongs to another session`);
-    return record;
-}
-async function childOf(handler, record) {
-    const child = await library.find(handler.place, handler.owner, { id: String(record.conversationId) }, context);
-    if (child === undefined)
-        throw new Error(`Missing conversation ${record.conversationId}`);
-    return child;
-}
 function failureText(handle, reason, detail) {
     if (reason === "aborted")
         return `${handle} was aborted`;
@@ -557,27 +486,6 @@ function failureText(handle, reason, detail) {
             : undefined;
     return text === undefined ? `${handle} failed: ${reason}` : `${handle} failed: ${text}`;
 }
-/** The info of `handle`. A caller that already has the record gives it as `record`. */
-async function childInfo(handler, handle, record) {
-    record ??= await childRecord(handler.harness, handle);
-    const child = await childOf(handler, record);
-    const childState = await child.state(context);
-    // A closed child is idle: the watch can still send it before its record goes and the `stopped` line follows.
-    const state = childState === "closed" ? "idle" : childState;
-    const fields = await agentFields(child.conversation);
-    return record.name === undefined ? { handle, state, ...fields } : { handle, name: record.name, state, ...fields };
-}
-/** The model, thinking level and directory of the agent of `conversation`, for its info. */
-async function agentFields(conversation) {
-    const agent = await conversation.agent(context);
-    return {
-        provider: agent.model?.provider ?? "",
-        model: agent.model?.modelId ?? "",
-        thinking: agent.thinkingLevel,
-        // `spawnChild` refuses a spawn without `cwd`; the fallback only satisfies pi-durable's optional type.
-        cwd: agent.cwd ?? "",
-    };
-}
 /**
  * The root conversation as the agent of `project`. The first time, it gets Pi's default model when it has a login, else
  * the first model with a login, Pi's default thinking level, and the directory `cwd`. Without a model with a login, it
@@ -611,7 +519,8 @@ async function setUpAgent(root, models, settings, project, cwd) {
  * `drain` then stays on the closed socket and goes with it. When the child stops, the client gets a `stopped` event and the connection ends; when the conversation
  * watch ends for another reason, the connection ends.
  */
-async function serveWatch(handler, handle, connection) {
+async function serveWatch(handler, ref, connection) {
+    const handle = ref.conversation ?? ref.handle;
     const { harness } = handler;
     const { socket } = connection;
     const write = (event) => socket.write(`${JSON.stringify({ event })}\n`);
@@ -628,8 +537,9 @@ async function serveWatch(handler, handle, connection) {
     let conversation;
     let last;
     try {
-        found = await target(handler, handle);
-        // The project agent has no record, and no `Children` watch: it is never renamed or stopped.
+        found = await target(handler, ref);
+        // The project agent and a conversation target have no record and no `Children` watch: they are never renamed
+        // or stopped.
         if (found.record !== undefined) {
             // The `Children` watch opens before the info, so it gets each later rename and stop of the child.
             children = await harness.watchDoc(Children, watchContext);
@@ -683,10 +593,6 @@ async function serveWatch(handler, handle, connection) {
     });
     return { view: conversation.value, child: last };
 }
-/** The record of `handle` in the `Children` value `state`. */
-function recordOf(state, handle) {
-    return state != null && Object.hasOwn(state.children, handle) ? state.children[handle] : undefined;
-}
 /**
  * The lock of the host, a write transaction on `lock.sqlite`, held until `close()`. The system drops it when the
  * process ends. It is undefined when another process holds it. `IMMEDIATE`, not `EXCLUSIVE`: two hosts that start at

package/dist/mirror.d.ts

@@ -3,27 +3,39 @@ import { type Static, Type } from "typebox";
 import { type ChildInfo, type Request } from "./protocol.ts";
 /** The `customType` of the session entry that holds the target of a mirror session. */
 export declare const MIRROR_ENTRY = "harness-mirror";
-/** The conversation that a mirror session shows: the child or project agent `handle` of the host of `project`. */
-export declare const MirrorTarget: Type.TObject<{
+/**
+ * The conversation that a mirror session shows, in the host of `project`: the child or project agent `handle`, or the
+ * conversation `conversation` that the children library opened. Each refuses the other key.
+ */
+export declare const MirrorTarget: Type.TUnion<[Type.TObject<{
     project: Type.TString;
     handle: Type.TString;
-}>;
+    conversation: Type.TOptional<Type.TNever>;
+}>, Type.TObject<{
+    project: Type.TString;
+    conversation: Type.TString;
+    handle: Type.TOptional<Type.TNever>;
+}>]>;
 export type MirrorTarget = Static<typeof MirrorTarget>;
 /** Whether the data of a session entry is a mirror target. */
 export declare function isMirrorTarget(data: unknown): data is MirrorTarget;
-/** The Pi flags that open a mirror session of a target: the project, and the child in place of the project agent. */
+/**
+ * The Pi flags that open a mirror session of a target: the project, and the child or the conversation in place of the
+ * project agent.
+ */
 export declare const PI_FLAGS: {
     readonly project: "harness";
     readonly child: "harness-child";
+    readonly conversation: "harness-conversation";
 };
 /** The arguments of `pi` that open a mirror session of `target`. */
 export declare function piArgs(target: MirrorTarget): string[];
 /**
  * The arguments of the `harness` CLI that open `target` in Pi: `<project>` for the project agent, `--project <project>
- * attach <handle>` for a child.
+ * attach <handle>` for a child, and `--project <project> attach --conversation <id>` for a conversation.
  */
 export declare function harnessArgs(target: MirrorTarget): string[];
-/** The title of the agent of `target` before the host gives its name. */
+/** The title of the agent of `target` before the host gives its name: the handle or the conversation ID of a child. */
 export declare function targetTitle(target: MirrorTarget): string;
 /** A change of the model or the thinking level of the mirrored conversation. */
 export type MirrorConfigure = Omit<Extract<Request, {
@@ -73,7 +85,10 @@ export declare class Mirror {
     send(message: string, followUp: boolean): Promise<void>;
     /** Aborts the turn, and gives the texts of the queued messages that the host withdraws, steers first. */
     abort(): Promise<string[]>;
-    /** Changes the model or the thinking level. The host refuses a model it does not know and a level it does not have. */
+    /**
+     * Changes the model or the thinking level. The host refuses a model it does not know and a level it does not have. A
+     * conversation of the children library refuses it without a request.
+     */
     configure(change: MirrorConfigure): Promise<void>;
     /** Closes the connection and stops connecting. The conversation keeps running in the host. */
     close(): void;