pim-agent 0.9.0 → 0.11.0

package/packages/core/src/session/SessionRegistry.ts

@@ -1,8 +1,13 @@
-import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import {
+  SessionManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
 import { stat } from "node:fs/promises";
 import { join } from "node:path";
 
 import { Directories } from "../shared/Directories";
+import { Pool } from "../shared/Pool";
+import type { Surface } from "../shared/Surface";
 import { AgentRuntime, type ModelChoice } from "./AgentRuntime";
 import { EventLog } from "./EventLog";
 import { SessionCache } from "./SessionCache";
@@ -11,6 +16,9 @@ import {
   type CustomToolContext,
   type HostSettings,
 } from "./SessionHost";
+import { SessionLease } from "./SessionLease";
+import { SessionName } from "./SessionName";
+import type { SessionUi } from "./SessionUi";
 
 /** A session as pi stores it: one JSONL file under a cwd-encoded directory. */
 export type SessionSummary = {
@@ -33,6 +41,8 @@ export type SessionRegistryDeps = {
   ) => readonly ToolDefinition[];
   /** Appended to every session's system prompt. */
   readonly systemInstruction?: () => Promise<string | undefined>;
+  /** Where this frontend's human is reading. */
+  readonly surface?: Surface;
 };
 
 export type SessionCreateOptions = {
@@ -41,11 +51,15 @@ export type SessionCreateOptions = {
   readonly like?: SessionHost;
 };
 
+/** A session tree is thousands of files and each header is one open; fanning out over all of them at once is how a listing runs the process out of descriptors. */
+const HEADER_READS = 32;
+
 /** Live sessions keyed on pi's session UUID; the catalogue is pi's sessions directory, read on demand. */
 export class SessionRegistry {
   private readonly deps: SessionRegistryDeps;
   private readonly runtime: AgentRuntime;
   private readonly hosts: SessionCache<SessionHost>;
+  private ui: ((host: SessionHost) => SessionUi | undefined) | undefined;
 
   public constructor(deps: SessionRegistryDeps) {
     this.deps = deps;
@@ -53,28 +67,37 @@ export class SessionRegistry {
     this.hosts = new SessionCache(deps.capacity);
   }
 
+  /**
+   * Where the extensions of every host built from here speak. It belongs to the
+   * registry rather than each caller because `create` binds an agent eagerly,
+   * and pi freezes a session's UI mode at that bind. Resolved per call: a
+   * host outlives the stream that speaks for it.
+   */
+  public setUi(ui: (host: SessionHost) => SessionUi | undefined): void {
+    this.ui = ui;
+  }
+
   public get sessionsRoot(): string {
     return join(this.runtime.agentDir, "sessions");
   }
 
+  public get agentDir(): string {
+    return this.runtime.agentDir;
+  }
+
   public async init(): Promise<void> {
     await this.runtime.init();
   }
 
   /** Sessions on disk, newest first; reads only each file's header line. */
   public async list(cwd?: string): Promise<readonly SessionSummary[]> {
-    const root = this.sessionsRoot;
-    if (!(await stat(root).catch(() => undefined))?.isDirectory()) {
-      return [];
-    }
-    const paths: string[] = [];
-    for await (const relative of new Bun.Glob("*/*.jsonl").scan({
-      cwd: root,
-      onlyFiles: true,
-    })) {
-      paths.push(join(root, relative));
-    }
-    const summaries = (await Promise.all(paths.map(readSummary))).filter(
+    const summaries = (
+      await Pool.mapPooled(
+        await this.paths("*/*.jsonl"),
+        HEADER_READS,
+        readSummary
+      )
+    ).filter(
       (summary): summary is SessionSummary =>
         summary !== undefined && (cwd === undefined || summary.cwd === cwd)
     );
@@ -86,6 +109,38 @@ export class SessionRegistry {
     return this.hosts.peek(sessionId);
   }
 
+  /**
+   * Rename a session through pi's own session name, so its `/resume` picker shows
+   * it too; `null` clears it. A live session is renamed by its agent, a closed one
+   * by appending to its file under the turn lease. Answers with the name pi kept.
+   */
+  public async setName(
+    sessionId: string,
+    name: string | null
+  ): Promise<string | undefined> {
+    const host = this.peek(sessionId);
+    if (host?.agentSession) {
+      return await host.setName(name);
+    }
+    const summary = await this.find(sessionId);
+    if (summary === undefined) {
+      throw new Error(`unknown session: ${sessionId}`);
+    }
+    const next = SessionName.normalise(name);
+    // Reopening is a plain read today, but a pi that migrates the file rewrites it.
+    // The lease is only ever held for a whole turn, so a rename refuses rather than queues.
+    return await SessionLease.hold(
+      summary.path,
+      "daemon",
+      async () => {
+        const manager = SessionManager.open(summary.path);
+        manager.appendSessionInfo(next);
+        return manager.getSessionName();
+      },
+      { timeoutMs: 0 }
+    );
+  }
+
   /** Every model this machine has credentials for, qualified as `SessionHost.setModel` takes them. */
   public models(): readonly ModelChoice[] {
     return this.runtime.models();
@@ -96,7 +151,7 @@ export class SessionRegistry {
     if (cached) {
       return cached;
     }
-    const summary = (await this.list()).find((s) => s.sessionId === sessionId);
+    const summary = await this.find(sessionId);
     if (!summary) {
       throw new Error(`unknown session: ${sessionId}`);
     }
@@ -134,8 +189,44 @@ export class SessionRegistry {
     await this.hosts.disposeAll();
   }
 
+  /**
+   * One session by id. Pi names a file for the id it carries, so the usual
+   * answer is one glob and one header; resolving it by listing would read the
+   * header of every session on disk to throw all but one away.
+   */
+  private async find(sessionId: string): Promise<SessionSummary | undefined> {
+    for (const path of await this.paths(`*/*${sessionId}.jsonl`)) {
+      const summary = await readSummary(path);
+      if (summary?.sessionId === sessionId) {
+        return summary;
+      }
+    }
+    // A file named something else entirely: the id is the header's, not the name's.
+    return (await this.list()).find(
+      (summary) => summary.sessionId === sessionId
+    );
+  }
+
+  private async paths(pattern: string): Promise<readonly string[]> {
+    const root = this.sessionsRoot;
+    if (!(await stat(root).catch(() => undefined))?.isDirectory()) {
+      return [];
+    }
+    const found: string[] = [];
+    for await (const relative of new Bun.Glob(pattern).scan({
+      cwd: root,
+      onlyFiles: true,
+    })) {
+      found.push(join(root, relative));
+    }
+    return found;
+  }
+
   private buildHost(label: string, settings: HostSettings): SessionHost {
-    return new SessionHost({
+    const ui = this.ui;
+    // Named so the sink can reach back for the host it belongs to; the closure
+    // only ever runs once construction has returned.
+    const host: SessionHost = new SessionHost({
       label: `session ${label}`,
       settings,
       defaults: this.deps.defaults,
@@ -150,7 +241,12 @@ export class SessionRegistry {
       ...(this.deps.systemInstruction === undefined
         ? {}
         : { systemInstruction: this.deps.systemInstruction }),
+      ...(this.deps.surface === undefined
+        ? {}
+        : { surface: this.deps.surface }),
+      ...(ui === undefined ? {} : { ui: () => ui(host) }),
     });
+    return host;
   }
 }
 

package/packages/core/src/session/SessionUi.ts

@@ -0,0 +1,127 @@
+import type {
+  ExtensionUIContext,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+
+import type { NoticeSeverity } from "../view/ViewBlock";
+
+/** The slice of pi's dialog options a surface without a terminal can honour; the rest is countdown chrome. */
+export type UiAsk = {
+  readonly timeout?: number;
+  readonly signal?: AbortSignal;
+};
+
+/** Where an extension's own words go. Four of pi's thirty methods: the ones that address a human rather than a terminal. */
+export type SessionUi = {
+  readonly notify: (text: string, severity: NoticeSeverity) => void;
+  readonly select: (
+    title: string,
+    options: readonly string[],
+    opts?: UiAsk
+  ) => Promise<string | undefined>;
+  readonly confirm: (
+    title: string,
+    message: string,
+    opts?: UiAsk
+  ) => Promise<boolean>;
+  readonly input: (
+    title: string,
+    placeholder?: string,
+    opts?: UiAsk
+  ) => Promise<string | undefined>;
+};
+
+/** Everything off the terminal paints with; also what pi's border getters hand back. */
+const IDENTITY = (text: string): string => text;
+
+/**
+ * pi keeps its own `theme` instance to itself, and nothing off the terminal has
+ * colours to paint with. `satisfies` covers the whole public surface — `keyof`
+ * skips the private fields the cast is for — so a method pi adds is a type
+ * error here rather than a throw inside somebody's event handler.
+ */
+const PLAIN_THEME = {
+  fg: (_color: string, text: string) => text,
+  bg: (_color: string, text: string) => text,
+  bold: IDENTITY,
+  italic: IDENTITY,
+  underline: IDENTITY,
+  inverse: IDENTITY,
+  strikethrough: IDENTITY,
+  getFgAnsi: () => "",
+  getBgAnsi: () => "",
+  getColorMode: () => "truecolor",
+  getThinkingBorderColor: () => IDENTITY,
+  getBashModeBorderColor: () => IDENTITY,
+} satisfies { [K in keyof Theme]: Theme[K] } as unknown as Theme;
+
+function severityOf(
+  kind: Parameters<ExtensionUIContext["notify"]>[1]
+): NoticeSeverity {
+  return kind === "warning" ? "warn" : (kind ?? "info");
+}
+
+/** A dialog an extension awaits goes unanswered rather than ever throwing at it. */
+async function settle<T>(
+  ask: () => Promise<T> | undefined
+): Promise<T | undefined> {
+  try {
+    return await ask();
+  } catch (err) {
+    console.warn("[SessionUi] dialog sink failed:", err);
+    return undefined;
+  }
+}
+
+/**
+ * Widens the sink onto pi's `ExtensionUIContext`, no-opping everything a
+ * terminal owns exactly as pi's own RPC mode does. `sink` is read per call, so
+ * an agent rebuilt under a host keeps whatever its host was last handed.
+ *
+ * Every method has to be an *own* property: pi re-wraps what it is given with
+ * `{ ...ui }` (`runner.js:274`), which copies own enumerable keys only. A class
+ * instance would arrive with `notify` and the rest of the prototype missing.
+ */
+export function adaptSessionUi(
+  sink: () => SessionUi | undefined
+): ExtensionUIContext {
+  return {
+    select: (title, options, opts) =>
+      settle(() => sink()?.select(title, options, opts)),
+    confirm: async (title, message, opts) =>
+      (await settle(() => sink()?.confirm(title, message, opts))) === true,
+    input: (title, placeholder, opts) =>
+      settle(() => sink()?.input(title, placeholder, opts)),
+    notify: (message, kind) => {
+      try {
+        sink()?.notify(message, severityOf(kind));
+      } catch (err) {
+        console.warn("[SessionUi] notify sink failed:", err);
+      }
+    },
+    onTerminalInput: () => () => {},
+    setStatus: () => {},
+    setWorkingMessage: () => {},
+    setWorkingVisible: () => {},
+    setWorkingIndicator: () => {},
+    setHiddenThinkingLabel: () => {},
+    setWidget: () => {},
+    setFooter: () => {},
+    setHeader: () => {},
+    setTitle: () => {},
+    custom: async <T>() => undefined as T,
+    pasteToEditor: () => {},
+    setEditorText: () => {},
+    getEditorText: () => "",
+    editor: async () => undefined,
+    addAutocompleteProvider: () => {},
+    setEditorComponent: () => {},
+    getEditorComponent: () => undefined,
+    theme: PLAIN_THEME,
+    getAllThemes: () => [],
+    getTheme: () => undefined,
+    setTheme: () => ({ success: false, error: "UI not available" }),
+    getToolsExpanded: () => false,
+    setToolsExpanded: () => {},
+  };
+}

package/packages/core/src/session/WriteMark.ts

@@ -33,5 +33,19 @@ function foreignSince(mark: WriteMark, next: WriteMark): boolean {
   return next.head - base.head - (next.entries - base.entries) > 0;
 }
 
+/**
+ * Whether every line the file gained since `mark` is one no reader has to replay.
+ * A rename appends `session_info` and moves no history, so a surface that absorbs
+ * it stays on the session it is already holding. Only ask between turns: a window
+ * that also holds our own appends is not benign, and a running turn's is.
+ */
+async function benignSince(log: EventLog, mark: WriteMark): Promise<boolean> {
+  const added = await log.read(mark.head);
+  return (
+    added.length > 0 &&
+    added.every(({ entry }) => entry.type === "session_info")
+  );
+}
+
 /** Write accounting over one session file: whose lines are these? */
-export const WriteMark = { UNREAD, of, foreignSince };
+export const WriteMark = { UNREAD, of, foreignSince, benignSince };

package/packages/core/src/shared/DiffLines.ts

@@ -301,4 +301,4 @@ function partLines(value: string): readonly string[] {
 
 const emptySide: ToolDiffSide = { lines: [], hasTrailingNewline: false };
 
-export const DiffLines = { buildToolDiff, fromText, emptySide };
+export const DiffLines = { buildToolDiff, fromText, emptySide, attachEmphasis };

package/packages/core/src/shared/DiffPatch.ts

@@ -0,0 +1,70 @@
+import * as Diff from "diff";
+import {
+  DiffLines,
+  type ToolDiff,
+  type ToolDiffHunk,
+  type ToolDiffLine,
+  type ToolDiffLineKind,
+} from "./DiffLines";
+
+function fromUnified(path: string, patch: string): ToolDiff | undefined {
+  const hunks = Diff.parsePatch(patch)
+    .flatMap((file) => file.hunks)
+    .map(toHunk)
+    .filter((hunk) => hunk.lines.length > 0);
+
+  return hunks.length === 0 ? undefined : { path, hunks };
+}
+
+function toHunk(hunk: Diff.StructuredPatchHunk): ToolDiffHunk {
+  const lines: ToolDiffLine[] = [];
+  let oldLine = hunk.oldStart;
+  let newLine = hunk.newStart;
+
+  for (const raw of hunk.lines) {
+    if (raw.startsWith("\\")) {
+      continue;
+    }
+
+    const kind = kindOf(raw);
+    const text = raw.slice(1);
+
+    if (kind === "added") {
+      lines.push({ kind, newLine, text });
+      newLine += 1;
+      continue;
+    }
+
+    if (kind === "removed") {
+      lines.push({ kind, oldLine, text });
+      oldLine += 1;
+      continue;
+    }
+
+    lines.push({ kind, oldLine, newLine, text });
+    oldLine += 1;
+    newLine += 1;
+  }
+
+  return {
+    oldStart: hunk.oldStart,
+    oldLines: hunk.oldLines,
+    newStart: hunk.newStart,
+    newLines: hunk.newLines,
+    lines: DiffLines.attachEmphasis(lines),
+  };
+}
+
+function kindOf(line: string): ToolDiffLineKind {
+  if (line.startsWith("+")) {
+    return "added";
+  }
+
+  if (line.startsWith("-")) {
+    return "removed";
+  }
+
+  return "context";
+}
+
+export const DiffPatch = { fromUnified };

package/packages/core/src/shared/DiffRenderer.ts

@@ -95,7 +95,7 @@ function highlightHunkLines(
   hunk: ToolDiffHunk,
   highlighter: DiffHighlighter
 ): readonly string[] {
-  const highlighted = DiffLayout.mapSides(hunk, highlighter);
+  const highlighted = DiffLayout.mapSides(hunk.lines, highlighter);
   return hunk.lines.map((line, index) => highlighted[index] ?? line.text);
 }
 

package/packages/core/src/shared/Directories.ts

@@ -1,5 +1,5 @@
-import { readdir, stat } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { mkdir, readdir, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 
 import { FsErrors } from "./FsErrors";
 import { Paths } from "./Paths";
@@ -29,12 +29,16 @@ async function check(path: string): Promise<string | undefined> {
   }
 }
 
-async function list(path: string): Promise<DirectoryListing> {
+function rooted(path: string): string {
   const expanded = Paths.expandHome(path);
   if (!isAbsolute(expanded)) {
     throw new Error(`not an absolute path: ${path}`);
   }
-  const resolved = resolve(expanded);
+  return resolve(expanded);
+}
+
+async function list(path: string): Promise<DirectoryListing> {
+  const resolved = rooted(path);
   const reason = await check(resolved);
   if (reason !== undefined) {
     throw new Error(reason);
@@ -58,4 +62,34 @@ async function list(path: string): Promise<DirectoryListing> {
   };
 }
 
-export const Directories = { check, list };
+function refusal(error: unknown, path: string): string {
+  switch (FsErrors.code(error)) {
+    case "ENOENT":
+      return `path does not exist: ${dirname(path)}`;
+    case "EEXIST":
+      return `already exists: ${path}`;
+    case "ENOTDIR":
+      return `not a directory: ${dirname(path)}`;
+    case "EACCES":
+    case "EPERM":
+      return `permission denied: ${path}`;
+    default:
+      return `mkdir failed: ${(error as Error).message}`;
+  }
+}
+
+/** Makes one directory inside an existing one. Never recursive: a parent that is missing is said so, not invented. */
+async function create(path: string): Promise<void> {
+  const name = basename(Paths.expandHome(path));
+  if (name === "" || name === "." || name === "..") {
+    throw new Error(`not a directory to create: ${path}`);
+  }
+  const resolved = rooted(path);
+  try {
+    await mkdir(resolved);
+  } catch (error) {
+    throw new Error(refusal(error, resolved));
+  }
+}
+
+export const Directories = { check, list, create };

package/packages/core/src/shared/ExtensionToggles.ts

@@ -34,6 +34,13 @@ const DEFAULT_DISABLED: readonly PimExtensionName[] = ["todo", "tps"];
 
 const REQUIRED: readonly PimExtensionName[] = ["_init", "pim", "session-lease"];
 
+// Hardcoded, never derived: the browser switches these and nothing else, under
+// the label it gives them — the terminal menu names them by key, this does not.
+const WEB = [{ name: "todo", label: "Todo Tool" }] as const satisfies readonly {
+  name: PimExtensionName;
+  label: string;
+}[];
+
 function isRequired(name: string): boolean {
   return (REQUIRED as readonly string[]).includes(name);
 }
@@ -119,6 +126,7 @@ function enabled(
 export const ExtensionToggles = {
   REQUIRED,
   NAMES,
+  WEB,
   isRequired,
   isKnown,
   describe,

package/packages/core/src/shared/FileWatch.ts

@@ -8,6 +8,12 @@ import { basename, dirname, join } from "node:path";
 
 const POLL_MS = 1_000;
 
+/**
+ * A burst coalesces into one event, and the read it triggers can land inside
+ * the burst — so look once more after it, or the last write waits on the poll.
+ */
+const SETTLE_MS = 25;
+
 function signatureOf(path: string): string {
   const stats = statSync(path, { throwIfNoEntry: false });
   return stats === undefined
@@ -41,6 +47,13 @@ function follow(
   pollMs: number
 ): () => void {
   let watcher: FSWatcher | undefined;
+  let settle: ReturnType<typeof setTimeout> | undefined;
+  const fire = (): void => {
+    onEvent();
+    clearTimeout(settle);
+    settle = setTimeout(onEvent, SETTLE_MS);
+    settle.unref?.();
+  };
   const arm = (): void => {
     if (watcher !== undefined) {
       return;
@@ -48,7 +61,7 @@ function follow(
     try {
       watcher = watchFs(watched, { persistent: false }, (_event, changed) => {
         if (entry === undefined || changed === null || changed === entry) {
-          onEvent();
+          fire();
         }
       });
       watcher.on("error", () => {
@@ -66,6 +79,7 @@ function follow(
   timer.unref?.();
   return (): void => {
     clearInterval(timer);
+    clearTimeout(settle);
     try {
       watcher?.close();
     } catch {}