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

package/src/browser-response-groups.mjs

@@ -0,0 +1,57 @@
+import { toolIdentity } from './tool-identity.mjs';
+
+const isTool = item => ['tool', 'tool-preview'].includes(item.kind);
+const isBrowser = item => isTool(item) && !item.child && (toolIdentity(item.name).family === 'browser'
+  || ['mcp__computer-use__', 'mcp__plugin_zcode-cua_computer-use__'].some(prefix => item.name?.startsWith(prefix)));
+
+/** Response membership is a Host fact, not adjacency or text inference. This
+ * read-only projection mirrors the reference CUA flow: pure browser responses
+ * share a work stage; mixed responses and final prose stay in the outer flow. */
+export function browserResponseGroups(items, { stageTailIsRunning = false } = {}) {
+  const responses = new Map();
+  for (const item of items) if (isTool(item) && item.responseId) {
+    const value = responses.get(item.responseId) ?? { browser: false, other: false };
+    if (isBrowser(item)) value.browser = true; else value.other = true;
+    responses.set(item.responseId, value);
+  }
+  const result = [], identities = new Map(); let active = null;
+  const close = () => { if (active) active.active = false; active = null; };
+  const append = item => {
+    if (!active) {
+      const identity = item.responseId ? `activity:browser:response:${item.responseId}`
+        : `activity:browser:call:${item.callId ?? item.id}`;
+      const occurrence = identities.get(identity) ?? 0;
+      identities.set(identity, occurrence + 1);
+      // A mixed response can resume browser work after another tool. Distinct
+      // stages must not share React keys or disclosure state with one another.
+      active = { kind: 'activity-group', id: occurrence ? `${identity}:stage:${occurrence}` : identity,
+        family: 'browser', children: [], events: [], active: true,
+        failed: 0, uncertain: 0 };
+      result.push(active);
+    }
+    active.events.push(item);
+    if (isBrowser(item)) {
+      active.children.push(item);
+      if (item.status === 'failed') active.failed++;
+      if (['uncertain', 'interrupted', 'waiting'].includes(item.status)) active.uncertain++;
+    }
+  };
+  for (const item of items) {
+    if (isBrowser(item)) { append(item); continue; }
+    if (isTool(item) || item.kind === 'text' && item.role === 'user') { close(); result.push(item); continue; }
+    if (item.kind === 'text' || item.kind === 'thought') {
+      const classification = item.responseId && responses.get(item.responseId);
+      if (classification?.browser && !classification.other) { append(item); continue; }
+      // A future tool declaration may classify streaming text/reasoning. Keep
+      // it exactly where it is until evidence arrives, without closing an
+      // earlier browser stage merely because the new response is incomplete.
+      if (item.kind === 'thought' && !classification || item.kind === 'text' && item.responseId && !classification && item.streaming) {
+        result.push(item); continue;
+      }
+      close(); result.push(item); continue;
+    }
+    result.push(item);
+  }
+  if (!stageTailIsRunning) close();
+  return result;
+}

package/src/command-output.mjs

@@ -0,0 +1,57 @@
+import { sanitizeAnsi } from './terminal.mjs';
+
+const states = new Set(['starting', 'running', 'completed', 'failed', 'canceled', 'timed_out', 'output_limit', 'unknown', 'unavailable']);
+const statusLabels = { starting: '正在启动', running: '执行中', completed: '已结束', failed: '执行失败', canceled: '已停止',
+  timed_out: '执行超时', output_limit: '输出达到限制', unknown: '执行结果未知', unavailable: '输出不可用' };
+const textWindow = text => { const points = Array.from(text); return { text: points.slice(-131072).join(''), omitted: Math.max(0, points.length - 131072) }; };
+
+/** Cursor values refer to backend bytes, never the redacted display length.
+ * This read-only view does not manufacture Harness events or tool receipts.
+ */
+export function appendCommandOutput(previous, page, request) {
+  if (page?.contract !== 'agentkit.studio-command-output/v1' || page.sessionId !== request.sessionId || page.taskId !== request.taskId
+    || typeof page.runId !== 'string' || !states.has(page.status)
+    || page.command !== undefined && (typeof page.command !== 'string' || page.command.length > 32768)
+    || ['stdout', 'stderr'].some(key => typeof page[key] !== 'string' || page[key].length > 65536)
+    || ['stdoutCursor', 'stderrCursor'].some(key => !Number.isSafeInteger(page[key]) || page[key] < (request[key] ?? 0))
+    || previous && (previous.sessionId !== page.sessionId || previous.taskId !== page.taskId
+      || ['stdoutCursor', 'stderrCursor'].some(key => previous[key] !== (request[key] ?? 0)))
+    || !previous && ['stdoutCursor', 'stderrCursor'].some(key => (request[key] ?? 0) !== 0))
+    throw Error('命令输出窗口或归属已变化');
+  const out = textWindow((previous?.stdout ?? '') + (page.stdoutCursor > (request.stdoutCursor ?? 0) ? page.stdout : ''));
+  const err = textWindow((previous?.stderr ?? '') + (page.stderrCursor > (request.stderrCursor ?? 0) ? page.stderr : ''));
+  return { ...page, stdout: out.text, stderr: err.text,
+    omitted: (previous?.omitted ?? 0) + out.omitted + err.omitted,
+    exitCode: ['completed', 'failed', 'canceled', 'timed_out', 'output_limit'].includes(page.status)
+      && page.evidenceIncomplete !== true && Number.isSafeInteger(page.exitCode) ? page.exitCode : null };
+}
+
+/** Peer-injected React; all docking, transport and disclosure stay in the Host. */
+export function createCommandOutputComponents(React) {
+  const { createElement: h, useEffect, useRef, useState } = React;
+  function CommandOutputPane({ output, title = '终端输出', error, onCopy, theme = 'dark' }) {
+    const viewport = useRef(null), [following, setFollowing] = useState(true);
+    useEffect(() => { if (following && viewport.current) viewport.current.scrollTop = viewport.current.scrollHeight; },
+      [following, output?.stdout, output?.stderr]);
+    const stdout = sanitizeAnsi(output?.stdout ?? ''), stderr = sanitizeAnsi(output?.stderr ?? '');
+    const muted = theme === 'light' ? '#64666b' : '#96979b';
+    return h('section', { 'data-testid': 'native-command-output-pane', style: { height: '100%', display: 'flex', flexDirection: 'column', minHeight: 0,
+      color: theme === 'light' ? '#222' : '#e5e5e5', background: theme === 'light' ? '#fff' : '#141414', padding: 16, boxSizing: 'border-box', fontSize: 13 } },
+    h('header', { style: { display: 'flex', alignItems: 'center', gap: 8 } },
+      h('strong', { style: { overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', flex: 1 }, title: output?.command || title }, output?.command || title),
+      onCopy ? h('button', { type: 'button', 'aria-label': '复制终端输出', onClick: () => onCopy(stdout + (stderr ? '\n' + stderr : '')) }, '复制') : null),
+    h('p', { 'data-testid': 'command-output-status', style: { color: muted } }, output ? statusLabels[output.status] : '正在读取输出…',
+      output?.exitCode !== null && output?.exitCode !== undefined ? ` · 退出码 ${output.exitCode}` : ''),
+    error ? h('p', { role: 'alert' }, error) : null,
+    output?.withheld ? h('p', { role: 'status' }, '输出等待展示策略处理') : null,
+    output?.evidenceIncomplete ? h('p', { role: 'status' }, '执行证据不完整，不能确认最终结果') : null,
+    output?.omitted ? h('p', { role: 'status', style: { color: muted } }, `较早的 ${output.omitted} 个字符已从预览省略`) : null,
+    h('div', { ref: viewport, style: { overflow: 'auto', flex: 1, minHeight: 0 }, onScroll: () => {
+      const node = viewport.current; if (node) setFollowing(node.scrollHeight - node.scrollTop - node.clientHeight < 12);
+    } }, h('pre', { 'data-testid': 'command-output-stdout', style: { whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' } }, stdout),
+    stderr ? h('pre', { 'data-testid': 'command-output-stderr', 'aria-label': '标准错误输出', style: { whiteSpace: 'pre-wrap', overflowWrap: 'anywhere', color: muted } }, stderr) : null),
+    output?.outputMayBeTruncated ? h('p', { style: { color: muted } }, '仍有后续输出，或进程输出已达到保留限制') : null,
+    !following ? h('button', { type: 'button', onClick: () => setFollowing(true) }, '回到最新') : null);
+  }
+  return { CommandOutputPane };
+}

package/src/components.mjs

@@ -0,0 +1,9 @@
+import * as React from "react";
+import { createHarnessComponents } from "./react-binding.mjs";
+export const { HarnessTimeline } = createHarnessComponents(React);
+export { buildViewModel, styles } from "./react-binding.mjs";
+
+import * as ReactDOM from "react-dom";
+import { createStatusPanelComponents } from "./status-panel.mjs";
+export const { ConversationStatusPanel, SubagentDirectory } = createStatusPanelComponents(React, ReactDOM);
+export { statusPanelStyles } from "./status-panel.mjs";

package/src/context-markers.mjs

@@ -0,0 +1,19 @@
+/** Place committed context notices at their original transcript boundary.
+ * Unloaded anchors stay hidden until history arrives, never moved to the end. */
+export function contextTimelineItems(items, markers = []) {
+  const boundaries = new Map();
+  for (const marker of markers) {
+    let index = -1;
+    if (marker.after.kind === 'start') {
+      index = 0; while (index < items.length && items[index].role === 'user') index++;
+    } else {
+      for (let i = items.length - 1; i >= 0; i--) {
+        if (marker.after.kind === 'tool' ? items[i].callId === marker.after.id : items[i].sourceMessageId === marker.after.id) { index = i + 1; break; }
+      }
+    }
+    if (index < 0) continue;
+    const group = boundaries.get(index) ?? [];
+    group.push({ kind: 'context-marker', ...marker }); boundaries.set(index, group);
+  }
+  return items.flatMap((item, index) => [...boundaries.get(index) ?? [], item]).concat(boundaries.get(items.length) ?? []);
+}

package/src/context-status.mjs

@@ -0,0 +1,34 @@
+/** Independent presentation of a host's content-free, committed context quote. */
+export function createContextStatus(React) {
+  const h = React.createElement;
+  return function ContextStatus({ value, runId, labels = {} }) {
+    if (!value || value.contract !== 'agentkit.native-context-status/v1' || value.runId !== runId) return null;
+    const l = { context: 'Context', automatic: 'Automatic compaction', disabled: 'Disabled', trigger: 'Trigger',
+      reserved: 'Reserved output', lastRequest: 'Last prepared request (estimated)', unknown: 'Not measured',
+      compacting: 'Compacting context…', interrupted: 'Context compaction interrupted', blocked: 'Context budget blocked',
+      completed: 'Compactions completed', ...labels };
+    const input = Number.isSafeInteger(value.lastRequestInputTokens) && value.lastRequestInputTokens >= 0 ? value.lastRequestInputTokens : null;
+    const window = Number.isSafeInteger(value.contextWindow) && value.contextWindow > 0 ? value.contextWindow : null;
+    const count = Number.isSafeInteger(value.compactions) && value.compactions >= 0 ? value.compactions : 0;
+    const reserved = Number.isSafeInteger(value.reservedOutputTokens) && value.reservedOutputTokens >= 0 ? `${value.reservedOutputTokens.toLocaleString()} tokens` : l.unknown;
+    const threshold = Number.isFinite(value.thresholdRatio) ? `${Math.round(value.thresholdRatio * 100)}%` : l.unknown;
+    const summary = value.state === 'compacting' ? l.compacting : value.state === 'interrupted' ? l.interrupted
+      : value.state === 'blocked' ? l.blocked : `${l.context} · ${input === null ? l.unknown : input.toLocaleString() + (window ? ' / ' + window.toLocaleString() : '')}${count ? ' · ' + l.completed + ' ' + count : ''}`;
+    return h('details', { className: 'harness-context-status', 'data-testid': 'context-status', 'data-state': value.state },
+      h('summary', { role: value.state === 'compacting' ? 'status' : undefined }, summary),
+      h('dl', null,
+        h('dt', null, l.lastRequest), h('dd', null, input === null ? l.unknown : `${input.toLocaleString()} tokens`),
+        h('dt', null, l.reserved), h('dd', null, reserved),
+        h('dt', null, l.automatic), h('dd', null, value.enabled ? `${l.trigger} ${threshold}` : l.disabled),
+        h('dt', null, l.completed), h('dd', null, count)));
+  };
+}
+export const contextStatusStyles = `
+.harness-context-status { color: var(--harness-fg-muted, #888); font-size: 12px; margin: 12px 0; }
+.harness-context-status > summary { cursor: pointer; }
+.harness-context-status[data-state="compacting"] > summary { animation: harness-context-pulse 1.5s ease-in-out infinite; }
+.harness-context-status dl { display: grid; grid-template-columns: auto 1fr; gap: 4px 16px; margin: 8px 0; }
+.harness-context-status dd { margin: 0; }
+@keyframes harness-context-pulse { 50% { opacity: .5; } }
+@media (prefers-reduced-motion: reduce) { .harness-context-status > summary { animation: none !important; } }
+`;

package/src/diff.mjs

@@ -0,0 +1,240 @@
+// @kingsoftcloud/agentkit-harness-ui — unified-diff parsing
+//
+// Pure patch parsing for the file-edit renderer. Extracts actual line numbers
+// from `@@ -oldStart,oldCount +newStart,newCount @@` hunk headers (never
+// synthesized), counts additions/deletions, and produces bounded unified and
+// split representations with real gutter line numbers. The full patch is never
+// rendered verbatim; a bounded preview is returned and the host retrieves the
+// full diff via a callback when the user asks for it.
+//
+// No file is read and no write is inferred from input. This module only parses
+// a patch string the host already supplied in a `tool.result` display payload.
+
+const HUNK_HEADER_RE = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+const FILE_HEADER_RE = /^(?:diff --git a\/(\S+) b\/\S+|(?:---|\+\+\+) (?:a\/|b\/)?(.+))$/;
+
+/** Maximum preview lines rendered inline before the host retrieves the full diff. */
+export const MAX_DIFF_PREVIEW_LINES = 200;
+/** Maximum hunk line number rendered; beyond this the gutter is blanked for safety. */
+export const MAX_DIFF_LINE_NUMBER = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Count added/removed lines in a patch. Hunk headers, file headers, and the
+ * `\ No newline` marker are excluded. Returns null when the patch is empty.
+ * @param {string} patch
+ * @returns {{added: number, removed: number}|null}
+ */
+export function countChangeStat(patch) {
+  const text = String(patch || "");
+  if (!text) return null;
+  let added = 0;
+  let removed = 0;
+  let inHunk = false;
+  for (const raw of text.split("\n")) {
+    if (!raw) continue;
+    if (raw.startsWith("@@")) { inHunk = true; continue; }
+    if (raw.startsWith("diff --git ")) { inHunk = false; continue; }
+    if (raw.startsWith("index ")) continue;
+    if (!inHunk && (raw.startsWith("--- ") || raw.startsWith("+++ "))) continue;
+    if (raw.startsWith("\\ ")) continue;
+    if (raw.startsWith("+")) added += 1;
+    else if (raw.startsWith("-")) removed += 1;
+  }
+  if (!added && !removed) return null;
+  return { added, removed };
+}
+
+/**
+ * Resolve the file path from a patch's `--- a/path` / `+++ b/path` or
+ * `diff --git a/x b/x` headers. Returns "" when no header is present.
+ * @param {string} patch
+ * @returns {string}
+ */
+export function patchFilePath(patch) {
+  const text = String(patch || "");
+  if (!text) return "";
+  for (const raw of text.split("\n")) {
+    if (raw.startsWith("diff --git a/") && raw.includes(" b/")) {
+      const rest = raw.slice("diff --git ".length);
+      const aEnd = rest.indexOf(" b/");
+      if (aEnd > 0) return rest.slice(2, aEnd);
+      continue;
+    }
+    if (raw.startsWith("--- ") || raw.startsWith("+++ ")) {
+      let p = raw.slice(4).trim();
+      const tab = p.indexOf("\t");
+      if (tab >= 0) p = p.slice(0, tab).trim();
+      if (!p || p === "/dev/null") continue;
+      if (p.startsWith("a/") || p.startsWith("b/")) p = p.slice(2);
+      return p;
+    }
+  }
+  return "";
+}
+
+/**
+ * Infer the edit operation kind from an explicit `operationKind`, an
+ * `actionLabel`, or the patch shape (`--- /dev/null` ⇒ write, `+++ /dev/null`
+ * ⇒ delete). Falls back to "edit".
+ * @param {string} [operationKind]
+ * @param {string} [actionLabel]
+ * @param {string} [patch]
+ * @returns {"write"|"delete"|"edit"}
+ */
+export function inferOperationKind(operationKind, actionLabel, patch) {
+  const op = String(operationKind || "").toLowerCase();
+  if (op === "write" || op === "create") return "write";
+  if (op === "delete" || op === "remove") return "delete";
+  const label = String(actionLabel || "").toLowerCase();
+  if (label === "write" || label === "create") return "write";
+  if (label === "delete" || label === "remove") return "delete";
+  const text = String(patch || "");
+  if (text) {
+    const hasNewNull = text.split("\n").some(l => l.startsWith("+++ /dev/null"));
+    const hasOldNull = text.split("\n").some(l => l.startsWith("--- /dev/null"));
+    if (hasNewNull && !hasOldNull) return "delete";
+    if (hasOldNull && !hasNewNull) return "write";
+  }
+  return "edit";
+}
+
+/**
+ * Parse a unified diff into bounded hunks carrying REAL line numbers derived
+ * from the hunk headers (old side starts at oldStart, new side at newStart;
+ * context/removed advance the old gutter, context/added advance the new
+ * gutter). Returns both a unified interleaved list and a split pair so the
+ * view can render either; the host chooses via options and CSS switches
+ * responsively.
+ *
+ * @param {string} patch
+ * @param {{maxLines?: number, maxLineChars?: number}} [opts]
+ * @returns {{path: string, added: number, removed: number, truncated: boolean,
+ *   unified: DiffLine[], split: {old: DiffLine[], new: DiffLine[]}}|null}
+ *
+ * @typedef {{marker: " " | "+" | "-", text: string, oldLine: number|null, newLine: number|null}} DiffLine
+ */
+export function parseDiffHunks(patch, opts = {}) {
+  const text = String(patch || "");
+  if (!text) return null;
+  const maxLines = opts.maxLines && opts.maxLines > 0 ? Math.floor(opts.maxLines) : MAX_DIFF_PREVIEW_LINES;
+  const maxChars = opts.maxLineChars && opts.maxLineChars > 0 ? Math.floor(opts.maxLineChars) : 200;
+  const path = patchFilePath(text);
+  const lines = text.split("\n");
+  const unified = [];
+  const splitOld = [];
+  const splitNew = [];
+  let added = 0;
+  let removed = 0;
+  let truncated = false;
+  let oldLine = null;
+  let newLine = null;
+  let inHunk = false;
+
+  for (const raw of lines) {
+    if (truncated) break;
+    if (raw.startsWith("diff --git ") || raw.startsWith("index ")) continue;
+    if (!inHunk && (raw.startsWith("--- ") || raw.startsWith("+++ "))) continue;
+    const header = HUNK_HEADER_RE.exec(raw);
+    if (header) {
+      inHunk = true;
+      oldLine = parseLineNumber(header[1], header[2]);
+      newLine = parseLineNumber(header[3], header[4]);
+      continue;
+    }
+    // A bare `@@` (no line ranges) is still a hunk header; the reference
+    // accepts `line === "@@"` as a hunk start. Line numbers stay null.
+    if (raw === "@@") { inHunk = true; oldLine = null; newLine = null; continue; }
+    if (!inHunk || !raw || ![" ", "+", "-", "\\"].includes(raw[0])) continue;
+    if (raw.startsWith("\\ ")) continue; // ""
+    const marker = raw.startsWith("+") ? "+" : raw.startsWith("-") ? "-" : " ";
+    const body = raw.length ? raw.slice(1) : "";
+    const lineText = truncateLine(body, maxChars);
+    const entry = { marker, text: lineText, oldLine: null, newLine: null };
+    if (marker === "+") {
+      added += 1;
+      entry.newLine = newLine;
+      newLine = incLine(newLine);
+    } else if (marker === "-") {
+      removed += 1;
+      entry.oldLine = oldLine;
+      oldLine = incLine(oldLine);
+    } else {
+      entry.oldLine = oldLine;
+      entry.newLine = newLine;
+      oldLine = incLine(oldLine);
+      newLine = incLine(newLine);
+    }
+    pushBounded(unified, entry, maxLines, () => { truncated = true; });
+    pushSplit(splitOld, splitNew, entry, maxLines, () => { truncated = true; });
+  }
+  if (!unified.length) return null;
+  return { path, added, removed, truncated, unified, split: { old: splitOld, new: splitNew } };
+}
+
+function parseLineNumber(start, count) {
+  const s = Number.parseInt(start, 10);
+  if (!Number.isSafeInteger(s) || s < 0) return null;
+  // Real editors number from the start line; a 0-count hunk is a pure insertion
+  // whose first body line is `start` (or `start+1` when start is 0). Match the
+  // unified-diff convention: line numbers begin at `start`, clamped to >= 1.
+  return Math.max(1, s);
+}
+
+function incLine(line) {
+  if (line == null) return null;
+  const next = line + 1;
+  return next > MAX_DIFF_LINE_NUMBER ? null : next;
+}
+
+function truncateLine(text, maxChars) {
+  if (!text) return "";
+  if (text.length <= maxChars) return text;
+  return text.slice(0, Math.max(0, maxChars - 1)) + "…";
+}
+
+function pushBounded(list, entry, maxLines, markTruncated) {
+  if (list.length >= maxLines) { markTruncated(); return; }
+  list.push(entry);
+}
+
+function pushSplit(oldList, newList, entry, maxLines, markTruncated) {
+  // Split view pairs old and new columns; a context line occupies both, an
+  // added line only the new column, a removed line only the old column.
+  if (entry.marker === "+") {
+    if (newList.length >= maxLines) { markTruncated(); return; }
+    newList.push(entry);
+    if (oldList.length < maxLines) oldList.push(blankSplit(entry.oldLine));
+  } else if (entry.marker === "-") {
+    if (oldList.length >= maxLines) { markTruncated(); return; }
+    oldList.push(entry);
+    if (newList.length < maxLines) newList.push(blankSplit(entry.newLine));
+  } else {
+    if (oldList.length >= maxLines || newList.length >= maxLines) { markTruncated(); return; }
+    oldList.push(entry);
+    newList.push(entry);
+  }
+}
+
+function blankSplit(line) {
+  return { marker: " ", text: "", oldLine: line, newLine: line };
+}
+
+/**
+ * Bounded backward-compat preview: a flat list of `{marker, text}` lines, the
+ * shape the original `fileDiffPreview` returned. Kept so existing hosts and
+ * tests that consume the simple preview still work.
+ * @param {string} patch
+ * @param {{maxLines?: number}} [opts]
+ * @returns {{path: string, lines: {marker: string, text: string}[], truncated: boolean}|null}
+ */
+export function diffPreviewLines(patch, opts = {}) {
+  const parsed = parseDiffHunks(patch, opts);
+  if (!parsed) return null;
+  return {
+    path: parsed.path,
+    lines: parsed.unified.map(l => ({ marker: l.marker, text: l.text })),
+    truncated: parsed.truncated,
+  };
+}
+
+export { patchFilePath as _patchFilePath };

package/src/explore-tool-call.mjs

@@ -0,0 +1,139 @@
+// Adapted from ZCode, Apache-2.0; see NOTICE and LICENSE.
+// Revision 3c5b227649371507ddc4eb46ac5133afe6db1cab
+// packages/ui/src/lib/exploreToolCall.ts
+// Reference SHA-256: 24420d687f0e252dc5fb373f8c6238464ae27731dc7ec9282f3bb6da05f0fe3a
+// Only TypeScript erasure and the host-independent identity adapter change.
+// Presentation classification never grants permissions or replay authority.
+import { toolIdentity } from './tool-identity.mjs';
+const families = { execute: 'shell', file: 'file-read', list: 'search', search: 'search',
+    'web-search': 'explore', 'web-fetch': 'web-fetch', edit: 'file-write', write: 'file-write', delete: 'file-write' };
+const resolveToolCallIdentity = ({ kind }) => ({ family: families[toolIdentity(kind).family] ?? 'generic' });
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function splitCommandSegments(command) {
+    return command
+        .split(/&&|\|\||;/g)
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+}
+function unwrapShellCommand(command) {
+    const trimmed = command.trim();
+    const stripWrappingQuotes = (value) => {
+        const normalized = value.trim();
+        if ((normalized.startsWith('"') && normalized.endsWith('"')) ||
+            (normalized.startsWith("'") && normalized.endsWith("'"))) {
+            return normalized.slice(1, -1).trim();
+        }
+        return normalized;
+    };
+    const shellCommandMatch = trimmed.match(/^(?:\/bin\/)?(?:zsh|bash|sh)\s+-lc\s+([\s\S]+)$/i);
+    if (shellCommandMatch?.[1]) {
+        return stripWrappingQuotes(shellCommandMatch[1]);
+    }
+    const powershellCommandMatch = trimmed.match(/^(?:powershell(?:\.exe)?|pwsh(?:\.exe)?)\b[\s\S]*?\s-(?:command|c)\s+([\s\S]+)$/i);
+    if (powershellCommandMatch?.[1]) {
+        return stripWrappingQuotes(powershellCommandMatch[1]);
+    }
+    return trimmed;
+}
+function normalizeCommandCandidate(candidate) {
+    const unwrapped = unwrapShellCommand(candidate);
+    if (unwrapped.length === 0) {
+        return [];
+    }
+    return splitCommandSegments(unwrapped);
+}
+function extractToolCommands(input) {
+    const commandCandidates = [];
+    const collectFromValue = (value) => {
+        if (typeof value === "string") {
+            const command = value.trim();
+            if (command.length > 0) {
+                commandCandidates.push(command);
+            }
+            return;
+        }
+        if (!Array.isArray(value)) {
+            return;
+        }
+        if (value.every((item) => typeof item === "string")) {
+            const commandParts = value;
+            const shellCommandIndex = commandParts.findIndex((part) => part === "-lc");
+            if (shellCommandIndex >= 0 && typeof commandParts[shellCommandIndex + 1] === "string") {
+                const shellCommand = commandParts[shellCommandIndex + 1].trim();
+                if (shellCommand.length > 0) {
+                    commandCandidates.push(shellCommand);
+                    return;
+                }
+            }
+            const joinedCommand = commandParts.join(" ").trim();
+            if (joinedCommand.length > 0) {
+                commandCandidates.push(joinedCommand);
+            }
+            return;
+        }
+        for (const item of value) {
+            if (!isPlainRecord(item)) {
+                continue;
+            }
+            const parsedCommand = item.cmd;
+            if (typeof parsedCommand === "string" && parsedCommand.trim().length > 0) {
+                commandCandidates.push(parsedCommand.trim());
+            }
+        }
+    };
+    collectFromValue(input);
+    if (!isPlainRecord(input)) {
+        return Array.from(new Set(commandCandidates.flatMap((candidate) => normalizeCommandCandidate(candidate))));
+    }
+    for (const key of ["command", "cmd", "script", "parsed_cmd"]) {
+        collectFromValue(input[key]);
+    }
+    return Array.from(new Set(commandCandidates.flatMap((candidate) => normalizeCommandCandidate(candidate))));
+}
+const EXECUTE_READ_COMMAND_RE = /\b(rg|grep|find|ls|cat|head|tail|wc|stat|pwd|which|readlink|tree|sed\s+-n|get-childitem|gci|dir|get-content|gc|type|select-string|sls|get-location|test-path|resolve-path)\b|^git\s+(status|log|show|diff)\b/i;
+const EXECUTE_WRITE_COMMAND_RE = /\b(sed\s+-i|perl\s+-pi|tee|mv|cp|rm|mkdir|rmdir|touch|truncate|chmod|chown|remove-item|del|erase|set-content|add-content|clear-content|out-file|new-item|move-item|copy-item|rename-item|set-item)\b|^git\s+(add|commit|rm|mv|checkout|switch|restore|reset|clean|revert|cherry-pick|merge|rebase)\b/i;
+const SHELL_REDIRECT_WRITE_RE = /(^|[^\d<])>>?\s*\S|&>\s*\S/i;
+const SHELL_LOOP_RE = /\b(for|while)\b/i;
+export function isShellToolCallAwaitingCommand({ kind, input }) {
+    const identity = resolveToolCallIdentity({ kind, input });
+    return identity.family === "shell" && extractToolCommands(input).length === 0;
+}
+export function isExploreToolCall({ kind, input }) {
+    const identity = resolveToolCallIdentity({ kind, input });
+    if (identity.family === "file-write") {
+        return false;
+    }
+    if (identity.family === "file-read" ||
+        identity.family === "search" ||
+        identity.family === "web-fetch" ||
+        identity.family === "explore") {
+        return true;
+    }
+    if (identity.family !== "shell") {
+        return false;
+    }
+    const commands = extractToolCommands(input);
+    if (commands.length === 0) {
+        return false;
+    }
+    if (commands.some((command) => EXECUTE_WRITE_COMMAND_RE.test(command))) {
+        return false;
+    }
+    if (commands.some((command) => SHELL_REDIRECT_WRITE_RE.test(command))) {
+        return false;
+    }
+    if (commands.some((command) => EXECUTE_READ_COMMAND_RE.test(command))) {
+        return true;
+    }
+    // 有些只读探查会包在 for/while 循环里，例如批量查看 README 或递归扫目录，
+    // 这种命令本身不一定以 rg/ls 开头，但仍然属于 explore。
+    return commands.some((command) => SHELL_LOOP_RE.test(command) && EXECUTE_READ_COMMAND_RE.test(command));
+}
+export function isExecuteToolCall({ kind, input }) {
+    const identity = resolveToolCallIdentity({ kind, input });
+    return (identity.family === "shell" &&
+        !isShellToolCallAwaitingCommand({ kind, input }) &&
+        !isExploreToolCall({ kind, input }));
+}

package/src/file-preview.mjs

@@ -0,0 +1,50 @@
+const byteLength = text => new TextEncoder().encode(text).length;
+function validPage(page) {
+  if (page?.contract !== 'agentkit.native-child-file/v1' || page.workspace !== 'child' || page.readOnly !== true
+    || typeof page.path !== 'string' || !page.path || page.path.length > 1024 || /[\0\\]/.test(page.path)
+    || !page.path.split('/').every(part => part && part !== '.' && part !== '..')
+    || !Number.isSafeInteger(page.offset) || page.offset < 0 || !Number.isSafeInteger(page.totalBytes)
+    || page.totalBytes < page.offset || typeof page.text !== 'string' || page.text.length > 65536 || byteLength(page.text) > 65536
+    || !/^sha256:[a-f0-9]{64}$/.test(page.pageDigest ?? '')) return false;
+  const end = page.offset + byteLength(page.text);
+  return end <= page.totalBytes && (page.nextOffset === null ? end === page.totalBytes
+    : Number.isSafeInteger(page.nextOffset) && page.nextOffset === end && end > page.offset && end < page.totalBytes);
+}
+
+/** A current read-only observation, separate from immutable tool results.
+ * The Host owns scope, loading and cursors; this view renders one real page.
+ */
+export function createFilePreviewComponents(React) {
+  const h = React.createElement;
+  function FilePreviewPane({ page, loading = false, error = '', onNext, onPrevious, onCopy, labels = {}, theme = 'system' }) {
+    const visible = validPage(page) && !loading && !error;
+    const muted = theme === 'light' ? '#64666b' : '#96979b';
+    const button = { type: 'button', style: { font: 'inherit', cursor: 'pointer' } };
+    return h('section', { 'data-testid': 'harness-file-preview', 'aria-busy': loading,
+      style: { display: 'flex', flexDirection: 'column', height: '100%', minHeight: 0, boxSizing: 'border-box', padding: 16,
+        fontSize: 13, color: theme === 'system' ? 'CanvasText' : theme === 'light' ? '#222' : '#e5e5e5',
+        background: theme === 'system' ? 'Canvas' : theme === 'light' ? '#fff' : '#141414' } },
+    h('header', { style: { display: 'flex', alignItems: 'center', gap: 8 } },
+      h('strong', { title: visible ? page.path : undefined,
+        style: { flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } },
+      visible ? page.path : labels.unavailable || 'File preview'),
+      onCopy ? h('button', { ...button, 'data-testid': 'file-preview-copy', disabled: !visible,
+        onClick: () => { if (visible) onCopy(page.text); } }, labels.copy || 'Copy page') : null),
+    h('p', { style: { color: muted } }, labels.readOnly || 'Read-only workspace observation'),
+    loading ? h('p', { role: 'status' }, labels.loading || 'Reading file…') : error
+      ? h('p', { role: 'alert' }, error) : !visible ? h('p', { role: 'alert' }, labels.unavailable || 'File observation unavailable') : null,
+    visible ? h(React.Fragment, null,
+      h('p', { 'data-testid': 'file-preview-range', style: { color: muted } },
+        `${page.offset}–${page.offset + byteLength(page.text)} / ${page.totalBytes} ${labels.bytes || 'bytes'}`),
+      h('div', { style: { flex: 1, minHeight: 0, overflow: 'auto' } },
+        h('pre', { 'data-testid': 'file-preview-text', style: { margin: 0, whiteSpace: 'pre-wrap', overflowWrap: 'anywhere',
+          fontFamily: 'ui-monospace, SFMono-Regular, Consolas, monospace', lineHeight: 1.6 } }, page.text)),
+      h('p', { style: { color: muted } }, labels.observation || 'Current file data, not a tool receipt or task verification.')) : null,
+    h('nav', { style: { display: 'flex', gap: 8, marginTop: 12 } },
+      onPrevious ? h('button', { ...button, 'data-testid': 'file-preview-previous', disabled: loading,
+        onClick: () => { if (!loading) onPrevious(); } }, labels.previous || 'Previous page') : null,
+      onNext ? h('button', { ...button, 'data-testid': 'file-preview-next', disabled: !visible || page.nextOffset === null,
+        onClick: () => { if (visible && page.nextOffset !== null) onNext(page.nextOffset); } }, labels.next || 'Next page') : null));
+  }
+  return { FilePreviewPane };
+}