@hienlh/ppm 0.23.11 → 0.23.12

package/src/shared/android-protocol.ts

@@ -0,0 +1,184 @@
+/**
+ * The `/ws/android` wire format, version 1. Shared by `src/server/ws/android.ts` and the
+ * browser viewer so neither can drift from the other.
+ *
+ * Text frames are JSON control messages; binary frames are video. Video never travels as
+ * base64 inside JSON — that is a 33% tax on the one thing that has a bandwidth budget.
+ *
+ * Two generations ride on every message, and they answer different questions:
+ *  - `sessionGeneration` changes when control moves to another client (a Take control). It is
+ *    what lets the server drop input from a client that has been superseded but does not yet
+ *    know it.
+ *  - `geometryGeneration` changes when the frame size or rotation changes. Input carrying an
+ *    old geometry describes a screen that no longer exists, so it is rejected rather than
+ *    mapped onto the new one — the plan's "Reject input theo geometry cũ".
+ */
+
+export const ANDROID_PROTOCOL_VERSION = 1;
+
+// ---------------------------------------------------------------------------------------------
+// Binary video framing
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Header laid out little-endian, then the Annex-B payload:
+ *
+ *   0  u8   protocol version
+ *   1  u8   flags  (bit0 = keyframe, bit1 = codec config)
+ *   2  u16  session generation
+ *   4  u16  geometry generation
+ *   6  u32  sequence number
+ *  10  f64  presentation timestamp, milliseconds since the session began
+ *  18  u32  payload length
+ *  22  ...  payload
+ *
+ * The length is carried even though a WS frame already delimits itself, because a proxy that
+ * coalesces or splits frames would otherwise be undetectable — a truncated access unit decodes
+ * to garbage rather than failing.
+ */
+export const VIDEO_HEADER_BYTES = 22;
+
+export const VIDEO_FLAG_KEYFRAME = 1 << 0;
+export const VIDEO_FLAG_CODEC_CONFIG = 1 << 1;
+
+export interface VideoFrameHeader {
+  version: number;
+  keyframe: boolean;
+  codecConfig: boolean;
+  sessionGeneration: number;
+  geometryGeneration: number;
+  sequence: number;
+  ptsMs: number;
+  payloadLength: number;
+}
+
+export function encodeVideoFrame(header: Omit<VideoFrameHeader, "version" | "payloadLength">, payload: Uint8Array): Uint8Array {
+  const out = new Uint8Array(VIDEO_HEADER_BYTES + payload.length);
+  const view = new DataView(out.buffer);
+  view.setUint8(0, ANDROID_PROTOCOL_VERSION);
+  view.setUint8(1, (header.keyframe ? VIDEO_FLAG_KEYFRAME : 0) | (header.codecConfig ? VIDEO_FLAG_CODEC_CONFIG : 0));
+  view.setUint16(2, header.sessionGeneration, true);
+  view.setUint16(4, header.geometryGeneration, true);
+  view.setUint32(6, header.sequence, true);
+  view.setFloat64(10, header.ptsMs, true);
+  view.setUint32(18, payload.length, true);
+  out.set(payload, VIDEO_HEADER_BYTES);
+  return out;
+}
+
+/** Returns null when the buffer is too short or the declared length disagrees with what arrived. */
+export function decodeVideoFrame(buf: ArrayBuffer | Uint8Array): { header: VideoFrameHeader; payload: Uint8Array } | null {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  if (bytes.length < VIDEO_HEADER_BYTES) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const flags = view.getUint8(1);
+  const payloadLength = view.getUint32(18, true);
+  if (bytes.length - VIDEO_HEADER_BYTES !== payloadLength) return null;
+  return {
+    header: {
+      version: view.getUint8(0),
+      keyframe: (flags & VIDEO_FLAG_KEYFRAME) !== 0,
+      codecConfig: (flags & VIDEO_FLAG_CODEC_CONFIG) !== 0,
+      sessionGeneration: view.getUint16(2, true),
+      geometryGeneration: view.getUint16(4, true),
+      sequence: view.getUint32(6, true),
+      ptsMs: view.getFloat64(10, true),
+      payloadLength,
+    },
+    payload: bytes.subarray(VIDEO_HEADER_BYTES),
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Control messages
+// ---------------------------------------------------------------------------------------------
+
+export interface AndroidGeometry {
+  /** Frame size actually being encoded. */
+  width: number;
+  height: number;
+  /** The guest's own display size, which the frame may be a scaled copy of. */
+  deviceWidth: number;
+  deviceHeight: number;
+  rotation: 0 | 90 | 180 | 270;
+  generation: number;
+}
+
+export type AndroidQuality = "low" | "balanced" | "high";
+
+/** Client -> server. */
+export type AndroidClientMessage =
+  | { type: "auth"; nonce: string; quality?: AndroidQuality; viewport?: { width: number; height: number } }
+  | { type: "touch"; geometryGeneration: number; touches: AndroidTouchPoint[] }
+  | { type: "key"; geometryGeneration: number; key: string; action: "down" | "up" | "press" }
+  /** ASCII only. Anything outside [32,127) is dropped by the emulator *silently* — measured —
+   *  so the viewer must route non-ASCII through `paste` instead. */
+  | { type: "text"; text: string }
+  /** The path for Vietnamese, emoji and CJK: set the guest clipboard, then send the paste combo. */
+  | { type: "paste"; text: string }
+  | { type: "hardware"; key: "home" | "back" | "recent" | "power" | "volume-up" | "volume-down" }
+  | { type: "rotate"; rotation: 0 | 90 | 180 | 270 }
+  | { type: "quality"; quality: AndroidQuality }
+  | { type: "visibility"; visible: boolean }
+  | { type: "input-reset" }
+  | { type: "take-control" }
+  /** Subscribing starts the device's logcat stream; unsubscribing stops it when nobody is left,
+   *  which is the plan's "logs hidden ngừng subscription". */
+  | { type: "logcat"; subscribe: boolean }
+  | { type: "heartbeat" };
+
+// ---------------------------------------------------------------------------------------------
+// Logcat
+// ---------------------------------------------------------------------------------------------
+
+export type AndroidLogLevel = "verbose" | "debug" | "info" | "warn" | "error" | "fatal";
+
+export interface AndroidLogEntry {
+  /** Monotonic within one device stream, so the viewer can key rows and drop duplicates. */
+  id: number;
+  /** Unix milliseconds, as the emulator reports them. */
+  timestamp: number;
+  pid: number;
+  tid: number;
+  level: AndroidLogLevel;
+  tag: string;
+  message: string;
+}
+
+export interface AndroidTouchPoint {
+  /** Frame coordinates, not CSS pixels. The viewer maps before sending. */
+  x: number;
+  y: number;
+  /** Stable for the life of one finger. */
+  id: number;
+  /** 0 releases the finger. The emulator will not free a slot until it sees one. */
+  pressure: number;
+}
+
+/** Server -> client. */
+export type AndroidServerMessage =
+  /** `codec` is the WebCodecs `avc1.PPCCLL` string derived from the real SPS, and is null until
+   *  the encoder has emitted its first keyframe — a `codec` message follows when it has.
+   *  `encoder` is the ffmpeg encoder's name, for display only. */
+  | { type: "ready"; sessionId: string; sessionGeneration: number; geometry: AndroidGeometry; controller: boolean; codec: string | null; encoder: string }
+  /** Sent whenever the bitstream's profile/level changes — first keyframe, a rung switch, a
+   *  rotation. Never guessed: `encoderArgs` sets no `-profile`/`-level`, so it is encoder-default
+   *  and unknown until the bitstream exists, and a wrong string makes `configure()` throw. */
+  | { type: "codec"; codec: string }
+  | { type: "geometry"; geometry: AndroidGeometry }
+  | { type: "controller"; controller: boolean; reason?: string }
+  | { type: "quality"; quality: AndroidQuality }
+  | { type: "status"; booted: boolean; detail?: string }
+  /** A batch of log lines. The first batch after subscribing is the server's ring buffer, so a
+   *  panel opened on a device that has been up for an hour is not empty. */
+  | { type: "log"; entries: AndroidLogEntry[] }
+  | { type: "error"; message: string; fatal?: boolean }
+  | { type: "heartbeat" };
+
+/** Quality rungs. Height is a **ceiling**: a rung taller than the guest never upscales, which
+ *  would spend the whole budget on interpolated pixels. */
+export const ANDROID_QUALITY_PRESETS: Record<AndroidQuality, { maxHeight: number; fps: number; bitrate: string }> = {
+  low: { maxHeight: 720, fps: 24, bitrate: "1.5M" },
+  balanced: { maxHeight: 1280, fps: 30, bitrate: "4M" },
+  high: { maxHeight: 1920, fps: 30, bitrate: "8M" },
+};

package/src/shared/file-index-limits.ts

@@ -0,0 +1,17 @@
+/**
+ * Where a project's file list is searched: in the browser, or on the server where it is held.
+ *
+ * Shared because both ends act on the same number: the browser asks for the list only up to it,
+ * and the index worker keeps a list that long ready to search.
+ */
+
+/**
+ * From this many entries a list is searched on the server instead of being sent to the browser.
+ * nxsys-workspace's 175k entries are a 22 MB download that took 39 ms to parse and 19–85 ms per
+ * keystroke to search on a desktop, measured in Bun — several times that on a phone. Below it
+ * the list is sent once and searched locally, with no round trip per keystroke.
+ */
+export const REMOTE_FILE_SEARCH_FROM_ENTRIES = 50_000;
+
+/** How many ranked entries a server-side search sends back; the palette shows 100. */
+export const REMOTE_FILE_SEARCH_LIMIT = 100;

package/src/shared/session-trace.ts

@@ -0,0 +1,61 @@
+/**
+ * Shapes shared by the session trace's writers: the server (agent runs) and the browser
+ * (`POST /api/trace`). See `docs/architecture/plugins-and-tracing.md`.
+ */
+
+/** Who wrote a row: a provider's stream, PPM itself (inputs, outcomes), or a browser tab. */
+export type TraceSource = "agent" | "server" | "browser";
+
+/** Which door a run came through. The browser path is `ws`; `browser` is only for client rows. */
+export type TraceOrigin =
+  | "ws"
+  | "scheduler"
+  | "ppmbot"
+  | "group-chat"
+  | "jira"
+  | "cli"
+  | "proxy"
+  | "browser"
+  | "unknown";
+
+/** Most entries one `POST /api/trace` may carry; a larger batch is refused whole. */
+export const TRACE_INGEST_MAX_BATCH = 50;
+
+/** Largest serialised payload one browser entry may carry; a larger entry is dropped. */
+export const TRACE_INGEST_MAX_PAYLOAD_BYTES = 16 * 1024;
+
+/** A device id as `device-id.ts` mints it (a UUID) — anything else is refused. */
+export const TRACE_DEVICE_ID_RE = /^[A-Za-z0-9-]{8,64}$/;
+
+/** Row types a browser may write. Anything else in a batch is dropped. */
+export const BROWSER_TRACE_TYPES = [
+  "console_log",
+  "console_info",
+  "console_debug",
+  "console_warn",
+  "console_error",
+  "browser_error",
+  "unhandled_rejection",
+  "render_error",
+  "chunk_error",
+  "entry_never_ran",
+  "console_dropped",
+] as const;
+
+export type BrowserTraceType = (typeof BROWSER_TRACE_TYPES)[number];
+
+export interface BrowserTraceEntry {
+  /** The browser's clock when it happened; the server corrects it by `sentAt`. */
+  ts: number;
+  type: BrowserTraceType;
+  /** The chat session the tab was showing, so the row joins that session's trace. */
+  refId: string | null;
+  payload: Record<string, unknown>;
+}
+
+export interface BrowserTraceBatch {
+  deviceId: string;
+  /** The browser's clock at send time, so a skewed clock can be corrected. */
+  sentAt: number;
+  entries: BrowserTraceEntry[];
+}

package/src/types/chat.ts

@@ -64,6 +64,8 @@ export interface AIProvider {
   ): AsyncIterable<ChatEvent>;
 
   // Optional capabilities — providers implement what they support
+  /** Start the process a chat about to be created will run on, ahead of its first message. */
+  prewarm?(input: PrewarmInput): Promise<void>;
   resolveApproval?(requestId: string, approved: boolean, data?: unknown): void;
   onToolApproval?: (callback: ToolApprovalHandler) => void;
   abortQuery?(sessionId: string, source?: string): void;
@@ -117,6 +119,21 @@ export interface SessionConfig {
   projectName?: string;
   projectPath?: string;
   title?: string;
+  /**
+   * Take the CLI `prewarm` started in this project, if one is waiting. Only the new-chat
+   * route asks: a scheduled run or a bot taking it would leave the tab it was started for
+   * to boot one of its own.
+   */
+  adoptWarmSpare?: boolean;
+}
+
+/** What `prewarm` needs to start the CLI a new chat's first message will run on. */
+export interface PrewarmInput {
+  projectPath: string;
+  /** The account the new-chat tab claimed, which its session will be bound to. */
+  accountId?: string;
+  /** The per-session picks the first message will carry. */
+  opts?: Pick<SendMessageOpts, "permissionMode" | "model" | "effort" | "thinkingBudget">;
 }
 
 export interface ProjectTag {

package/src/types/config.ts

@@ -23,6 +23,20 @@ export interface ThemeConfig {
   customThemeId?: string;
 }
 
+export interface AndroidConfig {
+  /** SDK root the user picked. Empty/absent = discover it (env, then the per-OS default). */
+  sdk_root?: string;
+  /** How many emulators PPM may have running at once. Plan §1 keeps this at 1 by default:
+   *  each one costs gigabytes of host RAM, and two is the design test rather than the target. */
+  max_concurrent?: number;
+  /** Window mode for emulators PPM starts. `no-window` needs no display; `qt-hide-window`
+   *  creates a hidden Qt window and therefore needs one. */
+  window_mode?: "no-window" | "qt-hide-window" | "window";
+  /** `-gpu` argument. Left unset the emulator picks; `swiftshader_indirect` is the safe
+   *  software fallback on a host with no usable GPU for the guest. */
+  gpu_mode?: string;
+}
+
 export interface PpmConfig {
   device_name: string;
   port: number;
@@ -35,7 +49,9 @@ export interface PpmConfig {
   clawbot?: PPMBotConfig;
   cloud_url?: string;
   query_audit: QueryAuditConfig;
+  session_trace: SessionTraceConfig;
   tunnel: TunnelConfig;
+  android?: AndroidConfig;
 }
 
 /**
@@ -69,6 +85,13 @@ export interface QueryAuditConfig {
   max_size_mb: number;
 }
 
+export interface SessionTraceConfig {
+  /** Rows older than this are pruned. */
+  retention_days: number;
+  /** Hard ceiling for session-trace.db; oldest rows go first once it is hit. */
+  max_size_mb: number;
+}
+
 export interface AuthConfig {
   enabled: boolean;
   token: string;
@@ -171,6 +194,10 @@ export const DEFAULT_CONFIG: PpmConfig = {
     retention_days: 30,
     max_size_mb: 500,
   },
+  session_trace: {
+    retention_days: 30,
+    max_size_mb: 500,
+  },
   telegram: {
     bot_token: "",
   },

package/src/types/project.ts

@@ -31,6 +31,15 @@ export interface FileEntry {
   isIgnored?: boolean;
 }
 
+/**
+ * `/files/index?max=` for a project holding more entries than `max`: too long to send, so it is
+ * searched with `/files/index/search` instead.
+ */
+export interface FileIndexTooLarge {
+  tooLarge: true;
+  count: number;
+}
+
 /** Entry returned by /files/list (single directory level) */
 export interface FileDirEntry {
   name: string;

package/src/web/app.tsx

@@ -29,6 +29,7 @@ import { useWakeLock } from "@/hooks/use-wake-lock";
 import { WakeLockMobileBadge } from "@/components/layout/wake-lock-indicator";
 import { useTabPrefetch } from "@/hooks/use-tab-prefetch";
 import { useFileIndexInvalidation } from "@/hooks/use-file-index-invalidation";
+import { useUiPreload } from "@/hooks/use-ui-preload";
 import { useGlobalEvents } from "@/hooks/use-global-events";
 import { useServerReload } from "@/hooks/use-server-reload";
 import { CommandPalette } from "@/components/layout/command-palette";
@@ -151,6 +152,10 @@ export function App() {
   // lazily, so this trades a little background work for instant tab switching.
   useTabPrefetch();
 
+  // Load every tab's and window's code during idle time (desktop or Wi-Fi), so the
+  // first one of each kind opens without waiting on its chunk or a spinner.
+  useUiPreload(authState === "authenticated");
+
   // Warn before closing browser tab (prevents accidental Ctrl+W)
   useEffect(() => {
     if (authState !== "authenticated") return;

package/src/web/components/android/android-apk-upload.ts

@@ -0,0 +1,75 @@
+/**
+ * Uploading an APK with progress and a working cancel.
+ *
+ * `fetch` has no upload progress — `ReadableStream` request bodies do exist but need HTTP/2 and
+ * a `duplex` option that PPM's usual plain-HTTP LAN deployment cannot rely on, and even then
+ * nothing reports how far the send has got. `XMLHttpRequest.upload.onprogress` does, and
+ * `xhr.abort()` really stops the send rather than only dropping the response. So this is the one
+ * place in the Android client that is not on the api client.
+ *
+ * It is kept out of the component so the URL it builds and the way it reads an error can be
+ * unit-tested; a component here cannot be imported under `bun:test` (the stores read
+ * `localStorage` at module scope).
+ */
+
+export interface ApkUploadOptions {
+  deviceId: string;
+  file: File;
+  allowDowngrade?: boolean;
+  token: string | null;
+  onProgress?: (fraction: number) => void;
+}
+
+export interface ApkUploadHandle {
+  /** Resolves with the operation id the server started for the install itself. */
+  done: Promise<string>;
+  cancel(): void;
+}
+
+export function apkUploadUrl(deviceId: string, filename: string, allowDowngrade: boolean): string {
+  const params = new URLSearchParams({ filename });
+  if (allowDowngrade) params.set("downgrade", "1");
+  return `/api/android/devices/${encodeURIComponent(deviceId)}/apk?${params.toString()}`;
+}
+
+/** PPM's envelope is `{ok, data}` / `{ok:false, error}`; a proxy's 502 page is neither. */
+export function readUploadResponse(status: number, body: string): { operationId: string } {
+  let parsed: unknown = null;
+  try { parsed = JSON.parse(body); } catch { /* not JSON at all */ }
+  const envelope = parsed as { ok?: boolean; error?: string; data?: { operationId?: string } } | null;
+  if (status >= 200 && status < 300 && envelope?.ok && envelope.data?.operationId) {
+    return { operationId: envelope.data.operationId };
+  }
+  throw new Error(envelope?.error ?? (body.trim() || `the upload failed with HTTP ${status}`));
+}
+
+export function uploadApk(opts: ApkUploadOptions): ApkUploadHandle {
+  const xhr = new XMLHttpRequest();
+  let cancelled = false;
+
+  const done = new Promise<string>((resolve, reject) => {
+    xhr.open("POST", apkUploadUrl(opts.deviceId, opts.file.name, opts.allowDowngrade === true));
+    if (opts.token) xhr.setRequestHeader("Authorization", `Bearer ${opts.token}`);
+    xhr.setRequestHeader("Content-Type", "application/vnd.android.package-archive");
+    xhr.setRequestHeader("x-ppm-client", "web");
+
+    xhr.upload.onprogress = (e) => {
+      if (e.lengthComputable && opts.onProgress) opts.onProgress(e.loaded / e.total);
+    };
+    xhr.onload = () => {
+      try { resolve(readUploadResponse(xhr.status, xhr.responseText).operationId); } catch (e) { reject(e); }
+    };
+    xhr.onerror = () => reject(new Error("the upload could not reach the server"));
+    xhr.onabort = () => reject(new Error("cancelled"));
+    xhr.send(opts.file);
+  });
+
+  return {
+    done,
+    cancel() {
+      if (cancelled) return;
+      cancelled = true;
+      xhr.abort();
+    },
+  };
+}