@vzlentin/harness 0.2.3 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 Observable, persistent subagents 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 watch it live in a viewer.
+host process. You can spawn it, check its status, wait for its answer, steer it, and talk to it live in Pi.
 
 ## Install
 
@@ -14,9 +14,9 @@ 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` command 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:
+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
+`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")"
@@ -39,12 +39,15 @@ harness spawn --name review --prompt "Review the current diff"
 harness list
 harness wait <handle>
 harness send <handle> "Focus on error handling"
-harness attach <handle>     # live viewer
+harness attach <handle>     # open it in Pi
 harness stop <handle>
-harness main                # talk to the agent of the main project
+harness main                # open the agent of the main project in Pi
 ```
 
-[docs/spec.md](docs/spec.md) describes all the commands, the tool, the viewer, projects, the host and its state.
+In Pi, `/harness <project>` opens a session that shows the agent of the project in Pi's own chat, and sends what you
+type to it. Without a project, it asks for one. `pi --harness <project>` starts Pi in such a session.
+
+[docs/spec.md](docs/spec.md) describes all the commands, the tool, the Pi extension, projects, the host and its state.
 
 ## Development
 
@@ -58,5 +61,5 @@ XDG_STATE_HOME=/tmp/harness-dev node src/cli.ts list
 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
+`postinstall` script. To release, merge the release PR `release: <version>` that CI keeps open: CI then publishes that version. `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/`.

package/dist/answer.js

@@ -5,7 +5,7 @@
 import { copyJson } from "@earendil-works/chord";
 import { Type, validateToolArguments } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
-import { Json } from "./protocol.js";
+import { errorMessage, Json } from "./protocol.js";
 /**
  * The user message that asks again for a `respond` call after an answer of a `schema` ask without one. A reminder is
  * known by its exact text, so a user prompt with the same text counts as one.
@@ -49,7 +49,7 @@ export function createAnswers(durable) {
             catch (error) {
                 return {
                     isError: true,
-                    output: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+                    output: [{ type: "text", text: errorMessage(error) }],
                 };
             }
             await api.commit(async (tx) => {

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,9 +1,13 @@
 #!/usr/bin/env node
+import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
-import { addProject, checkProject, MAIN_PROJECT, projectDir, readProjects } from "./projects.js";
-import { AGENT_HANDLE, statePaths } from "./protocol.js";
-import { setupOnce } from "./setup.js";
+import { request } from "./client.js";
+import { piEnv } from "./herdr.js";
+import { piArgs } from "./mirror.js";
+import { addProject, checkProject, MAIN_PROJECT, projectDir, readProjects, resolveProject } from "./projects.js";
+import { AGENT_HANDLE, errorMessage, statePaths } from "./protocol.js";
+import { setupOnce, userPath } from "./setup.js";
 import { runTool, sendToHost } from "./tool.js";
 function fail(message) {
     throw new Error(message);
@@ -20,6 +24,7 @@ function usage() {
   harness stop <handle>
   harness list
   harness attach <handle>
+  harness attach --conversation <id>
   harness create <name> --cwd <dir>
   harness projects
 Any command but harness <project> takes --project <name> before it; without it, the project is HARNESS_PROJECT, then the cwd.`);
@@ -178,25 +183,42 @@ async function hostCommand(args, project) {
     await host.closed;
     process.exit(0);
 }
-/** Opens the viewer of a child 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 openViewer(handle);
+    await openInPi({ project: resolveProject(process.env, process.cwd()), ...ref });
 }
-/** Opens the viewer of the agent of the project `name`, which is `main` or a project, in this terminal. */
+/** Opens the agent of the project `name`, which is `main` or a project, in Pi in this terminal. */
 async function agentCommand(name, project) {
     if (project !== undefined)
         fail(`harness ${name} takes no --project`);
-    // The viewer's connection resolves the project from the env.
-    process.env.HARNESS_PROJECT = name;
-    await openViewer(AGENT_HANDLE);
+    await openInPi({ project: name, handle: AGENT_HANDLE });
 }
-async function openViewer(handle) {
-    const { ProcessTerminal } = await import("@earendil-works/pi-tui");
-    const { attach } = await import("./viewer.js");
-    process.exitCode = await attach(handle, { terminal: new ProcessTerminal(), env: process.env });
+/**
+ * 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, an unknown conversation and a
+ * project agent without a model.
+ */
+async function openInPi(target) {
+    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() },
+    });
+    if (result.error !== undefined && "code" in result.error && result.error.code === "ENOENT") {
+        fail("pi is not on PATH. Install Pi to open the agent");
+    }
+    if (result.error !== undefined)
+        throw result.error;
+    process.exitCode = result.status ?? 1;
 }
 /**
  * Runs a command as a call of the `subagent` tool. The caller is `PI_SESSION_ID`, or `cli` outside Pi, and the defaults
@@ -246,6 +268,6 @@ async function main() {
     process.stdout.write(text);
 }
 main().catch((cause) => {
-    process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`);
+    process.stderr.write(`${errorMessage(cause)}\n`);
     process.exitCode = 1;
 });

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.
@@ -11,14 +11,16 @@ export declare class Client {
     /** The project of the host. `connect` sets it. */
     project: string;
     constructor(socket: Socket);
+    /** Whether the connection closed. A request that failed then may have reached the host or not. */
+    get ended(): boolean;
     request<T extends Request["type"]>(request: Extract<Request, {
         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;
@@ -26,14 +28,16 @@ export declare class Client {
     abort(cause: unknown): void;
 }
 /**
- * A connection to the host of the project of `HARNESS_PROJECT` or the cwd (see `resolveProject`), after its `hello`.
- * When no host listens and `start` is true, it starts one, detached, with its output in `host.log`, and tries to
- * connect for 10 s, or until `signal` aborts. When no host listens and `start` is false, it is undefined.
+ * A connection to the host of `project`, or of the project of `HARNESS_PROJECT` or the cwd (see `resolveProject`),
+ * after its `hello`. When no host listens and `start` is true, it starts one, detached, with its output in `host.log`,
+ * and tries to connect for 10 s, or until `signal` aborts. When no host listens and `start` is false, it is undefined.
  */
 export declare function connect(options: ConnectOptions): Promise<Client | undefined>;
 type ConnectOptions = {
     readonly start: boolean;
     readonly signal?: AbortSignal | undefined;
+    /** `main` or a project name. Without it, the project comes from `HARNESS_PROJECT` and the cwd. */
+    readonly project?: string;
 };
 type OneShot<T extends Request["type"]> = Extract<Request, {
     type: T;

package/dist/client.js

@@ -4,7 +4,7 @@ import { createConnection } from "node:net";
 import { Readable } from "node:stream";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
-import { MAIN_PROJECT, resolveProject } from "./projects.js";
+import { checkProject, MAIN_PROJECT, resolveProject } from "./projects.js";
 import { cliPath, onLines, PROTOCOL_VERSION, statePaths, } from "./protocol.js";
 const START_TIMEOUT_MS = 10_000;
 /** A line from the host: a reply, or an event of the watch. The value of a reply and the event are not checked here. */
@@ -50,6 +50,10 @@ export class Client {
         socket.on("error", () => this.#end());
         socket.on("close", () => this.#end());
     }
+    /** Whether the connection closed. A request that failed then may have reached the host or not. */
+    get ended() {
+        return this.#ended;
+    }
     request(request) {
         if (this.#ended)
             return Promise.reject(new Error("The harness host closed the connection"));
@@ -61,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() {
@@ -87,12 +92,12 @@ export class Client {
     }
 }
 /**
- * A connection to the host of the project of `HARNESS_PROJECT` or the cwd (see `resolveProject`), after its `hello`.
- * When no host listens and `start` is true, it starts one, detached, with its output in `host.log`, and tries to
- * connect for 10 s, or until `signal` aborts. When no host listens and `start` is false, it is undefined.
+ * A connection to the host of `project`, or of the project of `HARNESS_PROJECT` or the cwd (see `resolveProject`),
+ * after its `hello`. When no host listens and `start` is true, it starts one, detached, with its output in `host.log`,
+ * and tries to connect for 10 s, or until `signal` aborts. When no host listens and `start` is false, it is undefined.
  */
 export async function connect(options) {
-    const project = resolveProject(process.env, process.cwd());
+    const project = options.project === undefined ? resolveProject(process.env, process.cwd()) : checkProject(options.project);
     const paths = statePaths(project);
     let socket = await tryConnect(paths.socket);
     if (socket === undefined) {

package/dist/context.js

@@ -7,6 +7,7 @@ import { join } from "node:path";
 import { createFindTool, createGrepTool, createLsTool, DefaultPackageManager, formatSkillsForPrompt, getAgentDir, loadProjectContextFiles, loadSkills, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { defineExtension, defineTool, section, } from "@earendil-works/pi-durable";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@earendil-works/pi-durable/tools";
+import { errorMessage } from "./protocol.js";
 import { savedTrust } from "./trust.js";
 /** A Pi coding agent tool as a durable tool that runs in the calling conversation's directory. */
 function piTool(create) {
@@ -45,7 +46,7 @@ async function resourcesOf(cwd) {
         return await found;
     }
     catch (error) {
-        process.stderr.write(`warning: ${cwd}: ${error instanceof Error ? error.message : String(error)}; no project instructions or skills\n`);
+        process.stderr.write(`warning: ${cwd}: ${errorMessage(error)}; no project instructions or skills\n`);
         return { context: [], skills: [] };
     }
 }

package/dist/herdr.d.ts

@@ -1,38 +1,40 @@
+import { type MirrorTarget } from "./mirror.ts";
 import { type ChildInfo } from "./protocol.ts";
-export type ViewerTarget = {
-    title(child: ChildInfo): string;
-    project: string[];
-    resume: string[];
-};
 export type AgentReporter = {
     report(busy: boolean): void;
     release(): Promise<void>;
 };
-/**
- * How the viewer of `handle` on `project` shows and resumes it: the title of its child, the `--project` words, and the
- * words after them that open it again. The project agent is `harness <project>`, with no `--project`; a child is
- * `harness --project <project> attach <handle>`.
- */
-export declare function viewerTarget(handle: string, project: string): ViewerTarget;
-/**
- * The words of the command that runs the viewer of `handle`, 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`.
- */
-export declare function viewerCommand(handle: string, project: string): string[];
+/** Whether this process runs in a Herdr pane, also as the Pi that the CLI starts there. */
+export declare function inHerdr(env: NodeJS.ProcessEnv): boolean;
+/** The environment of the Pi that the CLI starts: in a Herdr pane, `HARNESS_HERDR_PANE` in place of `HERDR_ENV`. */
+export declare function piEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /**
  * Runs `herdr` with `args` and gives its output. When `herdr` fails, it rejects with the stderr of `herdr`, or with the
  * error of `execFile` when stderr is empty.
  */
 export declare function herdr(args: readonly string[], env: NodeJS.ProcessEnv): Promise<string>;
 /**
- * Opens a Herdr tab that runs the viewer of `child`, on the project of `env` and this process's cwd. It rejects when a
+ * Opens a Herdr tab that opens `child` in Pi, on the project of `env` and this process's cwd. It rejects when a
  * `herdr` call fails or gives no pane ID.
  */
-export declare function openViewerTab(child: ChildInfo, env: NodeJS.ProcessEnv): Promise<void>;
+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 this process, with the viewer of `handle` on `project` as
- * the resume command. Both methods do nothing outside Herdr.
- * The calls run one after another, so `--seq` reaches Herdr in order.
+ * 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
+ * started in a Herdr pane reports. The calls run one after another, so `--seq` reaches Herdr in order.
  */
-export declare function agentReporter(env: NodeJS.ProcessEnv, label: string, handle: string, project: string): AgentReporter;
+export declare function agentReporter(env: NodeJS.ProcessEnv, label: string, target: MirrorTarget): AgentReporter;

package/dist/herdr.js

@@ -1,31 +1,53 @@
 import { execFile } from "node:child_process";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
+import { harnessArgs } from "./mirror.js";
 import { resolveProject } from "./projects.js";
-import { AGENT_HANDLE, childLabel, cliPath, runDisplayName } from "./protocol.js";
+import { childLabel, cliPath } from "./protocol.js";
 const HERDR_SOURCE = "custom:harness";
+/**
+ * The variable that gives the Herdr pane to the Pi that the CLI starts there, in place of `HERDR_ENV`. Without
+ * `HERDR_ENV`, Herdr's own Pi integration does not report, so the pane shows the state of the mirrored agent, which the
+ * extension reports, and not the state of Pi's own agent, which does not run.
+ */
+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() }) }) });
 /**
- * How the viewer of `handle` on `project` shows and resumes it: the title of its child, the `--project` words, and the
- * words after them that open it again. The project agent is `harness <project>`, with no `--project`; a child is
- * `harness --project <project> attach <handle>`.
+ * 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`.
  */
-export function viewerTarget(handle, project) {
-    // The agent's name already says what it is; a child's shows its handle too.
-    if (handle === AGENT_HANDLE)
-        return { title: childLabel, project: [], resume: [project] };
-    return { title: runDisplayName, project: ["--project", project], resume: ["attach", handle] };
+function openCommand(target) {
+    return ["env", process.execPath, cliPath(), ...harnessArgs(target)];
 }
-/**
- * The words of the command that runs the viewer of `handle`, 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`.
- */
-export function viewerCommand(handle, project) {
-    const cli = cliPath();
-    const target = viewerTarget(handle, project);
-    return ["env", process.execPath, cli, ...target.project, ...target.resume];
+/** 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]);
+}
+/** The environment of the Pi that the CLI starts: in a Herdr pane, `HARNESS_HERDR_PANE` in place of `HERDR_ENV`. */
+export function piEnv(env) {
+    const { HERDR_ENV, ...rest } = env;
+    return HERDR_ENV && env.HERDR_PANE_ID ? { ...rest, [PANE_VARIABLE]: env.HERDR_PANE_ID } : env;
 }
 /**
  * Runs `herdr` with `args` and gives its output. When `herdr` fails, it rejects with the stderr of `herdr`, or with the
@@ -42,24 +64,61 @@ export function herdr(args, env) {
     });
 }
 /**
- * Opens a Herdr tab that runs the viewer of `child`, on the project of `env` and this process's cwd. It rejects when a
+ * Opens a Herdr tab that opens `child` in Pi, on the project of `env` and this process's cwd. It rejects when a
  * `herdr` call fails or gives no pane ID.
  */
-export async function openViewerTab(child, 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 {
@@ -70,20 +129,16 @@ export async function openViewerTab(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 viewer = viewerCommand(child.handle, project)
-        .map((word) => `'${word.replaceAll("'", "'\\''")}'`)
-        .join(" ");
-    await herdr(["pane", "run", pane, viewer], env);
+    await runOpen(output.result.root_pane.pane_id, target, env);
 }
 /**
- * Reports the state of the agent `label` to the Herdr pane of this process, with the viewer of `handle` on `project` as
- * the resume command. Both methods do nothing outside Herdr.
- * The calls run one after another, so `--seq` reaches Herdr in order.
+ * 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
+ * started in a Herdr pane reports. The calls run one after another, so `--seq` reaches Herdr in order.
  */
-export function agentReporter(env, label, handle, project) {
-    const pane = env.HERDR_ENV ? env.HERDR_PANE_ID : undefined;
-    const resume = pane === undefined ? [] : ["--", ...viewerCommand(handle, project)];
+export function agentReporter(env, label, target) {
+    const pane = env[PANE_VARIABLE] || undefined;
+    const resume = pane === undefined ? [] : ["--", ...openCommand(target)];
     let calls = Promise.resolve();
     let seq = 0;
     let reported;

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-import { type Models } from "@earendil-works/pi-ai/models";
+import type { Models } from "@earendil-works/pi-ai/models";
 export type Host = {
     /** Resolves once the host has closed, by `close()`, the idle exit, or a store failure. */
     readonly closed: Promise<void>;