pim-agent 0.9.0 → 0.11.0

package/packages/server/src/SessionStream.ts

@@ -4,10 +4,12 @@ import { PickerService } from "#core/picker/PickerService";
 import { MessageText } from "#core/session/MessageText";
 import type { LeaseState, SessionHost } from "#core/session/SessionHost";
 import { SessionLease, type LeaseRecord } from "#core/session/SessionLease";
+import type { SessionUi, UiAsk } from "#core/session/SessionUi";
 import { FileWatch } from "#core/shared/FileWatch";
-import { Git, type GitState } from "#core/shared/Git";
+import { GitMonitor } from "#core/shared/GitMonitor";
 import { Tools } from "#core/shared/Tools";
-import type { ToolView } from "#core/view/ViewBlock";
+import type { NoticeSeverity, ToolView } from "#core/view/ViewBlock";
+import type { Command } from "#protocol/Command";
 import type {
   EphemeralEvent,
   ServerEvent,
@@ -17,6 +19,21 @@ import { SessionProjection } from "./SessionProjection";
 
 export type StreamListener = (event: ServerEvent) => void;
 
+/** What one client sent back for a `ui_request`; a dismissal is `cancelled`. */
+export type UiAnswer = Omit<
+  Extract<Command, { readonly type: "ui_response" }>,
+  "id" | "type" | "sessionId" | "requestId"
+>;
+
+type PendingRequest = {
+  /** Kept whole: a client that reattaches inside the grace is shown the dialog again. */
+  readonly asked: Extract<EphemeralEvent, { readonly type: "ui_request" }>;
+  /** Answers the waiting extension; only the first call of the first caller lands. */
+  readonly settle: (answer: UiAnswer | undefined, because?: string) => void;
+  readonly expiry: ReturnType<typeof setTimeout>;
+  grace: ReturnType<typeof setTimeout> | undefined;
+};
+
 type LiveTool = {
   readonly callId: string;
   readonly name: string;
@@ -35,7 +52,28 @@ type LiveMessage = {
   readonly tools: LiveTool[];
 };
 
-const GIT_TTL_MS = 5_000;
+export type SessionStreamDeps = {
+  /** How often the file watch falls back to a poll; the default is a second. */
+  readonly pollMs?: number;
+  /** Shared with every other session in the same directory; one is made here when none is given. */
+  readonly git?: GitMonitor;
+  /**
+   * Whether a session in this stream's directory is mid-turn, this one
+   * included. Only the gateway can see the others, so a stream standing alone
+   * reports nothing rather than guessing from itself.
+   */
+  readonly repoBusy?: () => boolean;
+  /** Longest a dialog may hold an extension waiting; defaults to `REQUEST_CEILING_MS`. */
+  readonly requestCeilingMs?: number;
+  /** How long a pending dialog outlives its last reader; defaults to `DETACH_GRACE_MS`. */
+  readonly detachGraceMs?: number;
+};
+
+/** No extension may be parked on a human forever, whatever it asked for; `opts.timeout` still wins when shorter. */
+const REQUEST_CEILING_MS = 180_000;
+
+/** A reload, a tunnel blip and a phone unlock all read as a detach, and all three are back inside this. */
+const DETACH_GRACE_MS = 15_000;
 
 function sameLease(a: LeaseState, b: LeaseState): boolean {
   return (
@@ -46,14 +84,20 @@ function sameLease(a: LeaseState, b: LeaseState): boolean {
 }
 
 /** One session's view of the world, shared by every client attached to it and kept running when none are. */
-export class SessionStream {
+export class SessionStream implements SessionUi {
   public readonly sessionId: string;
   public readonly host: SessionHost;
   public readonly picker: PickerService;
   private readonly sessionPath: string;
   private readonly projection: SessionProjection;
   private readonly listeners = new Set<StreamListener>();
+  private readonly observers = new Set<StreamListener>();
   private readonly pollMs: number | undefined;
+  private readonly git: GitMonitor;
+  private readonly repoBusy: (() => boolean) | undefined;
+  private readonly requestCeilingMs: number;
+  private readonly detachGraceMs: number;
+  private readonly pending = new Map<string, PendingRequest>();
   private liveTurn: LiveMessage[] = [];
   private unsubscribe: (() => void) | undefined;
   private unsubscribeLease: (() => void) | undefined;
@@ -65,23 +109,27 @@ export class SessionStream {
   private drainQueued = false;
   private sentSeq = 0;
   private liveMessageId = 0;
+  private uiSeq = 0;
+  private readonly dispatching: string[] = [];
   private turnStartedAt = 0;
-  private git: GitState = Git.EMPTY;
-  private gitCwd = "";
-  private gitReadAt = 0;
-  private gitInFlight = false;
+  private gitCwd: string | undefined;
+  private gitStop: (() => void) | undefined;
+  private gitBranch: string | null = null;
 
   public constructor(
     sessionId: string,
     host: SessionHost,
     sessionPath: string,
-    /** How often the file watch falls back to a poll; the default is a second. */
-    pollMs?: number
+    deps: SessionStreamDeps = {}
   ) {
     this.sessionId = sessionId;
     this.host = host;
     this.sessionPath = sessionPath;
-    this.pollMs = pollMs;
+    this.pollMs = deps.pollMs;
+    this.git = deps.git ?? new GitMonitor();
+    this.repoBusy = deps.repoBusy;
+    this.requestCeilingMs = deps.requestCeilingMs ?? REQUEST_CEILING_MS;
+    this.detachGraceMs = deps.detachGraceMs ?? DETACH_GRACE_MS;
     this.projection = new SessionProjection(sessionPath, () => host.cwd);
     this.picker = new PickerService({
       cwd: () => host.cwd,
@@ -120,6 +168,7 @@ export class SessionStream {
     if (!active) {
       this.unwatch?.();
       this.unwatch = undefined;
+      this.syncGit();
       return;
     }
     const stops = [
@@ -139,6 +188,37 @@ export class SessionStream {
         stop();
       }
     };
+    this.syncGit();
+  }
+
+  /** Re-points the git watch after the session moves; the monitor is shared, so a repeat is free. */
+  public syncGit(): void {
+    const wanted = this.unwatch === undefined ? undefined : this.host.cwd;
+    if (wanted === this.gitCwd) {
+      return;
+    }
+    this.gitStop?.();
+    this.gitStop = undefined;
+    this.gitCwd = wanted;
+    if (wanted === undefined) {
+      return;
+    }
+    this.gitStop = this.git.watch(wanted, (state) => {
+      // Whoever moved it — this client, the terminal, another window — every
+      // path the pickers hold is from the branch that just left. The first
+      // reading is a discovery rather than a move, and drops nothing.
+      const moved = this.gitBranch !== null && state.branch !== this.gitBranch;
+      this.gitBranch = state.branch;
+      if (moved) {
+        this.invalidatePickers("files");
+      }
+      this.emit(this.sessionState());
+    });
+  }
+
+  /** Reads the repository again for a client that has reason to think its picture is old. */
+  public async refreshGit(fetch: boolean): Promise<void> {
+    await this.git.refresh(this.host.cwd, { fetch });
   }
 
   /** Project whatever pi has appended since the last read, telling every client; returns the head. */
@@ -149,11 +229,192 @@ export class SessionStream {
 
   public subscribe(listener: StreamListener): () => void {
     this.listeners.add(listener);
+    this.holdRequests();
     return () => {
       this.listeners.delete(listener);
+      this.holdRequests();
+    };
+  }
+
+  /**
+   * Hears everything a client hears without counting as one: the server's own
+   * bookkeeping must not make a session nobody is reading look attended, or
+   * the rules below park an extension on a dialog with no eyes on it.
+   */
+  public observe(listener: StreamListener): () => void {
+    this.observers.add(listener);
+    return () => {
+      this.observers.delete(listener);
     };
   }
 
+  /**
+   * Runs `run` as the answer to something the user typed, so anything it says
+   * or asks reaches the client under `command`'s name. A stack rather than a
+   * name: one command handler may prompt another, and the innermost is the
+   * one speaking.
+   */
+  public async dispatch<T>(command: string, run: () => Promise<T>): Promise<T> {
+    this.dispatching.push(command);
+    try {
+      return await run();
+    } finally {
+      this.dispatching.pop();
+    }
+  }
+
+  /** Fire-and-forget: with nobody attached the notice is dropped rather than held. */
+  public notify(text: string, severity: NoticeSeverity): void {
+    this.emit({
+      type: "ui_notice",
+      id: this.nextUiId("notice"),
+      severity,
+      text,
+      ...this.asked(),
+    });
+  }
+
+  /** Whose words these are: the command being dispatched, if any is. */
+  private asked(): { readonly command?: string } {
+    const command = this.dispatching.at(-1);
+    return command === undefined ? {} : { command };
+  }
+
+  public async select(
+    title: string,
+    options: readonly string[],
+    opts?: UiAsk
+  ): Promise<string | undefined> {
+    return (
+      await this.ask({ method: "select", title, options: [...options] }, opts)
+    )?.value;
+  }
+
+  public async confirm(
+    title: string,
+    message: string,
+    opts?: UiAsk
+  ): Promise<boolean> {
+    return (
+      (await this.ask({ method: "confirm", title, message }, opts))
+        ?.confirmed === true
+    );
+  }
+
+  public async input(
+    title: string,
+    placeholder?: string,
+    opts?: UiAsk
+  ): Promise<string | undefined> {
+    return (
+      await this.ask(
+        {
+          method: "input",
+          title,
+          ...(placeholder === undefined ? {} : { placeholder }),
+        },
+        opts
+      )
+    )?.value;
+  }
+
+  /** Whether the answer was taken; a second one for the same request is refused. */
+  public answer(requestId: string, answer: UiAnswer): boolean {
+    const request = this.pending.get(requestId);
+    if (request === undefined) {
+      return false;
+    }
+    request.settle(answer);
+    return true;
+  }
+
+  /** The answer as the client sent it, or `undefined` where it was cancelled, timed out or never asked. */
+  private ask(
+    request: Omit<
+      Extract<ServerEvent, { readonly type: "ui_request" }>,
+      "type" | "requestId" | "command"
+    >,
+    opts: UiAsk | undefined
+  ): Promise<UiAnswer | undefined> {
+    // A headless session may not park an extension on a dialog nobody can see.
+    if (this.listeners.size === 0) {
+      this.answered(request.title, "nobody was attached");
+      return Promise.resolve(undefined);
+    }
+    const requestId = this.nextUiId("request");
+    const waitMs = Math.min(this.requestCeilingMs, opts?.timeout ?? Infinity);
+    const asked = {
+      ...request,
+      ...this.asked(),
+      type: "ui_request",
+      requestId,
+    } as const;
+    return new Promise<UiAnswer | undefined>((resolve) => {
+      const settle = (answer: UiAnswer | undefined, because?: string): void => {
+        const entry = this.pending.get(requestId);
+        if (entry === undefined) {
+          return;
+        }
+        this.pending.delete(requestId);
+        clearTimeout(entry.expiry);
+        clearTimeout(entry.grace);
+        opts?.signal?.removeEventListener("abort", abort);
+        this.emit({ type: "ui_request_done", requestId });
+        if (because !== undefined) {
+          this.answered(asked.title, because);
+        }
+        resolve(answer?.cancelled === true ? undefined : answer);
+      };
+      const abort = (): void => {
+        settle(undefined, "the extension withdrew it");
+      };
+      this.pending.set(requestId, {
+        asked,
+        settle,
+        expiry: setTimeout(() => {
+          settle(undefined, "it timed out");
+        }, waitMs),
+        grace: undefined,
+      });
+      opts?.signal?.addEventListener("abort", abort, { once: true });
+      this.emit(asked);
+      // A listener is never called for a signal that was already spent.
+      if (opts?.signal?.aborted === true) {
+        abort();
+      }
+    });
+  }
+
+  /** A dialog answered by the server is never silent: the human is told what was decided for them. */
+  private answered(title: string, why: string): void {
+    this.notify(`Answered “${title}” for you: ${why}.`, "warn");
+  }
+
+  /** The last reader leaving starts the grace; one arriving inside it calls the whole thing off. */
+  private holdRequests(): void {
+    const detached = this.listeners.size === 0;
+    for (const [requestId, request] of this.pending) {
+      if (!detached) {
+        clearTimeout(request.grace);
+        request.grace = undefined;
+        continue;
+      }
+      request.grace ??= setTimeout(() => {
+        this.pending.get(requestId)?.settle(undefined, "everyone had left");
+      }, this.detachGraceMs);
+    }
+  }
+
+  private nextUiId(kind: "notice" | "request"): string {
+    this.uiSeq += 1;
+    return `${this.sessionId}:${kind}:${this.uiSeq}`;
+  }
+
+  /** Whether `callId` names a tool this session is still running, log written or not. */
+  public isRunning(callId: string): boolean {
+    return this.findTool(callId)?.done === false;
+  }
+
   /** Everything a client at `fromSeq` has not seen: the durable tail, the in-flight turn coalesced, then state. */
   public async replay(fromSeq: number): Promise<readonly StreamEvent[]> {
     await Promise.all([this.flushDurable(), this.readLease()]);
@@ -193,6 +454,11 @@ export class SessionStream {
         }
       }
     }
+    // A dialog is only ever answered by whoever is attached now, so a client
+    // arriving mid-question is handed it rather than left waiting on a grace.
+    for (const request of this.pending.values()) {
+      events.push(request.asked);
+    }
     events.push(this.sessionState());
     return events;
   }
@@ -211,7 +477,9 @@ export class SessionStream {
   public sessionState(): EphemeralEvent {
     const tps = this.host.tps;
     const usage = this.host.usage();
-    const { branch, dirtyCount, ahead, behind } = this.gitState();
+    const cwd = this.host.cwd;
+    const { branch, dirtyCount, ahead, behind, revision } =
+      this.git.stateOf(cwd);
     const modelLabel = this.host.currentModelLabel;
     const turnElapsedMs =
       this.host.status === "idle" || this.turnStartedAt === 0
@@ -219,13 +487,14 @@ export class SessionStream {
         : Date.now() - this.turnStartedAt;
     return {
       type: "session_state",
-      cwd: this.host.cwd,
+      cwd,
       model: this.host.currentModelId ?? "",
       ...(modelLabel === undefined ? {} : { modelLabel }),
       thinking: this.host.currentThinkingLevel,
       cost: this.host.settings.cumulativeCost ?? 0,
       status: this.host.status,
       ...this.leaseState(),
+      ...(this.repoBusy?.() === true ? { repoBusy: true } : {}),
       ...(tps === undefined ? {} : { tps }),
       ...(turnElapsedMs === undefined ? {} : { turnElapsedMs }),
       ...(usage?.percent === null || usage === undefined
@@ -234,7 +503,9 @@ export class SessionStream {
             contextPercent: usage.percent,
             contextWindow: usage.contextWindow,
           }),
-      ...(branch === null ? {} : { branch, dirtyCount, ahead, behind }),
+      ...(branch === null
+        ? {}
+        : { branch, dirtyCount, ahead, behind, repoRevision: revision }),
     };
   }
 
@@ -283,37 +554,6 @@ export class SessionStream {
     }
   }
 
-  private gitState(): GitState {
-    const cwd = this.host.cwd;
-    const moved = cwd !== this.gitCwd;
-    if (moved) {
-      this.gitCwd = cwd;
-      this.git = Git.EMPTY;
-    }
-    if (
-      (moved || Date.now() - this.gitReadAt > GIT_TTL_MS) &&
-      !this.gitInFlight
-    ) {
-      this.gitInFlight = true;
-      void Git.fetchStatus(cwd)
-        .then((next) => {
-          this.gitInFlight = false;
-          this.gitReadAt = Date.now();
-          const changed =
-            next.branch !== this.git.branch ||
-            next.dirtyCount !== this.git.dirtyCount ||
-            next.ahead !== this.git.ahead ||
-            next.behind !== this.git.behind;
-          this.git = next;
-          if (changed) {
-            this.emit(this.sessionState());
-          }
-        })
-        .catch(() => {});
-    }
-    return this.git;
-  }
-
   public dispose(): void {
     this.unsubscribe?.();
     this.unsubscribe = undefined;
@@ -322,7 +562,12 @@ export class SessionStream {
     this.unsubscribeForeign?.();
     this.unsubscribeForeign = undefined;
     this.watchFiles(false);
+    // Deleting the entry each settle clears is what a Map iterator is allowed to outlive.
+    for (const request of this.pending.values()) {
+      request.settle(undefined, "the session stopped");
+    }
     this.listeners.clear();
+    this.observers.clear();
   }
 
   private onAgentEvent(event: AgentSessionEvent): void {
@@ -413,6 +658,8 @@ export class SessionStream {
         });
         if (Tools.effectOf(event.toolName)?.kind !== "readOnly") {
           this.invalidatePickers("files");
+          // The tool just wrote the worktree, which `.git` never reports.
+          void this.git.refresh(this.host.cwd);
         }
         return;
       }
@@ -594,6 +841,11 @@ export class SessionStream {
   }
 
   private emit(event: ServerEvent): void {
+    // Observers first: the bookkeeping one does may broadcast server-wide, and
+    // that belongs ahead of the frame that caused it on every socket.
+    for (const observer of this.observers) {
+      observer(event);
+    }
     for (const listener of this.listeners) {
       listener(event);
     }

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;