@vzlentin/harness 0.1.0 → 0.2.0

package/README.md

@@ -13,25 +13,28 @@ with `/login` in `pi`, or set the API key of the provider, such as `ANTHROPIC_AP
 npm install -g @vzlentin/harness
 ```
 
-This gives you the `harness` command.
-
-### Pi
-
-To also get the `subagent` tool, the `/subagent` command and the subagents widget in Pi:
+This works with npm 11 and npm 12. It gives you the `harness` command, and a setup runs `pi install` on the `pi/`
+folder of the package, which adds the `subagent` tool, the `/subagent` command and the subagents widget to Pi. Pi and
+the `harness` command use the same host. npm 12 runs no install script by default, so there the first `harness` command
+does the setup. When `pi` is not on your `PATH`, or the step fails, the setup prints the command to run later:
 
 ```sh
-pi install npm:@vzlentin/pi-subagent
+pi install "$(realpath "$(npm root -g)/@vzlentin/harness/pi")"
 ```
 
-You can add it now or later. Pi and the `harness` command use the same host.
+When you install with `--prefix`, give the same `--prefix` to `npm root -g`.
+
+### Move from 0.1.0
+
+0.1.0 had the extension in the separate Pi package `@vzlentin/pi-subagent`. Update as below: the setup removes that
+package from Pi (`pi remove npm:@vzlentin/pi-subagent`), since it conflicts with the new extension.
 
 ### Update and remove
 
 ```sh
-npm update -g @vzlentin/harness
-pi update                                   # when you installed @vzlentin/pi-subagent
+npm install -g @vzlentin/harness@latest
+pi remove "$(realpath "$(npm root -g)/@vzlentin/harness/pi")"    # first: npm runs no script on uninstall
 npm uninstall -g @vzlentin/harness
-pi remove npm:@vzlentin/pi-subagent
 ```
 
 ## Use
@@ -52,12 +55,13 @@ harness main                # talk to the agent of the main project
 
 ```sh
 npm ci
-npm run check               # Biome, TypeScript, Vitest
+npm run check               # Biome, oxlint, TypeScript, Vitest
 XDG_STATE_HOME=/tmp/harness-dev node src/cli.ts list
 ```
 
 `node src/cli.ts` runs the CLI of this checkout. Give it its own `XDG_STATE_HOME`, so its hosts do not share sockets and
 stores with the hosts of the installed `harness`.
 
-The checkout runs from its TypeScript source. `npm publish` builds `dist/` first, and the package contains only
-`dist/`. The Pi plugin is the package in `pi-subagent/`, published from that directory with `npm publish`.
+The checkout runs from its TypeScript source. `npm publish` builds `dist/` first, and the package contains `dist/`,
+the Pi extension in `pi/` and its `postinstall` script. `npm run check` builds `dist/` too, before the type check. The extension imports `../dist/`, so to try the checkout's
+extension in Pi, run `npm run build`, then `pi install ./pi`, and build again after each change in `src/`.

package/dist/answer.js

@@ -4,6 +4,8 @@
  */
 import { copyJson } from "@earendil-works/chord";
 import { Type, validateToolArguments } from "@earendil-works/pi-ai";
+import { Value } from "typebox/value";
+import { Json } from "./protocol.js";
 /**
  * The user message that asks again for a `respond` call after an answer of a `schema` ask without one. A reminder is
  * known by its exact text, so a user prompt with the same text counts as one.
@@ -37,9 +39,12 @@ export function createAnswers(durable) {
             if (doc?.schema === undefined || requestId === undefined) {
                 return { isError: true, output: [{ type: "text", text: "This turn asks for no structured answer." }] };
             }
+            if (!Value.Check(Json, args.answer)) {
+                return { isError: true, output: [{ type: "text", text: "The answer must be a JSON value." }] };
+            }
             let answer;
             try {
-                answer = checkedAnswer(doc.schema, args, api.callId);
+                answer = checkedAnswer(doc.schema, args.answer, api.callId);
             }
             catch (error) {
                 return {
@@ -103,7 +108,7 @@ export function createAnswers(durable) {
                 if (!Array.isArray(tools)) {
                     const remove = tools?.remove?.filter((tool) => tool !== name);
                     const add = (tools?.add ?? []).filter((tool) => tool !== name);
-                    agent.modelTools = { ...(remove === undefined ? {} : { remove }), add: [...add, name] };
+                    agent.modelTools = remove === undefined ? { add: [...add, name] } : { remove, add: [...add, name] };
                 }
                 else if (!tools.includes(name))
                     tools.push(name);
@@ -134,9 +139,9 @@ function remindersAtEnd(messages) {
         if (message.role !== "user")
             continue;
         const { content } = message;
-        const text = typeof content === "string"
-            ? content
-            : content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("");
+        const text = Array.isArray(content)
+            ? content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("")
+            : content;
         if (text !== REMINDER)
             break;
         count++;
@@ -144,27 +149,27 @@ function remindersAtEnd(messages) {
     return count;
 }
 /**
- * The answer of `args` checked against `schema`, as `validateToolArguments` returns it. A string answer that does not
- * match is parsed as JSON, and an object or array is checked again, because a model can send it as its JSON text. Any
- * other string throws the first error.
+ * `answer` checked against `schema`, as `validateToolArguments` returns it. A string answer that does not match is
+ * parsed as JSON, and an object or array is checked again, because a model can send it as its JSON text. Any other
+ * string throws the first error.
  */
-function checkedAnswer(schema, args, id) {
-    const parameters = { type: "object", properties: { answer: schema }, required: ["answer"] };
-    const check = (answer) => validateToolArguments({ name: "respond", description: "", parameters }, { type: "toolCall", id, name: "respond", arguments: { answer } }).answer;
+function checkedAnswer(schema, answer, id) {
+    const parameters = Type.Object({ answer: Type.Unsafe(schema) });
+    const check = (value) => validateToolArguments({ name: "respond", description: "", parameters }, { type: "toolCall", id, name: "respond", arguments: { answer: value } }).answer;
     try {
-        return check(args.answer);
+        return check(answer);
     }
     catch (error) {
-        if (typeof args.answer !== "string")
+        if (!Value.Check(Type.String(), answer))
             throw error;
         let parsed;
         try {
-            parsed = JSON.parse(args.answer);
+            parsed = JSON.parse(answer);
         }
         catch {
             throw error;
         }
-        if (typeof parsed !== "object" || parsed === null)
+        if (!(parsed instanceof Object))
             throw error;
         return check(parsed);
     }

package/dist/chat.js

@@ -3,15 +3,15 @@ import { Container, Spacer, Text } from "@earendil-works/pi-tui";
 import { color } from "./theme.js";
 import { liveOf, userText } from "./view-state.js";
 /** Pi's renderers of the tools that children have under the same names. */
-const RENDERERS = {
-    read: createReadToolDefinition,
-    bash: createBashToolDefinition,
-    edit: createEditToolDefinition,
-    write: createWriteToolDefinition,
-    grep: createGrepToolDefinition,
-    find: createFindToolDefinition,
-    ls: createLsToolDefinition,
-};
+const RENDERERS = new Map([
+    ["read", createReadToolDefinition],
+    ["bash", createBashToolDefinition],
+    ["edit", createEditToolDefinition],
+    ["write", createWriteToolDefinition],
+    ["grep", createGrepToolDefinition],
+    ["find", createFindToolDefinition],
+    ["ls", createLsToolDefinition],
+]);
 const DIAGNOSTICS = /^<harness>\n([\s\S]*)\n<\/harness>$/;
 /**
  * A tool result as Pi shows its own. pi-durable adds the diagnostics of a call for the model as a `<harness>` block, such
@@ -174,7 +174,7 @@ export class ChatView {
     renderer(toolName) {
         let definition = this.renderers.get(toolName);
         if (definition === undefined) {
-            const create = RENDERERS[toolName];
+            const create = RENDERERS.get(toolName);
             if (create === undefined)
                 return undefined;
             definition = create(this.cwd);

package/dist/children.d.ts

@@ -15,7 +15,7 @@ export declare const DEFAULT_DEPTH_LIMIT = 2;
  * callbacks return nothing, as a task's do, and read back through `tx` or `snapshot`.
  */
 export type Store = {
-    commit(change: (tx: Tx) => Promise<undefined>, context: Context): Promise<unknown>;
+    commit(change: (tx: Tx) => Promise<undefined>, context: Context): Promise<void>;
     readonly snapshot: DocumentReader["snapshot"];
     conversation(id: ConversationId, context: Context): Promise<Conversation | undefined>;
     submission(id: SubmissionId, context: Context): Promise<Submission | undefined>;
@@ -101,7 +101,7 @@ export type Failure = {
     readonly status: "failed";
     readonly reason: "unanswered";
     readonly cause: string;
-    readonly detail?: unknown;
+    readonly detail?: JsonValue | undefined;
 };
 /** Input to a child, at most once per request ID. */
 export type Input = Parameters<Conversation["submit"]>[0] & {
@@ -144,6 +144,8 @@ export type Child = {
      * `context` stops only the wait; the child runs until `close()`.
      */
     settled(context: Context, request?: string): Promise<Answer>;
+    /** The newest request ID admitted, which `settled` waits for by default, or null before the first one. */
+    lastRequest(context: Context): Promise<string | null>;
     state(context: Context): Promise<ChildState>;
     /** The spend of the child and everything under it, for reports. */
     usage(context: Context): Promise<UsageState>;
@@ -195,6 +197,11 @@ export type Turn = {
     state(context: Context): Promise<Exclude<ChildState, "closed">>;
 };
 export declare function createChildren(durable: typeof Durable): Children;
+/** The model and the thinking level of a child. */
+export type ResolvedModel = {
+    model: ModelRef;
+    thinkingLevel: ModelThinkingLevel;
+};
 /**
  * The model and thinking level of `request`; a field left out comes from `fallback`. An explicit `thinking` that the
  * model does not have is refused. Without it, the level is `fallbackThinking`, else the fallback's, clamped to the
@@ -205,7 +212,4 @@ export declare function resolveModel(models: Models, fallback: Pick<Agent, "mode
     readonly model?: string | undefined;
     readonly thinking?: string | undefined;
     readonly fallbackThinking?: string | undefined;
-}): {
-    model: ModelRef;
-    thinkingLevel: ModelThinkingLevel;
-};
+}): ResolvedModel;

package/dist/children.js

@@ -1,5 +1,6 @@
 import { withCancel } from "@earendil-works/chord/context";
 import { clampThinkingLevel, getSupportedThinkingLevels } from "@earendil-works/pi-ai/models";
+import { MODEL_THINKING_LEVELS } from "@earendil-works/pi-ai/providers/model-schema";
 import { complete, createAnswers } from "./answer.js";
 /** The deepest child by default: a child of a child of a root. */
 export const DEFAULT_DEPTH_LIMIT = 2;
@@ -47,19 +48,18 @@ export function createChildren(durable) {
     const extension = durable.defineExtension({ name: "pi-subagent-children", tasks: [Anchor] });
     const ownerState = (owner) => owner.kind === "detached"
         ? { kind: "detached" }
-        : { kind: "task", taskId: owner.taskId, ...(owner.group === undefined ? {} : { group: owner.group }) };
+        : owner.group === undefined
+            ? { kind: "task", taskId: owner.taskId }
+            : { kind: "task", taskId: owner.taskId, group: owner.group };
     const sameOwner = (a, b) => {
         if (a.kind === "detached" || b.kind === "detached")
             return a.kind === b.kind;
         return a.group !== undefined || b.group !== undefined ? a.group === b.group : a.taskId === b.taskId;
     };
-    const lineageOf = (doc) => ({
-        key: doc.key,
-        root: doc.root,
-        ...(doc.parent === null ? {} : { parent: doc.parent }),
-        depth: doc.depth,
-        limit: doc.limit,
-    });
+    const lineageOf = (doc) => {
+        const found = { key: doc.key, root: doc.root, depth: doc.depth, limit: doc.limit };
+        return doc.parent === null ? found : { ...found, parent: doc.parent };
+    };
     async function childDoc(store, id, context) {
         const doc = await store.snapshot(ChildDoc, id, context);
         return doc === undefined || doc.key === "" ? undefined : doc;
@@ -71,18 +71,21 @@ export function createChildren(durable) {
     }
     /** Reads through a commit, which returns nothing on a task's runtime. */
     async function read(place, reader, context) {
-        let value;
+        let result;
         await place.store.commit(async (tx) => {
-            value = await reader(tx);
+            result = { value: await reader(tx) };
             return undefined;
         }, context);
-        return value;
+        if (result === undefined)
+            throw new Error("The commit did not run its change");
+        return result.value;
     }
     /** `id` and every child under it, parents first. */
     async function subtree(place, id, context) {
         const ids = [id];
-        for (let i = 0; i < ids.length; i++) {
-            const doc = await childDoc(place.store, ids[i], context);
+        // The loop also visits the IDs that it appends.
+        for (const member of ids) {
+            const doc = await childDoc(place.store, member, context);
             for (const child of doc?.children ?? [])
                 ids.push(child);
         }
@@ -214,15 +217,18 @@ export function createChildren(durable) {
             send: turns.send,
             ask,
             settled,
+            lastRequest: async (context) => (await lastRequest(context)) ?? null,
             async state(context) {
                 if ((await place.store.snapshot(ChildDoc, id, context))?.closed === true)
                     return "closed";
                 return turns.state(context);
             },
             async usage(context) {
-                let sum = { models: {}, tools: {} };
+                const sum = { models: {}, tools: {} };
                 for (const member of await subtree(place, id, context)) {
-                    sum = addNumbers(sum, await place.store.snapshot(durable.UsageDoc, member, context));
+                    const usage = await place.store.snapshot(durable.UsageDoc, member, context);
+                    if (usage !== undefined)
+                        addUsageState(sum, usage);
                 }
                 return sum;
             },
@@ -291,13 +297,14 @@ export function createChildren(durable) {
                 if (known.conversation !== 0)
                     return undefined;
                 const child = await tx.createConversation({ ownership: { kind: "task", taskId: ownerTask } });
-                await durable.configure(tx, child.id, {
-                    model,
-                    thinkingLevel,
-                    ...(cwd === undefined ? {} : { cwd }),
-                    ...(tools === undefined ? {} : { tools }),
-                    ...(spec.instructions === undefined ? {} : { instructions: spec.instructions }),
-                });
+                let change = { model, thinkingLevel };
+                if (cwd !== undefined)
+                    change = { ...change, cwd };
+                if (tools !== undefined)
+                    change = { ...change, tools };
+                if (spec.instructions !== undefined)
+                    change = { ...change, instructions: spec.instructions };
+                await durable.configure(tx, child.id, change);
                 // The child keeps the extensions of the owner's agent and selects the answer extension too.
                 const agent = await tx.doc(durable.AgentDoc, child.id);
                 const answerName = answers.extension.name;
@@ -362,29 +369,51 @@ export function resolveModel(models, fallback, request) {
         throw new Error(`Unknown model: ${provider}/${modelId}`);
     const levels = getSupportedThinkingLevels(model);
     if (request.thinking !== undefined) {
-        if (!levels.includes(request.thinking)) {
+        const thinkingLevel = levels.find((level) => level === request.thinking);
+        if (thinkingLevel === undefined)
             throw new Error(`${provider}/${modelId} has no thinking level ${request.thinking}`);
-        }
-        return { model: { provider, modelId }, thinkingLevel: request.thinking };
+        return { model: { provider, modelId }, thinkingLevel };
     }
+    const inherited = request.fallbackThinking ?? fallback?.thinkingLevel ?? "off";
+    const known = MODEL_THINKING_LEVELS.find((level) => level === inherited);
     // `clampThinkingLevel` gives the model's first level for a name that it does not know.
-    const inherited = (request.fallbackThinking ?? fallback?.thinkingLevel ?? "off");
-    return { model: { provider, modelId }, thinkingLevel: clampThinkingLevel(model, inherited) };
+    return {
+        model: { provider, modelId },
+        thinkingLevel: known === undefined ? (levels[0] ?? "off") : clampThinkingLevel(model, known),
+    };
 }
 /** The conversation ID that `value` spells, as callers write it; nothing for another caller, such as a Pi session. */
 function conversationIdOf(value) {
-    return /^[1-9][0-9]*$/.test(value) && Number.isSafeInteger(Number(value))
-        ? Number(value)
-        : undefined;
+    if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(Number(value)))
+        return undefined;
+    // SAFETY: a conversation ID is a positive safe integer, and the callers look up the conversation of this one.
+    return Number(value);
 }
-/** `a` with every number in `b` added at the same path; `b` undefined adds nothing. */
-function addNumbers(a, b) {
-    if (typeof b === "number")
-        return (typeof a === "number" ? a : 0) + b;
-    if (b === null || typeof b !== "object")
-        return a ?? b;
-    const sum = { ...(a !== null && typeof a === "object" ? a : {}) };
-    for (const [key, value] of Object.entries(b))
-        sum[key] = addNumbers(sum[key], value);
-    return sum;
+/** Adds every counter of `state` to `sum`. A counter that one side leaves out counts as 0. */
+function addUsageState(sum, state) {
+    for (const bucket of ["models", "tools"]) {
+        const totals = sum[bucket];
+        for (const [key, usage] of Object.entries(state[bucket])) {
+            const total = Object.hasOwn(totals, key) ? totals[key] : undefined;
+            if (total === undefined) {
+                // Define rather than assign: assigning a tool named `__proto__` would set the prototype.
+                Object.defineProperty(totals, key, { value: structuredClone(usage), enumerable: true, writable: true });
+                continue;
+            }
+            total.input += usage.input;
+            total.output += usage.output;
+            total.cacheRead += usage.cacheRead;
+            total.cacheWrite += usage.cacheWrite;
+            total.totalTokens += usage.totalTokens;
+            if (usage.cacheWrite1h !== undefined)
+                total.cacheWrite1h = (total.cacheWrite1h ?? 0) + usage.cacheWrite1h;
+            if (usage.reasoning !== undefined)
+                total.reasoning = (total.reasoning ?? 0) + usage.reasoning;
+            total.cost.input += usage.cost.input;
+            total.cost.output += usage.cost.output;
+            total.cost.cacheRead += usage.cost.cacheRead;
+            total.cost.cacheWrite += usage.cost.cacheWrite;
+            total.cost.total += usage.cost.total;
+        }
+    }
 }

package/dist/chrome.js

@@ -3,6 +3,7 @@ import { calculateContextTokens } from "@earendil-works/pi-coding-agent";
 import { UsageDoc } from "@earendil-works/pi-durable";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { bold, color } from "./theme.js";
+import { docOf } from "./view-state.js";
 /** One line, cut to the width, with `hints` at the right end: the first hints go when they do not all fit. */
 export class Line {
     text = "";
@@ -33,7 +34,7 @@ export function headerText(child, title) {
  * `contextWindow` is known and the child has answered once.
  */
 export function footerText(child, view, contextWindow) {
-    const usage = totalUsage(view.docs[UsageDoc.definition.kind]);
+    const usage = totalUsage(docOf(view, UsageDoc));
     const used = lastUsage(view.entries);
     const context = contextWindow === undefined || contextWindow === 0 || used === undefined
         ? []

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { addProject, checkProject, MAIN_PROJECT, projectDir, readProjects } from "./projects.js";
 import { AGENT_HANDLE, statePaths } from "./protocol.js";
+import { setupOnce } from "./setup.js";
 import { runTool, sendToHost } from "./tool.js";
 function fail(message) {
     throw new Error(message);
@@ -209,6 +211,10 @@ async function main() {
         all.splice(0, 2);
     }
     const [command, ...args] = all;
+    // npm 12 runs no install script by default, so an installed CLI finishes the setup. A checkout runs `cli.ts`, and
+    // the host starts from a command that already did it.
+    if (import.meta.url.endsWith(".js") && command !== "host")
+        setupOnce(fileURLToPath(new URL("..", import.meta.url)));
     if (command === "create")
         return createCommand(args);
     if (command === "projects")
@@ -239,7 +245,7 @@ async function main() {
     });
     process.stdout.write(text);
 }
-main().catch((error) => {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+main().catch((cause) => {
+    process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`);
     process.exitCode = 1;
 });

package/dist/client.d.ts

@@ -22,8 +22,8 @@ export declare class Client {
         lines: AsyncIterable<WatchLine>;
     }>;
     close(): void;
-    /** Rejects the pending requests with `reason` and closes the connection. The host then stops them. */
-    abort(reason: unknown): void;
+    /** Rejects the pending requests with `cause` and closes the connection. The host then stops them. */
+    abort(cause: unknown): void;
 }
 /**
  * A connection to the host of the project of `HARNESS_PROJECT` or the cwd (see `resolveProject`), after its `hello`.

package/dist/client.js

@@ -2,9 +2,17 @@ import { spawn } from "node:child_process";
 import { closeSync, mkdirSync, openSync } from "node:fs";
 import { createConnection } from "node:net";
 import { Readable } from "node:stream";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
 import { MAIN_PROJECT, resolveProject } from "./projects.js";
 import { cliPath, onLines, PROTOCOL_VERSION, statePaths, } from "./protocol.js";
 const START_TIMEOUT_MS = 10_000;
+/** A line from the host: a reply, or an event of the watch. The value of a reply and the event are not checked here. */
+const HostLine = Type.Union([
+    Type.Object({ ok: Type.Literal(true), value: Type.Optional(Type.Unknown()) }),
+    Type.Object({ ok: Type.Literal(false), error: Type.String() }),
+    Type.Object({ event: Type.Unknown() }),
+]);
 /**
  * A connection to the host. Requests are answered in order, one reply line for each request line. After `watch`, the
  * event lines of the watch come between the replies.
@@ -23,6 +31,10 @@ export class Client {
         this.#socket = socket;
         onLines(socket, (line) => {
             const parsed = JSON.parse(line);
+            if (!Value.Check(HostLine, parsed)) {
+                this.#pending.shift()?.reject(new Error(`The harness host sent an invalid reply: ${line}`));
+                return;
+            }
             if ("event" in parsed) {
                 this.#lines?.push(parsed.event);
                 return;
@@ -41,10 +53,12 @@ export class Client {
     request(request) {
         if (this.#ended)
             return Promise.reject(new Error("The harness host closed the connection"));
-        return new Promise((resolve, reject) => {
-            this.#pending.push({ resolve: resolve, reject });
-            this.#socket.write(`${JSON.stringify(request)}\n`);
-        });
+        const reply = Promise.withResolvers();
+        this.#pending.push(reply);
+        this.#socket.write(`${JSON.stringify(request)}\n`);
+        // SAFETY: the host answers each request line in order with the value of `Replies` for its type, and `connect`
+        // refuses a host of another protocol version.
+        return reply.promise;
     }
     /**
      * Sends the `watch` request of `handle`. Its `lines` are the events of the watch, and end when the connection closes.
@@ -59,17 +73,17 @@ export class Client {
     close() {
         this.#socket.end();
     }
-    /** Rejects the pending requests with `reason` and closes the connection. The host then stops them. */
-    abort(reason) {
-        this.#end(reason);
+    /** Rejects the pending requests with `cause` and closes the connection. The host then stops them. */
+    abort(cause) {
+        this.#end(cause);
         this.#socket.destroy();
     }
-    #end(reason = new Error("The harness host closed the connection")) {
+    #end(cause = new Error("The harness host closed the connection")) {
         if (!this.#ended)
             this.#lines?.push(null);
         this.#ended = true;
         for (const waiter of this.#pending.splice(0))
-            waiter.reject(reason);
+            waiter.reject(cause);
     }
 }
 /**

package/dist/entries.js

@@ -5,6 +5,9 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+const Entries = Type.Record(Type.String(), Type.String());
 /** The file of the entries: `$XDG_CONFIG_HOME/harness/entries.json`, default `~/.config/harness/entries.json`. */
 export function entriesPath() {
     return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "harness", "entries.json");
@@ -17,15 +20,12 @@ export function readEntries() {
         text = readFileSync(path, "utf8");
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
             return {};
         throw error;
     }
     const entries = JSON.parse(text);
-    if (typeof entries !== "object" ||
-        entries === null ||
-        Array.isArray(entries) ||
-        !Object.values(entries).every((module) => typeof module === "string" && isAbsolute(module))) {
+    if (!Value.Check(Entries, entries) || !Object.values(entries).every((module) => isAbsolute(module))) {
         throw new Error(`${path} is not an object of entry names to absolute module paths`);
     }
     return entries;

package/dist/herdr.d.ts

@@ -1,14 +1,19 @@
 import { type ChildInfo } from "./protocol.ts";
+export type ViewerTarget = {
+    title(child: ChildInfo): string;
+    project: string[];
+    resume: string[];
+};
+export type AgentReporter = {
+    report(busy: boolean): void;
+    release(): Promise<void>;
+};
 /**
  * How the viewer of `handle` on `project` shows and resumes it: the title of its child, the `--project` words, and the
  * words after them that open it again. The project agent is `harness <project>`, with no `--project`; a child is
  * `harness --project <project> attach <handle>`.
  */
-export declare function viewerTarget(handle: string, project: string): {
-    title(child: ChildInfo): string;
-    project: string[];
-    resume: string[];
-};
+export declare function viewerTarget(handle: string, project: string): ViewerTarget;
 /**
  * The words of the command that runs the viewer of `handle`, with this Node and this package's CLI, so it does not
  * need the CLI on PATH. Herdr wants a plain command name as the first word of a resume command, so it starts with
@@ -30,7 +35,4 @@ export declare function openViewerTab(child: ChildInfo, env: NodeJS.ProcessEnv):
  * the resume command. Both methods do nothing outside Herdr.
  * The calls run one after another, so `--seq` reaches Herdr in order.
  */
-export declare function agentReporter(env: NodeJS.ProcessEnv, label: string, handle: string, project: string): {
-    report(busy: boolean): void;
-    release(): Promise<void>;
-};
+export declare function agentReporter(env: NodeJS.ProcessEnv, label: string, handle: string, project: string): AgentReporter;

package/dist/herdr.js

@@ -1,7 +1,11 @@
 import { execFile } from "node:child_process";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
 import { resolveProject } from "./projects.js";
 import { AGENT_HANDLE, childLabel, cliPath, runDisplayName } from "./protocol.js";
 const HERDR_SOURCE = "custom:harness";
+/** The part of the output of `herdr tab create` that has the pane of the tab. */
+const TabCreated = Type.Object({ result: Type.Object({ root_pane: Type.Object({ pane_id: Type.String() }) }) });
 /**
  * How the viewer of `handle` on `project` shows and resumes it: the title of its child, the `--project` words, and the
  * words after them that open it again. The project agent is `harness <project>`, with no `--project`; a child is
@@ -57,15 +61,16 @@ export async function openViewerTab(child, env) {
         ...(state ? ["--env", `XDG_STATE_HOME=${state}`] : []),
         ...(config ? ["--env", `XDG_CONFIG_HOME=${config}`] : []),
     ], env);
-    let pane;
+    let output;
     try {
-        pane = JSON.parse(created).result?.root_pane?.pane_id;
+        output = JSON.parse(created);
     }
     catch {
-        pane = undefined;
+        output = undefined;
     }
-    if (typeof pane !== "string")
+    if (!Value.Check(TabCreated, output))
         throw new Error(`herdr tab create gave no pane ID: ${created.trim()}`);
+    const pane = output.result.root_pane.pane_id;
     const viewer = viewerCommand(child.handle, project)
         .map((word) => `'${word.replaceAll("'", "'\\''")}'`)
         .join(" ");