@vzlentin/harness 0.3.0 → 0.3.1

package/README.md

@@ -61,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/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

@@ -24,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.`);
@@ -182,12 +183,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 +203,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() },

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;

package/dist/mirror.js

@@ -13,28 +13,46 @@ import { applyChange } from "./view-change.js";
 import { inboxOf, withdrawnTexts } from "./view-state.js";
 /** The `customType` of the session entry that holds the target of a mirror session. */
 export const MIRROR_ENTRY = "harness-mirror";
-/** The conversation that a mirror session shows: the child or project agent `handle` of the host of `project`. */
-export const MirrorTarget = Type.Object({ project: Type.String(), handle: Type.String() });
+/**
+ * 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 const MirrorTarget = Type.Union([
+    Type.Object({ project: Type.String(), handle: Type.String(), conversation: Type.Optional(Type.Never()) }),
+    Type.Object({ project: Type.String(), conversation: Type.String(), handle: Type.Optional(Type.Never()) }),
+]);
 /** Whether the data of a session entry is a mirror target. */
 export function isMirrorTarget(data) {
     return Value.Check(MirrorTarget, data);
 }
-/** The Pi flags that open a mirror session of a target: the project, and the child in place of the project agent. */
-export const PI_FLAGS = { project: "harness", child: "harness-child" };
+/**
+ * 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 const PI_FLAGS = { project: "harness", child: "harness-child", conversation: "harness-conversation" };
 /** The arguments of `pi` that open a mirror session of `target`. */
 export function piArgs(target) {
-    const child = target.handle === AGENT_HANDLE ? [] : [`--${PI_FLAGS.child}`, target.handle];
+    const child = target.conversation !== undefined
+        ? [`--${PI_FLAGS.conversation}`, target.conversation]
+        : target.handle === AGENT_HANDLE
+            ? []
+            : [`--${PI_FLAGS.child}`, target.handle];
     return [`--${PI_FLAGS.project}`, target.project, ...child];
 }
 /**
  * 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 function harnessArgs(target) {
+    if (target.conversation !== undefined) {
+        return ["--project", target.project, "attach", "--conversation", target.conversation];
+    }
     return target.handle === AGENT_HANDLE ? [target.project] : ["--project", target.project, "attach", target.handle];
 }
-/** 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 function targetTitle(target) {
+    if (target.conversation !== undefined)
+        return target.conversation;
     return target.handle === AGENT_HANDLE ? `${target.project} agent` : target.handle;
 }
 const RETRY_DELAYS_MS = [0, 2000, 5000];
@@ -51,6 +69,8 @@ const HOST_CLOSED = "The harness host closed the connection";
  */
 export class Mirror {
     target;
+    /** The target of the requests: the handle or the conversation of `target`, without the project. */
+    #ref;
     #onChange;
     #retryDelaysMs;
     #start;
@@ -65,6 +85,7 @@ export class Mirror {
     #sending = false;
     constructor(target, onChange, options = {}) {
         this.target = target;
+        this.#ref = target.conversation === undefined ? { handle: target.handle } : { conversation: target.conversation };
         this.#onChange = onChange;
         this.#retryDelaysMs = options.retryDelaysMs ?? RETRY_DELAYS_MS;
         this.#start = options.start ?? true;
@@ -105,13 +126,20 @@ export class Mirror {
     async abort() {
         const { client, view } = this.#connection();
         const texts = withdrawnTexts(inboxOf(view));
-        this.#setChild(await client.request({ type: "abort", handle: this.target.handle }));
+        this.#setChild(await client.request({ type: "abort", ...this.#ref }));
         return texts;
     }
-    /** 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.
+     */
     async configure(change) {
+        const { handle } = this.target;
+        if (handle === undefined) {
+            throw new Error("A conversation of the children library keeps its model and thinking level");
+        }
         const { client } = this.#connection();
-        this.#setChild(await client.request({ type: "configure", handle: this.target.handle, ...change }));
+        this.#setChild(await client.request({ type: "configure", handle, ...change }));
     }
     /** Closes the connection and stops connecting. The conversation keeps running in the host. */
     close() {
@@ -168,7 +196,7 @@ export class Mirror {
                 client = await connect({ start: this.#start, project: this.target.project, signal });
                 if (client === undefined)
                     throw new Error("Could not connect to the harness host");
-                const watched = await client.watch(this.target.handle);
+                const watched = await client.watch(this.#ref);
                 if (signal.aborted) {
                     client.close();
                     break;
@@ -210,7 +238,7 @@ export class Mirror {
                     const reply = await client.request({
                         type: "input",
                         requestId,
-                        handle: this.target.handle,
+                        ...this.#ref,
                         message,
                         followUp,
                     });

package/dist/protocol.d.ts

@@ -5,16 +5,20 @@ import type { ConversationView, TaskId, TaskOutcome, TaskState } from "@earendil
 import { type Static, Type } from "typebox";
 import type { ViewChange } from "./view-change.ts";
 /** The version of the protocol between the CLI and the host. A client refuses a host with another version. */
-export declare const PROTOCOL_VERSION = 8;
+export declare const PROTOCOL_VERSION = 9;
 /**
  * The handle of the project agent, the host's root conversation, in `watch`, `input`, `abort` and `configure`. It is not
  * hex, so no child has it.
  */
 export declare const AGENT_HANDLE = "agent";
 export type ChildState = "busy" | "idle" | "error";
-/** One child as the host reports it. Provider, model and thinking level come from the child's agent. */
+/**
+ * One child as the host reports it. Provider, model and thinking level come from the child's agent. For a `{ conversation }`
+ * target, `handle` and `conversation` are the conversation ID, and `name` is the child's lineage key.
+ */
 export type ChildInfo = {
     readonly handle: string;
+    readonly conversation?: string;
     readonly name?: string;
     readonly state: ChildState;
     readonly provider: string;
@@ -41,6 +45,17 @@ export type TaskInfo = {
 export declare const Json: Type.TCyclic<{
     Json: Type.TUnion<[Type.TNull, Type.TBoolean, Type.TNumber, Type.TString, Type.TArray<Type.TRef<"Json">>, Type.TRecord<"^.*$", Type.TRef<"Json">>]>;
 }, "Json">;
+/**
+ * The target of `watch`, `input` and `abort`: a handle, or the ID of a conversation that the children library opened,
+ * such as a child of a task.
+ */
+export type Target = {
+    readonly handle: string;
+    readonly conversation?: never;
+} | {
+    readonly conversation: string;
+    readonly handle?: never;
+};
 /** One request line. The caller is `PI_SESSION_ID`, or `cli` without one. */
 export type Request = {
     readonly type: "hello";
@@ -91,15 +106,13 @@ export type Request = {
  * after each commit to the child's conversation and after each rename. Every other line on the connection stays a
  * reply, in request order. A connection carries one watch.
  */
- | {
+ | ({
     readonly type: "watch";
-    readonly handle: string;
-}
+} & Target)
 /** Stops the child's current turn. A mirror session sends it. */
- | {
+ | ({
     readonly type: "abort";
-    readonly handle: string;
-}
+} & Target)
 /**
  * A mirror session's change of the child's model or thinking level. It has no caller. A new model keeps the thinking level
  * when the model has it, and takes the nearest level that it has otherwise. The host refuses a level that the model
@@ -112,14 +125,13 @@ export type Request = {
     readonly model?: string;
     readonly thinking?: ModelThinkingLevel;
 }
-/** A mirror session's message to the child. It has no caller. */
- | {
+/** A mirror session's message to the child. It has no caller. A conversation takes it only while it works, as a steer. */
+ | ({
     readonly type: "input";
     readonly requestId: string;
-    readonly handle: string;
     readonly message: string;
     readonly followUp: boolean;
-}
+} & Target)
 /**
  * Starts a background task of the kind `kind`, a task of an entry in `entries.json`, in the root conversation.
  * A repeated `key` gives the first task, and its new kind, version and input are ignored. With `version`, a host
@@ -190,25 +202,45 @@ export declare const RequestLine: Type.TUnion<[Type.TObject<{
     type: Type.TLiteral<"stop">;
     caller: Type.TString;
     handle: Type.TString;
-}>, Type.TObject<{
+}>, Type.TUnion<[Type.TObject<{
     type: Type.TLiteral<"watch">;
     handle: Type.TString;
+    conversation: Type.TOptional<Type.TNever>;
 }>, Type.TObject<{
+    type: Type.TLiteral<"watch">;
+    conversation: Type.TString;
+    handle: Type.TOptional<Type.TNever>;
+}>]>, Type.TUnion<[Type.TObject<{
     type: Type.TLiteral<"abort">;
     handle: Type.TString;
+    conversation: Type.TOptional<Type.TNever>;
 }>, Type.TObject<{
+    type: Type.TLiteral<"abort">;
+    conversation: Type.TString;
+    handle: Type.TOptional<Type.TNever>;
+}>]>, Type.TObject<{
     type: Type.TLiteral<"configure">;
     handle: Type.TString;
     provider: Type.TOptional<Type.TString>;
     model: Type.TOptional<Type.TString>;
     thinking: Type.TOptional<Type.TString>;
-}>, Type.TObject<{
-    type: Type.TLiteral<"input">;
+}>, Type.TUnion<[Type.TObject<{
     requestId: Type.TString;
-    handle: Type.TString;
     message: Type.TString;
     followUp: Type.TBoolean;
+} & {
+    type: Type.TLiteral<"input">;
+    handle: Type.TString;
+    conversation: Type.TOptional<Type.TNever>;
 }>, Type.TObject<{
+    requestId: Type.TString;
+    message: Type.TString;
+    followUp: Type.TBoolean;
+} & {
+    type: Type.TLiteral<"input">;
+    conversation: Type.TString;
+    handle: Type.TOptional<Type.TNever>;
+}>]>, Type.TObject<{
     type: Type.TLiteral<"start">;
     kind: Type.TString;
     input: Type.TCyclic<{
@@ -292,23 +324,26 @@ export type StatePaths = {
 };
 export declare function statePaths(project: string): StatePaths;
 export declare function isValidRunName(value: string): boolean;
-/** The label of a child: its name, or its handle when it has no name. */
-export declare function childLabel(child: {
+type Labeled = {
     readonly handle: string;
     readonly name?: string | undefined;
-}): string;
+    readonly conversation?: string | undefined;
+};
+/** The label of a child: its name, or its handle when it has no name. */
+export declare function childLabel(child: Labeled): string;
 export declare function runDisplayName(metadata: {
     readonly handle: string;
     readonly name?: string | undefined;
 }): string;
-/** The title of a child in a client: `<name> (<handle>)`, or only the name for the project agent, which says what it is. */
-export declare function childTitle(child: {
-    readonly handle: string;
-    readonly name?: string | undefined;
-}): string;
+/**
+ * The title of a child in a client: `<name> (<handle>)`, or only the name for the project agent, which says what it is,
+ * and for a conversation, whose name is its key.
+ */
+export declare function childTitle(child: Labeled): string;
 /** The message of a thrown value. */
 export declare function errorMessage(cause: unknown): string;
 /** The line of one child in a list. */
 export declare function childLine(child: ChildInfo): string;
 /** Calls `onLine` with each line that arrives on `socket`, without its newline. */
 export declare function onLines(socket: Socket, onLine: (line: string) => void): void;
+export {};

package/dist/protocol.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 /** The version of the protocol between the CLI and the host. A client refuses a host with another version. */
-export const PROTOCOL_VERSION = 8;
+export const PROTOCOL_VERSION = 9;
 /**
  * The handle of the project agent, the host's root conversation, in `watch`, `input`, `abort` and `configure`. It is not
  * hex, so no child has it.
@@ -20,6 +20,26 @@ export const Json = Type.Cyclic({
         Type.Record(Type.String(), Type.Ref("Json")),
     ]),
 }, "Json");
+/**
+ * The request objects of `type` with `fields` and a target: one with `handle`, one with `conversation`. Each refuses the
+ * other key, because an object schema accepts extra keys.
+ */
+function targeted(type, fields) {
+    return Type.Union([
+        Type.Object({
+            ...fields,
+            type: Type.Literal(type),
+            handle: Type.String(),
+            conversation: Type.Optional(Type.Never()),
+        }),
+        Type.Object({
+            ...fields,
+            type: Type.Literal(type),
+            conversation: Type.String(),
+            handle: Type.Optional(Type.Never()),
+        }),
+    ]);
+}
 /**
  * The check of a request line on the host. It is looser than `Request`, so the host answers a spawn without `cwd` and an
  * unknown thinking level with its own errors.
@@ -52,8 +72,8 @@ export const RequestLine = Type.Union([
     Type.Object({ type: Type.Literal("list"), caller: Type.String() }),
     Type.Object({ type: Type.Literal("rename"), caller: Type.String(), handle: Type.String(), name: Type.String() }),
     Type.Object({ type: Type.Literal("stop"), caller: Type.String(), handle: Type.String() }),
-    Type.Object({ type: Type.Literal("watch"), handle: Type.String() }),
-    Type.Object({ type: Type.Literal("abort"), handle: Type.String() }),
+    targeted("watch", {}),
+    targeted("abort", {}),
     Type.Object({
         type: Type.Literal("configure"),
         handle: Type.String(),
@@ -61,13 +81,7 @@ export const RequestLine = Type.Union([
         model: Type.Optional(Type.String()),
         thinking: Type.Optional(Type.String()),
     }),
-    Type.Object({
-        type: Type.Literal("input"),
-        requestId: Type.String(),
-        handle: Type.String(),
-        message: Type.String(),
-        followUp: Type.Boolean(),
-    }),
+    targeted("input", { requestId: Type.String(), message: Type.String(), followUp: Type.Boolean() }),
     Type.Object({
         type: Type.Literal("start"),
         kind: Type.String(),
@@ -106,9 +120,12 @@ export function childLabel(child) {
 export function runDisplayName(metadata) {
     return metadata.name ? `${metadata.name} (${metadata.handle})` : metadata.handle;
 }
-/** The title of a child in a client: `<name> (<handle>)`, or only the name for the project agent, which says what it is. */
+/**
+ * The title of a child in a client: `<name> (<handle>)`, or only the name for the project agent, which says what it is,
+ * and for a conversation, whose name is its key.
+ */
 export function childTitle(child) {
-    return child.handle === AGENT_HANDLE ? childLabel(child) : runDisplayName(child);
+    return child.handle === AGENT_HANDLE || child.conversation !== undefined ? childLabel(child) : runDisplayName(child);
 }
 /** The message of a thrown value. */
 export function errorMessage(cause) {

package/dist/targets.d.ts

@@ -0,0 +1,67 @@
+import * as durable from "@earendil-works/pi-durable";
+import { type Conversation, type ConversationId, type Harness } from "@earendil-works/pi-durable";
+import { type Child, type Input, type Owner, type Place } from "./children.ts";
+import { type ChildInfo, type Target } from "./protocol.ts";
+/** What the targets use of the host. */
+export type TargetHost = {
+    readonly harness: Harness;
+    /** The host's store, models and tools, for the children library. */
+    readonly place: Place;
+    readonly owner: Owner;
+    readonly project: string;
+    /** The project agent: the root conversation, with a model and the project directory from its first use. */
+    readonly agent: () => Promise<Conversation>;
+};
+export type ChildRecord = {
+    name?: string;
+    /** `PI_SESSION_ID` of the spawner: a Pi session, the conversation ID of another child, or `cli`. */
+    caller: string;
+    createdAt: string;
+    conversationId: ConversationId;
+    /** The request IDs of the spawn and of each `send` of the caller, in order. */
+    sent?: string[];
+    /** How many requests of `sent` a `wait` gave the answer of. */
+    read?: number;
+};
+export type ChildrenState = {
+    children: Record<string, ChildRecord>;
+    requests: Record<string, 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.
+ */
+export declare const Children: durable.SessionDocToken<ChildrenState>;
+/** The children library, on this process's pi-durable. */
+export declare const library: import("./children.ts").Children;
+/**
+ * The conversation of `ref`: a child or the project agent by handle, or a conversation of the children library by ID,
+ * with its info, its input, and the record of a child.
+ */
+export declare function target(handler: TargetHost, ref: Target): Promise<{
+    conversation: Conversation;
+    info: () => Promise<ChildInfo>;
+    send: (input: Input) => Promise<void>;
+    record: undefined;
+} | {
+    conversation: Conversation;
+    info: () => Promise<ChildInfo>;
+    send: (input: Input) => Promise<void>;
+    record: ChildRecord;
+}>;
+export type Found = Awaited<ReturnType<typeof target>>;
+/** The target of the child `handle`, whose record is `record`. */
+export declare function childTarget(handler: TargetHost, handle: string, record: ChildRecord): Promise<{
+    conversation: Conversation;
+    info: () => Promise<ChildInfo>;
+    send: (input: Input) => Promise<void>;
+    record: ChildRecord;
+}>;
+export declare function childRecord(harness: Harness, handle: string): Promise<ChildRecord>;
+/** The record of `handle`, which must belong to `caller`. */
+export declare function ownRecord(harness: Harness, handle: string, caller: string): Promise<ChildRecord>;
+export declare function childOf(handler: Pick<TargetHost, "place" | "owner">, record: ChildRecord): Promise<Child>;
+/** The info of `handle`. A caller that already has the record gives it as `record`. */
+export declare function childInfo(handler: Pick<TargetHost, "harness" | "place" | "owner">, handle: string, record?: ChildRecord): Promise<ChildInfo>;
+/** The record of `handle` in the `Children` value `state`. */
+export declare function recordOf(state: Readonly<ChildrenState> | null | undefined, handle: string): ChildRecord | undefined;

package/dist/targets.js

@@ -0,0 +1,140 @@
+/**
+ * The targets of the host's requests: the children by handle, the project agent, and the conversations of the children
+ * library by ID, with the `Children` records of the host.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import * as durable from "@earendil-works/pi-durable";
+import { defineDoc } from "@earendil-works/pi-durable";
+import { createChildren } from "./children.js";
+import { AGENT_HANDLE } from "./protocol.js";
+const context = BACKGROUND_CONTEXT;
+/**
+ * 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.
+ */
+export 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. */
+export const library = createChildren(durable);
+/**
+ * The conversation of `ref`: a child or the project agent by handle, or a conversation of the children library by ID,
+ * with its info, its input, and the record of a child.
+ */
+export async function target(handler, ref) {
+    if (ref.conversation !== undefined)
+        return conversationTarget(handler, ref.conversation);
+    const { handle } = ref;
+    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 library conversation `id`, of any owner, such as a child of a task. It has no record, and it takes
+ * input only while it works.
+ */
+async function conversationTarget(handler, id) {
+    const child = await library.inspect(handler.place, id, context);
+    if (child === undefined)
+        throw new Error(`Unknown conversation: ${id}`);
+    const { conversation, lineage } = child;
+    const info = async () => {
+        const childState = await child.state(context);
+        const state = childState === "closed" ? "idle" : childState;
+        return { handle: id, conversation: id, name: lineage.key, state, ...(await agentFields(conversation)) };
+    };
+    return {
+        conversation,
+        info,
+        send: async (input) => {
+            if ((await child.state(context)) !== "busy")
+                throw new Error(`${lineage.key} takes input only while it works`);
+            // Small race: a turn that ends between the check and the submit starts a new turn; needs busy-only admission in
+            // pi-durable.
+            await conversation.submit({ ...input, whenBusy: "steer" }, context);
+        },
+        record: undefined,
+    };
+}
+/** The target of the child `handle`, whose record is `record`. */
+export 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,
+    };
+}
+export 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`. */
+export 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;
+}
+export 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;
+}
+/** The info of `handle`. A caller that already has the record gives it as `record`. */
+export 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 record of `handle` in the `Children` value `state`. */
+export function recordOf(state, handle) {
+    return state != null && Object.hasOwn(state.children, handle) ? state.children[handle] : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vzlentin/harness",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "A durable agent harness on Pi, starting with observable, persistent subagents",
 	"repository": {
 		"type": "git",

package/pi/attachment.ts

@@ -20,6 +20,7 @@ import { type ChildInfo, childLabel, childTitle, errorMessage } from "../dist/pr
 import { inboxOf, liveOf, queued, statusText } from "../dist/view-state.js";
 import { ChatView } from "./chat.ts";
 import { ModelSync } from "./model-sync.ts";
+import { ProgramStatusReport } from "./program-status.ts";
 import { usageLine } from "./usage-line.ts";
 
 /** The key of the status widget above the editor. */
@@ -40,6 +41,8 @@ export class Attachment {
 	#chat: ChatView | undefined;
 	/** The state of the agent for Herdr, made when the agent is first known. */
 	#reporter: AgentReporter | undefined;
+	/** The state of the agent for the terminal, made with the TUI. */
+	#programStatus: ProgramStatusReport | undefined;
 	#expanded = false;
 	#closed = false;
 
@@ -57,6 +60,7 @@ export class Attachment {
 			(ui, theme) => {
 				this.#ui = ui;
 				this.#theme = theme;
+				this.#programStatus ??= new ProgramStatusReport(ui.terminal);
 
 				return this.#status;
 			},
@@ -64,6 +68,7 @@ export class Attachment {
 		);
 		ctx.ui.setEditorComponent((ui, theme, keybindings) => new MirrorEditor(ui, theme, keybindings, this));
 		this.#mirror = new Mirror(target, (previous) => this.#update(previous));
+		this.#programStatus?.update(this.#mirror);
 		this.models = new ModelSync(pi, ctx, this.#mirror, (cause) => this.#notify(cause));
 	}
 
@@ -121,6 +126,7 @@ export class Attachment {
 		this.#ctx.ui.setWidget(WIDGET, undefined);
 		this.#ctx.ui.setEditorComponent(undefined);
 		void this.#reporter?.release();
+		this.#programStatus?.leave(this.#mirror);
 	}
 
 	/** Shows each change of the mirror, whose status was `previous` before it. */
@@ -135,6 +141,7 @@ export class Attachment {
 
 		if (status.kind === "failed" && previous.kind !== "failed") this.#showFailure(status.reason);
 		this.#reporter?.report(this.#mirror.busy);
+		this.#programStatus?.update(this.#mirror);
 
 		if (child !== undefined) this.#followAgent(child);
 		ui.requestRender();

package/pi/mirror.ts

@@ -1,8 +1,8 @@
 /**
  * Mirror sessions: a Pi session that shows a child or the agent of a harness project in Pi's own chat, and sends what
  * the user types to it. The agent runs in the host of the project; the session keeps only its target, in one custom
- * entry. `/harness [project]` opens one in a new session, and `pi --harness <project> [--harness-child <handle>]` in the
- * session that Pi starts with.
+ * entry. `/harness [project]` opens one in a new session, and `pi --harness <project> [--harness-child <handle> |
+ * --harness-conversation <id>]` in the session that Pi starts with.
  */
 
 import { homedir } from "node:os";
@@ -45,6 +45,12 @@ export function registerMirror(pi: ExtensionAPI): void {
 		description: "Show this subagent of the harness project in the new session, in place of the project agent",
 	});
 
+	pi.registerFlag(PI_FLAGS.conversation, {
+		type: "string",
+		description:
+			"Show this conversation of the children library of the harness project in the new session, in place of the project agent",
+	});
+
 	pi.registerEntryRenderer(MIRROR_ENTRY, (entry, options, theme) => {
 		if (attached?.entryId === entry.id) attached.restyle(theme, options.expanded);
 
@@ -125,15 +131,23 @@ function mirrorEntry(entries: readonly SessionEntry[]): MirrorEntry | undefined
 }
 
 /**
- * The mirror entry for `--harness <project>` and `--harness-child <handle>`, written in the session that Pi starts
- * with. Without a project, it is the project of `HARNESS_PROJECT` and Pi's working directory; without a child, the
- * project agent. It refuses a session with messages, such as one of `--continue`, because Pi's own agent answered there.
+ * The mirror entry for `--harness <project>`, `--harness-child <handle>` and `--harness-conversation <id>`, written in
+ * the session that Pi starts with. Without a project, it is the project of `HARNESS_PROJECT` and Pi's working
+ * directory; without a child or a conversation, the project agent. It refuses both a child and a conversation, and a
+ * session with messages, such as one of `--continue`, because Pi's own agent answered there.
  */
 function flagEntry(pi: ExtensionAPI, ctx: ExtensionContext): MirrorEntry | undefined {
 	const project = stringFlag(pi, PI_FLAGS.project);
 	const child = stringFlag(pi, PI_FLAGS.child);
+	const conversation = stringFlag(pi, PI_FLAGS.conversation);
+
+	if (project === undefined && child === undefined && conversation === undefined) return undefined;
 
-	if (project === undefined && child === undefined) return undefined;
+	if (child && conversation) {
+		ctx.ui.notify("harness: use --harness-child or --harness-conversation, not both", "error");
+
+		return undefined;
+	}
 
 	if (ctx.sessionManager.getBranch().some((entry) => entry.type === "message")) {
 		ctx.ui.notify("harness: --harness needs a new session, not one with messages", "error");
@@ -144,10 +158,8 @@ function flagEntry(pi: ExtensionAPI, ctx: ExtensionContext): MirrorEntry | undef
 	let target: MirrorTarget;
 
 	try {
-		target = {
-			project: project ? checkProject(project) : resolveProject(process.env, ctx.cwd),
-			handle: child || AGENT_HANDLE,
-		};
+		const name = project ? checkProject(project) : resolveProject(process.env, ctx.cwd);
+		target = conversation ? { project: name, conversation } : { project: name, handle: child || AGENT_HANDLE };
 	} catch (error) {
 		ctx.ui.notify(`harness: ${errorMessage(error)}`, "error");
 

package/pi/program-status.ts

@@ -0,0 +1,66 @@
+/**
+ * The state of the agent of a mirror session for the terminal, with the Program Status Protocol (OSC 7501): `working`
+ * while it works, `error` when its last request failed, and `idle` in all other cases.
+ */
+import type { ProgramStatus, Terminal } from "@earendil-works/pi-tui";
+import { type Mirror, targetTitle } from "../dist/mirror.js";
+import { childTitle } from "../dist/protocol.js";
+
+/** The program name of each report. */
+const APP = "harness";
+
+type Mirrored = Pick<Mirror, "target" | "status" | "child" | "view" | "busy">;
+
+/** The title of the agent of `mirror`. */
+function title({ target, child }: Pick<Mirrored, "target" | "child">): string {
+	return child === undefined ? targetTitle(target) : childTitle(child);
+}
+
+/** The first line of the error of the last failed request, or `Error` when there is none. */
+function errorLine({ view }: Pick<Mirrored, "view">): string {
+	const failed = view?.entries.findLast((entry) => {
+		const message = entry.model?.[0];
+
+		return entry.kind === "pi.assistant" && message?.role === "assistant" && message.stopReason === "error";
+	})?.model?.[0];
+
+	const text = failed?.role === "assistant" ? failed.errorMessage : undefined;
+
+	return text?.split(/\r?\n/, 1)[0]?.trim() || "Error";
+}
+
+/** The state of the agent of `mirror`. */
+function programStatus(mirror: Mirrored): ProgramStatus {
+	if (mirror.busy) return { state: "working", app: APP, message: title(mirror) };
+
+	if (mirror.status.kind === "open" && mirror.child?.state === "error") {
+		return { state: "error", app: APP, message: errorLine(mirror) };
+	}
+
+	return { state: "idle", app: APP, message: title(mirror) };
+}
+
+export class ProgramStatusReport {
+	readonly #terminal: Pick<Terminal, "setProgramStatus">;
+	/** The state and the message of the last report. */
+	#last: string | undefined;
+
+	constructor(terminal: Pick<Terminal, "setProgramStatus">) {
+		this.#terminal = terminal;
+	}
+
+	/** Reports the state of the agent of `mirror` when its state or its message changed since the last report. */
+	update(mirror: Mirrored): void {
+		const report = programStatus(mirror);
+		const key = `${report.state}\n${report.message}`;
+
+		if (key === this.#last) return;
+		this.#last = key;
+		this.#terminal.setProgramStatus(report);
+	}
+
+	/** Reports `idle` one more time, when Pi leaves the session of `mirror`. */
+	leave(mirror: Pick<Mirrored, "target" | "child">): void {
+		this.#terminal.setProgramStatus({ state: "idle", app: APP, message: title(mirror) });
+	}
+}