@grackle-ai/web-components 0.113.0 → 0.114.0

package/src/components/streams/StreamDetailPanel.tsx

@@ -4,12 +4,17 @@
  * Renders as an absolutely-positioned overlay anchored to the right of its
  * containing block (which must have `position: relative`).
  *
+ * Read-only: participants link to their sessions; low-level wiring (fds, full
+ * GUIDs, permission/delivery mode) is tucked behind an "Advanced" disclosure.
+ * Live conversation content arrives in V2 (#1230).
+ *
  * @module
  */
 
 import { useEffect, type JSX } from "react";
 import type { StreamData } from "../../hooks/types.js";
 import { useAppNavigate, sessionUrl } from "../../utils/navigation.js";
+import { streamKind, type StreamKind } from "../../utils/streamCoordination.js";
 import styles from "./StreamDetailPanel.module.scss";
 
 /** Props for the StreamDetailPanel component. */
@@ -20,6 +25,13 @@ export interface StreamDetailPanelProps {
   onClose: () => void;
 }
 
+/** Human-readable kind label. */
+const KIND_LABEL: Record<StreamKind, string> = {
+  chatroom: "Chatroom",
+  pipe: "Pipe",
+  channel: "Channel",
+};
+
 /** Render a permission badge with appropriate color. */
 function PermissionBadge({ permission }: { permission: string }): JSX.Element {
   const cls = permission === "rw"
@@ -41,7 +53,8 @@ function DeliveryModeBadge({ mode }: { mode: string }): JSX.Element {
 }
 
 /**
- * Pull-out right drawer showing stream metadata: overview, subscribers, fds.
+ * Pull-out right drawer showing stream metadata: overview, participants, and an
+ * Advanced disclosure with low-level wiring. Conversation content is V2.
  */
 export function StreamDetailPanel({ stream, onClose }: StreamDetailPanelProps): JSX.Element {
   const navigate = useAppNavigate();
@@ -61,7 +74,7 @@ export function StreamDetailPanel({ stream, onClose }: StreamDetailPanelProps):
     <div className={styles.panel} data-testid="stream-detail-panel">
       <div className={styles.header}>
         <h3 className={styles.title}>{stream.name}</h3>
-        <button className={styles.closeButton} onClick={onClose} aria-label="Close stream details">
+        <button type="button" className={styles.closeButton} onClick={onClose} aria-label="Close stream details">
           &times;
         </button>
       </div>
@@ -71,11 +84,11 @@ export function StreamDetailPanel({ stream, onClose }: StreamDetailPanelProps):
         <div className={styles.section}>
           <div className={styles.sectionLabel}>Overview</div>
           <div className={styles.metaRow}>
-            <span className={styles.metaKey}>Stream ID</span>
-            <span className={styles.metaValue}>{stream.id}</span>
+            <span className={styles.metaKey}>Kind</span>
+            <span className={styles.metaValue}>{KIND_LABEL[streamKind(stream)]}</span>
           </div>
           <div className={styles.metaRow}>
-            <span className={styles.metaKey}>Subscribers</span>
+            <span className={styles.metaKey}>Participants</span>
             <span className={styles.metaValue}>{stream.subscriberCount}</span>
           </div>
           <div className={styles.metaRow}>
@@ -84,35 +97,56 @@ export function StreamDetailPanel({ stream, onClose }: StreamDetailPanelProps):
           </div>
         </div>
 
-        {/* Subscribers */}
+        {/* Participants */}
         <div className={styles.section}>
-          <div className={styles.sectionLabel}>Subscribers</div>
+          <div className={styles.sectionLabel}>Participants</div>
           {stream.subscribers.length === 0 ? (
             <div className={styles.emptySubscribers}>No active subscribers</div>
           ) : (
             stream.subscribers.map((sub) => (
               <div key={sub.subscriptionId} className={styles.subscriberCard} data-testid={`subscriber-card-${sub.subscriptionId}`}>
-                <div className={styles.subscriberHeader}>
-                  <span className={styles.fdNumber}>fd {sub.fd}</span>
-                  <button
-                    className={styles.sessionLink}
-                    onClick={() => { navigate(sessionUrl(sub.sessionId)); }}
-                    title={sub.sessionId}
-                  >
-                    {sub.sessionId.slice(0, 12)}…
-                  </button>
-                </div>
-                <div className={styles.badges}>
-                  <PermissionBadge permission={sub.permission} />
-                  <DeliveryModeBadge mode={sub.deliveryMode} />
-                  {sub.createdBySpawn && (
-                    <span className={styles.spawnTag}>spawn</span>
-                  )}
-                </div>
+                <button
+                  type="button"
+                  className={styles.sessionLink}
+                  onClick={() => { navigate(sessionUrl(sub.sessionId)); }}
+                  title={sub.sessionId}
+                >
+                  {sub.sessionId.slice(0, 12)}…
+                </button>
+                {sub.createdBySpawn && <span className={styles.spawnTag}>spawn</span>}
               </div>
             ))
           )}
         </div>
+
+        {/* Live conversation — V2 */}
+        <div className={styles.section}>
+          <div className={styles.sectionLabel}>Conversation</div>
+          <div className={styles.placeholder} data-testid="stream-conversation-placeholder">
+            Live conversation view — coming in V2.
+          </div>
+        </div>
+
+        {/* Advanced wiring */}
+        <details className={styles.advanced} data-testid="stream-advanced">
+          <summary className={styles.advancedSummary}>Advanced</summary>
+          <div className={styles.metaRow}>
+            <span className={styles.metaKey}>Stream ID</span>
+            <span className={styles.metaValueMono}>{stream.id}</span>
+          </div>
+          {stream.subscribers.map((sub) => (
+            <div key={sub.subscriptionId} className={styles.subscriberCard}>
+              <div className={styles.subscriberHeader}>
+                <span className={styles.fdNumber}>fd {sub.fd}</span>
+                <span className={styles.metaValueMono} title={sub.subscriptionId}>{sub.subscriptionId.slice(0, 12)}…</span>
+              </div>
+              <div className={styles.badges}>
+                <PermissionBadge permission={sub.permission} />
+                <DeliveryModeBadge mode={sub.deliveryMode} />
+              </div>
+            </div>
+          ))}
+        </details>
       </div>
     </div>
   );

package/src/components/streams/index.ts

@@ -1,10 +1,10 @@
 /**
- * Stream sidebar and detail panel components.
+ * IPC stream inventory and detail panel components (Coordination tab).
  *
  * @module streams
  */
 
-export { StreamList } from "./StreamList.js";
-export type { StreamListProps } from "./StreamList.js";
+export { CoordinationList } from "./CoordinationList.js";
+export type { CoordinationListProps } from "./CoordinationList.js";
 export { StreamDetailPanel } from "./StreamDetailPanel.js";
 export type { StreamDetailPanelProps } from "./StreamDetailPanel.js";

package/src/hooks/types.ts

@@ -49,6 +49,8 @@ export interface Session {
   error?: string;
   endReason?: string;
   personaId?: string;
+  /** ID of the task this session belongs to, if any (root/orchestrated work). */
+  taskId?: string;
   inputTokens?: number;
   outputTokens?: number;
   costMillicents?: number;
@@ -641,6 +643,8 @@ export interface StreamData {
   messageBufferDepth: number;
   /** Full subscriber details. */
   subscribers: StreamSubscriberData[];
+  /** Whether publishers receive their own messages echoed back (marks a chatroom). */
+  selfEcho: boolean;
 }
 
 /** Values returned by the streams domain hook. */
@@ -653,8 +657,11 @@ export interface UseStreamsResult {
   streamsLoadedOnce: boolean;
   /** True if the most recent loadStreams call failed (e.g. RPC/network error). */
   streamsLoadError: boolean;
-  /** Request the current stream list from the server. */
-  loadStreams: () => Promise<void>;
+  /**
+   * Request the current stream list from the server. Pass `includeInternal`
+   * to surface internal IPC plumbing (lifecycle/pipe/stdin); defaults to false.
+   */
+  loadStreams: (includeInternal?: boolean) => Promise<void>;
   /** Handle a domain event from the event bus. Returns `true` if handled. */
   handleEvent: (event: GrackleEvent) => boolean;
   /** Lifecycle hook for connect/disconnect/event routing. */

package/src/index.ts

@@ -86,9 +86,9 @@ export type { ScheduleManagerProps } from "./components/schedules/ScheduleManage
 // Settings
 export { SettingsNav } from "./components/settings/SettingsNav.js";
 
-// Streams
-export { StreamList, StreamDetailPanel } from "./components/streams/index.js";
-export type { StreamListProps, StreamDetailPanelProps } from "./components/streams/index.js";
+// Streams (Coordination tab)
+export { CoordinationList, StreamDetailPanel } from "./components/streams/index.js";
+export type { CoordinationListProps, StreamDetailPanelProps } from "./components/streams/index.js";
 
 // Tools
 export { ToolCard } from "./components/tools/ToolCard.js";
@@ -165,7 +165,7 @@ export {
   SETTINGS_APPEARANCE_URL, SETTINGS_ABOUT_URL, SETTINGS_SHORTCUTS_URL,
   PAIR_PATH, NEW_WORKSPACE_URL, KNOWLEDGE_URL, HOME_URL,
   FINDINGS_URL, findingsUrl, findingUrl,
-  CHAT_URL, chatStreamUrl, TASKS_URL,
+  CHAT_URL, COORDINATION_URL, TASKS_URL,
 } from "./utils/navigation.js";
 
 export {

package/src/mocks/MockGrackleProvider.tsx

@@ -44,6 +44,7 @@ const NOOP_DOMAIN_HOOK: DomainHook = {
 import {
   MOCK_ENVIRONMENTS,
   MOCK_SESSIONS,
+  MOCK_STREAMS,
   MOCK_EVENTS,
   MOCK_WORKSPACES,
   MOCK_TASKS,
@@ -57,7 +58,16 @@ import {
   MOCK_KNOWLEDGE_DETAILS,
   type MockStreamStep,
 } from "./mockData.js";
-import type { GraphNode, GraphLink, NodeDetail } from "../hooks/types.js";
+import type { GraphNode, GraphLink, NodeDetail, StreamData } from "../hooks/types.js";
+import { INTERNAL_STREAM_PREFIXES } from "../utils/streamCoordination.js";
+
+/** Filter internal IPC plumbing streams unless explicitly requested. */
+function filterMockStreams(includeInternal: boolean): StreamData[] {
+  if (includeInternal) {
+    return MOCK_STREAMS;
+  }
+  return MOCK_STREAMS.filter((s) => !INTERNAL_STREAM_PREFIXES.some((p) => s.name.startsWith(p)));
+}
 
 // ─── Constants ──────────────────────────────────────
 
@@ -81,6 +91,7 @@ export function MockGrackleProvider({ children }: MockGrackleProviderProps): JSX
   // ── State ─────────────────────────────────────────
   const [environments, setEnvironments] = useState<Environment[]>(MOCK_ENVIRONMENTS);
   const [sessions, setSessions] = useState<Session[]>(MOCK_SESSIONS);
+  const [streams, setStreams] = useState<StreamData[]>(() => filterMockStreams(false));
   const [events, setEvents] = useState<SessionEvent[]>(MOCK_EVENTS);
   const [lastSpawnedId, setLastSpawnedId] = useState<string | undefined>(undefined);
   const [workspaces, setWorkspaces] = useState<Workspace[]>(MOCK_WORKSPACES);
@@ -1176,11 +1187,11 @@ export function MockGrackleProvider({ children }: MockGrackleProviderProps): JSX
       },
 
       streams: {
-        streams: [],
+        streams,
         streamsLoading: false,
         streamsLoadedOnce: true,
         streamsLoadError: false,
-        loadStreams: async () => {},
+        loadStreams: async (includeInternal = false) => { setStreams(filterMockStreams(includeInternal)); },
         domainHook: NOOP_DOMAIN_HOOK,
       },
 
@@ -1371,6 +1382,7 @@ export function MockGrackleProvider({ children }: MockGrackleProviderProps): JSX
     [
       environments,
       sessions,
+      streams,
       events,
       lastSpawnedId,
       taskSessions,

package/src/mocks/mockData.ts

@@ -17,6 +17,7 @@ import type {
   PersonaData,
 } from "../hooks/types.js";
 export { MOCK_KNOWLEDGE_NODES, MOCK_KNOWLEDGE_LINKS, MOCK_KNOWLEDGE_DETAILS } from "./mockKnowledgeData.js";
+export { MOCK_STREAMS } from "./mockStreamsData.js";
 
 // ─── Environments ───────────────────────────────────
 
@@ -94,6 +95,7 @@ export const MOCK_SESSIONS: Session[] = [
     status: "running",
     prompt: "Refactor the authentication middleware to use JWT tokens",
     startedAt: "2026-02-27T08:15:00Z",
+    taskId: "task-001",
     inputTokens: 42_600,
     outputTokens: 8_100,
     costMillicents: 22_000,
@@ -107,6 +109,7 @@ export const MOCK_SESSIONS: Session[] = [
     prompt: "Write unit tests for the user registration endpoint",
     startedAt: "2026-02-27T07:30:00Z",
     endedAt: "2026-02-27T07:33:00Z",
+    taskId: "task-003",
     inputTokens: 31_400,
     outputTokens: 9_800,
     costMillicents: 18_000,
@@ -131,6 +134,7 @@ export const MOCK_SESSIONS: Session[] = [
     status: "running",
     prompt: "Implement rate limiting for the public API",
     startedAt: "2026-02-27T09:00:00Z",
+    taskId: "task-006c",
     inputTokens: 18_900,
     outputTokens: 4_500,
     costMillicents: 10_000,

package/src/mocks/mockStreamsData.ts

@@ -0,0 +1,80 @@
+/**
+ * Static mock IPC streams for the Coordination surface in `?mock` demo mode.
+ *
+ * Subscribers reference sessions from {@link MOCK_SESSIONS}; sessions carry a
+ * `taskId`, so the Coordination tab attributes each stream to its owning task.
+ * Internal plumbing (`lifecycle:`/`pipe:`/`stdin:`) is hidden until the user
+ * toggles "Show internals".
+ *
+ * @module
+ */
+
+import type { StreamData } from "../hooks/types.js";
+
+/** Sample IPC streams: a chatroom + channel attributed to tasks, an unattached
+ * stream, and internal plumbing streams. */
+export const MOCK_STREAMS: StreamData[] = [
+  {
+    id: "stream-planning",
+    name: "jwt-planning-room",
+    selfEcho: true,
+    subscriberCount: 2,
+    messageBufferDepth: 3,
+    subscribers: [
+      { subscriptionId: "sub-p1", sessionId: "sess-001", fd: 3, permission: "rw", deliveryMode: "async", createdBySpawn: false },
+      { subscriptionId: "sub-p2", sessionId: "sess-002", fd: 4, permission: "r", deliveryMode: "async", createdBySpawn: true },
+    ],
+  },
+  {
+    id: "stream-metrics",
+    name: "rate-limit-metrics",
+    selfEcho: false,
+    subscriberCount: 1,
+    messageBufferDepth: 0,
+    subscribers: [
+      { subscriptionId: "sub-m1", sessionId: "sess-004", fd: 3, permission: "r", deliveryMode: "sync", createdBySpawn: false },
+    ],
+  },
+  {
+    id: "stream-cli",
+    name: "cli-inspector",
+    selfEcho: false,
+    subscriberCount: 1,
+    messageBufferDepth: 1,
+    subscribers: [
+      { subscriptionId: "sub-c1", sessionId: "external-cli-session", fd: 5, permission: "rw", deliveryMode: "async", createdBySpawn: false },
+    ],
+  },
+  // ── Internal plumbing — hidden unless "Show internals" is on ──
+  {
+    id: "stream-lifecycle",
+    name: "lifecycle:sess-001-7f3a",
+    selfEcho: false,
+    subscriberCount: 1,
+    messageBufferDepth: 0,
+    subscribers: [
+      { subscriptionId: "sub-l1", sessionId: "sess-001", fd: 6, permission: "rw", deliveryMode: "detach", createdBySpawn: true },
+    ],
+  },
+  {
+    id: "stream-pipe",
+    name: "pipe:sess-001-sess-004",
+    selfEcho: false,
+    subscriberCount: 2,
+    messageBufferDepth: 0,
+    subscribers: [
+      { subscriptionId: "sub-pp1", sessionId: "sess-001", fd: 7, permission: "rw", deliveryMode: "async", createdBySpawn: false },
+      { subscriptionId: "sub-pp2", sessionId: "sess-004", fd: 8, permission: "rw", deliveryMode: "async", createdBySpawn: true },
+    ],
+  },
+  {
+    id: "stream-stdin",
+    name: "stdin:sess-002-9c2e",
+    selfEcho: false,
+    subscriberCount: 1,
+    messageBufferDepth: 0,
+    subscribers: [
+      { subscriptionId: "sub-s1", sessionId: "sess-002", fd: 9, permission: "w", deliveryMode: "detach", createdBySpawn: true },
+    ],
+  },
+];

package/src/utils/navigation.ts

@@ -159,13 +159,11 @@ export const SETTINGS_SHORTCUTS_URL: string = "/settings/shortcuts";
 /** URL for the device pairing page. */
 export const PAIR_PATH: string = "/pair";
 
-/** URL for the root-task chat page. */
+/** URL for the root-task ("Root") chat page. */
 export const CHAT_URL: string = "/chat";
 
-/** Build URL for a specific IPC stream's chat page. */
-export function chatStreamUrl(streamId: string): string {
-  return `/chat/${encodeURIComponent(streamId)}`;
-}
+/** URL for the Coordination page (read-only IPC stream inventory). */
+export const COORDINATION_URL: string = "/coordination";
 
 /** URL for the home dashboard page. */
 export const HOME_URL: string = "/";

package/src/utils/streamCoordination.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import type { Session, StreamData, StreamSubscriberData } from "../hooks/types.js";
+import { attributeStream, groupStreamsByTask, isInternalStream, streamKind } from "./streamCoordination.js";
+
+function makeSub(sessionId: string): StreamSubscriberData {
+  return { subscriptionId: `sub-${sessionId}`, sessionId, fd: 3, permission: "rw", deliveryMode: "async", createdBySpawn: false };
+}
+
+function makeStream(over: Partial<StreamData> & { id: string; name: string }): StreamData {
+  return {
+    subscriberCount: over.subscribers?.length ?? 0,
+    messageBufferDepth: 0,
+    selfEcho: false,
+    subscribers: [],
+    ...over,
+  };
+}
+
+function makeSession(id: string, taskId?: string): Session {
+  return { id, environmentId: "env-1", runtime: "claude-code", status: "running", prompt: "", startedAt: "2026-01-01T00:00:00Z", taskId };
+}
+
+describe("streamKind", () => {
+  it("classifies self-echo streams as chatroom", () => {
+    expect(streamKind(makeStream({ id: "1", name: "room", selfEcho: true }))).toBe("chatroom");
+  });
+  it("classifies pipe: streams as pipe", () => {
+    expect(streamKind(makeStream({ id: "2", name: "pipe:abc" }))).toBe("pipe");
+  });
+  it("classifies other named streams as channel", () => {
+    expect(streamKind(makeStream({ id: "3", name: "telemetry" }))).toBe("channel");
+  });
+});
+
+describe("isInternalStream", () => {
+  it("flags reserved prefixes", () => {
+    expect(isInternalStream(makeStream({ id: "1", name: "lifecycle:x" }))).toBe(true);
+    expect(isInternalStream(makeStream({ id: "2", name: "pipe:x" }))).toBe(true);
+    expect(isInternalStream(makeStream({ id: "3", name: "stdin:x" }))).toBe(true);
+  });
+  it("does not flag normal names", () => {
+    expect(isInternalStream(makeStream({ id: "4", name: "agent-chat" }))).toBe(false);
+  });
+});
+
+describe("attributeStream", () => {
+  const sessions = [makeSession("s-task", "task-1"), makeSession("s-orphan")];
+
+  it("attributes to a task when a subscriber session has a taskId", () => {
+    const stream = makeStream({ id: "1", name: "x", subscribers: [makeSub("s-task")] });
+    expect(attributeStream(stream, sessions)).toEqual({ kind: "task", taskId: "task-1" });
+  });
+  it("returns unattached when the session is known but task-less", () => {
+    const stream = makeStream({ id: "2", name: "x", subscribers: [makeSub("s-orphan")] });
+    expect(attributeStream(stream, sessions)).toEqual({ kind: "unattached" });
+  });
+  it("returns external when no subscriber session is known", () => {
+    const stream = makeStream({ id: "3", name: "x", subscribers: [makeSub("s-unknown")] });
+    expect(attributeStream(stream, sessions)).toEqual({ kind: "external" });
+  });
+});
+
+describe("groupStreamsByTask", () => {
+  it("groups streams by owning task with a trailing orphan bucket", () => {
+    const sessions = [makeSession("s1", "task-1"), makeSession("s2", "task-2"), makeSession("s3")];
+    const streams = [
+      makeStream({ id: "a", name: "a", subscribers: [makeSub("s1")] }),
+      makeStream({ id: "b", name: "b", subscribers: [makeSub("s2")] }),
+      makeStream({ id: "c", name: "c", subscribers: [makeSub("s1")] }),
+      makeStream({ id: "d", name: "d", subscribers: [makeSub("s3")] }), // unattached
+      makeStream({ id: "e", name: "e", subscribers: [makeSub("s-unknown")] }), // external
+    ];
+    const groups = groupStreamsByTask(streams, sessions);
+
+    expect(groups.map((g) => g.taskId)).toEqual(["task-1", "task-2", undefined]);
+    expect(groups[0].streams.map((s) => s.id)).toEqual(["a", "c"]);
+    expect(groups[1].streams.map((s) => s.id)).toEqual(["b"]);
+    expect(groups[2].streams.map((s) => s.id)).toEqual(["d", "e"]);
+  });
+
+  it("omits the orphan bucket when every stream is attributed", () => {
+    const sessions = [makeSession("s1", "task-1")];
+    const streams = [makeStream({ id: "a", name: "a", subscribers: [makeSub("s1")] })];
+    const groups = groupStreamsByTask(streams, sessions);
+    expect(groups).toHaveLength(1);
+    expect(groups[0].taskId).toBe("task-1");
+  });
+});

package/src/utils/streamCoordination.ts

@@ -0,0 +1,108 @@
+/**
+ * Pure helpers for the Coordination surface: classifying IPC streams by kind
+ * and attributing them to the task that owns their subscribers.
+ *
+ * No React or DOM dependencies — safe to unit test in isolation.
+ *
+ * @module
+ */
+
+import type { Session, StreamData } from "../hooks/types.js";
+
+/** Internal IPC plumbing prefixes (mirrors the server's RESERVED_PREFIXES). */
+export const INTERNAL_STREAM_PREFIXES: readonly string[] = ["lifecycle:", "pipe:", "stdin:"];
+
+/** Display kind of a stream, derived from its shape. */
+export type StreamKind = "chatroom" | "pipe" | "channel";
+
+/** Ownership classification of a stream, derived from its subscribers' sessions. */
+export type StreamOwnership =
+  | { kind: "task"; taskId: string }
+  | { kind: "unattached" }
+  | { kind: "external" };
+
+/**
+ * Classify a stream's kind:
+ * - `chatroom` — self-echo streams (N-party rooms where senders see their own messages).
+ * - `pipe` — internal point-to-point pipes (`pipe:` prefix).
+ * - `channel` — any other named stream.
+ */
+export function streamKind(stream: StreamData): StreamKind {
+  if (stream.selfEcho) {
+    return "chatroom";
+  }
+  if (stream.name.startsWith("pipe:")) {
+    return "pipe";
+  }
+  return "channel";
+}
+
+/** Returns true when a stream is internal IPC plumbing (reserved prefix). */
+export function isInternalStream(stream: StreamData): boolean {
+  return INTERNAL_STREAM_PREFIXES.some((prefix) => stream.name.startsWith(prefix));
+}
+
+/**
+ * Attribute a stream to the task that owns it, by resolving its subscribers'
+ * sessions:
+ * - the first subscriber whose session has a `taskId` wins → `{ kind: "task" }`;
+ * - else if any subscriber's session is known (but task-less) → `unattached`;
+ * - else (no subscriber session resolvable — e.g. CLI/MCP-created) → `external`.
+ */
+export function attributeStream(stream: StreamData, sessions: readonly Session[]): StreamOwnership {
+  return attributeWithMap(stream, new Map(sessions.map((s) => [s.id, s])));
+}
+
+/** Attribution against a precomputed session map — avoids rebuilding it per stream. */
+function attributeWithMap(stream: StreamData, sessionsById: ReadonlyMap<string, Session>): StreamOwnership {
+  let sawKnownSession = false;
+  for (const sub of stream.subscribers) {
+    const session = sessionsById.get(sub.sessionId);
+    if (session) {
+      sawKnownSession = true;
+      if (session.taskId) {
+        return { kind: "task", taskId: session.taskId };
+      }
+    }
+  }
+  return sawKnownSession ? { kind: "unattached" } : { kind: "external" };
+}
+
+/** A group of streams sharing an owning task (or the unattached/external bucket). */
+export interface StreamGroup {
+  /** Owning task id, or `undefined` for the combined unattached/external bucket. */
+  taskId?: string;
+  /** Streams in this group, in their incoming order. */
+  streams: StreamData[];
+}
+
+/**
+ * Group streams by owning task, preserving first-seen order of tasks. Streams
+ * that are unattached or external are collected into a single trailing bucket
+ * with `taskId === undefined`.
+ */
+export function groupStreamsByTask(streams: readonly StreamData[], sessions: readonly Session[]): StreamGroup[] {
+  const sessionsById = new Map(sessions.map((s) => [s.id, s]));
+  const taskGroups = new Map<string, StreamData[]>();
+  const orphans: StreamData[] = [];
+
+  for (const stream of streams) {
+    const ownership = attributeWithMap(stream, sessionsById);
+    if (ownership.kind === "task") {
+      const existing = taskGroups.get(ownership.taskId);
+      if (existing) {
+        existing.push(stream);
+      } else {
+        taskGroups.set(ownership.taskId, [stream]);
+      }
+    } else {
+      orphans.push(stream);
+    }
+  }
+
+  const groups: StreamGroup[] = Array.from(taskGroups, ([taskId, groupStreams]) => ({ taskId, streams: groupStreams }));
+  if (orphans.length > 0) {
+    groups.push({ taskId: undefined, streams: orphans });
+  }
+  return groups;
+}