@vzlentin/harness 0.0.0-stage → 0.1.0

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. `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,209 @@
+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. \`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")}`;
+    return {
+        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,
+    };
+}
+/** 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,16 @@
+/**
+ * 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 { UserMessage } from "@earendil-works/pi-ai";
+import { type ConversationView, type InboxState, type LiveState } from "@earendil-works/pi-durable";
+export declare function liveOf(view: ConversationView): LiveState;
+export declare function inboxOf(view: ConversationView): InboxState;
+export declare function userText(content: 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;

package/dist/view-state.js

@@ -0,0 +1,39 @@
+import { InboxDoc, LiveDoc } from "@earendil-works/pi-durable";
+export function liveOf(view) {
+    return view.docs[LiveDoc.definition.kind] ?? {};
+}
+export function inboxOf(view) {
+    return view.docs[InboxDoc.definition.kind] ?? { items: [] };
+}
+export function userText(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("");
+}
+/** The queued steers and follow-ups, in inbox order. */
+export function queued(inbox) {
+    return inbox.items.flatMap((item) => item.mode === "write" ? [] : [{ mode: item.mode, text: userText(item.content) }]);
+}
+/** What the conversation does now, as Pi's working indicator says it; empty when it does nothing. */
+export function statusText(live) {
+    const generation = live.generation;
+    const compaction = live.compactions?.[0];
+    const runningTool = live.tools?.find((slot) => slot.status === "running");
+    if (generation?.retry !== undefined)
+        return `Retrying (attempt ${generation.attempt + 1}): ${generation.retry.error}`;
+    if (generation?.deferred !== undefined)
+        return "Waiting for deferred response...";
+    if (compaction !== undefined) {
+        return compaction.retry
+            ? `Retrying ${compaction.reason} compaction (attempt ${compaction.attempt + 1})...`
+            : `Compacting (${compaction.reason})...`;
+    }
+    if (runningTool !== undefined)
+        return `Running ${runningTool.name}... (esc to interrupt)`;
+    if (live.run !== undefined)
+        return "Working... (esc to interrupt)";
+    return "";
+}

package/dist/viewer.d.ts

@@ -0,0 +1,20 @@
+import { type Terminal } from "@earendil-works/pi-tui";
+declare module "@earendil-works/pi-tui" {
+    interface Keybindings {
+        "app.scroll.lineUp": true;
+        "app.scroll.lineDown": true;
+        "app.scroll.pageUp": true;
+        "app.scroll.pageDown": true;
+    }
+}
+export type AttachOptions = {
+    readonly terminal: Terminal;
+    readonly env: NodeJS.ProcessEnv;
+};
+/**
+ * Shows the conversation of the child `handle`, or of the project agent for `agent`, in `terminal` and sends
+ * what the user types to it. It starts the host when none runs, and rejects before the terminal starts when the handle
+ * is unknown. It resolves with the exit code: 0 after Ctrl+C or when the child is stopped, 1 when the host closes the
+ * connection. The child keeps running.
+ */
+export declare function attach(handle: string, options: AttachOptions): Promise<number>;