@hienlh/ppm 0.23.11 → 0.23.12

package/src/providers/claude-agent-sdk.ts

@@ -1,17 +1,20 @@
 import type { StripMode } from "../services/transcript-images.ts";
 import {
   query,
+  type Query,
   listSessions as sdkListSessions,
   getSessionInfo as sdkGetSessionInfo,
   getSessionMessages,
 } from "@anthropic-ai/claude-agent-sdk";
-import { buildModelQueryOptions, buildSystemPromptOption, designMcpServers, preToolUseDecision } from "./claude-agent-sdk-query-options.ts";
+import { allowedToolsFor, buildModelQueryOptions, buildSystemPromptOption, designMcpServers, preToolUseDecision, READ_ONLY_TOOLS } from "./claude-agent-sdk-query-options.ts";
+import { WarmSpares, spawnFingerprint } from "./claude-warm-spare.ts";
 import { CLAUDE_DESIGN_CHECK_TOOL } from "../services/design/mcp/design-mcp-tool.ts";
 import { designToolDecision } from "../services/design/design-tool-policy.ts";
 import { CLAUDE_MODELS } from "../types/claude-models.ts";
 import { isImageLimitRejection } from "./image-limit-detection.ts";
 import type {
   AIProvider,
+  PrewarmInput,
   Session,
   SessionConfig,
   SessionInfo,
@@ -38,7 +41,7 @@ import { isCompiledBinary } from "../services/autostart-generator.ts";
 import { resolveClaudeCliPath } from "../services/claude-cli-resolver.ts";
 import { resolve, dirname } from "node:path";
 import { existsSync, readdirSync, unlinkSync, readFileSync, statSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, totalmem } from "node:os";
 
 const CLAUDE_PROJECTS_DIR = resolve(homedir(), ".claude/projects");
 
@@ -238,6 +241,10 @@ export class ClaudeAgentSdkProvider implements AIProvider {
    * and this is the only place that knows what made it do so.
    */
   private teardownReasons = new Map<string, string>();
+  /** CLIs started for chats that do not exist yet — see `prewarm`. */
+  private readonly warmSpares = new WarmSpares<Query>();
+  /** Hosts with less RAM keep no warm CLI: each one holds ~500 MB while it waits. */
+  private minWarmSpareHostMemory = 8 * 1024 ** 3;
 
   /** Auth-related env keys for diagnostic logging */
   private readonly AUTH_ENV_KEYS = ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN"];
@@ -510,7 +517,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
   }
 
   async createSession(config: SessionConfig): Promise<Session> {
-    const id = crypto.randomUUID();
+    const id = (config.adoptWarmSpare && config.projectPath && this.warmSpares.claim(config.projectPath)) || crypto.randomUUID();
     const meta: Session = {
       id,
       providerId: this.id,
@@ -811,6 +818,131 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     return process.env.CLAUDE_CODE_OAUTH_TOKEN ? SUBSCRIPTION_PROMPT_CACHE_TTL_MS : API_KEY_PROMPT_CACHE_TTL_MS;
   }
 
+  /**
+   * What a turn spawns the CLI with. `sendMessage` and `prewarm` both build it here, so a
+   * warm spare is only ever taken over by a turn that would have started that same process
+   * (`spawnFingerprint` compares the two).
+   */
+  private buildQueryOptions(p: {
+    sessionId?: string;
+    resume?: string;
+    forkSession?: boolean;
+    cwd: string;
+    systemPrompt: ReturnType<typeof buildSystemPromptOption>;
+    env: Record<string, string | undefined>;
+    allowedTools: string[];
+    mcpServers: Record<string, unknown>;
+    permissionMode: string;
+    opts?: Pick<import("./provider.interface.ts").SendMessageOpts, "model" | "oneMContext" | "effort" | "thinkingBudget" | "maxTurns">;
+    providerConfig: Partial<import("../types/config.ts").AIProviderConfig>;
+    stderr: (chunk: string) => void;
+  }): Record<string, any> {
+    // 1M context (GA): the CLI enables a 1M window when the model name carries a
+    // [1m] suffix. The suffix is stripped before the API call. Requires an entitled
+    // account (Max/Team/Enterprise) and a supported model; otherwise the API errors.
+    // Per-call overrides win over provider config (lightweight calls can opt out of 1M;
+    // the chat input picker sets per-session model/effort/thinking). Effort enum is
+    // guarded inside the helper — "extra" would crash the CLI subprocess.
+    const mqo = buildModelQueryOptions(
+      {
+        model: p.opts?.model,
+        oneMContext: p.opts?.oneMContext,
+        effort: p.opts?.effort,
+        thinkingBudget: p.opts?.thinkingBudget,
+      },
+      p.providerConfig,
+    );
+
+    // Compiled binaries have no node_modules → resolve a Claude CLI explicitly
+    // (system claude or the one shipped in cli/). Source installs → undefined
+    // (SDK self-resolves from node_modules, unchanged).
+    const cliExecutablePath = resolveCliExecutablePath(
+      (p.providerConfig as { cli_command?: string }).cli_command,
+    );
+
+    return {
+      // Run the CLI under node only for a .js entry (or the win32 source-mode
+      // default). A native claude(.exe) must be spawned directly.
+      ...(needsNodeInterpreter(process.platform, cliExecutablePath) && { executable: "node" }),
+      ...(cliExecutablePath && { pathToClaudeCodeExecutable: cliExecutablePath }),
+      sessionId: p.sessionId,
+      resume: p.resume,
+      ...(p.forkSession && { forkSession: true }),
+      cwd: p.cwd,
+      systemPrompt: p.systemPrompt,
+      settingSources: ["user", "project"],
+      env: p.env,
+      settings: { permissions: { allow: [], deny: [] } },
+      allowedTools: p.allowedTools,
+      ...(Object.keys(p.mcpServers).length > 0 && { mcpServers: p.mcpServers }),
+      permissionMode: p.permissionMode,
+      allowDangerouslySkipPermissions: p.permissionMode === "bypassPermissions",
+      ...(mqo.model && { model: mqo.model }),
+      ...(mqo.effort && { effort: mqo.effort }),
+      maxTurns: p.opts?.maxTurns ?? p.providerConfig.max_turns ?? 1000,
+      ...(p.providerConfig.max_budget_usd && { maxBudgetUsd: p.providerConfig.max_budget_usd }),
+      ...(mqo.thinking && { thinking: mqo.thinking }),
+      // Beta headers are honored only for API-key auth; OAuth/subscription sessions
+      // reject them ("Custom betas are only available for API key users") and crash the
+      // subprocess. Entitled OAuth accounts still get 1M context via the [1m] model suffix.
+      ...(mqo.use1m && !!p.env.ANTHROPIC_API_KEY && { betas: ["context-1m-2025-08-07"] }),
+      includePartialMessages: true,
+      stderr: p.stderr,
+    };
+  }
+
+  /**
+   * Start the CLI the next chat created in `projectPath` will run on, so that chat's first
+   * message does not wait ~1.4 s for it to boot (`claude-warm-spare.ts` has the numbers).
+   * Given the settings the message will carry, the options are built exactly as
+   * `sendMessage` builds them; anything this cannot foresee only makes that turn start cold.
+   */
+  async prewarm(input: PrewarmInput): Promise<void> {
+    const { projectPath, accountId, opts } = input;
+    if (!existsSync(projectPath) || totalmem() < this.minWarmSpareHostMemory) return;
+    const providerConfig = this.getProviderConfig();
+    const permissionMode = opts?.permissionMode || providerConfig.permission_mode || "bypassPermissions";
+    const isBypass = permissionMode === "bypassPermissions";
+
+    let account: AccountWithTokens | null = null;
+    if (accountSelector.isEnabled()) {
+      // The session will be bound to the account its tab claimed, and its turn runs on that
+      // one. Without a claim the turn's own pick cannot be foreseen, so nothing is started.
+      if (!accountId || !accountSelector.canServe(accountId)) return;
+      account = await accountService.ensureFreshToken(accountId);
+      if (!account) return;
+      // What `sendMessage` does too: a background refresh may have rotated the token.
+      account = accountService.getWithTokens(accountId) ?? account;
+    }
+
+    const options = this.buildQueryOptions({
+      cwd: projectPath,
+      systemPrompt: buildSystemPromptOption(providerConfig.system_prompt),
+      env: this.buildQueryEnv(projectPath, account),
+      allowedTools: allowedToolsFor({ isBypass, agentTeams: providerConfig.agent_teams }),
+      mcpServers: this.resolveMcpServers(projectPath),
+      permissionMode,
+      opts,
+      providerConfig,
+      stderr: () => {},
+    });
+    this.warmSpares.offer(projectPath, spawnFingerprint(options), (sessionId, callbacks) => {
+      const { generator, controller } = createMessageChannel();
+      const q = query({
+        prompt: generator,
+        options: {
+          ...options,
+          sessionId,
+          stderr: callbacks.stderr,
+          ...(!isBypass && { hooks: { PreToolUse: [{ matcher: ".*", hooks: [callbacks.preToolUse] }] } }),
+          canUseTool: callbacks.canUseTool,
+        } as any,
+      });
+      console.log(`[sdk] session=${sessionId} warm CLI started for ${projectPath}`);
+      return { query: q, controller };
+    });
+  }
+
   async *sendMessage(
     _sessionId: string,
     message: string,
@@ -899,26 +1031,9 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     // No project root means nothing can be proven inside it, so every file tool asks.
     const designRoot = designPolicy && meta.projectPath && existsSync(meta.projectPath) ? meta.projectPath : undefined;
 
-    // Build allowedTools based on permission mode.
-    // SDK auto-approves everything in allowedTools (skips canUseTool callback).
-    // In non-bypass modes, only pre-approve read-only tools so write/execute tools
-    // go through the permission evaluation chain → canUseTool callback.
-    // The design policy pre-approves nothing: the read-only list would let Read and Grep
-    // reach any path on disk and every MCP tool run unasked, which is exactly what a
-    // design session's agent (fed page content it did not write) must not do.
-    const readOnlyTools = ["Read", "Glob", "Grep", "WebSearch", "WebFetch", "ToolSearch"];
-    const writeTools = ["Write", "Edit", "Bash", "Agent", "Skill", "TodoWrite", "AskUserQuestion"];
-    const teamTools = providerConfig.agent_teams
-      ? ["TeamCreate", "TeamDelete", "SendMessage", "TaskCreate", "TaskUpdate", "TaskList", "TaskGet"]
-      : [];
-    const mcpTools = ["mcp__*"];
     // `design_check` only reads the canvas, so a design session never asks before it runs.
     const designCheckTool = opts?.designSession && opts.designMcp ? CLAUDE_DESIGN_CHECK_TOOL : null;
-    const allowedTools = designPolicy
-      ? (designCheckTool ? [designCheckTool] : [])
-      : isBypass
-        ? [...readOnlyTools, ...writeTools, ...teamTools, ...mcpTools]
-        : [...readOnlyTools, ...mcpTools];
+    const allowedTools = allowedToolsFor({ isBypass, agentTeams: providerConfig.agent_teams, designPolicy, designCheckTool });
 
     /**
      * Approval events to yield from the generator.
@@ -991,7 +1106,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         if (designToolDecision(toolName, hookInput?.tool_input, designRoot) === "allow") {
           return preToolUseDecision("allow");
         }
-      } else if (readOnlyTools.includes(toolName)) {
+      } else if (READ_ONLY_TOOLS.includes(toolName)) {
         // Read-only tools: always allow
         return {};
       }
@@ -1148,61 +1263,21 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         console.log(`[sdk] session=${sessionId} mcpServers: ${Object.keys(mcpServers).join(", ")}`);
       }
 
-      // 1M context (GA): the CLI enables a 1M window when the model name carries a
-      // [1m] suffix. The suffix is stripped before the API call. Requires an entitled
-      // account (Max/Team/Enterprise) and a supported model; otherwise the API errors.
-      // Per-call overrides win over provider config (lightweight calls can opt out of 1M;
-      // the chat input picker sets per-session model/effort/thinking). Effort enum is
-      // guarded inside the helper — "extra" would crash the CLI subprocess.
-      const mqo = buildModelQueryOptions(
-        {
-          model: opts?.model,
-          oneMContext: opts?.oneMContext,
-          effort: opts?.effort,
-          thinkingBudget: opts?.thinkingBudget,
-        },
-        providerConfig,
-      );
-      const resolvedModel = mqo.model;
-      const use1m = mqo.use1m;
-
-      // Compiled binaries have no node_modules → resolve a Claude CLI explicitly
-      // (system claude or the one shipped in cli/). Source installs → undefined
-      // (SDK self-resolves from node_modules, unchanged).
-      const cliExecutablePath = resolveCliExecutablePath(
-        (providerConfig as { cli_command?: string }).cli_command,
-      );
-
-      const queryOptions: Record<string, any> = {
-        // Run the CLI under node only for a .js entry (or the win32 source-mode
-        // default). A native claude(.exe) must be spawned directly.
-        ...(needsNodeInterpreter(process.platform, cliExecutablePath) && { executable: "node" }),
-        ...(cliExecutablePath && { pathToClaudeCodeExecutable: cliExecutablePath }),
+      const queryOptions = this.buildQueryOptions({
         // First message: create session with this ID. Subsequent: resume by same ID.
         sessionId: isFirstMessage && !shouldFork ? sessionId : undefined,
         resume: (isFirstMessage && !shouldFork) ? undefined : (shouldFork ? forkSourceId : sessionId),
-        ...(shouldFork && { forkSession: true }),
+        forkSession: shouldFork,
         cwd: effectiveCwd,
         systemPrompt: systemPromptOpt,
-        settingSources: ["user", "project"],
         env: queryEnv,
-        settings: { permissions: { allow: [], deny: [] } },
         allowedTools,
-        ...(hasMcp && { mcpServers }),
+        mcpServers,
         permissionMode,
-        allowDangerouslySkipPermissions: isBypass,
-        ...(resolvedModel && { model: resolvedModel }),
-        ...(mqo.effort && { effort: mqo.effort }),
-        maxTurns: opts?.maxTurns ?? providerConfig.max_turns ?? 1000,
-        ...(providerConfig.max_budget_usd && { maxBudgetUsd: providerConfig.max_budget_usd }),
-        ...(mqo.thinking && { thinking: mqo.thinking }),
-        // Beta headers are honored only for API-key auth; OAuth/subscription sessions
-        // reject them ("Custom betas are only available for API key users") and crash the
-        // subprocess. Entitled OAuth accounts still get 1M context via the [1m] model suffix.
-        ...(use1m && !!queryEnv.ANTHROPIC_API_KEY && { betas: ["context-1m-2025-08-07"] }),
-        includePartialMessages: true,
+        opts,
+        providerConfig,
         stderr: stderrCallback,
-      };
+      });
 
       // Crash retry: if subprocess exits with non-zero code before producing events,
       // clean up and retry once with a fresh query before surfacing the error.
@@ -1252,21 +1327,28 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         };
       };
 
-      const { generator: streamGen, controller: initialCtrl } = createMessageChannel();
+      // A new session's first attempt takes over the CLI `prewarm` started for it, if that
+      // is exactly the process it would have spawned; otherwise it spawns one as always.
+      const spare = crashRetryCount === 0 && isFirstMessage && !shouldFork
+        ? this.warmSpares.adopt(sessionId, spawnFingerprint(queryOptions), { canUseTool, preToolUse: preToolUseHook, stderr: stderrCallback })
+        : undefined;
+      const channel = spare ? undefined : createMessageChannel();
+      const initialCtrl = spare?.controller ?? channel!.controller;
       // On crash retry, use buildRetryMsg to get the latest user message (not the stale firstMsg)
       const initRetry = crashRetryCount > 0 ? buildRetryMsg() : null;
       initialCtrl.push(initRetry?.msg ?? firstMsg);
       const initContent = initRetry?.lastUserContent ?? modelInput;
       const initImages = initRetry?.lastUserImages ?? opts?.images;
 
-      const initialQuery = query({
-        prompt: streamGen,
+      const initialQuery = spare?.query ?? query({
+        prompt: channel!.generator,
         options: {
           ...queryOptions,
           ...(permissionHooks && { hooks: permissionHooks }),
           canUseTool,
         } as any,
       });
+      if (spare) console.log(`[sdk] session=${sessionId} took over the warm CLI started ${spare.ageMs} ms ago`);
       this.streamingSessions.set(sessionId, { meta, query: initialQuery, controller: initialCtrl, lastUserContent: initContent, lastUserImages: initImages });
       this.activeQueries.set(sessionId, initialQuery);
       let eventSource: AsyncIterable<any> = initialQuery;

package/src/providers/claude-warm-spare.ts

@@ -0,0 +1,176 @@
+/**
+ * A Claude CLI started before the chat that will use it exists.
+ *
+ * A new chat's first message used to wait for the CLI to boot before anything reached the
+ * API. Measured against a local stub API, so the figure is the CLI's own: 1.33–1.53 s from
+ * the message to the request, against 37–43 ms for a CLI started a few seconds earlier and
+ * waiting on stdin. The price is ~500 MB of RAM (the CLI plus the MCP servers it starts)
+ * and ~2.5% of a core while it waits — hence spares exist only while a new-chat composer is
+ * open, expire when nobody touches it, and are capped.
+ *
+ * A spare is spawned under a session id chosen now. `claim` hands that id to the next chat
+ * created in the project, and that chat's first turn takes the process over through `adopt`
+ * — but only when every option it would spawn a CLI with is the one the spare was spawned
+ * with. Any difference (another model, a rotated token, an edited MCP list) closes the spare
+ * and the turn starts cold, so a stale spare can cost the speed-up but never the behaviour.
+ * A spare closed unused has written nothing (the CLI creates the transcript on the first
+ * message), which is what lets its id go on to a cold start.
+ */
+import { createHash } from "node:crypto";
+
+/** The per-turn callbacks a CLI is spawned with. A spare's forward to the turn that adopts it. */
+export interface SpareHandlers {
+  canUseTool: (...args: any[]) => Promise<any>;
+  preToolUse: (...args: any[]) => Promise<any>;
+  stderr: (chunk: string) => void;
+}
+
+export interface SpareProcess<Q> {
+  query: Q;
+  controller: { push(msg: unknown): void; done(): void };
+}
+
+interface Spare<Q> extends SpareProcess<Q> {
+  key: string;
+  sessionId: string;
+  fingerprint: string;
+  startedAt: number;
+  claimed: boolean;
+  handlers?: SpareHandlers;
+  /** What the CLI wrote to stderr before a turn took it, handed to that turn's handler. */
+  stderr: string;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+export interface WarmSpareLimits {
+  /** How long a spare nobody claims stays, from the last `offer` for its key. */
+  idleMs: number;
+  /** How long a claimed spare waits for its session's first message. */
+  claimedMs: number;
+  /** Spares alive at once, across every project. */
+  max: number;
+}
+
+const DEFAULT_LIMITS: WarmSpareLimits = { idleMs: 5 * 60_000, claimedMs: 60_000, max: 2 };
+
+export class WarmSpares<Q extends { close(): void; initializationResult?(): Promise<unknown> }> {
+  private readonly spares = new Map<string, Spare<Q>>();
+
+  constructor(private readonly limits: WarmSpareLimits = DEFAULT_LIMITS) {}
+
+  /**
+   * Keep a spare ready for `key`. One already waiting there with the same fingerprint is kept
+   * and its expiry pushed back; one with any other is replaced. Returns the waiting spare's
+   * session id.
+   */
+  offer(key: string, fingerprint: string, start: (sessionId: string, callbacks: SpareHandlers) => SpareProcess<Q>): string {
+    const waiting = this.waiting(key);
+    if (waiting?.fingerprint === fingerprint) {
+      this.expireIn(waiting, this.limits.idleMs);
+      return waiting.sessionId;
+    }
+    if (waiting) this.close(waiting);
+    // Oldest first, and a claimed spare last: its first message is at most seconds away.
+    for (const victim of [...this.spares.values()].sort((a, b) => Number(a.claimed) - Number(b.claimed))) {
+      if (this.spares.size < this.limits.max) break;
+      this.close(victim);
+    }
+
+    const spare: Spare<Q> = {
+      key, fingerprint, sessionId: crypto.randomUUID(), startedAt: Date.now(), claimed: false, stderr: "",
+    } as Spare<Q>;
+    const callbacks: SpareHandlers = {
+      // Nothing can ask before a turn has pushed a message; refusing is the safe answer anyway.
+      canUseTool: (...args) => spare.handlers
+        ? spare.handlers.canUseTool(...args)
+        : Promise.resolve({ behavior: "deny", message: "No turn has taken this process over yet" }),
+      preToolUse: (...args) => spare.handlers ? spare.handlers.preToolUse(...args) : Promise.resolve({}),
+      stderr: (chunk) => {
+        if (spare.handlers) spare.handlers.stderr(chunk);
+        else spare.stderr = (spare.stderr + chunk).slice(-2048);
+      },
+    };
+    Object.assign(spare, start(spare.sessionId, callbacks));
+    this.spares.set(spare.sessionId, spare);
+    this.expireIn(spare, this.limits.idleMs);
+    // A CLI that dies during startup (a broken MCP entry, a missing binary) says so here;
+    // dropping it keeps a turn from adopting a process that is already gone.
+    spare.query.initializationResult?.().catch(() => {
+      if (this.spares.get(spare.sessionId) === spare) this.close(spare);
+    });
+    return spare.sessionId;
+  }
+
+  /** Hand the spare waiting for `key` to the session being created there. */
+  claim(key: string): string | undefined {
+    const spare = this.waiting(key);
+    if (!spare) return undefined;
+    spare.claimed = true;
+    this.expireIn(spare, this.limits.claimedMs);
+    return spare.sessionId;
+  }
+
+  /**
+   * Take over the spare started for `sessionId`, if the turn would have spawned exactly it.
+   * One that differs is closed rather than kept: its session is starting cold, and no other
+   * session can have its id.
+   */
+  adopt(sessionId: string, fingerprint: string, handlers: SpareHandlers): (SpareProcess<Q> & { ageMs: number }) | undefined {
+    const spare = this.spares.get(sessionId);
+    if (!spare) return undefined;
+    this.forget(spare);
+    if (spare.fingerprint !== fingerprint) {
+      console.log(`[sdk] session=${sessionId} warm CLI does not match this turn's options — starting cold`);
+      this.stop(spare);
+      return undefined;
+    }
+    spare.handlers = handlers;
+    if (spare.stderr) handlers.stderr(spare.stderr);
+    return { query: spare.query, controller: spare.controller, ageMs: Date.now() - spare.startedAt };
+  }
+
+  closeAll(): void {
+    for (const spare of [...this.spares.values()]) this.close(spare);
+  }
+
+  private waiting(key: string): Spare<Q> | undefined {
+    for (const spare of this.spares.values()) if (spare.key === key && !spare.claimed) return spare;
+    return undefined;
+  }
+
+  private expireIn(spare: Spare<Q>, ms: number): void {
+    clearTimeout(spare.timer);
+    spare.timer = setTimeout(() => this.close(spare), ms);
+    spare.timer.unref?.();
+  }
+
+  private close(spare: Spare<Q>): void {
+    this.forget(spare);
+    this.stop(spare);
+  }
+
+  private forget(spare: Spare<Q>): void {
+    clearTimeout(spare.timer);
+    this.spares.delete(spare.sessionId);
+  }
+
+  private stop(spare: Spare<Q>): void {
+    spare.controller.done();
+    spare.query.close();
+  }
+}
+
+/**
+ * A digest of every option a CLI is spawned with but its session id. Functions do not
+ * serialise and have no say; everything else — the environment and its token included —
+ * does, which is also why this is a digest and not the text.
+ */
+export function spawnFingerprint(options: Record<string, unknown>): string {
+  const { sessionId: _sessionId, ...rest } = options;
+  return createHash("sha256").update(JSON.stringify(rest, sortKeys)).digest("hex");
+}
+
+function sortKeys(_key: string, value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  return Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}

package/src/providers/provider.interface.ts

@@ -9,5 +9,6 @@ export type {
   UsageInfo,
   LimitBucket,
   SendMessageOpts,
+  PrewarmInput,
   ModelOption,
 } from "../types/chat.ts";

package/src/server/index.ts

@@ -33,8 +33,10 @@ import { globalWebSocket } from "./ws/global.ts";
 import { groupChatWebSocket } from "./ws/group-chat.ts";
 import { remoteDesktopWebSocket } from "./ws/remote-desktop.ts";
 import { lspWebSocket } from "./ws/lsp.ts";
+import { androidWebSocket } from "./ws/android.ts";
 import { lspManager } from "../services/lsp/lsp-manager.ts";
 import { isRemoteDesktopEnabled } from "../services/remote-desktop/remote-desktop-flag.ts";
+import { isAndroidEmulatorEnabled } from "../services/android/android-flag.ts";
 import { ok, err } from "../types/api.ts";
 
 /** Tee console.log/error to ~/.ppm/ppm.log while preserving terminal output */
@@ -239,6 +241,12 @@ app.get("/api/system/event-loop", async (c) => {
 import { remoteDesktopRoutes } from "./routes/remote-desktop.ts";
 app.route("/api/remote-desktop", remoteDesktopRoutes);
 
+// Android emulator — OFF by default, opt-in via ANDROID_EMULATOR_ENABLED=1, see android-flag.ts.
+// Unlike remote desktop this spawns multi-gigabyte emulator processes, and most hosts have no
+// Android SDK at all, so it stays dark until somebody asks for it.
+import { androidRoutes } from "./routes/android.ts";
+app.route("/api/android", androidRoutes);
+
 // Finishes an OAuth loopback login started from another device
 import { loopbackRoutes } from "./routes/oauth-loopback.ts";
 app.route("/api/loopback", loopbackRoutes);
@@ -270,6 +278,10 @@ app.route("/api/jira", jiraRoutes);
 import { schedulesRoutes } from "./routes/schedules.ts";
 app.route("/api/schedules", schedulesRoutes);
 
+// Session trace — browser logs in, a session's timeline out
+import { traceRoutes } from "./routes/trace.ts";
+app.route("/api/trace", traceRoutes);
+
 // AI resources (skills / agents / commands) management
 import { aiResourcesRoutes } from "./routes/ai-resources.ts";
 app.route("/api/ai-resources", aiResourcesRoutes);
@@ -879,6 +891,30 @@ if (process.argv.includes("__serve__")) {
     setInterval(runCleanup, 24 * 60 * 60 * 1000);
   }
 
+  // Same again for the session trace: age, then size. Skipped until something has been traced.
+  {
+    const { existsSync } = await import("node:fs");
+    const { getTraceDbPath } = await import("../services/session-trace/session-trace-db.ts");
+    const { cleanupSessionTrace } = await import("../services/session-trace/session-trace-cleanup.ts");
+
+    const runTraceCleanup = () => {
+      if (!existsSync(getTraceDbPath())) return;
+      try {
+        const { retention_days, max_size_mb } = configService.get("session_trace");
+        const { deletedByAge, deletedBySize, freedBytes } = cleanupSessionTrace(retention_days, max_size_mb);
+        const removed = deletedByAge + deletedBySize;
+        if (removed > 0) {
+          console.log(`[session-trace] pruned ${removed} rows (${(freedBytes / 1024 / 1024).toFixed(1)} MB freed)`);
+        }
+      } catch (e) {
+        console.error(`[session-trace] cleanup failed: ${(e as Error).message}`);
+      }
+    };
+
+    runTraceCleanup();
+    setInterval(runTraceCleanup, 24 * 60 * 60 * 1000);
+  }
+
   // On Windows the supervisor reaps the previous server's whole process tree
   // before respawning, so the port is released cleanly. A lingering bind can
   // still appear for a moment during an upgrade handoff, so wait for it to
@@ -959,6 +995,20 @@ if (process.argv.includes("__serve__")) {
         return new Response("WebSocket upgrade failed", { status: 400 });
       }
 
+      if (url.pathname === "/ws/android") {
+        // Same shape and the same reasoning as the remote-desktop branch above: an explicit
+        // branch so this can never fall through to the terminal (shell) handler, with the flag
+        // and `auth.enabled` re-checked independently of `isWsUpgradeAuthorized`, which returns
+        // true unconditionally when PPM auth is disabled.
+        if (!isAndroidEmulatorEnabled()) return new Response("Not Found", { status: 404 });
+        if (!configService.get("auth").enabled) {
+          return new Response("Forbidden: android emulator control requires PPM authentication to be enabled", { status: 403 });
+        }
+        const upgraded = server.upgrade(req, { data: { type: "android" } });
+        if (upgraded) return undefined;
+        return new Response("WebSocket upgrade failed", { status: 400 });
+      }
+
       if (url.pathname.startsWith("/ws/project/")) {
         const parts = url.pathname.split("/");
         const projectName = decodeURIComponent(parts[3] ?? "");
@@ -1014,6 +1064,7 @@ if (process.argv.includes("__serve__")) {
         else if (t === "extensions") extensionWebSocket.open(ws);
         else if (t === "global") globalWebSocket.open(ws);
         else if (t === "remote-desktop") remoteDesktopWebSocket.open(ws);
+        else if (t === "android") androidWebSocket.open(ws);
         else if (t === "terminal") terminalWebSocket.open(ws);
         else if (t === "lsp") lspWebSocket.open(ws);
         else ws.close(1008, "unknown socket type");
@@ -1025,6 +1076,7 @@ if (process.argv.includes("__serve__")) {
         else if (t === "extensions") extensionWebSocket.message(ws, msg);
         else if (t === "global") globalWebSocket.message(ws, msg);
         else if (t === "remote-desktop") remoteDesktopWebSocket.message(ws, msg);
+        else if (t === "android") androidWebSocket.message(ws, msg);
         else if (t === "terminal") terminalWebSocket.message(ws, msg);
         else if (t === "lsp") lspWebSocket.message(ws, msg);
       },
@@ -1035,6 +1087,7 @@ if (process.argv.includes("__serve__")) {
         else if (t === "extensions") extensionWebSocket.close(ws);
         else if (t === "global") globalWebSocket.close(ws);
         else if (t === "remote-desktop") remoteDesktopWebSocket.close(ws);
+        else if (t === "android") androidWebSocket.close(ws);
         else if (t === "terminal") terminalWebSocket.close(ws);
         else if (t === "lsp") lspWebSocket.close(ws);
       },

package/src/server/middleware/gzip-json.ts

@@ -5,9 +5,20 @@
  * untouched. JSON compresses ~5-8x; a 542KB file index becomes ~80KB on the wire.
  */
 import type { MiddlewareHandler } from "hono";
+import { gzip } from "node:zlib";
+import { promisify } from "node:util";
 
 const MIN_SIZE_BYTES = 1024;
 
+/**
+ * From this size on, compress on zlib's thread pool instead of the event loop. `Bun.gzipSync`
+ * stopped the server for 93 ms on each download of nxsys-workspace's 22 MB file index, while the
+ * pool left it waiting 3 ms at most. Below it the synchronous call blocks for well under a
+ * millisecond (0.3 ms for 200 KB) and answers sooner than the pool does.
+ */
+const ASYNC_FROM_BYTES = 256 * 1024;
+const gzipAsync = promisify(gzip);
+
 export const gzipJson: MiddlewareHandler = async (c, next) => {
   await next();
 
@@ -27,7 +38,8 @@ export const gzipJson: MiddlewareHandler = async (c, next) => {
     return;
   }
 
-  const gzipped = Bun.gzipSync(new Uint8Array(body));
+  const bytes = new Uint8Array(body);
+  const gzipped = body.byteLength < ASYNC_FROM_BYTES ? Bun.gzipSync(bytes) : await gzipAsync(bytes);
   const headers = new Headers(res.headers);
   headers.set("Content-Encoding", "gzip");
   headers.set("Content-Length", String(gzipped.byteLength));