@spzxg/cli-ui 0.6.2 → 0.6.5

package/src/operator/node/protocol/customModels.ts

@@ -0,0 +1,23 @@
+import type { AgentModelOption } from "./agents/types";
+
+export function validModelId(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0 && value.trim().length <= 2048 && !/[\0-\x1f\x7f]/.test(value);
+}
+
+export function savedCustomModels(raw: string | null | undefined): string[] {
+  try {
+    const values: unknown = JSON.parse(raw || "[]");
+    return Array.isArray(values) ? [...new Set(values.filter(validModelId).map(value => value.trim()))] : [];
+  } catch {
+    return [];
+  }
+}
+
+export function withCustomModels(models: AgentModelOption[], names: string[]): AgentModelOption[] {
+  const known = new Set(models.map(model => model.value));
+  return [...models, ...names.filter(name => !known.has(name)).map(name => ({
+    value: name, label: name, sub: "自定义模型", group: "自定义",
+    // Match the existing conservative fallback for provider-native model IDs.
+    contextWindow: /\[1m\]|claude-sonnet-5|claude-fable-5/i.test(name) ? 1_000_000 : 200_000,
+  }))];
+}

package/src/operator/node/protocol/events.ts

@@ -0,0 +1,13 @@
+import type { AgentAuthEvent, GlobalTaskEvent } from "./types";
+export type GlobalTaskWireEvent = Omit<GlobalTaskEvent, "event"> & {
+  event: GlobalTaskEvent["event"] | "task_created" | "task_updated";
+};
+export type TaskDeletedWireEvent = {
+  type: "task_deleted";
+  taskId: string;
+  projectId: string;
+  /** The project's awaiting count recomputed AFTER the row was deleted. */
+  awaiting_count: number;
+};
+export type GlobalWireEvent = GlobalTaskWireEvent | TaskDeletedWireEvent | AgentAuthEvent;
+

package/src/operator/node/protocol/features.ts

@@ -0,0 +1,70 @@
+declare const process: { env: Record<string, string | undefined> };
+/**
+ * Instance-level feature flags.
+ *
+ * In-progress features default OFF and are turned on per-instance via env, the
+ * same env-driven philosophy as lib/config.ts. Flags are resolved server-side
+ * (`resolveFeatures`) and handed to the client by injecting `window.__FEATURES`
+ * in app/layout.tsx — mirroring how PUBLIC_BASE_URL crosses the boundary — so
+ * both sides gate identically without a per-flag NEXT_PUBLIC_ var.
+ *
+ * To add a flag: extend `Features` + `DEFAULT_FEATURES`, read its env var in
+ * `resolveFeatures`, document it in .env.example, and gate the UI on
+ * `clientFeatures().<flag>` (client) or `resolveFeatures().<flag>` (server).
+ */
+export interface Features {
+  /** PREVIEW tab (project live-URL view). WIP — depends on the remote-execution
+   *  backend landing first, so it stays off until the live URL is real. */
+  livePreview: boolean;
+  /** Command palette: the toolbar "Jump to project, session, or command…"
+   *  omni-search bar and its ⌘K/Ctrl-K shortcut (app/orchestrator/CommandPalette). */
+  omniSearch: boolean;
+  /** Managed Services — the toolbar "Services" button, the Services config
+   *  block in the project-context editor, and the persisted supervisor
+   *  (lib/services.ts). Shipped: ON by default; set ORCH_FEATURE_SERVICES=0 to
+   *  disable. NOTE: public service hostnames are NOT part of this flag — they
+   *  stay opt-in via ORCH_SERVICE_HOSTS (lib/service-host.mjs), so enabling
+   *  services exposes nothing publicly. */
+  services: boolean;
+  /** Per-task real browser (docs/BROWSER_PLAN.md): Operator runs one ego lite
+   *  instance per node with one task space per task, agents drive it with
+   *  ego-browser scripts, and the session rail streams it. WIP — default OFF
+   *  (ORCH_FEATURE_BROWSER=1). With the flag off nothing is injected into any
+   *  agent and no route is active. */
+  browser: boolean;
+}
+
+export const DEFAULT_FEATURES: Features = {
+  livePreview: false,
+  omniSearch: false,
+  services: true,
+  browser: false,
+};
+
+const truthy = (v: string | undefined) => v === "1" || v === "true" || v === "on";
+// Unset/empty env keeps the flag's shipped default; any explicit value decides.
+// A shipped flag (default ON) is therefore disabled with =0, not by omission.
+// lib/service-router.mjs (plain JS, can't import this file) mirrors this read.
+const flag = (v: string | undefined, dflt: boolean) => (v ? truthy(v) : dflt);
+
+/** Server-side resolve from env. Never call this from client code (reads env). */
+export function resolveFeatures(): Features {
+  return {
+    livePreview: flag(process.env.ORCH_FEATURE_LIVE_PREVIEW, DEFAULT_FEATURES.livePreview),
+    omniSearch: flag(process.env.ORCH_FEATURE_OMNI_SEARCH, DEFAULT_FEATURES.omniSearch),
+    services: flag(process.env.ORCH_FEATURE_SERVICES, DEFAULT_FEATURES.services),
+    browser: flag(process.env.ORCH_FEATURE_BROWSER, DEFAULT_FEATURES.browser),
+  };
+}
+
+/** Client-side read of the flags injected onto `window` by the root layout. */
+export function clientFeatures(): Features {
+  // SSR of a client component has no `window` yet. Resolve from env — the same
+  // values layout.tsx injects as window.__FEATURES — so the server HTML and the
+  // client's first render agree (returning DEFAULT_FEATURES here made every
+  // enabled flag a hydration mismatch, e.g. the ⌘K omni button). In the browser
+  // this branch never runs, so the process.env reads never execute client-side.
+  if (typeof window === "undefined") return resolveFeatures();
+  const w = window as unknown as { __FEATURES?: Partial<Features> };
+  return { ...DEFAULT_FEATURES, ...(w.__FEATURES ?? {}) };
+}

package/src/operator/node/protocol/internalUsage.ts

@@ -0,0 +1 @@
+export type InternalUsageEstimate = { tokens: number; cost_usd: number; source: "project_latest" | "instance_median" | "scaled_history" };

package/src/operator/node/protocol/promptLimits.ts

@@ -0,0 +1,52 @@
+// Guards + recovery constants for the "Prompt is too long" failure mode.
+//
+// A giant paste used to permanently poison a task: the SDK reports the API's
+// "prompt is too long" error as a soft stream error AFTER the session has
+// already opened, so lib/runner.ts persists the session id anyway and every
+// later message resumes the same over-limit session — the error repeats
+// forever. These shared limits let the composer defuse big pastes up front
+// (attach as a file instead of inlining), the messages route reject anything
+// that slips through, and the runner recognize the error to surface a
+// one-click recovery. Kept dependency-free so both server and client bundles
+// can import it.
+
+/** Client: a text paste larger than this becomes a `.txt` attachment instead
+ *  of being inlined into the message (see app/orchestrator/Composer.tsx). */
+export const PASTE_ATTACH_THRESHOLD = 100_000; // ~100 KB
+
+/** Server: hard cap on a single message's characters (POST /messages). Big
+ *  content should ride as an attachment, whose bytes never enter the prompt. */
+export const MAX_MESSAGE_CHARS = 262_144; // 256 KB
+
+// Each provider phrases a context-window overflow differently, and the recovery
+// flow ("Start fresh context") is agent-agnostic, so we match every driver's
+// signature here:
+//   - Anthropic (Claude driver): "prompt is too long: N tokens > M maximum".
+//   - OpenAI/Codex (Codex driver): the API returns "context_length_exceeded"
+//     with a message like "maximum context length is N tokens. However, your
+//     messages resulted in M tokens" / "reduce the length of the messages".
+//     The codex CLI surfaces the same as an "exceeds the context window" / "input
+//     is too long" turn failure. Any of these should trip the same recovery.
+const CONTEXT_OVERFLOW_RES = [
+  /prompt is too long/i,
+  /context[_ ]length[_ ]exceeded/i,
+  /maximum context length/i,
+  /exceeds? the (?:model'?s? )?context (?:window|length|limit)/i,
+  /(?:input|conversation|message)s? (?:is |are )?too long/i,
+  /reduce the length of the messages/i,
+];
+
+/** True when an error/stream message is a provider's context-overflow rejection
+ *  (Anthropic "prompt is too long", OpenAI/Codex "context_length_exceeded", …). */
+export function isPromptTooLong(msg: string | null | undefined): boolean {
+  return !!msg && CONTEXT_OVERFLOW_RES.some((re) => re.test(msg));
+}
+
+/** Appended to the persisted error line when a turn overflows the context
+ *  window. The UI (app/orchestrator/Transcript.tsx) matches this exact string
+ *  to render the "Start fresh context" recovery button. Persisted message
+ *  content is the durable channel — it survives SSE reconnects because the
+ *  snapshot replays messages from SQLite. */
+export const CONTEXT_OVERFLOW_NOTICE =
+  "本次会话的上下文已超出模型上限，无法继续。" +
+  "请开启一个新的上下文窗口以继续 —— 本次会话的摘要会一并带过去。";

package/src/operator/node/protocol/storageRetention.ts

@@ -0,0 +1,13 @@
+// Shared by the storage form and its API; keep this module browser-safe.
+export const DEFAULT_RETENTION_DAYS = 30;
+export const DAY_MS = 86_400_000;
+
+export function validRetentionDays(value: unknown): value is string {
+  if (typeof value !== "string" || !/^\d+$/.test(value)) return false;
+  const days = Number(value);
+  return days >= 1 && Number.isSafeInteger(days * DAY_MS);
+}
+
+export function retentionDays(value: string | null | undefined): number {
+  return validRetentionDays(value) ? Number(value) : DEFAULT_RETENTION_DAYS;
+}

package/src/operator/node/protocol/types.ts

@@ -0,0 +1,332 @@
+interface AgentProfile { base_url: string; token: string; model: string; wire_api?: string | null; api?: string | null; reasoning?: string | null }
+
+export type Priority = "hi" | "med" | "lo";
+export type Status = "not_started" | "in_progress" | "on_hold" | "done" | "cancelled";
+export type MsgRole = "user" | "assistant" | "tool" | "system" | "session_break";
+
+export interface Project {
+  id: string;
+  name: string;
+  icon: string;
+  sub: string; // short tagline, e.g. "notes app"
+  color: string; // accent color for the project glyph
+  context: string; // "what we're building" — description, stack & conventions (single field)
+  building: string; // legacy — kept for back-compat, folded into context
+  conventions: string; // legacy — kept for back-compat, folded into context
+  repo_path: string; // working dir for Claude Code
+  branch: string; // git branch (context only)
+  dev_command: string; // long-running dev server command supervised by lib/services.ts ("" = none)
+  setup_command: string; // optional one-shot setup command (install/migrate/etc.)
+  test_command: string; // optional one-shot test command
+  port: number; // deterministic per-project port, injected as PORT into services + the PTY
+  default_agent: string; // agent driver new tasks in this project run under (lib/agents/registry.ts)
+  send_context: number; // 1 = include the saved project context in new agent sessions (default for new tasks)
+  recap: string; // last LLM "where you left off" recap (auto-generated when idle)
+  recap_at: number; // when the recap was generated (0 = none)
+  recap_covers_at: number; // the project's last-activity ts the recap was based on
+  // Detached "Refresh with AI" job (drafts run in the background; see lib/contextRefresh.ts).
+  refresh_status: "idle" | "running" | "done" | "error";
+  refresh_draft: string; // drafted context awaiting the user's review (when status="done")
+  refresh_error: string; // failure message (when status="error")
+  refresh_started_at: number; // when the current/last job started (ms epoch, 0 = never)
+  position: number; // manual sidebar order (ascending)
+  deprecated: number; // 1 = hidden in the sidebar's "deprecated" area, not built on
+  seeded: number; // 1 = the built-in "Welcome" tutorial project (see lib/db.ts seedIfEmpty)
+  created_at: number;
+}
+
+export interface Task {
+  id: string;
+  parent_task_id?: string | null;
+  fork_commit?: string;
+  fork_source_title?: string;
+  fork_context?: string;
+  fork_group_id?: string;
+  project_id: string;
+  title: string;
+  description: string;
+  priority: Priority;
+  status: Status;
+  suggested: number; // 1 = Claude-proposed, idle in the suggested tray
+  agent: string; // agent driver this task's sessions run under (default "claude"; see lib/agents/)
+  send_context: number; // 1 = include the saved project context in this task's sessions (seeded from projects.send_context)
+  model: string | null; // chosen model alias ("fable"|"opus"|"sonnet"|"haiku"); null = inherit default
+  resolved_model: string | null; // model the SDK actually ran last turn (for the badge)
+  reasoning: string | null; // thinking preset ("off"|"think"|"think_hard"|"ultrathink"); null = inherit default
+  permission_mode: string | null; // run permission ("acceptEdits"|"plan"); null = bypassPermissions (default)
+  session_id: string | null; // the agent's opaque session/thread id for the current generation
+  worktree_path: string; // isolated git worktree this task runs in ("" = runs in repo_path)
+  work_branch: string; // the worktree's branch (e.g. "orch/<id>")
+  base_sha: string; // commit the worktree branched from — the stable diff/merge base
+  merged_at: number; // when this task's branch was merged back (0 = not merged)
+  pr_url: string; // GitHub PR opened from this task's branch via "Create PR" ("" = none)
+  generation: number; // increments on each /clear
+  position: number; // manual order within the project (list groups + board columns, ascending)
+  started: number; // 1 once the initial prompt has been sent
+  auto_start: number; // 1 = start automatically when the last unfinished blocker is marked done (lib/autoStart.ts)
+  running: number; // 1 while a Claude turn is actively streaming
+  awaiting_input: number; // 1 when it's your turn: Claude's turn ended mid-task, or it's parked on an AskUserQuestion
+  created_at: number;
+  updated_at: number;
+  // Not a column: the runner attaches the CLITaskCenter-supplied model account for
+  // the agent this turn runs on (lib/agentProfile.ts). Absent/null = the CLI uses
+  // this machine's own configuration.
+  agent_profile?: AgentProfile | null;
+  // Per-launch contract, never a task column. Durable run records live in the
+  // managed project's .workspace directory; queued UI turns get their own ID.
+  workspace_request?: { run_id?: string; input?: unknown; [key: string]: unknown };
+}
+
+export interface Message {
+  id: string;
+  task_id: string;
+  generation: number;
+  role: MsgRole;
+  content: string;
+  created_at: number;
+}
+
+export interface Summary {
+  id: string;
+  task_id: string;
+  generation: number;
+  summary: string;
+  created_at: number;
+}
+
+// A follow-up the user typed while a turn was still running. Parked in the
+// pending_messages table (FIFO per task) and shown as "queued" in the
+// transcript; the runner dequeues the oldest one as the next turn when the
+// current turn ends. Distinct from `messages` (the committed transcript).
+export interface PendingMessage {
+  id: string;
+  task_id: string;
+  generation: number;
+  content: string;
+  created_at: number;
+}
+
+export interface Session {
+  id: string;
+  project_id: string;
+  task_id: string;
+  generation: number;
+  // The agent's own opaque session/thread id (named for the first driver; any
+  // driver's id — e.g. a Codex thread id — lands in this same column).
+  claude_session_id: string | null;
+  started_at: number;
+  ended_at: number | null;
+}
+
+// ---------- managed services (lib/services.ts) ----------
+
+// A supervised process belonging to a project. `kind` is the configured slot the
+// service maps to ("dev"/"setup"/"test"), or "exposed" for a server Claude
+// registered at runtime via the expose_service MCP tool (we don't own that
+// process, we only track its url). The orchestrator can start/stop/restart the
+// configured kinds; an exposed entry is informational (its url is reportable).
+export type ServiceStatus = "stopped" | "starting" | "running" | "exited" | "errored";
+export type ServiceKind = "dev" | "setup" | "test" | "exposed";
+// Who can open a service's public URL: private = the instance's own session
+// auth, shared = anyone holding the tokened link (?t=…), public = anyone.
+export type ServiceVisibility = "private" | "shared" | "public";
+
+export interface ServiceInfo {
+  projectId: string;
+  name: string; // unique per project — the kind for configured services, or Claude's chosen name
+  kind: ServiceKind;
+  command: string; // the shell command (empty for an exposed, externally-started service)
+  status: ServiceStatus;
+  pid: number | null;
+  exitCode: number | null;
+  port: number; // the port injected as PORT (configured) or reported by expose_service
+  url: string | null; // browseable URL once running/exposed
+  startedAt: number | null;
+  managed: boolean; // true if the orchestrator owns the process (can stop/restart)
+  slug: string | null; // public hostname label (<slug>--<host>); null until first persisted
+  visibility: ServiceVisibility;
+  shareUrl: string | null; // tokened link (url?t=…) when visibility is "shared"
+  // Human-readable supervisor-level failure (port already in use, spawn failed).
+  // Distinct from a nonzero exit, which the logs explain; cleared on next start.
+  error: string | null;
+}
+
+// One captured line of a service's combined stdout/stderr.
+export interface ServiceLogLine {
+  ts: number;
+  stream: "stdout" | "stderr" | "system"; // "system" = supervisor notice (started/exited)
+  text: string;
+}
+
+// Live events on a project's services SSE stream (GET .../services/stream).
+export type ServiceEvent =
+  | { type: "snapshot"; services: ServiceInfo[]; logs: Record<string, ServiceLogLine[]> }
+  | { type: "status"; service: ServiceInfo }
+  | { type: "log"; name: string; line: ServiceLogLine }
+  | { type: "removed"; name: string };
+
+// A multiple-choice question Claude raised via the AskUserQuestion tool.
+export interface AskOption {
+  label: string;
+  description?: string;
+}
+export interface AskQuestion {
+  question: string;
+  header: string; // short chip label (≤12 chars)
+  multiSelect?: boolean;
+  options: AskOption[];
+}
+// answers[i] = the chosen value(s) for question i — option labels and/or the
+// free-text typed into "Other". One entry per question, in question order.
+export type AskAnswers = string[][];
+
+// browser_ask_user (lib/browserInput.ts): the agent needs something typed or
+// picked in the chat — an SMS / 2FA code, an account, a password, a choice —
+// to carry on in the task's browser. Shown as an input card in the transcript.
+export interface InputField {
+  label: string;
+  /** A password or similar: masked in the card, never stored or shown to the model. */
+  secret?: boolean;
+  /** Pick one of these (the user may still type something else). */
+  options?: string[];
+  placeholder?: string;
+}
+export interface InputRequest {
+  id: string;
+  message: string;
+  fields: InputField[];
+  status: "pending" | "answered" | "cancelled";
+  /** What the transcript keeps once answered: secret fields are masked. */
+  values?: string[];
+}
+
+// Token usage + dollar cost for one Claude turn, parsed from the SDK result
+// message. Persisted per turn (task_usage table) and summed for cumulative spend.
+export interface TurnUsage {
+  cost_usd: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+}
+
+// Cumulative usage totals across one task (or project): summed turn usage plus
+// `total_tokens` (the four token counts combined) and the turn count.
+export interface UsageTotals extends TurnUsage {
+  total_tokens: number;
+  turns: number;
+}
+
+// One rendered diff line: added (+, green), removed (-, red), or unchanged
+// context (" ", dim). Used by both the capped peek and the full expanded diff.
+export type DiffLine = { sign: "+" | "-" | " "; text: string };
+
+// An always-visible "peek" at a tool's effect — mimics Claude Code's `⎿` line.
+// `count`: a one-liner (Read N lines / Found N matches) with no content shown.
+// `diff`: a -/+ hunk for Edits/Writes.  `lines`: a short snippet (Bash output)
+// with a +N-more affordance.  `todos`: a rendered checklist.
+export type ToolPeek =
+  | { kind: "count"; text: string }
+  | { kind: "diff"; added: number; removed: number; label?: string; lines: DiffLine[]; truncated?: number }
+  | { kind: "lines"; label?: string; lines: string[]; truncated?: number }
+  | { kind: "todos"; items: { text: string; status: string }[] };
+
+// Server-sent stream events from a Claude turn.
+export type StreamEvent =
+  | { type: "session"; sessionId: string }
+  | { type: "model"; model: string }
+  | { type: "assistant"; content: string }
+  | { type: "tool"; id: string; title: string; detail: string; peek?: ToolPeek; diff?: DiffLine[] }
+  | { type: "tool_result"; id: string; content: string; isError: boolean; peek?: ToolPeek }
+  | { type: "ask"; id: string; questions: AskQuestion[] }
+  | { type: "ask_answered"; id: string; answers: AskAnswers }
+  // An input card was raised or settled (the whole card each time; upsert by msgId).
+  | { type: "input"; input: InputRequest }
+  | { type: "suggested"; title: string }
+  | { type: "usage"; usage: TurnUsage }
+  | { type: "notice"; content: string } // a quiet, non-error system note (e.g. "caught up to main")
+  | { type: "error"; content: string }
+  | { type: "done"; sessionId: string | null };
+
+// Events as delivered over the task event bus and the GET /messages SSE tail.
+// Turn events are enriched with the persisted DB message id (+ generation) so
+// reconnecting clients can upsert idempotently instead of blindly appending:
+// `msgId` is the row the event created (assistant/tool/ask/notice/error/user)
+// or updated in place (tool_result/ask_answered). `snapshot` opens every
+// stream — the full persisted transcript plus whether a turn is live — and
+// `turn_end` marks the runner's finally block (running flag is off, task row
+// settled), letting clients refresh without owning the turn's lifetime.
+// `queued` is a follow-up parked while a turn runs; `dequeued` removes a parked
+// follow-up from the transcript — either because the runner is now running it
+// as the next turn, or because it was cancelled. `snapshot` carries the parked
+// queue too, so a reload mid-run re-renders the queued bubbles.
+// `ts` mirrors the persisted row's created_at (ms epoch) so a live-tail bubble
+// carries the same clock a reconnect's snapshot row would.
+export type TaskStreamEvent =
+  | (StreamEvent & { msgId?: string; generation?: number; ts?: number })
+  | { type: "user"; content: string; msgId: string; generation: number; ts?: number }
+  | { type: "queued"; msgId: string; content: string; generation: number; ts?: number }
+  | { type: "dequeued"; msgId: string }
+  // `older` is set only when the viewer asked for a tail (?tail=N): how many
+  // earlier messages were left out (fetch them from /api/tasks/:id/history).
+  | { type: "snapshot"; messages: Message[]; pending: PendingMessage[]; running: boolean; older?: number }
+  | AgentAuthEvent
+  | { type: "turn_end" };
+
+// An agent's credentials died (broken=true) or started working again
+// (broken=false). Published by the runner on the failing/succeeding task's
+// channel — but it's really an INSTANCE-wide fact (one login per agent, shared
+// by every task), so GET /api/events relays it verbatim to every tab, where it
+// drives the titlebar reconnect banner. See lib/authFailure.ts.
+export type AgentAuthEvent = {
+  type: "agent_auth";
+  agent: string;
+  broken: boolean;
+  reason: string | null;
+};
+
+// Coarse cross-task lifecycle events on the always-open GET /api/events stream
+// (the wildcard channel of lib/events.ts). One event per turn boundary — turn
+// launched, parked on a question, question answered, suggestion created, turn
+// ended — carrying the task row's settled running/awaiting_input/status (the
+// runner persists before it publishes, so these are authoritative) plus the
+// project's fresh awaiting count. This is what keeps spinners, project badges,
+// and the "N need you" pill live for tasks whose transcript stream isn't open.
+export type GlobalTaskEvent = {
+  type: "task";
+  event: "turn_started" | "awaiting_input" | "ask_answered" | "suggested" | "turn_end";
+  taskId: string;
+  projectId: string;
+  running: boolean;
+  awaiting_input: boolean;
+  status: Status;
+  /** In-progress tasks awaiting the user across this task's project. */
+  awaiting_count: number;
+};
+
+// Everything GET /api/events can send. Task lifecycle is the bulk of it;
+// agent_auth rides the same stream because a dead login affects every task in
+// every project at once, so there's nothing task-shaped to hang it off.
+export type GlobalEvent = GlobalTaskEvent | AgentAuthEvent;
+
+// How a tool call is stored (JSON) in a "tool" message's content.
+export interface ToolData {
+  title: string;
+  detail?: string;
+  result?: string;
+  isError?: boolean;
+  // Always-visible summary/snippet of the call's effect (see ToolPeek). Input-
+  // derived peeks (diff/todos/write) are set with the tool event; result-derived
+  // peeks (read count, bash output) are filled in when the tool_result arrives.
+  peek?: ToolPeek;
+  // Full colored diff for Edit/Write, rendered in the expanded body (the peek
+  // shows a capped slice of the same lines). Absent on older persisted messages,
+  // which fall back to the plaintext `detail`.
+  diff?: DiffLine[];
+  // Present when this "tool" message is an AskUserQuestion prompt. `id` is the
+  // tool_use id (stored here so it survives a reload — there's no DB column for
+  // it). `answers` is absent while awaiting the user, set once answered.
+  ask?: { id: string; questions: AskQuestion[]; answers?: AskAnswers };
+  // Present when this "tool" message is a browser_ask_user input card.
+  input?: InputRequest;
+}

package/src/operator/node/protocol/usageLimit.ts

@@ -0,0 +1,72 @@
+// Detection + recovery constants for the "your subscription's usage limit is
+// spent" failure mode.
+//
+// A subscription limit (Claude's 5-hour window, the weekly cap, an API 429)
+// hits mid-run and looks like a code problem: the raw provider string ("Claude
+// AI usage limit reached|1735689600") lands in ONE task's transcript with no
+// hint that nothing is broken — the quota is simply spent and refills on its
+// own. Worse, without classification the runner would treat it as an ordinary
+// work failure and drain the pending queue: each queued follow-up would
+// dequeue, run straight into the same dead quota, and fail identically,
+// emptying the queue for nothing.
+//
+// So a usage-limit failure is classified here (agent-agnostically — a Codex
+// quota phrases it differently and fails identically), which lets
+// lib/runner.ts append USAGE_LIMIT_NOTICE and park the queue instead of
+// burning it. Unlike the auth twin (lib/authFailure.ts) there is no button to
+// click — the recovery is waiting for the reset — so the notice is purely
+// informational, and the Claude driver enriches the error line with the
+// machine-reported reset time when the SDK provided one. Kept dependency-free
+// so both server and client bundles can import it (same rule as
+// lib/promptLimits.ts).
+
+// Each provider words a spent quota differently, and the recovery ("wait for
+// the reset") is identical for all of them:
+//   - Claude Code (subscription): "Claude AI usage limit reached|<epoch>";
+//     the CLI's display forms "5-hour limit reached ∙ resets 3pm" and
+//     "Weekly limit reached".
+//   - Anthropic API: 429 rate_limit_error ("Number of request tokens has
+//     exceeded your per-minute rate limit", "This request would exceed your
+//     organization's rate limit").
+//   - OpenAI/Codex: "You've hit your usage limit", 429 insufficient_quota
+//     ("You exceeded your current quota").
+// The generic patterns (429, "rate limit", "quota") require a nearby
+// limit/exceeded word so an unrelated error that merely mentions a status
+// code or the word "quota" can't trip the parking behavior.
+const USAGE_LIMIT_RES = [
+  /usage limit reached/i,
+  /\b(?:5|five)[- ]hour limit/i,
+  /\bweekly limit\b/i,
+  /(?:usage|subscription|plan) limit[^.\n]{0,40}(?:reached|exceeded|hit)/i,
+  /(?:reached|exceeded|hit)[^.\n]{0,30}(?:usage|subscription|plan|rate) limit/i,
+  /rate[_ ]limit(?:_error|ed)?[^.\n]{0,40}(?:exceeded|reached|exhausted)/i,
+  /(?:exceed|exceeded|exceeds)[^.\n]{0,40}rate[_ ]limit/i,
+  /(?:exceeded|exhausted)[^.\n]{0,30}(?:your|current|the)[^.\n]{0,20}quota/i,
+  /quota[^.\n]{0,30}(?:exceeded|exhausted|reached)/i,
+  /insufficient[_ ]quota/i,
+  /out of (?:usage|quota|credits)/i,
+  /\b429\b[^\n]{0,60}(?:rate[_ ]limit|quota|usage limit|too many requests)/i,
+  /too many requests[^\n]{0,40}\b429\b/i,
+  /(?:ThrottlingException|TooManyRequestsException)/i,
+  /(?:bedrock|aws)[^.\n]{0,40}(?:service quota|throttl)[^.\n]{0,40}(?:exceed|reached|exception)/i,
+];
+
+/** True when a turn's error text is a spent-quota rejection (Claude's 5-hour /
+ *  weekly subscription limit, an API 429 rate limit) rather than a work
+ *  failure. Checked AFTER isPromptTooLong and isAuthFailure in lib/runner.ts,
+ *  so those classifiers keep first claim on their own signatures. */
+export function isUsageLimit(msg: string | null | undefined): boolean {
+  return !!msg && USAGE_LIMIT_RES.some((re) => re.test(msg));
+}
+
+/** Appended to the persisted error line when a turn dies on a spent usage
+ *  limit. The UI (app/orchestrator/Transcript.tsx) matches this exact string
+ *  to render the informational recovery hint — keep it stable. No action
+ *  button: the quota refills on its own, so the recovery is waiting (the raw
+ *  provider text above the notice carries the reset time when the SDK reported
+ *  one). Persisted message content is the durable channel — it survives SSE
+ *  reconnects because the snapshot replays from SQLite. */
+export const USAGE_LIMIT_NOTICE =
+  "该智能体的用量已达上限，在额度重置之前无法运行任何轮次。" +
+  "没有任何内容丢失：本次会话及其 worktree 均未受影响，排队中的消息也仍在队列里 —— " +
+  "额度重置后会自动继续运行。";