@thaut/claude-ide 0.0.0-stage → 1.0.0

package/web/src/components/SessionChannels.tsx

@@ -0,0 +1,288 @@
+import { useRef, useState } from "react";
+import { Link } from "react-router";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { HttpBindingOverrides, HttpChannelBinding, HttpChannelDirection, HttpChannelsInfo, HttpExtraBody, HttpSource, HttpSourceDetails, HttpSourceInput, HttpSubscribeMethod, HttpSourceKind } from "@shared/http-channels.ts";
+import { api } from "../api.ts";
+import { Modal } from "./Modal.tsx";
+import { useConfirm } from "./Confirmation.tsx";
+import { useUnsavedChanges } from "../unsaved.tsx";
+import { Button } from "../ui/Button.tsx";
+import { Select } from "../ui/Select.tsx";
+import { Field, inputCls, monoInputCls, monoTextareaCls, Segmented, Tag } from "../ui/Form.tsx";
+
+type SourceDraft = { id?: string; kind: HttpSourceKind; brainId: string; brainVoice: string; name: string; url: string; timeout: string; subscribeMethod: HttpSubscribeMethod; headers: string; hasHeaders: boolean; extraBody: string };
+const emptySource = (): SourceDraft => ({ kind: "http", brainId: "", brainVoice: "", name: "", url: "", timeout: "120", subscribeMethod: "GET", headers: "", hasHeaders: false, extraBody: "" });
+type BrainDraft = { brainId: string; brainVoice: string; inheritVoice: boolean };
+const emptyBrain = (): BrainDraft => ({ brainId: "", brainVoice: "", inheritVoice: true });
+const brainOverrides = (draft: BrainDraft): HttpBindingOverrides => ({ brainId: draft.brainId.trim() || null, brainVoice: draft.inheritVoice ? null : draft.brainVoice });
+
+function BrainBindingFields({ source, draft, onChange }: { source: HttpSource; draft: BrainDraft; onChange: (next: BrainDraft) => void }) {
+  return <div className="space-y-3">
+    <Field label="brain_id" hint={source.brainId ? "留空继承 HTTP 源配置。" : "请在激活前填写。"}>
+      <input aria-label="会话 brain_id" className={monoInputCls} value={draft.brainId} maxLength={256} placeholder="填写 brain_id" onChange={(event) => onChange({ ...draft, brainId: event.target.value })} />
+    </Field>
+    <Field label="x-brain-voice" group hint="仅用于推送。取消勾选后留空则不发送 voice。">
+      <div className="flex min-w-0 items-center gap-3">
+        <input aria-label="会话 x-brain-voice" value={draft.brainVoice} maxLength={1024} disabled={draft.inheritVoice} className={`${monoInputCls} flex-1 disabled:cursor-not-allowed disabled:bg-surface-2`} onChange={(event) => onChange({ ...draft, brainVoice: event.target.value })} />
+        <label className="flex min-h-10 shrink-0 cursor-pointer items-center gap-2 whitespace-nowrap text-xs md:min-h-8">
+          <input type="checkbox" checked={draft.inheritVoice} onChange={(event) => onChange({ ...draft, inheritVoice: event.target.checked })} className="size-4 accent-accent" />
+          使用源配置
+        </label>
+      </div>
+    </Field>
+  </div>;
+}
+
+function EditBrainBinding({ binding, source, onClose }: { binding: HttpChannelBinding; source: HttpSource; onClose: () => void }) {
+  const [draft, setDraft] = useState<BrainDraft>({ brainId: binding.brainId ?? "", brainVoice: binding.brainVoice ?? "", inheritVoice: binding.brainVoice == null });
+  const [original] = useState(() => JSON.stringify(draft));
+  const { discard } = useUnsavedChanges(JSON.stringify(draft) !== original, "会话 brain 配置");
+  const qc = useQueryClient();
+  const save = useMutation({
+    mutationFn: () => api(`/api/http-channels/bindings/${binding.id}`, { method: "PATCH", json: brainOverrides(draft) }),
+    onSuccess: () => { void qc.invalidateQueries({ queryKey: ["http-channels"] }); onClose(); },
+  });
+  return <Modal title="会话 brain 配置" onClose={() => { if (!save.isPending) void discard().then((ok) => { if (ok) onClose(); }); }} testId="brain-binding-dialog">
+    <form className="space-y-4" onSubmit={(event) => { event.preventDefault(); save.mutate(); }}>
+      <p className="break-words text-sm text-muted">{source.name} · 配置仅影响这条注册。</p>
+      <fieldset disabled={save.isPending} className="min-w-0"><BrainBindingFields source={source} draft={draft} onChange={setDraft} /></fieldset>
+      {save.error && <p role="alert" className="text-sm text-danger">{save.error.message}</p>}
+      <div className="flex justify-end gap-2"><Button disabled={save.isPending} onClick={() => void discard().then((ok) => { if (ok) onClose(); })}>取消</Button><Button type="submit" variant="primary" loading={save.isPending}>保存配置</Button></div>
+    </form>
+  </Modal>;
+}
+
+/** Configuration persists on the server; closing this panel never stops an active binding. */
+export function SessionChannelsDialog({ pid, sid, onClose }: { pid: string; sid: string; onClose: () => void }) {
+  const qc = useQueryClient();
+  const confirm = useConfirm();
+  const info = useQuery({ queryKey: ["http-channels"], queryFn: () => api<HttpChannelsInfo>("/api/http-channels"), refetchInterval: 2000 });
+  const [tab, setTab] = useState<"session" | "all" | "sources">("session");
+  const [sourceId, setSourceId] = useState("");
+  const [direction, setDirection] = useState<HttpChannelDirection>("subscribe");
+  const [brainDraft, setBrainDraft] = useState<BrainDraft>(emptyBrain);
+  const [editingBinding, setEditingBinding] = useState<HttpChannelBinding | null>(null);
+  const [editor, setEditor] = useState<SourceDraft | null>(null);
+  const [opening, setOpening] = useState(false);
+  const [openError, setOpenError] = useState<string>();
+  const editorEpoch = useRef(0);
+  const [original, setOriginal] = useState("");
+  const [notice, setNotice] = useState<string>();
+  const { discard } = useUnsavedChanges(!!editor && JSON.stringify(editor) !== original, "HTTP 源配置");
+  const close = async () => { if (await discard()) { editorEpoch.current++; setOpening(false); onClose(); } };
+  const cancelEditor = async () => { if (await discard()) { editorEpoch.current++; setOpening(false); setEditor(null); } };
+  const changeTab = async (next: typeof tab) => {
+    if (next === tab) return;
+    if (await discard()) { editorEpoch.current++; setOpening(false); setEditor(null); setTab(next); }
+  };
+  const editSource = async (source?: HttpSource) => {
+    if (!await discard()) return;
+    const epoch = ++editorEpoch.current;
+    setEditor(null);
+    setTab("sources");
+    setOpening(true);
+    setOpenError(undefined);
+    action.reset();
+    try {
+      const details = source ? await api<HttpSourceDetails>(`/api/http-channels/sources/${source.id}`, { cache: "no-store" }) : undefined;
+      if (editorEpoch.current !== epoch) return;
+      const draft = details ? {
+        id: details.id, kind: details.kind, brainId: details.brainId ?? "", brainVoice: details.brainVoice ?? "", name: details.name, url: details.url, timeout: String(details.timeoutMs / 1000), subscribeMethod: details.subscribeMethod,
+        headers: details.hasHeaders ? JSON.stringify(details.headers, null, 2) : "", hasHeaders: details.hasHeaders,
+        extraBody: details.hasExtraBody ? JSON.stringify(details.extraBody, null, 2) : "",
+      } : emptySource();
+      setEditor(draft);
+      setOriginal(JSON.stringify(draft));
+    } catch (error) {
+      if (editorEpoch.current === epoch) setOpenError(error instanceof Error ? error.message : String(error));
+    } finally {
+      if (editorEpoch.current === epoch) setOpening(false);
+    }
+  };
+  const action = useMutation({
+    mutationFn: (fn: () => Promise<unknown>) => fn(),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["http-channels"] }),
+  });
+  const sources = info.data?.sources ?? [];
+  const selectedSource = sources.find((source) => source.id === sourceId);
+  const selectedBrain = selectedSource?.kind === "brain-api";
+  const isBrain = (binding: HttpChannelBinding) => sources.find((source) => source.id === binding.sourceId)?.kind === "brain-api";
+  const bindingType = (binding: HttpChannelBinding) => isBrain(binding) ? "brain-api 订阅" : binding.direction === "subscribe" ? "订阅" : "推送";
+  const bindings = info.data?.bindings.filter((binding) => tab === "all" || binding.sessionId === sid) ?? [];
+  const sourceName = (id: string) => sources.find((source) => source.id === id)?.name ?? "HTTP 源";
+  const error = action.error ?? openError ?? info.error;
+
+  const activate = (binding: HttpChannelBinding) => action.mutate(async () => {
+    if (binding.active && !(await confirm({
+      title: "反激活这条注册？",
+      description: `将停止“${sourceName(binding.sourceId)}”的${isBrain(binding) ? "订阅与推送" : bindingType(binding)}，清除尚未投递的内容。已交给会话的消息继续处理。`,
+      confirmLabel: "反激活",
+    })).confirmed) return;
+    const result = await api<{ deactivatedId: string | null }>(`/api/http-channels/bindings/${binding.id}/activation`, { method: "POST", json: { active: !binding.active } });
+    const replaced = info.data?.bindings.find((entry) => entry.id === result.deactivatedId);
+    setNotice(replaced ? `已激活；最早激活的${bindingType(replaced)}“${sourceName(replaced.sourceId)}”已反激活。` : undefined);
+  });
+  const removeBinding = (binding: HttpChannelBinding) => action.mutate(async () => {
+    if (!(await confirm({ title: "删除这条注册？", description: `会停止“${sourceName(binding.sourceId)}”的${isBrain(binding) ? "订阅与推送" : bindingType(binding)}并删除注册配置。`, confirmLabel: "删除注册", danger: true })).confirmed) return;
+    await api(`/api/http-channels/bindings/${binding.id}`, { method: "DELETE" });
+  });
+  const removeSource = (source: HttpSource) => action.mutate(async () => {
+    if (!(await confirm({ title: "删除 HTTP 源？", description: `“${source.name}”以及所有会话对它的注册都会删除，正在执行的请求会取消。`, confirmLabel: "删除源", danger: true })).confirmed) return;
+    await api(`/api/http-channels/sources/${source.id}`, { method: "DELETE" });
+    if (sourceId === source.id) setSourceId("");
+  });
+  const saveSource = () => action.mutate(async () => {
+    if (!editor) return;
+    const submitted = editor;
+    const epoch = editorEpoch.current;
+    let headers: Record<string, string> | undefined = editor.hasHeaders ? {} : undefined;
+    if (editor.headers.trim()) {
+      try { headers = JSON.parse(editor.headers); } catch { throw new Error("请求头不是有效 JSON"); }
+    }
+    let extraBody: HttpExtraBody = {};
+    if (editor.kind === "http" && editor.extraBody.trim()) {
+      try { extraBody = JSON.parse(editor.extraBody); } catch { throw new Error("Extra body 不是有效 JSON"); }
+    }
+    const input: HttpSourceInput = { name: editor.name, url: editor.url, kind: editor.kind, brainId: editor.brainId, ...(editor.kind === "brain-api" ? { brainVoice: editor.brainVoice } : {}), timeoutMs: Number(editor.timeout) * 1000, subscribeMethod: editor.subscribeMethod, extraBody, ...(headers !== undefined ? { headers } : {}) };
+    const source = await api<HttpSource>(`/api/http-channels/sources${editor.id ? `/${editor.id}` : ""}`, { method: editor.id ? "PUT" : "POST", json: input });
+    if (editorEpoch.current !== epoch) return;
+    setSourceId(source.id);
+    if (source.id !== sourceId) setBrainDraft(emptyBrain());
+    setNotice(`HTTP 源“${source.name}”已保存。`);
+    setOriginal(JSON.stringify({ ...submitted, id: source.id, hasHeaders: source.hasHeaders }));
+    setEditor((current) => {
+      if (editorEpoch.current !== epoch || !current) return current;
+      // Retain edits made while saving; a newly created source becomes an update next time.
+      return current === submitted ? null : { ...current, id: source.id, hasHeaders: source.hasHeaders };
+    });
+  });
+
+  return (
+    <Modal title="推送与订阅" onClose={() => void close()} testId="http-channels-dialog">
+      <div className="space-y-4">
+        <div className="flex flex-wrap items-center justify-between gap-2 text-xs text-muted">
+          <span>已激活 {info.data?.activeCount ?? 0} / {info.data?.activeLimit ?? 32}</span>
+          <span>待投递 {info.data?.inboxSize ?? 0} / {info.data?.inboxLimit ?? 1024}</span>
+        </div>
+        <Segmented label="通道管理" value={tab} onChange={(next) => void changeTab(next)} stretch options={[
+          { value: "session", label: "本会话" }, { value: "all", label: "全部注册" }, { value: "sources", label: "HTTP 源" },
+        ]} />
+        {error && <p role="alert" className="whitespace-pre-wrap break-words text-sm text-danger">{error instanceof Error ? error.message : String(error)}</p>}
+        {notice && <p role="status" className="rounded-lg bg-surface-2 px-3 py-2 text-sm">{notice}</p>}
+        {info.isPending && <p className="text-sm text-muted">正在加载…</p>}
+        {tab !== "sources" && (
+          <>
+            <p className="text-xs leading-relaxed text-muted">推送和订阅共用 32 个激活名额，超出时自动反激活最早的一条。关闭网页不影响服务端运行。</p>
+            <div className="space-y-2">
+              {bindings.map((binding) => (
+                <div key={binding.id} className="rounded-lg border border-border bg-surface px-3 py-2.5" data-testid="http-binding" data-active={binding.active}>
+                  <div className="flex min-w-0 items-center gap-2">
+                    <Tag tone={binding.active ? "accent" : "neutral"}>{bindingType(binding)}</Tag>
+                    <span className="min-w-0 flex-1 truncate text-sm font-medium">{sourceName(binding.sourceId)}</span>
+                    <Tag tone={binding.active ? "ok" : "neutral"}>{binding.active ? "已激活" : "未激活"}</Tag>
+                  </div>
+                  {tab === "all" && <Link to={`/p/${binding.projectId}/s/${binding.sessionId}`} onClick={onClose} className="mt-1 block text-xs text-accent">{binding.sessionId === sid ? "当前会话" : `会话 ${binding.sessionId.slice(0, 8)}`}</Link>}
+                  {isBrain(binding) && <p className="mt-1 break-words text-xs text-muted">brain_id: {binding.brainId ?? sources.find((source) => source.id === binding.sourceId)?.brainId ?? "未设置"}{binding.brainId ? "（会话覆写）" : "（继承源）"} · voice: {binding.brainVoice === "" ? "不发送" : binding.brainVoice ?? sources.find((source) => source.id === binding.sourceId)?.brainVoice ?? "未设置"}</p>}
+                  {binding.stats ? (
+                    <p className="mt-1.5 text-xs text-muted">{isBrain(binding) ? `已接收 ${binding.stats.received} · 已推送 ${binding.stats.pushed}` : `已${binding.direction === "subscribe" ? "投递" : "推送"} ${binding.stats.delivered}`} · 待处理 {binding.stats.pending} · 去重 {binding.stats.duplicates}{binding.stats.dropped > 0 ? ` · 未发送 ${binding.stats.dropped}` : ""}</p>
+                  ) : binding.inactiveReason && <p className="mt-1.5 text-xs text-muted">{binding.inactiveReason}</p>}
+                  {isBrain(binding) ? <>
+                    {binding.stats?.lastPullError && <p className="mt-1.5 break-words text-xs text-danger">订阅：{binding.stats.lastPullError}</p>}
+                    {binding.stats?.lastPushError && <p className="mt-1.5 break-words text-xs text-danger">推送：{binding.stats.lastPushError}</p>}
+                  </> : binding.stats?.lastError && <p className="mt-1.5 break-words text-xs text-danger">{binding.stats.lastError}</p>}
+                  <div className="mt-2 flex justify-end gap-2">
+                    {isBrain(binding) && <Button size="sm" disabled={action.isPending} onClick={() => setEditingBinding(binding)}>配置</Button>}
+                    <Button size="sm" variant="ghost" disabled={action.isPending} onClick={() => removeBinding(binding)}>删除</Button>
+                    <Button size="sm" variant={binding.active ? "secondary" : "primary"} disabled={action.isPending} onClick={() => activate(binding)}>{binding.active ? "反激活" : "激活"}</Button>
+                  </div>
+                </div>
+              ))}
+              {!bindings.length && <p className="rounded-lg border border-dashed border-border py-5 text-center text-sm text-muted">暂无注册</p>}
+            </div>
+            {tab === "session" && (
+              <form className="space-y-3 border-t border-border pt-3" onSubmit={(event) => {
+                event.preventDefault();
+                action.mutate(async () => {
+                  await api(`/api/projects/${pid}/sessions/${sid}/http-bindings`, { method: "POST", json: { sourceId, direction: selectedBrain ? "subscribe" : direction, ...(selectedBrain ? brainOverrides(brainDraft) : {}) } });
+                });
+              }}>
+                <Field label="HTTP 源" group>
+                  <Select label="HTTP 源" value={sourceId} onChange={(id) => { setSourceId(id); setBrainDraft(emptyBrain()); }} className="w-full" emptyText="请先添加 HTTP 源" options={[
+                    { value: "", label: "选择 HTTP 源…" }, ...sources.map((source) => ({ value: source.id, label: source.name, hint: source.url })),
+                  ]} />
+                </Field>
+                {!selectedBrain && <Segmented label="注册方向" value={direction} onChange={setDirection} stretch options={[{ value: "subscribe", label: "订阅 → 会话" }, { value: "push", label: "会话 → 推送" }]} />}
+                {selectedBrain && <BrainBindingFields key={sourceId} source={selectedSource!} draft={brainDraft} onChange={setBrainDraft} />}
+                <p className="text-xs leading-relaxed text-muted">{selectedBrain ? "brain-api 订阅：同时接收消息和推送会话正文，占 1 个激活名额。" : direction === "subscribe" ? "接收外部消息，发送到当前会话。" : "将会话正文发送到 HTTP 源。"}</p>
+                <div className="flex justify-between gap-2">
+                  <Button variant="ghost" onClick={() => void editSource()}>添加源</Button>
+                  <Button type="submit" variant="primary" disabled={!sourceId} loading={action.isPending}>注册</Button>
+                </div>
+                <p className="text-xs text-muted">注册后点击“激活”开始运行。</p>
+              </form>
+            )}
+          </>
+        )}
+        {tab === "sources" && (
+          <>
+            <div className="space-y-2">
+              {sources.map((source) => (
+                <div key={source.id} className="rounded-lg border border-border bg-surface px-3 py-2.5">
+                  <div className="flex flex-wrap items-center gap-2"><span className="min-w-0 flex-1 truncate text-sm font-medium">{source.name}</span>{source.kind === "brain-api" && <Tag>brain-api 订阅</Tag>}{source.hasHeaders && <Tag>已设请求头</Tag>}{source.hasExtraBody && <Tag>Extra body</Tag>}</div>
+                  <p className="mt-1 break-all font-mono text-xs text-muted">{source.url}</p>
+                  {source.kind === "brain-api" && <p className="mt-1 break-all font-mono text-xs text-muted">默认 brain_id: {source.brainId ?? "未设置"}</p>}
+                  <div className="mt-2 flex justify-end gap-2">
+                    <Button variant="ghost" size="sm" disabled={action.isPending} onClick={() => removeSource(source)}>删除</Button>
+                    <Button size="sm" disabled={action.isPending || opening} onClick={() => void editSource(source)}>编辑</Button>
+                  </div>
+                </div>
+              ))}
+            </div>
+            {opening && <p className="text-sm text-muted" role="status">正在加载源配置…</p>}
+            {!editor && <Button className="w-full" disabled={opening} onClick={() => void editSource()}>添加源</Button>}
+            {editor && (
+              <form className="space-y-3 border-t border-border pt-3" onSubmit={(event) => { event.preventDefault(); saveSource(); }}>
+                <p className="text-sm font-medium">{editor.id ? "编辑源" : "添加源"}</p>
+                {!editor.id ? <Segmented label="源类型" value={editor.kind} disabled={action.isPending} onChange={(kind) => { if (!action.isPending) setEditor({ ...editor, kind }); }} stretch options={[{ value: "http", label: "HTTP 源" }, { value: "brain-api", label: "brain-api 订阅" }]} /> : <Tag>{editor.kind === "brain-api" ? "brain-api 订阅" : "HTTP 源"}</Tag>}
+                <Field label={editor.kind === "brain-api" ? "名称（可选）" : "名称"}><input aria-label="源名称" value={editor.name} onChange={(event) => setEditor({ ...editor, name: event.target.value })} className={inputCls} maxLength={100} /></Field>
+                <Field label={editor.kind === "brain-api" ? "服务 URL" : "HTTP 地址"} hint={editor.kind === "brain-api" ? "填写服务根地址，自动连接两个收发端点。" : undefined}><input aria-label="源地址" value={editor.url} onChange={(event) => setEditor({ ...editor, url: event.target.value })} className={monoInputCls} placeholder={editor.kind === "brain-api" ? "http://localhost:8000" : "https://example.com/messages"} required /></Field>
+                {editor.kind === "brain-api" && <Field label="默认 brain_id（可选）" hint="也可以在每个会话注册时填写。"><input aria-label="brain_id" value={editor.brainId} onChange={(event) => setEditor({ ...editor, brainId: event.target.value })} className={monoInputCls} maxLength={256} placeholder="留空，在会话中配置" /></Field>}
+                {editor.kind === "brain-api" && <Field label="默认 x-brain-voice（可选）" hint="仅用于推送请求头，会话可以覆写。"><input aria-label="x-brain-voice" value={editor.brainVoice} onChange={(event) => setEditor({ ...editor, brainVoice: event.target.value })} className={monoInputCls} maxLength={1024} /></Field>}
+                {editor.kind === "http" && <Field label="订阅请求方式" group hint="仅影响订阅；推送始终使用 POST。">
+                  <Segmented label="订阅请求方式" value={editor.subscribeMethod} onChange={(subscribeMethod) => setEditor({ ...editor, subscribeMethod })} options={[{ value: "GET", label: "GET" }, { value: "POST", label: "POST" }]} />
+                </Field>}
+                <Field label="请求超时（秒）" hint="订阅使用长轮询，按外部服务的等待时间设置。"><input aria-label="源超时" type="number" min={1} max={600} value={editor.timeout} onChange={(event) => setEditor({ ...editor, timeout: event.target.value })} className={inputCls} /></Field>
+                <Field label="请求头 JSON（可选）" hint="如鉴权 Token。留空清除，Content-Type 固定为 application/json。">
+                  <textarea aria-label="源请求头" value={editor.headers} onChange={(event) => setEditor({ ...editor, headers: event.target.value })} className={monoTextareaCls} rows={3} placeholder={'{"Authorization":"Bearer …"}'} spellCheck={false} />
+                </Field>
+                {editor.kind === "http" && <Field label="Extra body JSON（可选）" hint="POST 订阅按原样发送；推送支持 {{text}}。留空清除。">
+                  <textarea aria-label="源额外请求体" value={editor.extraBody} onChange={(event) => setEditor({ ...editor, extraBody: event.target.value })} className={monoTextareaCls} rows={4} placeholder={editor.subscribeMethod === "POST" ? '{"brain_id":"你的ID"}' : '{"target_id":"频道ID","content":"{{text}}"}'} spellCheck={false} />
+                </Field>}
+                {error && <p role="alert" className="whitespace-pre-wrap break-words text-sm text-danger">{error instanceof Error ? error.message : String(error)}</p>}
+                <div className="flex justify-end gap-2"><Button variant="ghost" onClick={() => void cancelEditor()}>取消</Button><Button variant="primary" type="submit" disabled={!editor.url.trim() || (editor.kind === "http" && !editor.name.trim())} loading={action.isPending}>保存源</Button></div>
+              </form>
+            )}
+            <div className="space-y-2 rounded-lg bg-surface-2 p-3 text-xs leading-relaxed text-muted">
+              <p>订阅接收消息，推送发送会话正文。</p>
+              <p>brain-api 自动收发。源可设置默认 brain_id 和 voice，会话注册可覆写；激活前需有 brain_id。</p>
+              <details>
+                <summary className="cursor-pointer">查看消息格式</summary>
+                <div className="mt-2 space-y-2">
+                  <p>订阅无消息时返回 <code>{'{"kind":"empty"}'}</code>，有消息时返回：</p>
+                  <pre className="whitespace-pre-wrap break-words">{'{"kind":"text","text":"正文"}'}</pre>
+                  <p>可附带唯一 <code>id</code> 去重；省略时每次响应都作为新消息。正文原样投递。</p>
+                  <p>订阅可选 GET 或 POST。POST 请求体为 Extra body 原文，不附加推送字段。</p>
+                  <p>推送使用 POST JSON，Extra body 合并到以下内容：</p>
+                  <pre className="whitespace-pre-wrap break-words">{'{"kind":"text","id":"消息ID","text":"正文","sessionId":"会话ID"}'}</pre>
+                  <p>Extra body 的字符串可使用 <code>{'{{text}}'}</code>、<code>{'{{id}}'}</code>、<code>{'{{sessionId}}'}</code>，不能覆盖上述四个字段。</p>
+                  <p>服务重启后，待投递消息和去重记录会清空。</p>
+                </div>
+              </details>
+            </div>
+          </>
+        )}
+      </div>
+      {editingBinding && sources.find((source) => source.id === editingBinding.sourceId) && <EditBrainBinding key={editingBinding.id} binding={editingBinding} source={sources.find((source) => source.id === editingBinding.sourceId)!} onClose={() => setEditingBinding(null)} />}
+    </Modal>
+  );
+}

package/web/src/components/SessionExtras.tsx

@@ -0,0 +1,263 @@
+import { Popover, usePopover } from "../ui/Popover.tsx";
+import { Button } from "../ui/Button.tsx";
+import { BrainIcon } from "../ui/icons.tsx";
+import { useEffect, useRef, useState } from "react";
+import { Link, useNavigate } from "react-router";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { BtwInfo, ContextInfo } from "@shared/protocol.ts";
+import { api } from "../api.ts";
+import { useSessionLive } from "../live.ts";
+import { Markdown } from "./Markdown.tsx";
+import { StateDot } from "./Shell.tsx";
+import { ChevronIcon } from "./icons.tsx";
+import { useCompactSession } from "../session-confirmations.ts";
+
+// ---------- /btw ----------
+
+export function useBtw(pid: string, sid: string) {
+  return useQuery({ queryKey: ["btw", pid, sid], queryFn: ({ signal }) => api<BtwInfo>(`/api/projects/${pid}/sessions/${sid}/btw`, { signal }) });
+}
+
+export function useAskBtw(pid: string, sid: string, onAsked?: (id: string) => void) {
+  const qc = useQueryClient();
+  const current = useRef({ pid, sid });
+  current.current = { pid, sid };
+  const mounted = useRef(false);
+  useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+  return async (question: string) => {
+    const { id } = await api<{ id: string }>(`/api/projects/${pid}/sessions/${sid}/btw`, { method: "POST", json: { question } });
+    // Opening the selected branch must not wait for every preview to refresh.
+    void qc.invalidateQueries({ queryKey: ["btw", pid, sid] });
+    if (mounted.current && current.current.pid === pid && current.current.sid === sid) onAsked?.(id);
+  };
+}
+
+function usePromote(pid: string) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (id: string) => api(`/api/projects/${pid}/sessions/${id}/promote`, { method: "POST" }),
+    onSuccess: async (_data, id) => {
+      // The server has committed the promotion. Reflect it immediately, before
+      // revalidating previews, and prevent old in-flight lists restoring it.
+      await qc.cancelQueries({ queryKey: ["btw", pid] });
+      qc.setQueriesData<BtwInfo>({ queryKey: ["btw", pid] }, (previous) => previous ? {
+        parent: previous.parent,
+        children: previous.children.filter((child) => child.id !== id),
+      } : previous);
+      qc.setQueryData<BtwInfo>(["btw", pid, id], (previous) => ({ parent: null, children: previous?.children ?? [] }));
+      qc.invalidateQueries({ queryKey: ["btw", pid] });
+      qc.invalidateQueries({ queryKey: ["sessions", pid] });
+    },
+  });
+}
+
+/** Shown on a btw session: where it came from, and the way to make it a normal session. */
+export function BtwBanner({ pid, sid }: { pid: string; sid: string }) {
+  const btw = useBtw(pid, sid);
+  const promote = usePromote(pid);
+  const parent = btw.data?.parent;
+  if (!parent) return null;
+  return (
+    <div className="flex flex-wrap items-center gap-x-3 gap-y-1 border-b border-border bg-surface-2/60 px-4 py-2 text-sm md:px-6" data-testid="btw-banner">
+      <span className="text-muted">btw 旁支 · 后续消息留在此会话</span>
+      <Link to={`/p/${pid}/s/${parent}`} className="text-accent underline underline-offset-2">
+        返回主会话
+      </Link>
+      <Button size="sm" className="ml-auto" onClick={() => promote.mutate(sid)} loading={promote.isPending}>
+        转为普通会话
+      </Button>
+      {promote.error && <p role="alert" className="basis-full text-xs text-danger">转换失败：{promote.error.message}</p>}
+    </div>
+  );
+}
+
+/** The side questions asked from this session, listed inside it (not in the session list). */
+export function BtwPanel({ pid, sid, open, setOpen }: { pid: string; sid: string; open: boolean; setOpen: (v: boolean) => void }) {
+  const btw = useBtw(pid, sid);
+  const promote = usePromote(pid);
+  const navigate = useNavigate();
+  const ask = useAskBtw(pid, sid, (id) => navigate(`/p/${pid}/s/${id}`));
+  const [q, setQ] = useState("");
+  const [err, setErr] = useState<string>();
+  const [asking, setAsking] = useState(false);
+  const submitting = useRef(false);
+  const children = btw.data?.children ?? [];
+  if (children.length === 0 && !open) return null;
+  const runningCount = children.filter((c) => c.state !== "idle").length;
+
+  return (
+    <div className="mb-2 rounded-xl border border-border bg-surface" data-testid="btw-panel">
+      <button className="flex w-full items-center gap-2 px-3 py-2 text-left text-sm" onClick={() => setOpen(!open)} aria-expanded={open}>
+        <ChevronIcon open={open} />
+        <span>旁支问答</span>
+        <span className="text-muted">{children.length}</span>
+        {runningCount > 0 && <span className="size-1.5 animate-pulse rounded-full bg-accent" />}
+      </button>
+      {open && (
+        <div className="max-h-[40dvh] space-y-2 overflow-y-auto overscroll-contain border-t border-border px-3 py-2">
+          {children.map((c) => (
+            <div key={c.id} className="rounded-lg border border-border px-3 py-2" data-testid="btw-item" data-state={c.state}>
+              <div className="flex items-start gap-2">
+                <StateDot state={c.state} />
+                <div className="min-w-0 flex-1 break-words text-sm font-medium">{c.question}</div>
+              </div>
+              <div className="mt-1 text-sm" data-testid="btw-answer">
+                {c.answer ? <Markdown text={c.answer} /> : <span className="text-muted">{c.state === "idle" ? "暂无回答" : "正在回答…"}</span>}
+              </div>
+              <div className="mt-2 flex flex-wrap gap-2 text-xs">
+                <Button size="sm" onClick={() => navigate(`/p/${pid}/s/${c.id}`)}>
+                  继续对话
+                </Button>
+                <Button size="sm" onClick={() => promote.mutate(c.id)} loading={promote.isPending && promote.variables === c.id} disabled={promote.isPending}>
+                  转为普通会话
+                </Button>
+              </div>
+            </div>
+          ))}
+          {children.length === 0 && <form
+            className="flex gap-2"
+            onSubmit={async (e) => {
+              e.preventDefault();
+              if (!q.trim() || submitting.current) return;
+              submitting.current = true; setAsking(true);
+              setErr(undefined);
+              try {
+                await ask(q);
+                setQ("");
+              } catch (error) {
+                setErr(error instanceof Error ? error.message : String(error));
+              } finally {
+                submitting.current = false; setAsking(false);
+              }
+            }}
+          >
+            <input
+              aria-label="旁支问题"
+              placeholder="创建一个旁支，单独讨论这个问题"
+              value={q}
+              onChange={(e) => setQ(e.target.value)}
+              className="h-10 min-w-0 flex-1 rounded-md border border-border bg-bg px-3 text-base outline-none focus:border-accent/60 focus:ring-2 focus:ring-accent/20 md:h-8 md:text-sm"
+            />
+            <Button type="submit" variant="primary" disabled={!q.trim()} loading={asking}>
+              创建旁支
+            </Button>
+          </form>}
+          <p className="text-xs text-muted">每个主会话绑定一个 btw 旁支。继续对话不会新建；转为普通会话后，主会话才能创建新的旁支。</p>
+          {err && <p className="text-xs text-danger" role="alert">{err}</p>}
+          {promote.error && <p className="text-xs text-danger" role="alert">转换失败：{promote.error.message}</p>}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ---------- context usage ----------
+
+function fmtTokens(n: number) {
+  return n >= 1000 ? `${(n / 1000).toFixed(n >= 100_000 ? 0 : 1)}k` : String(n);
+}
+
+/** Context usage in the session header; opens the /context breakdown with compact and clear actions. */
+export function ContextMeter({ pid, sid, onClear }: { pid: string; sid: string; onClear: () => Promise<boolean> }) {
+  const compact = useCompactSession(pid, sid);
+  const live = useSessionLive(sid);
+  const results = live?.events.filter((e) => e.k === "sdk" && e.m.type === "result").length ?? 0;
+  const state = live?.snapshot.state;
+  const ctx = useQuery({
+    queryKey: ["context", sid, results, state === "idle"],
+    queryFn: () => api<ContextInfo | null>(`/api/projects/${pid}/sessions/${sid}/context`),
+    placeholderData: (prev) => prev,
+  });
+  const pop = usePopover();
+  const [instructions, setInstructions] = useState("");
+  const [actionError, setActionError] = useState<string>();
+
+  const data = ctx.data;
+  const pct = data ? Math.round(data.percentage) : undefined;
+  const used = data?.categories.filter((c) => c.kind !== "deferred") ?? [];
+
+  return (
+    <>
+      <Button
+        ref={pop.triggerRef}
+        iconOnly
+        icon={<BrainIcon size={18} className={pct !== undefined && pct >= 80 ? "text-danger" : "text-muted"} />}
+        onClick={pop.toggle}
+        aria-haspopup="dialog"
+        aria-expanded={pop.open}
+        aria-label="上下文用量"
+        title={pct !== undefined ? `上下文用量：${pct}%` : "上下文用量"}
+        data-testid="context-meter"
+      />
+      <Popover open={pop.open} onClose={pop.close} anchor={pop.triggerRef} align="end" width={340} label="上下文用量" testId="context-details">
+        <div className="px-4 pb-3 pt-2 text-sm">
+          <div className="flex items-baseline justify-between">
+            <h3 className="text-base">上下文</h3>
+            {live?.snapshot.costUsd !== undefined && <span className="text-xs tabular-nums text-muted">本会话 ${live.snapshot.costUsd.toFixed(4)}</span>}
+          </div>
+          {data ? (
+            <>
+              <div className="mt-2 h-2 overflow-hidden rounded-full bg-surface-2">
+                <div className={`h-full ${pct !== undefined && pct >= 80 ? "bg-danger" : "bg-accent"}`} style={{ width: `${pct ?? 0}%` }} />
+              </div>
+              <p className="mt-1.5 text-xs text-muted">
+                {fmtTokens(data.totalTokens)} / {fmtTokens(data.maxTokens)} tokens · {pct}% · {data.model}
+              </p>
+              <table className="mt-2 w-full text-xs">
+                <tbody>
+                  {used.map((c) => (
+                    <tr key={c.name} className="border-t border-border" data-testid="context-row">
+                      <td className="py-1.5 pr-2">{c.name}</td>
+                      <td className="py-1.5 pr-2 text-right font-mono tabular-nums">{fmtTokens(c.tokens)}</td>
+                      <td className="w-12 py-1.5 text-right font-mono tabular-nums text-muted">{data.maxTokens ? ((c.tokens / data.maxTokens) * 100).toFixed(1) : "0"}%</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </>
+          ) : (
+            <p className="mt-1 text-muted">发出第一条消息后可见。</p>
+          )}
+          <div className="mt-3 space-y-2 border-t border-border pt-3">
+            <input
+              aria-label="压缩说明"
+              placeholder="压缩说明（可选），如：保留接口设计的讨论"
+              value={instructions}
+              onChange={(e) => setInstructions(e.target.value)}
+              className="h-10 w-full rounded-md border border-border bg-bg px-3 text-base outline-none focus:border-accent/60 focus:ring-2 focus:ring-accent/20 md:h-8 md:text-sm"
+            />
+            <div className="flex gap-2">
+              <Button
+                className="flex-1"
+                onClick={async () => {
+                  pop.close();
+                  if (await compact(instructions)) setInstructions("");
+                  else pop.setOpen(true);
+                }}
+              >
+                压缩
+              </Button>
+              <Button
+                className="flex-1"
+                title="新建一个会话并跳转过去，原会话保留"
+                onClick={async () => {
+                  pop.close();
+                  setActionError(undefined);
+                  try {
+                    if (!await onClear()) pop.setOpen(true);
+                  } catch (error) {
+                    setActionError(error instanceof Error ? error.message : String(error));
+                    pop.setOpen(true);
+                  }
+                }}
+              >
+                新开会话
+              </Button>
+            </div>
+            {actionError && <p role="alert" className="text-xs text-danger">{actionError}</p>}
+          </div>
+        </div>
+      </Popover>
+    </>
+  );
+}

package/web/src/components/SettingsLink.tsx

@@ -0,0 +1,21 @@
+import { NavLink, useLocation } from "react-router";
+
+/** Sidebar entry to the global settings area; carries the current project along. */
+export function SettingsLink() {
+  const { pathname, search } = useLocation();
+  const pid = /^\/p\/([^/]+)/.exec(pathname)?.[1] ?? (pathname.startsWith("/settings") ? new URLSearchParams(search).get("p") : null);
+  return (
+    <NavLink
+        to={`/settings/general${pid ? `?p=${encodeURIComponent(pid)}` : ""}`}
+        className={() =>
+          `flex items-center gap-2 rounded-md px-2.5 py-2 text-sm ${pathname.startsWith("/settings") ? "bg-surface font-medium text-text" : "text-muted hover:bg-surface"}`
+        }
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round" aria-hidden>
+          <circle cx="12" cy="12" r="3" />
+          <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09a1.65 1.65 0 0 0-1-1.51 1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09a1.65 1.65 0 0 0 1.51-1 1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33h0a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51h0a1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82v0a1.65 1.65 0 0 0 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" />
+        </svg>
+        设置
+    </NavLink>
+  );
+}