@vzlentin/harness 0.0.0-stage → 0.2.0

package/dist/picker.d.ts

@@ -0,0 +1,22 @@
+import { type Component } from "@earendil-works/pi-tui";
+import type { ModelInfo } from "./protocol.ts";
+/**
+ * A filter over a list of models, fuzzy as Pi's model selector: typing narrows the list and keeps the selected model
+ * when it still matches, ↑↓ move, Enter picks, Esc closes.
+ */
+export declare class ModelPicker implements Component {
+    private readonly input;
+    private readonly items;
+    private readonly modelOf;
+    private readonly onSelect;
+    private readonly onCancel;
+    private readonly border;
+    private list;
+    focused: boolean;
+    constructor(models: readonly ModelInfo[], current: ModelInfo | undefined, border: (text: string) => string, onSelect: (model: ModelInfo) => void, onCancel: () => void);
+    /** A frame with full-width lines, so the transcript does not show through. */
+    render(width: number): string[];
+    handleInput(data: string): void;
+    invalidate(): void;
+    private listOf;
+}

package/dist/picker.js

@@ -0,0 +1,70 @@
+import { getSelectListTheme } from "@earendil-works/pi-coding-agent";
+import { fuzzyFilter, Input, matchesKey, SelectList, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+/** The keys that the list of the model picker gets; the filter gets the others. */
+const LIST_KEYS = ["up", "down", "enter", "escape", "pageUp", "pageDown"];
+/**
+ * A filter over a list of models, fuzzy as Pi's model selector: typing narrows the list and keeps the selected model
+ * when it still matches, ↑↓ move, Enter picks, Esc closes.
+ */
+export class ModelPicker {
+    input = new Input();
+    items;
+    modelOf = new Map();
+    onSelect;
+    onCancel;
+    border;
+    list;
+    focused = true;
+    constructor(models, current, border, onSelect, onCancel) {
+        this.items = models.map((model) => {
+            const item = {
+                value: `${model.provider}/${model.id}`,
+                label: `${model.provider}/${model.id}`,
+                description: model.name,
+            };
+            this.modelOf.set(item, model);
+            return item;
+        });
+        this.border = border;
+        this.onSelect = onSelect;
+        this.onCancel = onCancel;
+        this.input.focused = true;
+        this.list = this.listOf(this.items);
+        this.list.setSelectedIndex(current === undefined ? 0 : models.indexOf(current));
+    }
+    /** A frame with full-width lines, so the transcript does not show through. */
+    render(width) {
+        const inner = Math.max(1, width - 2);
+        const body = [" Model", ...this.input.render(inner), ...this.list.render(inner)].map((line) => {
+            const cut = truncateToWidth(line, inner);
+            return `${this.border("│")}${cut}${" ".repeat(Math.max(0, inner - visibleWidth(cut)))}${this.border("│")}`;
+        });
+        return [this.border(`╭${"─".repeat(inner)}╮`), ...body, this.border(`╰${"─".repeat(inner)}╯`)];
+    }
+    handleInput(data) {
+        if (LIST_KEYS.some((key) => matchesKey(data, key))) {
+            this.list.handleInput(data);
+            return;
+        }
+        this.input.handleInput(data);
+        const selected = this.list.getSelectedItem();
+        const query = this.input.getValue();
+        const items = fuzzyFilter(this.items, query, (item) => `${item.label} ${item.description ?? ""}`);
+        this.list = this.listOf(items);
+        this.list.setSelectedIndex(selected === null ? 0 : items.indexOf(selected));
+    }
+    invalidate() {
+        this.input.invalidate();
+        this.list.invalidate();
+    }
+    listOf(items) {
+        const list = new SelectList(items, 10, getSelectListTheme());
+        list.onSelect = (item) => {
+            const model = this.modelOf.get(item);
+            if (model !== undefined)
+                this.onSelect(model);
+        };
+        list.onCancel = this.onCancel;
+        return list;
+    }
+}

package/dist/projects.d.ts

@@ -0,0 +1,23 @@
+/** The project that has no directory. A cwd outside every project goes to it. */
+export declare const MAIN_PROJECT = "main";
+/** The file of the projects: `$XDG_CONFIG_HOME/harness/projects.json`, default `~/.config/harness/projects.json`. */
+export declare function projectsPath(): string;
+/**
+ * The projects, name to real directory, in creation order. It is empty when the file does not exist. It throws when the
+ * file is not an object of valid names to absolute directories.
+ */
+export declare function readProjects(): Record<string, string>;
+/**
+ * Adds the project `name` with the real path of `dir` to the projects, and gives that path. It throws for an invalid or
+ * existing name and for a directory that does not exist.
+ */
+export declare function addProject(name: string, dir: string): string;
+/** `name` when it is `main` or a project. Otherwise it throws. */
+export declare function checkProject(name: string, projects?: Readonly<Record<string, string>>): string;
+/** The directory of the project `name`: the home directory for `main`. It throws for an unknown project. */
+export declare function projectDir(name: string, projects?: Readonly<Record<string, string>>): string;
+/**
+ * The project of a command: `HARNESS_PROJECT` in `env`, then the project with the longest directory that is `cwd` or
+ * contains it, then `main`. An unknown `HARNESS_PROJECT` is an error.
+ */
+export declare function resolveProject(env: NodeJS.ProcessEnv, cwd: string, projects?: Readonly<Record<string, string>>): string;

package/dist/projects.js

@@ -0,0 +1,96 @@
+import { mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+/** The project that has no directory. A cwd outside every project goes to it. */
+export const MAIN_PROJECT = "main";
+const NAME = /^[a-z][a-z0-9-]{0,31}$/;
+/** The file of the projects: `$XDG_CONFIG_HOME/harness/projects.json`, default `~/.config/harness/projects.json`. */
+export function projectsPath() {
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "harness", "projects.json");
+}
+/**
+ * The projects, name to real directory, in creation order. It is empty when the file does not exist. It throws when the
+ * file is not an object of valid names to absolute directories.
+ */
+export function readProjects() {
+    const path = projectsPath();
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+    const projects = JSON.parse(text);
+    if (!Value.Check(Type.Record(Type.String(), Type.Unknown()), projects)) {
+        throw new Error(`${path} is not an object of project names to directories`);
+    }
+    return Object.fromEntries(Object.entries(projects).map(([name, dir]) => {
+        if (!NAME.test(name) || name === MAIN_PROJECT || !Value.Check(Type.String(), dir) || !isAbsolute(dir)) {
+            throw new Error(`${path} has an invalid project: ${name}`);
+        }
+        return [name, dir];
+    }));
+}
+/**
+ * Adds the project `name` with the real path of `dir` to the projects, and gives that path. It throws for an invalid or
+ * existing name and for a directory that does not exist.
+ */
+export function addProject(name, dir) {
+    if (!NAME.test(name))
+        throw new Error(`A project name has 1 to 32 characters: a-z first, then a-z, 0-9 or -: ${name}`);
+    if (name === MAIN_PROJECT)
+        throw new Error(`A project cannot have the name ${name}`);
+    let real;
+    try {
+        real = realpathSync(resolve(dir));
+    }
+    catch {
+        throw new Error(`No such directory: ${dir}`);
+    }
+    if (!statSync(real).isDirectory())
+        throw new Error(`Not a directory: ${dir}`);
+    const projects = readProjects();
+    if (Object.hasOwn(projects, name))
+        throw new Error(`The project ${name} exists (${projects[name]})`);
+    const path = projectsPath();
+    mkdirSync(dirname(path), { recursive: true });
+    // A temporary file, then a rename, so a stop in between does not truncate the projects.
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify({ ...projects, [name]: real }, null, "\t")}\n`);
+    renameSync(temporary, path);
+    return real;
+}
+/** `name` when it is `main` or a project. Otherwise it throws. */
+export function checkProject(name, projects = readProjects()) {
+    if (name !== MAIN_PROJECT && !Object.hasOwn(projects, name))
+        throw new Error(`Unknown harness project: ${name}`);
+    return name;
+}
+/** The directory of the project `name`: the home directory for `main`. It throws for an unknown project. */
+export function projectDir(name, projects = readProjects()) {
+    // `checkProject` passes only `main`, which `projects` never has, and the names in `projects`.
+    return projects[checkProject(name, projects)] ?? homedir();
+}
+/**
+ * The project of a command: `HARNESS_PROJECT` in `env`, then the project with the longest directory that is `cwd` or
+ * contains it, then `main`. An unknown `HARNESS_PROJECT` is an error.
+ */
+export function resolveProject(env, cwd, projects = readProjects()) {
+    if (env.HARNESS_PROJECT)
+        return checkProject(env.HARNESS_PROJECT, projects);
+    let found = MAIN_PROJECT;
+    let length = -1;
+    for (const [name, dir] of Object.entries(projects)) {
+        // The first project wins over a later one with the same directory.
+        if (dir.length > length && (cwd === dir || cwd.startsWith(dir.endsWith(sep) ? dir : dir + sep))) {
+            found = name;
+            length = dir.length;
+        }
+    }
+    return found;
+}

package/dist/protocol.d.ts

@@ -0,0 +1,323 @@
+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";
+/** 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;
+/**
+ * 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. */
+export type ChildInfo = {
+    readonly handle: string;
+    readonly name?: string;
+    readonly state: ChildState;
+    readonly provider: string;
+    readonly model: string;
+    readonly thinking: ModelThinkingLevel;
+    /** The child's working directory. */
+    readonly cwd: string;
+};
+/** A task that `start` created, by its client key. `outcome` is there only when the task is terminal. */
+export type TaskInfo = {
+    readonly key: string;
+    readonly id: TaskId<JsonValue>;
+    /** The name of the task definition. */
+    readonly kind: string;
+    /**
+     * The version on the task's record: the version of the definition that last ran or migrated it, so a client can tell
+     * which version of an entry the host used for this task. A task that no loaded definition can run keeps its version.
+     */
+    readonly version: number;
+    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">;
+/** One request line. The caller is `PI_SESSION_ID`, or `cli` without one. */
+export type Request = {
+    readonly type: "hello";
+    readonly version: number;
+} | {
+    readonly type: "spawn";
+    readonly requestId: string;
+    readonly caller: string;
+    readonly name?: string;
+    readonly provider: string;
+    readonly model: string;
+    /** The level the caller asks for; the host refuses it when the model does not have it. */
+    readonly thinking?: string;
+    /** The caller's own level, used without `thinking`, clamped to the nearest level that the model has. */
+    readonly callerThinking: string;
+    readonly cwd: string;
+    readonly tools?: readonly string[];
+    readonly prompt: string;
+} | {
+    readonly type: "send";
+    readonly requestId: string;
+    readonly caller: string;
+    readonly handle: string;
+    readonly message: string;
+    readonly followUp: boolean;
+} | {
+    readonly type: "wait";
+    readonly handle: string;
+    readonly timeout: number;
+} | {
+    readonly type: "status";
+    readonly handle: string;
+} | {
+    readonly type: "list";
+    readonly caller: string;
+} | {
+    readonly type: "rename";
+    readonly caller: string;
+    readonly handle: string;
+    readonly name: string;
+} | {
+    readonly type: "stop";
+    readonly caller: string;
+    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.
+ */
+ | {
+    readonly type: "watch";
+    readonly handle: string;
+}
+/** Stops the child's current turn. The viewer 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
+ * 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.
+ */
+ | {
+    readonly type: "configure";
+    readonly handle: string;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly thinking?: ModelThinkingLevel;
+}
+/** The viewer's message to the child. It has no caller. */
+ | {
+    readonly type: "input";
+    readonly requestId: string;
+    readonly handle: string;
+    readonly message: string;
+    readonly followUp: boolean;
+}
+/**
+ * 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
+ * whose definition of `kind` has another version refuses before it creates anything.
+ */
+ | {
+    readonly type: "start";
+    readonly kind: string;
+    readonly input: JsonValue;
+    readonly key: string;
+    readonly version?: number;
+} | {
+    readonly type: "task";
+    readonly key: string;
+}
+/** Waits until the task is terminal, and replies with its outcome. A client polls `task` for the status. */
+ | {
+    readonly type: "wait-task";
+    readonly key: string;
+}
+/** Aborts the task and the work that it owns. */
+ | {
+    readonly type: "abort-task";
+    readonly key: string;
+};
+/**
+ * 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.
+ */
+export declare const RequestLine: Type.TUnion<[Type.TObject<{
+    type: Type.TLiteral<"hello">;
+    version: Type.TNumber;
+}>, Type.TObject<{
+    type: Type.TLiteral<"spawn">;
+    requestId: Type.TString;
+    caller: Type.TString;
+    name: Type.TOptional<Type.TString>;
+    provider: Type.TString;
+    model: Type.TString;
+    thinking: Type.TOptional<Type.TString>;
+    callerThinking: Type.TString;
+    cwd: Type.TOptional<Type.TString>;
+    tools: Type.TOptional<Type.TImmutable<Type.TArray<Type.TString>>>;
+    prompt: Type.TString;
+}>, Type.TObject<{
+    type: Type.TLiteral<"send">;
+    requestId: Type.TString;
+    caller: Type.TString;
+    handle: Type.TString;
+    message: Type.TString;
+    followUp: Type.TBoolean;
+}>, Type.TObject<{
+    type: Type.TLiteral<"wait">;
+    handle: Type.TString;
+    timeout: Type.TNumber;
+}>, Type.TObject<{
+    type: Type.TLiteral<"status">;
+    handle: Type.TString;
+}>, Type.TObject<{
+    type: Type.TLiteral<"list">;
+    caller: Type.TString;
+}>, Type.TObject<{
+    type: Type.TLiteral<"rename">;
+    caller: Type.TString;
+    handle: Type.TString;
+    name: Type.TString;
+}>, Type.TObject<{
+    type: Type.TLiteral<"stop">;
+    caller: Type.TString;
+    handle: Type.TString;
+}>, Type.TObject<{
+    type: Type.TLiteral<"watch">;
+    handle: Type.TString;
+}>, Type.TObject<{
+    type: Type.TLiteral<"abort">;
+    handle: Type.TString;
+}>, Type.TObject<{
+    type: Type.TLiteral<"models">;
+}>, 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">;
+    requestId: Type.TString;
+    handle: Type.TString;
+    message: Type.TString;
+    followUp: Type.TBoolean;
+}>, Type.TObject<{
+    type: Type.TLiteral<"start">;
+    kind: Type.TString;
+    input: Type.TCyclic<{
+        Json: Type.TUnion<[Type.TNull, Type.TBoolean, Type.TNumber, Type.TString, Type.TArray<Type.TRef<"Json">>, Type.TRecord<"^.*$", Type.TRef<"Json">>]>;
+    }, "Json">;
+    key: Type.TString;
+    version: Type.TOptional<Type.TNumber>;
+}>, Type.TObject<{
+    type: Type.TLiteral<"task">;
+    key: Type.TString;
+}>, Type.TObject<{
+    type: Type.TLiteral<"wait-task">;
+    key: Type.TString;
+}>, Type.TObject<{
+    type: Type.TLiteral<"abort-task">;
+    key: Type.TString;
+}>]>;
+export type RequestLine = Static<typeof RequestLine>;
+/** The value of the reply to each request type. */
+export type Replies = {
+    readonly hello: {
+        readonly version: number;
+        readonly pid: number;
+    };
+    readonly spawn: ChildInfo;
+    readonly send: {
+        readonly verb: string;
+        readonly child: ChildInfo;
+    };
+    readonly wait: {
+        readonly answer: string;
+    };
+    readonly status: ChildInfo;
+    readonly list: readonly ChildInfo[];
+    readonly rename: ChildInfo;
+    readonly stop: {
+        readonly handle: string;
+        readonly name?: string;
+    };
+    readonly watch: {
+        readonly view: ConversationView;
+        readonly child: ChildInfo;
+    };
+    readonly abort: ChildInfo;
+    readonly input: Replies["send"];
+    readonly models: readonly ModelInfo[];
+    readonly configure: ChildInfo;
+    readonly start: TaskInfo;
+    readonly task: TaskInfo;
+    readonly "wait-task": TaskInfo;
+    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.
+ */
+export type WatchLine = {
+    readonly ops: readonly Op[];
+    readonly child: ChildInfo;
+    readonly stopped?: undefined;
+} | {
+    readonly stopped: true;
+};
+/** One reply line. */
+export type Reply = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** The files of the host of `project`: `$XDG_STATE_HOME/harness/<project>/`, default `~/.local/state/harness/<project>/`. */
+/**
+ * The CLI of this install, which the host start and the Herdr tabs run with this Node: `cli.js` next to the built
+ * modules, or `cli.ts` in a checkout, which Node runs with type stripping.
+ */
+export declare function cliPath(): string;
+export type StatePaths = {
+    dir: string;
+    socket: string;
+    log: string;
+};
+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: {
+    readonly handle: string;
+    readonly name?: string | undefined;
+}): string;
+export declare function runDisplayName(metadata: {
+    readonly handle: string;
+    readonly name?: string | undefined;
+}): 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;

package/dist/protocol.js

@@ -0,0 +1,126 @@
+import { homedir } from "node:os";
+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;
+/**
+ * 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 const AGENT_HANDLE = "agent";
+/** Any JSON value. A request line is JSON, so `start` takes any input. */
+export const Json = Type.Cyclic({
+    Json: Type.Union([
+        Type.Null(),
+        Type.Boolean(),
+        Type.Number(),
+        Type.String(),
+        Type.Array(Type.Ref("Json")),
+        Type.Record(Type.String(), Type.Ref("Json")),
+    ]),
+}, "Json");
+/**
+ * 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.
+ */
+export const RequestLine = Type.Union([
+    Type.Object({ type: Type.Literal("hello"), version: Type.Number() }),
+    Type.Object({
+        type: Type.Literal("spawn"),
+        requestId: Type.String(),
+        caller: Type.String(),
+        name: Type.Optional(Type.String()),
+        provider: Type.String(),
+        model: Type.String(),
+        thinking: Type.Optional(Type.String()),
+        callerThinking: Type.String(),
+        cwd: Type.Optional(Type.String()),
+        tools: Type.Optional(Type.Immutable(Type.Array(Type.String()))),
+        prompt: Type.String(),
+    }),
+    Type.Object({
+        type: Type.Literal("send"),
+        requestId: Type.String(),
+        caller: Type.String(),
+        handle: Type.String(),
+        message: Type.String(),
+        followUp: Type.Boolean(),
+    }),
+    Type.Object({ type: Type.Literal("wait"), handle: Type.String(), timeout: Type.Number() }),
+    Type.Object({ type: Type.Literal("status"), handle: Type.String() }),
+    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") }),
+    Type.Object({
+        type: Type.Literal("configure"),
+        handle: Type.String(),
+        provider: Type.Optional(Type.String()),
+        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(),
+    }),
+    Type.Object({
+        type: Type.Literal("start"),
+        kind: Type.String(),
+        input: Json,
+        key: Type.String(),
+        version: Type.Optional(Type.Number()),
+    }),
+    Type.Object({ type: Type.Literal("task"), key: Type.String() }),
+    Type.Object({ type: Type.Literal("wait-task"), key: Type.String() }),
+    Type.Object({ type: Type.Literal("abort-task"), key: Type.String() }),
+]);
+/** The files of the host of `project`: `$XDG_STATE_HOME/harness/<project>/`, default `~/.local/state/harness/<project>/`. */
+/**
+ * The CLI of this install, which the host start and the Herdr tabs run with this Node: `cli.js` next to the built
+ * modules, or `cli.ts` in a checkout, which Node runs with type stripping.
+ */
+export function cliPath() {
+    return fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "./cli.ts" : "./cli.js", import.meta.url));
+}
+export function statePaths(project) {
+    const dir = join(process.env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "harness", project);
+    return { dir, socket: join(dir, "host.sock"), log: join(dir, "host.log") };
+}
+export function isValidRunName(value) {
+    return (value.length > 0 && value.length <= 64 && value.trim() === value && !Array.from(value).some(isControlCharacter));
+}
+/** U+0000 to U+001F and U+007F. */
+function isControlCharacter(character) {
+    const code = character.charCodeAt(0);
+    return code <= 0x1f || code === 0x7f;
+}
+/** The label of a child: its name, or its handle when it has no name. */
+export function childLabel(child) {
+    return child.name ?? child.handle;
+}
+export function runDisplayName(metadata) {
+    return metadata.name ? `${metadata.name} (${metadata.handle})` : metadata.handle;
+}
+/** 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}`;
+}
+/** Calls `onLine` with each line that arrives on `socket`, without its newline. */
+export function onLines(socket, onLine) {
+    let buffer = "";
+    socket.setEncoding("utf8");
+    socket.on("data", (chunk) => {
+        buffer += chunk;
+        for (let end = buffer.indexOf("\n"); end !== -1; end = buffer.indexOf("\n")) {
+            const line = buffer.slice(0, end);
+            buffer = buffer.slice(end + 1);
+            onLine(line);
+        }
+    });
+}

package/dist/setup.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Registers `<packageDir>/pi` in Pi when `packageDir` is a top-level global npm install. First it runs `pi remove` for
+ * each Pi package of the `retiredPiPackages` field of the package's `package.json` that Pi's settings list. It writes
+ * its messages to stderr, and it does not throw for a Pi failure: it writes a warning with the command to run.
+ * It writes the stamp that `setupOnce` reads unless a `pi` command failed, so the next run tries again. Without `pi`
+ * on PATH it writes the stamp, so a user without Pi gets the hint once per version.
+ */
+export declare function setup(packageDir: string): void;
+/**
+ * `setup` once per version and path of the package: it does nothing when the stamp of `setup` exists. It never
+ * throws; an error is a warning.
+ */
+export declare function setupOnce(packageDir: string): void;