pi-open-deskos 0.3.0 → 0.4.0

package/src/console-extension.ts

@@ -2,21 +2,25 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Container, Input, Key, SelectList, Text, matchesKey, truncateToWidth, type Focusable, type SelectItem } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { DeskConsoleClient, type ConsoleAttachment } from "./console-client.ts";
-import type { DeskLinkSnapshot } from "./reporter.ts";
-import type { DeskLinkConfig, HistoryPage, HostedPiSession, PositionedSessionEvent } from "./types.ts";
+import type { OdkLinkSnapshot } from "./reporter.ts";
+import type { OdkLinkConfig, HistoryPage, HostedPiSession, PositionedSessionEvent } from "./types.ts";
 import type { ControlTransport } from "./control-transport.ts";
 
-const CONSOLE_STATE_ENTRY = "open-deskos-console-state";
-const CONSOLE_CONTEXT_MESSAGE = "open-deskos-hosted-pi";
+const CONSOLE_STATE_ENTRY = "odk-console-state";
+const CONSOLE_CONTEXT_MESSAGE = "odk-hosted-pi";
 const CONTEXT_EVENTS = 24;
 const CONTEXT_BYTES = 24 * 1024;
 const TOOL_OUTPUT_BYTES = 48 * 1024;
 
 export interface ConsoleExtensionOptions {
   pi: ExtensionAPI;
-  config: DeskLinkConfig | null;
-  createControlTransport: (config: DeskLinkConfig) => ControlTransport;
-  reporterSnapshot: () => DeskLinkSnapshot | null;
+  config: OdkLinkConfig | null;
+  /** Every desk this machine reports to, in configuration order. */
+  desks?: OdkLinkConfig[];
+  /** Entries the configuration stated and this machine refuses to use, with the reason. */
+  refusals?: string[];
+  createControlTransport: (config: OdkLinkConfig) => ControlTransport;
+  reporterSnapshot: () => OdkLinkSnapshot | null;
   configHint: string;
 }
 
@@ -105,17 +109,20 @@ export function formatHistory(page: HistoryPage): string {
 
 export function registerConsoleExtension(options: ConsoleExtensionOptions): void {
   const { pi, config, createControlTransport, reporterSnapshot, configHint } = options;
+  const desks = options.desks ?? (config === null ? [] : [config]);
+  const refusals = options.refusals ?? [];
   let currentConsoleSessionId = "";
   let state: PersistedConsoleState = { lastApplied: 0 };
   let client: DeskConsoleClient | null = null;
   let attachment: ConsoleAttachment | null = null;
+  let generation = 0;
   let tail: PositionedSessionEvent[] = [];
   const surfaceListeners = new Set<(entry: PositionedSessionEvent) => void>();
 
   const controlConfigured = (): boolean => config !== null && Boolean(config.controlToken);
   const unavailable = (): string => config !== null
-    ? "set ODK_DESK_LINK_CONTROL_TOKEN to enable the Console"
-    : `${configHint}; set ODK_DESK_LINK_CONTROL_TOKEN to enable the Console`;
+    ? "set ODK_LINK_CONTROL_TOKEN to enable the Console"
+    : `${configHint}; set ODK_LINK_CONTROL_TOKEN to enable the Console`;
   const requireClient = (): DeskConsoleClient => {
     if (!controlConfigured() || !client) throw new Error(unavailable());
     return client;
@@ -127,7 +134,7 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
       state.sessionId ? `Hosted Pi ${state.sessionId}` : "Hosted Pi",
       ...tail.map(eventLine),
       ...(terminal === undefined ? [] : [`terminal ${JSON.stringify(terminal)}`]),
-      "Complete content remains available through desk_history.",
+      "Complete content remains available through odk_history.",
     ].join("\n");
     // Persist the bounded observation in context without autonomously starting
     // another model turn. The next user turn sees it, and a terminal result is
@@ -140,17 +147,26 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
     for (const listener of surfaceListeners) listener(entry);
   };
   const attach = async (sessionId: string, position = state.sessionId === sessionId ? state.lastApplied : undefined): Promise<ConsoleAttachment> => {
+    const owner = requireClient();
+    const attachingGeneration = ++generation;
+    injectContext();
     attachment?.close();
-    const next = await requireClient().attach({
+    attachment = null;
+    const next = await owner.attach({
       sessionId,
       ...(position === undefined ? {} : { position }),
-      onEvent: applyEvent,
+      onEvent(entry) { if (attachingGeneration === generation) applyEvent(entry); },
       onPosition(lastApplied) {
+        if (attachingGeneration !== generation) return;
         state = { sessionId, ...(state.attachmentId ? { attachmentId: state.attachmentId } : {}), lastApplied };
         persist();
       },
-      onTerminal(record) { injectContext(record); },
+      onTerminal(record) { if (attachingGeneration === generation) injectContext(record); },
     });
+    if (attachingGeneration !== generation || owner !== client) {
+      next.close();
+      throw new Error("Console session changed during attach");
+    }
     attachment = next;
     state = { sessionId, attachmentId: next.attachmentId, lastApplied: next.lastApplied() };
     persist();
@@ -159,9 +175,12 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
 
   if (controlConfigured()) {
     pi.registerMessageRenderer(CONSOLE_CONTEXT_MESSAGE, (message, _renderOptions, theme) =>
-      new Text(`${theme.fg("customMessageLabel", "[open-deskos] ")}${theme.fg("customMessageText", firstLine(typeof message.content === "string" ? message.content : "Hosted Pi update", 160))}`, 0, 0));
+      new Text(`${theme.fg("customMessageLabel", "[odk] ")}${theme.fg("customMessageText", firstLine(typeof message.content === "string" ? message.content : "Hosted Pi update", 160))}`, 0, 0));
 
     pi.on("session_start", (_event, ctx) => {
+    generation += 1;
+    attachment?.close();
+    client?.closeAttachment();
     currentConsoleSessionId = ctx.sessionManager.getSessionId();
     state = restoreState(ctx);
     tail = [];
@@ -172,6 +191,7 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
   });
   pi.on("agent_settled", () => injectContext());
     pi.on("session_shutdown", () => {
+      generation += 1;
       attachment?.close();
       attachment = null;
       client?.closeAttachment();
@@ -179,7 +199,7 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
     });
 
     pi.registerTool({
-    name: "desk_list",
+    name: "odk_list",
     label: "Desk List",
     description: "List the Hosted Pi sessions on Open DeskOS, including state, project, goal, and age.",
     parameters: Type.Object({}),
@@ -190,7 +210,7 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
     },
   });
   pi.registerTool({
-    name: "desk_start",
+    name: "odk_start",
     label: "Desk Start",
     description: "Start a Hosted Pi on Open DeskOS with a project and prompt. Returns its durable identity immediately.",
     parameters: Type.Object({ project: Type.String(), prompt: Type.String(), session_id: Type.Optional(Type.String()), mutation_id: Type.Optional(Type.String()) }),
@@ -205,7 +225,7 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
     },
   });
   pi.registerTool({
-    name: "desk_attach",
+    name: "odk_attach",
     label: "Desk Attach",
     description: "Attach this Pi session to one Hosted Pi and follow it from the last applied log position.",
     parameters: Type.Object({ session_id: Type.String(), position: Type.Optional(Type.Integer({ minimum: 0 })) }),
@@ -215,18 +235,20 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
     },
   });
   pi.registerTool({
-    name: "desk_prompt",
+    name: "odk_prompt",
     label: "Desk Prompt",
     description: "Send a further instruction to the attached Hosted Pi; while running this steers the current turn.",
     parameters: Type.Object({ prompt: Type.String(), mutation_id: Type.Optional(Type.String()) }),
     async execute(_id, params) {
       if (!attachment) throw new Error("attach to a Hosted Pi first");
-      await attachment.prompt(params.prompt, params.mutation_id ? { mutationId: params.mutation_id } : {});
-      return textResult(`Prompt delivered to ${attachment.sessionId}.`, state);
+      const joined = attachment;
+      const requestState = { ...state };
+      await joined.prompt(params.prompt, params.mutation_id ? { mutationId: params.mutation_id } : {});
+      return textResult(`Prompt delivered to ${joined.sessionId}.`, requestState);
     },
   });
   pi.registerTool({
-    name: "desk_cancel",
+    name: "odk_cancel",
     label: "Desk Cancel",
     description: "Cancel the attached Hosted Pi's running turn without ending the session.",
     parameters: Type.Object({
@@ -236,31 +258,37 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
     }),
     async execute(_id, params) {
       if (!attachment) throw new Error("attach to a Hosted Pi first");
-      await attachment.cancel({
+      const joined = attachment;
+      const requestState = { ...state };
+      await joined.cancel({
         ...(params.mutation_id ? { mutationId: params.mutation_id } : {}),
         ...(params.turn_id ? { turnId: params.turn_id } : {}),
         ...(params.precondition ? { precondition: params.precondition } : {}),
       });
-      return textResult(`Cancelled the running turn on ${attachment.sessionId}.`, state);
+      return textResult(`Cancelled the running turn on ${joined.sessionId}.`, requestState);
     },
   });
   pi.registerTool({
-    name: "desk_end",
+    name: "odk_end",
     label: "Desk End",
     description: "End the attached Hosted Pi and release its host slot.",
     parameters: Type.Object({ mutation_id: Type.Optional(Type.String()) }),
     async execute(_id, params) {
       if (!attachment) throw new Error("attach to a Hosted Pi first");
-      const ended = attachment.sessionId;
-      await attachment.end(params.mutation_id ? { mutationId: params.mutation_id } : {});
-      injectContext({ type: "ended", sessionId: ended });
-      attachment.close();
-      attachment = null;
-      return textResult(`Ended Hosted Pi ${ended}.`, state);
+      const joined = attachment;
+      const requestGeneration = generation;
+      const requestState = { ...state };
+      await joined.end(params.mutation_id ? { mutationId: params.mutation_id } : {});
+      if (generation === requestGeneration && attachment === joined) {
+        injectContext({ type: "ended", sessionId: joined.sessionId });
+        joined.close();
+        attachment = null;
+      }
+      return textResult(`Ended Hosted Pi ${joined.sessionId}.`, requestState);
     },
   });
     pi.registerTool({
-      name: "desk_history",
+      name: "odk_history",
       label: "Desk History",
       description: "Read a bounded page of complete Hosted Pi history from a session-log position.",
       parameters: Type.Object({ session_id: Type.String(), position: Type.Optional(Type.Integer({ minimum: 0 })) }),
@@ -273,16 +301,20 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
 
   const showStatus = (ctx: ExtensionContext): void => {
     const snapshot = reporterSnapshot();
-    const endpoint = config !== null ? `${config.host}:${config.port}` : "not configured";
+    const endpoint = desks.length > 0 ? desks.map((desk) => `${desk.host}:${desk.port}`).join(", ") : "not configured";
     const report = snapshot ? `${snapshot.link} · ${snapshot.sessions} session(s) · ${snapshot.events} event(s)` : "reporting inactive";
     const control = controlConfigured() ? `Console ready${state.sessionId ? ` · attached ${state.sessionId} @ ${state.lastApplied}` : ""}` : unavailable();
-    ctx.ui.notify(`[open-deskos] ${snapshot?.link ?? "offline"} · ${config?.machine ?? "machine"} → ${endpoint} · ${report.replace(/^(offline|connecting|connected) · /, "")} · ${control}${snapshot?.lastError ? ` · ${snapshot.lastError}` : ""}`, snapshot?.link === "connected" ? "info" : "warning");
+    // A machine that reports to several desks states each one, so a desk that is down
+    // cannot hide behind a set that is otherwise healthy, and a refused entry is said out loud.
+    const perDesk = snapshot?.desks && snapshot.desks.length > 1 ? ` · ${snapshot.desks.map((desk) => `${desk.endpoint} ${desk.link}`).join(", ")}` : "";
+    const refused = refusals.length > 0 ? ` · ${refusals[0]}` : "";
+    ctx.ui.notify(`[odk] ${snapshot?.link ?? "offline"} · ${desks[0]?.machine ?? config?.machine ?? "machine"} → ${endpoint} · ${report.replace(/^(offline|connecting|connected) · /, "")}${perDesk}${refused} · ${control}${snapshot?.lastError ? ` · ${snapshot.lastError}` : ""}`, snapshot?.link === "connected" ? "info" : "warning");
   };
 
   const chooseSession = async (ctx: ExtensionContext): Promise<string | undefined> => {
     const sessions = (await requireClient().list()).sessions;
     if (sessions.length === 0) {
-      ctx.ui.notify("[open-deskos] no Hosted Pi sessions", "info");
+      ctx.ui.notify("[odk] no Hosted Pi sessions", "info");
       return undefined;
     }
     const labels = sessions.map((session) => `${session.sessionId} · ${sessionLabel(session)}`);
@@ -292,23 +324,23 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
   };
 
   const launchInteractive = async (ctx: ExtensionContext): Promise<void> => {
-    if (!ctx.hasUI) throw new Error("launch requires interactive UI or desk_start");
+    if (!ctx.hasUI) throw new Error("launch requires interactive UI or odk_start");
     const project = await ctx.ui.input("Hosted Pi project", ctx.cwd);
     if (!project) return;
     const prompt = await ctx.ui.editor("Hosted Pi prompt", "");
     if (!prompt?.trim()) return;
     const reply = await requireClient().launch({ project, prompt });
-    ctx.ui.notify(`[open-deskos] started ${String(reply.sessionId ?? "Hosted Pi")}`, "info");
+    ctx.ui.notify(`[odk] started ${String(reply.sessionId ?? "Hosted Pi")}`, "info");
   };
 
   const openConsole = async (ctx: ExtensionContext): Promise<void> => {
     if (!controlConfigured()) {
-      ctx.ui.notify(`[open-deskos] Console unavailable · ${unavailable()}`, "warning");
+      ctx.ui.notify(`[odk] Console unavailable · ${unavailable()}`, "warning");
       return;
     }
     if (ctx.mode !== "tui") {
       const sessions = await requireClient().list();
-      ctx.ui.notify(`[open-deskos] ${sessions.sessions.length} Hosted Pi session(s)`, "info");
+      ctx.ui.notify(`[odk] ${sessions.sessions.length} Hosted Pi session(s)`, "info");
       return;
     }
     const sessions = (await requireClient().list()).sessions;
@@ -336,7 +368,7 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
           truncateToWidth(theme.fg("accent", theme.bold("Open DeskOS Console")), width),
           ...body,
           ...(attachment ? ["", truncateToWidth(theme.fg("success", `attached ${attachment.sessionId} @ ${attachment.lastApplied()}`), width), ...(historyLines.length ? [theme.fg("muted", "History"), ...historyLines] : events), ...promptInput.render(width)] : []),
-          ...(error ? [truncateToWidth(theme.fg("error", error), width)] : []),
+          ...((error || attachment?.error()) ? [truncateToWidth(theme.fg("error", error || attachment?.error() || ""), width)] : []),
           truncateToWidth(theme.fg("dim", attachment ? "enter send · ctrl+h history · ctrl+x cancel · ctrl+e end · esc close" : "up/down select · enter attach · n launch · r refresh · esc close"), width),
         ];
       };
@@ -356,7 +388,16 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
           return;
         }
         if (attachment && matchesKey(data, Key.ctrl("x"))) { void attachment.cancel().catch((cause) => { error = String(cause); tui.requestRender(); }); return; }
-        if (attachment && matchesKey(data, Key.ctrl("e"))) { void attachment.end().then(() => { attachment?.close(); attachment = null; }).catch((cause) => { error = String(cause); }).finally(() => tui.requestRender()); return; }
+        if (attachment && matchesKey(data, Key.ctrl("e"))) {
+          const joined = attachment;
+          const requestGeneration = generation;
+          void joined.end().then(() => {
+            if (generation !== requestGeneration || attachment !== joined) return;
+            joined.close();
+            attachment = null;
+          }).catch((cause) => { error = String(cause); }).finally(() => tui.requestRender());
+          return;
+        }
         if (matchesKey(data, Key.enter)) {
           const value = promptInput.getValue().trim();
           if (attachment && value) {
@@ -385,7 +426,7 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
     });
   };
 
-  pi.registerCommand("open-deskos", {
+  pi.registerCommand("odk", {
     description: "Open DeskOS menu or use console/status/attach/launch/cancel/history fast paths",
     handler: async (raw, ctx) => {
       const [action, ...rest] = raw.trim().split(/\s+/).filter(Boolean);
@@ -402,7 +443,7 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
         const sessionId = rest[0] ?? state.sessionId ?? await chooseSession(ctx);
         if (!sessionId) return;
         const page = await requireClient().history({ sessionId, position: Number.parseInt(rest[1] ?? "0", 10) || 0 });
-        ctx.ui.notify(`[open-deskos] ${formatHistory(page)}`, "info");
+        ctx.ui.notify(`[odk] ${formatHistory(page)}`, "info");
         return;
       }
       if (ctx.mode !== "tui") {
@@ -411,7 +452,7 @@ export function registerConsoleExtension(options: ConsoleExtensionOptions): void
       }
       const rows: SelectItem[] = [
         { value: "console", label: "Console", description: controlConfigured() ? "List, launch, attach, and drive Hosted Pi" : unavailable() },
-        { value: "status", label: "Link status", description: config !== null ? `${config.machine} → ${config.host}:${config.port}` : configHint },
+        { value: "status", label: "Link status", description: desks.length > 0 ? `${desks[0]?.machine ?? "machine"} → ${desks.map((desk) => `${desk.host}:${desk.port}`).join(", ")}${refusals.length > 0 ? ` · ${refusals[0]}` : ""}` : `${configHint}${refusals.length > 0 ? ` · ${refusals[0]}` : ""}` },
         { value: "attach", label: "Attach", description: controlConfigured() ? "Attach to a Hosted Pi" : unavailable() },
         { value: "launch", label: "Launch", description: controlConfigured() ? "Start a Hosted Pi" : unavailable() },
         { value: "cancel", label: "Cancel", description: attachment ? `Cancel ${attachment.sessionId}` : "Attach first" },

package/src/control-transport.ts

@@ -1,8 +1,8 @@
 import { connect, type Socket } from "node:net";
 import { StringDecoder } from "node:string_decoder";
-import type { DeskLinkConfig } from "./types.ts";
+import type { OdkLinkConfig } from "./types.ts";
 
-export const DESK_LINK_CONTROL_PROTOCOL = 2;
+export const ODK_LINK_CONTROL_PROTOCOL = 2;
 export const MAX_CONTROL_RECORD_BYTES = 1024 * 1024;
 
 export interface ControlTransport {
@@ -52,7 +52,7 @@ export function createControlRecordReader(maxBytes = MAX_CONTROL_RECORD_BYTES):
   };
 }
 
-export function createControlTcpTransport(config: DeskLinkConfig): ControlTransport {
+export function createControlTcpTransport(config: OdkLinkConfig): ControlTransport {
   const openHandlers: Array<() => void> = [];
   const closeHandlers: Array<(reason: string) => void> = [];
   const recordHandlers: Array<(record: unknown) => void> = [];

package/src/desk-set.ts

@@ -0,0 +1,69 @@
+import type { OdkLinkSnapshot } from "./reporter.ts";
+import type { OdkLinkConfig } from "./types.ts";
+
+/** A desk's own snapshot plus the endpoint it belongs to, so an aggregate can name it. */
+export interface DeskSnapshot extends OdkLinkSnapshot {
+  endpoint: string;
+}
+
+/**
+ * The desk the Console drives. Only a desk that issued a control credential can
+ * be driven, so that desk is chosen by default; an operator who names one gets
+ * that one, even when it has no credential, because quietly driving a different
+ * desk than the one asked for would be worse than saying a credential is needed.
+ */
+export function selectConsoleDesk(configs: OdkLinkConfig[], preferred = ""): OdkLinkConfig | null {
+  const wanted = preferred.trim();
+  if (wanted.length > 0) {
+    const exact = configs.find((config) => `${config.host}:${config.port}` === wanted
+      || `[${config.host}]:${config.port}` === wanted);
+    if (exact) return exact;
+    const matchingHosts = configs.filter((config) => config.host === wanted);
+    return matchingHosts.length === 1 ? matchingHosts[0]! : null;
+  }
+  return configs.find((config) => Boolean(config.controlToken)) ?? null;
+}
+
+/**
+ * One state for a machine that reports to several desks.
+ *
+ * `connected` is claimed only when every desk is connected, and `offline` only
+ * when every desk is offline, because a set that is half up is neither. Counts
+ * come from the desks that are up, so a desk that is down cannot make this
+ * machine look like it is reporting nothing.
+ */
+export function aggregateDeskSnapshots(snapshots: DeskSnapshot[]): OdkLinkSnapshot | null {
+  if (snapshots.length === 0) return null;
+  if (snapshots.length === 1) {
+    const only = snapshots[0];
+    if (only === undefined) return null;
+    const { endpoint: _endpoint, ...snapshot } = only;
+    return { ...snapshot, desks: [{ endpoint: only.endpoint, link: only.link, ...(only.lastError === undefined ? {} : { lastError: only.lastError }) }] };
+  }
+
+  const connected = snapshots.filter((snapshot) => snapshot.link === "connected");
+  const link: OdkLinkSnapshot["link"] = connected.length === snapshots.length
+    ? "connected"
+    : connected.length === 0 && snapshots.every((snapshot) => snapshot.link === "offline")
+      ? "offline"
+      : "connecting";
+
+  const reporting = connected.length > 0 ? connected : snapshots;
+  const total = (pick: (snapshot: DeskSnapshot) => number): number => reporting.reduce((sum, snapshot) => sum + pick(snapshot), 0);
+  const firstError = snapshots.find((snapshot) => snapshot.lastError !== undefined)?.lastError;
+
+  return {
+    link,
+    machine: snapshots[0]?.machine ?? "",
+    sessions: total((snapshot) => snapshot.sessions),
+    events: total((snapshot) => snapshot.events),
+    attempts: snapshots.reduce((most, snapshot) => Math.max(most, snapshot.attempts), 0),
+    omittedSessions: total((snapshot) => snapshot.omittedSessions),
+    ...(firstError === undefined ? {} : { lastError: firstError }),
+    desks: snapshots.map((snapshot) => ({
+      endpoint: snapshot.endpoint,
+      link: snapshot.link,
+      ...(snapshot.lastError === undefined ? {} : { lastError: snapshot.lastError }),
+    })),
+  };
+}

package/src/events.ts

@@ -1,3 +1,4 @@
+import { classifyToolActivity } from "@fradser/pi-kit";
 import {
   MAX_EVENT_TEXT,
   MAX_EVENTS_PER_SESSION,
@@ -24,6 +25,37 @@ export function boundEventText(value: unknown, max = MAX_EVENT_TEXT): string {
   return "";
 }
 
+/** How many lines a prompt or a content line may arrive with. */
+export const MAX_EVENT_LINES = 4;
+
+/**
+ * A prompt or a content line as the desk reads it: the lines the person wrote,
+ * up to a budget, then an ellipsis. Returning only the first non-empty line threw
+ * away everything pasted after it, which is the report the desk owner made: a card
+ * showed 提交。 for a message that carried much more. Blank lines separate rather
+ * than count, and each line is collapsed, so a wrapped paste does not arrive with
+ * a terminal's own line breaks in it.
+ */
+export function boundEventLines(value: unknown, maxLines = MAX_EVENT_LINES, max = MAX_EVENT_TEXT): string {
+  if (typeof value !== "string") return "";
+  const budget = Math.max(1, maxLines);
+  const lines: string[] = [];
+  let truncated = false;
+  for (const raw of value.split(/\r?\n/)) {
+    const line = raw.replace(/\s+/g, " ").trim();
+    if (line.length === 0) continue;
+    if (lines.length >= budget) {
+      truncated = true;
+      break;
+    }
+    lines.push(line);
+  }
+  if (lines.length === 0) return "";
+  const joined = lines.join("\n");
+  if (joined.length > max) return `${joined.slice(0, Math.max(1, max - 1))}…`;
+  return truncated ? `${joined}\n…` : joined;
+}
+
 /** The bound each kind's body is held to. */
 const BODY_BYTES: Record<SessionEvent["kind"], number> = {
   result: MAX_RESULT_BYTES,
@@ -33,6 +65,14 @@ const BODY_BYTES: Record<SessionEvent["kind"], number> = {
   tool: MAX_TOOL_BYTES,
 };
 
+const STOP_REASONS = new Set(["stop", "toolUse", "length", "error", "aborted"]);
+
+function assistantMetadata(entryId: unknown, stopReason: unknown): Pick<SessionEvent, "eventId" | "stopReason"> {
+  if (typeof entryId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(entryId)) return {};
+  return { eventId: entryId, ...(typeof stopReason === "string" && STOP_REASONS.has(stopReason)
+    ? { stopReason: stopReason as SessionEvent["stopReason"] } : {}) };
+}
+
 /**
  * Apply the body bound without flattening or prefixing its Markdown. Every kind
  * keeps its line structure so the desk can render it the way Pi does: a bash
@@ -58,6 +98,7 @@ export function boundSessionEvent(event: SessionEvent): SessionEvent | null {
   return {
     kind: event.kind,
     text,
+    ...(event.kind === "assistant" ? assistantMetadata(event.eventId, event.stopReason) : {}),
     ...(toolName ? { toolName } : {}),
     ...(toolCallId ? { toolCallId } : {}),
     ...(event.kind === "result" && event.isError === true ? { isError: true } : {}),
@@ -71,7 +112,8 @@ export function retainEvents(events: readonly SessionEvent[]): SessionEvent[] {
   let bytes = 0;
   for (let index = events.length - 1; index >= 0 && retained.length < MAX_EVENTS_PER_SESSION; index -= 1) {
     const event = events[index]!;
-    const size = Buffer.byteLength(event.text) + Buffer.byteLength(event.toolName ?? "");
+    const size = Buffer.byteLength(event.text) + Buffer.byteLength(event.toolName ?? "")
+      + Buffer.byteLength(event.eventId ?? "") + Buffer.byteLength(event.stopReason ?? "");
     if (bytes + size > MAX_SESSION_EVENT_BYTES) break;
     retained.push(event);
     bytes += size;
@@ -91,19 +133,18 @@ function readArguments(args: unknown): Record<string, unknown> {
   return typeof args === "object" && args !== null ? (args as Record<string, unknown>) : {};
 }
 
-/** The command, file, or query a tool call names, as Pi issued it. */
+/** The command, path, pattern, or query a tool call names, as Pi issued it. */
 export function summarizeToolCall(name: string, args: unknown): string {
-  const parsed = readArguments(args);
-  const asText = (value: unknown): string => (typeof value === "string" ? value.trim() : "");
-  const command = asText(parsed.command);
-  if (command) return `bash: ${command}`;
-  const file = asText(parsed.path);
-  if (file) return `${name}: ${file}`;
-  const query = asText(parsed.query);
-  if (query) return `search: ${query}`;
-  const subject = asText(parsed.subject);
-  if (subject) return `${name}: ${subject}`;
-  return name;
+  const activity = classifyToolActivity(readArguments(args));
+  if (!activity) return name;
+  switch (activity.kind) {
+    case "command": return `bash: ${activity.value}`;
+    case "search": return `search: ${activity.value}`;
+    // A delivery target names a recipient rather than work done, so the row
+    // falls back to the tool name.
+    case "target": return name;
+    default: return `${name}: ${activity.value}`;
+  }
 }
 
 function isText(part: unknown): part is TextPart {
@@ -123,6 +164,7 @@ interface MessageView {
   toolName?: string;
   toolCallId?: string;
   isError?: boolean;
+  stopReason?: unknown;
   content?: unknown;
 }
 
@@ -146,13 +188,13 @@ export function promptFromMessage(message: unknown): string {
  * The Session Events one finalized message contributes. A tool result joins
  * all text parts into one bounded Markdown body; other events stay summaries.
  */
-export function eventsFromMessage(message: unknown): SessionEvent[] {
+export function eventsFromMessage(message: unknown, persistedEntryId?: unknown): SessionEvent[] {
   const view = asMessage(message);
   if (!view) return [];
   // A user message may carry plain text rather than parts.
   if (typeof view.content === "string") {
-    const text = boundEventText(view.content);
-    return text.length > 0 && view.role === "user" ? [{ kind: "user", text }] : [];
+    const event = view.role === "user" ? boundSessionEvent({ kind: "user", text: view.content }) : null;
+    return event ? [event] : [];
   }
   const parts = Array.isArray(view.content) ? view.content : [];
   if (view.role === "toolResult") {
@@ -190,7 +232,8 @@ export function eventsFromMessage(message: unknown): SessionEvent[] {
   if (view.role === "assistant") {
     // One reply may stream as several text parts; Pi reads them as one body.
     const said = parts.filter((part): part is TextPart => isText(part) && part.text.trim().length > 0);
-    if (said.length > 0) events.push({ kind: "assistant", text: said.map((part) => part.text).join("\n\n") });
+    if (said.length > 0) events.push({ kind: "assistant", text: said.map((part) => part.text).join("\n\n"),
+      ...assistantMetadata(persistedEntryId, view.stopReason) });
   }
   return events;
 }