@kingsoftcloud/agentkit-harness-ui 0.0.0-stage → 0.0.1

package/src/index.mjs

@@ -0,0 +1,52 @@
+// @kingsoftcloud/agentkit-harness-ui — public entry
+//
+// Re-exports the stable public surface. Hosts that want only the pure logic
+// (no React) should import from the subpaths (./protocol, ./reducer, ./view,
+// etc.) to avoid pulling React into their bundle. Importing from "." pulls
+// the React binding as well.
+
+export {
+  PROTOCOL_VERSION, EventType, TaskState, TaskOutcome, ToolStatus, DisplayKind,
+  TASK_TRANSITIONS, normalizeEvent, canTransition, isTaskState, isToolStatus, isEventType, isDisplayKind,
+} from "./protocol.mjs";
+
+export { initialState, reduce, reduceAll } from "./reducer.mjs";
+
+export {
+  visibleItems, isStreaming, isWaitingForFirstToken, isTerminal,
+  planProgress, activeTool, failedTools, taskStatusLabel, DEFAULT_LABELS,
+} from "./project.mjs";
+
+export {
+  latestNonEmptyLine, truncateText, redactValue, boundedDetailLines,
+  SummaryQueue, SENSITIVE_KEYS,
+} from "./summary.mjs";
+
+export {
+  toolTitle, toolDetailLines, workspaceRelative, fileDiffPreview, redactError,
+  MAX_TOOL_DETAIL_LINES,
+} from "./tool-detail.mjs";
+
+export {
+  countChangeStat, patchFilePath, inferOperationKind, parseDiffHunks, diffPreviewLines,
+  MAX_DIFF_PREVIEW_LINES,
+} from "./diff.mjs";
+
+export {
+  extractCommand, extractOutput, sanitizeAnsi, normalizeCwd,
+} from "./terminal.mjs";
+
+export {
+  renderTool, toolRendererKind,
+} from "./renderers.mjs";
+
+export {
+  buildViewModel, h, isElement, ELEMENT, DEFAULT_VIEW_OPTIONS,
+} from "./view.mjs";
+
+export { styles } from "./styles.mjs";
+export { toolIdentity, toolConversationVisible, localizedToolTitle } from './tool-identity.mjs';
+
+// React binding. Imported lazily-safe only because this barrel re-exports it;
+// hosts that do not need React should import the subpaths directly.
+export { HarnessTimeline } from "./components.mjs";

package/src/input-preview.mjs

@@ -0,0 +1,44 @@
+// Presentation only. A partial argument prefix is never an executable call.
+const FIELDS = new Set(['path', 'file_path', 'filePath', 'filename', 'command', 'content', 'new_text', 'old_text', 'pattern', 'query']);
+const MAX_PREFIX = 128 * 1024;
+export function previewToolInput(raw) {
+  const text = String(raw ?? '').slice(0, MAX_PREFIX), input = {};
+  let i = 0;
+  const space = () => { while (/\s/.test(text[i] ?? '') && i < text.length) i++; };
+  const string = partial => {
+    if (text[i++] !== '"') return;
+    const start = i; let escaped = false;
+    while (i < text.length) {
+      const ch = text[i++];
+      if (escaped) { escaped = false; continue; }
+      if (ch === '\\') { escaped = true; continue; }
+      if (ch === '"') { try { return JSON.parse(text.slice(start - 1, i)); } catch { return; } }
+    }
+    if (!partial) return;
+    const prefix = text.slice(start).replace(/\\u[0-9a-fA-F]{0,3}$/, '').replace(/\\$/, '');
+    try { return JSON.parse(`"${prefix}"`); } catch { return; }
+  };
+  space(); if (text[i++] !== '{') return input;
+  while (i < text.length) {
+    space(); if (text[i] === '}') break;
+    const key = string(false); if (key === undefined) break;
+    space(); if (text[i++] !== ':') break; space();
+    if (text[i] === '"') {
+      const value = string(true);
+      if (FIELDS.has(key) && value !== undefined) input[key] = value.slice(0, key === 'content' || key.endsWith('_text') ? 8000 : 2000);
+    } else {
+      let depth = 0, quoted = false, escaped = false;
+      while (i < text.length) {
+        const ch = text[i];
+        if (!quoted && depth === 0 && (ch === ',' || ch === '}')) break;
+        i++;
+        if (quoted) { if (escaped) escaped = false; else if (ch === '\\') escaped = true; else if (ch === '"') quoted = false; }
+        else if (ch === '"') quoted = true;
+        else if (ch === '[' || ch === '{') depth++;
+        else if (ch === ']' || ch === '}') depth--;
+      }
+    }
+    space(); if (text[i++] !== ',') break;
+  }
+  return input;
+}

package/src/inspector.mjs

@@ -0,0 +1,40 @@
+import { redactValue, truncateText } from './summary.mjs';
+
+const bounded = value => {
+  let parsed = value;
+  if (typeof value === 'string') { try { parsed = JSON.parse(value); } catch { /* text observation */ } }
+  const text = typeof parsed === 'string' ? parsed : JSON.stringify(parsed, (key, value) => redactValue(key, value), 2);
+  return truncateText(text.slice(0, 24000), { maxChars: 4000, maxLines: 500 });
+};
+
+/** The host selects a committed call; the package owns the read-only dialog. */
+export function createToolInspector(React) {
+  const { createElement: h, useEffect, useRef } = React;
+  return function ToolInspector({ item, onClose, labels = {} }) {
+    const ref = useRef(null);
+    useEffect(() => {
+      const dialog = ref.current;
+      if (!item || !dialog) return;
+      dialog.showModal?.();
+      return () => { if (dialog.open) dialog.close?.(); };
+    }, [item?.callId]);
+    if (!item) return null;
+    return h('dialog', { ref, className: 'harness-tool-inspector', 'aria-label': labels.toolDetails || 'Tool details',
+      onCancel: event => { event.preventDefault(); onClose(); },
+      style: { color: 'inherit', background: 'var(--harness-bg, Canvas)', border: '1px solid color-mix(in srgb, currentColor 20%, transparent)',
+        borderRadius: '10px', padding: '20px', width: 'min(720px, calc(100vw - 40px))', maxHeight: '85vh', overflow: 'auto' } },
+    h('style', null, '.harness-tool-inspector::backdrop{background:rgb(0 0 0 / .35)}.harness-tool-inspector pre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:12px;line-height:1.6}'),
+    h('header', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
+      h('strong', null, item.name), h('button', { type: 'button', onClick: onClose, autoFocus: true }, labels.close || 'Close')),
+    h('p', null, `${labels.state || 'State'}: ${item.status}`),
+    h('h4', null, labels.arguments || 'Arguments'), h('pre', null, bounded(item.input ?? {})),
+    h('h4', null, labels.result || 'Result'),
+    h('pre', null, item.error ? bounded(item.error) : item.result != null ? bounded(item.result)
+      : labels.noSettledResult || 'No settled result is available'),
+    item.display?.kind === 'file_edit' ? h(React.Fragment, null,
+      h('h4', null, labels.appliedChanges || 'Applied changes'),
+      ...item.display.files.map(file => h('section', { key: file.path }, h('strong', null, file.path),
+        h('pre', null, file.patch || labels.diffUnavailable || 'No diff preview is available'),
+        file.truncated ? h('p', null, labels.diffTruncated || 'Diff preview is truncated') : null))) : null);
+  };
+}

package/src/project.mjs

@@ -0,0 +1,132 @@
+import { contextTimelineItems } from './context-markers.mjs';
+// @kingsoftcloud/agentkit-harness-ui — projection selectors
+//
+// Pure read-only selectors over reducer state. They derive the concise facts the
+// timeline renders (ordered items, streaming/waiting flags, plan progress,
+// active tool, errors) without mutating state. Kept separate from the view so
+// the same projections can be tested and reused by hosts and screens readers.
+
+import { TaskState, ToolStatus } from "./protocol.mjs";
+import { toolConversationVisible } from './tool-identity.mjs';
+
+/**
+ * Ordered timeline items in stream order. The reducer already maintains order;
+ * this selector is the stable seam for hosts that build their own view.
+ * @param {object} state
+ * @returns {object[]}
+ */
+export function visibleItems(state, { includeInternal = false } = {}) {
+  const items = Array.isArray(state?.items) ? state.items : [];
+  const timeline = contextTimelineItems(items, state?.contextMarkers);
+  if (includeInternal) return timeline;
+  const visible = [];
+  for (const item of timeline) {
+    if (['tool', 'tool-preview'].includes(item.kind) && !toolConversationVisible(item)) continue;
+    if (item.kind === 'thought' && !String(item.text ?? '').trim()) continue;
+    const previous = visible.at(-1);
+    if (item.kind === 'thought' && previous?.kind === 'thought') {
+      const parts = [...previous.parts ?? [previous], item];
+      visible[visible.length - 1] = { ...previous, parts, memberIds: parts.map(part => part.id),
+        ...(parts.some(part => part.responseId) ? { responseId: parts.every(part => part.responseId === parts[0].responseId) ? parts[0].responseId : undefined } : {}),
+        text: parts.map(part => part.text).join('\n\n'), streaming: parts.some(part => part.streaming),
+        duration: parts.every(part => Number.isFinite(part.duration)) ? parts.reduce((sum, part) => sum + part.duration, 0) : undefined };
+    } else visible.push(item);
+  }
+  return visible;
+}
+
+/** True when any text or thought is still streaming. */
+export function isStreaming(state) {
+  return visibleItems(state).some(item => item.streaming);
+}
+
+/**
+ * True when the task is running but no visible transcript item has arrived yet.
+ * The timeline shows a neutral "Thinking…" status placeholder in this
+ * window. This is a status indicator, not a transcript item — it is never
+ * invented reasoning content, and `thinking.start` alone (which creates no
+ * item) still leaves the window open until the first delta lands.
+ * @param {object} state
+ */
+export function isWaitingForFirstToken(state) {
+  if (!state) return false;
+  if (state.taskState !== TaskState.Running) return false;
+  return visibleItems(state).length === 0;
+}
+
+/** A finished interrupted driver can still have an unverified outcome. */
+export function isTerminal(state) {
+  return state?.taskState === TaskState.Interrupted && state.taskOutcome != null
+    || state?.taskState === TaskState.Completed
+    || state?.taskState === TaskState.Failed
+    || state?.taskState === TaskState.Cancelled
+    || state?.taskState === TaskState.Blocked
+    || state?.taskState === TaskState.Unverified;
+}
+
+/** Concise plan progress: completed count, total, and the in-progress label. */
+export function planProgress(state) {
+  const plan = state?.plan;
+  if (!Array.isArray(plan) || !plan.length) return null;
+  const total = plan.length;
+  const completed = plan.filter(item => item.status === "completed").length;
+  const inProgress = plan.find(item => item.status === "in_progress");
+  return {
+    total,
+    completed,
+    inProgress: inProgress ? { id: inProgress.id, content: inProgress.content } : null,
+    ratio: total ? completed / total : 0,
+  };
+}
+
+/** The most recent tool that is still scheduled/running, if any. */
+export function activeTool(state) {
+  const items = visibleItems(state);
+  for (let i = items.length - 1; i >= 0; i -= 1) {
+    const item = items[i];
+    if (item.kind === "tool" && (item.status === ToolStatus.Running || item.status === ToolStatus.Scheduled)) {
+      return item;
+    }
+  }
+  return null;
+}
+
+/** Failed tool items, newest first, for concise error surfacing. */
+export function failedTools(state) {
+  return visibleItems(state).filter(item => item.kind === "tool" && item.status === ToolStatus.Failed);
+}
+
+/** A one-line concise status string for the task, host-declared only. */
+export function taskStatusLabel(state, labels = DEFAULT_LABELS) {
+  const s = state?.taskState;
+  if (s === TaskState.Running) {
+    const tool = activeTool(state);
+    if (tool) return tool.name;
+    if (state.pendingThinking?.size || visibleItems(state).some(i => i.kind === "thought" && i.streaming)) {
+      return labels.thinking;
+    }
+    return labels.running;
+  }
+  if (s === TaskState.Interrupted) return labels.interrupted;
+  if (s === TaskState.Recovered) return labels.recovered;
+  if (s === TaskState.Failed) return labels.failed;
+  if (s === TaskState.Completed) return labels.completed;
+  if (s === TaskState.Cancelled) return labels.cancelled;
+  if (s === TaskState.Blocked) return labels.blocked || "Blocked";
+  if (s === TaskState.Unverified) return state.verificationRequired === true
+    ? labels.unverified || "Unverified" : labels.ended || "Finished";
+  if (s === TaskState.Waiting) return labels.waiting || "Waiting for input";
+  if (s === TaskState.Paused) return labels.paused || "Paused";
+  return labels.idle;
+}
+
+export const DEFAULT_LABELS = Object.freeze({
+  idle: "",
+  running: "Running",
+  thinking: "Thinking…",
+  interrupted: "Interrupted",
+  recovered: "Recovering",
+  failed: "Failed",
+  completed: "Completed",
+  cancelled: "Cancelled",
+});

package/src/protocol.mjs

@@ -0,0 +1,362 @@
+// @kingsoftcloud/agentkit-harness-ui — event protocol
+//
+// Explicitly versioned stable event protocol that a host (the AgentKit Native
+// runtime, a Studio adapter, or a test harness) emits against. The UI consumes
+// only these events; it never calls runtime, provider, or session-store
+// internals. The reducer and the timeline are pure projections of this stream.
+//
+// Versioning: every event carries `v`. Bump PROTOCOL_VERSION when the event
+// shapes change in a way the reducer cannot normalize. Unknown future fields
+// are ignored, not rejected, so additive changes remain backward compatible.
+// The reducer accepts `v` up to its known ceiling and normalizes missing
+// optional fields. See README for host integration.
+
+export const PROTOCOL_VERSION = 1;
+
+/**
+ * Event type constants. Use the string form on the wire; the constants exist
+ * for readable host code and stable comparisons in tests.
+ */
+export const EventType = Object.freeze({
+  TaskStarted: "task.started",
+  TaskState: "task.state",
+  TaskFinished: "task.finished",
+  TextDelta: "text.delta",
+  TextDone: "text.done",
+  ThinkingStart: "thinking.start",
+  ThinkingDelta: "thinking.delta",
+  ThinkingDone: "thinking.done",
+  ToolPreview: "tool.preview",
+  SubagentBound: "subagent.bound",
+  ToolScheduled: "tool.scheduled",
+  ToolStarted: "tool.started",
+  ToolState: "tool.state",
+  ToolProgress: "tool.progress",
+  ToolResult: "tool.result",
+  ToolError: "tool.error",
+  PlanUpdated: "plan.updated",
+  ContextMarker: "context.marker",
+});
+
+/** Task lifecycle states the host may declare. */
+export const TaskState = Object.freeze({
+  Idle: "idle",
+  Running: "running",
+  Interrupted: "interrupted",
+  Failed: "failed",
+  Recovered: "recovered",
+  Completed: "completed",
+  Cancelled: "cancelled",
+  Blocked: "blocked",
+  Unverified: "unverified",
+  Waiting: "waiting",
+  Paused: "paused",
+});
+
+/** Host-declared terminal outcomes. */
+export const TaskOutcome = Object.freeze({
+  Blocked: "blocked",
+  Unverified: "unverified",
+  Completed: "completed",
+  Failed: "failed",
+  Cancelled: "cancelled",
+});
+
+/**
+ * Allowed task-state transitions. `cancelled` is reachable from any state
+ * (the host may cancel mid-flight). Terminal states (`completed`, `cancelled`)
+ * accept no further transitions. The reducer ignores `task.state` events that
+ * are not in this table from the current state; it never synthesizes a state.
+ */
+export const TASK_TRANSITIONS = Object.freeze({
+  [TaskState.Idle]: [TaskState.Running],
+  [TaskState.Running]: [TaskState.Interrupted, TaskState.Failed, TaskState.Completed, TaskState.Cancelled, TaskState.Waiting, TaskState.Paused, TaskState.Blocked, TaskState.Unverified],
+  [TaskState.Waiting]: [TaskState.Running, TaskState.Interrupted, TaskState.Cancelled, TaskState.Failed],
+  [TaskState.Paused]: [TaskState.Running, TaskState.Interrupted, TaskState.Cancelled, TaskState.Failed],
+  [TaskState.Blocked]: [],
+  [TaskState.Unverified]: [],
+  [TaskState.Interrupted]: [TaskState.Running, TaskState.Recovered, TaskState.Failed, TaskState.Cancelled],
+  [TaskState.Failed]: [TaskState.Running, TaskState.Recovered, TaskState.Cancelled],
+  [TaskState.Recovered]: [TaskState.Running, TaskState.Cancelled],
+  [TaskState.Completed]: [],
+  [TaskState.Cancelled]: [],
+});
+
+/** Tool lifecycle statuses, keyed by callId. */
+export const ToolStatus = Object.freeze({
+  NotDispatched: "not_dispatched",
+  Uncertain: "uncertain",
+  Interrupted: "interrupted",
+  Waiting: "waiting",
+  Scheduled: "scheduled",
+  Running: "running",
+  Completed: "completed",
+  Failed: "failed",
+});
+
+/**
+ * Explicit presentation payload kinds a host may attach to `tool.result`
+ * `display`. The UI renders a purpose-built block for each known kind; an
+ * unknown kind falls back to the generic bounded object preview. Every kind
+ * is optional — a host that only emits a raw `result` still renders fine.
+ */
+export const DisplayKind = Object.freeze({
+  CommandOutput: "command_output",
+  CommandPreview: "command_preview",
+  FileDiff: "file_diff",
+  FileRead: "file_read",
+  FileEdit: "file_edit",
+  Generic: "generic",
+});
+const DISPLAY_KINDS = new Set(Object.values(DisplayKind));
+
+const EVENT_TYPES = new Set(Object.values(EventType));
+const TASK_STATES = new Set(Object.values(TaskState));
+const TASK_OUTCOMES = new Set(Object.values(TaskOutcome));
+const TOOL_STATUSES = new Set(Object.values(ToolStatus));
+
+/**
+ * @typedef {Object} HarnessEvent envelope shared by every event.
+ * @property {1} v protocol version; must equal PROTOCOL_VERSION.
+ * @property {string} type one of EventType.
+ * @property {string} id stable event id; replaying the same id is a no-op.
+ * @property {"interrupted"} [executionState] closed driver state, separate from an unverified outcome.
+ * @property {number} [ts] client-observed timestamp (ms); for diagnostics only.
+ * @property {number} [seq] optional host monotonic sequence; for replay audit.
+ */
+
+/**
+ * Validate an event envelope and its type-specific payload. Returns a normalized
+ * copy with missing optional fields filled. Throws on an unrecoverable shape
+ * (unknown event type, wrong protocol version, missing required id/type).
+ * Malformed payloads the UI can survive (e.g. a tool input that is not an
+ * object) are coerced to a safe default rather than thrown, matching the
+ * tool-detail-block failure contract: skip invalid fields, never break render.
+ *
+ * @param {HarnessEvent & Record<string, unknown>} event
+ * @returns {HarnessEvent & Record<string, unknown>}
+ */
+export function normalizeEvent(event) {
+  if (!event || typeof event !== "object") throw new TypeError("event must be an object");
+  const v = event.v;
+  if (v !== PROTOCOL_VERSION) {
+    throw new RangeError(`event.v is ${String(v)}; expected protocol version ${PROTOCOL_VERSION}`);
+  }
+  const type = String(event.type || "");
+  if (!EVENT_TYPES.has(type)) throw new RangeError(`unknown event type: ${String(event.type)}`);
+  const id = event.id == null ? "" : String(event.id);
+  if (!id) throw new RangeError(`event.id is required for ${type}`);
+  const base = { v, type, id, ts: typeof event.ts === "number" ? event.ts : null, seq: typeof event.seq === "number" ? event.seq : null };
+  // Optional presentation lineage, supplied by the Host's response boundary.
+  // It is never a Run identity, tool claim or an execution permission.
+  if (['text.delta', 'text.done', 'thinking.delta', 'thinking.done', 'tool.preview', 'tool.scheduled'].includes(type)
+    && typeof event.responseId === 'string' && event.responseId.length > 0 && event.responseId.length <= 1024)
+    base.responseId = event.responseId;
+  return Object.assign(base, normalizePayload(type, event));
+}
+
+function normalizePayload(type, event) {
+  switch (type) {
+    case EventType.TaskStarted:
+      return { taskId: str(event.taskId), title: str(event.title) || null, runId: str(event.runId) || null,
+        ...(hostTime(event.startedAt) !== null ? { startedAt: event.startedAt } : {}) };
+    case EventType.TaskState:
+      return { state: requiredChoice(event.state, TASK_STATES, "task state"), reason: str(event.reason) || null, message: str(event.message) || null };
+    case EventType.TaskFinished: {
+      const outcome = requiredChoice(event.outcome, TASK_OUTCOMES, "task outcome");
+      if (event.executionState !== undefined && (event.executionState !== TaskState.Interrupted || outcome !== TaskOutcome.Unverified))
+        throw new RangeError('interrupted execution requires an unverified outcome');
+      return { outcome, summary: str(event.summary) || null, error: str(event.error) || null, reason: str(event.reason) || null,
+        ...(hostTime(event.endedAt) !== null ? { endedAt: event.endedAt } : {}),
+        ...(typeof event.finalAnswerId === 'string' && event.finalAnswerId ? { finalAnswerId: event.finalAnswerId } : {}),
+        ...(event.executionState === TaskState.Interrupted ? { executionState: TaskState.Interrupted } : {}),
+        verificationRequired: typeof event.verificationRequired === 'boolean' ? event.verificationRequired : null };
+    }
+    case EventType.TextDelta:
+      return { itemId: str(event.itemId), delta: str(event.delta) };
+    case EventType.TextDone:
+      return { itemId: str(event.itemId), ...(typeof event.sourceMessageId === "string" ? { sourceMessageId: event.sourceMessageId } : {}), ...(typeof event.text === "string" ? { text: event.text } : {}),
+        ...(event.role === "user" ? { role: "user" } : {}) };
+    case EventType.ThinkingStart:
+      return { itemId: str(event.itemId), provider: true };
+    case EventType.ThinkingDelta:
+      return { itemId: str(event.itemId), delta: str(event.delta), provider: true };
+    case EventType.ThinkingDone:
+      return { itemId: str(event.itemId), provider: true,
+        ...(typeof event.sourceMessageId === "string" ? { sourceMessageId: event.sourceMessageId } : {}),
+        ...(typeof event.text === "string" ? { text: event.text } : {}),
+        ...(event.duration != null ? { duration: numberOrNull(event.duration) } : {}) };
+    case EventType.SubagentBound: {
+      const child = event.child;
+      if (!child || !['runId', 'sessionId', 'parentRunId', 'role', 'title'].every(key => typeof child[key] === 'string')
+        || !child.runId || !child.sessionId || !child.parentRunId || child.title.length > 512) throw Error('Invalid subagent identity');
+      return { callId: str(event.callId), child: { runId: child.runId, sessionId: child.sessionId,
+        parentRunId: child.parentRunId, role: child.role, title: child.title, phase: str(child.phase),
+        activity: child.activity && typeof child.activity.name === 'string' && TOOL_STATUSES.has(child.activity.status)
+          ? { name: child.activity.name, input: asObject(child.activity.input), status: child.activity.status } : null } };
+    }
+    case EventType.ToolState:
+      return { callId: str(event.callId), status: requiredChoice(event.status, TOOL_STATUSES, "tool state"), message: str(event.message) || null };
+    case EventType.ToolPreview:
+      return { previewId: str(event.previewId), name: str(event.name) || 'tool', input: asObject(event.input),
+        receivedChars: Number.isSafeInteger(event.receivedChars) && event.receivedChars >= 0 ? event.receivedChars : 0 };
+    case EventType.ToolScheduled:
+      return { callId: str(event.callId), name: str(event.name) || "tool", input: asObject(event.input) };
+    case EventType.ToolStarted:
+      return { callId: str(event.callId) };
+    case EventType.ToolProgress:
+      return { callId: str(event.callId), progress: str(event.progress) || null, message: str(event.message) || null,
+        display: normalizeDisplay(event.display) };
+    case EventType.ToolResult:
+      return { callId: str(event.callId), result: event.result === undefined ? null : event.result, display: normalizeDisplay(event.display) };
+    case EventType.ToolError:
+      return { callId: str(event.callId), error: str(event.error) || "tool failed" };
+    case EventType.ContextMarker: {
+      const marker = event.marker;
+      if (!marker || typeof marker.id !== 'string' || !marker.id || marker.id.length > 256
+        || !['running', 'completed', 'failed', 'interrupted', 'noop'].includes(marker.status)
+        || !['auto', 'manual'].includes(marker.origin) || !marker.after
+        || !['start', 'tool', 'message'].includes(marker.after.kind)
+        || marker.after.kind !== 'start' && (typeof marker.after.id !== 'string' || !marker.after.id || marker.after.id.length > 256))
+        throw Error('Invalid context marker');
+      return { marker: { id: marker.id, status: marker.status, origin: marker.origin,
+        after: { kind: marker.after.kind, ...(marker.after.id ? { id: marker.after.id } : {}) } } };
+    }
+    case EventType.PlanUpdated:
+      return { items: Array.isArray(event.items) ? event.items.map(normalizePlanItem).filter(Boolean) : [] };
+    default:
+      return {};
+  }
+}
+
+function normalizePlanItem(item) {
+  if (!item || typeof item !== "object") return null;
+  return {
+    id: str(item.id),
+    content: str(item.content),
+    status: pick(item.status, new Set(["pending", "in_progress", "completed"]), "pending"),
+    priority: str(item.priority) || null,
+  };
+}
+
+function str(value) {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  try { return JSON.stringify(value); } catch { return String(value); }
+}
+
+function asObject(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value;
+  if (typeof value === "string") {
+    try { const parsed = JSON.parse(value); return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { value }; }
+    catch { return { value }; }
+  }
+  return value == null ? {} : { value: str(value) };
+}
+
+/**
+ * Normalize a `tool.result`/`tool.progress` display payload. A known `kind`
+ * yields a purpose-built shape; an unknown or missing kind falls back to a
+ * generic object so the generic renderer still renders something safe. The
+ * normalizer never reads files or infers a write succeeded — it only carries
+ * the host-supplied fields through, coerced to safe primitives.
+ * @param {unknown} display
+ * @returns {Record<string, unknown>}
+ */
+function normalizeDisplay(display) {
+  const obj = asObject(display);
+  if (!obj || typeof obj !== "object") return {};
+  const kind = pick(obj.kind, DISPLAY_KINDS, DisplayKind.Generic);
+  switch (kind) {
+    case DisplayKind.CommandOutput:
+      return {
+        kind, stdout: str(obj.stdout), stderr: str(obj.stderr),
+        exit: numberOrNull(obj.exit ?? obj.exitCode ?? obj.code ?? obj.returncode),
+        cwd: str(obj.cwd),
+      };
+    case DisplayKind.CommandPreview:
+      return { kind, fullText: str(obj.fullText ?? obj.stdout ?? obj.text),
+        ...(typeof obj.stderr === 'string' ? { stderr: obj.stderr } : {}) };
+    case DisplayKind.FileDiff:
+      return {
+        kind, path: str(obj.path), patch: str(obj.patch),
+        changeStat: normalizeChangeStat(obj.changeStat),
+        operationKind: str(obj.operationKind) || null,
+      };
+    case DisplayKind.FileRead:
+      return { kind, path: str(obj.path), entryType: pick(obj.entryType, new Set(["file", "directory"]), "file") };
+    case DisplayKind.FileEdit:
+      return { kind, omittedFiles: Number.isSafeInteger(obj.omittedFiles) && obj.omittedFiles > 0 ? obj.omittedFiles : 0,
+        files: Array.isArray(obj.files) ? obj.files.map(normalizeFileEdit).filter(Boolean) : [] };
+    default:
+      return { ...obj, kind };
+  }
+}
+
+function normalizeFileEdit(file) {
+  if (!file || typeof file !== "object") return null;
+  return {
+    path: str(file.path),
+    patch: str(file.patch),
+    truncated: file.truncated === true,
+    changeStat: normalizeChangeStat(file.changeStat),
+    operationKind: str(file.operationKind) || null,
+  };
+}
+
+function normalizeChangeStat(stat) {
+  if (!stat || typeof stat !== "object") return null;
+  const added = numberOrNull(stat.added);
+  const removed = numberOrNull(stat.removed);
+  if (added == null && removed == null) return null;
+  return { added: Math.max(0, added ?? 0), removed: Math.max(0, removed ?? 0) };
+}
+
+function numberOrNull(value) {
+  if (value == null || value === "") return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function hostTime(value) { return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null; }
+
+/** @returns {boolean} */
+export function isDisplayKind(value) {
+  return DISPLAY_KINDS.has(String(value));
+}
+
+function pick(value, allowed, fallback) {
+  const s = str(value);
+  return allowed.has(s) ? s : fallback;
+}
+
+/**
+ * @param {unknown} state
+ * @returns {boolean}
+ */
+export function canTransition(from, to) {
+  if (to === TaskState.Cancelled) return from !== TaskState.Completed && from !== TaskState.Cancelled;
+  const allowed = TASK_TRANSITIONS[from];
+  return Boolean(allowed && allowed.includes(to));
+}
+
+/** @returns {boolean} */
+export function isTaskState(value) {
+  return TASK_STATES.has(String(value));
+}
+
+/** @returns {boolean} */
+export function isToolStatus(value) {
+  return TOOL_STATUSES.has(String(value));
+}
+
+/** @returns {boolean} */
+export function isEventType(value) {
+  return EVENT_TYPES.has(String(value));
+}
+
+function requiredChoice(value, allowed, label) {
+  if (!allowed.has(value)) throw new TypeError(`Missing or unsupported ${label}`);
+  return value;
+}