@thaut/claude-ide 0.0.0-stage → 1.0.0

package/server/btw-instructions.ts

@@ -0,0 +1,19 @@
+/** Adapted from Codex's side-conversation boundary and developer instructions.
+ * Our branches are persistent, and writes require the host's explicit switch. */
+export const BTW_BOUNDARY = `Side conversation boundary.
+
+Everything before this boundary is inherited history from the parent conversation. It is reference context only, not your current task.
+Do not continue any task, goal, plan, approval, edit or tool call from that history. Only messages submitted after this boundary are active instructions for this conversation.
+You are now in a btw side conversation. Answer the user's side questions and do lightweight, non-mutating exploration. Do not resume the main conversation's work or interact with its sub-agents.
+This side conversation starts read-only. Do not modify files, git state, configuration, permissions or external systems. If the user wants execution, ask them to promote this conversation and explicitly enable writes.
+The host supplies the current conversation role and permissions before each subsequent prompt. Follow that current context if this conversation is later promoted.`;
+
+export function conversationInstructions(side: boolean, promoted: boolean, writeEnabled: boolean): string | undefined {
+  const role = side
+    ? `You are in a btw side conversation, separate from the main conversation. Answer only the user's side questions and perform lightweight exploration. Inherited history is reference-only: do not continue its tasks, goals, plans, approvals, edits or tool calls. Do not create or interact with sub-agents, including agents seen in inherited history. Wait for a question rather than continuing the main task.`
+    : promoted ? `The host has promoted this former btw side conversation to an ordinary conversation. Its earlier side-conversation role restrictions no longer apply. Continue only the user's current requests here; inherited pre-boundary tasks are still reference-only. Promotion does not itself enable writes.` : "";
+  const permissions = writeEnabled
+    ? side ? "Writes are enabled by the user, but mutations still require an explicit request in this side conversation. Never resume work merely because it appears in inherited history." : ""
+    : "The host has disabled writes for this conversation. Use only available read-only tools. Do not execute shell commands, modify workspace or external state, schedule work, or bypass these restrictions through external tools or delegation. Ask the user to turn off read-only before performing a requested mutation.";
+  return [role, permissions].filter(Boolean).join("\n\n") || undefined;
+}

package/server/btw-policy.ts

@@ -0,0 +1,17 @@
+import { db } from "./db.ts";
+import { sessionGoalProjection } from "./session-file.ts";
+
+/** Isolation belongs to a selected native branch, never a permanent session
+ * boolean. Rewind automatically discards evidence not present in that branch. */
+export async function needsInheritedGoalCleanup(cwd: string, sessionId: string): Promise<boolean> {
+  // Ordinary sessions do not need to open/index a transcript for this policy.
+  const origin = db.prepare("SELECT 1 FROM session_view WHERE session_id=? AND (btw_parent IS NOT NULL OR btw_prompt_uuid IS NOT NULL OR btw_question IS NOT NULL)").get(sessionId);
+  if (!origin) return false;
+  return !(await sessionGoalProjection(cwd, sessionId)).isolated;
+}
+
+/** Persist only the native identity acknowledged as cleared, not goal state.
+ * Branch membership is verified again before trusting this evidence. */
+export function markGoalIsolated(sessionId: string, uuid: string) {
+  db.prepare("UPDATE session_view SET btw_goal_isolated=1, btw_goal_isolation_uuid=? WHERE session_id=?").run(uuid, sessionId);
+}

package/server/btw.ts

@@ -0,0 +1,143 @@
+import { historyCwd, setSessionCwd } from "./session-dirs.ts";
+import crypto from "node:crypto";
+import { forkSession, getSessionInfo, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";
+import type { BtwInfo, BtwItem } from "../shared/protocol.ts";
+import { db } from "./db.ts";
+import { HttpError, sessions } from "./sessions.ts";
+import { BTW_BOUNDARY } from "./btw-instructions.ts";
+import { historyPage } from "./history-pages.ts";
+import { sessionFile } from "./session-file.ts";
+
+/**
+ * /btw (decided design, see PLAN.md): fork the current session and ask the side question in
+ * the fork, so the main thread is never interrupted. The fork is tied to its parent in sqlite
+ * (`session_view.btw_parent`) and hidden from the session list until promoted.
+ */
+
+type Block = { type: string; text?: string; id?: string; tool_use_id?: string };
+type Msg = { type: string; uuid: string; message?: { content?: unknown } };
+
+// The slot belongs to the parent, not to a browser tab or an HTTP request.
+// Serialize lookup + fork so concurrent clients cannot both create a branch.
+const pending = new Map<string, Promise<unknown>>();
+
+function blocks(m: Msg): Block[] {
+  const c = m.message?.content;
+  return Array.isArray(c) ? (c as Block[]) : typeof c === "string" ? [{ type: "text", text: c }] : [];
+}
+
+/**
+ * The last point where the transcript is a complete conversation: a user message or an
+ * assistant text message after which no tool call is left without its result. Forking there is safe while the parent
+ * is mid-turn (its last records may be a dangling tool_use).
+ */
+function safeCutPoint(msgs: Msg[]): string | undefined {
+  const open = new Set<string>();
+  let cut: string | undefined;
+  for (const m of msgs) {
+    for (const b of blocks(m)) {
+      if (b.type === "tool_use" && b.id) open.add(b.id);
+      if (b.type === "tool_result" && b.tool_use_id) open.delete(b.tool_use_id);
+    }
+    if (open.size > 0) continue;
+    if (m.type === "user" || blocks(m).some((b) => b.type === "text" && b.text?.trim())) cut = m.uuid;
+  }
+  return cut;
+}
+
+export async function askBtw(projectPath: string, parentId: string, question: string): Promise<{ id: string }> {
+  // Key by the requested session itself. Its role may change while a request
+  // waits (promotion), but requests that could fork from it still share this lock.
+  const previous = pending.get(parentId) ?? Promise.resolve();
+  const next = previous.catch(() => {}).then(() => askBtwLocked(projectPath, parentId, question));
+  pending.set(parentId, next);
+  try { return await next; }
+  finally { if (pending.get(parentId) === next) pending.delete(parentId); }
+}
+
+async function askBtwLocked(projectPath: string, parentId: string, question: string): Promise<{ id: string }> {
+  question = question.trim();
+  const origin = db.prepare("SELECT btw_parent FROM session_view WHERE session_id=?").get(parentId) as { btw_parent: string | null } | undefined;
+  // Inside a branch /btw means this same conversation, never a nested fork.
+  // Older installations may have several branches; reuse the newest rather than
+  // deleting, promoting, or restarting any of the user's existing conversations.
+  const existing = origin?.btw_parent ? { session_id: parentId }
+    : db.prepare("SELECT session_id FROM session_view WHERE btw_parent=? ORDER BY rowid DESC LIMIT 1").get(parentId) as { session_id: string } | undefined;
+  if (existing) {
+    if (question) {
+      const live = await sessions.getOrCreate(existing.session_id, projectPath);
+      if (!await live.send(crypto.randomUUID(), question)) throw new HttpError(409, "旁支消息未能发送，请重试。");
+    }
+    return { id: existing.session_id };
+  }
+  if (!question) throw new HttpError(400, "问题不能为空");
+  const parentLive = sessions.get(parentId);
+  // The parent may run in a worktree of the project: fork next to it and run there.
+  const dir = await historyCwd(projectPath, parentId);
+  const info = await getSessionInfo(parentId, { dir }).catch(() => undefined);
+  const title = `btw: ${question.replace(/\s+/g, " ").slice(0, 80)}`;
+  let id: string;
+  if (info) {
+    const running = parentLive && parentLive.state !== "idle";
+    const upToMessageId = running ? safeCutPoint((await getSessionMessages(parentId, { dir })) as Msg[]) : undefined;
+    ({ sessionId: id } = await forkSession(parentId, { dir, title, ...(upToMessageId ? { upToMessageId } : {}) }));
+  } else {
+    // Nothing written yet: the side question starts from an empty conversation.
+    id = crypto.randomUUID();
+  }
+  if (dir !== projectPath) setSessionCwd(id, dir);
+  const promptUuid = crypto.randomUUID();
+  db.prepare("INSERT OR REPLACE INTO session_view (session_id, project_path, btw_parent, btw_question, btw_prompt_uuid, write_enabled) VALUES (?, ?, ?, ?, ?, 0)").run(
+    id,
+    projectPath,
+    parentId,
+    question,
+    promptUuid,
+  );
+  const live = await sessions.getOrCreate(id, projectPath);
+  if (parentLive?.model) await live.setModel(parentLive.model);
+  if (parentLive?.effort) await live.setEffort(parentLive.effort);
+  if (!await live.send(promptUuid, question, [], BTW_BOUNDARY)) throw new HttpError(409, "旁支消息未能发送，请重试。");
+  sessions.notifyChanged(projectPath);
+  return { id };
+}
+
+export async function btwInfo(projectPath: string, sessionId: string): Promise<BtwInfo> {
+  const parentRow = db.prepare("SELECT btw_parent FROM session_view WHERE session_id = ?").get(sessionId) as { btw_parent: string | null } | undefined;
+  const rows = db
+    .prepare("SELECT session_id, btw_question, btw_prompt_uuid, rewind_anchor FROM session_view WHERE btw_parent = ? AND project_path = ?")
+    .all(sessionId, projectPath) as Row[];
+  const children = await Promise.all(rows.map((r) => btwItem(projectPath, r)));
+  children.sort((a, b) => b.lastModified - a.lastModified);
+  return { parent: parentRow?.btw_parent ?? null, children };
+}
+
+type Row = { session_id: string; btw_question: string | null; btw_prompt_uuid: string | null; rewind_anchor: string | null };
+
+async function btwItem(projectPath: string, row: Row): Promise<BtwItem> {
+  const id = row.session_id;
+  const live = sessions.get(id);
+  const state = live?.state ?? "idle";
+  const dir = await historyCwd(projectPath, id);
+  const info = await getSessionInfo(id, { dir }).catch(() => undefined);
+  // Reuse the bounded, indexed history reader instead of reading every branch's
+  // complete inherited transcript every time a list is invalidated.
+  const page = row.btw_prompt_uuid ? await historyPage(await sessionFile(dir, id), { after: row.btw_prompt_uuid, anchor: row.rewind_anchor }).catch(() => undefined) : undefined;
+  const msgs = (page?.items ?? []) as Msg[];
+  // The answer is what follows the prompt that asked the question.
+  const question = row.btw_question ?? info?.customTitle?.replace(/^btw: /, "") ?? "";
+  const answer =
+    page
+      ? msgs
+          .filter((m) => m.type === "assistant")
+          .flatMap((m) => blocks(m).filter((b) => b.type === "text" && b.text).map((b) => b.text!))
+          .join("\n\n").slice(0, 2000) || undefined
+      : undefined;
+  return { id, question, state, answer, lastModified: info?.lastModified ?? live?.lastActivity ?? Date.now() };
+}
+
+/** "转为普通会话": drop the btw tie so the session shows up in the list. */
+export function promoteBtw(projectPath: string, sessionId: string) {
+  db.prepare("UPDATE session_view SET btw_parent = NULL WHERE session_id = ?").run(sessionId);
+  sessions.notifyChanged(projectPath);
+}

package/server/child-env.ts

@@ -0,0 +1,29 @@
+/**
+ * Environment for processes we start (the CLI, probe queries, `claude` subcommands, `!` commands).
+ *
+ * When this server itself runs inside a Claude Code session (e.g. started from its terminal),
+ * the environment carries that outer session's identity: its session id, messaging socket and
+ * token, effort, "child session" markers. Passing those on would make every CLI we start act as
+ * a child of that unrelated session. Configuration variables (CLAUDE_CODE_USE_BEDROCK, …) stay.
+ */
+const OUTER_SESSION_VARS = [
+  "CLAUDECODE",
+  "CLAUDE_PID",
+  "CLAUDE_EFFORT",
+  "CLAUDE_JOB_DIR",
+  "CLAUDE_CODE_SESSION_ID",
+  "CLAUDE_CODE_CHILD_SESSION",
+  "CLAUDE_CODE_SESSION_ATTENDED",
+  "CLAUDE_CODE_MESSAGING_SOCKET",
+  "CLAUDE_CODE_MESSAGING_TOKEN",
+  "CLAUDE_CODE_EXECPATH",
+  "CLAUDE_CODE_ENTRYPOINT",
+  "CLAUDE_CODE_SSE_PORT",
+  "AI_AGENT",
+];
+
+export function childEnv(extra: Record<string, string | undefined> = {}): Record<string, string | undefined> {
+  const env: Record<string, string | undefined> = { ...process.env };
+  for (const k of OUTER_SESSION_VARS) delete env[k];
+  return { ...env, ...extra };
+}

package/server/cli-control.ts

@@ -0,0 +1,255 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import { query, type Query, type SDKControlInitializeResponse, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { claudeEnv, globalStateFile } from "./config/paths.ts";
+
+/**
+ * SDK adapter for the settings pages: control requests answered by the CLI without a
+ * model call. Each call starts a probe query whose input never yields, waits for
+ * initialize, runs the request(s) and closes the query (the same trick as cli-info.ts).
+ *
+ * Several of these methods exist at runtime but are not in sdk.d.ts ([隐藏] in NOTES.md);
+ * their shapes are typed here so an SDK upgrade only needs this file checked
+ * (`spikes/sdk/m6_config_probe.mjs` prints them all).
+ */
+
+export type MemoryDialog = {
+  files: { kind: string; path: string; label: string; description: string; exists: boolean }[];
+  folders: { kind: string; path: string; label: string }[];
+  memories: { name: string; path: string; description: string | null; modified_ms: number }[];
+  auto_memory: { enabled: boolean; toggleable: boolean; status: string };
+};
+
+export type HooksListingRaw = {
+  events: { name: string; summary: string; supportsMatcher: boolean; hookCount: number }[];
+  hooks: { event: string; matcher?: string; source: string; sourceLabel: string; type: string; displayText: string }[];
+  eventCatalog: { name: string; summary: string; supportsMatcher: boolean }[];
+};
+
+export type SkillsDialog = {
+  skills: { name: string; display_name: string; description: string; source: string; state: string; tokens?: number; locked_by?: string }[];
+};
+
+export type StatusDialog = { sections: { title: string; rows: { label: string; value: string }[] }[] };
+
+export type UsageWindow = { utilization: number | null; resets_at: string | null } | null;
+export type UsageReport = {
+  subscription_type: string | null;
+  rate_limits_available: boolean;
+  rate_limits: (Record<string, unknown> & { five_hour: UsageWindow; seven_day: UsageWindow }) | null;
+};
+
+export type McpStatusEntry = {
+  name: string;
+  status: string;
+  error?: string | null;
+  config?: Record<string, unknown>;
+  scope?: string;
+  source?: string;
+};
+
+export type McpAuthResult = {
+  authUrl?: string;
+  requiresUserAction?: boolean;
+  callbackExpected?: boolean;
+  callbackPort?: number;
+};
+
+/** The probe query with the hidden methods typed. */
+export type ControlQuery = Query & {
+  getMemoryDialog(): Promise<MemoryDialog>;
+  getHooksListing(): Promise<HooksListingRaw>;
+  getSkillsDialog(): Promise<SkillsDialog>;
+  getSettings(): Promise<{ effective: Record<string, unknown>; sources: { source: string; settings: Record<string, unknown> }[] }>;
+  getStatus(): Promise<StatusDialog>;
+  mcpAuthenticate(server: string, redirectUri?: string): Promise<McpAuthResult>;
+  mcpSubmitOAuthCallbackUrl(server: string, callbackUrl: string): Promise<unknown>;
+  mcpClearAuth(server: string): Promise<unknown>;
+};
+
+const never: AsyncIterable<SDKUserMessage> = { [Symbol.asyncIterator]: () => ({ next: () => new Promise(() => {}) }) };
+
+// Each probe is a CLI process (~250 MB); keep at most two alive at once.
+const MAX_PROBES = 2;
+let active = 0;
+const waiting: (() => void)[] = [];
+async function acquire() {
+  if (active < MAX_PROBES) {
+    active++;
+    return;
+  }
+  await new Promise<void>((r) => waiting.push(r));
+  active++;
+}
+function release() {
+  active--;
+  waiting.shift()?.();
+}
+
+function openProbe(cwd: string): ControlQuery {
+  return query({ prompt: never, options: { cwd, settingSources: ["user", "project", "local"], env: claudeEnv() } }) as ControlQuery;
+}
+
+/** Run control requests against a short-lived probe query in `cwd`. */
+export async function withControl<T>(cwd: string, fn: (q: ControlQuery, init: SDKControlInitializeResponse) => Promise<T>, timeoutMs = 30_000): Promise<T> {
+  await acquire();
+  const q = openProbe(cwd);
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    const work = (async () => fn(q, await q.initializationResult()))();
+    const timeout = new Promise<never>((_, rej) => {
+      timer = setTimeout(() => rej(new Error("CLI 控制请求超时")), timeoutMs);
+    });
+    return await Promise.race([work, timeout]);
+  } finally {
+    clearTimeout(timer);
+    q.close();
+    release();
+  }
+}
+
+const cache = new Map<string, { at: number; value: Promise<unknown> }>();
+/** Small TTL cache for listings that several requests in a row need (e.g. the memory dialog). */
+export function cached<T>(key: string, ttlMs: number, load: () => Promise<T>): Promise<T> {
+  const hit = cache.get(key);
+  if (hit && Date.now() - hit.at < ttlMs) return hit.value as Promise<T>;
+  const value = load();
+  value.catch(() => cache.delete(key));
+  cache.set(key, { at: Date.now(), value });
+  return value;
+}
+export function invalidate(prefix: string) {
+  for (const k of cache.keys()) if (k.startsWith(prefix)) cache.delete(k);
+}
+
+export const memoryDialog = (cwd: string) => cached(`memory:${cwd}`, 15_000, () => withControl(cwd, (q) => q.getMemoryDialog()));
+export const hooksListing = (cwd: string) => withControl(cwd, (q) => q.getHooksListing());
+export const skillsDialog = (cwd: string) => withControl(cwd, (q) => q.getSkillsDialog());
+export const effectiveSettings = (cwd: string) => withControl(cwd, (q) => q.getSettings());
+export const initInfo = (cwd: string) => cached(`init:${cwd}`, 60_000, () => withControl(cwd, async (_q, init) => init));
+
+/**
+ * MCP status. Servers start as "pending" while the probe connects; wait (bounded)
+ * until none is pending so the page shows a real connected/failed state.
+ */
+export function mcpStatus(cwd: string, waitMs = 6000): Promise<McpStatusEntry[]> {
+  return withControl(cwd, async (q) => {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+      const list = (await q.mcpServerStatus()) as McpStatusEntry[];
+      if (Date.now() > deadline || !list.some((s) => s.status === "pending")) return list;
+      await new Promise((r) => setTimeout(r, 300));
+    }
+  });
+}
+
+function disabledInState(name: string): boolean {
+  try {
+    const state = JSON.parse(fs.readFileSync(globalStateFile, "utf8")) as { projects?: Record<string, { disabledMcpServers?: string[] }> };
+    return Object.values(state.projects ?? {}).some((p) => p.disabledMcpServers?.includes(name));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Enable/disable an MCP server for this project. The CLI persists it in ~/.claude.json
+ * (`projects[<canonical root>].disabledMcpServers`) a moment *after* answering, and
+ * enabling a server that then fails to connect rejects ("Connection closed") although
+ * the change is still saved [实测]. So wait for the file before closing the probe.
+ */
+export const toggleMcp = (cwd: string, name: string, enabled: boolean) =>
+  withControl(cwd, async (q) => {
+    let error: Error | undefined;
+    try {
+      await q.toggleMcpServer(name, enabled);
+    } catch (err) {
+      error = err as Error;
+    }
+    const deadline = Date.now() + 4000;
+    while (Date.now() < deadline) {
+      if (disabledInState(name) === !enabled) return { warning: error?.message };
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    if (error) throw error;
+    return {};
+  });
+
+export const clearMcpAuth = (cwd: string, name: string) => withControl(cwd, (q) => q.mcpClearAuth(name));
+
+/** Account facts: initialize response, account, plan usage and /status rows. */
+export function accountSnapshot(cwd: string) {
+  return withControl(cwd, async (q, init) => {
+    const errors: string[] = [];
+    const safe = async <T>(label: string, p: Promise<T>): Promise<T | null> => {
+      try {
+        return await p;
+      } catch (err) {
+        errors.push(`${label}: ${(err as Error).message}`);
+        return null;
+      }
+    };
+    const account = await safe("accountInfo", q.accountInfo());
+    const usage = await safe("usage", q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET({ skipBehaviors: true }) as Promise<UsageReport>);
+    const status = await safe("getStatus", q.getStatus());
+    return { init, account, usage, status, errors };
+  });
+}
+
+// ---------- MCP OAuth: the flow state lives in the CLI process, so its probe stays open ----------
+
+type AuthFlow = { q: ControlQuery; server: string; cwd: string; timer: NodeJS.Timeout };
+const flows = new Map<string, AuthFlow>();
+const FLOW_TTL_MS = 10 * 60_000;
+
+function endFlow(id: string) {
+  const f = flows.get(id);
+  if (!f) return;
+  clearTimeout(f.timer);
+  f.q.close();
+  flows.delete(id);
+}
+
+/**
+ * Start an MCP OAuth sign-in. Returns the URL to open; the browser ends on the CLI's
+ * localhost callback, which a phone cannot reach — so the user pastes that final URL
+ * back and we hand it to `mcpSubmitOAuthCallbackUrl`.
+ */
+export async function startMcpAuth(cwd: string, server: string) {
+  for (const [id, f] of flows) if (f.server === server && f.cwd === cwd) endFlow(id);
+  const q = openProbe(cwd);
+  try {
+    await q.initializationResult();
+    // The server must have been tried once (needs-auth) before authenticating.
+    const deadline = Date.now() + 8000;
+    while (Date.now() < deadline) {
+      const s = ((await q.mcpServerStatus()) as McpStatusEntry[]).find((x) => x.name === server);
+      if (!s || s.status !== "pending") break;
+      await new Promise((r) => setTimeout(r, 300));
+    }
+    const res = await q.mcpAuthenticate(server);
+    const id = crypto.randomUUID();
+    flows.set(id, { q, server, cwd, timer: setTimeout(() => endFlow(id), FLOW_TTL_MS) });
+    return { flowId: id, ...res };
+  } catch (err) {
+    q.close();
+    throw err;
+  }
+}
+
+export async function submitMcpAuth(flowId: string, callbackUrl: string) {
+  const f = flows.get(flowId);
+  if (!f) throw new Error("登录流程已过期，请重新开始");
+  // A rejected URL (state mismatch, no code) leaves the flow waiting, so keep it open on error.
+  const res = await f.q.mcpSubmitOAuthCallbackUrl(f.server, callbackUrl);
+  endFlow(flowId);
+  return res;
+}
+
+export function cancelMcpAuth(flowId: string) {
+  endFlow(flowId);
+}
+
+export function closeAllControl() {
+  for (const id of [...flows.keys()]) endFlow(id);
+}

package/server/cli-files.ts

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+/** Locations of the CLI's own files (session transcripts live under <claudeDir>/projects). */
+export const claudeDir = () => process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
+
+/** The CLI's per-project directory name: non-alphanumerics become "-" (long paths get a hash we can't recompute). */
+export function encodedDir(p: string) {
+  return p.replace(/[^a-zA-Z0-9]/g, "-");
+}
+
+async function exists(p: string, strict = false) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch (err) {
+    if (strict && (err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    return false;
+  }
+}
+
+/** Directory holding <sessionId>.jsonl, found by name and falling back to a scan. */
+export async function sessionFileDir(projectPath: string, sessionId: string, strict = false): Promise<string | undefined> {
+  const projects = path.join(claudeDir(), "projects");
+  const direct = path.join(projects, encodedDir(projectPath));
+  if (await exists(path.join(direct, `${sessionId}.jsonl`), strict)) return direct;
+  if (!(await exists(projects, strict))) return undefined;
+  for (const d of await fs.readdir(projects, { withFileTypes: true })) {
+    if (d.isDirectory() && (await exists(path.join(projects, d.name, `${sessionId}.jsonl`), strict))) return path.join(projects, d.name);
+  }
+  return undefined;
+}
+
+/** The first transcript line, where the CLI records session-level facts such as `forkedFrom`. */
+export async function firstRecord(projectPath: string, sessionId: string): Promise<Record<string, unknown> | undefined> {
+  const dir = await sessionFileDir(projectPath, sessionId);
+  if (!dir) return undefined;
+  const fh = await fs.open(path.join(dir, `${sessionId}.jsonl`), "r");
+  try {
+    const buf = Buffer.alloc(64 * 1024);
+    const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+    const line = buf.subarray(0, bytesRead).toString("utf8").split("\n")[0];
+    return line ? JSON.parse(line) : undefined;
+  } catch {
+    return undefined;
+  } finally {
+    await fh.close();
+  }
+}
+
+export async function forkedFrom(projectPath: string, sessionId: string): Promise<{ sessionId: string; messageUuid?: string } | undefined> {
+  const f = (await firstRecord(projectPath, sessionId))?.forkedFrom as { sessionId?: string; messageUuid?: string } | undefined;
+  return f?.sessionId ? { sessionId: f.sessionId, messageUuid: f.messageUuid } : undefined;
+}

package/server/cli-info.ts

@@ -0,0 +1,73 @@
+import { childEnv } from "./child-env.ts";
+import { query, type SDKControlInitializeResponse, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { CommandInfo, ModelOption } from "../shared/protocol.ts";
+
+/**
+ * Static CLI facts (models, commands, account, version) without calling the model:
+ * start a query whose input never yields, read the init response, close it.
+ */
+const cache = new Map<string, { at: number; value: Promise<SDKControlInitializeResponse> }>();
+const TTL_MS = 10 * 60_000;
+
+export function cliInit(cwd: string): Promise<SDKControlInitializeResponse> {
+  const hit = cache.get(cwd);
+  if (hit && Date.now() - hit.at < TTL_MS) return hit.value;
+  const value = (async () => {
+    const never: AsyncIterable<SDKUserMessage> = { [Symbol.asyncIterator]: () => ({ next: () => new Promise(() => {}) }) };
+    const q = query({ prompt: never, options: { cwd, settingSources: ["user", "project", "local"], env: childEnv() } });
+    try {
+      return await q.initializationResult();
+    } finally {
+      q.close();
+    }
+  })();
+  value.catch(() => cache.delete(cwd));
+  cache.set(cwd, { at: Date.now(), value });
+  return value;
+}
+
+export async function modelOptions(cwd: string): Promise<ModelOption[]> {
+  const init = await cliInit(cwd);
+  return init.models.map((m) => ({
+    value: m.value,
+    displayName: m.displayName,
+    description: m.description,
+    efforts: m.supportedEffortLevels,
+  }));
+}
+
+// ---------- slash commands for the composer's `/` menu ----------
+
+/**
+ * Commands whose UX is bound to the terminal. The CLI announces them in system/init's
+ * `terminal_slash_commands` (only sent when a turn starts), so start from the last observed
+ * list [实测 2.1.296] and keep it updated from live sessions.
+ */
+const terminalCommands = new Set(["doctor", "color", "focus", "reload-plugins"]);
+
+export function noteTerminalCommands(list: string[] | undefined) {
+  for (const c of list ?? []) terminalCommands.add(c);
+}
+
+/** Commands the web UI implements itself (the CLI has no SDK version of them). */
+const WEB_COMMANDS: CommandInfo[] = [
+  { name: "btw", description: "顺口问一句：从当前会话分出一个旁支会话来回答，不打断主线", argumentHint: "<问题>" },
+  { name: "clear", description: "清空重开：新建一个会话并跳转过去（原会话保留）", argumentHint: "" },
+  { name: "add-dir", description: "允许 Claude 访问项目以外的一个目录（本会话）", argumentHint: "<绝对路径>" },
+  { name: "cd", description: "把当前会话移到另一个目录继续（该目录会加入项目列表）", argumentHint: "<绝对路径>" },
+  { name: "feedback", description: "向 Anthropic 反馈 Claude Code 的问题（附带本会话记录）", argumentHint: "<内容>", aliases: ["bug"] },
+  { name: "release-notes", description: "查看 Claude Code 的版本更新说明", argumentHint: "" },
+];
+
+export async function commandList(cwd: string): Promise<CommandInfo[]> {
+  const init = await cliInit(cwd);
+  const web = new Set(WEB_COMMANDS.map((c) => c.name));
+  const seen = new Set<string>();
+  const out: CommandInfo[] = [...WEB_COMMANDS];
+  for (const c of init.commands) {
+    if (c.name.startsWith("__") || terminalCommands.has(c.name) || web.has(c.name) || seen.has(c.name)) continue;
+    seen.add(c.name);
+    out.push({ name: c.name, description: c.description, argumentHint: c.argumentHint, ...(c.aliases?.length ? { aliases: c.aliases } : {}) });
+  }
+  return out;
+}

package/server/config/account.ts

@@ -0,0 +1,65 @@
+import os from "node:os";
+import type { AccountStatus, RateWindow } from "../../shared/config.ts";
+import { accountSnapshot, type UsageWindow } from "../cli-control.ts";
+import { configDir, parseJsonOutput, runClaude, tildify } from "./paths.ts";
+
+/**
+ * Account and health (/usage, /status, /doctor). Login state comes from
+ * `claude auth status --json`; the web never signs in on the user's behalf.
+ */
+
+const win = (w: UsageWindow | undefined): RateWindow | null => (w ? { utilization: w.utilization ?? null, resetsAt: w.resets_at ?? null } : null);
+
+const EXTRA_WINDOWS: Record<string, string> = { seven_day_opus: "7 天（Opus）", seven_day_sonnet: "7 天（Sonnet）" };
+
+export async function accountStatus(): Promise<AccountStatus> {
+  const errors: string[] = [];
+  const cwd = os.homedir();
+  const [authRun, snap] = await Promise.all([
+    runClaude(["auth", "status", "--json"], cwd, { timeoutMs: 30_000 }).catch((err: Error) => {
+      errors.push(`auth status: ${err.message}`);
+      return null;
+    }),
+    accountSnapshot(cwd).catch((err: Error) => {
+      errors.push(`CLI: ${err.message}`);
+      return null;
+    }),
+  ]);
+  const raw = authRun ? parseJsonOutput<Record<string, unknown>>(authRun.stdout) : undefined;
+  const auth = raw
+    ? {
+        loggedIn: raw.loggedIn === true,
+        authMethod: raw.authMethod as string | undefined,
+        email: raw.email as string | undefined,
+        orgName: raw.orgName as string | undefined,
+        subscriptionType: raw.subscriptionType as string | undefined,
+        raw,
+      }
+    : null;
+  if (snap) errors.push(...snap.errors);
+  const rl = snap?.usage?.rate_limits;
+  const extra = rl
+    ? Object.entries(EXTRA_WINDOWS)
+        .map(([k, label]) => ({ label, w: rl[k] as UsageWindow | undefined }))
+        .filter((x) => x.w && typeof x.w === "object")
+        .map((x) => ({ label: x.label, utilization: x.w!.utilization ?? null, resetsAt: x.w!.resets_at ?? null }))
+    : [];
+  return {
+    auth,
+    account: (snap?.account as Record<string, unknown> | null) ?? null,
+    version: snap?.init.claude_code_version ?? null,
+    model: snap?.status?.sections.flatMap((s) => s.rows).find((r) => r.label === "Model")?.value ?? null,
+    usage: rl ? { fiveHour: win(rl.five_hour), sevenDay: win(rl.seven_day), extra } : null,
+    status: snap?.status?.sections ?? [],
+    configDir: tildify(configDir),
+    errors,
+  };
+}
+
+export async function doctor(root: string | null) {
+  const r = await runClaude(["doctor"], root ?? os.homedir(), { timeoutMs: 60_000 });
+  // The output is meant for a terminal; strip ANSI escapes.
+  // eslint-disable-next-line no-control-regex
+  const text = (r.stdout + (r.stderr ? `\n${r.stderr}` : "")).replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "").trim();
+  return { code: r.code, text };
+}