@vzlentin/harness 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Observable, persistent subagents on [Pi](https://github.com/earendil-works/pi)'s libraries and
+[pi-durable](https://www.npmjs.com/package/@earendil-works/pi-durable). Each subagent is a conversation in a durable
+host process. You can spawn it, check its status, wait for its answer, steer it, and watch it live in a viewer.
+
+## Install
+
+You need Node.js 22.19 or later, and a login for a model provider in Pi's agent directory (`~/.pi/agent`): log in once
+with `/login` in `pi`, or set the API key of the provider, such as `ANTHROPIC_API_KEY`.
+
+```sh
+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:
+
+```sh
+pi install npm:@vzlentin/pi-subagent
+```
+
+You can add it now or later. Pi and the `harness` command use the same host.
+
+### Update and remove
+
+```sh
+npm update -g @vzlentin/harness
+pi update                                   # when you installed @vzlentin/pi-subagent
+npm uninstall -g @vzlentin/harness
+pi remove npm:@vzlentin/pi-subagent
+```
+
+## Use
+
+```sh
+harness spawn --name review --prompt "Review the current diff"
+harness list
+harness wait <handle>
+harness send <handle> "Focus on error handling"
+harness attach <handle>     # live viewer
+harness stop <handle>
+harness main                # talk to the agent of the main project
+```
+
+[docs/spec.md](docs/spec.md) describes all the commands, the tool, the viewer, projects, the host and its state.
+
+## Development
+
+```sh
+npm ci
+npm run check               # Biome, 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`.

package/dist/answer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Schema answers: the `respond` tool, its `answer_schema` section and its reminders, in the `harness-answer`
+ * extension. Its caller passes its pi-durable module, so a process never holds two copies.
+ */
+import { type JsonValue } from "@earendil-works/chord";
+import type * as Durable from "@earendil-works/pi-durable";
+import type { ConversationId, Extension, JsonObject, Tx } from "@earendil-works/pi-durable";
+/**
+ * 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.
+ */
+export declare const REMINDER = "Answer with the respond tool, as the schema in answer_schema says.";
+export type Answers = {
+    /**
+     * The extension with `respond`; the caller installs it and selects it for each conversation that can ask with a
+     * schema.
+     */
+    readonly extension: Extension;
+    /**
+     * Makes `requestId` the current ask of `id`, with `schema` or without one, and offers `respond` to the model only
+     * with a schema. Keeps the saved answers and the other entries of the stored `modelTools`.
+     */
+    prepare(tx: Tx, id: ConversationId, requestId: string, schema?: JsonObject): Promise<void>;
+    /** The answer that `respond` saved in the turn `requestId` of `id`, if any. */
+    valueIn(tx: Tx, id: ConversationId, requestId: string): Promise<JsonValue | undefined>;
+};
+export declare function createAnswers(durable: typeof Durable): Answers;
+/** True when an answer with `stopReason` reached its end; any other answer is cut. */
+export declare function complete(stopReason: string): boolean;

package/dist/answer.js

@@ -0,0 +1,171 @@
+/**
+ * Schema answers: the `respond` tool, its `answer_schema` section and its reminders, in the `harness-answer`
+ * extension. Its caller passes its pi-durable module, so a process never holds two copies.
+ */
+import { copyJson } from "@earendil-works/chord";
+import { Type, validateToolArguments } from "@earendil-works/pi-ai";
+/**
+ * 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.
+ */
+export const REMINDER = "Answer with the respond tool, as the schema in answer_schema says.";
+/** How many reminders one turn submission gets before its ask fails. */
+const MAX_REMINDERS = 2;
+export function createAnswers(durable) {
+    const AnswerDoc = durable.defineDoc({
+        kind: "harness.answer-schema",
+        version: 1,
+        scope: "conversation",
+        history: "latest",
+        fork: "current",
+        initial: () => ({ answers: {} }),
+    });
+    /** Saves a schema ask's answer, checked against the schema, and ends the turn. Only a schema ask offers it. */
+    const respond = durable.defineTool({
+        name: "respond",
+        description: "Give the answer of this turn in the structured form the prompt asks for. This ends the turn.",
+        parameters: Type.Object({
+            answer: Type.Unknown({
+                description: "The answer value itself, in the form the prompt asks for. Do not give its JSON text as a string.",
+            }),
+        }),
+        callers: ["model"],
+        deferred: true,
+        execute: async (args, api, context) => {
+            const doc = await api.snapshot(AnswerDoc, api.conversationId, context);
+            const requestId = doc?.requestId;
+            if (doc?.schema === undefined || requestId === undefined) {
+                return { isError: true, output: [{ type: "text", text: "This turn asks for no structured answer." }] };
+            }
+            let answer;
+            try {
+                answer = checkedAnswer(doc.schema, args, api.callId);
+            }
+            catch (error) {
+                return {
+                    isError: true,
+                    output: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+                };
+            }
+            await api.commit(async (tx) => {
+                (await tx.doc(AnswerDoc, api.conversationId)).answers[requestId] = answer;
+                return undefined;
+            }, context);
+            return { output: [{ type: "text", text: "Answer recorded." }], control: { terminate: true } };
+        },
+    });
+    /**
+     * Saves the number of reminders at the end of the request as the memo `reminders` of the generation, for a schema
+     * ask only. A continuation starts a new generation, so each generation counts the reminders of its turn again from
+     * its messages. A compaction in the turn can summarize reminders away and reset the count. Each reset needs a
+     * compaction, so the turn still ends.
+     */
+    const countReminders = async (request, api, context) => {
+        const doc = await api.snapshot(AnswerDoc, api.conversationId, context);
+        if (doc?.schema !== undefined)
+            await api.memo("reminders", remindersAtEnd(request.messages), context);
+        return undefined;
+    };
+    /** A reminder to call `respond`, when a schema ask got a complete answer without one and has reminders left. */
+    const remind = async (answer, api, context) => {
+        const doc = await api.snapshot(AnswerDoc, api.conversationId, context);
+        if (doc?.schema === undefined || doc.requestId === undefined)
+            return undefined;
+        if (Object.hasOwn(doc.answers, doc.requestId) || !complete(answer.stopReason))
+            return undefined;
+        const count = (await api.memo("reminders", context)) ?? 0;
+        return count < MAX_REMINDERS ? { continue: REMINDER } : undefined;
+    };
+    const extension = durable.defineExtension({
+        name: "harness-answer",
+        tools: [respond],
+        hooks: [durable.hook(durable.GenerationTask, { beforeRequest: countReminders, onYield: remind })],
+        sections: [
+            durable.section("answer_schema", async ({ read, conversationId }, context) => {
+                const schema = (await read.snapshot(AnswerDoc, conversationId, context))?.schema;
+                return schema && `The answer of respond must match this JSON Schema:\n${JSON.stringify(schema)}`;
+            }),
+        ],
+    });
+    return {
+        extension,
+        async prepare(tx, id, requestId, schema) {
+            const doc = await tx.doc(AnswerDoc, id);
+            if (schema === undefined)
+                delete doc.schema;
+            else
+                doc.schema = schema;
+            doc.requestId = requestId;
+            const agent = await tx.doc(durable.AgentDoc, id);
+            const name = respond.name;
+            const tools = agent.modelTools;
+            if (schema !== undefined) {
+                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] };
+                }
+                else if (!tools.includes(name))
+                    tools.push(name);
+            }
+            else if (Array.isArray(tools)) {
+                if (tools.includes(name))
+                    agent.modelTools = tools.filter((tool) => tool !== name);
+            }
+            else if (tools?.add?.includes(name)) {
+                agent.modelTools = { ...tools, add: tools.add.filter((tool) => tool !== name) };
+            }
+        },
+        async valueIn(tx, id, requestId) {
+            const { answers } = await tx.doc(AnswerDoc, id);
+            // A copy, because the draft is not readable after the commit.
+            return Object.hasOwn(answers, requestId) ? copyJson(answers[requestId]) : undefined;
+        },
+    };
+}
+/** True when an answer with `stopReason` reached its end; any other answer is cut. */
+export function complete(stopReason) {
+    return stopReason === "stop" || stopReason === "toolUse";
+}
+/** The number of reminders at the end of `messages`, counting back to the first other user message. */
+function remindersAtEnd(messages) {
+    let count = 0;
+    for (const message of messages.toReversed()) {
+        if (message.role !== "user")
+            continue;
+        const { content } = message;
+        const text = typeof content === "string"
+            ? content
+            : content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("");
+        if (text !== REMINDER)
+            break;
+        count++;
+    }
+    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.
+ */
+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;
+    try {
+        return check(args.answer);
+    }
+    catch (error) {
+        if (typeof args.answer !== "string")
+            throw error;
+        let parsed;
+        try {
+            parsed = JSON.parse(args.answer);
+        }
+        catch {
+            throw error;
+        }
+        if (typeof parsed !== "object" || parsed === null)
+            throw error;
+        return check(parsed);
+    }
+}

package/dist/chat.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A durable conversation drawn with Pi's own message and tool components.
+ *
+ * Adapted from `ChatView` in mavam/pi-agents, src/ui/attach.ts. MIT License, Copyright (c) 2026 Matthias Vallentin.
+ */
+import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import type { ConversationView } from "@earendil-works/pi-durable";
+import { Container, type TUI } from "@earendil-works/pi-tui";
+/**
+ * A tool result as Pi shows its own. pi-durable adds the diagnostics of a call for the model as a `<harness>` block, such
+ * as `Command exited with code 3`, and the card shows them as plain lines.
+ */
+export declare function displayedResult(result: ToolResultMessage): ToolResultMessage;
+/** The transcript of one conversation view, updated in place as the view changes. */
+export declare class ChatView {
+    readonly transcript: Container;
+    /** The newest card for each call ID: providers can use a call ID again in a later turn. */
+    private readonly tools;
+    /** Every card shown, also the older ones whose call ID a later turn used again. */
+    private readonly cards;
+    /** The cards that have no final result yet. */
+    private readonly running;
+    /** The call IDs whose cards the streamed answer made; its entry takes them over. */
+    private readonly streamingCalls;
+    private readonly renderers;
+    private renderedEntryIds;
+    private streaming;
+    /** Ctrl+O shows tool output in full, as in Pi. */
+    private expanded;
+    private readonly ui;
+    private readonly cwd;
+    constructor(ui: TUI, cwd: string);
+    apply(view: ConversationView): void;
+    /** Shows tool output in full, or collapses it again. */
+    toggleExpanded(): void;
+    /** Finishes the running cards: a running bash card keeps a timer until it gets a final result. */
+    stopTimers(): void;
+    private syncTranscript;
+    private rebuild;
+    private addEntry;
+    private syncStreaming;
+    private renderer;
+    /** The newest card of a call, or a new card when the call has none. */
+    private card;
+    /** A new card of a call, also for a call ID that an earlier turn used. */
+    private newCard;
+    private addText;
+}

package/dist/chat.js

@@ -0,0 +1,208 @@
+import { AssistantMessageComponent, createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, getMarkdownTheme, ToolExecutionComponent, UserMessageComponent, } from "@earendil-works/pi-coding-agent";
+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 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
+ * as `Command exited with code 3`, and the card shows them as plain lines.
+ */
+export function displayedResult(result) {
+    let changed = false;
+    const content = result.content.map((block) => {
+        const match = block.type === "text" ? DIAGNOSTICS.exec(block.text) : null;
+        if (!match)
+            return block;
+        changed = true;
+        const lines = (match[1] ?? "").split("\n").map((line) => line.replace(/^\[(error|warning|info)\] /, ""));
+        return { type: "text", text: `\n${lines.join("\n")}` };
+    });
+    return changed ? { ...result, content } : result;
+}
+/** The transcript of one conversation view, updated in place as the view changes. */
+export class ChatView {
+    transcript = new Container();
+    /** The newest card for each call ID: providers can use a call ID again in a later turn. */
+    tools = new Map();
+    /** Every card shown, also the older ones whose call ID a later turn used again. */
+    cards = [];
+    /** The cards that have no final result yet. */
+    running = new Set();
+    /** The call IDs whose cards the streamed answer made; its entry takes them over. */
+    streamingCalls = new Set();
+    renderers = new Map();
+    renderedEntryIds = [];
+    streaming;
+    /** Ctrl+O shows tool output in full, as in Pi. */
+    expanded = false;
+    ui;
+    cwd;
+    constructor(ui, cwd) {
+        this.ui = ui;
+        this.cwd = cwd;
+    }
+    apply(view) {
+        const live = liveOf(view);
+        this.syncTranscript(view.entries);
+        const message = live.generation?.message;
+        // A streamed answer without its entry was dropped, for example by a retry.
+        if (message === undefined && this.streaming !== undefined)
+            this.rebuild(view.entries);
+        if (message !== undefined)
+            this.syncStreaming(message);
+        for (const slot of live.tools ?? []) {
+            if (slot.status === "pending")
+                continue;
+            const component = this.card(slot.name, slot.callId);
+            component.setArgsComplete();
+            if (slot.status !== "running")
+                continue;
+            component.markExecutionStarted();
+            if (slot.output !== undefined || slot.details !== undefined) {
+                component.updateResult({ content: [{ type: "text", text: slot.output ?? "" }], details: slot.details, isError: false }, true);
+            }
+        }
+        this.transcript.invalidate();
+    }
+    /** Shows tool output in full, or collapses it again. */
+    toggleExpanded() {
+        this.expanded = !this.expanded;
+        for (const card of this.cards)
+            card.setExpanded(this.expanded);
+        this.transcript.invalidate();
+    }
+    /** Finishes the running cards: a running bash card keeps a timer until it gets a final result. */
+    stopTimers() {
+        for (const component of this.running)
+            component.updateResult({ content: [], isError: false }, false);
+        this.running.clear();
+    }
+    syncTranscript(entries) {
+        // A compaction or a reset replaces the head of the active transcript.
+        if (this.renderedEntryIds.some((id, index) => entries[index]?.id !== id))
+            this.rebuild(entries);
+        for (const entry of entries.slice(this.renderedEntryIds.length)) {
+            this.addEntry(entry);
+            this.renderedEntryIds.push(entry.id);
+        }
+    }
+    rebuild(entries) {
+        this.stopTimers();
+        this.transcript.clear();
+        this.cards.length = 0;
+        this.tools.clear();
+        this.streamingCalls.clear();
+        this.renderedEntryIds = [];
+        this.streaming = undefined;
+        for (const entry of entries) {
+            this.addEntry(entry);
+            this.renderedEntryIds.push(entry.id);
+        }
+    }
+    addEntry(entry) {
+        const message = entry.model?.[0];
+        if (entry.kind === "pi.user" && message?.role === "user") {
+            this.transcript.addChild(new Spacer(1));
+            this.transcript.addChild(new UserMessageComponent(userText(message.content), getMarkdownTheme()));
+        }
+        else if (entry.kind === "pi.assistant" && message?.role === "assistant") {
+            const component = this.streaming ?? new AssistantMessageComponent(undefined, false, getMarkdownTheme());
+            if (this.streaming === undefined)
+                this.transcript.addChild(component);
+            this.streaming = undefined;
+            component.updateContent(message, false);
+            // Only an answer that asks for tools runs its calls; an aborted, failed or cut answer never does.
+            const ran = message.stopReason === "toolUse";
+            for (const content of message.content) {
+                if (content.type !== "toolCall")
+                    continue;
+                const streamed = this.streamingCalls.has(content.id);
+                if (!ran && !streamed)
+                    continue;
+                const card = streamed
+                    ? this.card(content.name, content.id, content.arguments)
+                    : this.newCard(content.name, content.id, content.arguments);
+                card.setArgsComplete();
+                if (!ran) {
+                    const text = "Not run: the answer was interrupted.";
+                    card.updateResult({ content: [{ type: "text", text }], isError: true }, false);
+                    this.running.delete(card);
+                }
+            }
+            this.streamingCalls.clear();
+        }
+        else if (entry.kind === "pi.tool-result" && message?.role === "toolResult") {
+            const card = this.card(message.toolName, message.toolCallId);
+            card.updateResult(displayedResult(message));
+            this.running.delete(card);
+        }
+        else if (entry.kind === "pi.compaction") {
+            this.addText(color("muted", "[compaction]"));
+            if (message?.role === "user")
+                this.addText(userText(message.content));
+        }
+        else if (entry.kind === "pi.reset") {
+            this.addText(color("muted", "[new context]"));
+        }
+    }
+    syncStreaming(message) {
+        if (this.streaming === undefined) {
+            this.streaming = new AssistantMessageComponent(undefined, false, getMarkdownTheme());
+            this.transcript.addChild(this.streaming);
+        }
+        this.streaming.updateContent(message, true);
+        for (const content of message.content) {
+            if (content.type !== "toolCall")
+                continue;
+            if (this.streamingCalls.has(content.id))
+                this.card(content.name, content.id, content.arguments);
+            else
+                this.newCard(content.name, content.id, content.arguments);
+            this.streamingCalls.add(content.id);
+        }
+    }
+    renderer(toolName) {
+        let definition = this.renderers.get(toolName);
+        if (definition === undefined) {
+            const create = RENDERERS[toolName];
+            if (create === undefined)
+                return undefined;
+            definition = create(this.cwd);
+            this.renderers.set(toolName, definition);
+        }
+        return definition;
+    }
+    /** The newest card of a call, or a new card when the call has none. */
+    card(toolName, toolCallId, args) {
+        const existing = this.tools.get(toolCallId);
+        if (existing === undefined)
+            return this.newCard(toolName, toolCallId, args ?? {});
+        if (args !== undefined)
+            existing.updateArgs(args);
+        return existing;
+    }
+    /** A new card of a call, also for a call ID that an earlier turn used. */
+    newCard(toolName, toolCallId, args) {
+        const component = new ToolExecutionComponent(toolName, toolCallId, args, {}, this.renderer(toolName), this.ui, this.cwd);
+        component.setExpanded(this.expanded);
+        this.transcript.addChild(component);
+        this.cards.push(component);
+        this.running.add(component);
+        this.tools.set(toolCallId, component);
+        return component;
+    }
+    addText(text) {
+        this.transcript.addChild(new Spacer(1));
+        this.transcript.addChild(new Text(text, 1, 0));
+    }
+}