pim-agent 0.9.0 → 0.10.0

package/packages/server/src/StaticClient.ts

@@ -1,4 +1,7 @@
 import { join, resolve, sep } from "node:path";
+import { brotliCompressSync, constants } from "node:zlib";
+
+import type { BunFile } from "bun";
 
 /** The built Vite bundle, resolved relative to this file so it works installed. */
 export const DEFAULT_CLIENT_DIR = resolve(
@@ -18,6 +21,45 @@ const BUILD_HINT =
 /** Vite fingerprints everything under `assets/`, so it can never go stale. */
 export const IMMUTABLE = "public, max-age=31536000, immutable";
 
+const COMPRESSIBLE =
+  /^(?:text\/|image\/svg\+xml|application\/(?:javascript|json|wasm|xml))/;
+
+/** Below this a deflate stream is its own header: the framing costs more than the saving. */
+const MIN_COMPRESSED = 1024;
+
+type Bytes = Uint8Array<ArrayBuffer>;
+
+type Encoding = {
+  readonly name: string;
+  readonly compress: (bytes: Bytes) => Bytes;
+};
+
+/** Best first. Brotli at q5 beats gzip -9 on both size and time; q11 would cost 40x the CPU for 8%. */
+const ENCODINGS: readonly Encoding[] = [
+  {
+    name: "br",
+    compress: (bytes) =>
+      new Uint8Array(
+        brotliCompressSync(bytes, {
+          params: { [constants.BROTLI_PARAM_QUALITY]: 5 },
+        })
+      ),
+  },
+  { name: "gzip", compress: (bytes) => Bun.gzipSync(bytes) },
+];
+
+type Encoded = { readonly stamp: string; readonly bytes: Bytes };
+
+function accepts(header: string, name: string): boolean {
+  return header.split(",").some((entry) => {
+    const [token, ...params] = entry.trim().split(";");
+    return (
+      token?.toLowerCase() === name &&
+      !params.some((param) => param.replaceAll(" ", "") === "q=0")
+    );
+  });
+}
+
 /** A file off disk under a caching policy, or the 404 that a path naming nothing is. */
 export async function serveFile(
   path: string,
@@ -37,6 +79,7 @@ function looksLikeAsset(pathname: string): boolean {
 /** Serves the built browser client as a static SPA; unknown routes fall back to `index.html`. */
 export class StaticClient {
   private readonly root: string;
+  private readonly encoded = new Map<string, Encoded>();
 
   public constructor(root: string = DEFAULT_CLIENT_DIR) {
     this.root = resolve(root);
@@ -48,13 +91,11 @@ export class StaticClient {
     if (path !== undefined) {
       const file = Bun.file(path);
       if (await file.exists()) {
-        return new Response(file, {
-          headers: {
-            "cache-control": pathname.startsWith("/assets/")
-              ? IMMUTABLE
-              : "no-cache",
-          },
-        });
+        return await this.respond(
+          file,
+          request,
+          pathname.startsWith("/assets/") ? IMMUTABLE : "no-cache"
+        );
       }
     }
     if (looksLikeAsset(pathname)) {
@@ -67,14 +108,56 @@ export class StaticClient {
         headers: { "content-type": "text/plain; charset=utf-8" },
       });
     }
-    return new Response(index, {
-      headers: {
-        "content-type": "text/html; charset=utf-8",
-        "cache-control": "no-cache",
-      },
+    return await this.respond(
+      index,
+      request,
+      "no-cache",
+      "text/html; charset=utf-8"
+    );
+  }
+
+  // `vary` rides every answer, compressed or not: a cache must not hand one client's encoding to another.
+  private async respond(
+    file: BunFile,
+    request: Request,
+    cacheControl: string,
+    contentType = file.type
+  ): Promise<Response> {
+    const headers: Record<string, string> = {
+      "content-type": contentType,
+      "cache-control": cacheControl,
+      vary: "accept-encoding",
+    };
+    const encoding = this.negotiate(file, request);
+    if (encoding === undefined) {
+      return new Response(file, { headers });
+    }
+    return new Response(await this.compress(file, encoding), {
+      headers: { ...headers, "content-encoding": encoding.name },
     });
   }
 
+  private negotiate(file: BunFile, request: Request): Encoding | undefined {
+    if (!COMPRESSIBLE.test(file.type) || file.size < MIN_COMPRESSED) {
+      return undefined;
+    }
+    const accepted = request.headers.get("accept-encoding") ?? "";
+    return ENCODINGS.find((encoding) => accepts(accepted, encoding.name));
+  }
+
+  // Keyed by name, stamped by mtime: a rebuilt bundle replaces its entry instead of adding one.
+  private async compress(file: BunFile, encoding: Encoding): Promise<Bytes> {
+    const key = `${file.name ?? ""}\0${encoding.name}`;
+    const stamp = `${file.lastModified}:${file.size}`;
+    const cached = this.encoded.get(key);
+    if (cached?.stamp === stamp) {
+      return cached.bytes;
+    }
+    const bytes = encoding.compress(await file.bytes());
+    this.encoded.set(key, { stamp, bytes });
+    return bytes;
+  }
+
   // `new URL()` normalises literal `../` but not its percent-encoded spelling: re-resolve the decoded path.
   private within(pathname: string): string | undefined {
     let decoded: string;

package/packages/server/src/WsGateway.ts

@@ -7,16 +7,22 @@ import { Attachments } from "#core/attachments/Attachments";
 import type { PickerItem } from "#core/picker/PickerItem";
 import { Directories } from "#core/shared/Directories";
 import type { DirectoryListing } from "#core/shared/Directories";
+import { Git, type GitBranch } from "#core/shared/Git";
+import { GitMonitor, type GitRun } from "#core/shared/GitMonitor";
+import { RepoDiff } from "#core/shared/RepoDiff";
 import { ReadCursors } from "#core/session/ReadCursors";
 import type { SessionHost } from "#core/session/SessionHost";
+import { SessionMeta } from "#core/session/SessionMeta";
 import type { SessionRegistry } from "#core/session/SessionRegistry";
 import { PimVersion } from "#core/shared/PimVersion";
 import { SubagentLogs } from "#core/shared/SubagentLogs";
 import type { UpdateOutcome } from "#core/shared/Updater";
 import type { Command } from "#protocol/Command";
-import { CLOSE_PROTOCOL_MISMATCH, PROTOCOL_VERSION } from "#protocol/Protocol";
+import type { ChangeList, FileDiff, FileLines } from "#protocol/Diff";
 import type {
   ModelView,
+  ProjectView,
+  SearchHitView,
   ServerEvent,
   SessionSummaryView,
 } from "#protocol/ServerEvent";
@@ -41,6 +47,10 @@ export type WsGatewayDeps = {
   readonly imagesRoot?: string;
   /** Where the read cursors live; defaults to `~/.pim/read.json`. */
   readonly readCursorsPath?: string;
+  /** Where the per-session and per-project overrides live; defaults to `~/.pim/sessions.json`. */
+  readonly sessionMetaPath?: string;
+  /** How often a session file is polled where `fs.watch` says nothing; the default is a second. */
+  readonly pollMs?: number;
   /** The built web client; defaults to the bundle shipped beside this package. */
   readonly clientDir?: string;
   /** Runs the update a `reload` asks for, reporting each step as it starts. */
@@ -53,9 +63,18 @@ type Outcome = {
   readonly error?: string;
   readonly items?: readonly PickerItem[];
   readonly sessions?: readonly SessionSummaryView[];
+  readonly projects?: readonly ProjectView[];
+  readonly hits?: readonly SearchHitView[];
+  readonly dropped?: readonly string[];
+  readonly scanned?: number;
   readonly models?: readonly ModelView[];
   readonly thinkingLevels?: readonly string[];
   readonly directory?: DirectoryListing;
+  readonly branches?: readonly GitBranch[];
+  readonly commit?: { readonly sha: string };
+  readonly changes?: ChangeList;
+  readonly fileDiff?: FileDiff;
+  readonly fileLines?: FileLines;
   readonly restored?: readonly string[];
   readonly after?: () => void;
 };
@@ -81,6 +100,7 @@ export class WsGateway {
   private readonly uploads: AttachmentEndpoint;
   private readonly images: ImageEndpoint;
   private readonly catalogue: SessionCatalogue;
+  private readonly meta: SessionMeta;
   private readonly client: StaticClient;
   private readonly streams = new Map<string, SessionStream>();
   private readonly opening = new Map<string, Promise<SessionStream>>();
@@ -89,6 +109,9 @@ export class WsGateway {
     ClientConnection
   >();
   private readonly reloader: Reloader;
+  private readonly git = new GitMonitor();
+  private readonly pollMs: number | undefined;
+  private readonly busyRepos = new Set<string>();
   private versionsRead: Promise<readonly [string, string]> | undefined;
   private server: Server<undefined> | undefined;
 
@@ -96,15 +119,18 @@ export class WsGateway {
     this.registry = deps.registry;
     this.hostname = deps.hostname ?? DEFAULT_HOSTNAME;
     this.requestedPort = deps.port ?? DEFAULT_PORT;
+    this.pollMs = deps.pollMs;
     this.uploads = new AttachmentEndpoint(
       deps.attachmentsRoot === undefined ? {} : { root: deps.attachmentsRoot }
     );
     this.images = new ImageEndpoint(
       deps.imagesRoot === undefined ? {} : { root: deps.imagesRoot }
     );
+    this.meta = new SessionMeta(deps.sessionMetaPath);
     this.catalogue = new SessionCatalogue({
       registry: deps.registry,
       cursors: new ReadCursors(deps.readCursorsPath),
+      meta: this.meta,
       liveStatus: (sessionId) => this.streams.get(sessionId)?.host.status,
       liveSessionIds: () => this.streams.keys(),
       isBeingRead: (sessionId) => this.isBeingRead(sessionId),
@@ -145,7 +171,9 @@ export class WsGateway {
       fetch: (req, server) => {
         const { pathname } = new URL(req.url);
         if (pathname === "/health") {
-          return Response.json({ ok: true, protocolVersion: PROTOCOL_VERSION });
+          return this.versions().then(([pimVersion]) =>
+            Response.json({ ok: true, pimVersion })
+          );
         }
         if (AttachmentEndpoint.owns(pathname)) {
           return this.uploads.handle(req);
@@ -159,6 +187,8 @@ export class WsGateway {
       websocket: {
         backpressureLimit: 8 << 20,
         closeOnBackpressureLimit: false,
+        // Dedicated, so the window survives between frames: the repeated event envelope is most of a delta.
+        perMessageDeflate: { compress: "dedicated", decompress: "dedicated" },
         open: (ws) => {
           this.connections.set(ws, new ClientConnection(ws));
           this.syncWatches();
@@ -184,6 +214,8 @@ export class WsGateway {
     }
     this.streams.clear();
     this.opening.clear();
+    this.git.dispose();
+    this.busyRepos.clear();
     this.catalogue.watch(false);
     this.catalogue.clear();
     await this.catalogue.flush();
@@ -217,19 +249,6 @@ export class WsGateway {
       connection.send({ type: "error", message: "frame is not a command" });
       return;
     }
-    if (
-      command.type === "attach" &&
-      command.protocolVersion !== PROTOCOL_VERSION
-    ) {
-      connection.send({
-        type: "response",
-        id: command.id,
-        success: false,
-        error: `unsupported protocol version ${String(command.protocolVersion)}; this server speaks ${PROTOCOL_VERSION}`,
-      });
-      ws.close(CLOSE_PROTOCOL_MISMATCH, "protocol version mismatch");
-      return;
-    }
     try {
       const { error, after, ...answer } = await this.dispatch(
         connection,
@@ -260,8 +279,83 @@ export class WsGateway {
     switch (command.type) {
       case "attach":
         return await this.attach(connection, command);
+      case "attention": {
+        const regained = command.value && !connection.attentive;
+        connection.setAttentive(command.value);
+        const sessionId = connection.sessionId;
+        if (regained && sessionId !== undefined) {
+          await this.catalogue.markRead(sessionId);
+        }
+        return {};
+      }
       case "list_sessions":
-        return { sessions: await this.catalogue.list(command) };
+        return await this.catalogue.list(command);
+      case "search_sessions":
+        return await this.catalogue.search(command);
+      // The four below take a session this server may never have opened: a row
+      // is archived or renamed from the sidebar without being attached to, so
+      // none of them may reach for a stream. A sidecar write moves no session
+      // file and produces no `sessions_changed`, so the broadcast each ends
+      // with is the only word a listing already in a client's hands gets.
+      case "set_session_name": {
+        const name = await this.registry.setName(
+          command.sessionId,
+          command.value
+        );
+        this.broadcast({
+          type: "session_meta",
+          sessionId: command.sessionId,
+          name: name ?? null,
+        });
+        return {};
+      }
+      case "set_session_archived":
+        await this.meta.setArchived(command.sessionId, command.value);
+        this.broadcast({
+          type: "session_meta",
+          sessionId: command.sessionId,
+          archived: command.value,
+        });
+        return {};
+      case "set_session_unread":
+        await this.meta.setUnread(command.sessionId, command.value);
+        this.broadcast({
+          type: "session_meta",
+          sessionId: command.sessionId,
+          unread: command.value,
+        });
+        return {};
+      case "set_project_pinned":
+        await this.meta.setPinned(command.cwd, command.value);
+        this.broadcast({
+          type: "project_meta",
+          cwd: command.cwd,
+          pinned: command.value,
+        });
+        // The flag and the place it takes are one fact to a sidebar; a pin
+        // that arrived without a rank would sort by nothing until the next listing.
+        this.broadcast({ type: "pins_changed", order: await this.meta.pins() });
+        return {};
+      case "set_project_expanded":
+        await this.meta.setExpanded(command.cwd, command.value);
+        this.broadcast({
+          type: "project_meta",
+          cwd: command.cwd,
+          expanded: command.value,
+        });
+        return {};
+      case "set_project_label":
+        await this.meta.setLabel(command.cwd, command.value);
+        this.broadcast({
+          type: "project_meta",
+          cwd: command.cwd,
+          label: command.value,
+        });
+        return {};
+      case "set_pin_order":
+        await this.meta.setPinOrder(command.order);
+        this.broadcast({ type: "pins_changed", order: await this.meta.pins() });
+        return {};
       case "list_models":
         return {
           models: this.registry.models(),
@@ -270,6 +364,61 @@ export class WsGateway {
         };
       case "list_dirs":
         return { directory: await Directories.list(command.path) };
+      case "refresh_git": {
+        const stream = this.requireStream(connection);
+        await stream.refreshGit(command.fetch === true);
+        return {};
+      }
+      case "list_branches":
+        return {
+          branches: await Git.listBranches(
+            this.requireStream(connection).host.cwd
+          ),
+        };
+      // Reading the repository never moves it, so neither of these takes the `repoBusy` refusal.
+      case "list_changes":
+        return {
+          changes: await RepoDiff.listChanges(
+            this.requireStream(connection).host.cwd,
+            command.base,
+            this.git
+          ),
+        };
+      case "file_diff":
+        return {
+          fileDiff: await RepoDiff.fileDiff(
+            this.requireStream(connection).host.cwd,
+            command.base,
+            command.path,
+            this.git,
+            command.context
+          ),
+        };
+      case "read_lines":
+        return {
+          fileLines: await RepoDiff.readLines(
+            this.requireStream(connection).host.cwd,
+            command.base,
+            command.path,
+            command.spans,
+            this.git
+          ),
+        };
+      case "checkout": {
+        const stream = this.requireStream(connection);
+        return await this.runGit(stream, true, (cwd) =>
+          Git.checkout(cwd, command.branch)
+        );
+      }
+      case "commit":
+        return await this.commit(this.requireStream(connection), command);
+      case "pull":
+      case "push":
+        return await this.runGit(
+          this.requireStream(connection),
+          command.type === "pull",
+          command.type === "pull" ? Git.pull : Git.push
+        );
       case "unwatch_subagent":
         connection.unwatchSubagent(command.callId);
         return {};
@@ -288,6 +437,7 @@ export class WsGateway {
       case "set_cwd": {
         const stream = this.requireStream(connection);
         const result = await stream.host.setCwd(command.value);
+        stream.syncGit();
         stream.push(stream.sessionState());
         if (!result.ok) {
           return { error: result.error };
@@ -365,7 +515,8 @@ export class WsGateway {
     if (path === null) {
       return { error: `malformed call id: ${command.callId}` };
     }
-    if (!(await Bun.file(path).exists())) {
+    // A running call may not have written its log yet; the watch waits for it.
+    if (!stream.isRunning(command.callId) && !(await Bun.file(path).exists())) {
       return { error: `no subagent log for call ${command.callId}` };
     }
     await connection.watchSubagent(
@@ -380,6 +531,7 @@ export class WsGateway {
     connection: ClientConnection,
     command: Command & { readonly type: "attach" }
   ): Promise<Outcome> {
+    const attentive = command.attentive !== false;
     const like =
       command.like === undefined
         ? undefined
@@ -396,27 +548,98 @@ export class WsGateway {
     ]);
     connection.send({
       type: "attached",
-      protocolVersion: PROTOCOL_VERSION,
       sessionId: stream.sessionId,
       cwd: stream.host.cwd,
       head: await stream.refresh(),
       pimVersion,
       piVersion,
     });
-    await connection.attach(stream, command.fromSeq);
+    await connection.attach(stream, command.fromSeq, attentive);
     this.syncWatches();
-    await this.catalogue.markRead(stream.sessionId);
+    if (attentive) {
+      await this.catalogue.markRead(stream.sessionId);
+    }
     return {};
   }
 
-  /** A watch costs a poll, so only sessions someone is reading get one — and the catalogue only while someone is connected. */
+  /** A watch costs a poll, so only attached sessions get one — and the catalogue only while someone is connected. */
   private syncWatches(): void {
     for (const [sessionId, stream] of this.streams) {
-      stream.watchFiles(this.isBeingRead(sessionId));
+      // Attachment, not attention: a hidden tab that lost its watches would stop hearing about the session.
+      stream.watchFiles(this.isAttached(sessionId));
     }
     this.catalogue.watch(this.connections.size > 0);
   }
 
+  /**
+   * An operation that moves the working tree cannot run under an agent that
+   * may be halfway through an edit; `push` leaves the tree alone, so it can.
+   */
+  private async runGit<T = never>(
+    stream: SessionStream,
+    movesTree: boolean,
+    operation: (cwd: string) => Promise<GitRun<T>>
+  ): Promise<Outcome & { readonly value?: T }> {
+    const cwd = stream.host.cwd;
+    if (movesTree && this.repoBusy(cwd)) {
+      return {
+        error: `an agent is working in ${cwd}; wait for its turn to end`,
+      };
+    }
+    const result = await this.git.run<T>(cwd, () => operation(cwd));
+    if (!result.ok) {
+      return { error: result.error };
+    }
+    return result.value === undefined ? {} : { value: result.value };
+  }
+
+  private async commit(
+    stream: SessionStream,
+    command: Command & { readonly type: "commit" }
+  ): Promise<Outcome> {
+    const { value, ...outcome } = await this.runGit<string>(
+      stream,
+      true,
+      async (cwd) => {
+        const result = await Git.commit(cwd, {
+          message: command.message,
+          paths: command.paths,
+        });
+        return result.ok
+          ? { ok: true, value: result.sha }
+          : { ok: false, error: result.error };
+      }
+    );
+    return value === undefined ? outcome : { commit: { sha: value } };
+  }
+
+  private repoBusy(cwd: string): boolean {
+    for (const stream of this.streams.values()) {
+      if (stream.host.cwd === cwd && stream.host.status !== "idle") {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** A turn starting anywhere freezes the branch menu of every session beside it, which only their own state can say. */
+  private syncRepoBusy(cwd: string, source: string): void {
+    const busy = this.repoBusy(cwd);
+    if (this.busyRepos.has(cwd) === busy) {
+      return;
+    }
+    if (busy) {
+      this.busyRepos.add(cwd);
+    } else {
+      this.busyRepos.delete(cwd);
+    }
+    for (const [sessionId, stream] of this.streams) {
+      if (sessionId !== source && stream.host.cwd === cwd) {
+        stream.push(stream.sessionState());
+      }
+    }
+  }
+
   private reload(force: boolean): Outcome {
     const busy = [...this.streams.values()]
       .filter((stream) => stream.host.status !== "idle")
@@ -439,13 +662,20 @@ export class WsGateway {
     return this.versionsRead;
   }
 
+  private isAttached(sessionId: string): boolean {
+    return this.connections
+      .values()
+      .some((connection) => connection.sessionId === sessionId);
+  }
+
+  // The TUI never attaches, so reading a session there clears no dot here and a turn it runs trips no mark.
   private isBeingRead(sessionId: string): boolean {
-    for (const connection of this.connections.values()) {
-      if (connection.sessionId === sessionId) {
-        return true;
-      }
-    }
-    return false;
+    return this.connections
+      .values()
+      .some(
+        (connection) =>
+          connection.sessionId === sessionId && connection.attentive
+      );
   }
 
   private broadcast(event: ServerEvent): void {
@@ -498,12 +728,17 @@ export class WsGateway {
     if (existing) {
       return existing;
     }
-    const stream = new SessionStream(id, host, path);
+    const stream = new SessionStream(id, host, path, {
+      git: this.git,
+      repoBusy: () => this.repoBusy(host.cwd),
+      pollMs: this.pollMs,
+    });
     stream.start();
     this.catalogue.track(id, host.status);
     stream.subscribe((event) => {
       if (event.type === "session_state") {
         this.catalogue.onStatus(id, event.status);
+        this.syncRepoBusy(stream.host.cwd, id);
       }
     });
     this.streams.set(id, stream);