@thaut/claude-ide 0.0.0-stage → 1.0.0

package/shared/config.ts

@@ -0,0 +1,175 @@
+/**
+ * Settings pages (M6): memory, permissions, MCP, plugins, skills, hooks, agents,
+ * settings and account. Everything is read from / written to the CLI's own files
+ * or `claude` subcommands; these are only the wire shapes.
+ */
+
+/** Settings layers the web edits (managed/policy settings are read-only and not listed). */
+export type SettingsScope = "user" | "project" | "local";
+export const SCOPE_LABEL: Record<SettingsScope, string> = { user: "用户", project: "项目（共享）", local: "项目（本地）" };
+
+export type ScopeFile = { scope: SettingsScope; path: string; exists: boolean };
+
+// ---------- memory ----------
+
+export type MemoryKind = "user" | "user-rule" | "project" | "project-rule" | "local" | "auto" | "other";
+
+export type MemoryFile = {
+  kind: MemoryKind;
+  path: string;
+  /** Short label, e.g. "~/.claude/CLAUDE.md" or "MEMORY.md" */
+  label: string;
+  exists: boolean;
+  size?: number;
+  mtime?: number;
+};
+
+export type MemoryListing = {
+  files: MemoryFile[];
+  /** Directories where new files may be created (rules dirs, auto-memory dir) */
+  dirs: { kind: MemoryKind; path: string; label: string }[];
+  autoMemory: { enabled: boolean; dir: string | null; scope: SettingsScope | null };
+};
+
+export type TextFile = { path: string; content: string; mtime: number };
+
+// ---------- permissions ----------
+
+export type PermissionKind = "allow" | "deny" | "ask" | "additionalDirectories";
+export const PERMISSION_KINDS: PermissionKind[] = ["allow", "deny", "ask", "additionalDirectories"];
+
+export type PermissionLayer = ScopeFile & { lists: Record<PermissionKind, string[]> };
+
+export type PermissionOp =
+  | { scope: SettingsScope; kind: PermissionKind; op: "add"; value: string }
+  | { scope: SettingsScope; kind: PermissionKind; op: "remove"; value: string }
+  | { scope: SettingsScope; kind: PermissionKind; op: "replace"; old: string; value: string };
+
+// ---------- hooks ----------
+
+export type HookCommand = { type: string; command?: string; timeout?: number; [k: string]: unknown };
+export type HookGroup = { matcher?: string; hooks: HookCommand[] };
+export type HookLayer = ScopeFile & { hooks: Record<string, HookGroup[]> };
+export type HookEventInfo = { name: string; summary: string; supportsMatcher: boolean };
+export type HooksListing = {
+  layers: HookLayer[];
+  events: HookEventInfo[];
+  /** Hooks from sources the web does not edit (plugins, managed policy) */
+  readonly: { event: string; matcher?: string; source: string; label: string; text: string }[];
+};
+
+export type HookOp =
+  | { scope: SettingsScope; op: "add"; event: string; matcher?: string; hook: HookCommand }
+  | { scope: SettingsScope; op: "remove"; event: string; group: number; index: number }
+  | { scope: SettingsScope; op: "replace"; event: string; group: number; index: number; matcher?: string; hook: HookCommand };
+
+// ---------- settings (/config) ----------
+
+export type SettingsLayer = ScopeFile & { settings: Record<string, unknown> };
+export type SettingsInfo = {
+  layers: SettingsLayer[];
+  effective: Record<string, unknown>;
+  outputStyles: string[];
+  models: { value: string; displayName: string; description?: string }[];
+};
+
+// ---------- agents ----------
+
+export type AgentFile = {
+  scope: "user" | "project";
+  /** File name without .md */
+  file: string;
+  path: string;
+  name: string;
+  description: string;
+  tools: string;
+  model: string;
+  /** Other frontmatter keys, kept verbatim */
+  extra: string;
+  prompt: string;
+  mtime: number;
+};
+
+export type AgentInput = {
+  scope: "user" | "project";
+  /** Existing file name when editing; omitted when creating */
+  file?: string;
+  name: string;
+  description: string;
+  tools: string;
+  model: string;
+  prompt: string;
+};
+
+// ---------- MCP ----------
+
+export type McpServer = {
+  name: string;
+  /** local / project / user from config; plugin / claudeai / dynamic etc. are read-only */
+  scope: string;
+  status: string;
+  error?: string;
+  config: Record<string, unknown>;
+  editable: boolean;
+};
+
+export type McpAddInput = {
+  name: string;
+  scope: SettingsScope;
+  transport: "stdio" | "http" | "sse";
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  headers?: Record<string, string>;
+};
+
+export type McpAuthStart = { flowId: string; authUrl: string | null; requiresUserAction: boolean; callbackPort?: number };
+
+// ---------- plugins & skills ----------
+
+export type InstalledPlugin = {
+  id: string;
+  version?: string;
+  scope: string;
+  enabled: boolean;
+  installPath?: string;
+  description?: string;
+};
+
+export type Marketplace = { name: string; source?: string; repo?: string; url?: string; path?: string; installLocation?: string };
+
+export type AvailablePlugin = { pluginId: string; name: string; description?: string; marketplaceName: string; installCount?: number };
+
+export type PluginListing = { installed: InstalledPlugin[]; marketplaces: Marketplace[] };
+
+/** Result of a plugin command; `confirm` is set when the marketplace declares a command to run. */
+export type PluginActionResult = {
+  ok: boolean;
+  message: string;
+  confirm?: { sha256: string; command: unknown; kind?: string };
+};
+
+export type SkillInfo = {
+  name: string;
+  source: string;
+  description: string;
+  path: string | null;
+  state?: string;
+  plugin?: string;
+};
+
+// ---------- account ----------
+
+export type RateWindow = { utilization: number | null; resetsAt: string | null };
+
+export type AccountStatus = {
+  auth: { loggedIn: boolean; authMethod?: string; email?: string; orgName?: string; subscriptionType?: string; raw: Record<string, unknown> } | null;
+  account: Record<string, unknown> | null;
+  version: string | null;
+  model: string | null;
+  usage: { fiveHour: RateWindow | null; sevenDay: RateWindow | null; extra: { label: string; utilization: number | null; resetsAt: string | null }[] } | null;
+  status: { title: string; rows: { label: string; value: string }[] }[];
+  configDir: string;
+  errors: string[];
+};

package/shared/directories.ts

@@ -0,0 +1,12 @@
+/** Directories on the server, including paths not yet registered as projects. */
+export type DirectoryListing = {
+  path: string;
+  parent: string | null;
+  home: string;
+  entries: { name: string; path: string; type?: "dir" | "file" }[];
+  truncated: boolean;
+  /** Completion keeps the typed target separate from the directory being listed. */
+  requestedPath?: string;
+  requestedType?: "dir" | "file" | "missing";
+  prefix?: string;
+};

package/shared/files.ts

@@ -0,0 +1,51 @@
+/** REST shapes for the project file browser and git change views. */
+
+export type DirEntry = {
+  name: string;
+  /** Path relative to the project root, forward slashes */
+  path: string;
+  type: "dir" | "file" | "other";
+  size?: number;
+  /** Matched by .gitignore (still viewable, shown dimmed) */
+  ignored?: boolean;
+  /** Entry is a symlink */
+  link?: boolean;
+  /** Symlink whose target is outside the project (not openable) */
+  outside?: boolean;
+};
+
+export type DirListing = { path: string; entries: DirEntry[]; truncated: boolean; git: boolean };
+
+export type FileContent = {
+  path: string;
+  size: number;
+  /** Only a preview was returned (normally the first 1 MiB). */
+  truncated: boolean;
+  binary: boolean;
+  content?: string;
+};
+
+export type FileMatch = { path: string; score: number };
+
+/** `start`/`end` are string indices of the first hit within `text`. */
+export type ContentMatch = { path: string; line: number; text: string; start?: number; end?: number };
+
+/** Display status: M modified, A added, D deleted, U conflict, ?? untracked. */
+export type ChangeStatus = "M" | "A" | "D" | "U" | "??";
+
+export type GitChange = { path: string; status: ChangeStatus; staged: boolean; unstaged: boolean };
+
+export type GitStatus = { isRepo: false } | { isRepo: true; branch: string | null; changes: GitChange[] };
+
+export type GitDiff = { path: string; status: ChangeStatus | null; diff: string; truncated: boolean };
+
+export const IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".bmp", ".ico", ".svg"];
+export const AUDIO_TYPES: Record<string, string> = {
+  ".mp3": "audio/mpeg", ".wav": "audio/wav", ".wave": "audio/wav", ".ogg": "audio/ogg", ".oga": "audio/ogg",
+  ".opus": "audio/ogg", ".m4a": "audio/mp4", ".aac": "audio/aac", ".flac": "audio/flac", ".weba": "audio/webm",
+  ".aif": "audio/aiff", ".aiff": "audio/aiff",
+};
+
+export const MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
+export const MAX_UPLOAD_FILES = 100;
+export type UploadResult = { files: string[]; conflicts: string[] };

package/shared/http-channels.ts

@@ -0,0 +1,63 @@
+export const HTTP_CHANNEL_LIMIT = 32;
+export const HTTP_INBOX_LIMIT = 1024;
+
+export type HttpChannelDirection = "subscribe" | "push";
+export type HttpSourceKind = "http" | "brain-api";
+export type HttpSubscribeMethod = "GET" | "POST";
+export type HttpTextMessage = { kind: "text"; id: string; text: string };
+export type HttpPollResponse = { kind: "empty" } | { kind: "text"; id?: string; text: string };
+export type HttpPushMessage = HttpTextMessage & { sessionId: string };
+export type HttpJsonValue = string | number | boolean | null | HttpJsonValue[] | { [key: string]: HttpJsonValue };
+export type HttpExtraBody = Record<string, HttpJsonValue>;
+
+export type HttpSource = {
+  id: string;
+  kind: HttpSourceKind;
+  brainId: string | null;
+  brainVoice: string | null;
+  name: string;
+  url: string;
+  timeoutMs: number;
+  subscribeMethod: HttpSubscribeMethod;
+  hasHeaders: boolean;
+  hasExtraBody: boolean;
+};
+export type HttpSourceInput = { name?: string; url: string; kind?: HttpSourceKind; brainId?: string | null; brainVoice?: string | null; timeoutMs?: number; subscribeMethod?: HttpSubscribeMethod; headers?: Record<string, string>; extraBody?: HttpExtraBody };
+/** Loaded explicitly when editing; the general source listing omits header values. */
+export type HttpSourceDetails = HttpSource & { headers: Record<string, string>; extraBody: HttpExtraBody };
+/** null inherits the source; an empty voice explicitly suppresses its header. */
+export type HttpBindingOverrides = { brainId?: string | null; brainVoice?: string | null };
+export type HttpChannelStats = {
+  requests: number;
+  delivered: number;
+  received: number;
+  pushed: number;
+  duplicates: number;
+  dropped: number;
+  pending: number;
+  lastSuccessAt?: number;
+  lastError?: string;
+  lastPullError?: string;
+  lastPushError?: string;
+};
+export type HttpChannelBinding = {
+  id: string;
+  sessionId: string;
+  projectId: string;
+  sourceId: string;
+  direction: HttpChannelDirection;
+  brainId: string | null;
+  brainVoice: string | null;
+  active: boolean;
+  activatedAt: number | null;
+  inactiveReason: string | null;
+  stats: HttpChannelStats | null;
+};
+export type HttpChannelsInfo = {
+  sources: HttpSource[];
+  bindings: HttpChannelBinding[];
+  activeCount: number;
+  activeLimit: number;
+  inboxSize: number;
+  inboxLimit: number;
+};

package/shared/message-window.ts

@@ -0,0 +1,189 @@
+import type { LiveEvent, SdkMessageLike, SeqEvent } from "./protocol.ts";
+
+export const MESSAGE_LIMIT = 1500;
+export const SESSION_BYTES = 40 * 1024 * 1024;
+export const TOTAL_BYTES = 120 * 1024 * 1024;
+export const SESSION_LIMIT = 5;
+export const PAGE_LIMIT = 100;
+export const PAGE_BYTES = 512 * 1024;
+
+/** Approximate retained string payload, not a promise about the JS heap. */
+export function contentBytes(value: unknown): number {
+  if (typeof value === "string") return value.length * 2;
+  if (!value || typeof value !== "object") return 16;
+  if (Array.isArray(value)) return value.reduce((n, v) => n + contentBytes(v), 24);
+  return Object.entries(value).reduce((n, [k, v]) => n + k.length * 2 + contentBytes(v), 32);
+}
+
+const displaySizes = new WeakMap<object, number>();
+
+/** Large records stay in JSONL; a display placeholder can be hydrated explicitly. */
+export function displayMessage(m: SdkMessageLike, bytes?: number): SdkMessageLike {
+  if (m._deferred || m._hydrated) return m;
+  if (bytes === undefined) {
+    bytes = displaySizes.get(m);
+    if (bytes === undefined) { bytes = contentBytes(m); displaySizes.set(m, bytes); }
+  }
+  if (bytes <= PAGE_BYTES / 2) return m;
+  let nodes = 0;
+  let chars = 0;
+  const preview = (v: unknown): unknown => {
+    if (++nodes > 256) return "…";
+    if (typeof v === "string") { const text = v.slice(0, Math.min(2000, Math.max(0, 16000 - chars))); chars += text.length; return text; }
+    if (Array.isArray(v)) return v.slice(0, 20).map(preview);
+    if (!v || typeof v !== "object") return v;
+    return Object.fromEntries(Object.entries(v).filter(([k]) => k !== "data").slice(0, 30).map(([k, v]) => [k, preview(v)]));
+  };
+  // Completed shell XML may be clipped in the middle of its command. Retain a
+  // bounded structured preview so completion and output do not depend on parsing it.
+  const payload = (m.message as { content?: unknown } | undefined)?.content;
+  const text = typeof payload === "string" ? payload : Array.isArray(payload)
+    ? (payload.find((b) => b?.type === "text") as { text?: string } | undefined)?.text : undefined;
+  const shell = m.type === "user" && typeof text === "string"
+    ? /^\s*<bash-input>([\s\S]*?)<\/bash-input>\s*<bash-stdout>([\s\S]*?)<\/bash-stdout><bash-stderr>([\s\S]*?)<\/bash-stderr>/.exec(text) : null;
+  // Presentation payloads may be abbreviated; lifecycle and attribution must survive.
+  const controlKeys = ["session_id", "parent_agent_id", "timestamp", "isCompactSummary", "isQueuedCommand", "isCompletedLocalCommand", "is_meta", "error", "aborted",
+    "is_error", "total_cost_usd", "turn_cost_usd", "duration_ms", "duration_api_ms", "num_turns", "user_message_uuids",
+    "task_id", "tool_use_id", "parent_task_id", "spawn_depth", "run_id", "status", "subagent_type", "is_backgrounded", "task_type", "patch", "usage", "_streamBlocks", "_streamThinking"];
+  const controls = Object.fromEntries(controlKeys.filter((key) => m[key] !== undefined).map((key) => [key, m[key]]));
+  if (m.errors !== undefined) controls.errors = preview(m.errors);
+  if (m.description !== undefined) controls.description = preview(m.description);
+  if (m.summary !== undefined) controls.summary = preview(m.summary);
+  return { type: m.type, subtype: m.subtype, uuid: m.uuid, parent_tool_use_id: m.parent_tool_use_id,
+    ...controls, ...(shell ? { _bash: { command: shell[1]!.slice(0, 2000), stdout: shell[2]!.slice(0, 2000), stderr: shell[3]!.slice(0, 2000) } } : {}), message: preview(m.message), content: preview(m.content), _deferred: { bytes } };
+}
+
+export function displayEvent(ev: LiveEvent): LiveEvent {
+  if (ev.k === "sdk") return { ...ev, m: displayMessage(ev.m) };
+  if (ev.k === "user" && contentBytes(ev) > PAGE_BYTES / 2) {
+    return { k: "sdk", m: displayMessage({ type: "user", uuid: ev.uuid, message: { role: "user", content: [
+      ...(ev.imageData ?? []).map((i) => ({ type: "image", source: { media_type: i.mediaType, data: i.data } })),
+      { type: "text", text: ev.text },
+    ] } }) };
+  }
+  // Deltas are accumulated before trimming; truncating individual fragments loses their middle.
+  return ev;
+}
+
+export function eventUuid(ev: LiveEvent): string | undefined {
+  return ev.k === "sdk" ? ev.m.uuid : ev.k === "user" || ev.k === "bash" ? ev.uuid : undefined;
+}
+
+type Delta = Extract<LiveEvent, { k: "delta" }>;
+const streamKey = (d: Delta) => `${d.parent ?? ""}:${d.msgId}:${d.index}`;
+const STREAM_BYTES = SESSION_BYTES / 4;
+const STREAM_BLOCK_CHARS = SESSION_BYTES / 16;
+type StreamSettlement = { indexes: number[]; thinking: Record<number, number> };
+
+/** Cumulative previews of unfinished blocks, independent of the replay ring buffer. */
+export class StreamingReplay {
+  private pending = new Map<string, SeqEvent & { ev: Delta }>();
+  private completed = new Set<string>();
+  private settled = new Set<string>();
+  private bytes = 0;
+
+  clear() { this.pending.clear(); this.completed.clear(); this.settled.clear(); this.bytes = 0; }
+  get checkpoints(): SeqEvent[] { return [...this.pending.values()]; }
+
+  push(event: SeqEvent): StreamSettlement {
+    const settled: StreamSettlement = { indexes: [], thinking: {} };
+    const ev = event.ev;
+    if (ev.k === "reset") { this.clear(); return settled; }
+    if (ev.k === "delta") {
+      const key = streamKey(ev);
+      if (this.settled.has(key)) return settled;
+      const previous = this.pending.get(key);
+      const prefix = ev.checkpoint ? "" : previous?.ev.text ?? "";
+      const oldBytes = previous?.ev.text.length ? previous.ev.text.length * 2 : 0;
+      const available = Math.max(0, (STREAM_BYTES - this.bytes + oldBytes) / 2);
+      const limit = Math.min(STREAM_BLOCK_CHARS, available);
+      const text = prefix.length >= limit ? prefix.slice(0, limit) : prefix + ev.text.slice(0, limit - prefix.length);
+      const truncated = !!ev.truncated || !!previous?.ev.truncated && !ev.checkpoint || prefix.length + ev.text.length > limit;
+      this.bytes += text.length * 2 - oldBytes;
+      this.pending.set(key, { seq: event.seq, ev: { ...ev, text, checkpoint: true, ...(truncated ? { truncated: true } : {}) } });
+      // One CLI can only stream a small number of blocks concurrently. Bound identities as well as text.
+      while (this.pending.size > 128) this.remove(this.pending.keys().next().value!);
+    } else if (ev.k === "sdk" && ev.m.type === "assistant") {
+      if (ev.m.uuid) {
+        if (this.completed.has(ev.m.uuid)) return settled;
+        this.completed.add(ev.m.uuid);
+        if (this.completed.size > 5000) this.completed.delete(this.completed.values().next().value!);
+      }
+      const message = ev.m.message as { id?: string; content?: { type?: string }[] } | undefined;
+      if (!message?.id || !Array.isArray(message.content)) return settled;
+      const indexes = Array.isArray(ev.m._streamBlocks) ? ev.m._streamBlocks.filter((index): index is number => typeof index === "number") : [];
+      settled.indexes = indexes;
+      if (indexes.length) {
+        for (const index of indexes) this.settle(`${ev.m.parent_tool_use_id ?? ""}:${message.id}:${index}`);
+        // This metadata was already established before an earlier compaction.
+        if (ev.m._streamThinking) settled.thinking = ev.m._streamThinking as Record<number, number>;
+        return settled;
+      }
+      for (const [blockIndex, block] of message.content.entries()) {
+        if (block.type !== "text" && block.type !== "thinking") continue;
+        const match = [...this.pending].filter(([, d]) => d.ev.msgId === message.id && d.ev.parent === (ev.m.parent_tool_use_id ?? null) && d.ev.kind === block.type)
+          .sort((a, b) => a[1].ev.index - b[1].ev.index)[0];
+        if (match) {
+          indexes.push(match[1].ev.index);
+          if (block.type === "thinking") settled.thinking[blockIndex] = match[1].ev.index;
+          this.settle(match[0]);
+        }
+      }
+      return settled;
+    } else if (ev.k === "sdk" && ev.m.type === "result") {
+      for (const [key, d] of this.pending) if (d.ev.parent === (ev.m.parent_tool_use_id ?? null)) this.remove(key);
+    }
+    return settled;
+  }
+
+  private settle(key: string) {
+    this.remove(key);
+    this.settled.add(key);
+    if (this.settled.size > 5000) this.settled.delete(this.settled.values().next().value!);
+  }
+
+  private remove(key: string) {
+    const entry = this.pending.get(key);
+    if (entry) this.bytes -= entry.ev.text.length * 2;
+    this.pending.delete(key);
+  }
+}
+
+/** Fold streaming fragments before any count/byte slice; active prefixes are reserved at the end. */
+export function compactReplayEvents(events: SeqEvent[], checkpoints: SeqEvent[] = []): SeqEvent[] {
+  const streaming = new StreamingReplay();
+  const out: SeqEvent[] = [];
+  if (checkpoints.length) {
+    const replaced = new Set(checkpoints.flatMap(({ ev }) => ev.k === "delta" ? [streamKey(ev)] : []));
+    // A checkpoint already includes every raw fragment up to its seq. Keep its real
+    // position relative to completion frames, including frames still in the ring.
+    events = [...events.filter(({ ev }) => ev.k !== "delta" || !replaced.has(streamKey(ev))), ...checkpoints].sort((a, b) => a.seq - b.seq);
+  }
+  for (const event of events) {
+    const settled = streaming.push(event);
+    if (event.ev.k !== "delta") out.push(event.ev.k === "sdk" && settled.indexes.length && !event.ev.m._streamBlocks
+      ? { ...event, ev: { ...event.ev, m: { ...event.ev.m, _streamBlocks: settled.indexes,
+        ...(Object.keys(settled.thinking).length ? { _streamThinking: settled.thinking } : {}) } } } : event);
+  }
+  return [...out, ...streaming.checkpoints];
+}
+
+export function compactStreamEvents(events: LiveEvent[]): LiveEvent[] {
+  return compactReplayEvents(events.map((ev, seq) => ({ seq, ev }))).map((entry) => entry.ev);
+}
+
+/** Never bootstrap the browser with the entire 5,000-event server replay buffer. */
+export function boundedReplay(events: SeqEvent[], checkpoints: SeqEvent[] = []): SeqEvent[] {
+  events = compactReplayEvents(events, checkpoints);
+  const out: SeqEvent[] = [];
+  let bytes = 0;
+  for (let i = events.length - 1; i >= 0 && out.length < MESSAGE_LIMIT; i--) {
+    const e = events[i]!;
+    const ev = displayEvent(e.ev);
+    const size = contentBytes(ev);
+    if (bytes + size > SESSION_BYTES / 2) break;
+    out.push({ seq: e.seq, ev });
+    bytes += size;
+  }
+  return out.reverse();
+}

package/shared/project.ts

@@ -0,0 +1,77 @@
+/** REST shapes for M4's project features: per-turn file changes, extra directories, worktrees. */
+
+// ---------- files changed by a turn ----------
+
+export type TurnFileStatus = "A" | "M" | "D";
+
+export type TurnFile = {
+  /** Relative to the session cwd when inside it, absolute otherwise */
+  path: string;
+  status: TurnFileStatus;
+  additions: number;
+  deletions: number;
+  /** Tools of this turn that touched the file (Edit, Write…) */
+  tools: string[];
+  /** Before/after content comes from the CLI's checkpoints; false = only the tool calls' own patches */
+  checkpoint: boolean;
+  /** Touched, but the content at the end of the turn equals the start */
+  unchanged?: boolean;
+};
+
+export type TurnChanges = {
+  /** The user message the CLI checkpointed (file-history-snapshot.messageId) */
+  id: string;
+  /** The visible prompt that started the turn (where the UI anchors it) */
+  prompt: string;
+  files: TurnFile[];
+};
+
+export type TurnChangesInfo = { turns: TurnChanges[] };
+
+export type Hunk = { oldStart: number; newStart: number; lines: string[] };
+
+export type TurnFileDiff = {
+  path: string;
+  status: TurnFileStatus;
+  binary?: boolean;
+  truncated?: boolean;
+  /** Whole-file content before / after the turn (checkpoints); null = file did not exist */
+  before?: string | null;
+  after?: string | null;
+  /** Without checkpoints: the edits' own patches, in order */
+  patches?: Hunk[];
+};
+
+// ---------- extra directories ----------
+
+export type ExtraDirSource = "session" | "local" | "project" | "user";
+
+export type ExtraDir = {
+  path: string;
+  /** session: this session only (sqlite); local/project/user: permissions.additionalDirectories in that settings file */
+  sources: ExtraDirSource[];
+  exists: boolean;
+};
+
+export type ExtraDirsInfo = { cwd: string; dirs: ExtraDir[]; localSettingsFile: string };
+
+// ---------- worktrees ----------
+
+export type WorktreeSession = { id: string; title: string; lastModified: number; draft: boolean };
+
+export type WorktreeInfo = {
+  name: string;
+  path: string;
+  /** Session cwd inside this worktree (path + the project's subdirectory, if any) */
+  cwd: string;
+  branch: string | null;
+  head: string;
+  dirty: boolean;
+  /** Number of changed/untracked files */
+  changes: number;
+  locked: boolean;
+  exists: boolean;
+  sessions: WorktreeSession[];
+};
+
+export type WorktreeList = { isRepo: false } | { isRepo: true; root: string; branch: string | null; worktrees: WorktreeInfo[] };