@vzlentin/harness 0.2.3 → 0.3.1

package/dist/mirror.js

@@ -0,0 +1,291 @@
+/**
+ * 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, 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 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.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, 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 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];
+/** 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;
+    /** The target of the requests: the handle or the conversation of `target`, without the project. */
+    #ref;
+    #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.#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;
+        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", ...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. 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, ...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.#ref);
+                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,
+                        ...this.#ref,
+                        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,20 +1,24 @@
 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 = 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;
@@ -37,19 +41,21 @@ 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">>]>;
 }, "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";
@@ -96,25 +102,19 @@ 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. */
- | {
+} & Target)
+/** 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";
-}
+} & Target)
 /**
- * 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,14 +125,13 @@ 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. 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
@@ -203,27 +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<"models">;
-}>, 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<{
@@ -269,7 +286,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 +293,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;
 } | {
@@ -308,16 +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,
+ * 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 = 7;
+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,9 +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() }),
-    Type.Object({ type: Type.Literal("models") }),
+    targeted("watch", {}),
+    targeted("abort", {}),
     Type.Object({
         type: Type.Literal("configure"),
         handle: Type.String(),
@@ -62,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(),
@@ -107,6 +120,17 @@ 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,
+ * and for a conversation, whose name is its key.
+ */
+export function childTitle(child) {
+    return child.handle === AGENT_HANDLE || child.conversation !== undefined ? 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")))