pim-agent 0.9.0 → 0.11.0

package/packages/protocol/src/ServerEvent.ts

@@ -1,9 +1,12 @@
 import type { DirectoryListing } from "#core/shared/Directories";
+import type { CommitResult, GitBranch } from "#core/shared/Git";
 import type { PickerItem } from "#core/picker/PickerItem";
+import type { ExtensionEntry } from "#core/shared/PiExtensions";
+import type { SearchRange, SearchSnippet } from "#core/session/SearchIndex";
 import type { LeaseFrontend } from "#core/session/SessionLease";
 import type { UpdateSkip } from "#core/shared/Updater";
 import type { NoticeSeverity, ToolView } from "#core/view/ViewBlock";
-import type { ProtocolVersion } from "./Protocol";
+import type { ChangeList, FileDiff, FileLines } from "./Diff";
 
 export type SessionStatus = "idle" | "thinking" | "streaming" | "tool";
 
@@ -92,11 +95,11 @@ export type UpdateStateEvent =
 export type EphemeralEvent =
   | {
       readonly type: "attached";
-      readonly protocolVersion: ProtocolVersion;
       readonly sessionId: string;
       readonly cwd: string;
       /** Highest durable `seq` at attach time; replay follows immediately. */
       readonly head: number;
+      /** The server's build; a client built from another one is stale and should reload. */
       readonly pimVersion: string;
       readonly piVersion: string;
     }
@@ -152,6 +155,29 @@ export type EphemeralEvent =
       readonly events: readonly StreamEvent[];
     }
   | { readonly type: "turn_end"; readonly stats: TurnStats }
+  /** Something an extension said, in Markdown; shown and then forgotten, never written to the session. */
+  | {
+      readonly type: "ui_notice";
+      readonly id: string;
+      readonly severity: NoticeSeverity;
+      readonly text: string;
+      /** The command being dispatched when it was said, like `/login`; absent means nobody asked for it. */
+      readonly command?: string;
+    }
+  /** An extension is waiting on a human; the first `ui_response` wins and the rest are refused. */
+  | {
+      readonly type: "ui_request";
+      readonly requestId: string;
+      readonly method: "select" | "confirm" | "input";
+      readonly title: string;
+      readonly message?: string;
+      readonly options?: readonly string[];
+      readonly placeholder?: string;
+      /** The command that asked, like `/login`; absent where an extension asked unprompted. */
+      readonly command?: string;
+    }
+  /** The request is settled, by whoever answered it or by the server answering for them; drop its control. */
+  | { readonly type: "ui_request_done"; readonly requestId: string }
   /** Sent to every connection, not just those attached; only sessions this server holds open are reported. */
   | {
       readonly type: "session_activity";
@@ -160,8 +186,34 @@ export type EphemeralEvent =
     }
   /** Sent to every connection; the read cursor is one per session, not one per client. */
   | { readonly type: "session_read"; readonly sessionId: string }
+  /** Sent to every connection: one session's name or overrides changed, so a listing a client holds can be patched in place. */
+  | {
+      readonly type: "session_meta";
+      readonly sessionId: string;
+      /** The session's own name, `null` once it is cleared. */
+      readonly name?: string | null;
+      readonly archived?: boolean;
+      readonly unread?: boolean;
+    }
+  /**
+   * Sent to every connection; keyed by absolute working directory, not by
+   * session. A patch like `session_meta`: only what changed is said, so a
+   * fold carries no claim about the pin beside it.
+   */
+  | {
+      readonly type: "project_meta";
+      readonly cwd: string;
+      readonly pinned?: boolean;
+      readonly expanded?: boolean;
+      /** What the project is called in a listing, `null` once it is cleared. */
+      readonly label?: string | null;
+    }
+  /** Sent to every connection: the pinned projects, in the order they are shown. */
+  | { readonly type: "pins_changed"; readonly order: readonly string[] }
   /** Sent to every connection: the sessions on disk changed, so any listing a client holds is stale. */
   | { readonly type: "sessions_changed" }
+  /** Sent to every connection: an extension was switched, so any roster a client holds is stale. */
+  | { readonly type: "extensions_changed" }
   /** Sent to every connection; the restart it ends in drops every socket. */
   | UpdateStateEvent
   | {
@@ -175,6 +227,8 @@ export type EphemeralEvent =
       readonly status: SessionStatus;
       /** False while another process holds this session's turn lease. */
       readonly writable: boolean;
+      /** A session in the same working directory is mid-turn, so nothing may move the repository under it. */
+      readonly repoBusy?: boolean;
       /** Who holds it; absent when nothing does, or when their record is torn. */
       readonly heldBy?: {
         readonly frontend: LeaseFrontend;
@@ -192,6 +246,8 @@ export type EphemeralEvent =
       readonly dirtyCount?: number;
       readonly ahead?: number;
       readonly behind?: number;
+      /** Changes whenever the working copy does, content of a dirty file included. */
+      readonly repoRevision?: string;
     }
   /** A frame the server could not attribute to any command. */
   | { readonly type: "error"; readonly message: string };
@@ -205,12 +261,68 @@ export type SessionSummaryView = {
   readonly settledAt: number;
   /** The session's first user message, trimmed; absent when it has none. */
   readonly title?: string;
+  /** True when `title` is a name somebody wrote, rather than the first message. */
+  readonly named?: true;
+  readonly archived?: true;
   /** Has answered since anything last read it; absent means it has not. */
   readonly unread?: boolean;
   /** Absent when idle, and for a session this server does not hold open. */
   readonly status?: SessionStatus;
 };
 
+/** One working directory the catalogue holds sessions for, counted before any per-project cut. */
+export type ProjectView = {
+  readonly cwd: string;
+  /** Every session in it the listing's scope allows, including the ones the cut dropped. */
+  readonly count: number;
+  readonly pinned?: true;
+  /** Where it sorts among the pinned, 0 first; absent unless it is pinned. */
+  readonly pinRank?: number;
+  /** The sidebar group stands unfolded; absent is folded. */
+  readonly expanded?: true;
+  /** What to call it instead of its base name; absent when it goes by the directory. */
+  readonly label?: string;
+};
+
+/**
+ * One session a search matched. Deliberately not a `SessionSummaryView`: what
+ * a ranked list needs is why the row matched, and `unread` is the sidebar's
+ * triage while `status` resolves itself the moment the session opens.
+ */
+export type SearchHitView = {
+  readonly sessionId: string;
+  readonly cwd: string;
+  /** Its name if it has one, else the clamped opening message; the digest's, so it agrees with the sidebar's. */
+  readonly title?: string;
+  /** Offsets into the clamped `title`, empty when the title did not match. */
+  readonly titleRanges: readonly SearchRange[];
+  /** The session's opening ask, for a row whose name is all that matched and so has no snippet to show. */
+  readonly opening?: string;
+  /** End of the last completed turn and the row's clock, never the file mtime; falls back to when the session started, as the sidebar's does. */
+  readonly settledAt: number;
+  /** Searched and found anyway: the badge that makes "archived are in scope" honest. */
+  readonly archived?: true;
+  /** What matched, in the words it was said in, each with its own ranges. */
+  readonly snippets: readonly SearchSnippet[];
+  /** Matching messages in this session, before the snippet cut. */
+  readonly total: number;
+};
+
+/** One answer to `list_sessions`: the page of rows, and every directory that had one, counted whole. */
+export type SessionListing = {
+  readonly sessions: readonly SessionSummaryView[];
+  /** Counted before the per-project cut, so a group can say what a page of it leaves out. */
+  readonly projects: readonly ProjectView[];
+};
+
+/** One answer to `search_sessions`: the ranked rows, the words no session held, and the scope it read. */
+export type SessionSearch = {
+  readonly hits: readonly SearchHitView[];
+  readonly dropped: readonly string[];
+  /** Sessions searched, whole: what the empty state and the result footer say out loud. */
+  readonly scanned: number;
+};
+
 /** One model the server can be switched to, for the composer's model menu. */
 export type ModelView = {
   readonly id: string;
@@ -229,14 +341,36 @@ export type ResponseEvent = {
   readonly items?: readonly PickerItem[];
   /** The catalogue, for `list_sessions`. */
   readonly sessions?: readonly SessionSummaryView[];
+  /** The directories those sessions came from, for `list_sessions`. */
+  readonly projects?: readonly ProjectView[];
+  /** The ranked sessions, for `search_sessions`. */
+  readonly hits?: readonly SearchHitView[];
+  /** Query words no session held, dropped so the rest could match, for `search_sessions`. */
+  readonly dropped?: readonly string[];
+  /** Sessions the query actually searched, for `search_sessions`. */
+  readonly scanned?: number;
   /** The model catalogue, for `list_models`. */
   readonly models?: readonly ModelView[];
   /** What the *current* model supports, on the same answer. */
   readonly thinkingLevels?: readonly string[];
+  /** The extension roster, for `list_extensions`. */
+  readonly extensions?: readonly ExtensionEntry[];
   /** One directory's subdirectories, for `list_dirs`. */
   readonly directory?: DirectoryListing;
+  /** The cwd's local branches, for `list_branches`. */
+  readonly branches?: readonly GitBranch[];
+  /** The commit that landed, for `commit`. */
+  readonly commit?: Pick<Extract<CommitResult, { readonly ok: true }>, "sha">;
+  /** The change list, for `list_changes`. */
+  readonly changes?: ChangeList;
+  /** One file's hunks, for `file_diff`. */
+  readonly fileDiff?: FileDiff;
+  /** The lines behind one gap, for `read_lines`. */
+  readonly fileLines?: FileLines;
   /** For `cancel` and `dequeue`: queued messages pi gave back, now owned by the client that asked. */
   readonly restored?: readonly string[];
+  /** For `user_message`: it named an extension command, so no turn started and no entry was written. */
+  readonly dispatched?: boolean;
 };
 
 export type ServerEvent = DurableEvent | EphemeralEvent | ResponseEvent;
@@ -249,3 +383,58 @@ export type ServerEventType = ServerEvent["type"];
 export function isDurableEvent(event: ServerEvent): event is DurableEvent {
   return "seq" in event;
 }
+
+/**
+ * Whether the frame speaks for the one session a connection is attached to,
+ * and so says nothing to a client whose attach is still in flight. The rest
+ * name their own subject — another session, a directory, or nothing at all —
+ * and gating those on the attach window drops a broadcast every time a client
+ * switches session.
+ *
+ * Exhaustive by construction: a new event is a type error here until it is
+ * classified, which is the only reason this lives beside the wire types
+ * rather than in the client that gates on it.
+ */
+export function isAttachScoped(event: ServerEvent): boolean {
+  switch (event.type) {
+    case "attached":
+    case "replay":
+    case "message":
+    case "message_start":
+    case "message_retire":
+    case "text_delta":
+    case "thinking_delta":
+    case "tool_call":
+    case "tool_update":
+    case "tool_end":
+    case "tool_result":
+    case "notice":
+    case "subagent_events":
+    case "turn_end":
+    case "session_state":
+    case "ui_notice":
+    case "ui_request":
+    case "ui_request_done":
+    // Names a cwd, but only ever reaches a client down the session stream it
+    // is attached to, so the old session's is the only one that can arrive
+    // mid-attach — and re-querying for it would warm the wrong cache.
+    case "picker_invalidate":
+      return true;
+    case "session_activity":
+    case "session_read":
+    case "session_meta":
+    case "project_meta":
+    case "pins_changed":
+    case "sessions_changed":
+    case "extensions_changed":
+    case "update_state":
+    // Sent for a frame the server could not read at all, which is likeliest
+    // before an attach has settled: gating it swallows the diagnostic.
+    case "error":
+    case "response":
+      return false;
+    default:
+      event satisfies never;
+      return false;
+  }
+}

package/packages/server/src/ClientConnection.ts

@@ -44,6 +44,7 @@ export class ClientConnection {
   private paused = false;
   private cursor = 0;
   private closed = false;
+  private reading = true;
   private watch: SubagentWatch | undefined;
 
   public constructor(ws: ServerWebSocket<undefined>) {
@@ -54,6 +55,11 @@ export class ClientConnection {
     return this.stream?.sessionId;
   }
 
+  /** Whether the reader behind this socket is looking at the session right now. */
+  public get attentive(): boolean {
+    return this.reading;
+  }
+
   /** Highest durable `seq` this client has been handed. */
   public get seq(): number {
     return this.cursor;
@@ -66,17 +72,23 @@ export class ClientConnection {
 
   public async attach(
     stream: AttachableStream,
-    fromSeq: number
+    fromSeq: number,
+    attentive = true
   ): Promise<void> {
     this.detach();
     this.stream = stream;
     this.cursor = fromSeq;
+    this.reading = attentive;
     this.unsubscribe = stream.subscribe((event) => {
       this.onStreamEvent(event);
     });
     await this.sync();
   }
 
+  public setAttentive(attentive: boolean): void {
+    this.reading = attentive;
+  }
+
   /** Read a subagent's log alongside the attached session; at most one watch at a time. */
   public async watchSubagent(
     callId: string,
@@ -99,7 +111,7 @@ export class ClientConnection {
     if (this.closed) {
       return;
     }
-    this.ws.send(frame(event));
+    this.ws.send(frame(event), true);
   }
 
   public onDrain(): void {
@@ -239,7 +251,7 @@ export class ClientConnection {
     if (this.closed || this.paused) {
       return false;
     }
-    const status = this.ws.send(payload);
+    const status = this.ws.send(payload, true);
     if (status === 0) {
       this.paused = true;
       return false;

package/packages/server/src/ProbeClient.ts

@@ -2,14 +2,20 @@ import { basename } from "node:path";
 
 import type { PickerItem } from "#core/picker/PickerItem";
 import { RemoteFilePickerSuggestionEngine } from "#core/picker/RemoteFilePickerSuggestionEngine";
-import type { AttachmentRef, CommandDraft } from "#protocol/Command";
-import { PROTOCOL_VERSION } from "#protocol/Protocol";
+import type { ExtensionEntry } from "#core/shared/PiExtensions";
+import type {
+  AttachmentRef,
+  CommandDraft,
+  SearchScope,
+  SessionScope,
+} from "#protocol/Command";
 import {
   isDurableEvent,
   type ModelView,
   type ResponseEvent,
   type ServerEvent,
-  type SessionSummaryView,
+  type SessionListing,
+  type SessionSearch,
 } from "#protocol/ServerEvent";
 
 export type ProbeOptions = {
@@ -18,10 +24,10 @@ export type ProbeOptions = {
   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;
-  /** Sent instead of the real one, to exercise version rejection. */
-  readonly protocolVersion?: number;
   /** Keystroke debounce for `files`; 0 makes tests deterministic. */
   readonly debounceMs?: number;
 };
@@ -56,9 +62,6 @@ export class ProbeClient {
   }>();
   private socket: WebSocket | undefined;
   private nextId = 0;
-  private closeInfo:
-    | { readonly code: number; readonly reason: string }
-    | undefined;
 
   public constructor(options: ProbeOptions) {
     this.options = options;
@@ -78,7 +81,6 @@ export class ProbeClient {
       this.receive(String(event.data));
     });
     socket.addEventListener("close", (event) => {
-      this.closeInfo = { code: event.code, reason: event.reason };
       for (const { reject } of this.pending.values()) {
         reject(new Error(`socket closed: ${event.code} ${event.reason}`));
       }
@@ -94,14 +96,20 @@ export class ProbeClient {
     });
     return await this.send({
       type: "attach",
-      protocolVersion: (this.options.protocolVersion ??
-        PROTOCOL_VERSION) as typeof PROTOCOL_VERSION,
       ...(this.sessionId === undefined ? {} : { sessionId: this.sessionId }),
       ...(this.options.cwd === undefined ? {} : { cwd: this.options.cwd }),
+      ...(this.options.attentive === undefined
+        ? {}
+        : { attentive: this.options.attentive }),
       fromSeq: this.seq,
     });
   }
 
+  /** 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 });
+  }
+
   public send(command: CommandDraft): Promise<ResponseEvent> {
     const socket = this.socket;
     if (!socket) {
@@ -165,16 +173,82 @@ export class ProbeClient {
 
   /** Pi's session catalogue; answers whether or not this probe is attached. */
   public async listSessions(
-    cwd?: string
-  ): Promise<readonly SessionSummaryView[]> {
+    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");
+    }
+    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: "list_sessions",
-      ...(cwd === undefined ? {} : { cwd }),
+      type: "search_sessions",
+      query,
+      ...scope,
     });
     if (!response.success) {
-      throw new Error(response.error ?? "list_sessions failed");
+      throw new Error(response.error ?? "search_sessions failed");
     }
-    return response.sessions ?? [];
+    return {
+      hits: response.hits ?? [],
+      dropped: response.dropped ?? [],
+      scanned: response.scanned ?? 0,
+    };
+  }
+
+  /** Names a session through pi's own name; `null` clears it back to its opening message. */
+  public rename(
+    sessionId: string,
+    value: string | null
+  ): Promise<ResponseEvent> {
+    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
+  ): Promise<ResponseEvent> {
+    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. */
@@ -192,6 +266,26 @@ export class ProbeClient {
     };
   }
 
+  /** 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 ?? [];
+  }
+
+  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");
+    }
+  }
+
   /** 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);
@@ -249,17 +343,6 @@ export class ProbeClient {
     });
   }
 
-  /** Resolves when the socket closes, e.g. after a protocol rejection. */
-  public async closed(): Promise<{
-    readonly code: number;
-    readonly reason: string;
-  }> {
-    while (!this.closeInfo) {
-      await Bun.sleep(5);
-    }
-    return this.closeInfo;
-  }
-
   /** Drops the socket without a close frame, the way a killed client would. */
   public kill(): void {
     this.socket?.close(4000, "probe killed");