@vzlentin/harness 0.0.0-stage → 0.2.0

package/dist/durable-entry.d.ts

@@ -0,0 +1,13 @@
+import type * as Ai from "@earendil-works/pi-ai";
+import type * as Durable from "@earendil-works/pi-durable";
+/**
+ * The entry for a pi-durable host. The caller is `<store>:<conversation ID>`, where the store is a random ID that the store keeps,
+ * so conversations of two stores do not share children.
+ */
+export default function subagentEntry({ durable, ai }: {
+    readonly durable: typeof Durable;
+    readonly ai: typeof Ai;
+}): {
+    extensions: Durable.Extension<Durable.ToolRegistration<Ai.TSchema, import("@earendil-works/chord").JsonValue>>[];
+    close: () => Promise<void>;
+};

package/dist/durable-entry.js

@@ -0,0 +1,33 @@
+/**
+ * The `subagent` tool for hosts that run agents on pi-durable. The host passes its pi-durable and pi-ai modules, so
+ * this package loads no second copy of either.
+ */
+import { randomUUID } from "node:crypto";
+import { sendToHost, subagentTool } from "./tool.js";
+/**
+ * The entry for a pi-durable host. The caller is `<store>:<conversation ID>`, where the store is a random ID that the store keeps,
+ * so conversations of two stores do not share children.
+ */
+export default function subagentEntry({ durable, ai }) {
+    const Store = durable.defineDoc({
+        kind: "pi-subagent.store",
+        version: 1,
+        scope: "session",
+        initial: () => ({ id: "" }),
+    });
+    // The store ID never changes, so the first call reads it and the next calls reuse it.
+    let storeId;
+    const extension = subagentTool(durable, ai, {
+        caller: async (api, context) => {
+            storeId ??= await api.commit(async (tx) => {
+                const store = await tx.doc(Store);
+                if (store.id === "")
+                    store.id = randomUUID();
+                return store.id;
+            }, context);
+            return `${storeId}:${api.conversationId}`;
+        },
+        send: sendToHost,
+    });
+    return { extensions: [extension], close: async () => { } };
+}

package/dist/entries.d.ts

@@ -0,0 +1,9 @@
+/** The file of the entries: `$XDG_CONFIG_HOME/harness/entries.json`, default `~/.config/harness/entries.json`. */
+export declare function entriesPath(): string;
+/** The entries, name to absolute module path. It is empty when the file does not exist. */
+export declare function readEntries(): Record<string, string>;
+/**
+ * Sets the module of the entry `name` to the absolute path `module`. It is true when it changed the file: a host that
+ * runs already loads the new module only after it starts again.
+ */
+export declare function setEntry(name: string, module: string): boolean;

package/dist/entries.js

@@ -0,0 +1,50 @@
+/**
+ * The entries that the host loads, by name. A package such as workflows sets its entry before it starts a task, so the
+ * host does not depend on Pi's package settings.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+const Entries = Type.Record(Type.String(), Type.String());
+/** The file of the entries: `$XDG_CONFIG_HOME/harness/entries.json`, default `~/.config/harness/entries.json`. */
+export function entriesPath() {
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "harness", "entries.json");
+}
+/** The entries, name to absolute module path. It is empty when the file does not exist. */
+export function readEntries() {
+    const path = entriesPath();
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+    const entries = JSON.parse(text);
+    if (!Value.Check(Entries, entries) || !Object.values(entries).every((module) => isAbsolute(module))) {
+        throw new Error(`${path} is not an object of entry names to absolute module paths`);
+    }
+    return entries;
+}
+/**
+ * Sets the module of the entry `name` to the absolute path `module`. It is true when it changed the file: a host that
+ * runs already loads the new module only after it starts again.
+ */
+export function setEntry(name, module) {
+    if (!isAbsolute(module))
+        throw new Error(`An entry module must be an absolute path: ${module}`);
+    const entries = readEntries();
+    if (entries[name] === module)
+        return false;
+    const path = entriesPath();
+    mkdirSync(dirname(path), { recursive: true });
+    // A temporary file, then a rename, so a stop in between does not truncate the entries.
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify({ ...entries, [name]: module }, null, "\t")}\n`);
+    renameSync(temporary, path);
+    return true;
+}

package/dist/herdr.d.ts

@@ -0,0 +1,38 @@
+import { type ChildInfo } from "./protocol.ts";
+export type ViewerTarget = {
+    title(child: ChildInfo): string;
+    project: string[];
+    resume: string[];
+};
+export type AgentReporter = {
+    report(busy: boolean): void;
+    release(): Promise<void>;
+};
+/**
+ * How the viewer of `handle` on `project` shows and resumes it: the title of its child, the `--project` words, and the
+ * words after them that open it again. The project agent is `harness <project>`, with no `--project`; a child is
+ * `harness --project <project> attach <handle>`.
+ */
+export declare function viewerTarget(handle: string, project: string): ViewerTarget;
+/**
+ * The words of the command that runs the viewer of `handle`, with this Node and this package's CLI, so it does not
+ * need the CLI on PATH. Herdr wants a plain command name as the first word of a resume command, so it starts with
+ * `env`.
+ */
+export declare function viewerCommand(handle: string, project: string): string[];
+/**
+ * Runs `herdr` with `args` and gives its output. When `herdr` fails, it rejects with the stderr of `herdr`, or with the
+ * error of `execFile` when stderr is empty.
+ */
+export declare function herdr(args: readonly string[], env: NodeJS.ProcessEnv): Promise<string>;
+/**
+ * Opens a Herdr tab that runs the viewer of `child`, on the project of `env` and this process's cwd. It rejects when a
+ * `herdr` call fails or gives no pane ID.
+ */
+export declare function openViewerTab(child: ChildInfo, env: NodeJS.ProcessEnv): Promise<void>;
+/**
+ * Reports the state of the agent `label` to the Herdr pane of this process, with the viewer of `handle` on `project` as
+ * the resume command. Both methods do nothing outside Herdr.
+ * The calls run one after another, so `--seq` reaches Herdr in order.
+ */
+export declare function agentReporter(env: NodeJS.ProcessEnv, label: string, handle: string, project: string): AgentReporter;

package/dist/herdr.js

@@ -0,0 +1,111 @@
+import { execFile } from "node:child_process";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { resolveProject } from "./projects.js";
+import { AGENT_HANDLE, childLabel, cliPath, runDisplayName } from "./protocol.js";
+const HERDR_SOURCE = "custom:harness";
+/** The part of the output of `herdr tab create` that has the pane of the tab. */
+const TabCreated = Type.Object({ result: Type.Object({ root_pane: Type.Object({ pane_id: Type.String() }) }) });
+/**
+ * How the viewer of `handle` on `project` shows and resumes it: the title of its child, the `--project` words, and the
+ * words after them that open it again. The project agent is `harness <project>`, with no `--project`; a child is
+ * `harness --project <project> attach <handle>`.
+ */
+export function viewerTarget(handle, project) {
+    // The agent's name already says what it is; a child's shows its handle too.
+    if (handle === AGENT_HANDLE)
+        return { title: childLabel, project: [], resume: [project] };
+    return { title: runDisplayName, project: ["--project", project], resume: ["attach", handle] };
+}
+/**
+ * The words of the command that runs the viewer of `handle`, with this Node and this package's CLI, so it does not
+ * need the CLI on PATH. Herdr wants a plain command name as the first word of a resume command, so it starts with
+ * `env`.
+ */
+export function viewerCommand(handle, project) {
+    const cli = cliPath();
+    const target = viewerTarget(handle, project);
+    return ["env", process.execPath, cli, ...target.project, ...target.resume];
+}
+/**
+ * Runs `herdr` with `args` and gives its output. When `herdr` fails, it rejects with the stderr of `herdr`, or with the
+ * error of `execFile` when stderr is empty.
+ */
+export function herdr(args, env) {
+    return new Promise((resolve, reject) => {
+        execFile("herdr", args, { env }, (error, stdout, stderr) => {
+            if (error)
+                reject(new Error(stderr.trim() || error.message));
+            else
+                resolve(stdout);
+        });
+    });
+}
+/**
+ * Opens a Herdr tab that runs the viewer of `child`, on the project of `env` and this process's cwd. It rejects when a
+ * `herdr` call fails or gives no pane ID.
+ */
+export async function openViewerTab(child, env) {
+    const project = resolveProject(env, process.cwd());
+    // The tab must find the same host and projects as `statePaths()` in protocol.ts and `projectsPath()` in projects.ts.
+    const state = env.XDG_STATE_HOME;
+    const config = env.XDG_CONFIG_HOME;
+    const created = await herdr([
+        "tab",
+        "create",
+        "--cwd",
+        child.cwd,
+        "--label",
+        childLabel(child),
+        "--focus",
+        ...(state ? ["--env", `XDG_STATE_HOME=${state}`] : []),
+        ...(config ? ["--env", `XDG_CONFIG_HOME=${config}`] : []),
+    ], env);
+    let output;
+    try {
+        output = JSON.parse(created);
+    }
+    catch {
+        output = undefined;
+    }
+    if (!Value.Check(TabCreated, output))
+        throw new Error(`herdr tab create gave no pane ID: ${created.trim()}`);
+    const pane = output.result.root_pane.pane_id;
+    const viewer = viewerCommand(child.handle, project)
+        .map((word) => `'${word.replaceAll("'", "'\\''")}'`)
+        .join(" ");
+    await herdr(["pane", "run", pane, viewer], env);
+}
+/**
+ * Reports the state of the agent `label` to the Herdr pane of this process, with the viewer of `handle` on `project` as
+ * the resume command. Both methods do nothing outside Herdr.
+ * The calls run one after another, so `--seq` reaches Herdr in order.
+ */
+export function agentReporter(env, label, handle, project) {
+    const pane = env.HERDR_ENV ? env.HERDR_PANE_ID : undefined;
+    const resume = pane === undefined ? [] : ["--", ...viewerCommand(handle, project)];
+    let calls = Promise.resolve();
+    let seq = 0;
+    let reported;
+    const call = (command, options, resume) => {
+        if (pane === undefined)
+            return;
+        seq = Math.max(Date.now(), seq + 1);
+        const args = ["pane", command, "--source", HERDR_SOURCE, "--agent", label, ...options, "--seq", String(seq), pane];
+        // A failed report never stops the caller.
+        calls = calls.then(() => herdr([...args, ...resume], env)).catch(() => { });
+    };
+    return {
+        report(busy) {
+            const state = busy ? "working" : "idle";
+            if (state === reported)
+                return;
+            reported = state;
+            call("report-agent", ["--state", state], resume);
+        },
+        async release() {
+            call("release-agent", [], []);
+            await calls;
+        },
+    };
+}

package/dist/host.d.ts

@@ -0,0 +1,18 @@
+import { type Models } from "@earendil-works/pi-ai/models";
+export type Host = {
+    /** Resolves once the host has closed, by `close()`, the idle exit, or a store failure. */
+    readonly closed: Promise<void>;
+    close(): Promise<void>;
+};
+/**
+ * Runs the host of `project` in this process: the store in `stateDir`, the children's models from `models`, the
+ * project agent in `cwd`, and the socket. It is undefined when another host holds the lock.
+ */
+export declare function runHost(options: {
+    readonly stateDir: string;
+    readonly project: string;
+    readonly cwd: string;
+    readonly models: Models;
+    /** For tests: the idle time before the host exits. Default 5 minutes. */
+    readonly idleExitMs?: number;
+}): Promise<Host | undefined>;