@xopcai/xopc 0.0.103 → 0.0.104

package/dist/src/tui/tui-agent-events.js

@@ -1,111 +1,252 @@
 import { formatAgentRunErrorForDisplay } from "../agent/client-error-format.js";
+import { createAssistantMessageFromText } from "./components/assistant-message.js";
+import { markRunEvent, markRunIdleAfterCompletion } from "./tui-run-state.js";
 //#region src/tui/tui-agent-events.ts
-const pendingToolCallIds = /* @__PURE__ */ new Map();
-function clearPendingToolCallIds() {
-	pendingToolCallIds.clear();
+const seenStreamEventKeys = /* @__PURE__ */ new Set();
+const assistantByRun = /* @__PURE__ */ new Map();
+function clearSeenStreamEvents() {
+	seenStreamEventKeys.clear();
+	assistantByRun.clear();
+}
+function clearSeenStreamEventsForRun(runId) {
+	const prefix = `${runId}:`;
+	for (const key of Array.from(seenStreamEventKeys)) if (key.startsWith(prefix)) seenStreamEventKeys.delete(key);
+	assistantByRun.delete(runId);
 }
 const STREAM_TOUCH_EVENTS = new Set([
-	"status",
-	"token",
-	"thinking",
+	"run_start",
+	"assistant_message_start",
+	"assistant_delta",
+	"thinking_delta",
+	"thinking_end",
 	"tool_start",
+	"tool_update",
 	"tool_end",
+	"assistant_message_end",
 	"progress"
 ]);
-function dispatchAgentSSE(event, data, state, chatLog, assembler, tui, setActivityStatus, touchStreamingActivity, onRunEnded) {
+const DIRECT_RESPONSE_OWNED_EVENTS = new Set([
+	...STREAM_TOUCH_EVENTS,
+	"run_end",
+	"error"
+]);
+function resolveEventRunId(data, state) {
+	if (typeof data.runId === "string" && data.runId) return data.runId;
+	return state.activeRunId ?? state.runStatus.runId ?? state.runStatus.lastCompletedRunId;
+}
+function shouldSkipDuplicateBroadcastEvent(event, data, state, source) {
+	if (source !== "broadcast") return false;
+	if (!DIRECT_RESPONSE_OWNED_EVENTS.has(event)) return false;
+	const directRunId = state.runStatus.directStreamRunId;
+	if (!directRunId) return false;
+	return resolveEventRunId(data, state) === directRunId;
+}
+function streamEventKey(data, state) {
+	const runId = resolveEventRunId(data, state);
+	const seq = data.seq;
+	if (!runId || typeof seq !== "number" || !Number.isFinite(seq)) return null;
+	return `${runId}:${seq}`;
+}
+function shouldSkipSeenStreamEvent(data, state, source) {
+	if (source !== "agent-response" && source !== "agent-resume" && source !== "broadcast") return false;
+	const key = streamEventKey(data, state);
+	if (!key) return false;
+	if (seenStreamEventKeys.has(key)) return true;
+	seenStreamEventKeys.add(key);
+	return false;
+}
+function payload(data) {
+	return data.payload && typeof data.payload === "object" ? data.payload : {};
+}
+function assistantForRun(runId) {
+	let message = assistantByRun.get(runId);
+	if (!message) {
+		message = createAssistantMessageFromText("");
+		assistantByRun.set(runId, message);
+	}
+	return message;
+}
+function appendAssistantText(message, delta) {
+	const rec = message;
+	if (!Array.isArray(rec.content)) rec.content = [];
+	const content = rec.content;
+	const last = content[content.length - 1];
+	if (last?.type === "text" && typeof last.text === "string") {
+		last.text += delta;
+		return;
+	}
+	content.push({
+		type: "text",
+		text: delta
+	});
+}
+function appendThinkingText(message, delta) {
+	const rec = message;
+	if (!Array.isArray(rec.content)) rec.content = [];
+	const content = rec.content;
+	const last = content[content.length - 1];
+	if (last?.type === "thinking" && typeof last.text === "string") {
+		last.text += delta;
+		return;
+	}
+	content.push({
+		type: "thinking",
+		text: delta,
+		streaming: true
+	});
+}
+function finalizeThinking(message) {
+	const content = message.content;
+	if (!Array.isArray(content)) return;
+	for (const block of content) {
+		if (!block || typeof block !== "object") continue;
+		const rec = block;
+		if (rec.type === "thinking") rec.streaming = false;
+	}
+}
+function errorAssistantMessage(errorContent) {
+	return {
+		...createAssistantMessageFromText(""),
+		stopReason: "error",
+		errorMessage: errorContent
+	};
+}
+function dispatchAgentEvent(event, data, state, chatLog, tui, setActivityStatus, touchStreamingActivity, onRunEnded, onAssistantFinalized, source = "unknown") {
+	if (shouldSkipSeenStreamEvent(data, state, source)) return;
+	if (shouldSkipDuplicateBroadcastEvent(event, data, state, source)) return;
 	if (STREAM_TOUCH_EVENTS.has(event)) touchStreamingActivity?.();
-	const runId = state.activeRunId ?? "default";
+	const runId = resolveEventRunId(data, state) ?? state.activeRunId ?? "default";
+	const p = payload(data);
 	switch (event) {
-		case "status":
-			state.activeRunId = typeof data.runId === "string" ? data.runId : runId;
+		case "run_start":
+			state.activeRunId = runId;
+			markRunEvent(state, "waiting", runId, event, source);
 			setActivityStatus("waiting");
 			break;
-		case "token": {
-			const content = typeof data.content === "string" ? data.content : typeof data.delta === "string" ? data.delta : typeof data.text === "string" ? data.text : "";
-			if (!content) break;
+		case "user_message": {
+			const message = p.message;
+			chatLog.addUser(Array.isArray(message?.content) || typeof message?.content === "string" ? message.content : []);
+			tui.requestRender();
+			break;
+		}
+		case "user_transcript":
+			chatLog.addUser(String(p.text ?? ""));
+			tui.requestRender();
+			break;
+		case "assistant_message_start": {
+			const message = assistantForRun(runId);
+			chatLog.startAssistant(message, runId);
+			markRunEvent(state, "streaming", runId, event, source);
+			setActivityStatus("streaming");
+			tui.requestRender();
+			break;
+		}
+		case "assistant_delta": {
+			const delta = typeof p.delta === "string" ? p.delta : "";
+			if (!delta) break;
+			const message = assistantForRun(runId);
+			appendAssistantText(message, delta);
+			chatLog.updateAssistant(message, runId);
+			markRunEvent(state, "streaming", runId, event, source);
 			setActivityStatus("streaming");
-			const display = assembler.ingestToken(runId, content, state.showThinking);
-			if (display !== null) {
-				chatLog.updateAssistant(display, runId);
-				tui.requestRender();
-			}
+			tui.requestRender();
 			break;
 		}
-		case "thinking": {
-			const thinkContent = String(data.content ?? "");
-			const isDelta = Boolean(data.delta);
-			if (data.status === "started") break;
+		case "thinking_delta": {
+			const delta = typeof p.delta === "string" ? p.delta : "";
+			if (!delta) break;
+			const message = assistantForRun(runId);
+			appendThinkingText(message, delta);
+			chatLog.updateAssistant(message, runId);
+			markRunEvent(state, "streaming", runId, event, source);
 			setActivityStatus("streaming");
-			const display = assembler.ingestThinking(runId, thinkContent, isDelta, state.showThinking);
-			if (display !== null) {
-				chatLog.updateAssistant(display, runId);
-				tui.requestRender();
-			}
+			tui.requestRender();
+			break;
+		}
+		case "thinking_end": {
+			const message = assistantForRun(runId);
+			finalizeThinking(message);
+			chatLog.updateAssistant(message, runId);
+			tui.requestRender();
 			break;
 		}
-		case "thinking_end":
-		case "message_end": break;
 		case "tool_start": {
-			const toolName = String(data.toolName ?? "unknown");
-			const toolCallId = String(data.toolCallId || crypto.randomUUID());
-			const stack = pendingToolCallIds.get(toolName) ?? [];
-			stack.push(toolCallId);
-			pendingToolCallIds.set(toolName, stack);
+			const toolName = String(p.toolName ?? "unknown");
+			const toolCallId = String(p.toolCallId || "");
+			if (!toolCallId) break;
+			chatLog.startTool(toolCallId, toolName, p.args ?? {}, runId);
+			chatLog.markToolExecutionStarted(toolCallId);
+			markRunEvent(state, "tool", runId, event, source);
+			setActivityStatus("running");
+			tui.requestRender();
+			break;
+		}
+		case "tool_update": {
+			const toolName = String(p.toolName ?? "unknown");
+			const toolCallId = String(p.toolCallId || "");
+			if (!toolCallId) break;
+			chatLog.startTool(toolCallId, toolName, {}, runId);
+			if ("details" in p) chatLog.updateToolDetails(toolCallId, p.details);
+			if (typeof p.textDelta === "string") chatLog.updateToolResult(toolCallId, { text: p.textDelta }, false, true);
+			markRunEvent(state, "tool", runId, event, source);
 			setActivityStatus("running");
-			chatLog.startTool(toolCallId, toolName, data.args, runId);
 			tui.requestRender();
 			break;
 		}
 		case "tool_end": {
-			const toolName = String(data.toolName ?? "");
-			let toolCallId = typeof data.toolCallId === "string" && data.toolCallId ? data.toolCallId : "";
-			if (!toolCallId && toolName) {
-				const stack = pendingToolCallIds.get(toolName);
-				if (stack && stack.length > 0) {
-					toolCallId = stack.shift();
-					if (stack.length === 0) pendingToolCallIds.delete(toolName);
-				}
-			}
-			const resultText = String(data.result ?? "");
-			const isError = Boolean(data.isError);
-			if (toolCallId) chatLog.updateToolResult(toolCallId, resultText, isError);
+			const toolCallId = String(p.toolCallId || "");
+			if (!toolCallId) break;
+			chatLog.updateToolResult(toolCallId, p.result, p.status === "error" || p.status === "cancelled", false);
+			markRunEvent(state, "streaming", runId, event, source);
+			setActivityStatus("streaming");
+			tui.requestRender();
+			break;
+		}
+		case "assistant_message_end": {
+			const message = assistantForRun(runId);
+			finalizeThinking(message);
+			chatLog.finalizeAssistant(message, runId);
+			assistantByRun.delete(runId);
+			onAssistantFinalized?.(message);
+			markRunEvent(state, "streaming", runId, event, source);
 			setActivityStatus("streaming");
 			tui.requestRender();
 			break;
 		}
 		case "error": {
-			const errorContent = formatAgentRunErrorForDisplay(String(data.content ?? "Unknown error"));
-			const finalText = assembler.finalize(runId, state.showThinking);
-			if (finalText) chatLog.finalizeAssistant(finalText, runId);
-			chatLog.addSystem(`❌ ${errorContent}`);
+			const errorContent = formatAgentRunErrorForDisplay(String(p.message ?? "Unknown error"));
+			const message = errorAssistantMessage(errorContent);
+			chatLog.finalizeAssistant(message, runId);
+			onAssistantFinalized?.(message, { errorMessage: errorContent });
+			assistantByRun.delete(runId);
 			state.activeRunId = null;
+			markRunIdleAfterCompletion(state, runId, event, source);
 			setActivityStatus("idle");
 			onRunEnded?.();
 			tui.requestRender();
 			break;
 		}
-		case "result": {
-			const finalText = assembler.finalize(runId, state.showThinking);
-			if (finalText) chatLog.finalizeAssistant(finalText, runId);
+		case "run_end":
+			assistantByRun.delete(runId);
 			state.activeRunId = null;
+			markRunIdleAfterCompletion(state, runId, event, source);
 			setActivityStatus("idle");
 			onRunEnded?.();
 			tui.requestRender();
 			break;
-		}
 		case "progress": {
-			const stage = typeof data.stage === "string" ? data.stage : "";
-			const message = typeof data.message === "string" ? data.message : stage;
+			const stage = typeof p.stage === "string" ? p.stage : "";
+			const message = typeof p.message === "string" ? p.message : stage;
 			state.progressMessage = message || null;
+			markRunEvent(state, "progress", runId, event, source);
 			setActivityStatus(message ? `progress: ${message}` : "running");
 			tui.requestRender();
 			break;
 		}
-		default: break;
 	}
 }
 const DEFAULT_STREAMING_WATCHDOG_MS = 3e4;
 //#endregion
-export { DEFAULT_STREAMING_WATCHDOG_MS, clearPendingToolCallIds, dispatchAgentSSE };
+export { DEFAULT_STREAMING_WATCHDOG_MS, clearSeenStreamEvents, clearSeenStreamEventsForRun, dispatchAgentEvent, shouldSkipDuplicateBroadcastEvent };
 
 //# sourceMappingURL=tui-agent-events.js.map

package/dist/src/tui/tui-agent-events.js.map

@@ -1 +1 @@
-{"version":3,"file":"tui-agent-events.js","names":[],"sources":["../../../src/tui/tui-agent-events.ts"],"sourcesContent":["import type { TUI } from '@earendil-works/pi-tui';\n\nimport { formatAgentRunErrorForDisplay } from '../agent/client-error-format.js';\nimport type { ChatLog } from './components/chat-log.js';\nimport type { StreamAssembler } from './stream-assembler.js';\nimport type { TuiState } from './tui-types.js';\n\nconst pendingToolCallIds = new Map<string, string[]>();\n\nexport function clearPendingToolCallIds(): void {\n  pendingToolCallIds.clear();\n}\n\nconst STREAM_TOUCH_EVENTS = new Set([\n  'status',\n  'token',\n  'thinking',\n  'tool_start',\n  'tool_end',\n  'progress',\n]);\n\nexport function dispatchAgentSSE(\n  event: string,\n  data: Record<string, unknown>,\n  state: TuiState,\n  chatLog: ChatLog,\n  assembler: StreamAssembler,\n  tui: TUI,\n  setActivityStatus: (status: string) => void,\n  touchStreamingActivity?: () => void,\n  /** Called when a run ends (result/error) so the TUI can flush follow-up queue, etc. */\n  onRunEnded?: () => void,\n): void {\n  if (STREAM_TOUCH_EVENTS.has(event)) {\n    touchStreamingActivity?.();\n  }\n\n  const runId = state.activeRunId ?? 'default';\n\n  switch (event) {\n    case 'status': {\n      const newRunId = typeof data.runId === 'string' ? data.runId : runId;\n      state.activeRunId = newRunId;\n      setActivityStatus('waiting');\n      break;\n    }\n    case 'token': {\n      const content =\n        typeof data.content === 'string'\n          ? data.content\n          : typeof data.delta === 'string'\n            ? data.delta\n            : typeof data.text === 'string'\n              ? data.text\n              : '';\n      if (!content) break;\n      setActivityStatus('streaming');\n      const display = assembler.ingestToken(runId, content, state.showThinking);\n      if (display !== null) {\n        chatLog.updateAssistant(display, runId);\n        tui.requestRender();\n      }\n      break;\n    }\n    case 'thinking': {\n      const thinkContent = String(data.content ?? '');\n      const isDelta = Boolean(data.delta);\n      if (data.status === 'started') break;\n      setActivityStatus('streaming');\n      const display = assembler.ingestThinking(runId, thinkContent, isDelta, state.showThinking);\n      if (display !== null) {\n        chatLog.updateAssistant(display, runId);\n        tui.requestRender();\n      }\n      break;\n    }\n    case 'thinking_end':\n    case 'message_end':\n      break;\n    case 'tool_start': {\n      const toolName = String(data.toolName ?? 'unknown');\n      const toolCallId = String(data.toolCallId || crypto.randomUUID());\n      const stack = pendingToolCallIds.get(toolName) ?? [];\n      stack.push(toolCallId);\n      pendingToolCallIds.set(toolName, stack);\n      setActivityStatus('running');\n      chatLog.startTool(toolCallId, toolName, data.args, runId);\n      tui.requestRender();\n      break;\n    }\n    case 'tool_end': {\n      const toolName = String(data.toolName ?? '');\n      let toolCallId = typeof data.toolCallId === 'string' && data.toolCallId ? data.toolCallId : '';\n      if (!toolCallId && toolName) {\n        const stack = pendingToolCallIds.get(toolName);\n        if (stack && stack.length > 0) {\n          toolCallId = stack.shift()!;\n          if (stack.length === 0) pendingToolCallIds.delete(toolName);\n        }\n      }\n      const resultText = String(data.result ?? '');\n      const isError = Boolean(data.isError);\n      if (toolCallId) {\n        chatLog.updateToolResult(toolCallId, resultText, isError);\n      }\n      setActivityStatus('streaming');\n      tui.requestRender();\n      break;\n    }\n    case 'error': {\n      const errorContent = formatAgentRunErrorForDisplay(String(data.content ?? 'Unknown error'));\n      const finalText = assembler.finalize(runId, state.showThinking);\n      if (finalText) {\n        chatLog.finalizeAssistant(finalText, runId);\n      }\n      chatLog.addSystem(`❌ ${errorContent}`);\n      state.activeRunId = null;\n      setActivityStatus('idle');\n      onRunEnded?.();\n      tui.requestRender();\n      break;\n    }\n    case 'result': {\n      const finalText = assembler.finalize(runId, state.showThinking);\n      if (finalText) {\n        chatLog.finalizeAssistant(finalText, runId);\n      }\n      state.activeRunId = null;\n      setActivityStatus('idle');\n      onRunEnded?.();\n      tui.requestRender();\n      break;\n    }\n    case 'progress': {\n      const stage = typeof data.stage === 'string' ? data.stage : '';\n      const message = typeof data.message === 'string' ? data.message : stage;\n      state.progressMessage = message || null;\n      setActivityStatus(message ? `progress: ${message}` : 'running');\n      tui.requestRender();\n      break;\n    }\n    default:\n      break;\n  }\n}\n\nexport const DEFAULT_STREAMING_WATCHDOG_MS = 30_000;\n"],"mappings":"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"}
+{"version":3,"file":"tui-agent-events.js","names":[],"sources":["../../../src/tui/tui-agent-events.ts"],"sourcesContent":["import type { AgentMessage } from '@earendil-works/pi-agent-core';\nimport type { TUI } from '@earendil-works/pi-tui';\n\nimport { formatAgentRunErrorForDisplay } from '../agent/client-error-format.js';\nimport type { ChatLog } from './components/chat-log.js';\nimport { createAssistantMessageFromText } from './components/assistant-message.js';\nimport { markRunEvent, markRunIdleAfterCompletion } from './tui-run-state.js';\nimport type { TuiEventSource, TuiState } from './tui-types.js';\n\nconst seenStreamEventKeys = new Set<string>();\nconst assistantByRun = new Map<string, AgentMessage>();\n\nexport function clearSeenStreamEvents(): void {\n  seenStreamEventKeys.clear();\n  assistantByRun.clear();\n}\n\nexport function clearSeenStreamEventsForRun(runId: string): void {\n  const prefix = `${runId}:`;\n  for (const key of Array.from(seenStreamEventKeys)) {\n    if (key.startsWith(prefix)) seenStreamEventKeys.delete(key);\n  }\n  assistantByRun.delete(runId);\n}\n\nconst STREAM_TOUCH_EVENTS = new Set([\n  'run_start',\n  'assistant_message_start',\n  'assistant_delta',\n  'thinking_delta',\n  'thinking_end',\n  'tool_start',\n  'tool_update',\n  'tool_end',\n  'assistant_message_end',\n  'progress',\n]);\n\nconst DIRECT_RESPONSE_OWNED_EVENTS = new Set([...STREAM_TOUCH_EVENTS, 'run_end', 'error']);\n\nfunction resolveEventRunId(data: Record<string, unknown>, state: TuiState): string | null {\n  if (typeof data.runId === 'string' && data.runId) return data.runId;\n  return state.activeRunId ?? state.runStatus.runId ?? state.runStatus.lastCompletedRunId;\n}\n\nexport function shouldSkipDuplicateBroadcastEvent(\n  event: string,\n  data: Record<string, unknown>,\n  state: TuiState,\n  source: TuiEventSource,\n): boolean {\n  if (source !== 'broadcast') return false;\n  if (!DIRECT_RESPONSE_OWNED_EVENTS.has(event)) return false;\n  const directRunId = state.runStatus.directStreamRunId;\n  if (!directRunId) return false;\n  return resolveEventRunId(data, state) === directRunId;\n}\n\nfunction streamEventKey(data: Record<string, unknown>, state: TuiState): string | null {\n  const runId = resolveEventRunId(data, state);\n  const seq = data.seq;\n  if (!runId || typeof seq !== 'number' || !Number.isFinite(seq)) return null;\n  return `${runId}:${seq}`;\n}\n\nfunction shouldSkipSeenStreamEvent(\n  data: Record<string, unknown>,\n  state: TuiState,\n  source: TuiEventSource,\n): boolean {\n  if (source !== 'agent-response' && source !== 'agent-resume' && source !== 'broadcast') return false;\n  const key = streamEventKey(data, state);\n  if (!key) return false;\n  if (seenStreamEventKeys.has(key)) return true;\n  seenStreamEventKeys.add(key);\n  return false;\n}\n\nfunction payload(data: Record<string, unknown>): Record<string, unknown> {\n  return data.payload && typeof data.payload === 'object' ? data.payload as Record<string, unknown> : {};\n}\n\nfunction assistantForRun(runId: string): AgentMessage {\n  let message = assistantByRun.get(runId);\n  if (!message) {\n    message = createAssistantMessageFromText('') as AgentMessage;\n    assistantByRun.set(runId, message);\n  }\n  return message;\n}\n\nfunction appendAssistantText(message: AgentMessage, delta: string): void {\n  const rec = message as { content?: unknown };\n  if (!Array.isArray(rec.content)) rec.content = [];\n  const content = rec.content as Array<Record<string, unknown>>;\n  const last = content[content.length - 1];\n  if (last?.type === 'text' && typeof last.text === 'string') {\n    last.text += delta;\n    return;\n  }\n  content.push({ type: 'text', text: delta });\n}\n\nfunction appendThinkingText(message: AgentMessage, delta: string): void {\n  const rec = message as { content?: unknown };\n  if (!Array.isArray(rec.content)) rec.content = [];\n  const content = rec.content as Array<Record<string, unknown>>;\n  const last = content[content.length - 1];\n  if (last?.type === 'thinking' && typeof last.text === 'string') {\n    last.text += delta;\n    return;\n  }\n  content.push({ type: 'thinking', text: delta, streaming: true });\n}\n\nfunction finalizeThinking(message: AgentMessage): void {\n  const content = (message as { content?: unknown }).content;\n  if (!Array.isArray(content)) return;\n  for (const block of content) {\n    if (!block || typeof block !== 'object') continue;\n    const rec = block as { type?: unknown; streaming?: boolean };\n    if (rec.type === 'thinking') rec.streaming = false;\n  }\n}\n\nfunction errorAssistantMessage(errorContent: string): AgentMessage {\n  return {\n    ...createAssistantMessageFromText(''),\n    stopReason: 'error',\n    errorMessage: errorContent,\n  } as AgentMessage;\n}\n\nexport function dispatchAgentEvent(\n  event: string,\n  data: Record<string, unknown>,\n  state: TuiState,\n  chatLog: ChatLog,\n  tui: TUI,\n  setActivityStatus: (status: string) => void,\n  touchStreamingActivity?: () => void,\n  onRunEnded?: () => void,\n  onAssistantFinalized?: (message: AgentMessage, options?: { errorMessage?: string }) => void,\n  source: TuiEventSource = 'unknown',\n): void {\n  if (shouldSkipSeenStreamEvent(data, state, source)) return;\n  if (shouldSkipDuplicateBroadcastEvent(event, data, state, source)) return;\n\n  if (STREAM_TOUCH_EVENTS.has(event)) touchStreamingActivity?.();\n\n  const runId = resolveEventRunId(data, state) ?? state.activeRunId ?? 'default';\n  const p = payload(data);\n\n  switch (event) {\n    case 'run_start': {\n      state.activeRunId = runId;\n      markRunEvent(state, 'waiting', runId, event, source);\n      setActivityStatus('waiting');\n      break;\n    }\n    case 'user_message': {\n      const message = p.message as { content?: unknown } | undefined;\n      chatLog.addUser(Array.isArray(message?.content) || typeof message?.content === 'string' ? message.content : []);\n      tui.requestRender();\n      break;\n    }\n    case 'user_transcript': {\n      chatLog.addUser(String(p.text ?? ''));\n      tui.requestRender();\n      break;\n    }\n    case 'assistant_message_start': {\n      const message = assistantForRun(runId);\n      chatLog.startAssistant(message, runId);\n      markRunEvent(state, 'streaming', runId, event, source);\n      setActivityStatus('streaming');\n      tui.requestRender();\n      break;\n    }\n    case 'assistant_delta': {\n      const delta = typeof p.delta === 'string' ? p.delta : '';\n      if (!delta) break;\n      const message = assistantForRun(runId);\n      appendAssistantText(message, delta);\n      chatLog.updateAssistant(message, runId);\n      markRunEvent(state, 'streaming', runId, event, source);\n      setActivityStatus('streaming');\n      tui.requestRender();\n      break;\n    }\n    case 'thinking_delta': {\n      const delta = typeof p.delta === 'string' ? p.delta : '';\n      if (!delta) break;\n      const message = assistantForRun(runId);\n      appendThinkingText(message, delta);\n      chatLog.updateAssistant(message, runId);\n      markRunEvent(state, 'streaming', runId, event, source);\n      setActivityStatus('streaming');\n      tui.requestRender();\n      break;\n    }\n    case 'thinking_end': {\n      const message = assistantForRun(runId);\n      finalizeThinking(message);\n      chatLog.updateAssistant(message, runId);\n      tui.requestRender();\n      break;\n    }\n    case 'tool_start': {\n      const toolName = String(p.toolName ?? 'unknown');\n      const toolCallId = String(p.toolCallId || '');\n      if (!toolCallId) break;\n      chatLog.startTool(toolCallId, toolName, p.args ?? {}, runId);\n      chatLog.markToolExecutionStarted(toolCallId);\n      markRunEvent(state, 'tool', runId, event, source);\n      setActivityStatus('running');\n      tui.requestRender();\n      break;\n    }\n    case 'tool_update': {\n      const toolName = String(p.toolName ?? 'unknown');\n      const toolCallId = String(p.toolCallId || '');\n      if (!toolCallId) break;\n      chatLog.startTool(toolCallId, toolName, {}, runId);\n      if ('details' in p) chatLog.updateToolDetails(toolCallId, p.details);\n      if (typeof p.textDelta === 'string') chatLog.updateToolResult(toolCallId, { text: p.textDelta }, false, true);\n      markRunEvent(state, 'tool', runId, event, source);\n      setActivityStatus('running');\n      tui.requestRender();\n      break;\n    }\n    case 'tool_end': {\n      const toolCallId = String(p.toolCallId || '');\n      if (!toolCallId) break;\n      chatLog.updateToolResult(toolCallId, p.result, p.status === 'error' || p.status === 'cancelled', false);\n      markRunEvent(state, 'streaming', runId, event, source);\n      setActivityStatus('streaming');\n      tui.requestRender();\n      break;\n    }\n    case 'assistant_message_end': {\n      const message = assistantForRun(runId);\n      finalizeThinking(message);\n      chatLog.finalizeAssistant(message, runId);\n      assistantByRun.delete(runId);\n      onAssistantFinalized?.(message);\n      markRunEvent(state, 'streaming', runId, event, source);\n      setActivityStatus('streaming');\n      tui.requestRender();\n      break;\n    }\n    case 'error': {\n      const errorContent = formatAgentRunErrorForDisplay(String(p.message ?? 'Unknown error'));\n      const message = errorAssistantMessage(errorContent);\n      chatLog.finalizeAssistant(message, runId);\n      onAssistantFinalized?.(message, { errorMessage: errorContent });\n      assistantByRun.delete(runId);\n      state.activeRunId = null;\n      markRunIdleAfterCompletion(state, runId, event, source);\n      setActivityStatus('idle');\n      onRunEnded?.();\n      tui.requestRender();\n      break;\n    }\n    case 'run_end': {\n      assistantByRun.delete(runId);\n      state.activeRunId = null;\n      markRunIdleAfterCompletion(state, runId, event, source);\n      setActivityStatus('idle');\n      onRunEnded?.();\n      tui.requestRender();\n      break;\n    }\n    case 'progress': {\n      const stage = typeof p.stage === 'string' ? p.stage : '';\n      const message = typeof p.message === 'string' ? p.message : stage;\n      state.progressMessage = message || null;\n      markRunEvent(state, 'progress', runId, event, source);\n      setActivityStatus(message ? `progress: ${message}` : 'running');\n      tui.requestRender();\n      break;\n    }\n  }\n}\n\nexport const DEFAULT_STREAMING_WATCHDOG_MS = 30_000;\n"],"mappings":"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"}

package/dist/src/tui/tui-backend.d.ts

@@ -1,15 +1,27 @@
 import type { ClientHistoryMessage } from '../session/client-history.js';
-import type { SessionInfo } from './tui-types.js';
+import type { ExportFormat } from '../session/types.js';
+import type { SessionInfo, TuiEventSource } from './tui-types.js';
 /** Options for sending a chat message. */
 export interface ChatSendOptions {
     sessionKey: string;
     message: string;
+    attachments?: TuiInboundAttachment[];
     thinking?: string;
 }
+export interface TuiInboundAttachment {
+    id?: string;
+    type: string;
+    mimeType?: string;
+    data?: string;
+    name?: string;
+    size?: number;
+    uri?: string;
+}
 /** SSE event from the agent stream or broadcast channel. */
 export interface TuiEvent {
     event: string;
     data: unknown;
+    source?: TuiEventSource;
 }
 /** Minimal session list item. */
 export interface TuiSessionItem {
@@ -19,6 +31,14 @@ export interface TuiSessionItem {
     totalTokens?: number | null;
     displayName?: string;
     messageCount?: number;
+    forkedFromSessionKey?: string;
+    cwd?: string;
+}
+export interface TuiAgentInfo {
+    id: string;
+    source: 'configured' | 'builtin';
+    enabled: boolean;
+    displayName?: string;
 }
 /** Model choice for the selector overlay. */
 export interface TuiModelChoice {
@@ -27,6 +47,81 @@ export interface TuiModelChoice {
     provider: string;
     contextWindow?: number;
 }
+export interface TuiSessionStats {
+    totalMessages: number;
+    userMessages: number;
+    assistantMessages: number;
+    toolCalls: number;
+    toolResults: number;
+    contextRows: number;
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+export type TuiExportFormat = ExportFormat | 'html';
+export interface TuiCompactionResult {
+    compacted: boolean;
+    summary?: string;
+    tokensBefore?: number;
+    tokensAfter?: number;
+    transcriptSummary?: string;
+}
+export interface TuiBranchSummary {
+    sourceSessionKey: string;
+    targetSessionKey: string;
+    rowCount: number;
+    entryId?: string;
+    restoredText?: string;
+}
+export type TuiShareAudience = 'friend' | 'colleague' | 'public';
+export type TuiShareMode = 'auto' | 'force-file' | 'force-site' | 'force-zip';
+export interface TuiShareRequest {
+    path: string;
+    audience?: TuiShareAudience;
+    mode?: TuiShareMode;
+    title?: string;
+    description?: string;
+}
+export interface TuiShareResult {
+    kind: string;
+    shareUrl: string;
+    title?: string;
+    description?: string;
+    thumbnailUrl?: string;
+    reachability?: string;
+    reachabilityHint?: string | null;
+    expiresAt?: string;
+    maxViews?: number | null;
+    routingReason?: string;
+    routingHint?: string;
+}
+export interface TuiStartupResources {
+    context: string[];
+    skills: string[];
+    workflows: string[];
+    connectors: string[];
+}
+/** Read-only transcript tree row for current-session navigation/inspection. */
+export interface TuiTranscriptTreeEntry {
+    id: string;
+    parentId?: string;
+    depth: number;
+    label: string;
+    role?: string;
+    userLabel?: string;
+    labelTimestamp?: string;
+    turn: number;
+    preview?: string;
+    contentText?: string;
+    toolCallPreview?: string;
+    createdAt?: string;
+    isOnActivePath?: boolean;
+    isCurrentLeaf?: boolean;
+}
 /**
  * Abstraction over the gateway (SSE) or embedded agent backend.
  *
@@ -49,10 +144,20 @@ export interface TuiBackend {
     start(): void;
     /** Stop the backend. */
     stop(): void;
+    /** Current active chat abort signal, if a run is in progress. */
+    getActiveSignal?(): AbortSignal | undefined;
     /** Send a chat message, returns the run id. */
     sendChat(opts: ChatSendOptions): Promise<{
         runId: string;
     }>;
+    /** Reattach to a live gateway/webchat run when the original response stream stalled. */
+    resumeChat?(opts: {
+        sessionKey: string;
+        runId: string;
+    }): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
     /** Abort an active run. */
     abortChat(opts: {
         sessionKey: string;
@@ -67,6 +172,8 @@ export interface TuiBackend {
     }): Promise<{
         ok: boolean;
     }>;
+    /** Load startup resources shown in `/start` and initial help. */
+    getStartupResources?(sessionKey: string): Promise<TuiStartupResources>;
     /** Load chat history for a session. */
     loadHistory(opts: {
         sessionKey: string;
@@ -74,8 +181,14 @@ export interface TuiBackend {
     }): Promise<{
         messages: HistoryMessage[];
     }>;
+    /** Load current transcript rows as a tree-shaped list. */
+    loadTranscriptTree(sessionKey: string): Promise<TuiTranscriptTreeEntry[]>;
+    /** Compute transcript message/token statistics. */
+    getSessionStats(sessionKey: string): Promise<TuiSessionStats>;
     /** List sessions. */
     listSessions(): Promise<TuiSessionItem[]>;
+    /** List agents available for TUI agent switching. */
+    listAgents(): Promise<TuiAgentInfo[]>;
     /** Fetch session info (model, tokens, thinking). */
     getSessionInfo(sessionKey: string): Promise<SessionInfo>;
     /** List available models. */
@@ -95,9 +208,62 @@ export interface TuiBackend {
     /** Compact session transcript (returns whether compaction ran). */
     compactSession(sessionKey: string, options?: {
         force?: boolean;
+        instructions?: string;
+    }): Promise<TuiCompactionResult>;
+    /** Export a session transcript. */
+    exportSession(sessionKey: string, format: ExportFormat): Promise<string>;
+    /** Import an xopc JSON session export into a new session key. */
+    importSession(targetSessionKey: string, jsonContent: string): Promise<{
+        sessionKey: string;
+        rowCount: number;
+    }>;
+    /** Create a share link for a workspace file/folder/site artifact. */
+    createShare(sessionKey: string, request: TuiShareRequest, options?: {
+        agentId?: string;
+    }): Promise<TuiShareResult>;
+    /** Ask an ephemeral side question using this session as read-only background. */
+    btwQuery(sessionKey: string, question: string): Promise<{
+        text: string;
+        error?: string;
+    }>;
+    /** Fork one session transcript into a new session key. */
+    forkSession(sourceSessionKey: string, targetSessionKey: string): Promise<{
+        sessionKey: string;
+        rowCount: number;
+    }>;
+    /** Fork one session transcript through a selected transcript-tree entry. */
+    forkSessionAt(sourceSessionKey: string, targetSessionKey: string, entryId: string): Promise<{
+        sessionKey: string;
+        rowCount: number;
+    }>;
+    /** Append or clear a label for a transcript entry. */
+    setTranscriptLabel(sessionKey: string, entryId: string, label: string | undefined): Promise<{
+        ok: boolean;
+    }>;
+    /** Append extension state for replay by TUI extension sessionManager APIs. */
+    appendCustomEntry(sessionKey: string, customType: string, data?: unknown): Promise<{
+        ok: boolean;
+    }>;
+    /** Append a visible extension custom message. */
+    appendCustomMessage(sessionKey: string, message: {
+        customType: string;
+        content?: string | unknown[];
+        display?: boolean;
+        details?: unknown;
     }): Promise<{
-        compacted: boolean;
-        summary?: string;
+        ok: boolean;
+    }>;
+    /** Persist a local TUI shell execution for replay and optional LLM context. */
+    appendBashExecution(sessionKey: string, entry: {
+        command: string;
+        output?: string;
+        exitCode?: number | null;
+        signal?: string | null;
+        excludeFromContext?: boolean;
+        truncated?: boolean;
+        fullOutputPath?: string;
+    }): Promise<{
+        ok: boolean;
     }>;
 }
 /** A single message in chat history (aligned with `ClientHistoryMessage`). */