@tshu-w/pi-agents 0.0.0-stage → 0.1.0

package/src/agents/tool.ts

@@ -0,0 +1,205 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { boundBlocks, boundText } from "../output.ts";
+import { rejectFields } from "../params.ts";
+import { renderTextResult, renderToolCall, startDuration, type DurationState } from "../render-call.ts";
+import type { RootRuntime } from "../roots/runtime.ts";
+import {
+	THINKING_LEVELS,
+	type Limits,
+	type WaitOutcome,
+	type WaitResult,
+} from "./agents.ts";
+import {
+	deliver,
+	label,
+	nodes,
+	rememberRoots,
+	shortId,
+	resolveIn,
+	treeEntries,
+	type AgentNode,
+	type Entry,
+} from "./registry.ts";
+import { listLine, searchEntries } from "./search.ts";
+
+function resultBlock({ agent, input, history }: WaitResult, ids: string[]): string {
+	return `<agent-result name="${agent.name}" id="${shortId(agent.id, ids)}" status="${input.state}"${history ? ' history="true"' : ""}>\n${input.result ?? ""}\n</agent-result>`;
+}
+
+function resultDetails({ agent, input, history }: WaitResult, result?: string) {
+	return { id: agent.id, name: agent.name, state: input.state, history, ...(result === undefined ? {} : { result }) };
+}
+
+/** Renders wait results; returns the text and the results the caller has now read. */
+function renderWait(outcome: WaitOutcome, ids: string[]): { text: string; read: WaitResult[]; details: Record<string, unknown> } {
+	const { results, pending } = outcome;
+	const pendingLine = pending.length > 0 ? `Still pending: ${pending.map((agent) => label(agent, ids)).join(", ")}` : "";
+	if (results.length === 0) return { text: pendingLine || "No results.", read: [], details: { results: [], pending: pending.map((agent) => agent.id) } };
+	const only = results[0]!;
+	if (results.length === 1 && pending.length === 0 && !only.history && only.input.state === "completed") {
+		const bounded = boundText(only.input.result ?? "", "pi-agents-wait");
+		return { text: bounded.text, read: results, details: { results: [resultDetails(only, bounded.kept)], pending: [], ...bounded.details } };
+	}
+	const blocks = results.map((result) => resultBlock(result, ids));
+	const bounded = boundBlocks(blocks, "agent-result", "pi-agents-wait");
+	let offset = 0;
+	const details = results.map((result, index) => {
+		const block = blocks[index]!;
+		const available = Math.max(0, bounded.kept.length - offset - block.indexOf("\n") - 1);
+		offset += block.length + 2;
+		return resultDetails(result, index < bounded.shown ? (result.input.result ?? "").slice(0, available) : undefined);
+	});
+	let text = bounded.text;
+	const read = results.slice(0, bounded.shown);
+	const omitted = results.slice(bounded.shown);
+	if (omitted.length > 0) text += `\n\n[Results omitted: ${omitted.map((result) => label(result.agent, ids)).join(", ")}. Use wait with fewer targets.]`;
+	if (pendingLine) text += `\n\n${pendingLine}`;
+	return { text, read, details: { results: details, pending: pending.map((agent) => agent.id), ...bounded.details } };
+}
+
+/** Registers the `agent` tool. */
+export function registerAgentTool(
+	pi: ExtensionAPI,
+	{ limits, roots, requireNode }: { limits: Limits; roots: RootRuntime; requireNode: (current: ExtensionContext) => AgentNode },
+): void {
+	/** Agents visible to a node: its tree, and for a root Agent also the other root Agents. */
+	const visible = async (self: AgentNode, signal?: AbortSignal): Promise<Entry[]> => {
+		const tree = treeEntries(self.scopeId);
+		if (self.ownerId !== undefined) return tree;
+		const others = (await roots.roots(signal))
+			.filter((root) => !tree.some((entry) => entry.id === root.id))
+			.map((root) => ({ ...root, remote: !nodes.has(root.id) }));
+		rememberRoots(others.map((root) => root.id));
+		return [...tree, ...others];
+	};
+
+	const { maxConcurrent, maxOutstanding } = limits;
+	const slotsBusy = `all ${maxConcurrent} slots are busy`;
+
+	pi.registerTool({
+		name: "agent",
+		label: "Agent",
+		renderCall: (args, theme, context) => {
+			startDuration(context.state as DurationState, args.action === "wait", context.executionStarted);
+			return renderToolCall("agent", args, theme, context.lastComponent);
+		},
+		// `wait` shows how long it has waited.
+		renderResult: (result, options, theme, context) => renderTextResult(result, options, theme, context),
+		description: `Create, message, and coordinate Agents. \`spawn\` creates an owned Agent and sends its first input; \`send\` sends an input or a write to a visible Agent; \`wait\` waits for owned Agents and returns unread results; \`list\` finds visible Agents; \`abort\` stops an owned Agent's current turn and queued inputs while keeping it available. When an owned Agent finishes an input while its owner is not waiting for it, the owner receives a notification naming the Agent and outcome; \`wait\` returns the result. Owned Agents under the same root share \`${maxConcurrent}\` execution slots and a limit of \`${maxOutstanding}\` inputs that have not ended. Inputs that start a new turn queue when all slots are busy; new inputs are rejected at the input limit.`,
+		promptSnippet: "Create, message, and coordinate Agents",
+		promptGuidelines: [
+			"Use `agent(action='spawn', name=..., message=...)` for concrete, bounded work with a clear expected result. Keep the first message self-contained; use `context='fork'` only when the Agent needs the caller's conversation.",
+			"For independent work, start the Agents before waiting and partition tasks into non-overlapping responsibilities.",
+			"Use `agent(action='wait', ...)` when the next step depends on Agent results. Prefer one longer wait over repeated short polling.",
+		],
+		parameters: Type.Object({
+			action: StringEnum(["spawn", "send", "wait", "list", "abort"] as const, { description: "Operation and applicable parameters: `spawn(name, message, cwd?, context?, model?, thinkingLevel?)`, `send(target, message, deliverAs?)`, `wait(target?, history?, timeout?)`, `list(query?, state?, limit?, offset?)`, or `abort(target)`." }),
+			name: Type.Optional(Type.String({ description: "Name of the new Agent for `spawn`; unique among the caller's Agents." })),
+			message: Type.Optional(Type.String({ description: "Non-empty text for `spawn` or `send`." })),
+			cwd: Type.Optional(Type.String({ description: "Working directory for `spawn` (default: the caller's current working directory)." })),
+			context: Type.Optional(StringEnum(["fresh", "fork"] as const, { description: "Context for `spawn` (default: fresh). fresh starts without the caller's conversation; fork snapshots it." })),
+			model: Type.Optional(Type.String({ description: "Model for `spawn` as provider/modelId (default: the caller's model)." })),
+			thinkingLevel: Type.Optional(StringEnum(THINKING_LEVELS, { description: "Thinking level for `spawn`: off, minimal, low, medium, high, or xhigh (default: the caller's level)." })),
+			target: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())], { description: "Agent ID, name, or unique ID prefix for `send`, `wait`, or `abort`. `wait` and `send` with `deliverAs='write'` also accept an array. When omitted for `wait`, selects all owned Agents with pending or unread results." })),
+			deliverAs: Type.Optional(StringEnum(["followUp", "steer", "write"] as const, { description: "Delivery for `send` (default: followUp). followUp waits until the recipient's current turn ends; steer delivers after its current tool calls, before the next model call; write delivers like steer but never starts a turn and has no result." })),
+			history: Type.Optional(Type.Integer({ minimum: 0, description: "Number of most recent read results to return again per selected Agent for `wait` (default: 0)." })),
+			timeout: Type.Optional(Type.Number({ minimum: 10, maximum: 3600, description: "Maximum seconds for `wait` (default: 30, min: 10, max: 3600). Timeout does not abort Agents." })),
+			query: Type.Optional(Type.String({ description: "Search query for `list`, matching ID, name, cwd, summaries, and user messages. Case-insensitive; spaces mean AND; `|` means OR." })),
+			state: Type.Optional(StringEnum(["running", "waiting", "queued", "idle"] as const, { description: "State for `list`: running, waiting, queued, or idle." })),
+			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 200, description: "Maximum Agents returned by `list` (default: 20, max: 200)." })),
+			offset: Type.Optional(Type.Integer({ minimum: 0, description: "Number of Agents to skip for `list` (default: 0)." })),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, current) {
+			const self = requireNode(current);
+			const agents = self.agents;
+			const caller = { id: self.id, name: self.name() };
+			const ids = () => agents.ids();
+			const targets = params.target === undefined ? undefined : Array.isArray(params.target) ? params.target : [params.target];
+			switch (params.action) {
+				case "spawn": {
+					rejectFields(params, "spawn", ["target", "deliverAs", "history", "timeout", "query", "state", "limit", "offset"]);
+					if (!params.name?.trim() || !params.message?.trim()) throw new Error("spawn requires name and message");
+					const { record, queued } = agents.spawn({
+						name: params.name,
+						message: params.message,
+						cwd: params.cwd,
+						context: params.context,
+						model: params.model,
+						thinkingLevel: params.thinkingLevel,
+					});
+					return {
+						content: [{ type: "text", text: `Agent ${label(record, ids())} ${queued ? `queued: ${slotsBusy}` : "started"}.` }],
+						details: { id: record.id, name: record.name, queued },
+					};
+				}
+				case "send": {
+					rejectFields(params, "send", ["name", "cwd", "context", "model", "thinkingLevel", "history", "timeout", "query", "state", "limit", "offset"]);
+					const delivery = params.deliverAs ?? "followUp";
+					if (!targets?.length || !params.message?.trim()) throw new Error("send requires target and message");
+					if (targets.length > 1 && delivery !== "write") throw new Error("Only a write can go to several Agents.");
+					const tree = treeEntries(self.scopeId);
+					const candidates = targets.every((target) => tree.some((entry) => entry.id === target)) ? tree : await visible(self, signal);
+					const entries = targets.map((target) => resolveIn(candidates, target));
+					if (entries.some((entry) => entry.id === self.id)) throw new Error("An Agent cannot send to itself.");
+					const body = params.message;
+					const send = async (entry: Entry) => {
+						if (!entry.remote) return deliver(caller, entry, delivery, body);
+						await roots.send({ id: entry.id, label: label(entry, ids()) }, delivery, body, signal);
+						return { queued: false };
+					};
+					if (delivery === "write") {
+						for (const entry of entries) await send(entry);
+						return {
+							content: [{ type: "text", text: `Write accepted by ${entries.map((entry) => label(entry, ids())).join(", ")}.` }],
+							details: { ids: entries.map((entry) => entry.id) },
+						};
+					}
+					const entry = entries[0]!;
+					const { queued } = await send(entry);
+					return {
+						content: [{ type: "text", text: `Input accepted by ${label(entry, ids())}${queued ? `, queued: ${slotsBusy}` : ""}.` }],
+						details: { id: entry.id, queued },
+					};
+				}
+				case "wait": {
+					rejectFields(params, "wait", ["name", "message", "cwd", "context", "model", "thinkingLevel", "deliverAs", "query", "state", "limit", "offset"]);
+					const selected = targets?.map((target) => agents.ownedTarget(target));
+					// An empty partial result lets the row show the elapsed time.
+					onUpdate?.({ content: [], details: undefined });
+					const outcome = await agents.wait(selected, params.history ?? 0, params.timeout ?? 30, signal);
+					const rendered = renderWait(outcome, ids());
+					agents.markRead(rendered.read);
+					return { content: [{ type: "text", text: rendered.text }], details: rendered.details };
+				}
+				case "list": {
+					rejectFields(params, "list", ["name", "message", "cwd", "context", "model", "thinkingLevel", "target", "deliverAs", "history", "timeout"]);
+					const offset = params.offset ?? 0;
+					const limit = params.limit ?? 20;
+					const all = await visible(self, signal);
+					const entries = all.filter((entry) => entry.id !== self.id && (!params.state || entry.state === params.state));
+					const items = searchEntries(entries, params.query);
+					const page = items.slice(offset, offset + limit);
+					const agents = page.map(({ entry: { id, name, ownerId, state } }) => ({ id, name, ownerId, state }));
+					if (page.length === 0) return { content: [{ type: "text", text: "No matching Agents." }], details: { total: items.length, agents } };
+					const lines = page.map((item) => listLine(item, all.map((entry) => entry.id)));
+					const remaining = items.length - offset - page.length;
+					if (remaining > 0) lines.push(`[${remaining} more results. Use offset=${offset + page.length} to continue.]`);
+					const text = boundText(lines.join("\n"), "pi-agents-list");
+					return { content: [{ type: "text", text: text.text }], details: { total: items.length, agents, ...text.details } };
+				}
+				case "abort": {
+					rejectFields(params, "abort", ["name", "message", "cwd", "context", "model", "thinkingLevel", "deliverAs", "history", "timeout", "query", "state", "limit", "offset"]);
+					if (targets?.length !== 1) throw new Error("abort requires one target");
+					const agent = agents.ownedTarget(targets[0]!);
+					const aborted = await agents.abort(agent, { silent: true });
+					return {
+						content: [{ type: "text", text: `Agent ${label(agent.record, ids())} ${aborted ? "aborted" : "has no turn or queued inputs"}.` }],
+						details: { id: agent.record.id, aborted },
+					};
+				}
+			}
+		},
+	});
+}

package/src/daemon/client.mjs

@@ -0,0 +1,84 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { prepareDirectory } from '../roots/paths.mjs';
+import { request } from '../roots/transport.mjs';
+
+const RETRY = ['SERVER_CLOSED', 'CONNECTION_CLOSED', 'ECONNRESET', 'INVALID_FRAME'];
+
+/**
+ * Waits until the daemon answers, starting it when none runs.
+ * @param {ReturnType<typeof import('../roots/paths.mjs').statePaths>} paths
+ * @param {{ sessionDir: string, signal?: AbortSignal }} options
+ */
+export async function ensureDaemon(paths, { sessionDir, signal }) {
+  await prepareDirectory(paths.runtime);
+  for (;;) {
+    try {
+      return await request(paths.daemon, { action: 'status' }, { signal, timeoutMs: 1000 });
+    } catch (error) {
+      if (RETRY.includes(error.code)) {
+        await delay(50, undefined, { signal });
+        continue;
+      }
+      if (!['ENOENT', 'ECONNREFUSED'].includes(error.code)) throw error;
+    }
+    await prepareDirectory(paths.state);
+    const log = await open(paths.daemonLog, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    let child;
+    try {
+      const info = await log.stat();
+      if (!info.isFile() || info.uid !== process.getuid() || (info.mode & 0o077)) throw new Error('Daemon log must be a private regular file');
+      child = spawn(process.execPath, [fileURLToPath(new URL('../../bin/daemon.mjs', import.meta.url)), sessionDir], {
+        cwd: paths.runtime, detached: true, stdio: ['ignore', log.fd, log.fd],
+      });
+    } finally { await log.close(); }
+    let launchError;
+    child.on('error', error => { launchError = error; });
+    child.once('exit', code => {
+      if (code !== 0) launchError = new Error(`Daemon exited (${code}). See ${paths.daemonLog}`);
+    });
+    child.unref();
+    for (;;) {
+      signal?.throwIfAborted();
+      if (launchError) throw launchError;
+      try {
+        return await request(paths.daemon, { action: 'status' }, { signal, timeoutMs: 1000 });
+      } catch (failure) {
+        if (!['ENOENT', 'ECONNREFUSED', ...RETRY].includes(failure.code)) throw failure;
+        // Another daemon holds the lock; it answers once its socket is up.
+        if (child.exitCode === 0) break;
+      }
+      await delay(50, undefined, { signal });
+    }
+  }
+}
+
+export async function sendViaDaemon(paths, message, { sessionDir, launch, signal, timeoutMs = 10000 }) {
+  const deadline = AbortSignal.timeout(timeoutMs);
+  const stop = signal ? AbortSignal.any([signal, deadline]) : deadline;
+  try {
+    for (;;) {
+      await ensureDaemon(paths, { sessionDir, signal: stop });
+      try {
+        return await request(paths.daemon, { action: 'deliver', message, launch }, { signal: stop, timeoutMs });
+      } catch (error) {
+        // Replay only when the transport guarantees the handler was not invoked.
+        if (error.uncertainDelivery || !(['ENOENT', 'ECONNREFUSED'].includes(error.code)
+          || (error.code === 'SERVER_CLOSED' && error.uncertainDelivery === false))) throw error;
+        await delay(50, undefined, { signal: stop });
+      }
+    }
+  } catch (error) {
+    if (deadline.aborted && stop.reason === deadline.reason) {
+      throw Object.assign(new Error('Acknowledgement timed out', { cause: error }), {
+        code: 'ETIMEDOUT',
+        ...(typeof error.uncertainDelivery === 'boolean' ? { uncertainDelivery: error.uncertainDelivery } : {}),
+      });
+    }
+    throw error;
+  }
+}

package/src/daemon/router.mjs

@@ -0,0 +1,103 @@
+function fault(code, message, uncertainDelivery = false) {
+  return Object.assign(new Error(message), { code, uncertainDelivery });
+}
+
+// Bound the wait even when an injected operation ignores its signal. Aborting
+// this signal stops observation/retries, not work already accepted by a Session.
+function bounded(run, { signal, timeoutMs }, interruption) {
+  return new Promise((resolve, reject) => {
+    const controller = new AbortController();
+    let settled = false, timer;
+    function finish(error, value) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      if (error) reject(error); else resolve(value);
+    }
+    function interrupt(code) {
+      const error = interruption(code);
+      finish(error);
+      controller.abort(error);
+    }
+    const abort = () => interrupt('ABORT_ERR');
+    if (signal?.aborted) { abort(); return; }
+    signal?.addEventListener('abort', abort, { once: true });
+    timer = setTimeout(() => interrupt('ETIMEDOUT'), timeoutMs);
+    try {
+      Promise.resolve(run({ signal: controller.signal, timeoutMs })).then(
+        value => finish(null, value), error => finish(error),
+      );
+    } catch (error) { finish(error); }
+  });
+}
+
+function validateAck(value, message) {
+  if (value?.accepted !== true || value.messageId !== message.id) {
+    throw fault('INVALID_ACK', `Invalid acknowledgement for Message ${message.id}; the recipient may have received it`, true);
+  }
+  return value;
+}
+
+const WAKE_TIMEOUT_MS = 10000;
+
+export function createRouter({ deliverToSession, wake }) {
+  const waking = new Map();
+  function wakeOnce(recipient, { signal, launch }) {
+    signal.throwIfAborted();
+    let shared = waking.get(recipient);
+    if (!shared) {
+      shared = { controller: new AbortController(), waiters: 0, settled: false };
+      // Register waiters before invoking wake, which may itself cancel a caller.
+      // Each caller bounds its own wait; all waiters own the launch lifetime.
+      shared.pending = bounded(options => Promise.resolve().then(() => {
+        options.signal.throwIfAborted();
+        return wake(recipient, { ...options, launch });
+      }), { signal: shared.controller.signal, timeoutMs: WAKE_TIMEOUT_MS },
+      code => fault(code, `Wake ${code === 'ABORT_ERR' ? 'cancelled' : 'timed out'} for Agent ${recipient}`))
+        .finally(() => {
+          shared.settled = true;
+          if (waking.get(recipient) === shared) waking.delete(recipient);
+        });
+      waking.set(recipient, shared);
+    }
+    shared.waiters++;
+    return new Promise((resolve, reject) => {
+      let finished = false;
+      function finish(error) {
+        if (finished) return;
+        finished = true;
+        signal.removeEventListener('abort', abort);
+        shared.waiters--;
+        if (!shared.waiters && !shared.settled) {
+          if (waking.get(recipient) === shared) waking.delete(recipient);
+          shared.controller.abort();
+        }
+        if (error) reject(error); else resolve();
+      }
+      const abort = () => finish(signal.reason);
+      signal.addEventListener('abort', abort, { once: true });
+      shared.pending.then(() => finish(), error => finish(error));
+    });
+  }
+  return {
+    async accept(message, { signal, timeoutMs = 10000, launch } = {}) {
+      let delivering = false;
+      return bounded(async options => {
+        delivering = true;
+        try {
+          return validateAck(await deliverToSession(message, options), message);
+        } catch (error) {
+          options.signal.throwIfAborted();
+          if (error?.uncertainDelivery || !['ENOENT', 'ECONNREFUSED'].includes(error?.code)) throw error;
+        }
+        delivering = false;
+        await wakeOnce(message.recipient, { signal: options.signal, launch });
+        options.signal.throwIfAborted();
+        delivering = true;
+        return validateAck(await deliverToSession(message, options), message);
+      }, { signal, timeoutMs }, code => fault(code,
+        `${code === 'ABORT_ERR' ? 'Send cancelled' : 'Send timed out'}${delivering ? '; the recipient may have received it' : ''}`, delivering));
+    },
+  };
+}

package/src/daemon/sessions.mjs

@@ -0,0 +1,129 @@
+import { constants } from 'node:fs';
+import { open, readFile, realpath, rename } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { relative } from 'node:path';
+import { discoverRoots } from '../roots/discovery.mjs';
+import { isLocked } from '../roots/locks.mjs';
+
+const MARKS_VERSION = 1;
+
+async function readMarks(file) {
+  try {
+    const value = JSON.parse(await readFile(file, 'utf8'));
+    if (value?.version === MARKS_VERSION && value.sessions && typeof value.sessions === 'object') return value.sessions;
+  } catch (error) { if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error; }
+  return {};
+}
+
+/** Session files outside the session directory that the daemon has seen running. */
+export async function markedFiles(paths) {
+  return Object.values(await readMarks(paths.workbench)).flatMap(mark => mark.sessionFile ?? []);
+}
+
+/**
+ * The daemon's view of root Sessions: live state reported by running Sessions, and per Session
+ * its last finished turn, the last turn the user has seen, and whether the workbench lists it,
+ * and where its file is when outside `sessionDir`, kept in `paths.workbench`. A Session with no
+ * marks counts as seen.
+ */
+export async function createSessions(paths, sessionDir) {
+  const marks = await readMarks(paths.workbench);
+  const live = new Map();
+  let saving = Promise.resolve();
+
+  function save() {
+    const data = JSON.stringify({ version: MARKS_VERSION, sessions: marks });
+    saving = saving.then(async () => {
+      const temporary = `${paths.workbench}.${randomUUID()}.tmp`;
+      const file = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+      try { await file.writeFile(data); } finally { await file.close(); }
+      await rename(temporary, paths.workbench);
+    }).catch(error => console.error(`[pi-agents] Saving seen marks failed: ${error.message}`));
+    return saving;
+  }
+
+  function files() {
+    return Object.values(marks).flatMap(mark => mark.sessionFile ?? []);
+  }
+
+  function finished(id, turn) {
+    const mark = marks[id] ??= {};
+    if (mark.last && mark.last.at >= turn.at) return false;
+    mark.last = { at: turn.at, failed: turn.failed === true };
+    return true;
+  }
+
+  return {
+    /**
+     * Records the state a running Session reports; a turn that ends while attached is seen.
+     * A Session that runs without a terminal, as the workbench and wakes start it or after a detach, stays listed.
+     */
+    update(state) {
+      // Pi saves a new Session only after its first reply; until then the first report dates it.
+      live.set(state.id, { ...state, since: live.get(state.id)?.since ?? new Date().toISOString() });
+      let changed = state.turn ? finished(state.id, state.turn) : false;
+      if (state.sessionFile && relative(sessionDir, state.sessionFile).startsWith('..') && marks[state.id]?.sessionFile !== state.sessionFile) {
+        (marks[state.id] ??= {}).sessionFile = state.sessionFile;
+        changed = true;
+      }
+      if (!state.attached && !marks[state.id]?.listed) {
+        (marks[state.id] ??= {}).listed = true;
+        changed = true;
+      }
+      const mark = marks[state.id];
+      if (state.attached && mark?.last && (mark.seen ?? 0) < mark.last.at) {
+        mark.seen = mark.last.at;
+        changed = true;
+      }
+      if (changed) save();
+    },
+    /** Forgets a Session that stopped; one that stopped without saying so has failed. */
+    end(id, { abnormal = false } = {}) {
+      live.delete(id);
+      if (abnormal && finished(id, { at: Date.now(), failed: true })) save();
+    },
+    /** Lists a Session in the workbench, as when the user opens it there. */
+    show(id) {
+      (marks[id] ??= {}).listed = true;
+      save();
+    },
+    /** Removes a Session from the workbench list and clears its unseen turn; its file stays. */
+    hide(id) {
+      const mark = marks[id];
+      if (!mark) return;
+      delete mark.listed;
+      if (mark.last) mark.seen = mark.last.at;
+      else delete marks[id];
+      save();
+    },
+    files,
+    /** Root Sessions the workbench lists: running ones, listed ones, and ones with an unseen turn. */
+    async list({ signal } = {}) {
+      const ids = new Set(live.keys());
+      for (const [id, mark] of Object.entries(marks)) {
+        if (mark.listed || (mark.last && (mark.seen ?? 0) < mark.last.at)) ids.add(id);
+      }
+      const records = await discoverRoots(sessionDir, { extraFiles: files(), ids, signal });
+      const rows = new Map();
+      for (const record of records) {
+        let status = 'idle';
+        if (!live.has(record.id)) {
+          try { if (isLocked(paths.locks, await realpath(record.sessionFile), record.id)) status = 'unknown'; }
+          catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+        }
+        rows.set(record.id, { id: record.id, name: record.name, title: record.title, reply: record.reply, cwd: record.cwd, sessionFile: record.sessionFile, updatedAt: record.updatedAt, status });
+      }
+      for (const state of live.values()) {
+        const saved = rows.get(state.id);
+        rows.set(state.id, { ...saved, ...state, title: state.title ?? saved?.title, reply: state.reply ?? saved?.reply,
+          status: state.blocked ? 'blocked' : state.working ? 'working' : 'idle', running: true, updatedAt: saved?.updatedAt ?? state.since });
+      }
+      return [...rows.values()].map(row => {
+        const mark = marks[row.id];
+        const attention = mark?.last && (mark.seen ?? 0) < mark.last.at ? (mark.last.failed ? 'failed' : 'done') : undefined;
+        return { ...row, ...(attention ? { attention } : {}), ...(mark?.last ? { finishedAt: mark.last.at } : {}) };
+      });
+    },
+    saved: () => saving,
+  };
+}

package/src/daemon/version.mjs

@@ -0,0 +1,19 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = fileURLToPath(new URL('../../', import.meta.url));
+
+/** A hash of the package's code on disk, which changes when pi-agents is updated. */
+export async function codeVersion() {
+  const hash = createHash('sha256');
+  const files = ['package.json'];
+  for (const directory of ['bin', 'src']) {
+    for (const entry of await readdir(join(ROOT, directory), { recursive: true, withFileTypes: true })) {
+      if (entry.isFile()) files.push(join(entry.parentPath.slice(ROOT.length), entry.name));
+    }
+  }
+  for (const file of files.sort()) hash.update(file).update('\0').update(await readFile(join(ROOT, file))).update('\0');
+  return hash.digest('hex').slice(0, 16);
+}