@vzlentin/harness 0.2.2 → 0.3.0

package/dist/load-entries.d.ts

@@ -0,0 +1,18 @@
+import { type SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { AnyTask, Extension } from "@earendil-works/pi-durable";
+import type { createChildren, Place } from "./children.ts";
+type ChildrenLibrary = ReturnType<typeof createChildren>;
+/** What the default export of an entry returns: its extensions, the tasks that `start` runs, and `close`. */
+export type Entry = {
+    readonly extensions: readonly Extension[];
+    readonly tasks?: readonly AnyTask[];
+    close(): Promise<void>;
+};
+/**
+ * The `piDurable` entries of the installed packages in Pi's `settingsManager` for `cwd`, then the entries of
+ * `entries.json` (see `readEntries`), with the children library `children`, in one shared event bus, as one entry whose `close()` closes each of them and
+ * passes its errors to `warn`. When an entry fails to load, the entries loaded before it close. Missing packages are
+ * skipped, not installed, and so is an entry module that does not exist, such as one of an uninstalled package.
+ */
+export declare function loadEntries(cwd: string, agentDir: string, settingsManager: SettingsManager, place: Place, children: ChildrenLibrary, warn: (cause: unknown) => void): Promise<Required<Entry>>;
+export {};

package/dist/load-entries.js

@@ -0,0 +1,91 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * The entries that the host loads: the `piDurable` entries of Pi's packages and the entries of `entries.json`. Each
+ * entry is a module whose default export gives extensions and tasks to the host.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve as resolvePath, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import * as ai from "@earendil-works/pi-ai";
+import { createEventBus, DefaultPackageManager, } from "@earendil-works/pi-coding-agent";
+import * as durable from "@earendil-works/pi-durable";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { readEntries } from "./entries.js";
+/** A `package.json`, which is a JSON object. */
+const PackageJson = Type.Object({});
+/** The part of a package's `package.json` that names its entries. */
+const Manifest = Type.Object({
+    piDurable: Type.Optional(Type.Object({ extensions: Type.Optional(Type.Array(Type.String())) })),
+});
+/**
+ * The `piDurable` entries of the installed packages in Pi's `settingsManager` for `cwd`, then the entries of
+ * `entries.json` (see `readEntries`), with the children library `children`, in one shared event bus, as one entry whose `close()` closes each of them and
+ * passes its errors to `warn`. When an entry fails to load, the entries loaded before it close. Missing packages are
+ * skipped, not installed, and so is an entry module that does not exist, such as one of an uninstalled package.
+ */
+export async function loadEntries(cwd, agentDir, settingsManager, place, children, warn) {
+    const modules = new Set();
+    const roots = new DefaultPackageManager({ cwd, agentDir, settingsManager })
+        .listConfiguredPackages()
+        .flatMap((found) => found.installedPath ?? []);
+    for (const root of new Set(roots)) {
+        const path = join(root, "package.json");
+        const manifest = JSON.parse(await readFile(path, "utf8").catch(() => "{}"));
+        if (!Value.Check(PackageJson, manifest)) {
+            warn(new Error(`${path} is not a valid package.json`));
+            continue;
+        }
+        if (!Value.Check(Manifest, manifest)) {
+            warn(new Error(`${path} has an invalid piDurable field`));
+            continue;
+        }
+        for (const path of manifest.piDurable?.extensions ?? [])
+            modules.add(resolvePath(root, path));
+    }
+    for (const module of Object.values(readEntries()))
+        if (existsSync(module))
+            modules.add(module);
+    const events = createEventBus();
+    const entries = [];
+    const close = async () => {
+        for (const result of await Promise.allSettled(entries.map((entry) => entry.close()))) {
+            if (result.status === "rejected")
+                warn(result.reason);
+        }
+    };
+    try {
+        for (const module of modules) {
+            const entry = await importEntry(module);
+            entries.push(await entry.default({ durable, ai, events, children, place }));
+        }
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+    return {
+        extensions: entries.flatMap((entry) => entry.extensions),
+        tasks: entries.flatMap((entry) => entry.tasks ?? []),
+        close,
+    };
+}
+/**
+ * Imports the entry `module`. Node does not strip types under `node_modules`, where Pi installs npm packages, so jiti
+ * loads a TypeScript entry there.
+ */
+async function importEntry(module) {
+    if (module.endsWith(".ts") && module.split(sep).includes("node_modules")) {
+        const { createJiti } = await import("jiti");
+        return createJiti(import.meta.url).import(module);
+    }
+    return import(__rewriteRelativeImportExtension(pathToFileURL(module).href));
+}

package/dist/mirror.d.ts

@@ -0,0 +1,80 @@
+import type { ConversationView } from "@earendil-works/pi-durable";
+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<{
+    project: Type.TString;
+    handle: Type.TString;
+}>;
+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. */
+export declare const PI_FLAGS: {
+    readonly project: "harness";
+    readonly child: "harness-child";
+};
+/** 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.
+ */
+export declare function harnessArgs(target: MirrorTarget): string[];
+/** The title of the agent of `target` before the host gives its name. */
+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, {
+    type: "configure";
+}>, "type" | "handle">;
+/**
+ * The connection of a mirror: before the first one, open, connecting again after the host closed it, or failed for
+ * good, with the reason.
+ */
+export type MirrorStatus = {
+    readonly kind: "connecting" | "open" | "reconnecting";
+} | {
+    readonly kind: "failed";
+    readonly reason: string;
+};
+export type MirrorOptions = {
+    /** The waits before the tries to connect again after the host closed the connection. Default 0, 2 and 5 s. */
+    readonly retryDelaysMs?: readonly number[];
+    /** Whether a connection starts the host when none runs. Default true. */
+    readonly start?: boolean;
+};
+/**
+ * A live copy of one conversation of a harness host, and the requests that act on it. It connects at once, which starts
+ * the host when none runs, and connects again when the host closes the connection, with one try after each of
+ * `retryDelaysMs`. It fails for good when the first connection fails, when all the tries fail, when the child is
+ * stopped, and when the host closes a connection that was opened again less than 10 s before, so that a host that fails
+ * at each start does not start again and again. `onChange` runs after each change of `status`, `view` and `child`, with
+ * the status before the change.
+ */
+export declare class Mirror {
+    #private;
+    readonly target: MirrorTarget;
+    constructor(target: MirrorTarget, onChange: (previous: MirrorStatus) => void, options?: MirrorOptions);
+    get status(): MirrorStatus;
+    /** The conversation, as the last connection gave it. It is undefined before the first connection. */
+    get view(): ConversationView | undefined;
+    /** The child or the project agent, as the last connection gave it. It is undefined before the first connection. */
+    get child(): ChildInfo | undefined;
+    /** Whether the conversation works, as an open connection tells. */
+    get busy(): boolean;
+    /**
+     * Sends `message`: a new turn when the conversation is idle, else a steer, or a follow-up with `followUp`. It resolves
+     * once the host has the message. The message waits while the mirror connects. When its connection closes before the
+     * host answers, it goes again on the next connection with the same request ID, so that the host takes it once. It
+     * rejects when the host refuses the message, and when the mirror fails or closes before the host has it.
+     */
+    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. */
+    configure(change: MirrorConfigure): Promise<void>;
+    /** Closes the connection and stops connecting. The conversation keeps running in the host. */
+    close(): void;
+}

package/dist/mirror.js

@@ -0,0 +1,263 @@
+/**
+ * A mirror session is a Pi session that shows a conversation of a harness host and sends what the user types to it.
+ * The conversation stays in the host; the Pi session keeps only its target, in one custom entry. This module has no
+ * runtime import of Pi, chord or pi-durable, so the Pi extension can load it.
+ */
+import { randomUUID } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { connect } from "./client.js";
+import { AGENT_HANDLE, errorMessage, runDisplayName, } from "./protocol.js";
+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() });
+/** 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 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];
+    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.
+ */
+export function harnessArgs(target) {
+    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. */
+export function targetTitle(target) {
+    return target.handle === AGENT_HANDLE ? `${target.project} agent` : target.handle;
+}
+const RETRY_DELAYS_MS = [0, 2000, 5000];
+/** A connection that was opened again and ends sooner than this is not opened again: the host fails at each start. */
+const SHORT_CONNECTION_MS = 10_000;
+const HOST_CLOSED = "The harness host closed the connection";
+/**
+ * A live copy of one conversation of a harness host, and the requests that act on it. It connects at once, which starts
+ * the host when none runs, and connects again when the host closes the connection, with one try after each of
+ * `retryDelaysMs`. It fails for good when the first connection fails, when all the tries fail, when the child is
+ * stopped, and when the host closes a connection that was opened again less than 10 s before, so that a host that fails
+ * at each start does not start again and again. `onChange` runs after each change of `status`, `view` and `child`, with
+ * the status before the change.
+ */
+export class Mirror {
+    target;
+    #onChange;
+    #retryDelaysMs;
+    #start;
+    /** Stops the wait for a host that starts, and the waits between the tries, when the mirror closes. */
+    #closing = new AbortController();
+    /** The messages that the host does not have yet, in the order of `send`. */
+    #outgoing = [];
+    #status = { kind: "connecting" };
+    #view;
+    #child;
+    #client;
+    #sending = false;
+    constructor(target, onChange, options = {}) {
+        this.target = target;
+        this.#onChange = onChange;
+        this.#retryDelaysMs = options.retryDelaysMs ?? RETRY_DELAYS_MS;
+        this.#start = options.start ?? true;
+        void this.#run();
+    }
+    get status() {
+        return this.#status;
+    }
+    /** The conversation, as the last connection gave it. It is undefined before the first connection. */
+    get view() {
+        return this.#view;
+    }
+    /** The child or the project agent, as the last connection gave it. It is undefined before the first connection. */
+    get child() {
+        return this.#child;
+    }
+    /** Whether the conversation works, as an open connection tells. */
+    get busy() {
+        return this.#status.kind === "open" && this.#child?.state === "busy";
+    }
+    /**
+     * Sends `message`: a new turn when the conversation is idle, else a steer, or a follow-up with `followUp`. It resolves
+     * once the host has the message. The message waits while the mirror connects. When its connection closes before the
+     * host answers, it goes again on the next connection with the same request ID, so that the host takes it once. It
+     * rejects when the host refuses the message, and when the mirror fails or closes before the host has it.
+     */
+    send(message, followUp) {
+        if (this.#status.kind === "failed")
+            return Promise.reject(new Error(this.#status.reason));
+        if (this.#closing.signal.aborted)
+            return Promise.reject(new Error("The mirror is closed"));
+        const outgoing = { requestId: randomUUID(), message, followUp, sent: Promise.withResolvers() };
+        this.#outgoing.push(outgoing);
+        void this.#flush();
+        return outgoing.sent.promise;
+    }
+    /** Aborts the turn, and gives the texts of the queued messages that the host withdraws, steers first. */
+    async abort() {
+        const { client, view } = this.#connection();
+        const texts = withdrawnTexts(inboxOf(view));
+        this.#setChild(await client.request({ type: "abort", handle: this.target.handle }));
+        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. */
+    async configure(change) {
+        const { client } = this.#connection();
+        this.#setChild(await client.request({ type: "configure", handle: this.target.handle, ...change }));
+    }
+    /** Closes the connection and stops connecting. The conversation keeps running in the host. */
+    close() {
+        this.#closing.abort();
+        this.#client?.close();
+        this.#reject(new Error("The mirror is closed"));
+    }
+    /** Connects, follows the watch, and connects again after the host closed the connection, until a failure or `close()`. */
+    async #run() {
+        let attempt = await this.#connect([0]);
+        let again = false;
+        while (!(attempt instanceof Error)) {
+            const opened = Date.now();
+            this.#client = attempt.client;
+            this.#view = attempt.view;
+            this.#child = attempt.child;
+            this.#setStatus({ kind: "open" });
+            void this.#flush();
+            const end = await this.#follow(attempt.view, attempt.lines);
+            this.#client = undefined;
+            attempt.client.close();
+            if (this.#closing.signal.aborted)
+                return;
+            if (end === "stopped") {
+                this.#fail(`${runDisplayName(this.#child ?? attempt.child)} was stopped`);
+                return;
+            }
+            if (again && Date.now() - opened < SHORT_CONNECTION_MS) {
+                this.#fail(`${HOST_CLOSED}. Run /reload to attach again`);
+                return;
+            }
+            again = true;
+            this.#setStatus({ kind: "reconnecting" });
+            attempt = await this.#connect(this.#retryDelaysMs);
+        }
+        if (this.#closing.signal.aborted)
+            return;
+        this.#fail(again ? `${HOST_CLOSED}. Connecting again failed: ${attempt.message}` : attempt.message);
+    }
+    /**
+     * A connection with the watch of the target, after one try at each delay of `delays`. It is the error of the last try
+     * when all the tries fail, and an error after `close()`.
+     */
+    async #connect(delays) {
+        const { signal } = this.#closing;
+        let error = new Error("Could not connect to the harness host");
+        for (const delay of delays) {
+            if (delay > 0)
+                await sleep(delay, undefined, { signal }).catch(() => { });
+            if (signal.aborted)
+                break;
+            let client;
+            try {
+                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);
+                if (signal.aborted) {
+                    client.close();
+                    break;
+                }
+                return { ...watched, client };
+            }
+            catch (cause) {
+                client?.close();
+                error = new Error(errorMessage(cause));
+            }
+        }
+        return signal.aborted ? new Error("The mirror is closed") : error;
+    }
+    /** Applies each change of the watch until it ends: `stopped` when the child was stopped, else `closed`. */
+    async #follow(view, lines) {
+        let current = view;
+        for await (const line of lines) {
+            if (line.stopped)
+                return "stopped";
+            current = applyChange(current, line.change);
+            this.#view = current;
+            this.#child = line.child;
+            this.#onChange(this.#status);
+        }
+        return "closed";
+    }
+    /** Sends the waiting messages on the open connection, one at a time, in order. */
+    async #flush() {
+        if (this.#sending)
+            return;
+        this.#sending = true;
+        try {
+            for (let next = this.#outgoing[0]; next !== undefined; next = this.#outgoing[0]) {
+                const client = this.#client;
+                if (client === undefined)
+                    return;
+                const { requestId, message, followUp } = next;
+                try {
+                    const reply = await client.request({
+                        type: "input",
+                        requestId,
+                        handle: this.target.handle,
+                        message,
+                        followUp,
+                    });
+                    // `close()` and a failure settle the waiting messages themselves.
+                    if (this.#outgoing[0] !== next)
+                        return;
+                    this.#outgoing.shift();
+                    this.#setChild(reply.child);
+                    next.sent.resolve();
+                }
+                catch (error) {
+                    // After the end of the connection, the host may have the message or not, so it goes again.
+                    if (client.ended || this.#outgoing[0] !== next)
+                        return;
+                    this.#outgoing.shift();
+                    next.sent.reject(error);
+                }
+            }
+        }
+        finally {
+            this.#sending = false;
+        }
+    }
+    /** The open connection and its view, or an error without one. */
+    #connection() {
+        const client = this.#client;
+        const view = this.#view;
+        if (client === undefined || view === undefined)
+            throw new Error("Not connected to the harness host");
+        return { client, view };
+    }
+    #fail(reason) {
+        this.#reject(new Error(reason));
+        this.#setStatus({ kind: "failed", reason });
+    }
+    /** Rejects the waiting messages with `error`. */
+    #reject(error) {
+        for (const outgoing of this.#outgoing.splice(0))
+            outgoing.sent.reject(error);
+    }
+    #setStatus(status) {
+        const previous = this.#status;
+        this.#status = status;
+        this.#onChange(previous);
+    }
+    #setChild(child) {
+        this.#child = child;
+        this.#onChange(this.#status);
+    }
+}

package/dist/protocol.d.ts

@@ -1,11 +1,11 @@
 import type { Socket } from "node:net";
 import type { JsonValue } from "@earendil-works/chord";
-import type { Op } from "@earendil-works/chord/delta";
 import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
 import type { ConversationView, TaskId, TaskOutcome, TaskState } from "@earendil-works/pi-durable";
 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 = 7;
+export declare const PROTOCOL_VERSION = 8;
 /**
  * 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.
@@ -37,15 +37,6 @@ export type TaskInfo = {
     readonly status: TaskState<JsonValue, JsonValue>["status"];
     readonly outcome?: TaskOutcome<JsonValue>;
 };
-/** A model that the host can run, with what the viewer needs to show and change it. */
-export type ModelInfo = {
-    readonly provider: string;
-    readonly id: string;
-    readonly name: string;
-    readonly contextWindow: number;
-    /** The thinking levels of the model, from `off`. */
-    readonly thinkingLevels: readonly ModelThinkingLevel[];
-};
 /** Any JSON value. A request line is JSON, so `start` takes any input. */
 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">>]>;
@@ -96,25 +87,21 @@ export type Request = {
     readonly handle: string;
 }
 /**
- * The viewer's stream of the child: the reply, then one `{ event: WatchLine }` line 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.
+ * The stream of the child for a mirror session of the Pi extension: the reply, then one `{ event: WatchLine }` line
+ * 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;
 }
-/** Stops the child's current turn. The viewer sends it. */
+/** Stops the child's current turn. A mirror session sends it. */
  | {
     readonly type: "abort";
     readonly handle: string;
 }
-/** The models that have a login, for the viewer's model picker and context window. */
- | {
-    readonly type: "models";
-}
 /**
- * The viewer's change of the child's model or thinking level. It has no caller. A new model keeps the thinking level
+ * 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
  * does not have.
  */
@@ -125,7 +112,7 @@ export type Request = {
     readonly model?: string;
     readonly thinking?: ModelThinkingLevel;
 }
-/** The viewer's message to the child. It has no caller. */
+/** A mirror session's message to the child. It has no caller. */
  | {
     readonly type: "input";
     readonly requestId: string;
@@ -209,8 +196,6 @@ export declare const RequestLine: Type.TUnion<[Type.TObject<{
 }>, Type.TObject<{
     type: Type.TLiteral<"abort">;
     handle: Type.TString;
-}>, Type.TObject<{
-    type: Type.TLiteral<"models">;
 }>, Type.TObject<{
     type: Type.TLiteral<"configure">;
     handle: Type.TString;
@@ -269,7 +254,6 @@ export type Replies = {
     };
     readonly abort: ChildInfo;
     readonly input: Replies["send"];
-    readonly models: readonly ModelInfo[];
     readonly configure: ChildInfo;
     readonly start: TaskInfo;
     readonly task: TaskInfo;
@@ -277,11 +261,11 @@ export type Replies = {
     readonly "abort-task": TaskInfo;
 };
 /**
- * An event of a watch after its reply, sent as `{ event: WatchLine }`: the changes of one commit or a rename, or the end
- * when the child was stopped.
+ * An event of a watch after its reply, sent as `{ event: WatchLine }`: the change of one commit, an empty change after a
+ * rename, or the end when the child was stopped.
  */
 export type WatchLine = {
-    readonly ops: readonly Op[];
+    readonly change: ViewChange;
     readonly child: ChildInfo;
     readonly stopped?: undefined;
 } | {
@@ -317,6 +301,13 @@ 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 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. */

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 = 7;
+export const PROTOCOL_VERSION = 8;
 /**
  * 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.
@@ -54,7 +54,6 @@ export const RequestLine = Type.Union([
     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() }),
-    Type.Object({ type: Type.Literal("models") }),
     Type.Object({
         type: Type.Literal("configure"),
         handle: Type.String(),
@@ -107,6 +106,14 @@ 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. */
+export function childTitle(child) {
+    return child.handle === AGENT_HANDLE ? childLabel(child) : runDisplayName(child);
+}
+/** The message of a thrown value. */
+export function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
 /** The line of one child in a list. */
 export function childLine(child) {
     return `${runDisplayName(child)}  ${child.state.padEnd(8)}  ${child.provider}/${child.model}  ${child.thinking}`;

package/dist/setup.d.ts

@@ -10,3 +10,5 @@ export declare function setup(packageDir: string): void;
  * throws; an error is a warning.
  */
 export declare function setupOnce(packageDir: string): void;
+/** The `PATH` without the `node_modules/.bin` folders that npm adds: pi-coding-agent there has its own `pi`. */
+export declare function userPath(): string;

package/dist/setup.js

@@ -10,6 +10,7 @@ import { basename, delimiter, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
+import { errorMessage } from "./protocol.js";
 const PackageJson = Type.Object({ name: Type.String(), version: Type.String() });
 const PiSettings = Type.Object({
     packages: Type.Optional(Type.Array(Type.Union([Type.String(), Type.Object({ source: Type.String() })]))),
@@ -42,7 +43,7 @@ export function setupOnce(packageDir) {
             writeStamp(installed);
     }
     catch (error) {
-        process.stderr.write(`harness: setup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(`harness: setup failed: ${errorMessage(error)}\n`);
     }
 }
 /**
@@ -137,7 +138,7 @@ function expandHome(path) {
     return path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path;
 }
 /** The `PATH` without the `node_modules/.bin` folders that npm adds: pi-coding-agent there has its own `pi`. */
-function userPath() {
+export function userPath() {
     return (process.env.PATH ?? "")
         .split(delimiter)
         .filter((entry) => !entry.endsWith(join("node_modules", ".bin")))

package/dist/tool.js

@@ -30,7 +30,7 @@ export function toolSchemas(Type) {
         model: text("spawn: the model; default yours"),
         thinking: text("spawn: off, minimal, low, medium, high, xhigh or max; default yours"),
         cwd: text("spawn: the child's working directory; default yours"),
-        tools: texts("spawn: the only tools the child gets; default read, grep, find, ls, write, edit, bash and the package tools"),
+        tools: texts("spawn: the only tools the child gets; default read, grep, find, ls, write, edit, bash, codemode and the package tools"),
         prompts: texts("spawn: the task, in parts"),
         files: texts("spawn: files whose text goes before the task"),
         handle: text("send, wait, status, rename, stop: the hex ID that spawn prints in parentheses, not the name"),