@hienlh/ppm 0.18.1 → 0.18.3

package/src/server/ws/team-inbox-watcher.ts

@@ -21,17 +21,28 @@ interface WatcherCallbacks {
   onConfigUpdate: (teamName: string, config: unknown) => void;
 }
 
-/** Start watching a team's inboxes directory + config.json for changes */
-export function startTeamInboxWatcher(
+/** Start watching a team's inboxes directory + config.json for changes.
+ *  Snapshots are seeded from what is already on disk: a watcher can attach to a
+ *  team that has been running for hours, and an unseeded snapshot would replay
+ *  every historical message as "new" on the first file change. */
+export async function startTeamInboxWatcher(
   teamName: string,
   callbacks: WatcherCallbacks,
-): { watchers: FSWatcher[]; cleanup: () => void } {
+): Promise<{ watchers: FSWatcher[]; cleanup: () => void }> {
   const inboxDir = join(TEAMS_DIR, teamName, "inboxes");
   const configPath = join(TEAMS_DIR, teamName, "config.json");
   const watchers: FSWatcher[] = [];
   const inboxSnapshots = new Map<string, number>(); // filename → last known msg count
   const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
 
+  // Seed from current on-disk state before the first change event lands.
+  for (const file of await readInboxFiles(teamName)) {
+    try {
+      const parsed = JSON.parse(await Bun.file(join(inboxDir, file)).text());
+      if (Array.isArray(parsed)) inboxSnapshots.set(file, parsed.length);
+    } catch { /* mid-write or malformed — treat as empty */ }
+  }
+
   // Watch inboxes directory
   try {
     const inboxWatcher = watch(inboxDir, (_event, filename) => {
@@ -92,6 +103,27 @@ export async function readTeamConfig(teamName: string): Promise<unknown | null>
   } catch { return null; }
 }
 
+/** Inbox filenames (`<agent>.json`) for a team, empty when the dir is absent. */
+async function readInboxFiles(teamName: string): Promise<string[]> {
+  try {
+    return (await readdir(join(TEAMS_DIR, teamName, "inboxes"))).filter(f => f.endsWith(".json"));
+  } catch { return []; }
+}
+
+/** Member record for an agent only known by its inbox filename. */
+function synthesizeMember(name: string, teamName: string, status: string) {
+  return { name, agentId: `${name}@${teamName}`, agentType: "teammate", model: "unknown", status };
+}
+
+/** Whether a team directory holds anything usable.
+ *  config.json is optional: Claude Code now creates the team implicitly, named
+ *  after the session, and writes only inboxes/. Requiring a config would make
+ *  every implicitly-created team invisible. */
+export async function teamExists(teamName: string): Promise<boolean> {
+  if (await readTeamConfig(teamName)) return true;
+  return (await readInboxFiles(teamName)).length > 0;
+}
+
 /** List all teams from ~/.claude/teams/ */
 export async function listTeams(): Promise<unknown[]> {
   try {
@@ -99,8 +131,20 @@ export async function listTeams(): Promise<unknown[]> {
     const teams = [];
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const config = await readTeamConfig(entry.name);
-      if (config) teams.push(config);
+      const config = await readTeamConfig(entry.name) as any;
+      if (config) {
+        teams.push({ ...config, name: config.name ?? entry.name, implicit: false });
+        continue;
+      }
+      // Implicit team: membership is only discoverable from inbox filenames.
+      const inboxFiles = await readInboxFiles(entry.name);
+      if (inboxFiles.length === 0) continue;
+      teams.push({
+        name: entry.name,
+        team_name: entry.name,
+        implicit: true,
+        members: inboxFiles.map(f => synthesizeMember(f.replace(".json", ""), entry.name, "active")),
+      });
     }
     return teams;
   } catch { return []; }
@@ -109,14 +153,15 @@ export async function listTeams(): Promise<unknown[]> {
 /** Read team detail with merged inbox messages + inferred member status */
 export async function readTeamDetail(teamName: string): Promise<unknown | null> {
   const config = await readTeamConfig(teamName) as any;
-  if (!config) return null;
-
   const inboxDir = join(TEAMS_DIR, teamName, "inboxes");
+  const inboxFiles = await readInboxFiles(teamName);
+  // Only a directory with neither a config nor any inbox is "not a team".
+  if (!config && inboxFiles.length === 0) return null;
+  const base = config ?? { name: teamName, team_name: teamName, implicit: true };
+
   const messages: unknown[] = [];
-  let inboxFiles: string[] = [];
-  try {
-    inboxFiles = (await readdir(inboxDir)).filter(f => f.endsWith(".json"));
-    for (const file of inboxFiles) {
+  for (const file of inboxFiles) {
+    try {
       const content = await Bun.file(join(inboxDir, file)).text();
       const agentName = file.replace(".json", "");
       const parsed = JSON.parse(content);
@@ -127,8 +172,8 @@ export async function readTeamDetail(teamName: string): Promise<unknown | null>
           parsedType: inferMessageType(m.text ?? ""),
         })));
       }
-    }
-  } catch { /* no inboxes dir */ }
+    } catch { /* mid-write or malformed inbox — skip this agent */ }
+  }
 
   // Sort by timestamp
   messages.sort((a: any, b: any) =>
@@ -136,7 +181,7 @@ export async function readTeamDetail(teamName: string): Promise<unknown | null>
   );
 
   // Infer member status from inboxes
-  const members = (config.members ?? []).map((m: any) => ({
+  const members = (base.members ?? []).map((m: any) => ({
     ...m,
     status: inferMemberStatus(messages, m.name),
   }));
@@ -145,17 +190,11 @@ export async function readTeamDetail(teamName: string): Promise<unknown | null>
   for (const file of inboxFiles) {
     const name = file.replace(".json", "");
     if (!members.some((m: any) => m.name === name)) {
-      members.push({
-        name,
-        agentId: `${name}@${teamName}`,
-        agentType: "teammate",
-        model: "unknown",
-        status: inferMemberStatus(messages, name),
-      });
+      members.push(synthesizeMember(name, teamName, inferMemberStatus(messages, name)));
     }
   }
 
-  return { ...config, members, messages, memberCount: members.length };
+  return { ...base, name: base.name ?? teamName, members, messages, memberCount: members.length };
 }
 
 function inferMemberStatus(messages: unknown[], agentName: string): string {

package/src/server/ws/terminal.ts

@@ -1,5 +1,23 @@
+import { statSync } from "node:fs";
 import { terminalService } from "../../services/terminal.service.ts";
 import { resolveProjectPath } from "../helpers/resolve-project.ts";
+import { assertAllowed, resolvePath } from "../../services/fs-path-guard.service.ts";
+
+/**
+ * Where a new shell starts. An explicit `cwd` (explorer "Open in Terminal") wins
+ * over the project root and goes through the same allowlist as the filesystem
+ * API, so a terminal cannot be spawned anywhere the explorer could not browse.
+ */
+function resolveStartDir(projectName: string | undefined, cwd: string | undefined): string {
+  if (cwd) {
+    const resolved = resolvePath(cwd);
+    assertAllowed(resolved);
+    if (!statSync(resolved).isDirectory()) throw new Error("Not a directory");
+    return resolved;
+  }
+  if (projectName) return resolveProjectPath(projectName);
+  throw new Error("Session not found");
+}
 
 /** Control message prefix for resize commands */
 const RESIZE_PREFIX = "\x01RESIZE:";
@@ -13,18 +31,18 @@ const PONG_MSG = "\x01PONG";
  * Handles terminal session attach, input, resize, and disconnect.
  */
 export const terminalWebSocket = {
-  open(ws: { data: { type: string; id: string; projectName?: string }; send: (data: string) => void }) {
-    const { id, projectName } = ws.data;
+  open(ws: { data: { type: string; id: string; projectName?: string; cwd?: string }; send: (data: string) => void }) {
+    const { id, projectName, cwd } = ws.data;
 
     let session = id !== "new" ? terminalService.get(id) : undefined;
 
-    // If session doesn't exist and projectName is provided, create one
-    if (!session && projectName) {
+    // If session doesn't exist and a start directory is known, create one
+    if (!session && (projectName || cwd)) {
       try {
-        const projectPath = resolveProjectPath(projectName);
+        const startDir = resolveStartDir(projectName, cwd);
         // Create session with the requested ID — but TerminalService generates its own ID.
         // Instead, create and return the new session ID to client.
-        const newId = terminalService.create(projectPath);
+        const newId = terminalService.create(startDir);
         session = terminalService.get(newId);
         if (session) {
           // Update ws.data to reflect actual session ID

package/src/services/fs-ops/fs-ops-upload.service.ts

@@ -0,0 +1,120 @@
+import type { Stats } from "node:fs";
+import { lstat, mkdir, rename, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import {
+  assertAllowed,
+  assertNotPpmSubtreeDeep,
+  assertNotProtected,
+  resolvePath,
+} from "../fs-path-guard.service.ts";
+import { eexist } from "./fs-core-ops.ts";
+
+export interface UploadResult {
+  path: string;
+  size: number;
+}
+
+/**
+ * Suffix for the in-progress write. The stream lands here first and is only renamed onto
+ * the real name once it ends cleanly, so a client abort or a server crash mid-transfer never
+ * leaves a truncated file where a complete one used to be (or overwrites one at all).
+ */
+const TMP_SUFFIX = ".ppm-upload-tmp";
+
+async function lstatOrNull(path: string): Promise<Stats | null> {
+  try {
+    return await lstat(path);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pumps a web `ReadableStream` into a file via Bun's incremental writer, chunk by chunk. Reads
+ * through `getReader()` rather than `for await`: the DOM lib's `ReadableStream` type does not
+ * (yet) declare `Symbol.asyncIterator`, even though Bun implements it at runtime.
+ */
+async function pumpToFile(path: string, body: ReadableStream<Uint8Array>): Promise<number> {
+  const sink = Bun.file(path).writer();
+  const reader = body.getReader();
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    sink.write(value);
+    size += value.byteLength;
+  }
+  await sink.end();
+  return size;
+}
+
+/**
+ * Stream an upload body straight to disk at `path`. `body` is the raw web `ReadableStream`
+ * off the request, pumped chunk-by-chunk into a Bun `FileSink` — there is no per-file size
+ * limit here, disk is the only bound, and nothing sits fully in memory.
+ *
+ * This does *not* use `Bun.write(path, new Response(body))`, the more obvious one-liner:
+ * verified against a real `Bun.serve()` request on this host (Bun 1.3.10, Windows), that call
+ * never resolves — the handler enters it and simply hangs until the client's own timeout,
+ * even for a body a few bytes long. A `FileSink` fed by the same stream's async iterator
+ * completes normally, so that is the write path here; only `Bun.write` itself is implicated
+ * (the round-trip through `Response` and back is the one thing this path skips).
+ *
+ * `FileSink` has no `createPath` option (unlike `Bun.write`), so missing parent directories
+ * are created explicitly. The immediate parent existing as a *file* is checked before that
+ * `mkdir`: libuv reports it as `ENOTDIR` on POSIX but `EEXIST` on Windows, and the client-facing
+ * answer for "there's a file in the way" should not depend on the host OS.
+ */
+export async function uploadFile(
+  path: string,
+  body: ReadableStream<Uint8Array> | null,
+  overwrite: boolean,
+): Promise<UploadResult> {
+  if (!body) {
+    throw Object.assign(new Error("Missing request body"), { status: 400, code: "EINVAL" });
+  }
+  const target = resolvePath(path);
+  assertAllowed(target);
+  // Uploading into the PPM directory would let a client overwrite the config database, the
+  // auth token or the stored provider credentials.
+  await assertNotPpmSubtreeDeep(target);
+  await assertNotProtected(target);
+
+  const existing = await lstatOrNull(target);
+  if (existing) {
+    if (existing.isDirectory()) {
+      throw Object.assign(new Error(`${target} is a directory`), { status: 400, code: "EISDIR" });
+    }
+    if (!overwrite) throw eexist(target);
+  }
+
+  const parentStat = await lstatOrNull(dirname(target));
+  if (parentStat && !parentStat.isDirectory()) {
+    throw Object.assign(new Error(`${dirname(target)} is not a directory`), {
+      status: 400,
+      code: "ENOTDIR",
+    });
+  }
+
+  const tmpPath = `${target}${TMP_SUFFIX}`;
+  await mkdir(dirname(tmpPath), { recursive: true });
+
+  let size: number;
+  try {
+    size = await pumpToFile(tmpPath, body);
+  } catch (e) {
+    await rm(tmpPath, { force: true }).catch(() => {});
+    throw e;
+  }
+
+  try {
+    // `rename` already replaces an existing *file* destination on both POSIX and Windows —
+    // the collision was already refused above unless the caller opted into `overwrite`.
+    await rename(tmpPath, target);
+  } catch (e) {
+    await rm(tmpPath, { force: true }).catch(() => {});
+    throw e;
+  }
+
+  return { path: target, size };
+}

package/src/services/media-transcode/ffmpeg-capabilities.ts

@@ -0,0 +1,89 @@
+/**
+ * Discover ffmpeg/ffprobe on this machine and pick the fastest working H.264 encoder.
+ *
+ * ffmpeg is an *optional* dependency: without it PPM still plays browser-native
+ * media (mp4/webm) via Range requests, it just cannot transcode AVI/MKV. The
+ * result is cached for the process lifetime — the binary does not appear
+ * mid-session, and probing hardware encoders costs a real encode each.
+ *
+ * Hardware encoders are verified by encoding a few synthetic frames rather than by
+ * grepping `ffmpeg -encoders`: the list only says the build was compiled with
+ * NVENC/QSV support, not that a compatible GPU/driver is present.
+ */
+
+export interface FfmpegCapabilities {
+  ffmpeg: string | null;
+  ffprobe: string | null;
+  /** ffmpeg encoder name (`h264_nvenc`, `libx264`…) or null when nothing encodes. */
+  encoder: string | null;
+}
+
+/** Candidate encoders in preference order; each is test-encoded before being trusted. */
+function encoderCandidates(): string[] {
+  switch (process.platform) {
+    case "win32": return ["h264_nvenc", "h264_qsv", "h264_amf", "libx264"];
+    case "darwin": return ["h264_videotoolbox", "libx264"];
+    default: return ["h264_nvenc", "h264_qsv", "libx264"];
+  }
+}
+
+/** Per-encoder quality/speed flags tuned for "watch a file inside the IDE" latency. */
+export function encoderArgs(encoder: string): string[] {
+  switch (encoder) {
+    case "h264_nvenc": return ["-c:v", "h264_nvenc", "-preset", "p3", "-rc", "vbr", "-cq", "26", "-b:v", "0"];
+    case "h264_qsv": return ["-c:v", "h264_qsv", "-preset", "veryfast", "-global_quality", "26"];
+    case "h264_amf": return ["-c:v", "h264_amf", "-quality", "speed", "-rc", "cqp", "-qp_i", "24", "-qp_p", "26"];
+    case "h264_videotoolbox": return ["-c:v", "h264_videotoolbox", "-b:v", "6M", "-realtime", "1"];
+    default: return ["-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-maxrate", "8M", "-bufsize", "16M"];
+  }
+}
+
+async function encoderWorks(ffmpeg: string, encoder: string): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(
+      [
+        ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin",
+        // 256px: hardware encoders reject frames below ~145×49 (NVENC "Frame Dimension less than minimum").
+        "-f", "lavfi", "-i", "color=c=black:s=256x256:r=30:d=0.2",
+        "-frames:v", "3", "-pix_fmt", "yuv420p", ...encoderArgs(encoder),
+        "-f", "null", "-",
+      ],
+      { stdout: "ignore", stderr: "ignore", stdin: "ignore" },
+    );
+    // A hung driver must not stall the whole capability probe.
+    const timer = setTimeout(() => proc.kill(), 10_000);
+    const code = await proc.exited;
+    clearTimeout(timer);
+    return code === 0;
+  } catch {
+    return false;
+  }
+}
+
+let cached: Promise<FfmpegCapabilities> | null = null;
+
+async function detect(): Promise<FfmpegCapabilities> {
+  const ffmpeg = Bun.which("ffmpeg");
+  const ffprobe = Bun.which("ffprobe");
+  if (!ffmpeg) return { ffmpeg: null, ffprobe, encoder: null };
+  for (const candidate of encoderCandidates()) {
+    if (await encoderWorks(ffmpeg, candidate)) return { ffmpeg, ffprobe, encoder: candidate };
+  }
+  return { ffmpeg, ffprobe, encoder: null };
+}
+
+/** Cached capability lookup; the first call pays for the encoder probes. */
+export function getFfmpegCapabilities(): Promise<FfmpegCapabilities> {
+  if (!cached) {
+    cached = detect().catch((e) => {
+      cached = null; // let a later call retry after an unexpected failure
+      throw e;
+    });
+  }
+  return cached;
+}
+
+/** Test hook: drop the cache so a different PATH can be probed. */
+export function resetFfmpegCapabilitiesCache(): void {
+  cached = null;
+}

package/src/services/media-transcode/media-probe.ts

@@ -0,0 +1,63 @@
+/**
+ * Read container/codec facts about a media file with ffprobe.
+ *
+ * The transcoded stream the player receives is a live fragmented MP4 with no
+ * duration, so the UI needs the real duration from here to draw a seek bar.
+ */
+import { getFfmpegCapabilities } from "./ffmpeg-capabilities.ts";
+
+export interface MediaStreamInfo {
+  codec: string;
+  width?: number;
+  height?: number;
+}
+
+export interface MediaProbe {
+  /** Seconds; null when ffprobe could not determine it. */
+  duration: number | null;
+  container: string | null;
+  video: MediaStreamInfo | null;
+  audio: MediaStreamInfo | null;
+}
+
+interface FfprobeJson {
+  format?: { format_name?: string; duration?: string };
+  streams?: Array<{ codec_type?: string; codec_name?: string; width?: number; height?: number }>;
+}
+
+/** Returns null when ffprobe is unavailable or the file is not media it understands. */
+export async function probeMedia(absPath: string): Promise<MediaProbe | null> {
+  const { ffprobe } = await getFfmpegCapabilities();
+  if (!ffprobe) return null;
+
+  const proc = Bun.spawn(
+    [
+      ffprobe, "-v", "error", "-of", "json",
+      "-show_entries", "format=format_name,duration:stream=codec_type,codec_name,width,height",
+      absPath,
+    ],
+    { stdout: "pipe", stderr: "ignore", stdin: "ignore" },
+  );
+  const timer = setTimeout(() => proc.kill(), 15_000);
+  const [text, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+  clearTimeout(timer);
+  if (code !== 0) return null;
+
+  let json: FfprobeJson;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const pick = (type: string): MediaStreamInfo | null => {
+    const s = json.streams?.find((x) => x.codec_type === type && x.codec_name);
+    return s ? { codec: s.codec_name!, width: s.width, height: s.height } : null;
+  };
+  const duration = Number(json.format?.duration);
+  return {
+    duration: Number.isFinite(duration) && duration > 0 ? duration : null,
+    container: json.format?.format_name ?? null,
+    video: pick("video"),
+    audio: pick("audio"),
+  };
+}

package/src/services/media-transcode/transcode-stream.ts

@@ -0,0 +1,129 @@
+/**
+ * Spawn ffmpeg to re-encode a file the browser cannot play (AVI/MJPEG, MKV/AC3, HEVC…)
+ * into a fragmented MP4 that streams to `<video>` while it is still being produced.
+ *
+ * Why fragmented MP4 rather than HLS: a single progressive pipe needs no segmenter,
+ * no playlist, no temp files, and starts within a second. The trade-off is that the
+ * stream has no duration and cannot be seeked natively — the client handles seeking
+ * by re-requesting with `start`, which becomes `-ss` *before* `-i` (fast keyframe
+ * seek; exact-frame seeking would decode from the file start every time).
+ *
+ * Every spawned process is tied to the response body: when the browser drops the
+ * connection (tab closed, seek, next file) the stream is cancelled and only that PID
+ * is killed — never a blanket kill by image name.
+ */
+import { encoderArgs, getFfmpegCapabilities } from "./ffmpeg-capabilities.ts";
+
+/** Parallel ffmpeg jobs allowed. A seek briefly overlaps old + new job, so allow a little slack. */
+export const MAX_CONCURRENT_TRANSCODES = 3;
+let active = 0;
+
+/** How many transcodes are running right now (exposed for tests/diagnostics). */
+export function activeTranscodeCount(): number {
+  return active;
+}
+
+export class TranscodeUnavailableError extends Error {
+  constructor(msg = "ffmpeg is not installed or has no working H.264 encoder") {
+    super(msg);
+    this.name = "TranscodeUnavailableError";
+  }
+}
+
+export class TranscodeBusyError extends Error {
+  constructor() {
+    super(`Too many concurrent transcodes (max ${MAX_CONCURRENT_TRANSCODES})`);
+    this.name = "TranscodeBusyError";
+  }
+}
+
+export interface TranscodeOptions {
+  /** Seconds to skip before encoding. */
+  start?: number;
+  /** Aborts the job when the HTTP request is aborted. */
+  signal?: AbortSignal;
+}
+
+/** Build the ffmpeg argv; pure so tests can assert on it without spawning. */
+export function buildTranscodeArgs(ffmpeg: string, absPath: string, encoder: string, start = 0): string[] {
+  return [
+    ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin",
+    ...(start > 0 ? ["-ss", start.toFixed(3)] : []),
+    "-i", absPath,
+    // First video + first audio track; `?` makes the audio map optional (silent clips).
+    "-map", "0:v:0", "-map", "0:a:0?",
+    // Browsers only decode 4:2:0 H.264; cap at 1080p keeping even dimensions.
+    "-vf", "scale='min(1920,iw)':-2", "-pix_fmt", "yuv420p",
+    ...encoderArgs(encoder),
+    // 2s keyframe interval at 30fps → fragments start quickly after a seek.
+    "-g", "60",
+    "-c:a", "aac", "-b:a", "128k", "-ac", "2",
+    "-movflags", "frag_keyframe+empty_moov+default_base_moof",
+    "-f", "mp4", "pipe:1",
+  ];
+}
+
+export interface TranscodeJob {
+  stream: ReadableStream<Uint8Array>;
+  encoder: string;
+}
+
+/** Start a transcode; the returned stream is the fMP4 body to hand to `Response`. */
+export async function startTranscode(absPath: string, opts: TranscodeOptions = {}): Promise<TranscodeJob> {
+  const caps = await getFfmpegCapabilities();
+  if (!caps.ffmpeg || !caps.encoder) throw new TranscodeUnavailableError();
+  if (active >= MAX_CONCURRENT_TRANSCODES) throw new TranscodeBusyError();
+
+  const proc = Bun.spawn(buildTranscodeArgs(caps.ffmpeg, absPath, caps.encoder, opts.start), {
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+  });
+  active++;
+  let finished = false;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    active--;
+  };
+
+  // Drain stderr so ffmpeg never blocks on a full pipe; keep the tail for the log.
+  const stderrTail = new Response(proc.stderr).text().catch(() => "");
+  proc.exited.then(async (code) => {
+    finish();
+    if (code !== 0 && code !== null && !proc.killed) {
+      const tail = (await stderrTail).trim().split("\n").slice(-3).join(" | ");
+      console.warn(`[transcode] ffmpeg exited ${code} for ${absPath}: ${tail}`);
+    }
+  });
+
+  const kill = () => {
+    if (!proc.killed) proc.kill();
+    finish();
+  };
+  opts.signal?.addEventListener("abort", kill, { once: true });
+
+  // Wrap stdout so a cancelled response body (client went away) kills this process.
+  //
+  // The wrapper is not optional: handing `proc.stdout` straight to `Response`, or calling
+  // `reader.cancel()` on it, segfaults Bun 1.3.x on Windows the moment the client
+  // disconnects (guarded by tests/integration/transcode-stream-client-disconnect.test.ts).
+  // Killing the process is enough — its stdout then ends and the pending read resolves `done`.
+  const reader = proc.stdout.getReader();
+  const stream = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        try { controller.close(); } catch { /* already cancelled */ }
+        finish();
+        return;
+      }
+      controller.enqueue(value);
+    },
+    cancel() {
+      kill();
+    },
+  });
+
+  return { stream, encoder: caps.encoder };
+}

package/src/services/subagent-transcript-merger.ts

@@ -78,7 +78,7 @@ function indexAgentTranscripts(subagentsDir: string): Map<string, string> {
 }
 
 /** Parse one agent transcript into a flat children event list (stream order). */
-function parseAgentTranscript(filePath: string): ChatEvent[] {
+export function parseAgentTranscript(filePath: string): ChatEvent[] {
   const children: ChatEvent[] = [];
   let text: string;
   try {