@hienlh/ppm 0.17.45 → 0.17.47

package/src/services/subprocess-retention.ts

@@ -0,0 +1,63 @@
+/**
+ * How long a clientless session may keep its SDK subprocess alive.
+ *
+ * A disconnect is usually a tab refresh, a phone switching apps or a laptop sleeping, and the
+ * client is back within seconds. Killing the subprocess on the spot forces the next message
+ * down the resume path, which replays the whole transcript and pays cache-write rates for a
+ * prefix that was already cached — the reason the subprocess is kept at all.
+ *
+ * What bounds that generosity is not the disconnect but the prompt cache: once the cache
+ * behind the prefix has expired, the subprocess protects nothing and is only holding memory.
+ * These decisions live here, apart from the WebSocket wiring, so the timing they encode can
+ * be tested without standing up a session.
+ */
+
+/**
+ * Anthropic's default prompt-cache lifetime. A prefix not re-sent within this window has to
+ * be written to the cache again, so a subprocess older than this is worth nothing.
+ *
+ * Named here rather than inlined because the retention window is *derived* from it — the two
+ * were previously equal by coincidence, which read as if the teardown delay were arbitrary.
+ */
+export const PROMPT_CACHE_TTL_MS = 5 * 60_000;
+
+/**
+ * Milliseconds until a session's prompt cache lapses.
+ *
+ * Measured from the last completed turn, because that is when the cache was last written —
+ * not from the disconnect, which says nothing about the cache. Returns 0 once the window has
+ * already passed, meaning the subprocess can go immediately.
+ */
+export function cacheReleaseDelayMs(
+  lastTurnEndedAt: number | undefined,
+  now: number,
+  ttlMs: number = PROMPT_CACHE_TTL_MS,
+): number {
+  // No completed turn means nothing has been cached, so there is nothing to protect.
+  if (lastTurnEndedAt == null) return 0;
+  return Math.max(0, lastTurnEndedAt + ttlMs - now);
+}
+
+export interface WarmIdleSession {
+  sessionId: string;
+  /** When the session's last client left. Absent is treated as "longest idle". */
+  idleSince?: number;
+}
+
+/**
+ * Which held subprocesses to release when too many sessions are holding one.
+ *
+ * The grace period costs one Claude Code process per abandoned session, and PPM is built to
+ * be reachable from several devices, so abandoned sessions accumulate. Eviction takes the
+ * longest-idle sessions first: their caches are the closest to expiring, so their
+ * subprocesses are the ones worth the least.
+ *
+ * Returns session ids in eviction order; empty when the cap is not exceeded.
+ */
+export function selectWarmIdleEvictions(sessions: WarmIdleSession[], cap: number): string[] {
+  if (cap < 0 || sessions.length <= cap) return [];
+  const byIdleAscending = [...sessions].sort(
+    (a, b) => (a.idleSince ?? 0) - (b.idleSince ?? 0),
+  );
+  return byIdleAscending.slice(0, sessions.length - cap).map((s) => s.sessionId);
+}

package/src/services/transcript-images-file.ts

@@ -0,0 +1,144 @@
+import { closeSync, openSync, readSync, statSync, unlinkSync, writeSync } from "node:fs";
+import {
+  auditImageLine,
+  emptyImageAudit,
+  stripImageLine,
+  type ImageScopeOpts,
+  type StripMode,
+  type TranscriptImageAudit,
+} from "./transcript-images.ts";
+
+/**
+ * File-level image auditing and removal that never holds a transcript in memory.
+ *
+ * The in-memory helpers take the whole transcript as one string, which forces callers to
+ * refuse anything large — and a transcript only becomes worth cleaning once it *is* large,
+ * so that cap turned the feature off exactly where it was needed. Reading a line at a time
+ * removes the cap and the memory spike together: peak usage is one record, not one file.
+ */
+
+/**
+ * Copy `src` over `dest`, truncating it, without allocating either file in memory.
+ *
+ * `openSync(dest, "w")` truncates and writes through the existing inode, so a CLI holding
+ * the path open in append mode keeps writing to the file callers can still see.
+ */
+function copyOverInPlace(src: string, dest: string): void {
+  const buf = Buffer.allocUnsafe(1 << 20);
+  const from = openSync(src, "r");
+  const to = openSync(dest, "w");
+  try {
+    for (;;) {
+      const n = readSync(from, buf, 0, buf.length, null);
+      if (n === 0) break;
+      writeSync(to, buf, 0, n);
+    }
+  } finally {
+    closeSync(from);
+    closeSync(to);
+  }
+}
+
+/**
+ * Feed a file to a callback one newline-delimited record at a time.
+ *
+ * `terminated` says whether the record was followed by a newline in the source. A rewrite has
+ * to reproduce that exactly: the CLI appends to this file, and a transcript left without its
+ * final newline would have the next record glued onto the last one, corrupting both.
+ */
+async function forEachLine(
+  path: string,
+  onLine: (line: string, terminated: boolean) => void,
+): Promise<void> {
+  const reader = Bun.file(path).stream().getReader();
+  const decoder = new TextDecoder();
+  let carry = "";
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const parts = (carry + decoder.decode(value, { stream: true })).split("\n");
+      carry = parts.pop() ?? "";
+      for (const line of parts) onLine(line, true);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  if (carry) onLine(carry, false);
+}
+
+export async function auditTranscriptImagesFile(path: string): Promise<TranscriptImageAudit> {
+  const audit = emptyImageAudit();
+  await forEachLine(path, (line) => auditImageLine(audit, line));
+  return audit;
+}
+
+export interface StripFileResult {
+  removed: number;
+  bytesFreed: number;
+  remaining: TranscriptImageAudit;
+}
+
+/**
+ * Rewrite a transcript with its image payloads replaced, keeping the same inode.
+ *
+ * The rewrite goes to a sibling file first so a crash midway cannot leave a half-written
+ * transcript, and is then copied back over the original rather than renamed into place: the
+ * CLI holds this path open in append mode, and a rename would leave it writing to an inode
+ * nothing reads any more.
+ *
+ * Returns without touching the original when there was nothing to remove, so a no-op strip
+ * cannot change the file's mtime.
+ */
+export async function stripTranscriptImagesFile(
+  path: string,
+  mode: StripMode,
+  opts: ImageScopeOpts = {},
+): Promise<StripFileResult> {
+  const tmp = `${path}.strip-${process.pid}`;
+  let removed = 0;
+  let bytesFreed = 0;
+  const remaining = emptyImageAudit();
+  // The rewrite replaces the whole file, so anything appended after this point would be lost.
+  // Callers are expected to stop the session first; this catches the case where they did not,
+  // because the damage is silent — a dropped record breaks the parentUuid chain and the UI
+  // renders the conversation as empty from that point back.
+  const before = statSync(path);
+
+  const writer = Bun.file(tmp).writer();
+  try {
+    await forEachLine(path, (line, terminated) => {
+      const r = stripImageLine(line, mode, opts);
+      removed += r.removed;
+      bytesFreed += r.bytesFreed;
+      auditImageLine(remaining, r.line);
+      // Reproduce the source's separators byte for byte, trailing newline included.
+      writer.write(terminated ? r.line + "\n" : r.line);
+    });
+    await writer.end();
+
+    if (removed === 0) {
+      unlinkSync(tmp);
+      return { removed, bytesFreed, remaining };
+    }
+    // Guard against writing a truncated transcript over a good one.
+    if (statSync(tmp).size === 0 && before.size > 0) {
+      unlinkSync(tmp);
+      throw new Error("Refusing to replace transcript with an empty rewrite");
+    }
+    const after = statSync(path);
+    if (after.size !== before.size || after.mtimeMs !== before.mtimeMs) {
+      unlinkSync(tmp);
+      throw new Error(
+        "Transcript changed while it was being rewritten — the session is still running. " +
+        "Nothing was modified; stop the session and try again.",
+      );
+    }
+    copyOverInPlace(tmp, path);
+    unlinkSync(tmp);
+    return { removed, bytesFreed, remaining };
+  } catch (e) {
+    try { unlinkSync(tmp); } catch { /* already gone */ }
+    throw e;
+  }
+}

package/src/services/transcript-images.ts

@@ -9,16 +9,25 @@ import { base64ByteLength, imagePlaceholderText } from "../shared/tool-result-co
  * MANY_IMAGE_DIMENSION_LIMIT on a side and reports that it removed them — so those payloads
  * cost bandwidth and produce an error while contributing nothing to the model's context.
  *
- * Only images inside tool results are touched. An image the user attached to a message may
- * no longer exist anywhere else, whereas a tool result can be produced again by re-reading
- * the file it came from.
+ * Images live in two places, and they are not equally safe to remove. A tool result can be
+ * produced again by re-reading the file it came from, so those are removed by default. An
+ * image the user attached to a message usually exists nowhere else, so it is left alone
+ * unless the caller opts in — which it must be able to do, because a single oversized
+ * attachment is enough to make every later turn of the session fail outright.
  *
- * The payload lives at `message.content[].content[]`. A record also carries an image-shaped
- * echo at the top-level `toolUseResult` field, but that one holds no base64 and is not part
- * of an API request, so it is left as the CLI wrote it.
+ * A tool result's payload sits at `message.content[].content[]`; an attachment sits directly
+ * at `message.content[]`. A record also carries an image-shaped echo at the top-level
+ * `toolUseResult` field, but that one holds no base64 and is not part of an API request, so
+ * it is left as the CLI wrote it.
  */
 
-/** Per-image dimension cap the API applies once a request carries several images. */
+/**
+ * Per-image dimension cap the API applies once a request carries several images.
+ *
+ * The cap is a maximum, so an image measuring exactly this many pixels is already over it.
+ * Comparisons here are `>=` rather than `>` for that reason: treating 2000px as acceptable
+ * hides the one image the API is rejecting and makes a cleanup look like a no-op.
+ */
 export const MANY_IMAGE_DIMENSION_LIMIT = 2000;
 
 /** Base64 characters decoded to inspect a header — a JPEG frame can sit behind EXIF. */
@@ -26,10 +35,20 @@ const HEADER_CHARS = 4096;
 
 export type StripMode = "oversized" | "all";
 
+/** Which of the two image locations a scan or strip should cover. */
+export interface ImageScopeOpts {
+  /**
+   * Also cover images the user attached to their own messages. Off by default: the payload
+   * in the transcript is typically the only remaining copy, so removing it is lossy in a way
+   * removing a tool result is not.
+   */
+  includeAttachments?: boolean;
+}
+
 export interface TranscriptImageAudit {
-  /** Images found in tool results. */
+  /** Images found in scope. */
   total: number;
-  /** How many exceed the dimension cap and are therefore already being dropped. */
+  /** How many are at or over the dimension cap and are therefore already being rejected. */
   oversized: number;
   /** Decoded size of all of them. */
   bytes: number;
@@ -37,6 +56,10 @@ export interface TranscriptImageAudit {
   oversizedBytes: number;
   /** Longest side seen, or 0 when no dimensions could be read. */
   largestSide: number;
+  /** Of `total`, how many are user attachments rather than tool results. */
+  attachments: number;
+  /** Of `oversized`, how many are user attachments — these need `includeAttachments` to clear. */
+  oversizedAttachments: number;
 }
 
 export interface StripResult {
@@ -74,13 +97,26 @@ function visitImages(node: unknown, visit: Visitor): void {
   for (const value of Object.values(node)) visitImages(value, visit);
 }
 
-/** Images carried by tool results only — attachments on user messages are left alone. */
-function visitToolResultImages(record: unknown, visit: Visitor): void {
+/**
+ * Images carried by one record, in whichever of the two locations are in scope.
+ *
+ * The visitor is told which location an image came from so callers can count and report
+ * attachments separately — a user needs to know when the image blocking their session is one
+ * only they can authorise removing.
+ */
+function visitRecordImages(
+  record: unknown,
+  visit: (image: ImageBlock, replace: (block: unknown) => void, isAttachment: boolean) => void,
+): void {
   const content = (record as { message?: { content?: unknown } } | null)?.message?.content;
   if (!Array.isArray(content)) return;
-  for (const block of content) {
-    if ((block as { type?: unknown } | null)?.type !== "tool_result") continue;
-    visitImages((block as { content?: unknown }).content, visit);
+  for (let i = 0; i < content.length; i++) {
+    const block = content[i];
+    if ((block as { type?: unknown } | null)?.type === "tool_result") {
+      visitImages((block as { content?: unknown }).content, (img, replace) => visit(img, replace, false));
+    } else if (isImageBlock(block)) {
+      visit(block, (next) => { content[i] = next; }, true);
+    }
   }
 }
 
@@ -99,76 +135,103 @@ function longestSide(data: string): number {
   return size ? Math.max(size.w, size.h) : 0;
 }
 
-export function auditTranscriptImages(text: string): TranscriptImageAudit {
-  const audit: TranscriptImageAudit = {
+/** A zeroed audit, ready to accumulate records into. */
+export function emptyImageAudit(): TranscriptImageAudit {
+  return {
     total: 0,
     oversized: 0,
     bytes: 0,
     oversizedBytes: 0,
     largestSide: 0,
+    attachments: 0,
+    oversizedAttachments: 0,
   };
+}
 
-  for (const line of text.split("\n")) {
-    if (!line) continue;
-    let record: unknown;
-    try {
-      record = JSON.parse(line);
-    } catch {
-      continue;
-    }
-    visitToolResultImages(record, (image) => {
-      const data = imageData(image);
-      const bytes = base64ByteLength(data);
-      const side = longestSide(data);
-      audit.total++;
-      audit.bytes += bytes;
-      if (side > audit.largestSide) audit.largestSide = side;
-      if (side > MANY_IMAGE_DIMENSION_LIMIT) {
-        audit.oversized++;
-        audit.oversizedBytes += bytes;
-      }
-    });
+/**
+ * Fold one JSONL record into a running audit.
+ *
+ * Exposed per line so a transcript can be measured while it streams; a session large enough
+ * to be worth auditing is exactly the one too large to hold in memory as a single string.
+ */
+export function auditImageLine(audit: TranscriptImageAudit, line: string): void {
+  if (!line) return;
+  let record: unknown;
+  try {
+    record = JSON.parse(line);
+  } catch {
+    return;
   }
+  visitRecordImages(record, (image, _replace, isAttachment) => {
+    const data = imageData(image);
+    const bytes = base64ByteLength(data);
+    const side = longestSide(data);
+    audit.total++;
+    audit.bytes += bytes;
+    if (isAttachment) audit.attachments++;
+    if (side > audit.largestSide) audit.largestSide = side;
+    if (side >= MANY_IMAGE_DIMENSION_LIMIT) {
+      audit.oversized++;
+      audit.oversizedBytes += bytes;
+      if (isAttachment) audit.oversizedAttachments++;
+    }
+  });
+}
 
+export function auditTranscriptImages(text: string): TranscriptImageAudit {
+  const audit = emptyImageAudit();
+  for (const line of text.split("\n")) auditImageLine(audit, line);
   return audit;
 }
 
 /**
- * Replace image payloads with the standard placeholder text.
+ * Rewrite one JSONL record with its in-scope image payloads replaced by placeholder text.
  *
- * `oversized` leaves an image whose dimensions cannot be read, since removing something
- * that may well be within the cap would lose context for no benefit.
+ * `oversized` keeps an image whose dimensions cannot be read, since removing something that
+ * may well be within the cap would lose context for no benefit. Attachments are kept unless
+ * `includeAttachments` is set — see the note at the top of this file.
  */
-export function stripTranscriptImages(text: string, mode: StripMode): StripResult {
+export function stripImageLine(
+  line: string,
+  mode: StripMode,
+  opts: ImageScopeOpts = {},
+): { line: string; removed: number; bytesFreed: number } {
+  if (!line) return { line, removed: 0, bytesFreed: 0 };
+  let record: unknown;
+  try {
+    record = JSON.parse(line);
+  } catch {
+    // A line that does not parse is left byte-for-byte as it was found.
+    return { line, removed: 0, bytesFreed: 0 };
+  }
+
   let removed = 0;
   let bytesFreed = 0;
-  let changed = false;
+  visitRecordImages(record, (image, replace, isAttachment) => {
+    if (isAttachment && !opts.includeAttachments) return;
+    const data = imageData(image);
+    if (mode === "oversized" && longestSide(data) < MANY_IMAGE_DIMENSION_LIMIT) return;
+    const bytes = base64ByteLength(data);
+    replace({ type: "text", text: imagePlaceholderText(bytes || undefined) });
+    removed++;
+    bytesFreed += bytes;
+  });
 
-  const lines = text.split("\n").map((line) => {
-    if (!line) return line;
-    let record: unknown;
-    try {
-      record = JSON.parse(line);
-    } catch {
-      // A line that does not parse is left byte-for-byte as it was found.
-      return line;
-    }
+  return removed > 0 ? { line: JSON.stringify(record), removed, bytesFreed } : { line, removed: 0, bytesFreed: 0 };
+}
 
-    let touched = false;
-    visitToolResultImages(record, (image, replace) => {
-      const data = imageData(image);
-      if (mode === "oversized" && longestSide(data) <= MANY_IMAGE_DIMENSION_LIMIT) return;
-      const bytes = base64ByteLength(data);
-      replace({ type: "text", text: imagePlaceholderText(bytes || undefined) });
-      removed++;
-      bytesFreed += bytes;
-      touched = true;
-    });
-
-    if (!touched) return line;
-    changed = true;
-    return JSON.stringify(record);
+export function stripTranscriptImages(
+  text: string,
+  mode: StripMode,
+  opts: ImageScopeOpts = {},
+): StripResult {
+  let removed = 0;
+  let bytesFreed = 0;
+  const lines = text.split("\n").map((line) => {
+    const r = stripImageLine(line, mode, opts);
+    removed += r.removed;
+    bytesFreed += r.bytesFreed;
+    return r.line;
   });
-
-  return { text: changed ? lines.join("\n") : text, removed, bytesFreed };
+  return { text: removed > 0 ? lines.join("\n") : text, removed, bytesFreed };
 }

package/src/services/upgrade.service.ts

@@ -57,6 +57,44 @@ export async function checkForUpdate(): Promise<{
   }
 }
 
+const LATEST_VERSION_CACHE_MS = 300_000; // 5min
+
+/**
+ * Build a cached, in-flight-deduped "what is the newest published version"
+ * check. Every open UI polls the upgrade status once a minute, so an uncached
+ * check would turn into one registry request per client per minute.
+ *
+ * The TTL throttles *attempts*, not just successes: a machine that is offline
+ * or being rate-limited would otherwise re-enter a doomed 10s fetch on every
+ * poll. A failed attempt keeps the last known good version rather than
+ * forgetting it.
+ */
+export function createLatestVersionCheck(
+  checkFn: typeof checkForUpdate = checkForUpdate,
+  ttlMs = LATEST_VERSION_CACHE_MS,
+): () => Promise<string | null> {
+  let cache: { at: number; version: string | null } | null = null;
+  let inflight: Promise<string | null> | null = null;
+
+  const remember = (version: string | null) => {
+    cache = { at: Date.now(), version: version ?? cache?.version ?? null };
+    return cache.version;
+  };
+
+  return function getLatestVersion() {
+    if (cache && Date.now() - cache.at < ttlMs) return Promise.resolve(cache.version);
+    if (inflight) return inflight;
+    inflight = checkFn()
+      .then((r) => remember(r.latest))
+      .catch(() => remember(null))
+      .finally(() => { inflight = null; });
+    return inflight;
+  };
+}
+
+/** Newest published version — shared cache for the upgrade status endpoint. */
+export const getLatestPublishedVersion = createLatestVersionCheck();
+
 /** Resolve npm binary next to the running node runtime, falling back to bare "npm".
  *  Same rationale as bun: autostart may not have npm's bin dir on $PATH. */
 function resolveNpmBin(): string {

package/src/shared/turn-usage.ts

@@ -39,6 +39,13 @@ export interface TurnUsage {
   coldStart: boolean;
   /** Why the previous subprocess went away, when PPM knows. */
   coldReason?: string;
+  /**
+   * Account that served the turn. The prompt cache is scoped per account, so a turn's cost
+   * is only comparable to turns on the same account — a session that moved accounts shows
+   * a cold prefix here for a reason that has nothing to do with the transcript.
+   */
+  accountId?: string;
+  accountLabel?: string;
 }
 
 /** Total prefix replayed to the API this turn, cached or not. */
@@ -59,7 +66,7 @@ export function uncachedPrefixTokens(u: TurnUsage): number {
  */
 export function buildTurnUsage(
   modelUsage: Record<string, ModelUsageLike> | undefined,
-  opts: { coldReason?: string } = {},
+  opts: { coldReason?: string; accountId?: string; accountLabel?: string } = {},
 ): TurnUsage | undefined {
   if (!modelUsage) return undefined;
   const entries = Object.entries(modelUsage);
@@ -104,6 +111,8 @@ export function buildTurnUsage(
     cacheHitRate: prefix > 0 ? cacheReadTokens / prefix : 0,
     coldStart: !!opts.coldReason,
     ...(opts.coldReason && { coldReason: opts.coldReason }),
+    ...(opts.accountId && { accountId: opts.accountId }),
+    ...(opts.accountLabel && { accountLabel: opts.accountLabel }),
   };
 }
 
@@ -129,6 +138,10 @@ export interface TurnCostVerdict {
 }
 
 const COLD_REASON_TEXT: Record<string, string> = {
+  cache_expired: "the session's prompt cache had already lapsed, so PPM released its subprocess",
+  idle_timeout: "the session sat idle with no tab open long enough for PPM to release its subprocess",
+  warm_idle_cap: "too many idle sessions were holding a subprocess, so this one was released early",
+  // Retained for turns recorded before the teardown moved to the idle timer.
   tab_closed: "PPM shut the session's subprocess down when the last tab disconnected",
   set_model: "the model was changed, which restarts the session",
   stream_ended: "the session's subprocess had already exited",
@@ -204,6 +217,7 @@ export function formatTurnUsageLog(u: TurnUsage): string {
     : "";
   return [
     `model=${u.model}`,
+    ...(u.accountLabel || u.accountId ? [`account=${u.accountLabel ?? u.accountId}`] : []),
     `cold=${u.coldStart ? (u.coldReason ?? "yes") : "no"}`,
     `in=${fmtTokens(u.inputTokens)}`,
     `cacheRead=${fmtTokens(u.cacheReadTokens)}`,

package/src/web/components/chat/chat-tab.tsx

@@ -68,9 +68,10 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
   const updateTab = useTabStore((s) => s.updateTab);
   const version = useSettingsStore((s) => s.version);
 
-  // Usage runs independently — auto-refreshes on interval
+  // Usage runs independently — auto-refreshes on interval. Scoped to this session so the
+  // account shown is the one bound to it, not whichever session ran most recently.
   const { usageInfo, usageLoading, lastFetchedAt, refreshUsage } =
-    useUsage(projectName, providerId);
+    useUsage(projectName, providerId, sessionId ?? undefined);
 
   // Draft auto-save/restore
   const { draft, draftLoading, saveDraft, clearDraft } = useDraft(projectName, sessionId);

package/src/web/components/chat/message-action-bar.tsx

@@ -67,13 +67,11 @@ function CopyButton({ content }: { content: string }) {
 export function MessageActionBar({
   timestamp,
   content,
-  accountLabel,
   className,
   children,
 }: {
   timestamp: string;
   content: string;
-  accountLabel?: string;
   className?: string;
   children?: ReactNode;
 }) {
@@ -87,7 +85,6 @@ export function MessageActionBar({
       <time title={fullDate(timestamp)} className="pr-1 tabular-nums">
         {formatRelativeDate(timestamp)}
       </time>
-      {accountLabel && <span className="px-1 truncate max-w-40">via {accountLabel}</span>}
       <CopyButton content={content} />
       {children}
     </div>

package/src/web/components/chat/message-list.tsx

@@ -525,7 +525,6 @@ const MessageBubble = memo(function MessageBubble({ message, isStreaming, isLast
         <TurnChangeRollup
           timestamp={message.timestamp}
           content={turnCopyText ?? assistantMessageText(message)}
-          accountLabel={message.accountLabel}
           changes={turnChanges}
           onJumpToEdit={onJumpToEdit}
         />