cortico 0.1.0

package/src/web/client/features/live/index.ts

@@ -0,0 +1,392 @@
+import type { ContextRecord } from '../../../../protocol/open-responses/context.ts';
+/**
+ * 页面状态由 /ws/debug 推送，保存在挂载闭包中，随 Lifecycle 释放。
+ * 调试通道不可用时改用 /ws/sessions，只接收 session 列表。
+ */
+
+import type {
+  ConsoleStreamHandle,
+  Disposable,
+} from '../../../shared/client-panel.ts';
+import { PROVIDERS_LAMP_ID, panelStreamRoute } from '../../../shared/console-protocol.ts';
+import type { FeatureContext, FrameworkFeature } from '../feature.ts';
+import { get, post } from '../../core/api.ts';
+import { openStream } from '../../core/stream.ts';
+import { browserSocketEnv, openFrameworkSocket, type SocketEnv } from '../../core/websocket.ts';
+import { buildCtxPanel, computeCtx, type ContextBreakdown } from './context.ts';
+import { createForkView, MAIN_ID, MAIN_LABEL } from './fork.ts';
+import {
+  arr,
+  str,
+  type SessionStat,
+  type StatusSnapshot,
+  type ToolSchemaDoc,
+} from './protocol.ts';
+import { subscribeLamps } from '../../ui/lamp.ts';
+import { createOnboarding, type OnboardingView } from './onboarding.ts';
+import { createSessionBand } from './sessions.ts';
+import { applyDisplayName, createStatusBand } from './status.ts';
+import { S } from './strings.ts';
+import { createTimeline } from './timeline.ts';
+
+const DEBUG_WS_PATH = '/ws/debug';
+const SESSIONS_WS_PATH = '/ws/sessions';
+
+/** 测试注入点:不传就是真浏览器那一套。 */
+export interface LiveFeatureOptions {
+  env?: SocketEnv;
+}
+
+export function createLiveFeature(opts: LiveFeatureOptions = {}): FrameworkFeature {
+  return {
+    route: 'live',
+    label: S.navLabel,
+    icon: 'terminal',
+    navMode: 'primary',
+    // 两条通道任一挂着这一页就有意义;都没有的话导航里根本不出现它。
+    needsAny: ['debug', 'sessions'],
+    mount(ctx) {
+      return mountLive(ctx, opts.env ?? browserSocketEnv(window));
+    },
+  };
+}
+
+/** 缺省实例。host 直接用这个。 */
+export const liveFeature: FrameworkFeature = createLiveFeature();
+
+function ctxRingStyle(d: ContextBreakdown | null): string {
+  if (!d || !d.total || d.maxTokens === null) return '--ctx-ring:conic-gradient(var(--border) 0 100%)';
+  const stops: string[] = [];
+  let cursor = 0;
+  for (const cat of d.cats) {
+    if (cat.tok <= 0) continue;
+    const next = Math.min(100, cursor + cat.tok / d.maxTokens * 100);
+    if (next > cursor) stops.push(`${cat.color} ${cursor.toFixed(2)}% ${next.toFixed(2)}%`);
+    cursor = next;
+  }
+  stops.push(`var(--border) ${cursor.toFixed(2)}% 100%`);
+  return `--ctx-ring:conic-gradient(${stops.join(',')})`;
+}
+
+function mountLive(ctx: FeatureContext, env: SocketEnv): Disposable | void {
+  const { ui } = ctx;
+  const doc = ctx.root.ownerDocument;
+
+  // ── 这一页的全部活数据 ────────────────────────────────────────────
+  const state = {
+    messages: [] as ContextRecord[],
+    /** 合成开头，不写入 session 记录。 */
+    head: [] as ContextRecord[],
+    toolSchemas: [] as ToolSchemaDoc[],
+    status: null as StatusSnapshot | null,
+    sessions: [] as SessionStat[],
+    displayName: '',
+  };
+
+  const view = ui.h('div', 'liveview');
+  const band = ui.h('div', 'liveband');
+  view.appendChild(band);
+  ctx.root.appendChild(view);
+
+  // ── 顶栏 ──────────────────────────────────────────────────────────
+  const status = createStatusBand(ui);
+  status.render(null);
+
+  const timeline = createTimeline({ ui, lifecycle: ctx.lifecycle, signal: ctx.signal });
+
+  const sessionBand = createSessionBand({
+    ui,
+    signal: ctx.signal,
+    onPick: (id, label) => fork.switchTo(id, label),
+  });
+
+  const ctxAnchor = ui.h('span', 'ctxanchor');
+  const ctxOpen = ui.h('button', 'ctxdonut');
+  ctxOpen.type = 'button';
+  ctxOpen.setAttribute('aria-haspopup', 'dialog');
+  ctxOpen.setAttribute('aria-expanded', 'false');
+  ctxOpen.setAttribute('aria-label', S.ctxOpenAria);
+  const ctxPct = ui.h('span', 'ctxpct', '—');
+  ctxOpen.appendChild(ctxPct);
+  ctxAnchor.appendChild(ctxOpen);
+
+  let ctxPanel: HTMLElement | null = null;
+  const closeCtx = (): void => {
+    ctxPanel?.remove();
+    ctxPanel = null;
+    ctxOpen.setAttribute('aria-expanded', 'false');
+  };
+  ctxOpen.addEventListener('click', () => {
+    if (ctxPanel) {
+      closeCtx();
+      return;
+    }
+    ctxPanel = buildCtxPanel(
+      ui,
+      computeCtx({
+        messages: state.messages,
+        head: state.head,
+        toolSchemas: state.toolSchemas,
+        status: state.status,
+      }),
+    );
+    ctxPanel.setAttribute('role', 'dialog');
+    ctxPanel.setAttribute('aria-label', S.ctxPanelAria);
+    ctxAnchor.appendChild(ctxPanel);
+    ctxOpen.setAttribute('aria-expanded', 'true');
+  }, { signal: ctx.signal });
+  doc.addEventListener('pointerdown', (event) => {
+    if (ctxPanel && !ctxAnchor.contains(event.target as Node)) closeCtx();
+  }, { signal: ctx.signal });
+  doc.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape') closeCtx();
+  }, { signal: ctx.signal });
+
+  let netEl: HTMLElement = ui.pill(S.netConnecting, 'plain');
+  const setNet = (online: boolean): void => {
+    const next = ui.pill(online ? S.netOnline : S.netOffline, online ? 'on' : 'off');
+    netEl.replaceWith(next);
+    netEl = next;
+  };
+
+  const summary = ui.h('div', 'live-summary');
+  summary.append(status.el, ui.h('span', 'grow'), netEl);
+  band.append(summary, sessionBand.el);
+
+  const composer = ui.promptInput({
+    label: S.composerLabel,
+    placeholder: S.composerPlaceholder,
+    hint: S.composerHint,
+    tools: ctxAnchor,
+    images: { max: 8 },
+    onSubmit: (text, images) => {
+      if (!chatStream?.open) ui.toast(S.composerQueued);
+      // 首启时运行是停着的（见 launcher）；发话与按下那颗按钮同样是让它开始跑。
+      if (onboarding) {
+        void resumeRun();
+        dismissOnboarding();
+      }
+      const attached = images.map((i) => ({ mime: i.mime, base64: i.base64, name: i.name }));
+      chatStream?.send(JSON.stringify({ type: 'msg', text, ...(attached.length ? { images: attached } : {}) }));
+      return true;
+    },
+  });
+  view.append(timeline.el, composer.el);
+  timeline.rebuild([], { empty: S.emptyConnecting });
+
+  let providerReady = false;
+  ctx.lifecycle.own(subscribeLamps(ctx.root.ownerDocument, (lamps) => {
+    const lamp = lamps[PROVIDERS_LAMP_ID]?.[0];
+    composer.setPlaceholder(lamp && lamp.state !== 'online' ? S.composerNoProvider : null);
+    providerReady = lamp?.state === 'online';
+    onboarding?.setProvider(providerReady);
+  }));
+
+  const resumeRun = (): Promise<unknown> => post('/api/run/resume', {}, { signal: ctx.signal });
+
+  let onboarding: OnboardingView | null = null;
+  /** 本次挂载里已经收过一次；销标记的请求在路上时状态帧还会报 pending。 */
+  let dismissed = false;
+  const dismissOnboarding = (): void => {
+    dismissed = true;
+    void post('/api/onboarding/dismiss', {}, { signal: ctx.signal }).catch(() => { /* 删除失败时标记仍在，下次挂载仍显示引导。 */ });
+    syncOnboarding();
+  };
+  const syncOnboarding = (): void => {
+    const fresh = !dismissed && state.status?.onboardingPending === true;
+    if (fresh && !onboarding) {
+      onboarding = createOnboarding({
+        ui,
+        doc,
+        signal: ctx.signal,
+        go: (segments) => ctx.router.navigate(segments),
+        start: (label) => {
+          void resumeRun().then(
+            () => {
+              chatStream?.send(JSON.stringify({ type: 'greet', label }));
+              dismissOnboarding();
+            },
+            (err) => ctx.onError(err),
+          );
+        },
+      });
+      onboarding.setProvider(providerReady);
+      timeline.setHeader(onboarding.el);
+      timeline.setHideSystem(true);
+      timeline.rebuild(state.messages, { head: state.head });
+      return;
+    }
+    if (!fresh && onboarding) {
+      timeline.setHeader(null);
+      onboarding = null;
+      timeline.setHideSystem(false);
+      timeline.rebuild(state.messages, { head: state.head });
+    }
+  };
+
+  const hello = JSON.stringify({ type: 'hello', name: '控制台' });
+  let chatStream: ConsoleStreamHandle | null = null;
+
+  // ── fork 视图 ─────────────────────────────────────────────────────
+  const fork = createForkView({
+    ui,
+    lifecycle: ctx.lifecycle,
+    signal: ctx.signal,
+    timeline,
+    mainMessages: () => state.messages,
+    mainHead: () => state.head,
+    sessions: () => state.sessions,
+    onChange: () => sessionBand.render(state.sessions, fork.id),
+    onError: (err) => ctx.onError(err),
+  });
+
+  const updateCtx = (): void => {
+    const d = computeCtx({
+      messages: state.messages,
+      head: state.head,
+      toolSchemas: state.toolSchemas,
+      status: state.status,
+    });
+    ctxOpen.setAttribute('style', ctxRingStyle(d));
+    const known = d !== null && d.maxTokens !== null && d.maxTokens > 0;
+    const ratio = known ? d.total / d.maxTokens! : 0;
+    // 分母未知(Persona没报预算、Provider 也没报窗口)时圈里只写计数,不编百分比
+    ctxPct.textContent = d ? (known ? ui.fmt.percent(ratio) : ui.fmt.count(d.total)) : '—';
+    ctxOpen.className = `ctxdonut${ratio >= 1 ? ' danger' : d && d.softRatio !== null && ratio >= d.softRatio ? ' warn' : ''}`;
+    ctxOpen.title = d
+      ? S.ctxTitle(ui.fmt.count(d.total), known ? ui.fmt.count(d.maxTokens!) : null)
+      : S.ctxWaiting;
+  };
+
+  const setStatus = (st: StatusSnapshot | null): void => {
+    state.status = st;
+    status.render(st);
+    if (st && applyDisplayName(doc, st.displayName, state.displayName)) {
+      state.displayName = str(st.displayName);
+    }
+    if (st) timeline.setSpeaker(str(st.displayName));
+    updateCtx();
+  };
+
+  const setSessions = (list: SessionStat[]): void => {
+    state.sessions = list;
+    sessionBand.render(list, fork.id);
+    fork.noteSessions();
+  };
+
+  // ── 调试帧 ────────────────────────────────────────────────────────
+  const onFrame = (f: Readonly<Record<string, unknown>>): void => {
+    switch (f.t) {
+      case 'hello': {
+        state.toolSchemas = arr<ToolSchemaDoc>(f.toolSchemas);
+        state.messages = arr<ContextRecord>(f.session);
+        state.head = arr<ContextRecord>(f.head);
+        // 重连即回到主视图:那个 fork 的轮询若还开着,这里连它一起收。
+        fork.switchTo(MAIN_ID, MAIN_LABEL);
+        // 先记说话人再铺时间线:头像占位圆的首字在画气泡时就定了。
+        setStatus((f.status as StatusSnapshot | null) ?? null);
+        timeline.rebuild(state.messages, { head: state.head });
+        setSessions(arr<SessionStat>(f.sessions));
+        break;
+      }
+      case 'session.append': {
+        const index = f.index;
+        if (typeof index === 'number' && Number.isInteger(index) && index >= 0) {
+          if (index < state.messages.length) break;
+          if (index === state.messages.length) {
+            const message = f.message as ContextRecord;
+            state.messages.push(message);
+            if (fork.isMain()) timeline.append(message, index, true);
+            break;
+          }
+        }
+        // 缺失、非法或跳跃的索引需要重新获取完整会话。
+        socket?.dispose();
+        reopenDebug();
+        break;
+      }
+      case 'session.reset':
+        state.messages = arr<ContextRecord>(f.messages);
+        if (f.head !== undefined) state.head = arr<ContextRecord>(f.head);
+        if (fork.isMain()) {
+          timeline.rebuild(state.messages, { note: S.sessionResetNote, head: state.head });
+        }
+        break;
+      case 'status':
+        setStatus((f.status as StatusSnapshot | null) ?? null);
+        break;
+      case 'sessions':
+        setSessions(arr<SessionStat>(f.sessions));
+        break;
+      case 'sys':
+        // 服务端明说通道不可用:别再画"连接中",也别让 fork 轮询留着。
+        fork.switchTo(MAIN_ID, MAIN_LABEL);
+        state.messages = [];
+        timeline.rebuild([], { empty: str(f.text) || S.debugUnavailable });
+        break;
+      default:
+        break; // 认不出的帧忽略:服务端以后加帧型不该让这一页炸
+    }
+    updateCtx();
+    syncOnboarding();
+  };
+
+  let socket: Disposable | null = null;
+  const reopenDebug = (): void => {
+    socket = openFrameworkSocket({
+      path: DEBUG_WS_PATH,
+      lifecycle: ctx.lifecycle,
+      env,
+      onFrame,
+      onNet: setNet,
+      onError: (err) => ctx.onError(err),
+    });
+  };
+
+  if (ctx.capabilities.debug) {
+    reopenDebug();
+  } else {
+    timeline.rebuild([], { empty: S.debugNotMounted });
+    // 状态读数仍然有:`/api/status` 是框架端点,不随调试通道走。
+    void get<StatusSnapshot>('/api/status', { signal: ctx.signal }).then(
+      (st) => {
+        setStatus(st);
+        setNet(true);
+        syncOnboarding();
+      },
+      (err) => {
+        if ((err as { name?: string } | null)?.name === 'AbortError') return;
+        setNet(false);
+        ctx.onError(err);
+      },
+    );
+    if (ctx.capabilities.sessions) {
+      openFrameworkSocket({
+        path: SESSIONS_WS_PATH,
+        lifecycle: ctx.lifecycle,
+        env,
+        onFrame: (f) => {
+          if (f.t === 'sessions') setSessions(arr<SessionStat>(f.sessions));
+        },
+        onNet: setNet,
+        onError: (err) => ctx.onError(err),
+      });
+    }
+  }
+
+  chatStream = ctx.lifecycle.own(openStream({
+    url: env.wsUrl(panelStreamRoute('world:terminal', 'chat')),
+    signal: ctx.signal,
+    createSocket: env.createSocket,
+    setTimer: env.setTimer,
+    clearTimer: env.clearTimer,
+    onError: (err) => ctx.onError(err),
+    handlers: {
+      message: () => {},
+      close: (willRetry) => {
+        if (willRetry) chatStream?.send(hello);
+      },
+    },
+  }));
+  chatStream.send(hello);
+}

package/src/web/client/features/live/onboarding.ts

@@ -0,0 +1,113 @@
+/**
+ * 开场引导的配置状态与操作入口。
+ * 端点状态由终端页从 providers 灯推进来，已启用的 World 在挂载时读一次接口。
+ * 是否显示由终端页判定，这里只画。
+ */
+
+import type { ConsoleUi } from '../../../shared/client-panel.ts';
+import { get } from '../../core/api.ts';
+import { brandMark, icon, type ConsoleIconName } from '../../ui/icons.ts';
+import { S } from './strings.ts';
+
+/** 这一页用得到的 `/api/worlds` 字段。 */
+interface WorldRow {
+  label?: unknown;
+  status?: unknown;
+}
+
+export interface OnboardingDeps {
+  ui: ConsoleUi;
+  doc: Document;
+  signal: AbortSignal;
+  /** 跳到控制台的另一页。 */
+  go(segments: readonly string[]): void;
+  /** 继续运行并请对方开口；`label` 是这颗按钮上的字，逐字进事件正文。 */
+  start(label: string): void;
+}
+
+export interface OnboardingView {
+  el: HTMLElement;
+  /** 端点可用性来自 providers 灯。 */
+  setProvider(ready: boolean): void;
+}
+
+/** 状态行的语气：成不成事各有各的颜色，不报读数时收起这一行。 */
+type Tone = 'ok' | 'bad';
+
+interface Bubble {
+  setState(text: string | null, tone?: Tone): void;
+  button: HTMLButtonElement;
+}
+
+export function createOnboarding(deps: OnboardingDeps): OnboardingView {
+  const { ui, doc, signal } = deps;
+
+  const el = ui.h('div', 'onboarding');
+  const grid = ui.h('div', 'ob-grid');
+  const gutter = ui.h('div', 'gutter ob-mark');
+  gutter.appendChild(brandMark(doc));
+  const col = ui.h('div', 'ob-col');
+  col.appendChild(ui.h('div', 'ob-who', S.obWho));
+  const body = ui.h('div', 'turnbody');
+  col.appendChild(body);
+  grid.append(gutter, col);
+  el.appendChild(grid);
+
+  const bubble = (
+    line: string,
+    action?: { label: string; icon?: ConsoleIconName; accent?: boolean; onClick(): void },
+  ): Bubble => {
+    const box = ui.h('div', 'monolog');
+    box.appendChild(ui.h('div', 'monolog-body', line));
+    const state = ui.h('div', 'ob-state hidden');
+    const button = ui.h('button', action?.accent ? 'seg active ob-btn ob-go' : 'seg active ob-btn');
+    button.type = 'button';
+    if (action?.icon) button.appendChild(icon(doc, action.icon));
+    button.appendChild(ui.h('span', null, action?.label ?? ''));
+    if (action) button.addEventListener('click', () => action.onClick(), { signal });
+    box.appendChild(state);
+    if (action) {
+      const acts = ui.h('div', 'ob-acts');
+      acts.appendChild(button);
+      box.appendChild(acts);
+    }
+    body.appendChild(box);
+    return {
+      button,
+      setState(text, tone) {
+        state.className = text === null ? 'ob-state hidden' : `ob-state ${tone ?? ''}`.trim();
+        state.textContent = text ?? '';
+      },
+    };
+  };
+
+  bubble(S.obWelcome);
+  const provider = bubble(S.obProvider, { label: S.obGoConfigure, onClick: () => deps.go(['providers']) });
+  const worlds = bubble(S.obWorlds, { label: S.obGoConfigure, onClick: () => deps.go(['world']) });
+  bubble(S.obPrompts, { label: S.obGoEdit, onClick: () => deps.go(['prompts']) });
+
+  const startLabel = S.obStart;
+  const ready = bubble(S.obReady, {
+    label: startLabel,
+    icon: 'play',
+    accent: true,
+    onClick: () => deps.start(startLabel),
+  });
+
+  // 读不到就让这一行空着：引导区少一行读数，不该变成错误卡。
+  void get<{ worlds?: WorldRow[] }>('/api/worlds', { signal }).then((data) => {
+    const active = (data?.worlds ?? [])
+      .filter((w) => w.status === 'active' && typeof w.label === 'string')
+      .map((w) => w.label as string);
+    if (active.length) worlds.setState(S.obWorldsState(active));
+  }, () => {});
+
+  return {
+    el,
+    setProvider(available) {
+      provider.setState(available ? S.obProviderReady : S.obProviderNone, available ? 'ok' : 'bad');
+      ready.setState(available ? null : S.obProviderNone, 'bad');
+      ready.button.disabled = !available;
+    },
+  };
+}

package/src/web/client/features/live/protocol.ts

@@ -0,0 +1,122 @@
+/**
+ * 调试帧与 /api/status 的前端读取形状。服务端 contribution 可提供可选字段，视图按字段是否存在决定展示；保留服务端键名，集中读取当前状态字段。
+ */
+
+export interface ToolOwner {
+  kind?: string;
+  id?: string;
+  label?: string;
+}
+
+/** `/api/tool-schemas` 与 debug hello 里的工具表条目。 */
+export interface ToolSchemaDoc {
+  name: string;
+  description?: string;
+  parameters?: unknown;
+  owner?: ToolOwner | null;
+  tags?: readonly string[];
+}
+
+/** `/api/sessions` 的一行(主意识与各 fork)。 */
+export interface SessionStat {
+  id: string;
+  label: string;
+  role: string;
+  calls: number;
+  promptTokens: number;
+  completionTokens: number;
+  cacheHitTokens: number;
+  cacheHitRate: number | null;
+  messageCount: number;
+  /** null = 还在跑 */
+  endedAt?: string | null;
+}
+
+export interface UsageSnapshot {
+  promptTokens?: number;
+  cacheHitTokens?: number;
+}
+
+/**
+ * 上下文预算。两个来源合成一份:core 在 `loop.context` 报物理上限、上游数过的
+ * 部分与摘除思维链开关;Persona在顶层 `context` 报自己的阶段预算与软预警线。
+ */
+export interface ContextBudget {
+  /** Persona的阶段预算(圈的分母);没报时分母退到 hardTokens */
+  maxTokens?: number;
+  softRatio?: number;
+  keepPastThinking?: boolean;
+  /** 模型一次请求能收的输入上限;窗口未知时 null */
+  hardTokens?: number | null;
+  /** estTokens 里上游数过的部分;整份估算时 0 */
+  countedTokens?: number;
+}
+
+export interface LoopStatus {
+  estTokens?: number | null;
+  messageCount?: number | null;
+  lastUsage?: UsageSnapshot | null;
+  batchesHandled?: number | null;
+  roundsLastBatch?: number | null;
+  paused?: boolean;
+  scheduleBlocked?: boolean;
+  truncating?: boolean;
+  context?: ContextBudget | null;
+}
+
+/** Persona自报的一枚状态筹码。框架照文本渲染,不解释里面说的是什么。 */
+export interface StatusChip {
+  label: string;
+  tone?: 'plain' | 'warn' | 'accent';
+}
+
+export interface StatusSnapshot {
+  displayName?: string;
+  loop?: LoopStatus | null;
+  /**
+   * Persona自报的状态筹码(「梦中」这类)。框架不认识任何一个人格概念,只把
+   * 文本按 tone 画出来——这是人格概念上状态条的**唯一**出口。
+   */
+  chips?: StatusChip[] | null;
+  eventCount?: number | null;
+  /** 部署目录里还挂着开场引导的标记。 */
+  onboardingPending?: boolean;
+  terminalOnline?: number | null;
+  context?: ContextBudget | null;
+  [key: string]: unknown;
+}
+
+export function loopOf(st: StatusSnapshot | null): LoopStatus {
+  return st?.loop ?? {};
+}
+
+/** 上下文预算:`status.loop.context`(core)与 `status.context`(Persona)合成,后者的键覆盖前者。 */
+export function contextOf(st: StatusSnapshot | null): ContextBudget {
+  if (!st) return {};
+  const inLoop = loopOf(st).context;
+  const own = st.context;
+  return {
+    ...(inLoop && typeof inLoop === 'object' ? inLoop : {}),
+    ...(own && typeof own === 'object' ? own : {}),
+  };
+}
+
+/** 一个字符串字段,不是字符串就当没有。 */
+export function str(v: unknown): string {
+  return typeof v === 'string' ? v : '';
+}
+
+/** 一个数组字段,不是数组就当空。 */
+export function arr<T>(v: unknown): T[] {
+  return Array.isArray(v) ? (v as T[]) : [];
+}
+
+/** Persona自报的状态筹码;形状不对的条目丢掉,坏数据不该让状态条整条消失。 */
+export function chipsOf(st: StatusSnapshot | null): StatusChip[] {
+  return arr<unknown>(st?.chips).flatMap((c) => {
+    if (!c || typeof c !== 'object') return [];
+    const { label, tone } = c as { label?: unknown; tone?: unknown };
+    if (typeof label !== 'string' || !label) return [];
+    return [{ label, ...(tone === 'warn' || tone === 'accent' ? { tone } : {}) }];
+  });
+}

package/src/web/client/features/live/sessions.ts

@@ -0,0 +1,71 @@
+/**
+ * session 卡条 —— 终端页顶上那一排"主意识 + 各 fork"。
+ *
+ * 一张卡就是一个可点的入口:点谁,时间线就切去看谁。数据来自 `/ws/debug` 的
+ * `sessions` 帧;调试通道没挂时由 `/ws/sessions` 顶上(见 `index.ts`)。
+ *
+ * 卡面上的 `r-<role>` 是**服务端给的角色字符串**,不是前端认识的名单——各角色的
+ * 圆点配色写在 `styles.css` 里,前端这边一个角色名都不写死。
+ */
+
+import type { ConsoleUi } from '../../../shared/client-panel.ts';
+import type { SessionStat } from './protocol.ts';
+import { S } from './strings.ts';
+
+export interface SessionBandDeps {
+  ui: ConsoleUi;
+  /**
+   * 本次挂载的 signal，统一管理卡片监听，unmount 后解除。
+   */
+  signal: AbortSignal;
+  /** 点了某张卡。切不切、怎么切由调用方决定。 */
+  onPick(id: string, label: string): void;
+}
+
+export interface SessionBand {
+  el: HTMLElement;
+  /** 重画。`currentId` 决定哪张卡带选中框。 */
+  render(sessions: readonly SessionStat[], currentId: string): void;
+}
+
+export function createSessionBand(deps: SessionBandDeps): SessionBand {
+  const { ui } = deps;
+  const el = ui.h('div', 'sesscards');
+  el.title = S.sessionBandTitle;
+
+  return {
+    el,
+    render(sessions, currentId) {
+      while (el.children.length) el.children[0].remove();
+      for (const s of sessions) {
+        const running = s.endedAt == null;
+        const cls = [
+          'sesscard',
+          running ? 'running' : '',
+          `r-${s.role}`,
+          s.id === currentId ? 'sel' : '',
+        ]
+          .filter((c) => c !== '')
+          .join(' ');
+        const card = ui.h('span', cls);
+        card.appendChild(ui.h('span', 'sdot'));
+        const info = ui.h('span');
+        info.appendChild(ui.h('b', null, s.label));
+        info.appendChild(ui.h('span', null, ` ↑${ui.fmt.count(s.promptTokens)} `));
+        info.appendChild(ui.h('span', 'shr', S.sessionCache(ui.fmt.percent(s.cacheHitRate))));
+        card.appendChild(info);
+        card.title = S.sessionCardTitle(
+          s.label,
+          s.id,
+          running,
+          running ? '' : ui.fmt.clock(s.endedAt),
+          s.promptTokens,
+          s.completionTokens,
+          s.cacheHitTokens,
+        );
+        card.addEventListener('click', () => deps.onPick(s.id, s.label), { signal: deps.signal });
+        el.appendChild(card);
+      }
+    },
+  };
+}