@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/chat/Composer.tsx

@@ -0,0 +1,239 @@
+// 输入框与 Operator 共用原件上传。上传完成只保留附件引用，用户发送时才交给 Agent。
+// 没有原件上传适配器的宿主继续使用原有文档文本解析。
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import {
+  ACCEPT_ATTR, ACCEPTED_LABEL, MAX_MESSAGE_CHARS, PASTE_NAME, charCount, composeMessage, isLongText, readFileText, type TextBlock,
+} from "../core/blocks";
+import { Icon } from "../ui/icons";
+import { clientId } from "../core/id";
+import { TextBlockCard } from "../ui/TextBlock";
+import { fmtCount } from "../ui/format";
+import { useComposerAutosize } from "../ui/useComposerAutosize";
+import { documentMarker, FILE_UPLOAD_ACCEPT, type UploadDocument } from "../core/documentUpload";
+import { UploadProgress } from "../ui/UploadProgress";
+
+import { clearComposerDraft, readComposerDraft, updateComposerDraft, useComposerDraft, type PendingFile } from "./draft";
+
+/** 输入框的可配置项（来自 CliChat 的 config.composer）。 */
+export interface ComposerOptions {
+  placeholderRunning: string;
+  hints: boolean;
+  charCount: boolean;
+  fileUpload: boolean;
+  fileButtonText: string;
+  queue: boolean;
+}
+
+export function Composer({ draft, placeholder, disabled, disabledHint, running, onSend, onStop, taskControl, options, toolbar, queued, context, uploadDocument }: {
+  /** 草稿按这个键存在 localStorage（一般是对话 id）。 */
+  draft: string;
+  placeholder: string;
+  disabled: boolean;
+  disabledHint?: string;
+  running: boolean;
+  onSend: (text: string) => Promise<void>;
+  onStop?: () => Promise<void> | void;
+  taskControl?: { paused: boolean; onToggle: () => Promise<void> };
+  options: ComposerOptions;
+  toolbar?: ReactNode;
+  queued?: ReactNode;
+  context?: ReactNode;
+  uploadDocument?: UploadDocument;
+}) {
+  const state = useComposerDraft(draft);
+  const { text: val, blocks, pending, error, sending } = state;
+  const setVal = (text: string) => updateComposerDraft(draft, s => ({ ...s, text }));
+  const setBlocks = (fn: (blocks: typeof state.blocks) => typeof state.blocks) => updateComposerDraft(draft, s => ({ ...s, blocks: fn(s.blocks) }));
+  const setPending = (fn: (pending: PendingFile[]) => PendingFile[]) => updateComposerDraft(draft, s => ({ ...s, pending: fn(s.pending) }));
+  const setError = (error: string | null) => updateComposerDraft(draft, s => ({ ...s, error }));
+  const setSending = (sending: boolean) => updateComposerDraft(draft, s => ({ ...s, sending }));
+  const [stopping, setStopping] = useState(false);
+  const [controlling, setControlling] = useState(false);
+  const [dragging, setDragging] = useState(false);
+  const dragDepth = useRef(0);
+  const stopLock = useRef(false);
+  const controlLock = useRef(false);
+  const composing = useRef(false);
+  const fileRef = useRef<HTMLInputElement>(null);
+  const ref = useRef<HTMLTextAreaElement>(null);
+  const uploads = useRef(new Map<string, AbortController>());
+  const selectedFiles = useRef(new Map<string, File>());
+
+  useEffect(() => () => {
+    const owned = new Set(uploads.current.keys());
+    for (const controller of uploads.current.values()) controller.abort();
+    uploads.current.clear(); selectedFiles.current.clear();
+    if (readComposerDraft(draft).pending.some(file => owned.has(file.key) && file.status === "reading")) {
+      updateComposerDraft(draft, current => ({ ...current, pending: current.pending.map(file => owned.has(file.key) && file.status === "reading"
+        ? { ...file, status: "error", error: file.phase ? "上传已中断，请重新选择文件。" : "解析已中断，请重新选择文件。" } : file) }));
+    }
+  }, [draft]);
+
+  useEffect(() => { if (!running) { stopLock.current = false; setStopping(false); } }, [running]);
+  useComposerAutosize(ref, val);
+
+  const nextKey = () => `blk-${clientId()}`;
+  const addBlock = (block: TextBlock) => setBlocks((prev) => [...prev, { ...block, key: nextKey() }]);
+
+  const addFiles = (files: File[]) => {
+    if (disabled || sending || !options.fileUpload) return;
+    for (const file of files) {
+      const key = nextKey();
+      const original = !!uploadDocument;
+      const controller = new AbortController();
+      uploads.current.set(key, controller);
+      selectedFiles.current.set(key, file);
+      setPending((prev) => [...prev, { key, name: file.name || "文件", status: "reading", ...(original ? { phase: "queued" as const, bytes: 0, size: file.size } : {}) }]);
+      const content = original ? Promise.resolve().then(() => uploadDocument!(file, { draftId: clientId(), signal: controller.signal,
+        onPhase: phase => { if (!controller.signal.aborted) setPending(prev => prev.map(p => p.key === key ? { ...p, phase } : p)); },
+        onBytes: bytes => { if (!controller.signal.aborted) setPending(prev => prev.map(p => p.key === key ? { ...p, bytes } : p)); },
+      })).then(documentMarker) : readFileText(file);
+      content
+        .then((text) => {
+          if (controller.signal.aborted) return;
+          if (!text.trim()) throw new Error(`「${file.name}」里没有可读的文字`);
+          updateComposerDraft(draft, s => s.pending.some(p => p.key === key && p.status === "reading")
+            ? { ...s, pending: s.pending.filter(p => p.key !== key), blocks: [...s.blocks, { key, name: file.name, text, kind: "file" }] }
+            : s);
+          selectedFiles.current.delete(key);
+        })
+        .catch((err: unknown) => {
+          if (controller.signal.aborted) return;
+          setPending((prev) => prev.map((p) => (p.key === key ? { ...p, status: "error", error: err instanceof Error ? err.message : String(err) } : p)));
+        }).finally(() => uploads.current.delete(key));
+    }
+  };
+
+  const message = composeMessage(val, blocks);
+  const total = charCount(message);
+  const tooLong = total > MAX_MESSAGE_CHARS;
+  const reading = pending.some((p) => p.status === "reading");
+  // 运行中不允许排队时，等这一轮结束再发。
+  const canSend = !!message.trim() && !pending.length && !reading && !tooLong && !sending && !stopping && (!running || options.queue);
+  const showStop = running && !!onStop && !sending && (stopping || disabled || !options.queue || !message.trim());
+
+  const submit = async () => {
+    if (!canSend || disabled || stopLock.current || readComposerDraft(draft).sending) return;
+    const submitted = JSON.stringify([val, blocks]);
+    setSending(true);
+    setError(null);
+    const key = draft;
+    try {
+      await onSend(message);
+      // 新建对话时发送完成前组件就换成了新对话的输入框（key 变了），这里直接清掉发出时那份草稿。
+      const current = readComposerDraft(key);
+      if (JSON.stringify([current.text, current.blocks]) === submitted) clearComposerDraft(key);
+    } catch (err) {
+      // 发送失败：内容留在输入框里，可以直接再发。
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setSending(false);
+    }
+  };
+
+  const isFileDrag = (e: React.DragEvent) => Array.from(e.dataTransfer?.types ?? []).includes("Files");
+  const hasFileDrag = (e: React.DragEvent) => options.fileUpload && isFileDrag(e);
+  const stopButton = running && onStop && (
+    <button type="button" className="send stop" onClick={async () => {
+      if (stopLock.current) return;
+      stopLock.current = true; setStopping(true); setError(null);
+      try { await onStop(); } catch (error) { stopLock.current = false; setStopping(false); setError(error instanceof Error ? error.message : "停止失败，请重试"); }
+    }}
+      disabled={stopping} aria-busy={stopping} aria-label={stopping ? "正在停止" : "停止当前轮次"} title={stopping ? "正在停止…" : "停止当前轮次"}>{stopping ? <span className="spinner" /> : Icon.stop()}</button>
+  );
+
+  return (
+    <div className="composer">
+      <div className="composer-inner">
+        {(error || tooLong) && (
+          <div className="cli-comp-err" role="alert">⚠ {tooLong ? `内容共 ${fmtCount(total)} 字，超过单条消息上限 ${fmtCount(MAX_MESSAGE_CHARS)} 字，请删减或分几条发送` : error}</div>
+        )}
+        {queued}
+        <div
+          className={`comp-box${dragging ? " dropping" : ""}`}
+          onDragEnter={(e) => { if (!disabled && hasFileDrag(e)) { e.preventDefault(); dragDepth.current++; setDragging(true); } }}
+          onDragOver={(e) => { if (isFileDrag(e)) e.preventDefault(); }}
+          onDragLeave={() => { if (dragDepth.current > 0 && --dragDepth.current === 0) setDragging(false); }}
+          onDrop={(e) => {
+            if (!isFileDrag(e)) return;
+            // 文件拖进来总要拦下：不拦的话浏览器会直接打开这个文件、离开当前页面。
+            e.preventDefault();
+            dragDepth.current = 0;
+            setDragging(false);
+            if (disabled) return;
+            if (!options.fileUpload) { setError("这里只能发送文字"); return; }
+            addFiles(Array.from(e.dataTransfer.files));
+          }}
+        >
+          {context}
+          {(blocks.length > 0 || pending.length > 0) && (
+            <div className="cli-blocks">
+              {blocks.map((b) => <TextBlockCard key={b.key} block={b} onRemove={() => setBlocks((prev) => prev.filter((x) => x.key !== b.key))} />)}
+              {pending.map((p) => p.phase ? <UploadProgress key={p.key} name={p.name} status={p.status === "error" ? "error" : p.phase}
+                bytes={p.bytes} total={p.size} error={p.error}
+                onCancel={() => { uploads.current.get(p.key)?.abort(); selectedFiles.current.delete(p.key); setPending(prev => prev.filter(x => x.key !== p.key)); }}
+                onRemove={() => { selectedFiles.current.delete(p.key); setPending(prev => prev.filter(x => x.key !== p.key)); }}
+                onRetry={selectedFiles.current.has(p.key) ? () => { if (disabled || sending) return; const file = selectedFiles.current.get(p.key)!; selectedFiles.current.delete(p.key); setPending(prev => prev.filter(x => x.key !== p.key)); addFiles([file]); } : undefined} /> : (
+                <div key={p.key} className={`attach-chip file ${p.status}`} title={p.error || p.name}>
+                  <span className="attach-file">{Icon.doc()} {p.name}</span>
+                  <span className={`attach-badge ${p.status === "error" ? "err" : ""}`}>{p.status === "reading" ? p.progress ?? "解析中…" : p.error}</span>
+                  <button type="button" className="attach-x" title={p.status === "reading" ? "取消添加" : "移除"} aria-label={`移除 ${p.name}`} onClick={() => { uploads.current.get(p.key)?.abort(); setPending((prev) => prev.filter((x) => x.key !== p.key)); }}>×</button>
+                </div>
+              ))}
+            </div>
+          )}
+          <div className="comp-area">
+            <textarea
+              ref={ref} rows={2} value={val} disabled={disabled || sending} aria-label="消息内容"
+              placeholder={disabled ? disabledHint ?? "暂时不能发送" : taskControl?.paused ? "任务已暂停，可补充消息，继续后依次执行…" : running && options.queue ? options.placeholderRunning : placeholder}
+              onChange={(e) => setVal(e.target.value)}
+              onCompositionStart={() => { composing.current = true; }} onCompositionEnd={() => { composing.current = false; }}
+              onKeyDown={(e) => { if (e.nativeEvent.isComposing || composing.current || e.keyCode === 229) return; if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); void submit(); } }}
+              onPaste={(e) => {
+                const files = Array.from(e.clipboardData?.files ?? []);
+                if (files.length) {
+                  e.preventDefault();
+                  if (!options.fileUpload) { setError("这里只能发送文字"); return; }
+                  if (!uploadDocument && files.some((f) => f.type.startsWith("image/"))) setError(`不支持发送图片，只能发送文字，或上传文档：${ACCEPTED_LABEL}`);
+                  addFiles(uploadDocument ? files : files.filter((f) => !f.type.startsWith("image/")));
+                  return;
+                }
+                // 大段粘贴不放进输入框（几万字的 textarea 会很卡），转成可折叠的文本块。
+                const text = e.clipboardData?.getData("text/plain") ?? "";
+                if (isLongText(text)) {
+                  e.preventDefault();
+                  addBlock({ name: PASTE_NAME, text, kind: "paste" });
+                }
+              }}
+            />
+          </div>
+          <div className="comp-foot">
+            {options.fileUpload && !disabled && <>
+              <input ref={fileRef} type="file" accept={uploadDocument ? FILE_UPLOAD_ACCEPT : ACCEPT_ATTR} multiple hidden onChange={(e) => { addFiles(Array.from(e.target.files ?? [])); e.target.value = ""; }} />
+              <button type="button" className="cli-attach" disabled={sending} aria-label={uploadDocument ? "添加文件" : "添加文档"} title={uploadDocument ? "添加文件（也可拖拽进来）；HTML、Markdown 最大 100 MiB，其他支持类型最大 10 MiB" : `添加文档：${ACCEPTED_LABEL}（也可拖拽进来）`}
+                onClick={() => fileRef.current?.click()}>{Icon.plus()}{options.fileButtonText && <span>{options.fileButtonText}</span>}</button>
+            </>}
+            {toolbar}
+            {options.hints && !disabled && <span className="hint comp-hint-extra">Shift + Enter 换行</span>}
+            <span className="spacer" />
+            {options.charCount && total > 0 && <span className={`hint cli-count ${tooLong ? "over" : ""}`}>{fmtCount(total)} 字</span>}
+            {!options.charCount && tooLong && <span className="hint cli-count over">{fmtCount(total)} 字</span>}
+            <div className="send-group">
+              {taskControl && <button type="button" className="btn btn-line cli-task-control" disabled={controlling}
+                aria-label={taskControl.paused ? "继续任务" : "暂停任务"}
+                title={taskControl.paused ? "重新派发当前子任务，排队消息随后执行" : "暂停当前子任务，继续时重新派发"}
+                onClick={async () => { if (controlLock.current) return; controlLock.current = true; setControlling(true); try { await taskControl.onToggle(); } catch (error) { setError(error instanceof Error ? error.message : "执行控制失败，请重试"); } finally { controlLock.current = false; setControlling(false); } }}>
+                {taskControl.paused ? Icon.play() : Icon.pause()}<span>{controlling ? "处理中…" : taskControl.paused ? "继续" : "暂停"}</span>
+              </button>}
+              {showStop ? stopButton : (!running || options.queue) && <button type="button" className={`send cli-send${running ? " queue" : ""}`} disabled={disabled || !canSend} aria-busy={sending}
+                onClick={() => void submit()} aria-label={sending ? "正在发送" : running ? "排队发送" : "发送消息"}
+                title={sending ? "发送中…" : taskControl?.paused ? "排队发送，继续任务后依次执行" : running ? "排队发送，当前轮次结束后执行" : "发送消息（Enter）"}>
+                {sending ? <span className="spinner" /> : Icon.send()}
+              </button>}
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/chat/GroupChat.tsx

@@ -0,0 +1,113 @@
+import { useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import type { Msg } from "../core/types";
+import { useCliState, useCliStore } from "../core/provider";
+import { boardContextBlock, charCount, MAX_MESSAGE_CHARS, serializeBlock } from "../core/blocks";
+import { MessageView } from "../ui/Transcript";
+import { ReferenceCard } from "../ui/ReferenceCard";
+import { useChatScrollbar } from "../ui/useChatScrollbar";
+import { Icon } from "../ui/icons";
+import { FileLinkContext, FileOpenContext } from "../ui/fileLinks";
+import { Composer, type ComposerOptions } from "./Composer";
+
+export interface GroupChatReference { id: string; label: string; text?: string }
+export interface GroupChatMessage {
+  id: string;
+  role: "user" | "assistant" | "system";
+  content: string;
+  createdAt?: string;
+  actor?: { id: string; name: string };
+  recipientLabel?: string;
+  status?: string;
+  error?: string | null;
+  references?: GroupChatReference[];
+}
+/** 群消息由宿主提供；所有输入始终经过同一个 onSend，不按发言人建立独立发送通道。 */
+export interface GroupChatAdapter {
+  /** 包含业务与用户身份的稳定键，隔离草稿和引用。 */
+  scopeKey: string;
+  messages: GroupChatMessage[];
+  onSend: (text: string) => Promise<void>;
+  userName?: string;
+  placeholder?: string;
+  toolbar?: ReactNode;
+  beforeMessages?: ReactNode;
+  onSource?: (reference: GroupChatReference, message: GroupChatMessage) => void;
+  /** 本地文件沿用共享 Markdown 解析；宿主按实际发言人的授权工作区打开。 */
+  onOpenFile?: (path: string, message: GroupChatMessage) => void;
+  /** 仅消费宿主明确授权给此群的看板引用键（如当前 Job 的成员 job#task）。 */
+  referenceKeys?: string[];
+}
+
+const OPTIONS: ComposerOptions = { placeholderRunning: "继续补充…", hints: false, charCount: false, fileUpload: false, fileButtonText: "文件", queue: true };
+type Quote = { id: string; author: string; text: string };
+
+/** CliChat 的群消息适配；沿用共享消息、输入框和引用组件，不连接单任务转录。 */
+export function GroupChat({ group, theme = "light", className, style, readOnly }: {
+  group: GroupChatAdapter; theme?: "light" | "dark"; className?: string; style?: CSSProperties; readOnly?: boolean;
+}) {
+  const [quote, setQuote] = useState<Quote | null>(null);
+  const [visibleCount, setVisibleCount] = useState(120);
+  const store = useCliStore();
+  const references = useCliState(state => state.refs);
+  const referenceKeys = [...new Set(group.referenceKeys ?? [])];
+  const boardRefs = referenceKeys.flatMap(key => (references[key] ?? []).map(ref => ({ key, ref })));
+  const scroll = useRef<HTMLDivElement>(null);
+  const pinned = useRef(true);
+  useChatScrollbar(scroll, group.scopeKey);
+  useLayoutEffect(() => {
+    if (pinned.current && scroll.current) scroll.current.scrollTop = scroll.current.scrollHeight;
+  }, [group.messages]);
+  const send = async (text: string) => {
+    const submittedQuote = quote;
+    const message = submittedQuote
+      ? `引用 ${submittedQuote.author}：\n${submittedQuote.text.split("\n").map(line => "> " + line).join("\n")}\n\n${text}` : text;
+    const taken = referenceKeys.map(key => ({ key, refs: store.takeRefs(key) }));
+    const refs = taken.flatMap(item => item.refs);
+    const content = refs.length ? `${message}\n\n${serializeBlock(boardContextBlock(refs.map(ref => ref.text)))}` : message;
+    try {
+      if (charCount(content) > MAX_MESSAGE_CHARS) throw new Error("加上引用后消息过长，请精简消息内容后重试。");
+      await group.onSend(content);
+    } catch (error) {
+      for (const item of taken) store.restoreRefs(item.key, item.refs);
+      throw error;
+    }
+    setQuote(current => current === submittedQuote ? null : current);
+    pinned.current = true;
+    if (scroll.current) scroll.current.scrollTop = scroll.current.scrollHeight;
+  };
+  return <div className={`cli-ui cli-chat cli-group-chat ${className ?? ""}`} data-theme={theme} style={style}>
+    <div className="session"><div className="workspace-chat-content" data-chat-layout="centered">
+      <div className="transcript-wrap"><div className="transcript" ref={scroll} role="log" aria-label="群组对话" aria-live="polite" onScroll={() => {
+        const element = scroll.current;
+        if (element) pinned.current = element.scrollHeight - element.scrollTop - element.clientHeight < 48;
+      }}><div className="tw">
+        {group.beforeMessages}
+        {group.messages.length > visibleCount && <div className="load-older"><button type="button" className="btn btn-ghost btn-sm" onClick={() => { pinned.current = false; setVisibleCount(value => value + 80); }}>查看更早的消息</button></div>}
+        {group.messages.slice(-visibleCount).map(message => {
+          const name = message.actor?.name || (message.role === "user" ? group.userName || "你" : "智能体");
+          const ts = message.createdAt ? Date.parse(message.createdAt) : NaN;
+          const msg: Msg = { id: message.id, role: message.role, content: message.content, generation: 0, ...(Number.isFinite(ts) ? { ts } : {}) };
+          return <div key={message.id} data-msg="" data-message-id={message.id} data-actor-id={message.actor?.id}>
+            {message.recipientLabel && <div className="cli-group-meta">{message.recipientLabel}</div>}
+            <FileLinkContext.Provider value={null}><FileOpenContext.Provider value={message.role === "assistant" && message.actor && group.onOpenFile
+              ? path => { group.onOpenFile?.(path, message); return true; } : null}>
+              <MessageView m={msg} initial={false} hideWho={false} view={{ timestamps: true, initialBadge: false, userLabel: name, agentName: name }} handlers={{
+                onQuote: readOnly ? undefined : (value, selected) => setQuote({ id: value.id, author: name, text: selected || value.content }),
+              }} />
+            </FileOpenContext.Provider></FileLinkContext.Provider>
+            {message.status && <div className="cli-group-meta">{message.status}</div>}
+            {message.error && <div className="cli-comp-err" role="alert">{message.error}</div>}
+            {!!message.references?.length && <div className="cli-group-references">{message.references.map(reference => group.onSource
+              ? <button key={reference.id} type="button" className="btn btn-ghost btn-sm" onClick={() => group.onSource?.(reference, message)}>{Icon.doc()}{reference.label}</button>
+              : <ReferenceCard key={reference.id} title={reference.label} text={reference.text || "引用内容未提供"} />)}</div>}
+          </div>;
+        })}
+      </div></div></div>
+      {!readOnly && <Composer draft={`group:${group.scopeKey}`} placeholder={group.placeholder || "发送消息…"} disabled={false} running={false} onSend={send} options={OPTIONS} toolbar={group.toolbar}
+        context={(quote || boardRefs.length > 0) && <div className="cli-refs composer-references">
+          {quote && <ReferenceCard title={quote.author} text={quote.text} removeLabel="取消引用" onRemove={() => setQuote(null)} />}
+          {boardRefs.map(({ key, ref }) => <ReferenceCard key={`${key}:${ref.id}`} title={ref.label} text={ref.text} removeLabel={`不带上 ${ref.label}`} onRemove={() => store.removeRef(key, ref.id)} />)}
+        </div>} />}
+    </div></div>
+  </div>;
+}

package/src/chat/RunControls.tsx

@@ -0,0 +1,196 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { AgentMark, Icon } from "../ui/icons";
+import { Popover } from "../ui/Popover";
+import { modelLabel } from "../ui/format";
+import { acquireConfiguration, useConfigurationBusy } from "./configuration";
+export interface RunOption { value: string; label: string; sub: string; group?: string }
+export interface RunCapabilities { models: RunOption[]; reasoningOptions: RunOption[]; permissionModes: RunOption[]; supportsCustomModels?: boolean }
+export interface RunTask { id: string; agent?: string; model?: string | null; reasoning?: string | null; permission_mode?: string | null; resolved_model?: string | null }
+const withDefault = (options?: RunOption[]) => [{ value: null as string | null, label: "默认", sub: "沿用智能体的默认设置", group: undefined as string | undefined }, ...(options ?? [])];
+const modelOptions = (caps?: RunCapabilities) => withDefault(caps?.models);
+const permissionOptions = (caps?: RunCapabilities) => withDefault(caps?.permissionModes);
+const agentNames = [{ id: "codex", label: "Codex" }, { id: "claude", label: "Claude" }, { id: "grok", label: "Grok" }, { id: "pi", label: "PI" }];
+const permissionIcon = (value: string | null) => value === null ? Icon.clear() : value === "bypassPermissions" ? Icon.bolt() : value === "plan" ? Icon.list() : value === "acceptEdits" ? Icon.edit() : Icon.lock();
+
+export type RunControlProps = {
+  task: RunTask;
+  agents?: {id:string;label:string;disabled?:boolean}[];
+  onSetAgent?: (id:string)=>Promise<void>;
+  caps?: RunCapabilities;
+  defaults?: { model?: string | null; reasoning?: string | null; permission_mode?: string | null };
+  disabled: boolean;
+  showAgent?: boolean;
+  showPermission?: boolean;
+  unavailableReason?: string;
+  onSetModel: (value: string | null) => Promise<void>;
+  onSetReasoning: (value: string | null) => Promise<void>;
+  onSetPermission: (value: string | null) => Promise<void>;
+  onBusyChange?: (busy: boolean) => void;
+};
+
+// Both the pre-start view and composer use the same capability-driven controls.
+// Await persistence before allowing Send so the next turn uses the chosen value.
+export function RunControls({ task, agents, onSetAgent, caps, defaults, disabled, showAgent = true, showPermission = true, unavailableReason, onSetModel, onSetReasoning, onSetPermission, onBusyChange }: RunControlProps) {
+  const [open, setOpen] = useState<"model" | "permission" | null>(null);
+  const [modelPage, setModelPage] = useState<"agents" | "settings" | "models">("agents");
+  const [switching, setSwitching] = useState<{ agent: string; saved: boolean } | null>(null);
+  const [custom, setCustom] = useState("");
+  const busy = useConfigurationBusy(task.id);
+  const currentTask = useRef({ id: task.id, revision: 0 });
+  if (currentTask.current.id !== task.id) currentTask.current = { id: task.id, revision: currentTask.current.revision + 1 };
+  const agentListRef = useRef<HTMLDivElement>(null);
+  const modelEntryRef = useRef<HTMLButtonElement>(null);
+  const modelListRef = useRef<HTMLDivElement>(null);
+  useEffect(() => { setOpen(null); setError(""); setCustom(""); setSwitching(null); setModelPage("agents"); }, [task.id]);
+  const [error, setError] = useState("");
+  const availableAgents = agentNames.flatMap(agent => {
+    const available = agents?.find(item => item.id === agent.id);
+    return available ? [{ ...available, label: agent.label }] : [];
+  });
+  const hasAgentPicker = !!onSetAgent && availableAgents.length > 0;
+  const currentAgent = agentNames.find(agent => agent.id === task.agent)?.label ?? agents?.find(agent => agent.id === task.agent)?.label ?? task.agent ?? "智能体";
+  const models = modelOptions(caps);
+  const permissions = permissionOptions(caps);
+  const effectiveModel = task.model ?? defaults?.model ?? null;
+  const currentModel = effectiveModel ? models.find(option => option.value === effectiveModel)?.label ?? modelLabel(effectiveModel) : "默认模型";
+  const effectivePermission = task.permission_mode ?? defaults?.permission_mode ?? caps?.permissionModes[0]?.value ?? null;
+  const defaultModel = defaults?.model ? models.find(option => option.value === defaults.model)?.label ?? modelLabel(defaults.model) : null;
+  const defaultReasoningOption = caps?.reasoningOptions.find(option => option.value === defaults?.reasoning);
+  const defaultReasoning = defaultReasoningOption?.label ?? defaults?.reasoning ?? null;
+  const currentReasoning = caps?.reasoningOptions.find(option => option.value === task.reasoning);
+  const reasoningLabel = task.reasoning ? currentReasoning?.label ?? task.reasoning : defaultReasoning ? `默认（${defaultReasoning}）` : "默认";
+  const reasoningDescription = task.reasoning ? currentReasoning?.sub ?? "当前任务的推理设置" : defaultReasoningOption?.sub ?? "沿用智能体的默认设置";
+  const defaultPermission = defaults?.permission_mode ?? caps?.permissionModes[0]?.value ?? null;
+  const defaultPermissionLabel = permissions.find(option => option.value === defaultPermission)?.label ?? defaultPermission;
+  const permission = permissions.find((p) => p.value === effectivePermission);
+  const change = async (save: () => Promise<void>, close = true) => {
+    if (disabled) return false;
+    const release = acquireConfiguration(task.id);
+    if (!release) return false;
+    const targetRevision = currentTask.current.revision;
+    setError("");
+    try {
+      onBusyChange?.(true);
+      await save();
+      if (currentTask.current.revision !== targetRevision) return false;
+      if (close) setOpen(null);
+      return true;
+    }
+    catch (e) { if(currentTask.current.revision === targetRevision) setError(e instanceof Error ? e.message : "设置保存失败，请重试。"); return false; }
+    finally { release(); onBusyChange?.(false); }
+  };
+  const locked = disabled || busy || !!switching || !caps;
+  const permissionAvailable = !!caps?.permissionModes.length;
+  useEffect(() => {
+    if ((open === "model" && (!showAgent || !caps)) || (open === "permission" && (!showPermission || !permissionAvailable))) setOpen(null);
+  }, [open, showAgent, showPermission, caps, permissionAvailable]);
+  const pickAgent = async (agent: string) => {
+    if (locked || !onSetAgent) return;
+    setError(""); setCustom("");
+    if (agent === task.agent) { setModelPage("settings"); return; }
+    const targetRevision = currentTask.current.revision;
+    setSwitching({ agent, saved: false });
+    const saved = await change(() => onSetAgent(agent), false);
+    if (currentTask.current.revision === targetRevision) setSwitching(saved ? { agent, saved: true } : null);
+  };
+  // SessionView derives caps from task.agent in the same render. Wait for that
+  // task update as well as the save, so the old agent's models never appear.
+  useEffect(() => {
+    if (switching?.saved && task.agent === switching.agent && caps) {
+      setSwitching(null); setModelPage("settings");
+    }
+  }, [switching, task.agent, caps]);
+  useEffect(() => {
+    if (open !== "model" || switching || busy) return;
+    if (modelPage === "settings") modelEntryRef.current?.focus({ preventScroll: true });
+    else if (modelPage === "models") (modelListRef.current?.querySelector<HTMLButtonElement>('button[aria-pressed="true"]:not(:disabled)') ?? modelListRef.current?.querySelector<HTMLButtonElement>('button:not(:disabled)'))?.focus({ preventScroll: true });
+    else (agentListRef.current?.querySelector<HTMLButtonElement>('button[aria-pressed="true"]:not(:disabled)') ?? agentListRef.current?.querySelector<HTMLButtonElement>('button:not(:disabled)'))?.focus({ preventScroll: true });
+  }, [open, modelPage, switching, busy]);
+  const modelGroups = models.reduce<{ label?: string; options: typeof models }[]>((groups, option) => {
+    const previous = groups.at(-1);
+    if (previous && previous.label === option.group) previous.options.push(option);
+    else groups.push({ label: option.group, options: [option] });
+    return groups;
+  }, []);
+  return <>
+    {showPermission && <div className="comp-control">
+      <button className={`comp-setting permission${effectivePermission === "bypassPermissions" ? " elevated" : ""}`} disabled={locked || !permissionAvailable} aria-label="权限模式" aria-expanded={open === "permission"} aria-haspopup="dialog" title={unavailableReason || (!permissionAvailable ? "当前智能体暂未提供执行模式设置" : disabled ? "本轮结束后可修改权限" : permission?.sub)} onClick={(e) => { e.stopPropagation(); setError(""); setOpen(open === "permission" ? null : "permission"); }}>
+        {Icon.lock()} <span>{permission?.value ? permission.label : "默认权限"}</span>{Icon.chevDown()}
+      </button>
+      {open === "permission" && permissionAvailable && <Popover onClose={() => setOpen(null)} className="composer-popover composer-permission-popover" ariaLabel="权限模式" placement="top" align="start">
+        <div className="composer-menu-heading">权限模式</div>
+        <p className="composer-menu-note">保存后用于下一轮</p>
+        {permissions.map((p) => <button key={p.value ?? "default"} className="pop-item composer-option run-permission-option" disabled={locked} aria-pressed={(task.permission_mode ?? null) === p.value} onClick={() => void change(() => onSetPermission(p.value))}>
+          <span className="composer-option-icon" aria-hidden="true">{permissionIcon(p.value)}</span>
+          <span className="composer-option-copy"><span className="composer-option-title">{p.label}</span><span className="composer-option-sub">{p.value === null && defaultPermissionLabel ? `沿用智能体默认设置：${defaultPermissionLabel}` : p.sub}</span></span>
+          <span className="composer-option-trailing" aria-hidden="true">{(task.permission_mode ?? null) === p.value && Icon.check()}</span>
+        </button>)}
+        {busy && <div className="composer-menu-note" role="status">正在保存…</div>}
+        {error && <div className="control-error" role="alert">{error}</div>}
+      </Popover>}
+    </div>}
+    {showAgent && <div className="comp-control comp-model">
+      <button className="comp-setting" disabled={locked} aria-label="智能体设置" aria-expanded={open === "model"} aria-haspopup="dialog" title={unavailableReason || (!caps ? "当前服务暂未提供智能体设置" : disabled ? "本轮结束后可修改智能体设置" : `当前智能体：${currentAgent}`)} onClick={(e) => { e.stopPropagation(); setError(""); setCustom(""); setModelPage(hasAgentPicker ? "agents" : "settings"); setOpen(open === "model" ? null : "model"); }}>
+        <span className="comp-model-name">{currentAgent}</span>{Icon.chevDown()}
+      </button>
+      {open === "model" && caps && <Popover onClose={() => setOpen(null)} className="composer-popover composer-agent-popover" ariaLabel={modelPage === "agents" ? "选择智能体" : modelPage === "models" ? "选择模型" : "模型与推理设置"} placement="top" align="end">
+        {modelPage === "agents" ? <div ref={agentListRef} className="run-agent-list">
+          <div className="composer-menu-heading">选择智能体</div>
+          {availableAgents.map(agent => <button key={agent.id} className="pop-item composer-option run-agent-option" disabled={locked || agent.disabled} aria-pressed={task.agent === agent.id} onClick={() => void pickAgent(agent.id)}>
+            <span className="composer-option-icon" aria-hidden="true">{AgentMark[agent.id]?.() ?? Icon.spark()}</span>
+            <span className="composer-option-copy"><span className="composer-option-title">{agent.label}</span></span>
+            <span className="composer-option-trailing run-agent-trailing" aria-hidden="true">{task.agent === agent.id && Icon.check()}{Icon.chevRight()}</span>
+          </button>)}
+        </div> : !switching && modelPage === "settings" ? <div className="run-settings">
+          <div className="run-settings-head">
+            {hasAgentPicker && <button className="pop-item run-settings-back" onClick={() => { setModelPage("agents"); setError(""); }}>{Icon.chevRight({ style: { transform: "rotate(180deg)" } })} 智能体</button>}
+            <span className="composer-menu-heading">{currentAgent}</span>
+          </div>
+          <div className="run-settings-field">
+            <div className="run-field-label">模型</div>
+            <button ref={modelEntryRef} className="composer-option run-model-entry" disabled={locked} aria-label="选择模型" onClick={() => { setModelPage("models"); setError(""); }}>
+              <span className="composer-option-icon" aria-hidden="true">{Icon.spark()}</span>
+              <span className="composer-option-copy"><span className="composer-option-title run-model-value">{currentModel}</span><span className="composer-option-sub">{task.model ? models.find(option => option.value === task.model)?.sub ?? "当前使用自定义模型" : "沿用智能体的默认设置"}</span></span>
+              <span className="composer-option-trailing" aria-hidden="true">{Icon.chevRight()}</span>
+            </button>
+          </div>
+          {!!caps?.reasoningOptions.length && <div className="run-reasoning-card">
+            <div className="run-reasoning-head"><span className="run-field-label">推理强度</span><span className="run-reasoning-value">{reasoningLabel}</span></div>
+            <p className="run-reasoning-note">{reasoningDescription}</p>
+            <div className="run-reasoning-options" role="group" aria-label="推理强度档位">
+              {caps.reasoningOptions.map(option => <button key={option.value} className="run-reasoning-option" disabled={locked} aria-pressed={task.reasoning === option.value} title={option.sub} onClick={() => void change(() => onSetReasoning(option.value))}>{option.label}</button>)}
+            </div>
+            <button className="run-reasoning-reset" disabled={locked} aria-label="使用默认推理强度" aria-pressed={task.reasoning == null} onClick={() => void change(() => onSetReasoning(null))}>{Icon.clear()} {defaultReasoning ? `默认（${defaultReasoning}）` : "使用默认设置"}{task.reasoning == null && Icon.check()}</button>
+          </div>}
+          <p className="composer-menu-note run-settings-note">保存后用于下一轮</p>
+        </div> : !switching && modelPage === "models" && <div className="run-settings run-models">
+          <div className="run-settings-head">
+            <button className="pop-item run-models-back" onClick={() => { setModelPage("settings"); setError(""); }}>{Icon.chevRight({ style: { transform: "rotate(180deg)" } })} 返回</button>
+            <span className="composer-menu-heading">选择模型</span>
+          </div>
+          <div ref={modelListRef} className="run-model-list">
+            {modelGroups.map((group, index) => <div className="run-model-group" key={`${group.label ?? "default"}-${index}`}>
+              {group.label && <div className="run-model-group-title">{group.label}</div>}
+              {group.options.map(option => <button key={option.value ?? "default"} className="pop-item composer-option run-model-option" data-model-value={option.value ?? ""} disabled={locked} aria-pressed={(task.model ?? null) === option.value} onClick={() => void change(() => onSetModel(option.value))}>
+                <span className="composer-option-copy"><span className="composer-option-title">{option.value === null && defaultModel ? `默认（${defaultModel}）` : option.label}</span><span className="composer-option-sub">{option.value === null && defaultModel ? `沿用智能体默认设置：${defaultModel}` : option.sub}</span></span>
+                <span className="composer-option-trailing" aria-hidden="true">{(task.model ?? null) === option.value && Icon.check()}</span>
+              </button>)}
+            </div>)}
+            {task.model && !models.some(option => option.value === task.model) && <button className="pop-item composer-option run-model-option" data-model-value={task.model} disabled={locked} aria-pressed onClick={() => void change(() => onSetModel(task.model!))}>
+              <span className="composer-option-copy"><span className="composer-option-title">{modelLabel(task.model)}（当前模型）</span><span className="composer-option-sub">当前任务使用的自定义模型</span></span>
+              <span className="composer-option-trailing" aria-hidden="true">{Icon.check()}</span>
+            </button>}
+          </div>
+          {caps?.supportsCustomModels && <form className="pop-custom-model" onSubmit={(e) => { e.preventDefault(); if (custom.trim()) void change(() => onSetModel(custom.trim())); }}>
+            <label className="composer-menu-heading" htmlFor={`custom-model-${task.id}`}>自定义模型</label>
+            <div className="pop-custom-row"><input id={`custom-model-${task.id}`} value={custom} onChange={(e) => setCustom(e.target.value)} placeholder="模型 ID" disabled={locked} /><button className="btn btn-sm" disabled={locked || !custom.trim()}>使用</button></div>
+          </form>}
+        </div>}
+        {(busy || switching) && <div className="composer-menu-note" role="status">{switching ? "正在切换智能体…" : "正在保存…"}</div>}
+        {error && <div className="control-error" role="alert">{error}</div>}
+      </Popover>}
+    </div>}
+  </>;
+}

package/src/chat/configuration.ts

@@ -0,0 +1,15 @@
+import { useSyncExternalStore } from 'react';
+// A task's setting request outlives its controls when the user changes tasks.
+const pending = new Set<string>();
+const listeners = new Set<() => void>();
+const notify = () => listeners.forEach(listener => listener());
+export const isConfigurationBusy = (taskId:string) => pending.has(taskId);
+export function acquireConfiguration(taskId:string): (()=>void) | null {
+  if (pending.has(taskId)) return null;
+  pending.add(taskId); notify();
+  let active=true;
+  return () => { if(active){active=false;pending.delete(taskId);notify();} };
+}
+export function useConfigurationBusy(taskId:string) {
+  return useSyncExternalStore(listener=>{listeners.add(listener);return()=>listeners.delete(listener);},()=>isConfigurationBusy(taskId),()=>false);
+}

package/src/chat/draft.ts

@@ -0,0 +1,49 @@
+import { useSyncExternalStore } from "react";
+import type { TextBlock } from "../core/blocks";
+import type { UploadPhase } from "../core/documentUpload";
+import type { ExecutionOptions } from "../core/execution";
+export type PendingFile = { key: string; name: string; status: "reading" | "error"; error?: string; progress?: string; phase?: UploadPhase; bytes?: number; size?: number };
+export interface ComposerDraft { text: string; blocks: Array<TextBlock & { key: string }>; pending: PendingFile[]; sending: boolean; error: string | null; revision: number; executionConfig?: ExecutionOptions; executionUncertain?: boolean }
+const empty = (): ComposerDraft => ({ text: "", blocks: [], pending: [], sending: false, error: null, revision: 0 });
+const server = empty();
+const entries = new Map<string, { state: ComposerDraft; stamp: string }>();
+const listeners = new Set<() => void>();
+const textKey = (id: string) => `cli-ui:draft:${id}`;
+const dataKey = (id: string) => `${textKey(id)}:data`;
+const stamp = (id: string) => { try { return JSON.stringify([localStorage.getItem(textKey(id)), localStorage.getItem(dataKey(id))]); } catch { return ""; } };
+export function readComposerDraft(id: string): ComposerDraft {
+  const stored = stamp(id), cached = entries.get(id);
+  if (cached?.stamp === stored) return cached.state;
+  let state = empty();
+  try {
+    state.text = localStorage.getItem(textKey(id)) ?? "";
+    const data = JSON.parse(localStorage.getItem(dataKey(id)) ?? "null");
+    if (data?.version === 1) {
+      if (data.executionUncertain === true) state.executionUncertain = true;
+      if (data.executionConfig && typeof data.executionConfig === "object") state.executionConfig = Object.fromEntries(
+        Object.entries(data.executionConfig).filter(([key, value]) => ["agent", "model", "reasoning", "permission_mode"].includes(key) && (typeof value === "string" || value === null)),
+      );
+      state.blocks = Array.isArray(data.blocks) ? data.blocks.filter((b: TextBlock & { key: string }) => typeof b?.text === "string" && typeof b?.key === "string") : [];
+      state.pending = Array.isArray(data.pending) ? data.pending.map((p: PendingFile) => ({ ...p, status: "error", error: p.phase
+        ? `${p.error || "页面重载中断了上传。"}${p.error?.includes("重新选择文件") ? "" : " 请重新选择文件。"}`
+        : p.error || "页面重载中断了解析，请移除后重新添加" })) : [];
+    }
+  } catch { /* Old text drafts and restricted storage remain usable. */ }
+  entries.set(id, { state, stamp: stored });
+  return state;
+}
+export function updateComposerDraft(id: string, update: (state: ComposerDraft) => ComposerDraft) {
+  const previous = readComposerDraft(id);
+  const state = { ...update(previous), revision: previous.revision + 1 };
+  try {
+    if (state.text) localStorage.setItem(textKey(id), state.text); else localStorage.removeItem(textKey(id));
+    if (state.blocks.length || state.pending.length || state.executionConfig || state.executionUncertain) localStorage.setItem(dataKey(id), JSON.stringify({ version: 1, blocks: state.blocks, pending: state.pending, executionConfig: state.executionConfig, executionUncertain: state.executionUncertain })); else localStorage.removeItem(dataKey(id));
+  } catch { /* Keep the in-memory draft even if storage is full. */ }
+  entries.set(id, { state, stamp: stamp(id) });
+  listeners.forEach(listener => listener());
+  return state;
+}
+export function useComposerDraft(id: string) {
+  return useSyncExternalStore(listener => { listeners.add(listener); return () => listeners.delete(listener); }, () => readComposerDraft(id), () => server);
+}
+export function clearComposerDraft(id: string) { updateComposerDraft(id, () => empty()); }