@vzlentin/harness 0.2.3 → 0.3.1

package/dist/host.js

@@ -1,62 +1,34 @@
-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;
-};
 import { randomBytes } from "node:crypto";
 import { once } from "node:events";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { mkdirSync, rmSync } from "node:fs";
 import { createServer } from "node:net";
-import { join, resolve as resolvePath, sep } from "node:path";
+import { join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
-import { pathToFileURL } from "node:url";
 import { BACKGROUND_CONTEXT, withAbortSignal } from "@earendil-works/chord/context";
 import * as ai from "@earendil-works/pi-ai";
-import { getSupportedThinkingLevels } from "@earendil-works/pi-ai/models";
-import { createEventBus, DefaultPackageManager, getAgentDir, ProjectTrustStore, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { CodemodeSandbox } from "@earendil-works/pi-codemode";
+import { getAgentDir, ProjectTrustStore, SettingsManager } from "@earendil-works/pi-coding-agent";
 import * as durable from "@earendil-works/pi-durable";
-import { AgentDoc, createRegistry, defineDoc, Harness, } from "@earendil-works/pi-durable";
+import { AgentDoc, createRegistry, Harness, } from "@earendil-works/pi-durable";
+import { createCodemodeExtension } from "@earendil-works/pi-durable/codemode";
 import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
 import { openNodeSqliteStorage } from "@earendil-works/pi-durable/storage/sqlite/node";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
-import { createChildren, resolveModel, } from "./children.js";
+import { resolveModel } from "./children.js";
 import { ChildContext } from "./context.js";
-import { readEntries } from "./entries.js";
-import { AGENT_HANDLE, onLines, PROTOCOL_VERSION, RequestLine, } from "./protocol.js";
+import { loadEntries } from "./load-entries.js";
+import { errorMessage, onLines, PROTOCOL_VERSION, RequestLine, } from "./protocol.js";
+import { Children, childInfo, childOf, childRecord, childTarget, library, ownRecord, recordOf, target, } from "./targets.js";
 import { abortTask, startableTasks, startTask, taskInfo, waitTask } from "./tasks.js";
 import { subagentTool } from "./tool.js";
+import { viewChange } from "./view-change.js";
 /** The host exits after this long with no connection, no live task and no request. */
 const IDLE_EXIT_MS = 5 * 60_000;
 const IDLE_CHECK_MS = 60_000;
 const context = BACKGROUND_CONTEXT;
 /** The `detail` of a failed turn that is an error object. */
 const ErrorDetail = Type.Object({ message: Type.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.
- */
-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. */
-const library = createChildren(durable);
 /**
  * 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.
@@ -74,7 +46,7 @@ export async function runHost(options) {
     const settings = SettingsManager.create(stateDir, agentDir, {
         projectTrusted: new ProjectTrustStore(agentDir).get(stateDir) === true,
     });
-    const warn = (cause) => process.stderr.write(`warning: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+    const warn = (cause) => process.stderr.write(`warning: ${errorMessage(cause)}\n`);
     // The store is there once the harness is open; entries get `place` before, and use the store in their tasks.
     let harness;
     const place = {
@@ -88,7 +60,7 @@ export async function runHost(options) {
             return registry.snapshot();
         },
     };
-    const entries = await loadEntries(stateDir, agentDir, settings, place, warn).catch((cause) => {
+    const entries = await loadEntries(stateDir, agentDir, settings, place, library, warn).catch((cause) => {
         lock.close();
         throw cause;
     });
@@ -107,7 +79,9 @@ export async function runHost(options) {
         caller: async (api) => String(api.conversationId),
         send: (request, signal) => handleRequest(request, { ...base, signal }),
     });
-    const selected = [ChildContext, tool, ...entries.extensions];
+    // Each script runs in a worker thread, in a VM of at most 256 MB, as in Pi.
+    const sandbox = new CodemodeSandbox({ memoryLimitBytes: 256 * 1024 * 1024 });
+    const selected = [ChildContext, tool, createCodemodeExtension({ sandbox }), ...entries.extensions];
     try {
         for (const extension of selected)
             registry.install(extension);
@@ -148,7 +122,7 @@ export async function runHost(options) {
         }
         catch (error) {
             await harness.close(context);
-            const message = error instanceof Error ? error.message : String(error);
+            const message = errorMessage(error);
             if (!message.includes("(subagent.children) requires migration from version"))
                 throw error;
             throw new Error(`${join(stateDir, "durable.sqlite")} was written by an older pi-subagent (${message}). Stop the host, remove the file and run the command again.`);
@@ -188,7 +162,7 @@ export async function runHost(options) {
                     };
                 }
                 catch (error) {
-                    reply = { ok: false, error: error instanceof Error ? error.message : String(error) };
+                    reply = { ok: false, error: errorMessage(error) };
                 }
                 if (socket.writable)
                     socket.write(`${JSON.stringify(reply)}\n`);
@@ -210,6 +184,7 @@ export async function runHost(options) {
         });
     }).catch(async (cause) => {
         await entries.close();
+        await sandbox.close();
         await harness.close(context);
         lock.close();
         throw cause;
@@ -224,8 +199,10 @@ export async function runHost(options) {
             for (const abort of aborts)
                 abort.abort();
             try {
-                // Entries close first: an entry may still need the open harness.
+                // Entries close first: an entry may still need the open harness. The sandbox closes before the harness, so a
+                // script that runs gets no outcome and continues after a restart.
                 await entries.close();
+                await sandbox.close();
                 await harness.close(context);
                 for (const env of envs.values())
                     await env.cleanup(context);
@@ -270,7 +247,8 @@ async function handleRequest(request, handler) {
             }
         }
         case "input":
-            return sendTo(request, await target(handler, request.handle));
+            // A conversation takes input only while it works, so its input is always a steer.
+            return sendTo(request.conversation === undefined ? request : { ...request, followUp: false }, await target(handler, request));
         case "wait":
             return waitChild(request, handler);
         case "status":
@@ -279,12 +257,10 @@ async function handleRequest(request, handler) {
             return abortChild(request, handler);
         case "configure":
             return configureChild(request, handler);
-        case "models":
-            return modelInfos(handler.place.models);
         case "watch":
             if (handler.connection === undefined)
                 throw new Error("A watch needs a connection");
-            return serveWatch(handler, request.handle, handler.connection);
+            return serveWatch(handler, request, handler.connection);
         case "start":
             // A child that a task opens without a model takes the project agent's, so the agent is set up first. Without
             // a model for the agent, the task still starts: its children may name their own.
@@ -452,7 +428,7 @@ async function waitChild(request, handler) {
 /**
  * The requests of `sent` from `read` on that a wait for `main` gives before the answer to `main`, and the new `read`.
  * When `main` is a request of the caller, they are the ones before it, and `main` counts as read; a send after it
- * stays unread. Otherwise, such as for viewer input, they are the caller's requests known when the wait started.
+ * stays unread. Otherwise, such as for the input of a mirror session, they are the caller's requests known when the wait started.
  */
 function unreadBefore(sent, read, main, atStart) {
     const index = main === null ? -1 : sent.indexOf(main);
@@ -488,79 +464,18 @@ async function markSent(harness, handle, requestId, add) {
     }, context);
 }
 async function abortChild(request, handler) {
-    const found = await target(handler, request.handle);
+    const found = await target(handler, request);
     // Without `background`, an abort of the project agent does not reach the anchors of the children, which keep running.
     await found.conversation.abort(context);
     return found.info();
 }
 async function configureChild(request, handler) {
-    const found = await target(handler, request.handle);
+    // Only the handle: the schema of `configure` does not refuse an extra `conversation` key.
+    const found = await target(handler, { handle: request.handle });
     const agent = await found.conversation.agent(context);
     await found.conversation.configure(resolveModel(handler.place.models, agent, request), context);
     return found.info();
 }
-/**
- * The conversation of `handle`, a child or the project agent, with its info, its input, and the record of a child.
- */
-async function target(handler, handle) {
-    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 child `handle`, whose record is `record`. */
-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,
-    };
-}
-async function modelInfos(models) {
-    return (await models.getAvailable()).map((model) => ({
-        provider: model.provider,
-        id: model.id,
-        name: model.name,
-        contextWindow: model.contextWindow,
-        thinkingLevels: getSupportedThinkingLevels(model),
-    }));
-}
-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`. */
-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;
-}
-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;
-}
 function failureText(handle, reason, detail) {
     if (reason === "aborted")
         return `${handle} was aborted`;
@@ -571,27 +486,6 @@ function failureText(handle, reason, detail) {
             : undefined;
     return text === undefined ? `${handle} failed: ${reason}` : `${handle} failed: ${text}`;
 }
-/** The info of `handle`. A caller that already has the record gives it as `record`. */
-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 root conversation as the agent of `project`. The first time, it gets Pi's default model when it has a login, else
  * the first model with a login, Pi's default thinking level, and the directory `cwd`. Without a model with a login, it
@@ -619,13 +513,14 @@ async function setUpAgent(root, models, settings, project, cwd) {
 }
 /**
  * Opens a watch of `handle` on `connection` and returns the reply, with the view and the child. After the reply, each
- * commit to the child's conversation and each rename gives one `{ event: WatchLine }` line. It waits for a slow socket
- * to drain, so pi-durable replaces the frames it holds back with one frame of the whole view. The watches stop when the
- * socket closes, when setup fails, or when the connection ends; a wait for `drain` then stays on the closed socket and
- * goes with it. When the child stops, the viewer gets a `stopped` event and the connection ends; when the conversation
+ * commit to the child's conversation gives one `{ event: WatchLine }` line with its change, and each rename one with
+ * an empty change. It waits for a slow socket to drain, so pi-durable replaces the frames it holds back with one frame
+ * of the whole view. The watches stop when the socket closes, when setup fails, or when the connection ends; a wait for
+ * `drain` then stays on the closed socket and goes with it. When the child stops, the client gets a `stopped` event and the connection ends; when the conversation
  * watch ends for another reason, the connection ends.
  */
-async function serveWatch(handler, handle, connection) {
+async function serveWatch(handler, ref, connection) {
+    const handle = ref.conversation ?? ref.handle;
     const { harness } = handler;
     const { socket } = connection;
     const write = (event) => socket.write(`${JSON.stringify({ event })}\n`);
@@ -642,8 +537,9 @@ async function serveWatch(handler, handle, connection) {
     let conversation;
     let last;
     try {
-        found = await target(handler, handle);
-        // The project agent has no record, and no `Children` watch: it is never renamed or stopped.
+        found = await target(handler, ref);
+        // The project agent and a conversation target have no record and no `Children` watch: they are never renamed
+        // or stopped.
         if (found.record !== undefined) {
             // The `Children` watch opens before the info, so it gets each later rename and stop of the child.
             children = await harness.watchDoc(Children, watchContext);
@@ -668,14 +564,14 @@ async function serveWatch(handler, handle, connection) {
         // pi-durable runs the callbacks of one watch in order, but not those of two watches. Both watches write through
         // this one chain, so a line never has older info than the line before it.
         let queue = Promise.resolve();
-        const send = (ops) => {
+        const send = (change) => {
             queue = queue.then(async () => {
                 // Some store reads per commit; cache the agent fields if streaming gets slow. A store failure drops this
                 // line. A stopped child still gives `idle` here, and its `stopped` line follows.
                 const child = await found.info().catch(() => undefined);
                 if (child === undefined || !socket.writable)
                     return;
-                if (!write({ ops, child }))
+                if (!write({ change, child }))
                     await once(socket, "drain").catch(() => { });
             });
             return queue;
@@ -690,17 +586,13 @@ async function serveWatch(handler, handle, connection) {
             }
             else if (next.name !== found.record?.name) {
                 found = { ...found, record: next, info: () => childInfo(handler, handle, next) };
-                await send([]);
+                await send({});
             }
         });
-        conversation.start((_view, ops) => send(ops));
+        conversation.start((view, ops) => send(viewChange(view, ops)));
     });
     return { view: conversation.value, child: last };
 }
-/** The record of `handle` in the `Children` value `state`. */
-function recordOf(state, handle) {
-    return state != null && Object.hasOwn(state.children, handle) ? state.children[handle] : undefined;
-}
 /**
  * The lock of the host, a write transaction on `lock.sqlite`, held until `close()`. The system drops it when the
  * process ends. It is undefined when another process holds it. `IMMEDIATE`, not `EXCLUSIVE`: two hosts that start at
@@ -756,72 +648,3 @@ function liveTasks(tasks) {
     }
     return tasks.length - dead.size;
 }
-/** A `package.json`, which is a JSON object. */
-const PackageJson = Type.Object({});
-/** The part of a package's `package.json` that names its entries. */
-const Manifest = Type.Object({
-    piDurable: Type.Optional(Type.Object({ extensions: Type.Optional(Type.Array(Type.String())) })),
-});
-/**
- * The `piDurable` entries of the installed packages in Pi's `settingsManager` for `cwd`, then the entries of
- * `entries.json` (see `readEntries`), in one shared event bus, as one entry whose `close()` closes each of them and
- * passes its errors to `warn`. When an entry fails to load, the entries loaded before it close. Missing packages are
- * skipped, not installed, and so is an entry module that does not exist, such as one of an uninstalled package.
- */
-async function loadEntries(cwd, agentDir, settingsManager, place, warn) {
-    const modules = new Set();
-    const roots = new DefaultPackageManager({ cwd, agentDir, settingsManager })
-        .listConfiguredPackages()
-        .flatMap((found) => found.installedPath ?? []);
-    for (const root of new Set(roots)) {
-        const path = join(root, "package.json");
-        const manifest = JSON.parse(await readFile(path, "utf8").catch(() => "{}"));
-        if (!Value.Check(PackageJson, manifest)) {
-            warn(new Error(`${path} is not a valid package.json`));
-            continue;
-        }
-        if (!Value.Check(Manifest, manifest)) {
-            warn(new Error(`${path} has an invalid piDurable field`));
-            continue;
-        }
-        for (const path of manifest.piDurable?.extensions ?? [])
-            modules.add(resolvePath(root, path));
-    }
-    for (const module of Object.values(readEntries()))
-        if (existsSync(module))
-            modules.add(module);
-    const events = createEventBus();
-    const entries = [];
-    const close = async () => {
-        for (const result of await Promise.allSettled(entries.map((entry) => entry.close()))) {
-            if (result.status === "rejected")
-                warn(result.reason);
-        }
-    };
-    try {
-        for (const module of modules) {
-            const entry = await importEntry(module);
-            entries.push(await entry.default({ durable, ai, events, children: library, place }));
-        }
-    }
-    catch (error) {
-        await close();
-        throw error;
-    }
-    return {
-        extensions: entries.flatMap((entry) => entry.extensions),
-        tasks: entries.flatMap((entry) => entry.tasks ?? []),
-        close,
-    };
-}
-/**
- * Imports the entry `module`. Node does not strip types under `node_modules`, where Pi installs npm packages, so jiti
- * loads a TypeScript entry there.
- */
-async function importEntry(module) {
-    if (module.endsWith(".ts") && module.split(sep).includes("node_modules")) {
-        const { createJiti } = await import("jiti");
-        return createJiti(import.meta.url).import(module);
-    }
-    return import(__rewriteRelativeImportExtension(pathToFileURL(module).href));
-}

package/dist/load-entries.d.ts

@@ -0,0 +1,18 @@
+import { type SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { AnyTask, Extension } from "@earendil-works/pi-durable";
+import type { createChildren, Place } from "./children.ts";
+type ChildrenLibrary = ReturnType<typeof createChildren>;
+/** What the default export of an entry returns: its extensions, the tasks that `start` runs, and `close`. */
+export type Entry = {
+    readonly extensions: readonly Extension[];
+    readonly tasks?: readonly AnyTask[];
+    close(): Promise<void>;
+};
+/**
+ * The `piDurable` entries of the installed packages in Pi's `settingsManager` for `cwd`, then the entries of
+ * `entries.json` (see `readEntries`), with the children library `children`, in one shared event bus, as one entry whose `close()` closes each of them and
+ * passes its errors to `warn`. When an entry fails to load, the entries loaded before it close. Missing packages are
+ * skipped, not installed, and so is an entry module that does not exist, such as one of an uninstalled package.
+ */
+export declare function loadEntries(cwd: string, agentDir: string, settingsManager: SettingsManager, place: Place, children: ChildrenLibrary, warn: (cause: unknown) => void): Promise<Required<Entry>>;
+export {};

package/dist/load-entries.js

@@ -0,0 +1,91 @@
+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;
+};
+/**
+ * The entries that the host loads: the `piDurable` entries of Pi's packages and the entries of `entries.json`. Each
+ * entry is a module whose default export gives extensions and tasks to the host.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve as resolvePath, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import * as ai from "@earendil-works/pi-ai";
+import { createEventBus, DefaultPackageManager, } from "@earendil-works/pi-coding-agent";
+import * as durable from "@earendil-works/pi-durable";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { readEntries } from "./entries.js";
+/** A `package.json`, which is a JSON object. */
+const PackageJson = Type.Object({});
+/** The part of a package's `package.json` that names its entries. */
+const Manifest = Type.Object({
+    piDurable: Type.Optional(Type.Object({ extensions: Type.Optional(Type.Array(Type.String())) })),
+});
+/**
+ * The `piDurable` entries of the installed packages in Pi's `settingsManager` for `cwd`, then the entries of
+ * `entries.json` (see `readEntries`), with the children library `children`, in one shared event bus, as one entry whose `close()` closes each of them and
+ * passes its errors to `warn`. When an entry fails to load, the entries loaded before it close. Missing packages are
+ * skipped, not installed, and so is an entry module that does not exist, such as one of an uninstalled package.
+ */
+export async function loadEntries(cwd, agentDir, settingsManager, place, children, warn) {
+    const modules = new Set();
+    const roots = new DefaultPackageManager({ cwd, agentDir, settingsManager })
+        .listConfiguredPackages()
+        .flatMap((found) => found.installedPath ?? []);
+    for (const root of new Set(roots)) {
+        const path = join(root, "package.json");
+        const manifest = JSON.parse(await readFile(path, "utf8").catch(() => "{}"));
+        if (!Value.Check(PackageJson, manifest)) {
+            warn(new Error(`${path} is not a valid package.json`));
+            continue;
+        }
+        if (!Value.Check(Manifest, manifest)) {
+            warn(new Error(`${path} has an invalid piDurable field`));
+            continue;
+        }
+        for (const path of manifest.piDurable?.extensions ?? [])
+            modules.add(resolvePath(root, path));
+    }
+    for (const module of Object.values(readEntries()))
+        if (existsSync(module))
+            modules.add(module);
+    const events = createEventBus();
+    const entries = [];
+    const close = async () => {
+        for (const result of await Promise.allSettled(entries.map((entry) => entry.close()))) {
+            if (result.status === "rejected")
+                warn(result.reason);
+        }
+    };
+    try {
+        for (const module of modules) {
+            const entry = await importEntry(module);
+            entries.push(await entry.default({ durable, ai, events, children, place }));
+        }
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+    return {
+        extensions: entries.flatMap((entry) => entry.extensions),
+        tasks: entries.flatMap((entry) => entry.tasks ?? []),
+        close,
+    };
+}
+/**
+ * Imports the entry `module`. Node does not strip types under `node_modules`, where Pi installs npm packages, so jiti
+ * loads a TypeScript entry there.
+ */
+async function importEntry(module) {
+    if (module.endsWith(".ts") && module.split(sep).includes("node_modules")) {
+        const { createJiti } = await import("jiti");
+        return createJiti(import.meta.url).import(module);
+    }
+    return import(__rewriteRelativeImportExtension(pathToFileURL(module).href));
+}

package/dist/mirror.d.ts

@@ -0,0 +1,95 @@
+import type { ConversationView } from "@earendil-works/pi-durable";
+import { type Static, Type } from "typebox";
+import { type ChildInfo, type Request } from "./protocol.ts";
+/** The `customType` of the session entry that holds the target of a mirror session. */
+export declare const MIRROR_ENTRY = "harness-mirror";
+/**
+ * The conversation that a mirror session shows, in the host of `project`: the child or project agent `handle`, or the
+ * conversation `conversation` that the children library opened. Each refuses the other key.
+ */
+export declare const MirrorTarget: Type.TUnion<[Type.TObject<{
+    project: Type.TString;
+    handle: Type.TString;
+    conversation: Type.TOptional<Type.TNever>;
+}>, Type.TObject<{
+    project: Type.TString;
+    conversation: Type.TString;
+    handle: Type.TOptional<Type.TNever>;
+}>]>;
+export type MirrorTarget = Static<typeof MirrorTarget>;
+/** Whether the data of a session entry is a mirror target. */
+export declare function isMirrorTarget(data: unknown): data is MirrorTarget;
+/**
+ * The Pi flags that open a mirror session of a target: the project, and the child or the conversation in place of the
+ * project agent.
+ */
+export declare const PI_FLAGS: {
+    readonly project: "harness";
+    readonly child: "harness-child";
+    readonly conversation: "harness-conversation";
+};
+/** The arguments of `pi` that open a mirror session of `target`. */
+export declare function piArgs(target: MirrorTarget): string[];
+/**
+ * The arguments of the `harness` CLI that open `target` in Pi: `<project>` for the project agent, `--project <project>
+ * attach <handle>` for a child, and `--project <project> attach --conversation <id>` for a conversation.
+ */
+export declare function harnessArgs(target: MirrorTarget): string[];
+/** The title of the agent of `target` before the host gives its name: the handle or the conversation ID of a child. */
+export declare function targetTitle(target: MirrorTarget): string;
+/** A change of the model or the thinking level of the mirrored conversation. */
+export type MirrorConfigure = Omit<Extract<Request, {
+    type: "configure";
+}>, "type" | "handle">;
+/**
+ * The connection of a mirror: before the first one, open, connecting again after the host closed it, or failed for
+ * good, with the reason.
+ */
+export type MirrorStatus = {
+    readonly kind: "connecting" | "open" | "reconnecting";
+} | {
+    readonly kind: "failed";
+    readonly reason: string;
+};
+export type MirrorOptions = {
+    /** The waits before the tries to connect again after the host closed the connection. Default 0, 2 and 5 s. */
+    readonly retryDelaysMs?: readonly number[];
+    /** Whether a connection starts the host when none runs. Default true. */
+    readonly start?: boolean;
+};
+/**
+ * A live copy of one conversation of a harness host, and the requests that act on it. It connects at once, which starts
+ * the host when none runs, and connects again when the host closes the connection, with one try after each of
+ * `retryDelaysMs`. It fails for good when the first connection fails, when all the tries fail, when the child is
+ * stopped, and when the host closes a connection that was opened again less than 10 s before, so that a host that fails
+ * at each start does not start again and again. `onChange` runs after each change of `status`, `view` and `child`, with
+ * the status before the change.
+ */
+export declare class Mirror {
+    #private;
+    readonly target: MirrorTarget;
+    constructor(target: MirrorTarget, onChange: (previous: MirrorStatus) => void, options?: MirrorOptions);
+    get status(): MirrorStatus;
+    /** The conversation, as the last connection gave it. It is undefined before the first connection. */
+    get view(): ConversationView | undefined;
+    /** The child or the project agent, as the last connection gave it. It is undefined before the first connection. */
+    get child(): ChildInfo | undefined;
+    /** Whether the conversation works, as an open connection tells. */
+    get busy(): boolean;
+    /**
+     * Sends `message`: a new turn when the conversation is idle, else a steer, or a follow-up with `followUp`. It resolves
+     * once the host has the message. The message waits while the mirror connects. When its connection closes before the
+     * host answers, it goes again on the next connection with the same request ID, so that the host takes it once. It
+     * rejects when the host refuses the message, and when the mirror fails or closes before the host has it.
+     */
+    send(message: string, followUp: boolean): Promise<void>;
+    /** Aborts the turn, and gives the texts of the queued messages that the host withdraws, steers first. */
+    abort(): Promise<string[]>;
+    /**
+     * Changes the model or the thinking level. The host refuses a model it does not know and a level it does not have. A
+     * conversation of the children library refuses it without a request.
+     */
+    configure(change: MirrorConfigure): Promise<void>;
+    /** Closes the connection and stops connecting. The conversation keeps running in the host. */
+    close(): void;
+}