@vzlentin/harness 0.0.0-stage → 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.d.ts

@@ -0,0 +1,31 @@
+import type { AnyTask, Conversation, Extension, Harness } from "@earendil-works/pi-durable";
+import type { Request, TaskInfo } from "./protocol.ts";
+/** What the task requests use of the host. */
+export type TaskHost = {
+    readonly harness: Harness;
+    /** The root conversation, which owns the started tasks. */
+    readonly root: Conversation;
+    /** The tasks that `start` can create, from `startableTasks`. */
+    readonly startable: Extension;
+    /** Aborted when the connection of the request closes. */
+    readonly signal: AbortSignal;
+};
+/**
+ * The extension of the tasks of the entries, which is the list of the kinds that `start` can create. The
+ * registry refuses a task name that two entries give.
+ */
+export declare function startableTasks(tasks: readonly AnyTask[]): Extension;
+/**
+ * Starts the task of `request.key` once. It is a background task of the root conversation, so an abort of the project
+ * agent's turn does not reach it. The key is written in the commit that creates the task, so a start after a crash
+ * finds it.
+ */
+export declare function startTask(host: TaskHost, request: Extract<Request, {
+    type: "start";
+}>): Promise<TaskInfo>;
+/** The info of the task that `start` created for `key`. */
+export declare function taskInfo(harness: Harness, key: string): Promise<TaskInfo>;
+/** Waits until the task of `key` is terminal, or the connection closes, and gives its info with the outcome. */
+export declare function waitTask(host: TaskHost, key: string): Promise<TaskInfo>;
+/** Aborts the task of `key`. The abort reaches the conversations that the task owns, and their turns. */
+export declare function abortTask(harness: Harness, key: string): Promise<TaskInfo>;

package/dist/tasks.js

@@ -0,0 +1,74 @@
+import { BACKGROUND_CONTEXT, withAbortSignal } from "@earendil-works/chord/context";
+import * as durable from "@earendil-works/pi-durable";
+const context = BACKGROUND_CONTEXT;
+/** The tasks that `start` created, by client key. A key is never removed. */
+const StartedTasks = durable.defineDoc({
+    kind: "harness.tasks",
+    version: 1,
+    scope: "session",
+    initial: () => ({ tasks: {} }),
+});
+/**
+ * The extension of the tasks of the entries, which is the list of the kinds that `start` can create. The
+ * registry refuses a task name that two entries give.
+ */
+export function startableTasks(tasks) {
+    return durable.defineExtension({ name: "harness-entry-tasks", tasks });
+}
+/**
+ * Starts the task of `request.key` once. It is a background task of the root conversation, so an abort of the project
+ * agent's turn does not reach it. The key is written in the commit that creates the task, so a start after a crash
+ * finds it.
+ */
+export async function startTask(host, request) {
+    await host.root.commit(async (tx) => {
+        const state = await tx.doc(StartedTasks);
+        if (Object.hasOwn(state.tasks, request.key))
+            return;
+        const task = startableTask(host.startable, request.kind);
+        if (request.version !== undefined && task.definition.version !== request.version) {
+            throw new Error(`This host has version ${task.definition.version} of ${request.kind}, not ${request.version}: stop the host so it starts again with the installed version`);
+        }
+        state.tasks[request.key] = await tx.createTask(task, request.input, {
+            ownership: { kind: "conversation" },
+            background: true,
+        });
+    }, context);
+    return taskInfo(host.harness, request.key);
+}
+/** The info of the task that `start` created for `key`. */
+export async function taskInfo(harness, key) {
+    const id = await taskId(harness, key);
+    const record = await harness.getTask(id, context);
+    if (record === undefined)
+        throw new Error(`Missing task ${id}`);
+    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) {
+    await host.harness.waitForTask(await taskId(host.harness, key), withAbortSignal(host.signal, context));
+    return taskInfo(host.harness, key);
+}
+/** Aborts the task of `key`. The abort reaches the conversations that the task owns, and their turns. */
+export async function abortTask(harness, key) {
+    await harness.abortTask(await taskId(harness, key), context);
+    return taskInfo(harness, key);
+}
+/** The ID of the task that `start` created for `key`. */
+async function taskId(harness, key) {
+    const state = await harness.snapshot(StartedTasks, context);
+    const id = state != null && Object.hasOwn(state.tasks, key) ? state.tasks[key] : undefined;
+    if (id === undefined)
+        throw new Error(`Unknown task: ${key}`);
+    return id;
+}
+/** The task of `kind` in `startable`. The entries give erased tasks, so this is where they get the type of `createTask`. */
+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.d.ts

@@ -0,0 +1,3 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+export declare function color(name: Parameters<Theme["fg"]>[0], text: string): string;
+export declare function bold(text: string): string;

package/dist/theme.js

@@ -0,0 +1,19 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// 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);
+}
+export function bold(text) {
+    return piTheme.theme.bold(text);
+}

package/dist/tool.d.ts

@@ -0,0 +1,137 @@
+import type { Context } from "@earendil-works/chord/context";
+import type * as Ai from "@earendil-works/pi-ai";
+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, 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<{
+        action: Ai.Type.TUnion<[Ai.Type.TLiteral<"spawn">, Ai.Type.TLiteral<"send">, Ai.Type.TLiteral<"wait">, Ai.Type.TLiteral<"status">, Ai.Type.TLiteral<"rename">, Ai.Type.TLiteral<"list">, Ai.Type.TLiteral<"stop">]>;
+        name: Ai.Type.TOptional<Ai.Type.TString>;
+        provider: Ai.Type.TOptional<Ai.Type.TString>;
+        model: Ai.Type.TOptional<Ai.Type.TString>;
+        thinking: Ai.Type.TOptional<Ai.Type.TString>;
+        cwd: Ai.Type.TOptional<Ai.Type.TString>;
+        tools: Ai.Type.TOptional<Ai.Type.TArray<Ai.Type.TString>>;
+        prompts: Ai.Type.TOptional<Ai.Type.TArray<Ai.Type.TString>>;
+        files: Ai.Type.TOptional<Ai.Type.TArray<Ai.Type.TString>>;
+        handle: Ai.Type.TOptional<Ai.Type.TString>;
+        message: Ai.Type.TOptional<Ai.Type.TString>;
+        followUp: Ai.Type.TOptional<Ai.Type.TBoolean>;
+        timeout: Ai.Type.TOptional<Ai.Type.TInteger>;
+        key: Ai.Type.TOptional<Ai.Type.TString>;
+    }>;
+    output: Ai.Type.TUnion<[Ai.Type.TObject<{
+        action: Ai.Type.TLiteral<"spawn">;
+        value: Ai.Type.TObject<{
+            handle: Ai.Type.TString;
+            name: Ai.Type.TOptional<Ai.Type.TString>;
+            state: Ai.Type.TUnion<[Ai.Type.TLiteral<"busy">, Ai.Type.TLiteral<"idle">, Ai.Type.TLiteral<"error">]>;
+            provider: Ai.Type.TString;
+            model: Ai.Type.TString;
+            thinking: Ai.Type.TString;
+            cwd: Ai.Type.TString;
+        }>;
+    }>, Ai.Type.TObject<{
+        action: Ai.Type.TLiteral<"send">;
+        value: Ai.Type.TObject<{
+            verb: Ai.Type.TString;
+            child: Ai.Type.TObject<{
+                handle: Ai.Type.TString;
+                name: Ai.Type.TOptional<Ai.Type.TString>;
+                state: Ai.Type.TUnion<[Ai.Type.TLiteral<"busy">, Ai.Type.TLiteral<"idle">, Ai.Type.TLiteral<"error">]>;
+                provider: Ai.Type.TString;
+                model: Ai.Type.TString;
+                thinking: Ai.Type.TString;
+                cwd: Ai.Type.TString;
+            }>;
+        }>;
+    }>, Ai.Type.TObject<{
+        action: Ai.Type.TLiteral<"wait">;
+        value: Ai.Type.TObject<{
+            answer: Ai.Type.TString;
+        }>;
+    }>, Ai.Type.TObject<{
+        action: Ai.Type.TLiteral<"status">;
+        value: Ai.Type.TObject<{
+            handle: Ai.Type.TString;
+            name: Ai.Type.TOptional<Ai.Type.TString>;
+            state: Ai.Type.TUnion<[Ai.Type.TLiteral<"busy">, Ai.Type.TLiteral<"idle">, Ai.Type.TLiteral<"error">]>;
+            provider: Ai.Type.TString;
+            model: Ai.Type.TString;
+            thinking: Ai.Type.TString;
+            cwd: Ai.Type.TString;
+        }>;
+    }>, Ai.Type.TObject<{
+        action: Ai.Type.TLiteral<"rename">;
+        value: Ai.Type.TObject<{
+            handle: Ai.Type.TString;
+            name: Ai.Type.TOptional<Ai.Type.TString>;
+            state: Ai.Type.TUnion<[Ai.Type.TLiteral<"busy">, Ai.Type.TLiteral<"idle">, Ai.Type.TLiteral<"error">]>;
+            provider: Ai.Type.TString;
+            model: Ai.Type.TString;
+            thinking: Ai.Type.TString;
+            cwd: Ai.Type.TString;
+        }>;
+    }>, Ai.Type.TObject<{
+        action: Ai.Type.TLiteral<"list">;
+        value: Ai.Type.TArray<Ai.Type.TObject<{
+            handle: Ai.Type.TString;
+            name: Ai.Type.TOptional<Ai.Type.TString>;
+            state: Ai.Type.TUnion<[Ai.Type.TLiteral<"busy">, Ai.Type.TLiteral<"idle">, Ai.Type.TLiteral<"error">]>;
+            provider: Ai.Type.TString;
+            model: Ai.Type.TString;
+            thinking: Ai.Type.TString;
+            cwd: Ai.Type.TString;
+        }>>;
+    }>, Ai.Type.TObject<{
+        action: Ai.Type.TLiteral<"stop">;
+        value: Ai.Type.TObject<{
+            handle: Ai.Type.TString;
+            name: Ai.Type.TOptional<Ai.Type.TString>;
+        }>;
+    }>]>;
+};
+type Schemas = ReturnType<typeof toolSchemas>;
+export type ToolArgs = Static<Schemas["parameters"]>;
+/** The result of a call: the text for the model, the same as the CLI output, and the host's reply for programs. */
+export type ToolResult = {
+    readonly text: string;
+    readonly data: Static<Schemas["output"]>;
+};
+/** Sends one request to the host and gives its reply. */
+export type Send = <T extends Request["type"]>(request: Extract<Request, {
+    type: T;
+}>, signal: AbortSignal) => Promise<Replies[T]>;
+/** Sends through the host's socket, and starts the host when none runs. */
+export declare const sendToHost: Send;
+/** What a tool call gets from its adapter. */
+export type ToolScope = {
+    /** The caller that owns the children. */
+    readonly caller: string;
+    /** The identity of the call. Without `key`, it is the key of a spawn or send. */
+    readonly callKey: string;
+    readonly provider: string | undefined;
+    readonly model: string | undefined;
+    readonly thinking: string;
+    /** Relative `cwd` and `files` paths resolve against it. A caller without one cannot spawn. */
+    readonly cwd: string | undefined;
+    readonly send: Send;
+    readonly signal: AbortSignal | undefined;
+};
+/** Runs one call of the tool. */
+export declare function runTool(args: ToolArgs, scope: ToolScope): Promise<ToolResult>;
+/** How a host reaches the harness host. */
+export type DurableScope = {
+    /** The caller that owns the children of the calling conversation. */
+    caller(api: ToolExecutionApi, context: Context): Promise<string>;
+    readonly send: Send;
+};
+/**
+ * The pi-durable extension with the `subagent` tool. A call that runs again after a restart has the same task, so its
+ * spawn or send has the same request ID and does not repeat.
+ */
+export declare function subagentTool(durable: typeof Durable, ai: typeof Ai, scope: DurableScope): Extension;
+export {};

package/dist/tool.js

@@ -0,0 +1,213 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { request } from "./client.js";
+import { childLine, isValidRunName, runDisplayName } from "./protocol.js";
+const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+/** The signal of a call that its adapter cannot abort. */
+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, 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.`;
+/** The parameters and the output schema of the tool, built with the `Type` of the caller's pi-ai. */
+export function toolSchemas(Type) {
+    const text = (description) => Type.Optional(Type.String({ description }));
+    const texts = (description) => Type.Optional(Type.Array(Type.String(), { description }));
+    const parameters = Type.Object({
+        action: Type.Union([
+            Type.Literal("spawn"),
+            Type.Literal("send"),
+            Type.Literal("wait"),
+            Type.Literal("status"),
+            Type.Literal("rename"),
+            Type.Literal("list"),
+            Type.Literal("stop"),
+        ], { description: "What to do" }),
+        name: text("spawn, rename: the child's name, 1 to 64 characters"),
+        provider: text("spawn: the provider; default yours"),
+        model: text("spawn: the model; default yours"),
+        thinking: text("spawn: off, minimal, low, medium, high, xhigh or max; default yours"),
+        cwd: text("spawn: the child's working directory; default yours"),
+        tools: texts("spawn: the only tools the child gets; default read, grep, find, ls, write, edit, bash and the package tools"),
+        prompts: texts("spawn: the task, in parts"),
+        files: texts("spawn: files whose text goes before the task"),
+        handle: text("send, wait, status, rename, stop: the hex ID that spawn prints in parentheses, not the name"),
+        message: text("send: the message"),
+        followUp: Type.Optional(Type.Boolean({ description: "send: queue after the current answer, not a steer" })),
+        timeout: Type.Optional(Type.Integer({ minimum: 1, description: "wait: seconds; default 1800" })),
+        key: text("spawn, send: a key that makes a repeated call do nothing; default the call"),
+    });
+    const child = Type.Object({
+        handle: Type.String(),
+        name: Type.Optional(Type.String()),
+        state: Type.Union([Type.Literal("busy"), Type.Literal("idle"), Type.Literal("error")]),
+        provider: Type.String(),
+        model: Type.String(),
+        thinking: Type.String(),
+        cwd: Type.String(),
+    });
+    const result = (action, value) => Type.Object({ action: Type.Literal(action), value });
+    const output = Type.Union([
+        result("spawn", child),
+        result("send", Type.Object({ verb: Type.String(), child })),
+        result("wait", Type.Object({ answer: Type.String() })),
+        result("status", child),
+        result("rename", child),
+        result("list", Type.Array(child)),
+        result("stop", Type.Object({ handle: Type.String(), name: Type.Optional(Type.String()) })),
+    ]);
+    return { parameters, output };
+}
+/** Sends through the host's socket, and starts the host when none runs. */
+export const sendToHost = (message, signal) => request(message, { start: true, signal });
+/** Runs one call of the tool. */
+export async function runTool(args, scope) {
+    const { action } = args;
+    const { send, caller } = scope;
+    const signal = scope.signal ?? NO_ABORT;
+    const requestId = `${caller}:${args.key ?? scope.callKey}`;
+    const handle = () => checkHandle(required(args.handle, "handle", action));
+    switch (action) {
+        case "spawn": {
+            const child = await send(spawnRequest(args, scope, requestId), signal);
+            return { text: `Spawned ${runDisplayName(child)}\nState: busy\n`, data: { action, value: child } };
+        }
+        case "send": {
+            const message = required(args.message?.trim(), "message", action);
+            const followUp = args.followUp === true;
+            const sent = await send({ type: "send", requestId, caller, handle: handle(), message, followUp }, signal);
+            return { text: `${sent.verb} ${runDisplayName(sent.child)}\n`, data: { action, value: sent } };
+        }
+        case "wait": {
+            const target = handle();
+            const waited = await send({ type: "wait", handle: target, timeout: args.timeout ?? 1800 }, signal);
+            return { text: `${target} finished\n\n${waited.answer}\n`, data: { action, value: waited } };
+        }
+        case "status": {
+            const child = await send({ type: "status", handle: handle() }, signal);
+            const text = `${runDisplayName(child)}: ${child.state} (${child.provider}/${child.model}, ${child.thinking})\n`;
+            return { text, data: { action, value: child } };
+        }
+        case "rename": {
+            const name = normalizeRunName(required(args.name, "name", action));
+            const child = await send({ type: "rename", caller, handle: handle(), name }, signal);
+            return { text: `Renamed ${runDisplayName(child)}\n`, data: { action, value: child } };
+        }
+        case "list": {
+            const children = await send({ type: "list", caller }, signal);
+            const text = children.length === 0 ? "No subagents\n" : children.map((child) => `${childLine(child)}\n`).join("");
+            return { text, data: { action, value: [...children] } };
+        }
+        case "stop": {
+            const stopped = await send({ type: "stop", caller, handle: handle() }, signal);
+            return { text: `Stopped ${runDisplayName(stopped)}\n`, data: { action, value: stopped } };
+        }
+        default:
+            throw new Error(`Unknown action: ${String(action)}`);
+    }
+}
+/** The spawn request of `args`, with the defaults of `scope`. */
+function spawnRequest(args, scope, requestId) {
+    const provider = args.provider ?? scope.provider;
+    const model = args.model ?? scope.model;
+    const thinking = args.thinking ?? scope.thinking;
+    if (!provider)
+        throw new Error("No provider specified and the caller has no model");
+    if (!model)
+        throw new Error("No model specified and the caller has no model");
+    if (!THINKING_LEVELS.has(thinking))
+        throw new Error(`Invalid thinking level: ${thinking}`);
+    const base = scope.cwd;
+    if (base === undefined)
+        throw new Error("spawn requires a caller with a working directory");
+    const name = args.name === undefined ? undefined : normalizeRunName(args.name);
+    const cwd = resolve(base, args.cwd ?? ".");
+    if (!existsSync(cwd))
+        throw new Error(`Working directory not found: ${cwd}`);
+    const tools = args.tools?.map((tool) => tool.trim()).filter((tool) => tool);
+    if (tools !== undefined && tools.length === 0)
+        throw new Error("tools requires at least one tool name");
+    const files = (args.files ?? []).map((file) => resolve(base, file));
+    for (const file of files)
+        if (!existsSync(file))
+            throw new Error(`File not found: ${file}`);
+    const prompts = args.prompts ?? [];
+    if (prompts.length === 0 && files.length === 0)
+        throw new Error("spawn requires at least one prompt or file");
+    // The first message: the text of each file, as Pi gives a file argument to the model, then `Task:` and the prompts.
+    let prompt = files.map(fileText).join("");
+    if (prompts.length > 0)
+        prompt += `Task:\n${prompts.join("\n\n")}`;
+    let request = {
+        type: "spawn",
+        requestId,
+        caller: scope.caller,
+        provider,
+        model,
+        callerThinking: scope.thinking,
+        cwd,
+        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) {
+    if (statSync(file).size === 0)
+        return "";
+    return `<file name="${file}">\n${readFileSync(file, "utf8").replace(/^\uFEFF/, "")}\n</file>\n`;
+}
+function required(value, argument, action) {
+    if (value === undefined || value === "")
+        throw new Error(`${action} requires ${argument}`);
+    return value;
+}
+/** `value` without surrounding spaces. It must be a valid run name. */
+function normalizeRunName(value) {
+    const name = value.trim();
+    if (!isValidRunName(name))
+        throw new Error("Subagent name must be a single line of 1 to 64 characters");
+    return name;
+}
+function checkHandle(handle) {
+    if (!/^[a-z0-9]+$/.test(handle))
+        throw new Error(`Invalid subagent handle: ${handle}`);
+    return handle;
+}
+/**
+ * The pi-durable extension with the `subagent` tool. A call that runs again after a restart has the same task, so its
+ * spawn or send has the same request ID and does not repeat.
+ */
+export function subagentTool(durable, ai, scope) {
+    const { parameters, output } = toolSchemas(ai.Type);
+    const tool = durable.defineTool({
+        name: "subagent",
+        description: TOOL_DESCRIPTION,
+        parameters,
+        structuredOutputSchema: output,
+        replay: "safe",
+        executionMode: "sequential",
+        async execute(args, api, context) {
+            const agent = await api.agent(context);
+            const { text, data } = await runTool(args, {
+                caller: await scope.caller(api, context),
+                callKey: String(api.taskId),
+                provider: agent.model?.provider,
+                model: agent.model?.modelId,
+                thinking: agent.thinkingLevel,
+                cwd: agent.cwd,
+                send: scope.send,
+                signal: context.abortSignal,
+            });
+            return { output: [{ type: "text", text }], structuredOutput: data };
+        },
+    });
+    return durable.defineExtension({ name: "pi-subagent", tools: [tool] });
+}

package/dist/trust.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether Pi trusts the project in `cwd` with no one to ask: a directory without project resources is trusted, then a
+ * decision saved with `/trust` counts, then the `defaultProjectTrust` setting, where `ask` means not trusted.
+ */
+export declare function savedTrust(cwd: string): boolean;

package/dist/trust.js

@@ -0,0 +1,15 @@
+/** Pi's project trust, apart from the rest of the context, so that a Pi extension can read it without pi-durable. */
+import { getAgentDir, hasTrustRequiringProjectResources, ProjectTrustStore, SettingsManager, } from "@earendil-works/pi-coding-agent";
+/**
+ * Whether Pi trusts the project in `cwd` with no one to ask: a directory without project resources is trusted, then a
+ * decision saved with `/trust` counts, then the `defaultProjectTrust` setting, where `ask` means not trusted.
+ */
+export function savedTrust(cwd) {
+    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/dist/view-state.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 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: JsonRepresentation<UserMessage["content"]>): string;
+/** The queued steers and follow-ups, in inbox order. */
+export declare function queued(inbox: InboxState): {
+    mode: "steer" | "followUp";
+    text: string;
+}[];
+/** What the conversation does now, as Pi's working indicator says it; empty when it does nothing. */
+export declare function statusText(live: LiveState): string;