pim-agent 0.13.0 → 0.14.0

package/packages/server/src/ImageEndpoint.ts

@@ -6,11 +6,11 @@ import { ImageRoute } from "#protocol/ImageRoute";
 import { IMMUTABLE, serveFile } from "./StaticClient";
 
 export type ImageEndpointDeps = {
-  /** Defaults to `~/.pim/cache`, where `read` spills the picture it showed the model. */
+  /** Defaults to `~/.pim/cache`. */
   readonly root?: string;
 };
 
-/** `GET /image/<sha256>.<ext>`: the cached copy of a picture a tool view addresses, or 404 once the TTL sweep took it. */
+/** Serves images cached by `read`; 404 once the TTL sweep removed them. */
 export class ImageEndpoint {
   private readonly root: string;
 
@@ -18,7 +18,6 @@ export class ImageEndpoint {
     this.root = deps.root ?? SpillCache.dir();
   }
 
-  /** Whether this endpoint owns the path, so the gateway can route to it. */
   public static owns(pathname: string): boolean {
     return ImageRoute.owns(pathname);
   }
@@ -27,7 +26,7 @@ export class ImageEndpoint {
     if (request.method !== "GET" && request.method !== "HEAD") {
       return new Response("expected GET", { status: 405 });
     }
-    // The name is a digest and a format we wrote, which admits no separator to escape the cache with.
+    // `nameOf` only admits `<hex>.<ext>`, so no path traversal.
     const name = ImageRoute.nameOf(new URL(request.url).pathname);
     return name === null
       ? new Response("not found", { status: 404 })

package/packages/server/src/ProbeClient.ts

@@ -20,23 +20,21 @@ import {
 
 export type ProbeOptions = {
   readonly url: string;
-  /** Omit to have the server create a session; the id comes back on attach. */
+  /** Omit to have the server create one. */
   readonly sessionId?: string;
   readonly cwd?: string;
   readonly fromSeq?: number;
-  /** Sent on the attach frame; false is a client that is connected but not looking. */
   readonly attentive?: boolean;
-  /** Called for every frame, in arrival order. */
   readonly onEvent?: (event: ServerEvent) => void;
   /** Keystroke debounce for `files`; 0 makes tests deterministic. */
   readonly debounceMs?: number;
 };
 
-/** What `POST /upload` answers with, all of it server-side. */
+/** The `POST /upload` response. */
 export type UploadedFile = {
   readonly id: string;
   readonly path: string;
-  /** Where the bytes can be read back, relative to the server's origin. */
+  /** Server-relative. */
   readonly url: string;
   readonly mimeType: string;
   readonly isImage: boolean;
@@ -47,12 +45,11 @@ type Pending = {
   readonly reject: (err: Error) => void;
 };
 
-/** The reference client: speaks the whole protocol, renders nothing. */
+/** Headless protocol client for tests and the probe CLI. */
 export class ProbeClient {
   public sessionId: string | undefined;
   public seq: number;
   public readonly events: ServerEvent[] = [];
-  /** The `@` picker, answered by the server one query at a time. */
   public readonly files: RemoteFilePickerSuggestionEngine;
   private readonly options: ProbeOptions;
   private readonly pending = new Map<string, Pending>();
@@ -105,7 +102,6 @@ export class ProbeClient {
     });
   }
 
-  /** Says whether this client's reader is present; regaining it reads the session. */
   public attention(value: boolean): Promise<ResponseEvent> {
     return this.send({ type: "attention", value });
   }
@@ -141,7 +137,7 @@ export class ProbeClient {
       query,
       limit,
     });
-    return itemsOf(response);
+    return ok(response).items ?? [];
   }
 
   public async pickCommands(
@@ -154,10 +150,10 @@ export class ProbeClient {
       query,
       ...(limit === undefined ? {} : { limit }),
     });
-    return itemsOf(response);
+    return ok(response).items ?? [];
   }
 
-  /** Reads one subagent's transcript; its events stay enveloped in `events`. */
+  /** Child events stay enveloped in `events`. */
   public watchSubagent(callId: string, fromSeq = 0): Promise<ResponseEvent> {
     return this.send({
       type: "watch_subagent",
@@ -171,38 +167,27 @@ export class ProbeClient {
     return this.send({ type: "unwatch_subagent", callId });
   }
 
-  /** Pi's session catalogue; answers whether or not this probe is attached. */
   public async listSessions(
     scope: SessionScope = {}
   ): Promise<SessionListing["sessions"]> {
     return (await this.catalogue(scope)).sessions;
   }
 
-  /** The listing whole: the rows the page kept and the projects they came from. */
   public async catalogue(scope: SessionScope = {}): Promise<SessionListing> {
-    const response = await this.send({ type: "list_sessions", ...scope });
-    if (!response.success) {
-      throw new Error(response.error ?? "list_sessions failed");
-    }
+    const response = ok(await this.send({ type: "list_sessions", ...scope }));
     return {
       sessions: response.sessions ?? [],
       projects: response.projects ?? [],
     };
   }
 
-  /** Searches every session on disk; an empty query warms the index and answers with no hits. */
   public async search(
     query: string,
     scope: SearchScope = {}
   ): Promise<SessionSearch> {
-    const response = await this.send({
-      type: "search_sessions",
-      query,
-      ...scope,
-    });
-    if (!response.success) {
-      throw new Error(response.error ?? "search_sessions failed");
-    }
+    const response = ok(
+      await this.send({ type: "search_sessions", query, ...scope })
+    );
     return {
       hits: response.hits ?? [],
       dropped: response.dropped ?? [],
@@ -210,7 +195,6 @@ export class ProbeClient {
     };
   }
 
-  /** Names a session through pi's own name; `null` clears it back to its opening message. */
   public rename(
     sessionId: string,
     value: string | null
@@ -218,7 +202,6 @@ export class ProbeClient {
     return this.send({ type: "set_session_name", sessionId, value });
   }
 
-  /** Puts a session out of the live listing, or brings it back. */
   public setArchived(
     sessionId: string,
     value: boolean
@@ -226,67 +209,45 @@ export class ProbeClient {
     return this.send({ type: "set_session_archived", sessionId, value });
   }
 
-  /** Holds a session unread until something reads it; survives a listing and a re-attach. */
   public markUnread(sessionId: string, value: boolean): Promise<ResponseEvent> {
     return this.send({ type: "set_session_unread", sessionId, value });
   }
 
-  /** Pins a working directory, not a session. */
   public setPinned(cwd: string, value: boolean): Promise<ResponseEvent> {
     return this.send({ type: "set_project_pinned", cwd, value });
   }
 
-  /** Re-orders the pinned directories; the whole order, pinned ones only. */
   public setPinOrder(order: readonly string[]): Promise<ResponseEvent> {
     return this.send({ type: "set_pin_order", order });
   }
 
-  /** Unfolds a working directory's sidebar group, or folds it. */
   public setExpanded(cwd: string, value: boolean): Promise<ResponseEvent> {
     return this.send({ type: "set_project_expanded", cwd, value });
   }
 
-  /** Names a working directory for the listings; `null` puts it back to its base name. */
   public setLabel(cwd: string, value: string | null): Promise<ResponseEvent> {
     return this.send({ type: "set_project_label", cwd, value });
   }
 
-  /** The model catalogue, plus this session's thinking levels; empty when unattached. */
   public async listModels(): Promise<{
     readonly models: readonly ModelView[];
     readonly thinkingLevels: readonly string[];
   }> {
-    const response = await this.send({ type: "list_models" });
-    if (!response.success) {
-      throw new Error(response.error ?? "list_models failed");
-    }
+    const response = ok(await this.send({ type: "list_models" }));
     return {
       models: response.models ?? [],
       thinkingLevels: response.thinkingLevels ?? [],
     };
   }
 
-  /** Every extension this server can switch, scoped to the attached session's cwd. */
   public async listExtensions(): Promise<readonly ExtensionEntry[]> {
-    const response = await this.send({ type: "list_extensions" });
-    if (!response.success) {
-      throw new Error(response.error ?? "list_extensions failed");
-    }
-    return response.extensions ?? [];
+    return ok(await this.send({ type: "list_extensions" })).extensions ?? [];
   }
 
   public async setExtension(id: string, value: boolean): Promise<void> {
-    const response = await this.send({
-      type: "set_extension",
-      extensionId: id,
-      value,
-    });
-    if (!response.success) {
-      throw new Error(response.error ?? "set_extension failed");
-    }
+    ok(await this.send({ type: "set_extension", extensionId: id, value }));
   }
 
-  /** Transfers a client-local file into the server's world; only the bytes and bare filename are sent. */
   public async upload(localPath: string): Promise<UploadedFile> {
     const file = Bun.file(localPath);
     const form = new FormData();
@@ -331,8 +292,6 @@ export class ProbeClient {
       return Promise.resolve(hit);
     }
     return new Promise<ServerEvent>((resolve, reject) => {
-      const waiter = { test, resolve };
-      this.waiters.add(waiter);
       const timer = setTimeout(() => {
         this.waiters.delete(waiter);
         reject(
@@ -340,10 +299,18 @@ export class ProbeClient {
         );
       }, timeoutMs);
       timer.unref?.();
+      const waiter = {
+        test,
+        resolve: (event: ServerEvent) => {
+          clearTimeout(timer);
+          resolve(event);
+        },
+      };
+      this.waiters.add(waiter);
     });
   }
 
-  /** Drops the socket without a close frame, the way a killed client would. */
+  /** Closes with an abnormal code, like a killed client. */
   public kill(): void {
     this.socket?.close(4000, "probe killed");
     this.socket = undefined;
@@ -387,9 +354,9 @@ export class ProbeClient {
   }
 }
 
-function itemsOf(response: ResponseEvent): readonly PickerItem[] {
+function ok(response: ResponseEvent): ResponseEvent {
   if (!response.success) {
-    throw new Error(response.error ?? "picker query failed");
+    throw new Error(response.error ?? "command failed");
   }
-  return response.items ?? [];
+  return response;
 }

package/packages/server/src/Reloader.ts

@@ -4,21 +4,19 @@ import { Updater, type UpdateOutcome } from "#core/shared/Updater";
 import type { ServerEvent } from "#protocol/ServerEvent";
 
 export type ReloaderDeps = {
-  /** To every connection: the restart takes all of them down together. */
   readonly announce: (event: ServerEvent) => void;
-  /** Runs the update, reporting each step as it starts. */
   readonly update?: (onStep: (label: string) => void) => Promise<UpdateOutcome>;
-  /** Takes this process down so the supervisor puts the new code up in its place. */
+  /** Exits so the supervisor restarts on the new code. */
   readonly shutdown?: () => Promise<void>;
 };
 
-// Re-raise SIGTERM rather than exiting: the handler stops the gateway and flushes the read cursors.
+// SIGTERM rather than exit, so the handler stops the gateway and flushes read cursors.
 async function restartAndExit(): Promise<void> {
   await Supervisor.restartSiblings(DaemonUnit);
   process.kill(process.pid, "SIGTERM");
 }
 
-/** Runs the update-restart-return an operator asked for, announcing each phase. */
+/** Runs update then restart, announcing each phase. */
 export class Reloader {
   private readonly announce: (event: ServerEvent) => void;
   private readonly update: (
@@ -34,7 +32,7 @@ export class Reloader {
     this.running = undefined;
   }
 
-  /** The run already in flight, or a new one; two callers share one install. */
+  /** Concurrent callers share one run. */
   public start(): Promise<void> {
     this.running ??= this.run().finally(() => {
       this.running = undefined;
@@ -78,7 +76,6 @@ export class Reloader {
     try {
       await this.shutdown();
     } catch (err) {
-      // Must follow the `restarting` frame: it corrects a client already told to expect the drop.
       this.failed(messageOf(err));
     }
   }

package/packages/server/src/SendFileTool.ts

@@ -54,7 +54,7 @@ function build(
           isImage: stored.mimeType.startsWith("image/"),
         };
         return {
-          // Never the URL: an address the model can repeat is a second, dead copy of this delivery.
+          // Omit the URL so the model can't repeat it.
           content: [{ type: "text", text: `Sent ${details.name} (${size} B)` }],
           details,
         };

package/packages/server/src/SessionCatalogue.ts

@@ -27,9 +27,7 @@ import type {
 
 export type SessionCatalogueDeps = {
   readonly registry: SessionRegistry;
-  /** Which sessions have been read, shared by every client. */
   readonly cursors: ReadCursors;
-  /** Archived, held-unread and pinned, shared by every client. */
   readonly meta: SessionMeta;
   readonly liveStatus: (sessionId: string) => SessionStatus | undefined;
   readonly liveSessionIds: () => Iterable<string>;
@@ -39,10 +37,10 @@ export type SessionCatalogueDeps = {
 
 const DEFAULT_SESSION_LIMIT = 50;
 
-/** A digest is a whole-file read; a page of them at once is a page of files in memory at once. */
+/** Concurrent digest reads; each reads a whole file into memory. */
 const DIGEST_READS = 16;
 
-/** Long enough that a turn's entries are one announcement, short enough that a new session appears while the user is still looking. */
+/** Debounce for `sessions_changed`. */
 const ANNOUNCE_MS = 500;
 
 type CachedDigest = SessionDigest & { readonly modifiedAt: number };
@@ -51,7 +49,6 @@ type Overrides = ReadonlyMap<string, SessionEntry>;
 
 type PageScope = {
   readonly overrides: Overrides;
-  /** True while listing the archived sessions rather than the live ones. */
   readonly archived: boolean;
   readonly limit: number;
   readonly perProject: number;
@@ -72,12 +69,7 @@ export class SessionCatalogue {
     this.index = this.newIndex();
   }
 
-  /**
-   * Follow the sessions tree while anyone is connected. A session the terminal
-   * or a vanilla `pi` starts is a file this process never hears about
-   * otherwise, and a list nobody asked to re-fetch is a list that never learns
-   * about it.
-   */
+  /** Watches the sessions tree, so sessions started by other processes are announced. */
   public watch(active: boolean): void {
     if (active === this.watching) {
       return;
@@ -103,7 +95,7 @@ export class SessionCatalogue {
       this.deps.meta.sessions(),
       this.deps.meta.pinning(),
     ]);
-    // Prune only on an unfiltered listing: a cwd-filtered one would forget every other directory.
+    // Prune only when unfiltered, or other directories would be forgotten.
     if (command.cwd === undefined) {
       const alive = new Set([
         ...summaries.map((summary) => summary.sessionId),
@@ -113,9 +105,10 @@ export class SessionCatalogue {
         this.deps.cursors.prune(alive),
         this.deps.meta.prune(alive),
       ]);
+      this.forget(alive, new Set(summaries.map((summary) => summary.path)));
     }
     const scope = command.archived === true;
-    // Before the cut: an archived row that ate the page budget would push a live one off the end.
+    // Filter before paging so out-of-scope rows don't use the page budget.
     const inScope = summaries.filter(
       (summary) =>
         (overrides.get(summary.sessionId)?.archived === true) === scope
@@ -126,19 +119,13 @@ export class SessionCatalogue {
         overrides,
         archived: scope,
         limit,
-        // Absent, a project may fill the page; it is the page that bounds it either way.
         perProject: command.perProject ?? limit,
       }),
-      // Counted before the cut, and over the whole scope: a collapsed group says how many it holds, and a row the cut dropped is one a client can still ask for.
+      // Counted before paging.
       projects: projectsOf(inScope, pinning),
     };
   }
 
-  /**
-   * The index cannot see the sidecar, so the archived scope is a predicate it
-   * calls before its own limit, and the badge is a `Map.get` over the one read
-   * of `sessions.json` this query makes.
-   */
   public async search(
     command: Command & { readonly type: "search_sessions" }
   ): Promise<SessionSearch> {
@@ -162,7 +149,7 @@ export class SessionCatalogue {
     };
   }
 
-  /** Announces a status edge to every client; the announcement must precede the read mark. */
+  /** Announces a status change; must precede the read mark. */
   public onStatus(sessionId: string, status: SessionStatus): void {
     if (this.activity.get(sessionId) === status) {
       return;
@@ -178,10 +165,10 @@ export class SessionCatalogue {
     this.activity.set(sessionId, status);
   }
 
-  /** Moves a session's read cursor to now, drops the mark a reader left on it by hand, and says so to every client. */
+  /** Marks read now, clears the sticky unread flag, and announces it. */
   public async markRead(sessionId: string): Promise<void> {
     await this.deps.cursors.mark(sessionId);
-    // The only place the sticky flag is cleared; a listing must never clear it.
+    // The only place the sticky flag is cleared.
     if ((await this.deps.meta.of(sessionId)).unread === true) {
       await this.deps.meta.setUnread(sessionId, false);
     }
@@ -199,17 +186,28 @@ export class SessionCatalogue {
     this.index = this.newIndex();
   }
 
-  /** One index per catalogue, and so one per session root; the registry's listing is the tree it follows. */
+  private forget(alive: ReadonlySet<string>, paths: ReadonlySet<string>): void {
+    for (const map of [this.activity, this.settled]) {
+      for (const sessionId of map.keys()) {
+        if (!alive.has(sessionId)) {
+          map.delete(sessionId);
+        }
+      }
+    }
+    for (const path of this.digests.keys()) {
+      if (!paths.has(path)) {
+        this.digests.delete(path);
+      }
+    }
+  }
+
   private newIndex(): SearchIndex {
     return new SearchIndex({ list: () => this.deps.registry.list() });
   }
 
   /**
-   * Selects by modified time under a per-project budget and digests only what
-   * it selects: ordering by settle time would read every session on disk. A
-   * session with nothing to call itself is not a row, and the budget it spent
-   * goes back to its project, so a directory of abandoned files still shows
-   * the sessions underneath them.
+   * Selects by mtime under a per-project budget and digests only the selection.
+   * A session without a title yields no row and refunds its project's budget.
    */
   private async page(
     candidates: readonly SessionSummary[],
@@ -241,7 +239,7 @@ export class SessionCatalogue {
     return rows.sort((a, b) => b.settledAt - a.settledAt);
   }
 
-  /** Nothing for a session that never asked anything and was never named: the row it would draw is a truncated UUID. */
+  /** Undefined for a session with no title (never prompted or named). */
   private async row(
     { sessionId, cwd, path, createdAt, modifiedAt }: SessionSummary,
     { overrides, archived }: PageScope
@@ -273,7 +271,7 @@ export class SessionCatalogue {
     };
   }
 
-  // One watch per directory, never a recursive one: `fs.watch` recursion is unsupported on some platforms and silent on others.
+  // One watch per directory: recursive `fs.watch` is unreliable across platforms.
   private follow(): void {
     const root = this.deps.registry.sessionsRoot;
     const wanted = new Set([root, ...FileWatch.subdirectories(root)]);
@@ -295,7 +293,6 @@ export class SessionCatalogue {
     }
   }
 
-  // Debounced: a turn writes a dozen entries, and re-listing is a read of every session header.
   private onTreeChange(): void {
     if (this.announcing !== undefined || !this.watching) {
       return;
@@ -308,7 +305,7 @@ export class SessionCatalogue {
     this.announcing.unref?.();
   }
 
-  // A running session must be answered for by its last idle reading: mid-turn the file's time is the line just written.
+  // Mid-turn, use the last idle time: the file's time is just the latest write.
   private answerTime(
     sessionId: string,
     status: SessionStatus | undefined,
@@ -339,13 +336,7 @@ export class SessionCatalogue {
     return renamed(digest, name);
   }
 
-  /**
-   * Mid-turn the file is appended to between listings, so its digest never hits
-   * the cache and the whole-file read lands on the busiest session there is.
-   * Nothing it answers can have moved: the opening message was written long
-   * ago, the settle time is deliberately not read from the file while a turn
-   * runs, and the name is the live session's own to say.
-   */
+  /** Mid-turn the cached digest is reused despite a changed mtime: nothing it holds can have moved. */
   private reusable(
     path: string,
     modifiedAt: number,
@@ -356,8 +347,7 @@ export class SessionCatalogue {
     if (cached === undefined) {
       return undefined;
     }
-    // Except a name the live session has since cleared: the opening message a
-    // nameless row falls back to is in the file and nowhere else.
+    // A cleared name needs the opening message, which only the file has.
     if (name === null && cached.named === true) {
       return undefined;
     }
@@ -374,7 +364,7 @@ export class SessionCatalogue {
     return digest;
   }
 
-  /** What a live session calls itself, without reading its file; `null` is live and unnamed. */
+  /** `null` is live and unnamed; undefined is not live. */
   private liveName(sessionId: string): string | null | undefined {
     const agent = this.deps.registry.peek(sessionId)?.agentSession;
     return agent === undefined
@@ -383,7 +373,6 @@ export class SessionCatalogue {
   }
 }
 
-/** The row the wire carries: the index's hit, plus the one thing about it only the sidecar knows. */
 function hitOf(hit: SearchHit, archived: boolean): SearchHitView {
   return {
     sessionId: hit.sessionId,
@@ -398,7 +387,7 @@ function hitOf(hit: SearchHit, archived: boolean): SearchHitView {
   };
 }
 
-/** A live session's own name wins over the file's: a rename lands on the row before the digest behind it expires. */
+/** A live session's name wins over the file's. */
 function renamed(
   digest: SessionDigest,
   name: string | null | undefined
@@ -408,7 +397,7 @@ function renamed(
     : digest;
 }
 
-/** The next sessions to digest, newest first, skipping the projects that have spent their budget and the candidates an earlier round already took. */
+/** The next unconsumed sessions to digest, skipping projects over budget. */
 function choose(
   candidates: readonly SessionSummary[],
   consumed: Set<SessionSummary>,
@@ -431,7 +420,6 @@ function choose(
   return batch;
 }
 
-/** Every working directory the scope holds sessions in, newest first; the count is the header scan's, so it owes nothing to the page. */
 function projectsOf(
   summaries: readonly SessionSummary[],
   { projects, order }: Pinning

package/packages/server/src/SessionProjection.ts

@@ -15,17 +15,13 @@ import type {
 } from "#protocol/ServerEvent";
 import { attachmentUrl } from "./AttachmentEndpoint";
 
-type PendingCall = {
-  readonly name: string;
-  readonly args: unknown;
-};
-
-/** Projects pi's session file into durable events: one line in, at most one `DurableEvent` out, tagged with that line's ordinal. */
+/** Projects pi's session file into durable events: at most one per line, tagged with the line ordinal. */
 export class SessionProjection {
   private readonly log: EventLog;
   private readonly cwd: () => string;
   private readonly events: DurableEvent[] = [];
-  private readonly calls = new Map<string, PendingCall>();
+  /** Tool call args by call id. */
+  private readonly callArgs = new Map<string, unknown>();
   private draining: Promise<void> = Promise.resolve();
   private highest = 0;
 
@@ -53,7 +49,7 @@ export class SessionProjection {
     return this.events.slice(low);
   }
 
-  /** Read whatever pi has appended since the last drain; serialized, as overlapping reads double-project lines. */
+  /** Reads what pi appended since the last drain. Serialized: overlapping reads would double-project lines. */
   public async drain(): Promise<readonly DurableEvent[]> {
     const before = this.events.length;
     const done = this.draining.then(async () => {
@@ -111,7 +107,7 @@ export class SessionProjection {
           if (part.type !== "toolCall") {
             continue;
           }
-          this.calls.set(part.id, { name: part.name, args: part.arguments });
+          this.callArgs.set(part.id, part.arguments);
           toolCalls.push({
             callId: part.id,
             name: part.name,
@@ -141,7 +137,6 @@ export class SessionProjection {
         };
       }
       case "toolResult": {
-        const call = this.calls.get(message.toolCallId);
         return {
           seq,
           type: "tool_result",
@@ -150,7 +145,7 @@ export class SessionProjection {
           isError: message.isError,
           view: Tools.viewOf({
             name: message.toolName,
-            args: call?.args ?? {},
+            args: this.callArgs.get(message.toolCallId) ?? {},
             isError: message.isError,
             result: {
               content: withoutImages(message.content),
@@ -178,7 +173,7 @@ type ToolResultContent = Extract<
   { role: "toolResult" }
 >["content"];
 
-/** No base64 crosses the websocket: a view reaches its picture through `details.sha256` instead. */
+/** Keeps base64 off the websocket; views load images via `details.sha256`. */
 function withoutImages(content: ToolResultContent): ToolResultContent {
   return content.some((part) => part.type === "image")
     ? content.map((part) =>