@brainpilot/web 0.0.4 → 0.0.6

package/src/contexts/newUiEvents.ts

@@ -0,0 +1,190 @@
+import type {
+  AskUserView,
+  AutoRetryView,
+  ChatMessage,
+  SystemMessageView,
+  WebSocketEvent,
+} from "../contracts/backend";
+import { generateUUID } from "./messageReducer";
+
+/**
+ * 修正6 — event → view-model mapping for the three new UI features
+ * (system_message bubble, ask_user card, auto-retry countdown).
+ *
+ * Kept as pure functions (no React, no DOM) so the mapping is unit-testable in
+ * isolation. The reducer in messageReducer.ts calls these to fold the new
+ * AG-UI events into the ChatMessage stream, consistently with the existing
+ * event handling.
+ *
+ * Events arrive post-`normalizeAgUiEvent`, which camelizes every wire key. So a
+ * wire `request_id` is read here as `requestId`, `allow_free_text` as
+ * `allowFreeText`, etc. We still tolerate the snake_case originals as a
+ * fallback in case an event bypassed normalization.
+ */
+
+function str(value: unknown, fallback = ""): string {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function optStr(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function num(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+/** Map a `system_message` event to its view-model. */
+export function toSystemMessageView(event: WebSocketEvent): SystemMessageView {
+  const e = event as Record<string, unknown>;
+  const rawLevel = str(e.level, "info");
+  const level: SystemMessageView["level"] =
+    rawLevel === "warning" || rawLevel === "error" || rawLevel === "fatal" ? rawLevel : "info";
+  // `recoverable` defaults to false for fatal, true otherwise, when the wire
+  // omits it.
+  const recoverable =
+    typeof e.recoverable === "boolean" ? e.recoverable : level !== "fatal";
+  return {
+    level,
+    message: str(e.message),
+    details: optStr(e.details),
+    agent: optStr(e.agent) ?? optStr(e.agentName),
+    recoverable,
+    timestamp: optStr(e.timestamp),
+  };
+}
+
+/** Map a `user_input_request` event to the ask_user card view-model. */
+export function toAskUserView(event: WebSocketEvent): AskUserView {
+  const e = event as Record<string, unknown>;
+  const options = Array.isArray(e.options)
+    ? (e.options as unknown[]).filter((o): o is string => typeof o === "string")
+    : undefined;
+  return {
+    requestId: str(e.requestId ?? e.request_id),
+    agent: str(e.agent ?? e.agentName, "principal"),
+    question: str(e.question),
+    options: options && options.length > 0 ? options : undefined,
+    allowFreeText:
+      typeof (e.allowFreeText ?? e.allow_free_text) === "boolean"
+        ? (e.allowFreeText ?? e.allow_free_text) as boolean
+        : undefined,
+    timeoutSec: typeof (e.timeoutSec ?? e.timeout_sec) === "number"
+      ? (e.timeoutSec ?? e.timeout_sec) as number
+      : undefined,
+  };
+}
+
+/**
+ * Map an auto-retry indicator to its view-model. Pi's `auto_retry_start`
+ * surfaces as an `agent_status_update` (status `retrying`) carrying
+ * attempt/maxAttempts/delayMs, mirrored by a `system_message`. We read whichever
+ * fields are present, tolerating camel/snake casing.
+ */
+export function toAutoRetryView(event: WebSocketEvent): AutoRetryView {
+  const e = event as Record<string, unknown>;
+  // The retry detail may be nested under `data` / `value` / `autoRetry`.
+  const nested =
+    (e.autoRetry as Record<string, unknown> | undefined) ??
+    (e.data as Record<string, unknown> | undefined) ??
+    (e.value as Record<string, unknown> | undefined) ??
+    e;
+  return {
+    attempt: num(nested.attempt, 1),
+    maxAttempts: num(nested.maxAttempts ?? nested.max_attempts, 1),
+    delayMs: num(nested.delayMs ?? nested.delay_ms, 0),
+    reason: optStr(nested.reason) ?? optStr(e.message),
+  };
+}
+
+/** True iff this `agent_status_update` represents an auto-retry start. */
+export function isAutoRetryStatus(event: WebSocketEvent): boolean {
+  const e = event as Record<string, unknown>;
+  if (e.type !== "agent_status_update") return false;
+  const status = str(e.status ?? (e as { runStatus?: string }).runStatus).toLowerCase();
+  // Pi auto_retry_start surfaces with a retrying/auto_retry status marker, or an
+  // explicit autoRetry payload.
+  if (status === "retrying" || status === "auto_retry" || status === "auto_retry_start") {
+    return true;
+  }
+  return Boolean(e.autoRetry ?? e.auto_retry);
+}
+
+/** Build the `system_message` ChatMessage. */
+export function systemMessageToChatMessage(event: WebSocketEvent): ChatMessage {
+  const view = toSystemMessageView(event);
+  const e = event as Record<string, unknown>;
+  return {
+    id: str(e.id ?? e.messageId) || `sysmsg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    role: "system",
+    content: view.message,
+    createdAt: view.timestamp ?? new Date().toISOString(),
+    agent: view.agent,
+    streaming: false,
+    kind: "system_message",
+    systemMessage: view,
+  };
+}
+
+/** Build the `ask_user` ChatMessage. Keyed by requestId so it can be resolved. */
+export function askUserToChatMessage(event: WebSocketEvent): ChatMessage {
+  const view = toAskUserView(event);
+  return {
+    id: view.requestId ? `ask-${view.requestId}` : generateUUID(),
+    role: "system",
+    content: view.question,
+    createdAt: new Date().toISOString(),
+    agent: view.agent,
+    streaming: false,
+    kind: "ask_user",
+    askUser: view,
+  };
+}
+
+/** Build the `auto_retry` ChatMessage from an auto-retry status update. */
+export function autoRetryToChatMessage(event: WebSocketEvent): ChatMessage {
+  const view = toAutoRetryView(event);
+  const e = event as Record<string, unknown>;
+  return {
+    id: `retry-${str(e.agentName, "agent")}-${view.attempt}-${Date.now()}`,
+    role: "system",
+    content: view.reason ?? `Retrying (attempt ${view.attempt}/${view.maxAttempts})`,
+    createdAt: new Date().toISOString(),
+    agent: optStr(e.agentName),
+    streaming: false,
+    kind: "auto_retry",
+    autoRetry: view,
+  };
+}
+
+// ── Pure interaction helpers (shared by the components; testable w/o a DOM) ──
+
+/**
+ * Resolve an ask_user submission. Returns the `{ requestId, answer }` to send,
+ * or `null` when the input is empty or the card is no longer accepting input
+ * (already answered / timed out). The trimmed answer is what gets sent.
+ */
+export function resolveAskUserSubmission(
+  view: AskUserView,
+  rawAnswer: string,
+  opts: { answered?: boolean; timedOut?: boolean } = {},
+): { requestId: string; answer: string } | null {
+  if (opts.answered || opts.timedOut) return null;
+  const answer = rawAnswer.trim();
+  if (!answer || !view.requestId) return null;
+  return { requestId: view.requestId, answer };
+}
+
+/** Whether an ask_user card should still show interactive inputs. */
+export function isAskUserOpen(
+  view: AskUserView,
+  opts: { timedOut?: boolean } = {},
+): boolean {
+  return view.answer === undefined && !opts.timedOut;
+}
+
+/** Initial countdown (whole seconds) for an auto-retry from its delayMs. */
+export function autoRetryCountdownSeconds(view: AutoRetryView): number {
+  return view.delayMs > 0 ? Math.ceil(view.delayMs / 1000) : 0;
+}
+

package/src/contexts/runningToast.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure helper for the "X 正在工作 / X is working" toast above the composer (#76).
+ *
+ * Selects which i18n key + vars the toast should render given the set of agents
+ * currently working. Kept pure (no React) so it's unit-testable without a DOM —
+ * the component just calls `t(key, vars)` with the result. The trace agent is
+ * excluded by the caller (it self-records continuously and isn't "the user's
+ * task"), matching the runtime's run-active aggregation.
+ */
+export interface ToastLabel {
+  key: "chat.agentWorking" | "chat.agentsWorking" | "chat.agentThinking";
+  /** Interpolation vars; shape matches i18n `TranslateVars` (string|number). */
+  vars?: Record<string, string>;
+}
+
+/**
+ * @param workingAgentNames names of non-trace agents with status "running"
+ * @param separator locale-appropriate join for multiple names (default "、")
+ */
+export function runningToastLabel(
+  workingAgentNames: readonly string[],
+  separator = "、",
+): ToastLabel {
+  if (workingAgentNames.length === 1) {
+    return { key: "chat.agentWorking", vars: { name: workingAgentNames[0]! } };
+  }
+  if (workingAgentNames.length > 1) {
+    return { key: "chat.agentsWorking", vars: { names: workingAgentNames.join(separator) } };
+  }
+  // Streaming but no named running agent yet (status not yet "running"): keep the
+  // generic label so the toast never renders blank.
+  return { key: "chat.agentThinking" };
+}

package/src/contexts/traceReducer.ts

@@ -0,0 +1,62 @@
+import { CUSTOM_EVENT } from "@brainpilot/protocol";
+import type { TraceGraph, TraceNode, WebSocketEvent } from "../contracts/backend";
+import { normalizeTraceNode } from "../contracts/backend";
+
+/**
+ * #79: merge a single `CUSTOM:trace_node` event into the live Graph of Trace.
+ *
+ * The runtime emits `CUSTOM { name:"trace_node", value:{ op, node } }` on every
+ * trace mutation (LLM `record_trace`/`create_trace_*` and the deterministic
+ * post-turn hook). This keeps the Trace panel live without polling the whole
+ * graph every few seconds.
+ *
+ * Merge rules:
+ *  - a non-`trace_node` event returns the same graph reference (no-op);
+ *  - an unparseable / id-less payload is ignored (same reference);
+ *  - a node id already present is replaced in place (status/summary updates);
+ *  - a new node id is appended;
+ *  - `childIds` are recomputed from every node's `parentIds` so edges stay
+ *    consistent regardless of arrival order (a child can arrive before its
+ *    parent's childIds is known).
+ */
+export function reduceTraceForEvent(
+  graph: TraceGraph | null,
+  event: WebSocketEvent,
+  sessionId: string,
+): TraceGraph | null {
+  const e = event as Record<string, unknown>;
+  if (e.type !== "CUSTOM" || e.name !== CUSTOM_EVENT.TRACE_NODE) return graph;
+  const value = (e.value ?? {}) as Record<string, unknown>;
+  const rawNode = value.node;
+  if (!rawNode || typeof rawNode !== "object") return graph;
+  const node = normalizeTraceNode(rawNode);
+  if (!node.id) return graph;
+
+  const base: TraceGraph = graph ?? {
+    meta: { sessionId },
+    nodes: [],
+  };
+  const idx = base.nodes.findIndex((n) => n.id === node.id);
+  const nextNodes =
+    idx >= 0
+      ? base.nodes.map((n, i) => (i === idx ? node : n))
+      : [...base.nodes, node];
+
+  return { meta: base.meta, nodes: withChildIds(nextNodes) };
+}
+
+/** Recompute every node's `childIds` from the parent links across the set. */
+function withChildIds(nodes: TraceNode[]): TraceNode[] {
+  const childrenByParent = new Map<string, Set<string>>();
+  for (const n of nodes) {
+    for (const pid of n.parentIds) {
+      const set = childrenByParent.get(pid) ?? new Set<string>();
+      set.add(n.id);
+      childrenByParent.set(pid, set);
+    }
+  }
+  return nodes.map((n) => ({
+    ...n,
+    childIds: Array.from(childrenByParent.get(n.id) ?? []),
+  }));
+}

package/src/contexts/turnTimer.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "vitest";
+import {
+  turnTimerReducer,
+  initialTurnTimerState,
+  type TurnTimerState,
+} from "./turnTimer";
+
+/** Apply a sequence of events from the initial state. */
+function run(events: Parameters<typeof turnTimerReducer>[1][]): TurnTimerState {
+  return events.reduce(turnTimerReducer, initialTurnTimerState);
+}
+
+describe("turnTimerReducer (#99 whole-turn timing)", () => {
+  it("times a simple turn: user input → active true → active false → settle", () => {
+    const s = run([
+      { type: "userInput", atMs: 1000 },
+      { type: "active", value: true, atMs: 1010 },
+      { type: "active", value: false, atMs: 4200 },
+      { type: "settle" },
+    ]);
+    expect(s.running).toBe(false);
+    // Duration spans user input (1000) → terminal active=false (4200) = 3.2s.
+    expect(s.lastDurationMs).toBe(3200);
+    expect(s.startedAt).toBeNull();
+    expect(s.candidateEndAt).toBeNull();
+  });
+
+  it("does NOT end the turn on a mid-flap false that is re-woken before settle", () => {
+    let s = run([
+      { type: "userInput", atMs: 1000 },
+      { type: "active", value: true, atMs: 1010 },
+      // Principal turn ends momentarily...
+      { type: "active", value: false, atMs: 2000 },
+    ]);
+    expect(s.running).toBe(true); // still running (candidate pending, not settled)
+    expect(s.candidateEndAt).toBe(2000);
+
+    // ...but a hook / mailbox delivery re-wakes an agent before settle fires.
+    s = turnTimerReducer(s, { type: "active", value: true, atMs: 2050 });
+    expect(s.candidateEndAt).toBeNull(); // candidate discarded
+    expect(s.running).toBe(true);
+    expect(s.startedAt).toBe(1000); // original start preserved
+
+    // Real end later.
+    s = turnTimerReducer(s, { type: "active", value: false, atMs: 5000 });
+    s = turnTimerReducer(s, { type: "settle" });
+    expect(s.lastDurationMs).toBe(4000); // 1000 → 5000, the re-wake didn't reset it
+  });
+
+  it("uses the candidate-end timestamp, not the settle time, for the duration", () => {
+    // settle is dispatched 'later' but the committed duration must reflect the
+    // authoritative active=false timestamp (the settle window is not counted).
+    const s = run([
+      { type: "userInput", atMs: 0 },
+      { type: "active", value: true, atMs: 5 },
+      { type: "active", value: false, atMs: 1000 },
+      { type: "settle" }, // wall-clock-wise this happens ~800ms later, irrelevant
+    ]);
+    expect(s.lastDurationMs).toBe(1000);
+  });
+
+  it("seeds startedAt from active=true if the user-input open was missed (reconnect)", () => {
+    const s = run([
+      { type: "active", value: true, atMs: 3000 },
+      { type: "active", value: false, atMs: 3500 },
+      { type: "settle" },
+    ]);
+    expect(s.lastDurationMs).toBe(500);
+  });
+
+  it("ignores active=false when no turn is running", () => {
+    const s = run([{ type: "active", value: false, atMs: 100 }]);
+    expect(s).toEqual(initialTurnTimerState);
+  });
+
+  it("preserves the original start when a second userInput arrives mid-turn", () => {
+    const s = run([
+      { type: "userInput", atMs: 1000 },
+      { type: "active", value: true, atMs: 1010 },
+      { type: "userInput", atMs: 1500 }, // steering / follow-up during the run
+    ]);
+    expect(s.startedAt).toBe(1000);
+    expect(s.running).toBe(true);
+  });
+
+  it("keeps lastDurationMs across a reset of the active turn but reset() clears all", () => {
+    let s = run([
+      { type: "userInput", atMs: 0 },
+      { type: "active", value: true, atMs: 1 },
+      { type: "active", value: false, atMs: 2000 },
+      { type: "settle" },
+    ]);
+    expect(s.lastDurationMs).toBe(2000);
+    s = turnTimerReducer(s, { type: "reset" });
+    expect(s).toEqual(initialTurnTimerState);
+  });
+});

package/src/contexts/turnTimer.ts

@@ -0,0 +1,108 @@
+/**
+ * turnTimer — derive a "whole-turn" wall-clock duration for the Chat footer
+ * ("本轮对话用时"), issue #99.
+ *
+ * A turn is NOT a single assistant message. It spans from the user's input
+ * until every agent (principal + delegated experts + delivery loops) has
+ * finished — i.e. the authoritative `runState.active` flag (derived by the
+ * runtime, trace agent excluded) goes false and STAYS false.
+ *
+ * The subtlety (#99): `runState.active` can briefly flip true→false→true when a
+ * turn ends and a hook / system message / queued mailbox delivery immediately
+ * re-wakes an agent. That mid-flap `false` is NOT the end of the turn. So we
+ * debounce the terminal transition with a settle window: a false only counts as
+ * the turn's end once it has held for `settleMs`. If `active` goes true again
+ * inside the window, the candidate end is discarded and the same turn continues.
+ *
+ * This reducer is pure and driven entirely by authoritative backend signals
+ * (`runState.active` + the event's ISO timestamp). The host attaches the settle
+ * timer and a live "ticking" clock for the running display.
+ */
+
+export interface TurnTimerState {
+  /** ms epoch when the current turn started (user input / first active=true). */
+  startedAt: number | null;
+  /** Whether a turn is currently in progress (active, or within settle window). */
+  running: boolean;
+  /** Pending terminal end: active went false, awaiting settle confirmation. */
+  candidateEndAt: number | null;
+  /** The last settled whole-turn duration in ms, or null if none yet. */
+  lastDurationMs: number | null;
+}
+
+export const initialTurnTimerState: TurnTimerState = {
+  startedAt: null,
+  running: false,
+  candidateEndAt: null,
+  lastDurationMs: null,
+};
+
+export type TurnTimerEvent =
+  /** Authoritative runState.active snapshot at time `atMs` (from session_state). */
+  | { type: "active"; value: boolean; atMs: number }
+  /** The settle window elapsed with active still false → commit the turn end. */
+  | { type: "settle" }
+  /** A fresh user submission opens a new turn at `atMs` (optimistic start). */
+  | { type: "userInput"; atMs: number }
+  /** Session switch / reset — clear all timing. */
+  | { type: "reset" };
+
+/**
+ * Advance the turn-timer state machine. Pure: returns the next state. The host
+ * is responsible for (re)arming the settle timer whenever `candidateEndAt`
+ * becomes non-null, and dispatching `{type:"settle"}` after `settleMs`.
+ */
+export function turnTimerReducer(state: TurnTimerState, event: TurnTimerEvent): TurnTimerState {
+  switch (event.type) {
+    case "reset":
+      return initialTurnTimerState;
+
+    case "userInput": {
+      // Opening (or continuing) a turn from the user side. If a turn is already
+      // running, keep its original start; otherwise begin a new one. Clears any
+      // stale candidate end.
+      if (state.running && state.startedAt !== null) {
+        return { ...state, candidateEndAt: null };
+      }
+      return {
+        startedAt: event.atMs,
+        running: true,
+        candidateEndAt: null,
+        lastDurationMs: state.lastDurationMs,
+      };
+    }
+
+    case "active": {
+      if (event.value) {
+        // active=true: turn is (still) running. Cancel any pending end. Seed a
+        // start if the user-input optimistic open was missed (e.g. reconnect).
+        return {
+          startedAt: state.startedAt ?? event.atMs,
+          running: true,
+          candidateEndAt: null,
+          lastDurationMs: state.lastDurationMs,
+        };
+      }
+      // active=false: candidate terminal transition. Only meaningful if a turn
+      // is in progress. Record the candidate end; the host arms the settle
+      // timer. A re-wake (active=true) before settle discards this.
+      if (!state.running || state.startedAt === null) return state;
+      return { ...state, candidateEndAt: event.atMs };
+    }
+
+    case "settle": {
+      // Settle window held with active false → commit the whole-turn duration.
+      if (state.candidateEndAt === null || state.startedAt === null) return state;
+      const duration = Math.max(0, state.candidateEndAt - state.startedAt);
+      return {
+        startedAt: null,
+        running: false,
+        candidateEndAt: null,
+        lastDurationMs: duration,
+      };
+    }
+
+    default:
+      return state;
+  }
+}

package/src/contexts/useTurnTimer.ts

@@ -0,0 +1,104 @@
+/**
+ * useTurnTimer — React host for the whole-turn timer reducer (#99).
+ *
+ * Consumes the authoritative `runActive` signal from SessionContext
+ * (session_state.runState.active + backend timestamp) and produces:
+ *   - `running`: a turn is in progress (active, or within the settle window);
+ *   - `elapsedMs`: live elapsed while running (ticks ~every second), or the
+ *     last settled whole-turn duration once finished;
+ *   - `lastDurationMs`: the last settled whole-turn duration.
+ *
+ * The settle window debounces the true→false→true flap that happens when a hook
+ * / system message / queued mailbox delivery re-wakes an agent right after a
+ * turn momentarily ends — that mid-flap false must NOT end the turn.
+ */
+import { useEffect, useReducer, useRef, useState } from "react";
+import {
+  turnTimerReducer,
+  initialTurnTimerState,
+  type TurnTimerState,
+} from "./turnTimer";
+
+/** Default debounce for the terminal active=false transition. */
+export const DEFAULT_SETTLE_MS = 900;
+
+export interface TurnTiming {
+  running: boolean;
+  /** Live elapsed while running; the settled duration once finished; null if none. */
+  elapsedMs: number | null;
+  lastDurationMs: number | null;
+}
+
+interface UseTurnTimerOptions {
+  /** Backend run-active snapshot; null until the first session_state arrives. */
+  runActive: { active: boolean; atMs: number } | null;
+  /** Key that resets the timer when it changes (e.g. session id). */
+  resetKey?: string | null;
+  settleMs?: number;
+  /** Test seam: clock source (defaults to Date.now). */
+  now?: () => number;
+}
+
+export function useTurnTimer(options: UseTurnTimerOptions): TurnTiming {
+  const { runActive, resetKey, settleMs = DEFAULT_SETTLE_MS, now = Date.now } = options;
+  const [state, dispatch] = useReducer(turnTimerReducer, initialTurnTimerState);
+  const settleRef = useRef<number | undefined>(undefined);
+  const [, forceTick] = useState(0);
+
+  // Reset when the session changes.
+  useEffect(() => {
+    dispatch({ type: "reset" });
+  }, [resetKey]);
+
+  // Feed authoritative active transitions into the reducer.
+  useEffect(() => {
+    if (!runActive) return;
+    dispatch({ type: "active", value: runActive.active, atMs: runActive.atMs });
+  }, [runActive]);
+
+  // Arm/disarm the settle timer based on a pending candidate end.
+  const hasCandidate = state.candidateEndAt !== null;
+  useEffect(() => {
+    if (!hasCandidate) {
+      if (settleRef.current !== undefined) {
+        window.clearTimeout(settleRef.current);
+        settleRef.current = undefined;
+      }
+      return;
+    }
+    settleRef.current = window.setTimeout(() => {
+      settleRef.current = undefined;
+      dispatch({ type: "settle" });
+    }, settleMs);
+    return () => {
+      if (settleRef.current !== undefined) {
+        window.clearTimeout(settleRef.current);
+        settleRef.current = undefined;
+      }
+    };
+  }, [hasCandidate, settleMs]);
+
+  // Tick once per second while running so the live elapsed advances.
+  useEffect(() => {
+    if (!state.running) return;
+    const id = window.setInterval(() => forceTick((n) => n + 1), 1000);
+    return () => window.clearInterval(id);
+  }, [state.running]);
+
+  return deriveTiming(state, now);
+}
+
+function deriveTiming(state: TurnTimerState, now: () => number): TurnTiming {
+  if (state.running && state.startedAt !== null) {
+    return {
+      running: true,
+      elapsedMs: Math.max(0, now() - state.startedAt),
+      lastDurationMs: state.lastDurationMs,
+    };
+  }
+  return {
+    running: false,
+    elapsedMs: state.lastDurationMs,
+    lastDurationMs: state.lastDurationMs,
+  };
+}