pim-agent 0.9.0 → 0.11.0

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

@@ -0,0 +1,97 @@
+/** One indexable word and where it sits in the string it came from. */
+export type SearchToken = {
+  /** Lowercased: the corpus itself is never lowered, only its tokens. */
+  readonly text: string;
+  readonly start: number;
+  readonly end: number;
+};
+
+const RUN = /[\p{L}\p{N}_]+/gu;
+
+function scan(text: string): readonly SearchToken[] {
+  const tokens: SearchToken[] = [];
+  for (const run of text.matchAll(RUN)) {
+    const at = run.index;
+    const word = run[0];
+    const pieces = piecesOf(word);
+    for (const [from, to] of pieces) {
+      tokens.push({
+        text: word.slice(from, to).toLowerCase(),
+        start: at + from,
+        end: at + to,
+      });
+    }
+    if (pieces.length > 1) {
+      tokens.push({
+        text: word.toLowerCase(),
+        start: at,
+        end: at + word.length,
+      });
+    }
+  }
+  return tokens;
+}
+
+/**
+ * The words a query asks for: its pieces alone, never the identifier they
+ * spell. `SessionLease` asks for `session` and `lease`, which the index holds
+ * for `SessionLease` and for `session lease` alike; asking for `sessionlease`
+ * too would AND away the second.
+ */
+function words(query: string): readonly string[] {
+  const found: string[] = [];
+  for (const run of query.matchAll(RUN)) {
+    for (const [from, to] of piecesOf(run[0])) {
+      const word = run[0].slice(from, to).toLowerCase();
+      if (!found.includes(word)) {
+        found.push(word);
+      }
+    }
+  }
+  return found;
+}
+
+/** Half-open slices of one run: `WsGateway` is `ws` and `gateway`, `read_file` is `read` and `file`. */
+function piecesOf(run: string): readonly (readonly [number, number])[] {
+  const pieces: (readonly [number, number])[] = [];
+  let start = -1;
+  for (let at = 0; at < run.length; at++) {
+    if (run[at] === "_") {
+      if (start >= 0) {
+        pieces.push([start, at]);
+        start = -1;
+      }
+      continue;
+    }
+    if (start < 0) {
+      start = at;
+    } else if (breaksAt(run, at)) {
+      pieces.push([start, at]);
+      start = at;
+    }
+  }
+  if (start >= 0) {
+    pieces.push([start, run.length]);
+  }
+  return pieces;
+}
+
+function breaksAt(run: string, at: number): boolean {
+  const here = run[at]!;
+  if (!isUpper(here)) {
+    return false;
+  }
+  const before = run[at - 1]!;
+  const after = run[at + 1];
+  return !isUpper(before) || (after !== undefined && isLower(after));
+}
+
+function isUpper(char: string): boolean {
+  return char !== char.toLowerCase() && char === char.toUpperCase();
+}
+
+function isLower(char: string): boolean {
+  return char !== char.toUpperCase() && char === char.toLowerCase();
+}
+
+export const SearchTokens = { scan, words };

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

@@ -0,0 +1,161 @@
+import { parseSessionEntries } from "@earendil-works/pi-coding-agent";
+
+import { Attachments } from "../attachments/Attachments";
+import { MessageText } from "./MessageText";
+
+/** What the session catalogue shows for one file without opening a session. */
+export type SessionDigest = {
+  /** The session's name if it has one, else its first user message; absent when it has neither. */
+  readonly title?: string;
+  /** True when `title` is a name somebody wrote rather than the opening message. */
+  readonly named?: true;
+  /** When the agent last wrote; it moves with an in-flight turn, so read it before starting one. */
+  readonly settledAt?: number;
+};
+
+/**
+ * The digest before it is clamped, so a reader that tails an appended region
+ * can fold that region into what an earlier read of the same file found.
+ */
+export type DigestParts = {
+  readonly name?: string;
+  /** The opening ask, unclamped. */
+  readonly opening?: string;
+  readonly settledAt?: number;
+};
+
+/**
+ * A session file's durable bytes, undecoded: a whole session is megabytes of
+ * tool output and the digest wants a handful of lines of it, so the search
+ * runs over the bytes and only the lines it keeps become strings.
+ */
+export type Durable = {
+  readonly bytes: Buffer;
+  /** Past the last newline; a trailing fragment is a write in progress and is not a line. */
+  readonly end: number;
+};
+
+const PROBE_LINES = 16;
+
+const TAIL_LINES = 10;
+
+const TITLE_LIMIT = 120;
+
+/** Cheap reject before decoding a line: pi writes the discriminant verbatim. */
+const NAMED = Buffer.from('"session_info"');
+
+export const NEWLINE = 0x0a;
+
+function durable(read: Uint8Array): Durable | undefined {
+  const bytes = Buffer.from(read.buffer, read.byteOffset, read.byteLength);
+  const end = bytes.lastIndexOf(NEWLINE) + 1;
+  return end === 0 ? undefined : { bytes, end };
+}
+
+function partsOf(body: Durable): DigestParts {
+  return {
+    name: nameOf(body),
+    opening: firstUserMessage(headLinesOf(body, PROBE_LINES)),
+    settledAt: lastAgentTime(tailLinesOf(body, TAIL_LINES).reverse()),
+  };
+}
+
+/** An append only adds, so the opening ask stands and a later name or agent line wins. */
+function merge(before: DigestParts, appended: DigestParts): DigestParts {
+  return {
+    name: appended.name ?? before.name,
+    opening: before.opening ?? appended.opening,
+    settledAt: appended.settledAt ?? before.settledAt,
+  };
+}
+
+function of({ name, opening, settledAt }: DigestParts): SessionDigest {
+  const title = name ?? opening;
+  return {
+    ...(title === undefined ? {} : { title: clamp(title) }),
+    ...(name === undefined ? {} : { named: true as const }),
+    ...(settledAt === undefined ? {} : { settledAt }),
+  };
+}
+
+/** The last `session_info` line, found by walking the marker's occurrences backwards; a line that merely quotes the marker parses as something else, and the walk carries on past it. */
+function nameOf({ bytes, end }: Durable): string | undefined {
+  let at = end - 1;
+  while (at >= 0) {
+    const found = bytes.lastIndexOf(NAMED, at);
+    if (found === -1) {
+      return undefined;
+    }
+    const from = bytes.lastIndexOf(NEWLINE, found) + 1;
+    const to = bytes.indexOf(NEWLINE, found);
+    const entry = parseSessionEntries(bytes.toString("utf8", from, to))[0];
+    if (entry?.type === "session_info") {
+      return entry.name?.trim() || undefined;
+    }
+    at = from - 1;
+  }
+  return undefined;
+}
+
+function headLinesOf({ bytes, end }: Durable, count: number): string[] {
+  let at = 0;
+  for (let taken = 0; taken < count && at < end; taken++) {
+    at = bytes.indexOf(NEWLINE, at) + 1;
+  }
+  return split(bytes.toString("utf8", 0, at));
+}
+
+function tailLinesOf({ bytes, end }: Durable, count: number): string[] {
+  let at = end - 1;
+  for (let taken = 0; taken < count && at > 0; taken++) {
+    at = bytes.lastIndexOf(NEWLINE, at - 1);
+  }
+  return split(bytes.toString("utf8", at + 1, end));
+}
+
+function split(text: string): string[] {
+  const lines = text.split("\n");
+  lines.pop();
+  return lines;
+}
+
+function lastAgentTime(lines: readonly string[]): number | undefined {
+  for (const line of lines) {
+    const entry = parseSessionEntries(line)[0];
+    if (entry?.type !== "message") {
+      continue;
+    }
+    const role = entry.message.role;
+    if (role === "assistant" || role === "toolResult") {
+      const at = Date.parse(entry.timestamp);
+      return Number.isNaN(at) ? undefined : at;
+    }
+  }
+  return undefined;
+}
+
+function clamp(text: string): string {
+  return text.length > TITLE_LIMIT
+    ? `${text.slice(0, TITLE_LIMIT).trimEnd()}…`
+    : text;
+}
+
+/** Over the head window the caller has already cut, not the whole file. */
+function firstUserMessage(lines: readonly string[]): string | undefined {
+  for (const line of lines) {
+    const entry = parseSessionEntries(line)[0];
+    if (entry?.type !== "message" || entry.message.role !== "user") {
+      continue;
+    }
+    const said = Attachments.parse(MessageText.textOf(entry.message.content));
+    const text =
+      said.text.trim() ||
+      said.files.map((file) => Attachments.nameOf(file.path)).join(", ");
+    if (text !== "") {
+      return text;
+    }
+  }
+  return undefined;
+}
+
+export const SessionDigest = { durable, partsOf, merge, of, nameOf };

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

@@ -15,6 +15,7 @@ import {
   SettingsManager,
   type AgentSessionEvent,
   type CompactionResult,
+  type ExtensionError,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { unlink } from "node:fs/promises";
@@ -22,12 +23,15 @@ import { unlink } from "node:fs/promises";
 import { CoreExtensions } from "../extensions/CoreExtensions";
 import { Directories } from "../shared/Directories";
 import { FuzzyMatcher, type FuzzyCandidate } from "../shared/FuzzyMatcher";
+import type { Surface } from "../shared/Surface";
 import { EventLog } from "./EventLog";
 import {
   SessionLease,
   type LeaseFrontend,
   type LeaseRecord,
 } from "./SessionLease";
+import { SessionName } from "./SessionName";
+import { adaptSessionUi, type SessionUi } from "./SessionUi";
 import { WriteMark } from "./WriteMark";
 
 /** What the agent is doing right now. */
@@ -93,11 +97,20 @@ export type SessionHostDeps = {
   readonly mainSessionPath?: () => string;
   readonly isolatedSessionPath?: () => string;
   readonly systemInstruction?: () => Promise<string | undefined>;
+  /** Where this host's human is reading; surfaces in the system prompt's environment block. */
+  readonly surface?: Surface;
   readonly customTools?: (
     context: CustomToolContext
   ) => readonly ToolDefinition[];
   /** Runs after the agent is disposed, before the session file is forgotten. */
   readonly onRetire?: (sessionPath: string) => Promise<void>;
+  /**
+   * Where this host's extensions say things, resolved per call so an agent
+   * rebuilt under the host follows its live target. Omit to leave pi's no-op
+   * UI in place: pi freezes the mode at `bindExtensions`, so this is a dep
+   * rather than something a caller can turn on once a session exists.
+   */
+  readonly ui?: () => SessionUi | undefined;
 };
 
 /** What a frontend's own tools are built against. */
@@ -399,6 +412,18 @@ export class SessionHost {
     });
   }
 
+  /**
+   * Rename this session through pi's own session name, so its `/resume` picker
+   * shows it too; `null` clears it. Answers with the name pi kept.
+   */
+  public setName(name: string | null): Promise<string | undefined> {
+    return this.withLease(async () => {
+      const agent = await this.ensureCached();
+      agent.setSessionName(SessionName.normalise(name));
+      return agent.sessionManager.getSessionName();
+    });
+  }
+
   public compact(customInstructions?: string): Promise<SessionCompactResult> {
     return this.withLease(async (): Promise<SessionCompactResult> => {
       const agent = await this.ensureCached();
@@ -716,7 +741,7 @@ export class SessionHost {
       agentDir: this.deps.agentDir,
       settingsManager,
       // Load core tools in-process: a disk-loaded copy registers views into a second `Tools`.
-      extensionFactories: CoreExtensions.gated(),
+      extensionFactories: CoreExtensions.gated(this.deps.surface),
       appendSystemPromptOverride: (base) => {
         return promptRef.wrapped ? [...base, promptRef.wrapped] : base;
       },
@@ -754,16 +779,33 @@ export class SessionHost {
       ],
     });
 
-    // Emits session_start; without it extension tools are registered but never usable.
-    await agent.bindExtensions({
-      mode: "print",
-      onError: (err) => {
-        console.warn(
-          `[${this.label}] extension ${err.extensionPath} (${err.event}):`,
-          err.error
+    const onError = (err: ExtensionError) => {
+      console.warn(
+        `[${this.label}] extension ${err.extensionPath} (${err.event}):`,
+        err.error
+      );
+      // Pi answers a command handler that threw as if it had succeeded, so
+      // without this the user's message vanishes and only stderr says why.
+      this.deps
+        .ui?.()
+        ?.notify(
+          `${err.extensionPath} (${err.event}) failed: ${err.error}`,
+          "error"
         );
-      },
-    });
+    };
+    const ui = this.deps.ui;
+    // Emits session_start; without it extension tools are registered but never usable.
+    await agent.bindExtensions(
+      ui
+        ? // Any context at all makes pi's `hasUI()` true (`uiContext !== noOpUIContext`,
+          // runner.js:318); "rpc" is its own name for dialog-capable but not a terminal.
+          {
+            uiContext: adaptSessionUi(ui),
+            mode: "rpc",
+            onError,
+          }
+        : { mode: "print", onError }
+    );
 
     return { agent, cwd };
   }

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

@@ -0,0 +1,267 @@
+import { join } from "node:path";
+
+import { Fs } from "../shared/Fs";
+import { Json } from "../shared/Json";
+import { Paths } from "../shared/Paths";
+
+export type SessionEntry = {
+  readonly archived?: boolean;
+  /** Sticky: set by hand, and only a read clears it. */
+  readonly unread?: boolean;
+};
+
+export type ProjectEntry = {
+  readonly pinned?: boolean;
+  /** The sidebar group stands unfolded; absent is folded, which is where a project starts. */
+  readonly expanded?: boolean;
+  /** What to call the directory instead of its base name; the directory itself is never touched. */
+  readonly label?: string;
+};
+
+/** The pin flags and the order they are shown in, from one read of the file. */
+export type Pinning = {
+  /** Keyed by absolute cwd. */
+  readonly projects: ReadonlyMap<string, ProjectEntry>;
+  /** The pinned directories, in the order they are shown. */
+  readonly order: readonly string[];
+};
+
+type Stored = {
+  readonly version: 1;
+  readonly sessions: Record<string, SessionEntry>;
+  readonly projects: Record<string, ProjectEntry>;
+  /**
+   * Where the pinned directories sort, and only that: `projects` stays the
+   * truth of whether one is pinned. An entry here that is not pinned is
+   * ignored and a pin it has never heard of still sorts, so a file written by
+   * a pim that predates the order — or by one that does not write it — needs
+   * no migration.
+   */
+  readonly pins: readonly string[];
+};
+
+type Loaded = {
+  readonly sessions: Map<string, SessionEntry>;
+  readonly projects: Map<string, ProjectEntry>;
+  pins: string[];
+};
+
+const NONE: SessionEntry = {};
+
+/** Per-session and per-project overrides, shared by every surface on a machine. */
+export class SessionMeta {
+  private readonly file: string;
+  private readonly writes = Fs.serialised();
+
+  /** Defaults to `~/.pim/sessions.json`. */
+  public constructor(path?: string) {
+    this.file = path ?? join(Paths.pimHomeDir(), "sessions.json");
+  }
+
+  public async of(sessionId: string): Promise<SessionEntry> {
+    return (await this.sessions()).get(sessionId) ?? NONE;
+  }
+
+  /** One read for a whole listing; `of` per row is one read per row. */
+  public async sessions(): Promise<ReadonlyMap<string, SessionEntry>> {
+    return (await this.read()).sessions;
+  }
+
+  /** The pinned directories in display order; a listing wants both halves, and this is one read for them. */
+  public async pinning(): Promise<Pinning> {
+    const loaded = await this.read();
+    return { projects: loaded.projects, order: ordered(loaded) };
+  }
+
+  /** The pinned directories in display order. */
+  public async pins(): Promise<readonly string[]> {
+    return ordered(await this.read());
+  }
+
+  public setArchived(sessionId: string, archived: boolean): Promise<void> {
+    return this.mutate((loaded) =>
+      put(loaded.sessions, sessionId, { archived })
+    );
+  }
+
+  public setUnread(sessionId: string, unread: boolean): Promise<void> {
+    return this.mutate((loaded) => put(loaded.sessions, sessionId, { unread }));
+  }
+
+  /** A new pin goes to the top, where you have just put it; an old one leaves the order with the flag. */
+  public setPinned(cwd: string, pinned: boolean): Promise<void> {
+    return this.mutate((loaded) => {
+      const at = loaded.pins.indexOf(cwd);
+      if (at !== -1) {
+        loaded.pins.splice(at, 1);
+      }
+      if (pinned) {
+        loaded.pins.unshift(cwd);
+      }
+      return put(loaded.projects, cwd, { pinned });
+    });
+  }
+
+  /**
+   * Folds a project's group, or unfolds it. Kept beside the pin rather than
+   * in the browser, so the fold a phone made is the fold a desktop opens to.
+   */
+  public setExpanded(cwd: string, expanded: boolean): Promise<void> {
+    return this.mutate((loaded) => put(loaded.projects, cwd, { expanded }));
+  }
+
+  /** Names the project for the sidebar; `null` puts it back to its base name. */
+  public setLabel(cwd: string, label: string | null): Promise<void> {
+    return this.mutate((loaded) =>
+      put(loaded.projects, cwd, { label: label ?? "" })
+    );
+  }
+
+  /** Takes the whole order rather than a move, so two surfaces settle on the last one written. */
+  public setPinOrder(order: readonly string[]): Promise<void> {
+    return this.mutate((loaded) => {
+      loaded.pins = [...new Set(order)].filter(
+        (cwd) => loaded.projects.get(cwd)?.pinned === true
+      );
+      return true;
+    });
+  }
+
+  /** Drops the sessions that are gone; a pin outlives every session of its project. */
+  public prune(alive: ReadonlySet<string>): Promise<void> {
+    return this.mutate((loaded) => {
+      let dropped = false;
+      for (const sessionId of loaded.sessions.keys()) {
+        if (!alive.has(sessionId)) {
+          loaded.sessions.delete(sessionId);
+          dropped = true;
+        }
+      }
+      return dropped;
+    });
+  }
+
+  /** Settles the writes taken so far, for a clean stop. */
+  public async flush(): Promise<void> {
+    await this.writes.run(async () => undefined);
+  }
+
+  private async read(): Promise<Loaded> {
+    const raw = Json.asRecord(
+      await Fs.readJsonOr<unknown>(this.file, undefined)
+    );
+    if (raw?.version !== 1) {
+      return { sessions: new Map(), projects: new Map(), pins: [] };
+    }
+    return {
+      sessions: parseAll(raw.sessions, parseSession),
+      projects: parseAll(raw.projects, parseProject),
+      pins: Array.isArray(raw.pins)
+        ? raw.pins.filter((cwd) => typeof cwd === "string")
+        : [],
+    };
+  }
+
+  /** Re-reads under the lock, so a write by another process survives this one. */
+  private async mutate(update: (loaded: Loaded) => boolean): Promise<void> {
+    await this.writes.run(async () => {
+      const loaded = await this.read();
+      if (!update(loaded)) {
+        return;
+      }
+      await Paths.ensurePimHome();
+      await Fs.writeJson(this.file, {
+        version: 1,
+        sessions: Object.fromEntries(loaded.sessions),
+        projects: Object.fromEntries(loaded.projects),
+        pins: loaded.pins,
+      } satisfies Stored);
+    });
+  }
+}
+
+/**
+ * The pinned directories in display order: the ones the stored order names,
+ * then any pin it has not heard of, by path. A duplicate in the order is
+ * taken once, at the first place it appears.
+ */
+function ordered({ projects, pins }: Loaded): readonly string[] {
+  const unplaced = new Set(
+    [...projects]
+      .filter(([, entry]) => entry.pinned === true)
+      .map(([cwd]) => cwd)
+  );
+  const listed = pins.filter((cwd) => unplaced.delete(cwd));
+  return [...listed, ...[...unplaced].sort()];
+}
+
+function put<T extends object>(
+  into: Map<string, T>,
+  key: string,
+  patch: T
+): boolean {
+  const next = onlySet({ ...into.get(key), ...patch });
+  if (Object.keys(next).length === 0) {
+    into.delete(key);
+  } else {
+    into.set(key, next);
+  }
+  return true;
+}
+
+/** Every field is opt-in, so a false flag or an empty name is the same as an absent one. */
+function onlySet<T extends object>(entry: T): T {
+  return Object.fromEntries(
+    Object.entries(entry).filter(
+      ([, value]) =>
+        value === true || (typeof value === "string" && value !== "")
+    )
+  ) as T;
+}
+
+function parseAll<T>(
+  value: unknown,
+  parse: (value: unknown) => T | undefined
+): Map<string, T> {
+  const parsed = new Map<string, T>();
+  for (const [key, entry] of Object.entries(Json.asRecord(value) ?? {})) {
+    const valid = parse(entry);
+    if (valid !== undefined) {
+      parsed.set(key, valid);
+    }
+  }
+  return parsed;
+}
+
+function parseSession(value: unknown): SessionEntry | undefined {
+  const raw = Json.asRecord(value);
+  if (raw === undefined || !isFlag(raw.archived) || !isFlag(raw.unread)) {
+    return undefined;
+  }
+  return onlySet({ archived: raw.archived, unread: raw.unread });
+}
+
+function parseProject(value: unknown): ProjectEntry | undefined {
+  const raw = Json.asRecord(value);
+  if (
+    raw === undefined ||
+    !isFlag(raw.pinned) ||
+    !isFlag(raw.expanded) ||
+    !isName(raw.label)
+  ) {
+    return undefined;
+  }
+  return onlySet({
+    pinned: raw.pinned,
+    expanded: raw.expanded,
+    label: raw.label,
+  });
+}
+
+function isFlag(value: unknown): value is boolean | undefined {
+  return value === undefined || typeof value === "boolean";
+}
+
+function isName(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === "string";
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Twice the width a sidebar row can show, so a name is never silently cut at the
+ * length it happens to render at, and a pasted essay still cannot become one.
+ */
+const LIMIT = 80;
+
+/** What pi should store for this name: whitespace collapsed, controls gone, `""` to clear. */
+function normalise(name: string | null | undefined): string {
+  const clean = (name ?? "")
+    .replace(/\p{Cc}/gu, " ")
+    .replace(/\s+/gu, " ")
+    .trim();
+  // By code point: a cap that splits a surrogate pair stores half a character.
+  return [...clean].slice(0, LIMIT).join("").trim();
+}
+
+/** The one spelling of a session name pim writes into pi's `session_info`. */
+export const SessionName = { normalise };