@hienlh/ppm 0.23.8 → 0.23.10

package/src/web/components/floating-window/window-geometry.ts

@@ -42,6 +42,9 @@ export const Z_BASE = 30;
 
 const PREFERRED = { w: 880, h: 560 } as const;
 const SPAWN_MARGIN = 48;
+/** Cap on a portrait window's height — a 9:16 window this tall already shows a full step
+ *  list; taller than that just wastes space on an ultrawide monitor. */
+const PORTRAIT_MAX_H = 780;
 
 const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
 
@@ -115,6 +118,21 @@ export function cascadeSpawnRect(existing: Rect[], bounds: Bounds): Rect {
   );
 }
 
+/**
+ * Where an agent/teammate session window spawns: a portrait 9:16 rect pinned to the
+ * top-right, tall enough to read a step list without scrolling every other line, cascading
+ * like any other spawn once more than one is open.
+ */
+export function portraitSpawnRect(existing: Rect[], bounds: Bounds): Rect {
+  const h = Math.min(bounds.h - SPAWN_MARGIN * 2, PORTRAIT_MAX_H);
+  const w = Math.max(MIN_SIZE.w, Math.round((h * 9) / 16));
+  const step = existing.length % MAX_WINDOWS;
+  return clampRect(
+    { x: bounds.w - SPAWN_MARGIN - w - step * CASCADE_STEP, y: SPAWN_MARGIN + step * CASCADE_STEP, w, h },
+    bounds,
+  );
+}
+
 /** Nudge step for arrow keys on a focused titlebar (Shift = fine-grained). */
 export function nudgeRect(rect: Rect, dx: number, dy: number, bounds: Bounds): Rect {
   return clampRect({ ...rect, x: rect.x + dx, y: rect.y + dy }, bounds);

package/src/web/components/floating-window/window-persistence.ts

@@ -23,11 +23,12 @@ export interface PersistedWindow {
 
 /**
  * Kinds that may come back after a reload. Derived from WINDOW_KINDS so a new kind is
- * restorable by default; `team-member` is the one exclusion, because its body streams a
- * live subagent session that no longer exists after a reload — restoring it would open
- * an empty shell the user never asked for.
+ * restorable by default; `agent-session` is the one exclusion, because its body streams a
+ * live agent/teammate transcript that no longer exists after a reload — restoring it would
+ * open an empty shell the user never asked for. A persisted blob from before the kind was
+ * renamed (`team-member`) simply matches nothing here and is dropped the same way.
  */
-const RESTORABLE_KINDS: readonly WindowKind[] = WINDOW_KINDS.filter((k) => k !== "team-member");
+const RESTORABLE_KINDS: readonly WindowKind[] = WINDOW_KINDS.filter((k) => k !== "agent-session");
 const STATES: WindowVisualState[] = ["normal", "maximized", "minimized"];
 
 function isRect(v: unknown): v is Rect {

package/src/web/components/floating-window/window-store-types.ts

@@ -7,7 +7,7 @@ import type { Rect } from "./window-geometry";
  * Single source of truth: the persistence layer filters this list instead of repeating it,
  * so a new kind can never be silently dropped on reload.
  */
-export const WINDOW_KINDS = ["explorer", "team-member", "system-monitor", "tab-host", "remote-desktop", "settings"] as const;
+export const WINDOW_KINDS = ["explorer", "agent-session", "system-monitor", "tab-host", "remote-desktop", "settings"] as const;
 
 export type WindowKind = (typeof WINDOW_KINDS)[number];
 

package/src/web/components/settings/resolve-open-settings-action.ts

@@ -10,7 +10,7 @@ export type OpenSettingsAction =
   | { kind: "focus"; id: string; category?: SettingsCategoryId };
 
 /**
- * There is exactly one set of settings, so unlike `"explorer"`/`"team-member"` (legitimately
+ * There is exactly one set of settings, so unlike `"explorer"`/`"agent-session"` (legitimately
  * multi-instance — different payload, different folder/teammate), a second `"settings"`
  * window is never a distinct instance, only a duplicate. When one is already open, focus it
  * instead of spawning another.

package/src/web/components/system/resolve-open-system-monitor-action.ts

@@ -9,7 +9,7 @@ export type OpenSystemMonitorAction =
   | { kind: "focus"; id: string };
 
 /**
- * There is exactly one machine, so unlike `"explorer"`/`"team-member"` (legitimately
+ * There is exactly one machine, so unlike `"explorer"`/`"agent-session"` (legitimately
  * multi-instance — different payload, different folder/teammate), a second
  * `"system-monitor"` window is never a distinct instance, only a duplicate. When one
  * is already open, focus it instead of spawning another.

package/src/web/hooks/use-agent-activity.ts

@@ -0,0 +1,65 @@
+/**
+ * "Who is running right now" for one session, from the transcript hub's liveness
+ * feed on `/ws/global` (the `agent-activity` push).
+ *
+ * Mirrors `use-agent-session-stream.ts`'s subscribe contract exactly: a
+ * subscription is never queued while the socket is down (`sendIfOpen` drops it
+ * instead — a queued subscribe would flush late, against a state the caller has
+ * already moved past), and `onGlobalReady` (fired on every connect and every
+ * reconnect) is what actually (re)subscribes. There is no cursor to resume from
+ * here — each push is a full snapshot of who is running, not a page of steps —
+ * so a resubscribe is just the same message again.
+ */
+import { useEffect, useState } from "react";
+import { onGlobalReady, sendIfOpen } from "@/lib/global-ws-channel";
+import type {
+  AgentActivityMsg,
+  AgentTranscriptProviderId,
+  AgentTranscriptRunningEntry,
+} from "../../shared/agent-transcript-protocol";
+
+export interface UseAgentActivityOptions {
+  projectName: string;
+  providerId: AgentTranscriptProviderId;
+  /** Empty/absent — a draft chat with no session yet — subscribes to nothing. */
+  sessionId: string | null | undefined;
+}
+
+function newSubId(): string {
+  return `aa-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function useAgentActivity(opts: UseAgentActivityOptions): AgentTranscriptRunningEntry[] {
+  const { projectName, providerId, sessionId } = opts;
+  const [running, setRunning] = useState<AgentTranscriptRunningEntry[]>([]);
+
+  useEffect(() => {
+    setRunning([]);
+    if (!sessionId || !projectName) return;
+    const subId = newSubId();
+
+    const subscribe = () => {
+      sendIfOpen(JSON.stringify({ type: "agent-activity:subscribe", subId, projectName, providerId, sessionId }));
+    };
+
+    const onActivity = (e: Event) => {
+      const data = (e as CustomEvent<AgentActivityMsg>).detail;
+      if (data.subId !== subId) return;
+      setRunning(data.running);
+    };
+
+    window.addEventListener("agent-activity", onActivity);
+    const stopResubscribing = onGlobalReady(subscribe);
+    subscribe();
+
+    return () => {
+      window.removeEventListener("agent-activity", onActivity);
+      stopResubscribing();
+      sendIfOpen(JSON.stringify({ type: "agent-activity:unsubscribe", subId }));
+    };
+    // projectName/providerId/sessionId are every real dependency.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [projectName, providerId, sessionId]);
+
+  return running;
+}

package/src/web/hooks/use-agent-session-stream.ts

@@ -0,0 +1,134 @@
+/**
+ * Follow one Agent card's or teammate's work session live, from the transcript hub on
+ * `/ws/global`.
+ *
+ * Generalises the old per-teammate HTTP poll (`use-member-transcript-tail.ts`) to the hub
+ * protocol: a subscription is never queued while the socket is down — `sendIfOpen` drops it
+ * instead, because a queued subscribe would replay later with a cursor that is already
+ * stale by the time the flush happens. `onGlobalReady` (fired on every connect and every
+ * reconnect) is what actually (re)subscribes, using the cursor the last response handed
+ * back, so a reconnect resumes with no gap and no duplicate instead of going quiet.
+ */
+import { useEffect, useMemo, useState } from "react";
+import { onGlobalReady, sendIfOpen } from "@/lib/global-ws-channel";
+import { applyEnvelopeBatch, type StreamEntry } from "@/lib/agent-session-stream-merge";
+import type {
+  AgentTranscriptCursor,
+  AgentTranscriptErrorCode,
+  AgentTranscriptErrorMsg,
+  AgentTranscriptEventsMsg,
+  AgentTranscriptProviderId,
+  AgentTranscriptSourceKind,
+} from "../../shared/agent-transcript-protocol";
+import type { ChatEvent } from "../../types/chat";
+
+export interface UseAgentSessionStreamOptions {
+  projectName: string;
+  providerId: AgentTranscriptProviderId;
+  sessionId: string;
+  source: AgentTranscriptSourceKind;
+  /** Steps already held in chat memory — shown while the transcript stream is unavailable. */
+  fallbackEvents?: ChatEvent[];
+}
+
+export interface UseAgentSessionStream {
+  events: ChatEvent[];
+  /** True only once the server has answered with at least one readable file for this
+   *  source. False before the first response, and after one that found no transcript (old
+   *  session, never had one, or an error) — `events` falls back to `fallbackEvents` both
+   *  times, so a window shows what is already known rather than a blank list while the
+   *  first page is still in flight. */
+  available: boolean;
+  running: boolean;
+  loading: boolean;
+  error: AgentTranscriptErrorCode | null;
+}
+
+function newSubId(): string {
+  return `ats-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function useAgentSessionStream(opts: UseAgentSessionStreamOptions): UseAgentSessionStream {
+  const { projectName, providerId, sessionId, source, fallbackEvents } = opts;
+  const [entries, setEntries] = useState<StreamEntry[]>([]);
+  // False until the first response says otherwise, so a window opened with fallback events
+  // shows them immediately instead of a blank list while the first page is in flight.
+  const [available, setAvailable] = useState(false);
+  const [running, setRunning] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<AgentTranscriptErrorCode | null>(null);
+
+  // Any of these changing is a different subscription, not a resume of the same one —
+  // JSON-stringified so the effect only re-runs when the actual identity changes, not on
+  // every render a caller passes a fresh `source` object literal.
+  const sourceKey = JSON.stringify([projectName, providerId, sessionId, source]);
+
+  useEffect(() => {
+    const subId = newSubId();
+    let entriesBuf: StreamEntry[] = [];
+    let cursor: AgentTranscriptCursor | undefined;
+    setEntries([]);
+    setAvailable(false);
+    setRunning(false);
+    setLoading(true);
+    setError(null);
+
+    const subscribe = () => {
+      sendIfOpen(
+        JSON.stringify({
+          type: "agent-transcript:subscribe",
+          subId,
+          projectName,
+          providerId,
+          sessionId,
+          source,
+          ...(cursor ? { cursor } : {}),
+        }),
+      );
+    };
+
+    const onEvents = (e: Event) => {
+      const data = (e as CustomEvent<AgentTranscriptEventsMsg>).detail;
+      if (data.subId !== subId) return;
+      entriesBuf = applyEnvelopeBatch(entriesBuf, data);
+      cursor = data.cursor;
+      setEntries(entriesBuf);
+      setAvailable(data.available);
+      setRunning(data.running);
+      setLoading(false);
+      setError(null);
+    };
+
+    const onError = (e: Event) => {
+      const data = (e as CustomEvent<AgentTranscriptErrorMsg>).detail;
+      if (data.subId !== subId) return;
+      setAvailable(false);
+      setLoading(false);
+      setError(data.code);
+    };
+
+    window.addEventListener("agent-transcript:events", onEvents);
+    window.addEventListener("agent-transcript:error", onError);
+    const stopResubscribing = onGlobalReady(subscribe);
+    subscribe();
+
+    return () => {
+      window.removeEventListener("agent-transcript:events", onEvents);
+      window.removeEventListener("agent-transcript:error", onError);
+      stopResubscribing();
+      sendIfOpen(JSON.stringify({ type: "agent-transcript:unsubscribe", subId }));
+    };
+    // sourceKey captures every real dependency (projectName/providerId/sessionId/source).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sourceKey]);
+
+  const events = useMemo(() => entries.map((e) => e.ev), [entries]);
+
+  return {
+    events: available ? events : (fallbackEvents ?? []),
+    available,
+    running,
+    loading,
+    error,
+  };
+}

package/src/web/hooks/use-chat.ts

@@ -16,6 +16,13 @@ import type { ChatWsServerMessage, SessionPhase, BackgroundShell, VersionGroup }
 import { useBackgroundOutputStore } from "../stores/background-output-store";
 import { useSessionListStore } from "@/stores/session-list-store";
 import { projectRefForName } from "@/stores/session-list-sync-triggers";
+import { applyChildToParent, slimHistoryEvents } from "@/lib/agent-step-summary";
+
+/** Slim every Agent/Task card a provider stamped `transcriptAvailable` on, walking
+ *  in from the REST history response before it ever reaches React state. */
+function slimHistoryMessages(messages: ChatMessage[]): ChatMessage[] {
+  return messages.map((m) => (m.events ? { ...m, events: slimHistoryEvents(m.events) } : m));
+}
 
 interface ApprovalRequest {
   requestId: string;
@@ -316,12 +323,8 @@ export function useChat(
         const event = events[i]!;
         if (event.type !== "tool_use") continue;
         if ((event.tool === "Agent" || event.tool === "Task") && (event as any).toolUseId === parentToolUseId) {
-          const children = [...(event.children ?? [])];
-          const id = (childEvent as any).toolUseId as string | undefined;
-          const duplicate = id ? children.findIndex((c) => c.type === childEvent.type && (c as any).toolUseId === id) : -1;
-          if (duplicate === -1) children.push(childEvent);
-          else children[duplicate] = childEvent;
-          return [[...events.slice(0, i), { ...event, children }, ...events.slice(i + 1)], true];
+          const updated = applyChildToParent(event, childEvent);
+          return [[...events.slice(0, i), updated, ...events.slice(i + 1)], true];
         }
         if (event.children?.length) {
           const [children, found] = append(event.children);
@@ -360,16 +363,7 @@ export function useChat(
       }
       if (idx === -1) return prev;
       const msg = prev[idx]!;
-      const events = msg.events!.map((e) => {
-        if (!isParent(e) || e.type !== "tool_use") return e;
-        const children = [...(e.children ?? [])];
-        // Replays can redeliver id-bearing children — upsert instead of duplicating
-        const cid = (childEvent as any).toolUseId as string | undefined;
-        const dup = cid ? children.findIndex((c) => c.type === childEvent.type && (c as any).toolUseId === cid) : -1;
-        if (dup !== -1) children[dup] = childEvent;
-        else children.push(childEvent);
-        return { ...e, children };
-      });
+      const events = msg.events!.map((e) => (isParent(e) ? applyChildToParent(e, childEvent) : e));
       return [...prev.slice(0, idx), { ...msg, events }, ...prev.slice(idx + 1)];
     });
     return true;
@@ -1237,7 +1231,7 @@ export function useChat(
           // cached bundle from before the upgrade would otherwise render an empty
           // history with no error.
           const payload = Array.isArray(data) ? { messages: data, versionMap: {} } : data;
-          let history: ChatMessage[] = Array.isArray(payload?.messages) ? payload.messages : [];
+          let history: ChatMessage[] = slimHistoryMessages(Array.isArray(payload?.messages) ? payload.messages : []);
           if (payload?.versionMap) setVersionMap(payload.versionMap);
           // The server served this transcript from a different id than the one
           // asked for: the provider had renamed the session and this tab kept the
@@ -1529,7 +1523,7 @@ export function useChat(
         if (Array.isArray(payload?.messages) && payload.messages.length > 0) {
           historyReconciledRef.current++;
           if (syncRafRef.current) { clearTimeout(syncRafRef.current); syncRafRef.current = 0; }
-          setMessages(payload.messages);
+          setMessages(slimHistoryMessages(payload.messages));
           streamingContentRef.current = "";
           streamingEventsRef.current = [];
         }

package/src/web/hooks/use-global-events.ts

@@ -5,6 +5,14 @@ import { useNotificationStore } from "@/stores/notification-store";
 import { useStreamingStore } from "@/stores/streaming-store";
 import { syncRunningSessions } from "@/lib/sync-running-sessions";
 import { syncAllKnownProjects } from "@/stores/session-list-sync-triggers";
+import { notifyGlobalReady, sendIfOpen, setGlobalWsClient } from "@/lib/global-ws-channel";
+
+/** How often the client pings — well under the server's own idle timeout, so a live but
+ *  silent socket never gets reaped as dead. */
+const PING_INTERVAL_MS = 20_000;
+/** No message (including a pong) for this long means the socket is dead even though it
+ *  never fired close/error — force a fresh connect rather than waiting on the browser. */
+const IDLE_TIMEOUT_MS = 45_000;
 
 /**
  * App-wide event bus client (`/ws/global`).
@@ -30,8 +38,18 @@ import { syncAllKnownProjects } from "@/stores/session-list-sync-triggers";
  *   `design:comments_changed`). A design's `.design/` folder is not watched, so these
  *   are the only signal that its snapshots or comments changed.
  *
+ * - `agent-transcript:events` / `agent-transcript:error` / `agent-activity` → re-dispatched
+ *   as window events for `useAgentSessionStream` and the running-agents bar. Several of
+ *   those hooks can be subscribed at once (one per open session window), each filtering the
+ *   broadcast down to its own `subId` — same pattern as the other re-dispatches here.
+ *
  * Also tells the server which project to watch, so file watching follows the
  * active project instead of depending on a chat socket existing.
+ *
+ * Registers its `WsClient` with `global-ws-channel` and pings every 20s: the hub protocol's
+ * subscriptions (`useAgentSessionStream`) must never queue a send while this socket is
+ * down, so they need to know the instant it actually goes idle rather than only on the next
+ * browser-level close/error.
  */
 export function useGlobalEvents(enabled: boolean, projectName?: string): void {
   const clientRef = useRef<WsClient | null>(null);
@@ -44,8 +62,11 @@ export function useGlobalEvents(enabled: boolean, projectName?: string): void {
     if (!enabled) return;
 
     const token = getAuthToken();
-    const client = new WsClient(`/ws/global${token ? `?token=${encodeURIComponent(token)}` : ""}`);
+    const client = new WsClient(`/ws/global${token ? `?token=${encodeURIComponent(token)}` : ""}`, {
+      idleTimeoutMs: IDLE_TIMEOUT_MS,
+    });
     clientRef.current = client;
+    setGlobalWsClient(client);
 
     const unsubscribe = client.onMessage((event) => {
       let data: { type?: string; [k: string]: unknown };
@@ -68,6 +89,7 @@ export function useGlobalEvents(enabled: boolean, projectName?: string): void {
         // device renamed, pinned or deleted a session) — re-sync every
         // project this browser already knows about.
         syncAllKnownProjects();
+        notifyGlobalReady();
         return;
       }
 
@@ -103,17 +125,28 @@ export function useGlobalEvents(enabled: boolean, projectName?: string): void {
         return;
       }
 
-      if (type.startsWith("jira:") || type.startsWith("tunnel:") || type.startsWith("design:")) {
+      if (
+        type.startsWith("jira:")
+        || type.startsWith("tunnel:")
+        || type.startsWith("design:")
+        || type.startsWith("agent-transcript:")
+        || type === "agent-activity"
+      ) {
         window.dispatchEvent(new CustomEvent(type, { detail: data }));
       }
     });
 
     client.connect();
+    const pingTimer = setInterval(() => {
+      sendIfOpen(JSON.stringify({ type: "ping" }));
+    }, PING_INTERVAL_MS);
 
     return () => {
+      clearInterval(pingTimer);
       unsubscribe();
       client.disconnect();
       clientRef.current = null;
+      setGlobalWsClient(null);
     };
   }, [enabled]);
 

package/src/web/lib/agent-session-stream-merge.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure event-buffer reducer for the agent session stream hook.
+ *
+ * Split out from the hook itself so the ordering/de-dupe/replace/reset/cap rules are
+ * testable under `bun:test` with no WebSocket, no React and no store to mount. Two pushes
+ * for the same subscription are not guaranteed to arrive in `ts` order (a live tick can
+ * land while a catch-up backlog is still draining), and a Codex `replace` updates a step
+ * already shown in place rather than appending a new one.
+ */
+import type { AgentTranscriptEventsMsg } from "../../shared/agent-transcript-protocol";
+import type { ChatEvent } from "../../types/chat";
+
+/** One accumulated step, kept alongside its de-dupe key and timestamp for re-ordering. */
+export interface StreamEntry {
+  k: string;
+  ts: number;
+  ev: ChatEvent;
+}
+
+/** Mirrors the hub's own per-subscription cap so a long session stays renderable. */
+export const MAX_STREAM_ENTRIES = 2000;
+
+/**
+ * Apply one `agent-transcript:events` page to the entries accumulated so far.
+ *
+ * `reset` discards everything first — a truncated/rotated file or a Codex compaction means
+ * the server is telling us history itself changed, not just that more of it arrived.
+ * Otherwise: a `k` already held is either a `replace` (update in place) or a plain duplicate
+ * from an overlapping catch-up/live-tick window (skipped); a new `k` is inserted at the
+ * position its `ts` sorts into rather than appended blindly.
+ */
+export function applyEnvelopeBatch(
+  current: StreamEntry[],
+  batch: AgentTranscriptEventsMsg,
+): StreamEntry[] {
+  const next = batch.reset ? [] : current.slice();
+  for (const { ev, ts, k, replace } of batch.events) {
+    const existingIndex = next.findIndex((e) => e.k === k);
+    if (existingIndex !== -1) {
+      if (replace) next[existingIndex] = { k, ts, ev };
+      continue;
+    }
+    let insertAt = next.length;
+    while (insertAt > 0 && next[insertAt - 1]!.ts > ts) insertAt--;
+    next.splice(insertAt, 0, { k, ts, ev });
+  }
+  return next.length > MAX_STREAM_ENTRIES ? next.slice(next.length - MAX_STREAM_ENTRIES) : next;
+}