@vzlentin/harness 0.2.3 → 0.3.1

package/dist/targets.d.ts

@@ -0,0 +1,67 @@
+import * as durable from "@earendil-works/pi-durable";
+import { type Conversation, type ConversationId, type Harness } from "@earendil-works/pi-durable";
+import { type Child, type Input, type Owner, type Place } from "./children.ts";
+import { type ChildInfo, type Target } from "./protocol.ts";
+/** What the targets use of the host. */
+export type TargetHost = {
+    readonly harness: Harness;
+    /** The host's store, models and tools, for the children library. */
+    readonly place: Place;
+    readonly owner: Owner;
+    readonly project: string;
+    /** The project agent: the root conversation, with a model and the project directory from its first use. */
+    readonly agent: () => Promise<Conversation>;
+};
+export type ChildRecord = {
+    name?: string;
+    /** `PI_SESSION_ID` of the spawner: a Pi session, the conversation ID of another child, or `cli`. */
+    caller: string;
+    createdAt: string;
+    conversationId: ConversationId;
+    /** The request IDs of the spawn and of each `send` of the caller, in order. */
+    sent?: string[];
+    /** How many requests of `sent` a `wait` gave the answer of. */
+    read?: number;
+};
+export type ChildrenState = {
+    children: Record<string, ChildRecord>;
+    requests: Record<string, string>;
+};
+/**
+ * The children by handle, and the handle of each spawn request ID. Version 2 leaves each child's last request to the
+ * children library; a store with version 1 has children that the library does not know.
+ */
+export declare const Children: durable.SessionDocToken<ChildrenState>;
+/** The children library, on this process's pi-durable. */
+export declare const library: import("./children.ts").Children;
+/**
+ * The conversation of `ref`: a child or the project agent by handle, or a conversation of the children library by ID,
+ * with its info, its input, and the record of a child.
+ */
+export declare function target(handler: TargetHost, ref: Target): Promise<{
+    conversation: Conversation;
+    info: () => Promise<ChildInfo>;
+    send: (input: Input) => Promise<void>;
+    record: undefined;
+} | {
+    conversation: Conversation;
+    info: () => Promise<ChildInfo>;
+    send: (input: Input) => Promise<void>;
+    record: ChildRecord;
+}>;
+export type Found = Awaited<ReturnType<typeof target>>;
+/** The target of the child `handle`, whose record is `record`. */
+export declare function childTarget(handler: TargetHost, handle: string, record: ChildRecord): Promise<{
+    conversation: Conversation;
+    info: () => Promise<ChildInfo>;
+    send: (input: Input) => Promise<void>;
+    record: ChildRecord;
+}>;
+export declare function childRecord(harness: Harness, handle: string): Promise<ChildRecord>;
+/** The record of `handle`, which must belong to `caller`. */
+export declare function ownRecord(harness: Harness, handle: string, caller: string): Promise<ChildRecord>;
+export declare function childOf(handler: Pick<TargetHost, "place" | "owner">, record: ChildRecord): Promise<Child>;
+/** The info of `handle`. A caller that already has the record gives it as `record`. */
+export declare function childInfo(handler: Pick<TargetHost, "harness" | "place" | "owner">, handle: string, record?: ChildRecord): Promise<ChildInfo>;
+/** The record of `handle` in the `Children` value `state`. */
+export declare function recordOf(state: Readonly<ChildrenState> | null | undefined, handle: string): ChildRecord | undefined;

package/dist/targets.js

@@ -0,0 +1,140 @@
+/**
+ * The targets of the host's requests: the children by handle, the project agent, and the conversations of the children
+ * library by ID, with the `Children` records of the host.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import * as durable from "@earendil-works/pi-durable";
+import { defineDoc } from "@earendil-works/pi-durable";
+import { createChildren } from "./children.js";
+import { AGENT_HANDLE } from "./protocol.js";
+const context = BACKGROUND_CONTEXT;
+/**
+ * The children by handle, and the handle of each spawn request ID. Version 2 leaves each child's last request to the
+ * children library; a store with version 1 has children that the library does not know.
+ */
+export const Children = defineDoc({
+    kind: "subagent.children",
+    version: 2,
+    scope: "session",
+    initial: () => ({ children: {}, requests: {} }),
+});
+/** The request ID of the project agent's newest input, which its `error` state comes from. */
+const AgentState = defineDoc({
+    kind: "harness.agent",
+    version: 1,
+    scope: "conversation",
+    history: "latest",
+    fork: "initial",
+    initial: () => ({ lastRequest: null }),
+});
+/** The children library, on this process's pi-durable. */
+export const library = createChildren(durable);
+/**
+ * The conversation of `ref`: a child or the project agent by handle, or a conversation of the children library by ID,
+ * with its info, its input, and the record of a child.
+ */
+export async function target(handler, ref) {
+    if (ref.conversation !== undefined)
+        return conversationTarget(handler, ref.conversation);
+    const { handle } = ref;
+    if (handle !== AGENT_HANDLE)
+        return childTarget(handler, handle, await childRecord(handler.harness, handle));
+    const root = await handler.agent();
+    const { harness, place, project } = handler;
+    const turn = library.turn(place, root.id, root, async (readContext) => (await harness.snapshot(AgentState, root.id, readContext))?.lastRequest, async (tx, requestId) => {
+        (await tx.doc(AgentState, root.id)).lastRequest = requestId;
+    });
+    return {
+        conversation: root,
+        info: async () => ({
+            ...(await agentFields(root)),
+            handle,
+            name: `${project} agent`,
+            state: await turn.state(context),
+        }),
+        send: (input) => turn.send(input, context),
+        record: undefined,
+    };
+}
+/**
+ * The target of the library conversation `id`, of any owner, such as a child of a task. It has no record, and it takes
+ * input only while it works.
+ */
+async function conversationTarget(handler, id) {
+    const child = await library.inspect(handler.place, id, context);
+    if (child === undefined)
+        throw new Error(`Unknown conversation: ${id}`);
+    const { conversation, lineage } = child;
+    const info = async () => {
+        const childState = await child.state(context);
+        const state = childState === "closed" ? "idle" : childState;
+        return { handle: id, conversation: id, name: lineage.key, state, ...(await agentFields(conversation)) };
+    };
+    return {
+        conversation,
+        info,
+        send: async (input) => {
+            if ((await child.state(context)) !== "busy")
+                throw new Error(`${lineage.key} takes input only while it works`);
+            // Small race: a turn that ends between the check and the submit starts a new turn; needs busy-only admission in
+            // pi-durable.
+            await conversation.submit({ ...input, whenBusy: "steer" }, context);
+        },
+        record: undefined,
+    };
+}
+/** The target of the child `handle`, whose record is `record`. */
+export async function childTarget(handler, handle, record) {
+    const child = await childOf(handler, record);
+    return {
+        conversation: child.conversation,
+        info: () => childInfo(handler, handle, record),
+        send: (input) => child.send(input, context),
+        record,
+    };
+}
+export async function childRecord(harness, handle) {
+    const state = await harness.snapshot(Children, context);
+    const record = recordOf(state, handle);
+    if (record === undefined)
+        throw new Error(`Unknown subagent: ${handle}`);
+    return record;
+}
+/** The record of `handle`, which must belong to `caller`. */
+export async function ownRecord(harness, handle, caller) {
+    const record = await childRecord(harness, handle);
+    if (record.caller !== caller)
+        throw new Error(`Subagent ${handle} belongs to another session`);
+    return record;
+}
+export async function childOf(handler, record) {
+    const child = await library.find(handler.place, handler.owner, { id: String(record.conversationId) }, context);
+    if (child === undefined)
+        throw new Error(`Missing conversation ${record.conversationId}`);
+    return child;
+}
+/** The info of `handle`. A caller that already has the record gives it as `record`. */
+export async function childInfo(handler, handle, record) {
+    record ??= await childRecord(handler.harness, handle);
+    const child = await childOf(handler, record);
+    const childState = await child.state(context);
+    // A closed child is idle: the watch can still send it before its record goes and the `stopped` line follows.
+    const state = childState === "closed" ? "idle" : childState;
+    const fields = await agentFields(child.conversation);
+    return record.name === undefined ? { handle, state, ...fields } : { handle, name: record.name, state, ...fields };
+}
+/** The model, thinking level and directory of the agent of `conversation`, for its info. */
+async function agentFields(conversation) {
+    const agent = await conversation.agent(context);
+    return {
+        provider: agent.model?.provider ?? "",
+        model: agent.model?.modelId ?? "",
+        thinking: agent.thinkingLevel,
+        // `spawnChild` refuses a spawn without `cwd`; the fallback only satisfies pi-durable's optional type.
+        cwd: agent.cwd ?? "",
+    };
+}
+/** The record of `handle` in the `Children` value `state`. */
+export function recordOf(state, handle) {
+    return state != null && Object.hasOwn(state.children, handle) ? state.children[handle] : undefined;
+}

package/dist/tool.js

@@ -30,7 +30,7 @@ export function toolSchemas(Type) {
         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"),
+        tools: texts("spawn: the only tools the child gets; default read, grep, find, ls, write, edit, bash, codemode 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"),

package/dist/view-change.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The change of a watched conversation view that a watch line carries, and its two ends: the host makes it from the
+ * chord ops of a commit, and a client applies it, so the client needs no chord. It imports only types, so the Pi
+ * extension can load it.
+ *
+ * The entries of a change are the entries from one index to the end. This is correct because no op moves the entries
+ * before the index where it starts: a splice starts at its index, a change in an entry at that entry, and a reorder or
+ * a new array at the first entry.
+ */
+import type { Op } from "@earendil-works/chord/delta";
+import type { ConversationRecord, ConversationView, EntryRecord, JsonObject } from "@earendil-works/pi-durable";
+/**
+ * The parts of a watched view that changed, as whole values: the entries from index `from` on, the documents that
+ * changed by kind (`null` for a removed document), and the conversation record. A part that did not change is absent.
+ */
+export type ViewParts = {
+    readonly entries?: {
+        readonly from: number;
+        readonly items: readonly EntryRecord[];
+    };
+    readonly docs?: Readonly<Record<string, JsonObject | null>>;
+    readonly conversation?: ConversationRecord;
+};
+/**
+ * What one commit changed in a watched view, so a client keeps the view without chord: some parts, or the whole view,
+ * as after a watch that fell behind.
+ */
+export type ViewChange = ViewParts | {
+    readonly view: ConversationView;
+};
+/**
+ * What `ops` changed in a watched view, as whole values of `view`, the view after them: the entries from the first one
+ * that an op reached, each document that an op reached, and the conversation record. An op on the root, or on a part
+ * that this does not know, gives the whole view.
+ */
+export declare function viewChange(view: ConversationView, ops: readonly Op[]): ViewChange;
+/** `view` after `change`. A client of a watch keeps its view up to date with it. */
+export declare function applyChange(view: ConversationView, change: ViewChange): ConversationView;

package/dist/view-change.js

@@ -0,0 +1,55 @@
+/**
+ * What `ops` changed in a watched view, as whole values of `view`, the view after them: the entries from the first one
+ * that an op reached, each document that an op reached, and the conversation record. An op on the root, or on a part
+ * that this does not know, gives the whole view.
+ */
+export function viewChange(view, ops) {
+    let from;
+    const kinds = new Set();
+    let conversation = false;
+    for (const op of ops) {
+        if (op[0] === "r")
+            return { view };
+        const [part, next] = op[1];
+        if (part === "entries") {
+            const index = next !== undefined ? Number(next) : op[0] === "p" ? op[2] : 0;
+            from = Math.min(from ?? index, index);
+        }
+        else if (part === "docs" && next !== undefined) {
+            kinds.add(String(next));
+        }
+        else if (part === "conversation") {
+            conversation = true;
+        }
+        else {
+            return { view };
+        }
+    }
+    const parts = {};
+    if (from !== undefined)
+        parts.entries = { from, items: view.entries.slice(from) };
+    if (kinds.size > 0) {
+        parts.docs = Object.fromEntries([...kinds].map((kind) => [kind, view.docs[kind] ?? null]));
+    }
+    if (conversation)
+        parts.conversation = view.conversation;
+    return parts;
+}
+/** `view` after `change`. A client of a watch keeps its view up to date with it. */
+export function applyChange(view, change) {
+    if ("view" in change)
+        return change.view;
+    const { entries, docs = {}, conversation } = change;
+    const changedDocs = { ...view.docs };
+    for (const [kind, doc] of Object.entries(docs)) {
+        if (doc === null)
+            delete changedDocs[kind];
+        else
+            changedDocs[kind] = doc;
+    }
+    return {
+        conversation: conversation ?? view.conversation,
+        entries: entries === undefined ? view.entries : [...view.entries.slice(0, entries.from), ...entries.items],
+        docs: changedDocs,
+    };
+}

package/dist/view-state.d.ts

@@ -1,19 +1,35 @@
 /**
- * What the viewer reads from the documents of a durable conversation view: its live state, its inbox and the texts of
- * its user messages.
+ * What the Pi extension reads from a durable conversation view: its live state, its inbox, its usage and
+ * the texts of its user messages. It imports only types, so the Pi extension can load it.
  */
 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;
+import type { Usage, UserMessage } from "@earendil-works/pi-ai";
+import type { ConversationView, InboxState, LiveState, UsageState } from "@earendil-works/pi-durable";
 export declare function liveOf(view: ConversationView): LiveState;
 export declare function inboxOf(view: ConversationView): InboxState;
+export declare function usageOf(view: ConversationView): UsageState | undefined;
+/** The tokens and the cost of a conversation. */
+export type UsageTotals = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+};
+/** The sums of the usage of the model requests and of the tool results of the conversation, as Pi's footer counts. */
+export declare function usageTotals(view: ConversationView): UsageTotals;
+/**
+ * The usage of the last answer of the active transcript, which tells how full the context is. An aborted answer and an
+ * answer that failed do not count.
+ */
+export declare function lastAnswerUsage(view: ConversationView): Usage | undefined;
 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;
 }[];
+/** The texts of the queued messages that an abort withdraws, steers first, as they go back to the editor. */
+export declare function withdrawnTexts(inbox: InboxState): 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

@@ -1,14 +1,44 @@
-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];
+/** The built-in document of the kind `kind` in `view`, if the conversation has it. */
+function docOf(view, kind) {
+    // SAFETY: pi-durable keeps each built-in conversation document in `docs` under its kind: `pi.live` holds a
+    // `LiveState`, `pi.inbox` an `InboxState` and `pi.usage` a `UsageState`. Each caller passes the kind of its type.
+    return view.docs[kind];
 }
 export function liveOf(view) {
-    return docOf(view, LiveDoc) ?? {};
+    return docOf(view, "pi.live") ?? {};
 }
 export function inboxOf(view) {
-    return docOf(view, InboxDoc) ?? { items: [] };
+    return docOf(view, "pi.inbox") ?? { items: [] };
+}
+export function usageOf(view) {
+    return docOf(view, "pi.usage");
+}
+/** The sums of the usage of the model requests and of the tool results of the conversation, as Pi's footer counts. */
+export function usageTotals(view) {
+    const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+    const usage = usageOf(view);
+    for (const item of [...Object.values(usage?.models ?? {}), ...Object.values(usage?.tools ?? {})]) {
+        totals.input += item.input;
+        totals.output += item.output;
+        totals.cacheRead += item.cacheRead;
+        totals.cacheWrite += item.cacheWrite;
+        totals.cost += item.cost.total;
+    }
+    return totals;
+}
+/**
+ * The usage of the last answer of the active transcript, which tells how full the context is. An aborted answer and an
+ * answer that failed do not count.
+ */
+export function lastAnswerUsage(view) {
+    for (const entry of view.entries.toReversed()) {
+        const message = entry.model?.[0];
+        if (entry.kind !== "pi.assistant" || message?.role !== "assistant")
+            continue;
+        if (message.stopReason !== "aborted" && message.stopReason !== "error")
+            return message.usage;
+    }
+    return undefined;
 }
 export function userText(content) {
     if (!Array.isArray(content))
@@ -22,6 +52,14 @@ export function userText(content) {
 export function queued(inbox) {
     return inbox.items.flatMap((item) => item.mode === "write" ? [] : [{ mode: item.mode, text: userText(item.content) }]);
 }
+/** The texts of the queued messages that an abort withdraws, steers first, as they go back to the editor. */
+export function withdrawnTexts(inbox) {
+    const inputs = queued(inbox);
+    return [
+        ...inputs.filter((input) => input.mode === "steer"),
+        ...inputs.filter((input) => input.mode === "followUp"),
+    ].map((input) => input.text);
+}
 /** 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;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vzlentin/harness",
-	"version": "0.2.3",
+	"version": "0.3.1",
 	"description": "A durable agent harness on Pi, starting with observable, persistent subagents",
 	"repository": {
 		"type": "git",
@@ -35,6 +35,7 @@
 	"dependencies": {
 		"@earendil-works/chord": "1.3.0",
 		"@earendil-works/pi-ai": "1.3.0",
+		"@earendil-works/pi-codemode": "1.3.0",
 		"@earendil-works/pi-coding-agent": "1.3.0",
 		"@earendil-works/pi-durable": "1.3.0",
 		"@earendil-works/pi-tui": "1.3.0",