npm - shraga - Versions diffs - 0.1.96 → 0.1.97 - Mend

shraga 0.1.96 → 0.1.97

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/dist/client/assets/{index-CJDfTuzn.css → index-DlgCLI89.css} +1 -1
package/dist/client/assets/{index-519evGGj.js → index-QkJewVCL.js} +237 -237
package/dist/client/index.html +2 -2
package/package.json +1 -1
package/src/client/components/ChatView.tsx +2 -5
package/src/client/components/Sidebar.tsx +20 -1
package/src/client/hooks/useConversation.ts +2 -0
package/src/client/lib/build-version.ts +7 -0
package/src/client/lib/tool-preview.ts +28 -0
package/src/client/lib/ws.ts +1 -1
package/src/client/vite-env.d.ts +9 -0
package/src/server/boot.ts +28 -3
package/src/server/claude.ts +11 -30
package/src/server/slack/bot.ts +18 -31
package/src/server/turn-stream.ts +128 -0

package/dist/client/index.html CHANGED Viewed

@@ -13,8 +13,8 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-519evGGj.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CJDfTuzn.css">
+    <script type="module" crossorigin src="/assets/index-QkJewVCL.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DlgCLI89.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.96",
+  "version": "0.1.97",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",

package/src/client/components/ChatView.tsx CHANGED Viewed

@@ -23,6 +23,7 @@ const rehypeBidi: Plugin<[], Root> = () => (tree) => {
 import 'highlight.js/styles/github.css';
 import { ChevronRight, Wrench, User, Bot, Copy, Check, RotateCcw, Pencil, X, SendHorizontal, ShieldQuestion, CheckCircle2, XCircle, Eye, EyeOff, Info, Loader2, BrainCircuit, GitFork, Minimize2 } from 'lucide-react';
 import { cn } from '@/lib/utils';
+import { toolPreview } from '@/lib/tool-preview';
 import { annotateLimitReset } from '@/lib/limit-reset';
 import type { ChatMessage, MessageBlock, Attachment } from '@/hooks/useConversation';
 import type { AskQuestion, QuestionAnswers } from '@/lib/ws';
@@ -622,11 +623,7 @@ function ToolUseBlock({ block, tool, input, result, busy, screenMap }: { block:
   const [expanded, setExpanded] = useState(false);
   const inputStr = typeof input === 'string' ? input : JSON.stringify(input, null, 2);
   const isEmpty = typeof input === 'object' && input !== null && Object.keys(input as object).length === 0;
-  const preview = isEmpty
-    ? ''
-    : typeof input === 'object' && input !== null
-      ? Object.keys(input as object).join(', ')
-      : String(input).slice(0, 60);
+  const preview = isEmpty ? '' : toolPreview(input);
   const resultTrimmed = result != null ? stripLineNumbers(result.trim().replace(/\[Image #\d+\]\s*/g, '').trim()) : undefined;
   const hasResult = result != null;

package/src/client/components/Sidebar.tsx CHANGED Viewed

@@ -9,6 +9,7 @@ import { MachineStats } from './MachineStats';
 import type { UnreadSession } from '@/hooks/useUnread';
 import type { AgentSocket } from '@/lib/ws';
 import { useSessionList, type SessionRow as Session, type ChatsFilter } from '@/hooks/useSessionList';
+import { CLIENT_BUILD_VERSION } from '@/lib/build-version';
 interface Props {
   getToken: () => Promise<string | null>;
@@ -123,6 +124,14 @@ export function Sidebar({ getToken, activeSessionId, onSelect, onNew, refreshKey
     getToken().then(t => t ? fetch('/api/version', { headers: { Authorization: `Bearer ${t}` } }) : null).then(r => r?.json()).then(d => d && setVersion(d.version)).catch(() => {});
   }, []);
+  // Version skew is SILENT otherwise: a `dist/client` left stale by a deploy keeps serving a client
+  // written against an older API shape, which discards the new response and renders an empty list —
+  // no error, no log (the list routes are quiet on 200). Surface it instead of debugging a ghost.
+  const stale = !!version && version !== 'unknown' && CLIENT_BUILD_VERSION !== 'dev' && version !== CLIENT_BUILD_VERSION;
+  useEffect(() => {
+    if (stale) console.warn(`[shraga] stale client bundle: built from v${CLIENT_BUILD_VERSION}, server runs v${version} — rebuild dist/client`);
+  }, [stale, version]);
   function renderRow(s: Session) {
     const unread = unreads[s.sessionId];
     const isBusy = busySessions.has(s.sessionId) || s.runStatus === 'running' || s.scheduleRunStatus === 'running';
@@ -218,7 +227,17 @@ export function Sidebar({ getToken, activeSessionId, onSelect, onNew, refreshKey
         <MachineStats socket={socket ?? null} getToken={getToken} />
         {slots.sidebarExtras?.()}
         {version && (
-          <div className="text-[10px] text-muted-foreground/50 text-center">v{version}</div>
+          stale ? (
+            <button
+              onClick={() => location.reload()}
+              title={`This page was built from v${CLIENT_BUILD_VERSION}, the server runs v${version} — reload to update`}
+              className="text-[10px] text-amber-400 hover:text-amber-300 text-center underline decoration-dotted"
+            >
+              ⚠️ stale page (v{CLIENT_BUILD_VERSION} → v{version}) · reload
+            </button>
+          ) : (
+            <div className="text-[10px] text-muted-foreground/50 text-center">v{version}</div>
+          )
         )}
       </div>
     </div>

package/src/client/hooks/useConversation.ts CHANGED Viewed

@@ -391,6 +391,8 @@ function applyStream(setMessages: Dispatch<SetStateAction<ChatMessage[]>>, event
       return setMessages((prev) =>
         appendToAssistant(prev, { type: 'tool_result', toolUseId: event.toolUseId, output: event.output }),
       );
+    case 'tool_result_image':
+      return setMessages((prev) => appendToAssistant(prev, { type: 'image', src: event.dataUrl }));
   }
 }

package/src/client/lib/build-version.ts ADDED Viewed

@@ -0,0 +1,7 @@
+/**
+ * The shraga version this client bundle was built from (stamped by vite's `define`).
+ * Falls back to 'dev' wherever the define is absent (tests, an embedder's own vite config), which
+ * disables the skew check rather than reporting a false mismatch.
+ */
+export const CLIENT_BUILD_VERSION: string =
+  typeof __SHRAGA_CLIENT_VERSION__ === 'string' ? __SHRAGA_CLIENT_VERSION__ : 'dev';

package/src/client/lib/tool-preview.ts ADDED Viewed

@@ -0,0 +1,28 @@
+/**
+ * The one-line preview on a collapsed tool pill. Shows the ARGUMENT that identifies the call — the
+ * command, the path, the pattern — not the argument NAMES. Listing keys (`command, background,
+ * description`) made every Bash pill identical, so a real operation (dispatching a worker, running a
+ * build) was indistinguishable from any other and read as "no tool calls shown at all".
+ * Order is by how well a field identifies the call; anything unrecognised falls back to the first
+ * usable string value, then to the key list.
+ */
+const PREVIEW_KEYS = ['command', 'pattern', 'glob_pattern', 'file_path', 'path', 'url', 'query', 'prompt', 'id', 'description', 'name', 'text'];
+export function toolPreview(input: unknown, max = 120): string {
+  if (typeof input === 'string') return oneLine(input, max);
+  if (typeof input !== 'object' || input === null) return String(input).slice(0, max);
+  const obj = input as Record<string, unknown>;
+  for (const k of PREVIEW_KEYS) {
+    const v = obj[k];
+    if (typeof v === 'string' && v.trim()) return oneLine(v, max);
+  }
+  const first = Object.values(obj).find((v) => typeof v === 'string' && v.trim());
+  if (typeof first === 'string') return oneLine(first, max);
+  return Object.keys(obj).join(', ');
+}
+function oneLine(s: string, max: number): string {
+  const flat = s.replace(/\s+/g, ' ').trim();
+  return flat.length > max ? flat.slice(0, max) + '…' : flat;
+}

package/src/client/lib/ws.ts CHANGED Viewed

@@ -40,7 +40,7 @@ export type ServerEvent =
   | { type: 'session_title_updated'; sessionId: string; title: string }
   | { type: 'directives'; directives: { model?: string; turns?: number; thinking?: string; engine?: string } }
   | { type: 'session_busy'; sessionId: string; busy: boolean }
-  | { type: 'session_stream'; sessionId: string; event: { type: 'thinking_delta'; text: string } | { type: 'text_delta'; text: string } | { type: 'tool_use'; tool: string; toolUseId: string; input: unknown } | { type: 'tool_use_input'; toolUseId: string; input: unknown } | { type: 'tool_result'; toolUseId: string; output: string } }
+  | { type: 'session_stream'; sessionId: string; event: { type: 'thinking_delta'; text: string } | { type: 'text_delta'; text: string } | { type: 'tool_use'; tool: string; toolUseId: string; input: unknown } | { type: 'tool_use_input'; toolUseId: string; input: unknown } | { type: 'tool_result'; toolUseId: string; output: string } | { type: 'tool_result_image'; toolUseId: string; dataUrl: string } }
   | { type: 'artifact'; id: string; sessionId: string; title: string; dimensions: [number, number]; version: number }
   | { type: 'server_restarting' }
   | { type: 'unread'; sessionId: string; count: number; preview: string; source: 'response' | 'proactive' | 'schedule'; title?: string }

package/src/client/vite-env.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+/**
+ * The shraga version the CLIENT BUNDLE was built from, stamped by vite at build time.
+ * Compared against the server's `/api/version` at runtime — a mismatch means `dist/client` is
+ * stale relative to the running server, which fails SILENTLY (a client written against an older
+ * API shape just discards the response). See the version-skew banner in Sidebar.
+ */
+declare const __SHRAGA_CLIENT_VERSION__: string;

package/src/server/boot.ts CHANGED Viewed

@@ -27,7 +27,8 @@ import { registerSpaCatchAll } from './spa-catchall.ts';
 import { slackFeature } from './slack/feature.ts';
 import { dataPath } from './paths.ts';
 import { getAllSessions, getSession, getSessionHistory, upsertSession, appendMessage, saveConversation, loadConversation, setSessionDirectives, getAutoApprove, setAutoApprove, getSessionsByScheduleId, getSessionsVisibleTo, isSessionVisibleTo, setRunStatus, incrementRetryCount, getRunningSessions, getActiveLockCount, updateScheduledSessionStatus, setShuttingDown, backfillSessionVisibility, writePartial, readPartial, clearPartial, registerLivePartial, unregisterLivePartial, readLivePartial, acquireSessionLock, releaseSessionLock, replaceSessionLock, isSessionLocked, getSessionAbortController, forkSession, generateSessionTitle, toListItem, pageSessions, isOwnSession, type ConvBlock, type ConvMessage, type SessionMeta } from './sessions.ts';
-import { setBroadcaster } from './session-bus.ts';
+import { setBroadcaster, emitToSession } from './session-bus.ts';
+import { TURN_CONTROL_EVENTS } from './turn-stream.ts';
 import * as scheduler from './scheduler/index.ts';
 import { initPolls } from './polls.ts';
 import { initBackgroundJobs } from './background-jobs.ts';
@@ -609,6 +610,8 @@ app.get('/api/schedules/:id/runs', requireAuth, (req, res) => {
   res.json(getSessionsByScheduleId(id));
 });
+// Cap on a tool_result pushed to viewers; the transcript keeps the full output.
+const STREAMED_RESULT_MAX = 2000;
 // ── REST chat endpoint (for automation / CLI triggers / agent-to-agent) ──────
 /**
  * Run a single chat turn with all its side effects (session lock, message
@@ -666,7 +669,13 @@ async function runChatTurn(
       abortController,
       context: opts.context ?? { source: 'api', user: userEmail },
       onPermissionRequest: async () => ({ allow: true }),
-    }), onEvent);
+    }), onEvent, {
+      // Same reason as the wake lane: an /api/chat or MCP-driven turn used to surface nothing to a
+      // web viewer until it ended, and dropped an add-on engine's subagent events entirely.
+      maxResultChars: STREAMED_RESULT_MAX,
+      onDelta: (event) => broadcast({ type: 'session_stream', sessionId: sid, event }),
+      onPassthrough: (event) => emitToSession(sid, event),
+    });
     if (blocks.length) {
       appendMessage(sid, { id: crypto.randomUUID(), role: 'assistant', blocks });
     }
@@ -1218,7 +1227,18 @@ initPolls({
       await new Promise((r) => setTimeout(r, 2_000));
     }
     try {
-      return await consumeStream(streamChat({ prompt, sessionId, uid, userEmail, mcpServers: getMcpConfig(uid), abortController, onPermissionRequest: async () => ({ allow: true }) }));
+      // Stream it. A woken turn (a background job reporting back, a poll firing) used to surface
+      // NOTHING until it ended — and an add-on engine's subagent events were dropped outright — so a
+      // turn that dispatched a worker was indistinguishable from one that only claimed to.
+      return await consumeStream(
+        streamChat({ prompt, sessionId, uid, userEmail, mcpServers: getMcpConfig(uid), abortController, onPermissionRequest: async () => ({ allow: true }) }),
+        undefined,
+        {
+          maxResultChars: STREAMED_RESULT_MAX,
+          onDelta: (event) => broadcast({ type: 'session_stream', sessionId, event }),
+          onPassthrough: (event) => emitToSession(sessionId, event),
+        },
+      );
     } finally {
       if (releaseSessionLock(sessionId, abortController)) setRunStatus(sessionId, 'idle');
     }
@@ -1550,6 +1570,11 @@ async function runStream(ws: WebSocket, session: WsSession, sid: string, promptT
           send(ws, { type: 'error', message: event.message, sessionId: sid });
         }
         break;
+      } else if (!TURN_CONTROL_EVENTS.has(event.type)) {
+        // Not core-owned — an add-on engine's event (subagent pills, worker cards). The owning
+        // socket already got it verbatim above; mirror it to the session's OTHER viewers too, so a
+        // second device watching the same turn sees the same thing.
+        broadcast({ ...event, sessionId: sid }, ws);
       }
     }
     if (eventCount === 0) {

package/src/server/claude.ts CHANGED Viewed

@@ -3,6 +3,7 @@ import { summarizeText } from './summarize.ts';
 import { dataSync } from './data-sync.ts';
 import type { McpConfig } from './mcp.ts';
 import { loadConversation, saveConversation, appendMessage, getSession, setSessionDirectives, addTriggeredSkills, upsertSession, type ConvMessage, type ConvBlock } from './sessions.ts';
+import { createTurnAccumulator, type TurnStreamHooks } from './turn-stream.ts';
 import {
   resolveDefaultSkillsContent,
   expandMentionedSkills,
@@ -71,6 +72,8 @@ export function saveAgentConfig(config: AgentConfig): void {
 // ── WS events ───────────────────────────────────────────────────────────────
+export type { TurnStreamHooks };
 export type WsEvent =
   | { type: 'text_delta'; text: string }
   | { type: 'tool_use'; tool: string; toolUseId: string; input: unknown }
@@ -410,38 +413,16 @@ export async function* streamChat(opts: {
  * thing — the MCP path said NOTHING at all, so a truncated turn arrived looking finished. */
 export const MAX_TURNS_NOTICE = '\n\n---\n⚠️ Reached the maximum number of steps for this turn. Send "continue" to pick up where I left off.';
-export async function consumeStream(stream: AsyncGenerator<WsEvent>, onEvent?: (ev: WsEvent) => void): Promise<ConvBlock[]> {
-  let text = '';
-  let thinking = '';
-  const blocks: ConvBlock[] = [];
+export async function consumeStream(
+  stream: AsyncGenerator<WsEvent>,
+  onEvent?: (ev: WsEvent) => void,
+  hooks?: TurnStreamHooks,
+): Promise<ConvBlock[]> {
+  const acc = createTurnAccumulator(hooks ?? {});
   for await (const ev of stream) {
     onEvent?.(ev);
-    if (ev.type === 'thinking_delta') {
-      thinking += ev.text;
-    } else if (ev.type === 'text_delta') {
-      if (thinking) { blocks.push({ type: 'thinking', text: thinking }); thinking = ''; }
-      text += ev.text;
-    } else if (ev.type === 'tool_use') {
-      if (thinking) { blocks.push({ type: 'thinking', text: thinking }); thinking = ''; }
-      if (text) { blocks.push({ type: 'text', text }); text = ''; }
-      blocks.push({ type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input });
-    } else if (ev.type === 'tool_use_input') {
-      const existing = blocks.find((b) => b.type === 'tool_use' && b.toolUseId === ev.toolUseId) as any;
-      if (existing) existing.input = ev.input;
-    } else if (ev.type === 'tool_result') {
-      blocks.push({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output });
-    } else if (ev.type === 'tool_result_image') {
-      blocks.push({ type: 'image', src: ev.dataUrl });
-    } else if (ev.type === 'done') {
-      break;
-    } else if (ev.type === 'error') {
-      if (text) { blocks.push({ type: 'text', text }); text = ''; }
-      blocks.push({ type: 'error', text: ev.message });
-      break;
-    }
+    if (acc.push(ev)) break;
   }
-  if (thinking) blocks.push({ type: 'thinking', text: thinking });
-  if (text) blocks.push({ type: 'text', text });
-  return blocks;
+  return acc.finish();
 }

package/src/server/slack/bot.ts CHANGED Viewed

@@ -12,6 +12,7 @@ import { getMcpConfig } from '../mcp.ts';
 import { dataPath } from '../paths.ts';
 import { appendMessage, setSlackContext, setRunStatus, setVisibleTo, writePartial, clearPartial, registerLivePartial, unregisterLivePartial, acquireSessionLock, releaseSessionLock, getSession, recordSeenSlackTs, type ConvBlock, type SessionMeta } from '../sessions.ts';
 import { injectFile } from '../file-inject.ts';
+import { createTurnAccumulator } from '../turn-stream.ts';
 import {
   postMessage, addReaction, removeReaction, getBotUserId, getAgentUserId, getThreadMessages, getMessage,
   getChannelName, getUserName, getUserProfile, resolveUserMentions, isSupportedFile, SUPPORTED_FILE_MIMES,
@@ -72,48 +73,34 @@ async function* pumpStream(
   sessionId: string,
   opts: { partial?: boolean; artifacts?: boolean } = {},
 ): AsyncGenerator<AgentEvent> {
-  let assistantText = '';
-  const assistantBlocks: ConvBlock[] = [];
-  const collect = () => [...assistantBlocks, ...(assistantText ? [{ type: 'text' as const, text: assistantText }] : [])];
+  // Transcript + web-viewer streaming is the shared reducer's job (turn-stream.ts); this function
+  // only adds what is Slack's: which events become Slack text, and the artifact hook.
+  const acc = createTurnAccumulator({
+    maxResultChars: 2000,
+    onDelta: (event) => broadcastFn({ type: 'session_stream', sessionId, event }),
+    onPassthrough: (event) => broadcastFn({ ...event, sessionId }),
+  });
   let partialInterval: ReturnType<typeof setInterval> | undefined;
   if (opts.partial) {
-    registerLivePartial(sessionId, collect);
-    partialInterval = setInterval(() => { const b = collect(); if (b.length) writePartial(sessionId, b); }, 5_000);
+    registerLivePartial(sessionId, () => acc.snapshot());
+    partialInterval = setInterval(() => { const b = acc.snapshot(); if (b.length) writePartial(sessionId, b); }, 5_000);
   }
-  let stopReason = '';
   try {
     for await (const ev of gen) {
-      if (ev.type === 'text_delta') {
-        assistantText += ev.text;
-        broadcastFn({ type: 'session_stream', sessionId, event: { type: 'text_delta', text: ev.text } });
-        yield { type: 'text_delta', text: ev.text };
-      } else if (ev.type === 'tool_use') {
-        if (assistantText) { assistantBlocks.push({ type: 'text', text: assistantText }); assistantText = ''; }
-        assistantBlocks.push({ type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input });
-        broadcastFn({ type: 'session_stream', sessionId, event: { type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input } });
+      const terminal = acc.push(ev);
+      if (ev.type === 'text_delta') yield { type: 'text_delta', text: ev.text };
+      else if (ev.type === 'tool_use') {
         if (opts.artifacts) { const e = handleArtifactToolUse(sessionId, ev.tool, ev.input); if (e) broadcastFn(e); }
         yield { type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input };
-      } else if (ev.type === 'tool_result') {
-        assistantBlocks.push({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output });
-        const trimmed = ev.output.length > 2000 ? ev.output.slice(0, 2000) + '…' : ev.output;
-        broadcastFn({ type: 'session_stream', sessionId, event: { type: 'tool_result', toolUseId: ev.toolUseId, output: trimmed } });
-      } else if (ev.type === 'tool_result_image') {
-        assistantBlocks.push({ type: 'image', src: ev.dataUrl });
-      } else if (ev.type === 'done') {
-        stopReason = ev.stopReason ?? 'end_turn';
-        break;
       } else if (ev.type === 'error') {
         // Slack gets it as text (it has no block renderer); the transcript gets a real error block.
-        const t = `\n⚠️ ${ev.message}`;
-        if (assistantText) { assistantBlocks.push({ type: 'text', text: assistantText }); assistantText = ''; }
-        assistantBlocks.push({ type: 'error', text: ev.message });
-        yield { type: 'text_delta', text: t };
-        break;
+        yield { type: 'text_delta', text: `\n⚠️ ${ev.message}` };
       }
+      if (terminal) break;
     }
-    if (stopReason === 'max_turns_reached') {
+    if (acc.stopReason === 'max_turns_reached') {
       const notice = '\n\n---\n⚠️ _Reached the maximum number of steps for this turn. Reply "continue" to pick up where I left off._';
-      assistantText += notice;
+      acc.push({ type: 'text_delta', text: notice });
       yield { type: 'text_delta', text: notice };
     }
   } finally {
@@ -121,7 +108,7 @@ async function* pumpStream(
     if (opts.partial) unregisterLivePartial(sessionId);
   }
-  if (assistantText) assistantBlocks.push({ type: 'text', text: assistantText });
+  const assistantBlocks = acc.finish();
   for (const b of assistantBlocks) if (mdText(b)) (b as any).text = await resolveUserMentions(b.text);
   if (assistantBlocks.length) {
     if (opts.partial) clearPartial(sessionId);

package/src/server/turn-stream.ts ADDED Viewed

@@ -0,0 +1,128 @@
+/**
+ * The single event→(transcript blocks, client events) reducer for an agent turn.
+ *
+ * Every lane that runs a turn has to do the same two things with the engine's event stream: build
+ * the assistant message's `ConvBlock[]`, and push the live deltas to whoever is watching the session
+ * on the web. Each surface (websocket, Slack, webhook-driven, background-job/wake, the REST chat
+ * endpoint) grew its own copy, and most were lossy in a different way — a Slack turn rendered tool
+ * pills with empty inputs; a job-triggered turn streamed nothing at all and dropped an add-on
+ * engine's subagent events on the floor. This is that logic, once.
+ *
+ * Two output channels, deliberately distinct:
+ *  - `onDelta` gets the core display events, to be wrapped as `{ type: 'session_stream', event }`.
+ *  - `onPassthrough` gets everything the CORE DOESN'T OWN (an add-on engine's `duplex_*` subagent
+ *    pills — see the note on the WsEvent union in claude.ts), forwarded VERBATIM and top-level,
+ *    which is the shape those clients already listen for. Unknown = forward, never drop: dropping is
+ *    what made a dispatched worker invisible.
+ */
+import type { ConvBlock } from './sessions.ts';
+/** Events a lane handles itself (transport, control flow) — never a display delta, never forwarded. */
+export const TURN_CONTROL_EVENTS = new Set([
+  'done', 'error', 'permission_request', 'question_request',
+  'model_resolved', 'stats', 'session_id', 'session_busy', 'forked',
+]);
+/** The inner payload of a `session_stream` event — the core's display deltas. */
+export type StreamDelta =
+  | { type: 'thinking_delta'; text: string }
+  | { type: 'text_delta'; text: string }
+  | { type: 'tool_use'; tool: string; toolUseId: string; input: unknown }
+  | { type: 'tool_use_input'; toolUseId: string; input: unknown }
+  | { type: 'tool_result'; toolUseId: string; output: string }
+  | { type: 'tool_result_image'; toolUseId: string; dataUrl: string };
+export interface TurnStreamHooks {
+  onDelta?: (ev: StreamDelta) => void;
+  onPassthrough?: (ev: object) => void;
+  /** Cap on a tool_result's streamed output. The transcript keeps the full text either way. */
+  maxResultChars?: number;
+}
+export interface TurnAccumulator {
+  /** The assistant blocks so far — safe to read mid-turn (a live "partial" snapshot). */
+  readonly blocks: ConvBlock[];
+  /** Feed one engine event. Returns true for a terminal event (`done`/`error`), so lanes can break. */
+  push(ev: { type: string } & Record<string, any>): boolean;
+  /** Append arbitrary blocks (a lane's own notices, e.g. the max-turns hint). */
+  add(block: ConvBlock): void;
+  /** Flush trailing thinking/text and return the finished block list. */
+  finish(): ConvBlock[];
+  /** Blocks as they stand, including a trailing in-progress thinking/text — for live partials. */
+  snapshot(): ConvBlock[];
+  /** Set once a `done` event arrives. */
+  stopReason: string;
+}
+export function createTurnAccumulator(hooks: TurnStreamHooks = {}): TurnAccumulator {
+  const blocks: ConvBlock[] = [];
+  const max = hooks.maxResultChars ?? Infinity;
+  let text = '';
+  let thinking = '';
+  const flushThinking = () => { if (thinking) { blocks.push({ type: 'thinking', text: thinking }); thinking = ''; } };
+  const flushText = () => { if (text) { blocks.push({ type: 'text', text }); text = ''; } };
+  const delta = (ev: StreamDelta) => hooks.onDelta?.(ev);
+  const acc: TurnAccumulator = {
+    blocks,
+    stopReason: '',
+    add(block) { flushThinking(); flushText(); blocks.push(block); },
+    push(ev) {
+      switch (ev.type) {
+        case 'thinking_delta':
+          thinking += ev.text;
+          delta({ type: 'thinking_delta', text: ev.text });
+          return false;
+        case 'text_delta':
+          flushThinking();
+          text += ev.text;
+          delta({ type: 'text_delta', text: ev.text });
+          return false;
+        case 'tool_use':
+          flushThinking(); flushText();
+          blocks.push({ type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input });
+          delta({ type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input });
+          return false;
+        case 'tool_use_input': {
+          // The claude-code engine opens a tool_use with an EMPTY input and fills it here. A lane
+          // that drops this renders pills labelled with nothing.
+          const open = blocks.find((b) => b.type === 'tool_use' && b.toolUseId === ev.toolUseId) as { input?: unknown } | undefined;
+          if (open) open.input = ev.input;
+          delta({ type: 'tool_use_input', toolUseId: ev.toolUseId, input: ev.input });
+          return false;
+        }
+        case 'tool_result':
+          blocks.push({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output });
+          delta({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output.length > max ? ev.output.slice(0, max) + '…' : ev.output });
+          return false;
+        case 'tool_result_image':
+          blocks.push({ type: 'image', src: ev.dataUrl });
+          delta({ type: 'tool_result_image', toolUseId: ev.toolUseId, dataUrl: ev.dataUrl });
+          return false;
+        case 'done':
+          acc.stopReason = ev.stopReason ?? 'end_turn';
+          return true;
+        case 'error':
+          flushThinking(); flushText();
+          blocks.push({ type: 'error', text: ev.message });
+          acc.stopReason = 'error';
+          return true;
+        default:
+          // Not core-owned. An add-on engine's event (subagent pills, worker cards) — forward it
+          // verbatim rather than discarding it, and leave the transcript to whoever owns it.
+          if (!TURN_CONTROL_EVENTS.has(ev.type)) hooks.onPassthrough?.(ev);
+          return false;
+      }
+    },
+    finish() { flushThinking(); flushText(); return blocks; },
+    snapshot() {
+      return [
+        ...blocks,
+        ...(thinking ? [{ type: 'thinking' as const, text: thinking }] : []),
+        ...(text ? [{ type: 'text' as const, text }] : []),
+      ];
+    },
+  };
+  return acc;
+}