@vzlentin/harness 0.1.0 → 0.2.0

package/dist/setup.js

@@ -0,0 +1,133 @@
+/**
+ * Registers the Pi extension of a globally installed package in Pi. The `postinstall` script and the CLI of the package
+ * run it, since npm 12 does not run install scripts by default. workflows uses it too, as `@vzlentin/harness/setup`.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, join, sep } from "node:path";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+const PackageJson = Type.Object({
+    name: Type.String(),
+    version: Type.String(),
+    retiredPiPackages: Type.Optional(Type.Array(Type.String())),
+});
+const PiSettings = Type.Object({
+    packages: Type.Optional(Type.Array(Type.Union([Type.String(), Type.Object({ source: Type.String() })]))),
+});
+/**
+ * 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 function setup(packageDir) {
+    const installed = readInstalled(packageDir);
+    if (installed === undefined || !isTopLevelGlobal(installed))
+        return;
+    if (registerExtension(installed))
+        writeStamp(installed);
+}
+/**
+ * `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 function setupOnce(packageDir) {
+    try {
+        const installed = readInstalled(packageDir);
+        if (installed === undefined || !isTopLevelGlobal(installed) || existsSync(stampPath(installed)))
+            return;
+        if (registerExtension(installed))
+            writeStamp(installed);
+    }
+    catch (error) {
+        process.stderr.write(`harness: setup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+/**
+ * True when `dir` is `<global root>/<name>`: `<root>` is a `node_modules` folder in `lib` (in the prefix on Windows),
+ * and has no other `node_modules` above it. A copy nested in another package is not top-level.
+ */
+function isTopLevelGlobal({ dir, json }) {
+    const name = json.name.split("/").join(sep);
+    if (!dir.endsWith(`${sep}${name}`))
+        return false;
+    const root = dir.slice(0, -name.length - 1);
+    const segments = root.split(sep);
+    if (segments.at(-1) !== "node_modules" || segments.indexOf("node_modules") !== segments.length - 1)
+        return false;
+    return process.platform === "win32" || segments.at(-2) === "lib";
+}
+function readInstalled(packageDir) {
+    const dir = realpathSync(packageDir);
+    const json = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    return Value.Check(PackageJson, json) ? { dir, json } : undefined;
+}
+/** The stamp of `setup`: `$XDG_STATE_HOME/harness/.setup/<hash of path and version>`. */
+function stampPath({ dir, json }) {
+    const hash = createHash("sha256").update(`${dir}\n${json.version}`).digest("hex");
+    return join(process.env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "harness", ".setup", hash);
+}
+function writeStamp(installed) {
+    const path = stampPath(installed);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${installed.dir}\n${installed.json.version}\n`);
+}
+/** False when a `pi` command failed. */
+function registerExtension({ dir, json }) {
+    const label = basename(json.name);
+    const extension = join(dir, "pi");
+    const later = `To add the Pi extension of ${label}, run: pi install ${extension}`;
+    const listed = piPackages();
+    for (const retired of json.retiredPiPackages ?? []) {
+        for (const source of listed.filter((item) => item === retired || item.startsWith(`${retired}@`))) {
+            process.stderr.write(`${label}: removing ${source} from Pi, which ${json.name} replaces\n`);
+            if (!runPi(label, ["remove", source], `To remove it, run: pi remove ${source}`))
+                return false;
+        }
+    }
+    return runPi(label, ["install", extension], later);
+}
+/** Runs `pi`, with a warning when it is missing or fails. False when it failed; true when it worked or is missing. */
+function runPi(label, args, later) {
+    const result = spawnSync("pi", args, {
+        env: { ...process.env, PATH: userPath() },
+        stdio: ["ignore", 2, 2],
+        timeout: 120_000,
+    });
+    if (result.error !== undefined && "code" in result.error && result.error.code === "ENOENT") {
+        process.stderr.write(`${label}: pi is not on PATH. ${later}\n`);
+        return true;
+    }
+    if (result.error !== undefined || result.status !== 0) {
+        const reason = result.error?.message ?? `exit ${result.status ?? result.signal}`;
+        process.stderr.write(`${label}: pi ${args[0]} failed (${reason}). ${later}\n`);
+        return false;
+    }
+    return true;
+}
+/** The `PATH` without the `node_modules/.bin` folders that npm adds: pi-coding-agent there has its own `pi`. */
+function userPath() {
+    return (process.env.PATH ?? "")
+        .split(delimiter)
+        .filter((entry) => !entry.endsWith(join("node_modules", ".bin")))
+        .join(delimiter);
+}
+/** The sources of the packages in Pi's global settings, or none when the file is missing or not valid. */
+function piPackages() {
+    const env = process.env.PI_CODING_AGENT_DIR;
+    const agentDir = env ? env.replace(/^~(?=$|\/)/, homedir()) : join(homedir(), ".pi", "agent");
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (!Value.Check(PiSettings, settings))
+        return [];
+    return (settings.packages ?? []).map((item) => (Value.Check(Type.String(), item) ? item : item.source));
+}

package/dist/tasks.js

@@ -42,14 +42,8 @@ export async function taskInfo(harness, key) {
     const record = await harness.getTask(id, context);
     if (record === undefined)
         throw new Error(`Missing task ${id}`);
-    return {
-        key,
-        id,
-        kind: record.kind,
-        version: record.version,
-        status: record.state.status,
-        ...(record.state.status === "terminal" ? { outcome: record.state.outcome } : {}),
-    };
+    const info = { key, id, kind: record.kind, version: record.version, status: record.state.status };
+    return record.state.status === "terminal" ? { ...info, outcome: record.state.outcome } : info;
 }
 /** Waits until the task of `key` is terminal, or the connection closes, and gives its info with the outcome. */
 export async function waitTask(host, key) {
@@ -74,5 +68,7 @@ function startableTask(startable, kind) {
     const task = startable.tasks?.find((found) => found.definition.name === kind);
     if (task === undefined)
         throw new Error(`Unknown task kind: ${kind}`);
+    // SAFETY: `AnyTask` is a `Task` with its types erased. The store keeps the input, the phase state and the result of
+    // every task as JSON.
     return task;
 }

package/dist/theme.js

@@ -9,6 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // Pi gives its theme object only to extensions. Pi's cards color with the theme that `initTheme()` sets in this module,
 // so the viewer loads the same module by its path to color its own lines the same way. The path is not in the `exports`
 // of pi-coding-agent, so it holds only for the pinned version 1.3.0.
+// SAFETY: this module of pi-coding-agent 1.3.0, the version that package.json pins, exports the `theme` of Pi's cards.
 const piTheme = (await import(__rewriteRelativeImportExtension(new URL("./modes/interactive/theme/theme.js", import.meta.resolve("@earendil-works/pi-coding-agent")).href)));
 export function color(name, text) {
     return piTheme.theme.fg(name, text);

package/dist/tool.d.ts

@@ -4,7 +4,7 @@ import type { Static } from "@earendil-works/pi-ai";
 import type * as Durable from "@earendil-works/pi-durable";
 import type { Extension, ToolExecutionApi } from "@earendil-works/pi-durable";
 import { type Replies, type Request } from "./protocol.ts";
-export declare const TOOL_DESCRIPTION = "Spawn and manage subagents: separate agents with their own context, for second opinions, independent investigations and delegated work.\n- spawn: start a child with `prompts` and `files`. It uses your provider, model and thinking level unless you give others. Give it a short `name`. It prints `Spawned <name> (<handle>)`. The handle is the short hex ID in parentheses, not the name.\n- status, wait, send, rename, stop: act on the child `handle`. `wait` waits until the child answers its last message (up to `timeout` seconds, default 1800) and gives the answer. `stop` also stops the children the child spawned. `send` steers a busy child, or queues `message` with `followUp`.\n- list: your children.\nCalls in one message run one after another, in message order, so a `wait` after a `send` gives the answer to that message.\nChildren persist after a turn. Stop each child when you no longer need it.";
+export declare const TOOL_DESCRIPTION = "Spawn and manage subagents: separate agents with their own context, for second opinions, independent investigations and delegated work.\n- spawn: start a child with `prompts` and `files`. It uses your provider, model and thinking level unless you give others. Give it a short `name`. It prints `Spawned <name> (<handle>)`. The handle is the short hex ID in parentheses, not the name.\n- status, wait, send, rename, stop: act on the child `handle`. `wait` waits until the child answers its last message (up to `timeout` seconds, default 1800) and gives the answer, after the earlier answers of the spawn and the sends that no `wait` gave. `stop` also stops the children the child spawned. `send` steers a busy child, or queues `message` with `followUp`.\n- list: your children.\nCalls in one message run one after another, in message order, so a `wait` after a `send` gives the answer to that message.\nChildren persist after a turn. Stop each child when you no longer need it.";
 /** The parameters and the output schema of the tool, built with the `Type` of the caller's pi-ai. */
 export declare function toolSchemas(Type: typeof Ai.Type): {
     parameters: Ai.Type.TObject<{

package/dist/tool.js

@@ -7,7 +7,7 @@ const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhi
 const NO_ABORT = new AbortController().signal;
 export const TOOL_DESCRIPTION = `Spawn and manage subagents: separate agents with their own context, for second opinions, independent investigations and delegated work.
 - spawn: start a child with \`prompts\` and \`files\`. It uses your provider, model and thinking level unless you give others. Give it a short \`name\`. It prints \`Spawned <name> (<handle>)\`. The handle is the short hex ID in parentheses, not the name.
-- status, wait, send, rename, stop: act on the child \`handle\`. \`wait\` waits until the child answers its last message (up to \`timeout\` seconds, default 1800) and gives the answer. \`stop\` also stops the children the child spawned. \`send\` steers a busy child, or queues \`message\` with \`followUp\`.
+- status, wait, send, rename, stop: act on the child \`handle\`. \`wait\` waits until the child answers its last message (up to \`timeout\` seconds, default 1800) and gives the answer, after the earlier answers of the spawn and the sends that no \`wait\` gave. \`stop\` also stops the children the child spawned. \`send\` steers a busy child, or queues \`message\` with \`followUp\`.
 - list: your children.
 Calls in one message run one after another, in message order, so a \`wait\` after a \`send\` gives the answer to that message.
 Children persist after a turn. Stop each child when you no longer need it.`;
@@ -140,19 +140,23 @@ function spawnRequest(args, scope, requestId) {
     let prompt = files.map(fileText).join("");
     if (prompts.length > 0)
         prompt += `Task:\n${prompts.join("\n\n")}`;
-    return {
+    let request = {
         type: "spawn",
         requestId,
         caller: scope.caller,
-        ...(name === undefined ? {} : { name }),
         provider,
         model,
-        ...(args.thinking === undefined ? {} : { thinking: args.thinking }),
         callerThinking: scope.thinking,
         cwd,
-        ...(tools === undefined ? {} : { tools }),
         prompt,
     };
+    if (name !== undefined)
+        request = { ...request, name };
+    if (args.thinking !== undefined)
+        request = { ...request, thinking: args.thinking };
+    if (tools !== undefined)
+        request = { ...request, tools };
+    return request;
 }
 /** The text of `file` in a `<file>` block. An empty file gives nothing. */
 function fileText(file) {

package/dist/view-state.d.ts

@@ -2,11 +2,14 @@
  * What the viewer reads from the documents of a durable conversation view: its live state, its inbox and the texts of
  * its user messages.
  */
+import type { JsonRepresentation } from "@earendil-works/chord";
 import type { UserMessage } from "@earendil-works/pi-ai";
-import { type ConversationView, type InboxState, type LiveState } from "@earendil-works/pi-durable";
+import { type ConversationDocToken, type ConversationView, type InboxState, type JsonObject, type LiveState } from "@earendil-works/pi-durable";
+/** The built-in document of `token` in `view`, if the conversation has it. */
+export declare function docOf<T extends JsonObject>(view: ConversationView, token: ConversationDocToken<T>): T | undefined;
 export declare function liveOf(view: ConversationView): LiveState;
 export declare function inboxOf(view: ConversationView): InboxState;
-export declare function userText(content: UserMessage["content"]): string;
+export declare function userText(content: JsonRepresentation<UserMessage["content"]>): string;
 /** The queued steers and follow-ups, in inbox order. */
 export declare function queued(inbox: InboxState): {
     mode: "steer" | "followUp";

package/dist/view-state.js

@@ -1,12 +1,17 @@
-import { InboxDoc, LiveDoc } from "@earendil-works/pi-durable";
+import { InboxDoc, LiveDoc, } from "@earendil-works/pi-durable";
+/** The built-in document of `token` in `view`, if the conversation has it. */
+export function docOf(view, token) {
+    // SAFETY: pi-durable keeps each built-in conversation document in `docs` under the kind of its token.
+    return view.docs[token.definition.kind];
+}
 export function liveOf(view) {
-    return view.docs[LiveDoc.definition.kind] ?? {};
+    return docOf(view, LiveDoc) ?? {};
 }
 export function inboxOf(view) {
-    return view.docs[InboxDoc.definition.kind] ?? { items: [] };
+    return docOf(view, InboxDoc) ?? { items: [] };
 }
 export function userText(content) {
-    if (typeof content === "string")
+    if (!Array.isArray(content))
         return content;
     return content
         .filter((block) => block.type === "text")

package/dist/viewer.js

@@ -300,8 +300,8 @@ class Viewer {
         await this.reporter.release();
         this.#exit(code);
     }
-    showError = (error) => {
-        this.notice.setText(color("error", `Error: ${error instanceof Error ? error.message : String(error)}`));
+    showError = (cause) => {
+        this.notice.setText(color("error", `Error: ${cause instanceof Error ? cause.message : String(cause)}`));
         this.tui.requestRender();
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vzlentin/harness",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "A durable agent harness on Pi, starting with observable, persistent subagents",
 	"repository": {
 		"type": "git",
@@ -18,7 +18,9 @@
 		"./package.json": "./package.json"
 	},
 	"files": [
-		"dist"
+		"dist",
+		"pi",
+		"scripts/postinstall.js"
 	],
 	"engines": {
 		"node": ">=22.19.0"
@@ -26,7 +28,8 @@
 	"scripts": {
 		"build": "rm -rf dist && tsc -p tsconfig.build.json",
 		"prepack": "npm run build",
-		"check": "biome check . && tsc -p tsconfig.json && vitest --run --passWithNoTests",
+		"postinstall": "node scripts/postinstall.js",
+		"check": "biome check . && oxlint --deny-warnings && npm run build && tsc -p tsconfig.json && vitest --run --passWithNoTests",
 		"test": "vitest --run --passWithNoTests"
 	},
 	"dependencies": {
@@ -35,14 +38,20 @@
 		"@earendil-works/pi-coding-agent": "1.3.0",
 		"@earendil-works/pi-durable": "1.3.0",
 		"@earendil-works/pi-tui": "1.3.0",
-		"jiti": "2.7.0"
+		"jiti": "2.7.0",
+		"typebox": "1.3.27"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.15",
+		"@oxlint/plugins": "1.88.0",
 		"@types/node": "26.6.4",
+		"oxlint": "1.88.0",
 		"typescript": "7.0.2",
 		"vitest": "5.0.3"
 	},
+	"retiredPiPackages": [
+		"npm:@vzlentin/pi-subagent"
+	],
 	"publishConfig": {
 		"access": "public"
 	}

package/pi/index.ts

@@ -0,0 +1,168 @@
+/**
+ * The `subagent` tool, `/subagent` and the subagents widget. They use the client of the harness package that holds
+ * this folder, from its built `dist/`, and start the host of that package.
+ */
+import { resolve } from "node:path";
+import { Type } from "@earendil-works/pi-ai";
+import {
+	type ExtensionAPI,
+	type ExtensionContext,
+	getAgentDir,
+	hasTrustRequiringProjectResources,
+	ProjectTrustStore,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { request } from "../dist/client.js";
+import { openViewerTab } from "../dist/herdr.js";
+import { childLine, runDisplayName } from "../dist/protocol.js";
+import * as tool from "../dist/tool.js";
+
+const SESSION_TRUST_HINT =
+	"The child gets no project skills (.pi/skills, .agents/skills): this project is trusted for this Pi session only, and children see only the trust saved for future sessions. To give children project skills, run /trust and choose Trust.";
+
+export default function subagentExtension(pi: ExtensionAPI) {
+	const { parameters, output } = tool.toolSchemas(Type);
+	pi.registerTool({
+		name: "subagent",
+		label: "Subagent",
+		description: tool.TOOL_DESCRIPTION,
+		parameters,
+		outputSchema: output,
+		executionMode: "sequential",
+		async execute(toolCallId, args, signal, _onUpdate, ctx) {
+			const { text, data } = await tool.runTool(args, {
+				caller: ctx.sessionManager.getSessionId(),
+				callKey: toolCallId,
+				provider: ctx.model?.provider,
+				model: ctx.model?.id,
+				thinking: pi.getThinkingLevel(),
+				cwd: ctx.cwd,
+				send: tool.sendToHost,
+				signal,
+			});
+
+			// Children follow only the saved trust, so a session that trusts its project for itself says what the child misses.
+			const sessionOnly =
+				args.action === "spawn" &&
+				ctx.isProjectTrusted() &&
+				!savedTrust(ctx.cwd) &&
+				!savedTrust(resolve(ctx.cwd, args.cwd ?? "."));
+
+			const hint = sessionOnly ? `\n${SESSION_TRUST_HINT}\n` : "";
+
+			return { content: [{ type: "text", text: text + hint }], details: undefined, structuredContent: data };
+		},
+	});
+
+	pi.registerCommand("subagent", {
+		description: "Open the viewer of a subagent spawned by this session",
+		handler: async (_args, ctx) => {
+			const children = await request({ type: "list", caller: ctx.sessionManager.getSessionId() }, { start: true });
+
+			if (children.length === 0) {
+				ctx.ui.notify("No subagents spawned by this session", "info");
+
+				return;
+			}
+
+			const chosen = await ctx.ui.select("Attach to subagent", children.map(childLine));
+
+			// A name can start with the display name of another child, so the longest match is the chosen child.
+			const child = children
+				.filter((c: { handle: string; name?: string }) => chosen?.startsWith(`${runDisplayName(c)}  `))
+				.sort(
+					(a: { handle: string; name?: string }, b: { handle: string; name?: string }) =>
+						runDisplayName(b).length - runDisplayName(a).length,
+				)[0];
+
+			if (child === undefined) return;
+			const command = `harness attach ${child.handle}`;
+
+			if (!process.env.HERDR_ENV) {
+				ctx.ui.notify(`Run in another terminal: ${command}`, "info");
+
+				return;
+			}
+
+			try {
+				await openViewerTab(child, process.env);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				ctx.ui.notify(`Could not open a Herdr tab: ${message}. Run in another terminal: ${command}`, "error");
+			}
+		},
+	});
+
+	let widgetTimer: ReturnType<typeof setInterval> | undefined;
+	let widgetContext: ExtensionContext | undefined;
+	let refreshing = false;
+
+	// The widget does not start the host: when none runs, it shows nothing.
+	const refreshWidget = async (): Promise<void> => {
+		if (!widgetContext || refreshing) return;
+		refreshing = true;
+
+		try {
+			const context = widgetContext;
+
+			const children = await request(
+				{ type: "list", caller: context.sessionManager.getSessionId() },
+				{ start: false },
+			).catch(() => undefined);
+
+			if (context !== widgetContext) return;
+
+			if (children === undefined || children.length === 0) {
+				context.ui.setWidget("subagents", undefined);
+
+				return;
+			}
+
+			const theme = context.ui.theme;
+
+			const visible = children
+				.slice(0, 5)
+				.map(({ name, handle, state }: { name?: string; handle: string; state: string }) => {
+					const color = state === "busy" ? "warning" : state === "idle" ? "success" : "error";
+
+					return theme.fg(color, `${name ?? handle}:${state}`);
+				});
+
+			if (children.length > visible.length) visible.push(theme.fg("muted", `+${children.length - visible.length}`));
+			context.ui.setWidget("subagents", [theme.fg("dim", "subagents: ") + visible.join(theme.fg("dim", " | "))], {
+				placement: "belowEditor",
+			});
+		} finally {
+			refreshing = false;
+		}
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		if (!ctx.hasUI) return;
+		widgetContext = ctx;
+		void refreshWidget();
+		widgetTimer = setInterval(() => void refreshWidget(), 1000);
+		widgetTimer.unref();
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		if (widgetTimer) clearInterval(widgetTimer);
+		widgetTimer = undefined;
+		widgetContext = undefined;
+		ctx.ui.setWidget("subagents", undefined);
+	});
+}
+
+/**
+ * Whether Pi trusts the project in `cwd` with no one to ask, as the host does in `src/trust.ts` of harness. It is here
+ * with Pi's own modules, so Pi does not load the copy of pi-coding-agent that harness installs.
+ */
+function savedTrust(cwd: string): boolean {
+	if (!hasTrustRequiringProjectResources(cwd)) return true;
+	const agentDir = getAgentDir();
+	const decision = new ProjectTrustStore(agentDir).get(cwd);
+
+	if (decision !== null) return decision;
+
+	return SettingsManager.create(cwd, agentDir, { projectTrusted: false }).getDefaultProjectTrust() === "always";
+}

package/pi/package.json

@@ -0,0 +1,14 @@
+{
+	"private": true,
+	"description": "The Pi extension of harness: the subagent tool, the /subagent command and the subagents widget",
+	"type": "module",
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*"
+	}
+}

package/scripts/postinstall.js

@@ -0,0 +1,13 @@
+// Registers `pi/` in Pi after a global install, with `setup` of `dist/setup.js`. Plain JavaScript, since Node does not
+// strip types under node_modules. Other installs, such as `npm ci` in a checkout without `dist/`, do nothing, and an
+// error must not fail the npm install.
+import { fileURLToPath } from "node:url";
+
+if (process.env.npm_config_global === "true") {
+	try {
+		const { setup } = await import("../dist/setup.js");
+		setup(fileURLToPath(new URL("..", import.meta.url)));
+	} catch (error) {
+		console.warn(`harness: setup failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}