@vzlentin/harness 0.1.0 → 0.2.0

package/dist/host.js

@@ -22,16 +22,20 @@ import * as durable from "@earendil-works/pi-durable";
 import { AgentDoc, createRegistry, defineDoc, Harness, } from "@earendil-works/pi-durable";
 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 { ChildContext } from "./context.js";
 import { readEntries } from "./entries.js";
-import { AGENT_HANDLE, onLines, PROTOCOL_VERSION, } from "./protocol.js";
+import { AGENT_HANDLE, onLines, PROTOCOL_VERSION, RequestLine, } from "./protocol.js";
 import { abortTask, startableTasks, startTask, taskInfo, waitTask } from "./tasks.js";
 import { subagentTool } from "./tool.js";
 /** The host exits after this long with no connection, no live task and no request. */
 const IDLE_EXIT_MS = 5 * 60_000;
 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.
@@ -70,7 +74,7 @@ export async function runHost(options) {
     const settings = SettingsManager.create(stateDir, agentDir, {
         projectTrusted: new ProjectTrustStore(agentDir).get(stateDir) === true,
     });
-    const warn = (error) => process.stderr.write(`warning: ${error instanceof Error ? error.message : String(error)}\n`);
+    const warn = (cause) => process.stderr.write(`warning: ${cause instanceof Error ? cause.message : String(cause)}\n`);
     // The store is there once the harness is open; entries get `place` before, and use the store in their tasks.
     let harness;
     const place = {
@@ -84,18 +88,18 @@ export async function runHost(options) {
             return registry.snapshot();
         },
     };
-    const entries = await loadEntries(stateDir, agentDir, settings, place, warn).catch((error) => {
+    const entries = await loadEntries(stateDir, agentDir, settings, place, warn).catch((cause) => {
         lock.close();
-        throw error;
+        throw cause;
     });
     const envs = new Map();
     const startable = startableTasks(entries.tasks);
     let base;
     // The project agent is the root conversation, set up at its first use. A failed set-up runs again at the next use.
     let agentSetUp;
-    const agent = () => (agentSetUp ??= setUpAgent(base.root, models, settings, project, cwd).catch((error) => {
+    const agent = () => (agentSetUp ??= setUpAgent(base.root, models, settings, project, cwd).catch((cause) => {
         agentSetUp = undefined;
-        throw error;
+        throw cause;
     }));
     // A child calls the host in this process, not through the socket, so a long `wait` cannot hold up the requests
     // of a connection. Its caller is its conversation ID, which the depth limit and the owner checks key on.
@@ -174,7 +178,7 @@ export async function runHost(options) {
                 let start;
                 const connection = { socket, afterReply: (afterReply) => (start = afterReply) };
                 try {
-                    const request = JSON.parse(line);
+                    const request = parseRequest(line);
                     if (request.type !== "hello" && request.type !== "list" && request.type !== "status") {
                         lastActivity = Date.now();
                     }
@@ -204,11 +208,11 @@ export async function runHost(options) {
             server.off("error", rejectListen);
             resolveListen();
         });
-    }).catch(async (error) => {
+    }).catch(async (cause) => {
         await entries.close();
         await harness.close(context);
         lock.close();
-        throw error;
+        throw cause;
     });
     let closing;
     const close = () => {
@@ -252,8 +256,19 @@ async function handleRequest(request, handler) {
             return { version: PROTOCOL_VERSION, pid: process.pid };
         case "spawn":
             return spawnChild(request, handler);
-        case "send":
-            return sendTo(request, await childTarget(handler, request.handle, await ownRecord(handler.harness, request.handle, request.caller)));
+        case "send": {
+            const record = await ownRecord(handler.harness, request.handle, request.caller);
+            // Mark the request first: a wait that sees it as the last request must find it in `sent`.
+            const added = await markSent(handler.harness, request.handle, request.requestId, true);
+            try {
+                return await sendTo(request, await childTarget(handler, request.handle, record));
+            }
+            catch (error) {
+                if (added)
+                    await markSent(handler.harness, request.handle, request.requestId, false);
+                throw error;
+            }
+        }
         case "input":
             return sendTo(request, await target(handler, request.handle));
         case "wait":
@@ -319,12 +334,19 @@ async function handleRequest(request, handler) {
                         delete state.requests[requestId];
                 }
             }, context);
-            return { handle: request.handle, ...(record.name === undefined ? {} : { name: record.name }) };
+            return record.name === undefined ? { handle: request.handle } : { handle: request.handle, name: record.name };
         }
-        default:
-            throw new Error(`Unknown request: ${request.type}`);
     }
 }
+/** The request of a line from a client, checked against the protocol. */
+function parseRequest(line) {
+    const request = JSON.parse(line);
+    if (Value.Check(RequestLine, request))
+        return request;
+    throw new Error(Value.Check(Type.Object({ type: Type.String() }), request)
+        ? `Unknown or invalid request: ${request.type}`
+        : "Invalid request");
+}
 async function spawnChild(request, handler) {
     if (!request.cwd)
         throw new Error("spawn requires a working directory");
@@ -337,27 +359,25 @@ async function spawnChild(request, handler) {
             request.caller === String(handler.root.id)
             ? request.caller
             : undefined;
-        const spec = {
+        let spec = {
             ...(parent === undefined ? { root: request.caller } : { parent }),
             provider: request.provider,
             model: request.model,
-            ...(request.thinking === undefined ? {} : { thinking: request.thinking }),
             fallbackThinking: request.callerThinking,
             cwd: request.cwd,
-            ...(request.tools === undefined ? {} : { tools: request.tools }),
         };
+        if (request.thinking !== undefined)
+            spec = { ...spec, thinking: request.thinking };
+        if (request.tools !== undefined)
+            spec = { ...spec, tools: request.tools };
         // The record is written in the commit that creates the child.
         await library.open(place, handler.owner, `sub:${request.requestId}`, spec, context, async (tx, id) => {
             const current = await tx.doc(Children);
             let fresh = randomBytes(3).toString("hex");
             while (Object.hasOwn(current.children, fresh))
                 fresh = randomBytes(3).toString("hex");
-            current.children[fresh] = {
-                ...(request.name === undefined ? {} : { name: request.name }),
-                caller: request.caller,
-                createdAt: new Date().toISOString(),
-                conversationId: id,
-            };
+            const record = { caller: request.caller, createdAt: new Date().toISOString(), conversationId: id };
+            current.children[fresh] = request.name === undefined ? record : { name: request.name, ...record };
             current.requests[request.requestId] = fresh;
         });
         handle = (await harness.snapshot(Children, context))?.requests[request.requestId];
@@ -367,6 +387,7 @@ async function spawnChild(request, handler) {
     const record = await childRecord(harness, handle);
     // The request ID makes a repeated spawn find the first submission, also after a crash before it.
     await (await childOf(handler, record)).send({ type: "input", content: request.prompt, requestId: `spawn:${request.requestId}` }, context);
+    await markSent(harness, handle, `spawn:${request.requestId}`, true);
     return childInfo(handler, handle, record);
 }
 /** Sends the input of `request` to `found`. */
@@ -384,23 +405,87 @@ function sendVerb(busy, followUp) {
     return !busy ? "Prompted" : followUp ? "Queued follow-up for" : "Steered";
 }
 async function waitChild(request, handler) {
-    const child = await childOf(handler, await childRecord(handler.harness, request.handle));
+    const record = await childRecord(handler.harness, request.handle);
+    const child = await childOf(handler, record);
     const timeout = AbortSignal.timeout(request.timeout * 1000);
+    const waiting = withAbortSignal(AbortSignal.any([timeout, handler.signal]), context);
+    let main;
     let answer;
+    let earlier;
     try {
-        answer = await child.settled(withAbortSignal(AbortSignal.any([timeout, handler.signal]), context));
+        main = await child.lastRequest(waiting);
+        answer = await child.settled(waiting, main ?? undefined);
+        // Read the record after the answer: a send is in `sent` before it can be the last request.
+        const current = (await childRecord(handler.harness, request.handle)).sent ?? [];
+        const unread = unreadBefore(current, record.read ?? 0, main, record.sent ?? []);
+        earlier = [];
+        for (const requestId of unread.ids) {
+            const before = await child.settled(waiting, requestId);
+            // A steer goes into the turn that was running, so its request can share that turn's answer.
+            if (!("entry" in before && "entry" in answer && before.entry === answer.entry))
+                earlier.push(before);
+        }
+        await handler.harness.commit(async (tx) => {
+            const latest = (await tx.doc(Children)).children[request.handle];
+            if (latest !== undefined)
+                latest.read = Math.max(latest.read ?? 0, unread.read);
+        }, context);
     }
     catch (error) {
         if (timeout.aborted)
             throw new Error(`Timed out after ${request.timeout}s waiting for ${request.handle}`);
         throw error;
     }
-    // A cut answer still gives its text.
+    const texts = earlier.map((before) => {
+        const text = answerText(request.handle, before);
+        return text.failed ? `(no answer: ${text.text})` : text.text;
+    });
+    const last = answerText(request.handle, answer);
+    const all = [...texts, last.text];
+    const parts = all.map((text, index) => `--- Answer ${index + 1} of ${all.length} ---\n${text}`);
+    const text = texts.length === 0 ? last.text : `${all.length} unread answers, oldest first.\n\n${parts.join("\n\n")}`;
+    // A failed last turn is an error that still gives the earlier answers.
+    if (last.failed)
+        throw new Error(text);
+    return { answer: text };
+}
+/**
+ * The requests of `sent` from `read` on that a wait for `main` gives before the answer to `main`, and the new `read`.
+ * When `main` is a request of the caller, they are the ones before it, and `main` counts as read; a send after it
+ * stays unread. Otherwise, such as for viewer input, they are the caller's requests known when the wait started.
+ */
+function unreadBefore(sent, read, main, atStart) {
+    const index = main === null ? -1 : sent.indexOf(main);
+    if (index >= read)
+        return { ids: sent.slice(read, index), read: index + 1 };
+    if (index >= 0)
+        return { ids: [], read };
+    return { ids: atStart.slice(read), read: Math.max(read, atStart.length) };
+}
+/** The text of `answer`, or the failure of a turn with no answer. A cut answer still gives its text. */
+function answerText(handle, answer) {
     if (answer.status === "ok" || answer.reason !== "unanswered")
-        return { answer: answer.text };
-    if (answer.cause === "queued")
-        throw new Error(`${request.handle} stopped with queued messages after a failed turn`);
-    throw new Error(failureText(request.handle, answer.cause, answer.detail));
+        return { text: answer.text, failed: false };
+    if (answer.cause === "queued") {
+        return { text: `${handle} stopped with queued messages after a failed turn`, failed: true };
+    }
+    return { text: failureText(handle, answer.cause, answer.detail), failed: true };
+}
+/**
+ * Adds `requestId` to the requests of `handle` that a `wait` gives the answers of, or removes it after a send that
+ * failed. A repeated request is not added. True when it changed the record.
+ */
+async function markSent(harness, handle, requestId, add) {
+    return harness.commit(async (tx) => {
+        const record = (await tx.doc(Children)).children[handle];
+        if (record === undefined)
+            return false;
+        const sent = record.sent ?? [];
+        if (add === sent.includes(requestId))
+            return false;
+        record.sent = add ? [...sent, requestId] : sent.filter((id) => id !== requestId);
+        return true;
+    }, context);
 }
 async function abortChild(request, handler) {
     const found = await target(handler, request.handle);
@@ -479,9 +564,9 @@ async function childOf(handler, record) {
 function failureText(handle, reason, detail) {
     if (reason === "aborted")
         return `${handle} was aborted`;
-    const text = typeof detail === "string"
+    const text = Value.Check(Type.String(), detail)
         ? detail
-        : typeof detail?.message === "string"
+        : Value.Check(ErrorDetail, detail)
             ? detail.message
             : undefined;
     return text === undefined ? `${handle} failed: ${reason}` : `${handle} failed: ${text}`;
@@ -493,12 +578,8 @@ async function childInfo(handler, handle, 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;
-    return {
-        handle,
-        ...(record.name === undefined ? {} : { name: record.name }),
-        state,
-        ...(await agentFields(child.conversation)),
-    };
+    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) {
@@ -643,11 +724,11 @@ function piSettings(settings, extensions) {
         get stream() {
             const provider = settings.getProviderRetrySettings();
             const idle = settings.getHttpIdleTimeoutMs();
-            return {
+            const stream = {
                 timeoutMs: provider.timeoutMs ?? (idle === 0 ? 2147483647 : idle),
                 maxRetryDelayMs: provider.maxRetryDelayMs,
-                ...(provider.maxRetries === undefined ? {} : { maxRetries: provider.maxRetries }),
             };
+            return provider.maxRetries === undefined ? stream : { ...stream, maxRetries: provider.maxRetries };
         },
         get retry() {
             return settings.getRetrySettings();
@@ -675,6 +756,12 @@ function liveTasks(tasks) {
     }
     return tasks.length - dead.size;
 }
+/** 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`), in one shared event bus, as one entry whose `close()` closes each of them and
@@ -687,7 +774,16 @@ async function loadEntries(cwd, agentDir, settingsManager, place, warn) {
         .listConfiguredPackages()
         .flatMap((found) => found.installedPath ?? []);
     for (const root of new Set(roots)) {
-        const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8").catch(() => "{}"));
+        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));
     }

package/dist/projects.js

@@ -1,6 +1,8 @@
 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}$/;
@@ -19,20 +21,20 @@ export function readProjects() {
         text = readFileSync(path, "utf8");
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
             return {};
         throw error;
     }
     const projects = JSON.parse(text);
-    if (typeof projects !== "object" || projects === null || Array.isArray(projects)) {
+    if (!Value.Check(Type.Record(Type.String(), Type.Unknown()), projects)) {
         throw new Error(`${path} is not an object of project names to directories`);
     }
-    for (const [name, dir] of Object.entries(projects)) {
-        if (!NAME.test(name) || name === MAIN_PROJECT || typeof dir !== "string" || !isAbsolute(dir)) {
+    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 projects;
+        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
@@ -71,7 +73,8 @@ export function checkProject(name, projects = readProjects()) {
 }
 /** The directory of the project `name`: the home directory for `main`. It throws for an unknown project. */
 export function projectDir(name, projects = readProjects()) {
-    return checkProject(name, projects) === MAIN_PROJECT ? homedir() : projects[name];
+    // `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

package/dist/protocol.d.ts

@@ -3,6 +3,7 @@ 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;
 /**
@@ -45,6 +46,10 @@ export type ModelInfo = {
     /** 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";
@@ -110,7 +115,8 @@ export type Request = {
 }
 /**
  * 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.
+ * 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";
@@ -152,6 +158,90 @@ export type Request = {
     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: {
@@ -211,12 +301,13 @@ export type Reply = {
  * modules, or `cli.ts` in a checkout, which Node runs with type stripping.
  */
 export declare function cliPath(): string;
-export declare function statePaths(project: string): {
+export type StatePaths = {
     dir: string;
     socket: string;
     log: string;
 };
-export declare function isValidRunName(value: unknown): value is 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;

package/dist/protocol.js

@@ -1,6 +1,7 @@
 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;
 /**
@@ -8,6 +9,77 @@ export const PROTOCOL_VERSION = 7;
  * 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
@@ -21,12 +93,12 @@ export function statePaths(project) {
     return { dir, socket: join(dir, "host.sock"), log: join(dir, "host.log") };
 }
 export function isValidRunName(value) {
-    return (typeof value === "string" &&
-        value.length > 0 &&
-        value.length <= 64 &&
-        value.trim() === value &&
-        // biome-ignore lint/suspicious/noControlCharactersInRegex: a name must not contain control characters.
-        !/[\u0000-\u001f\u007f]/.test(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) {

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;