@mseep/claudian 2.0.25

package/src/providers/acp/methodNames.ts

@@ -0,0 +1,50 @@
+export type AcpLogicalMethod =
+  | 'initialize'
+  | 'authenticate'
+  | 'newSession'
+  | 'loadSession'
+  | 'listSessions'
+  | 'prompt'
+  | 'cancel'
+  | 'setMode'
+  | 'setConfigOption';
+
+export type AcpMethodOverrides = Partial<Record<AcpLogicalMethod, string | string[]>>;
+
+const ACP_METHOD_CANDIDATES = {
+  authenticate: ['authenticate'],
+  cancel: ['session/cancel', 'cancel'],
+  initialize: ['initialize'],
+  listSessions: ['session/list', 'listSessions'],
+  loadSession: ['session/load', 'loadSession'],
+  newSession: ['session/new', 'newSession'],
+  prompt: ['session/prompt', 'prompt'],
+  setConfigOption: ['session/set_config_option', 'setSessionConfigOption'],
+  setMode: ['session/set_mode', 'setSessionMode'],
+} as const satisfies Record<AcpLogicalMethod, readonly string[]>;
+
+export const ACP_SERVER_NOTIFICATION_ALIASES = {
+  sessionUpdate: ['session/update', 'sessionUpdate'],
+} as const;
+
+export const ACP_SERVER_REQUEST_ALIASES = {
+  createTerminal: ['terminal/create', 'terminalCreate'],
+  killTerminal: ['terminal/kill', 'terminalKill'],
+  readTextFile: ['fs/read_text_file', 'fs/readTextFile'],
+  releaseTerminal: ['terminal/release', 'terminalRelease'],
+  requestPermission: ['session/request_permission', 'requestPermission'],
+  terminalOutput: ['terminal/output', 'terminalOutput'],
+  waitForTerminalExit: ['terminal/wait_for_exit', 'terminalWaitForExit'],
+  writeTextFile: ['fs/write_text_file', 'fs/writeTextFile'],
+} as const;
+
+export function getAcpMethodCandidates(
+  logicalMethod: AcpLogicalMethod,
+  overrides?: AcpMethodOverrides,
+): string[] {
+  const override = overrides?.[logicalMethod];
+  if (override) {
+    return Array.isArray(override) ? [...override] : [override];
+  }
+  return [...ACP_METHOD_CANDIDATES[logicalMethod]];
+}

package/src/providers/acp/types.ts

@@ -0,0 +1,566 @@
+export const ACP_PROTOCOL_VERSION = 1 as const;
+
+export type AcpProtocolVersion = typeof ACP_PROTOCOL_VERSION;
+export type AcpRequestId = number | string | null;
+export type AcpSessionId = string;
+export type AcpSessionModeId = string;
+export type AcpSessionConfigId = string;
+export type AcpSessionConfigValueId = string;
+export type AcpToolCallId = string;
+export type AcpPermissionOptionId = string;
+export type AcpPositionEncodingKind = 'utf-16' | 'utf-32' | 'utf-8';
+export type AcpRole = 'assistant' | 'user';
+export type AcpStopReason = string;
+
+export interface AcpImplementation {
+  name: string;
+  version: string;
+  title?: string | null;
+}
+
+export interface AcpAuthEnvVar {
+  name: string;
+  label?: string | null;
+  optional?: boolean;
+  secret?: boolean;
+}
+
+export type AcpAuthMethod = {
+  description?: string | null;
+  id: string;
+  name?: string | null;
+} & (
+  | { type?: 'agent' }
+  | { envVars: AcpAuthEnvVar[]; type: 'env_var' }
+  | { args?: string[]; command: string; type: 'terminal' }
+);
+
+export interface AcpFileSystemCapabilities {
+  readTextFile?: boolean;
+  writeTextFile?: boolean;
+}
+
+export interface AcpClientAuthCapabilities {
+  terminal?: boolean;
+}
+
+export interface AcpClientCapabilities {
+  auth?: AcpClientAuthCapabilities;
+  fs?: AcpFileSystemCapabilities;
+  terminal?: boolean;
+  positionEncodings?: AcpPositionEncodingKind[];
+}
+
+export interface AcpPromptCapabilities {
+  audio?: boolean;
+  embeddedContext?: boolean;
+  image?: boolean;
+}
+
+export interface AcpMcpCapabilities {
+  http?: boolean;
+  sse?: boolean;
+}
+
+export interface AcpSessionCapabilities {
+  close?: Record<string, never> | null;
+  fork?: Record<string, never> | null;
+  list?: Record<string, never> | null;
+  resume?: Record<string, never> | null;
+}
+
+export interface AcpAgentCapabilities {
+  auth?: {
+    logout?: Record<string, never> | null;
+  };
+  loadSession?: boolean;
+  mcpCapabilities?: AcpMcpCapabilities;
+  positionEncoding?: AcpPositionEncodingKind | null;
+  promptCapabilities?: AcpPromptCapabilities;
+  sessionCapabilities?: AcpSessionCapabilities;
+}
+
+export interface AcpInitializeRequest {
+  clientCapabilities?: AcpClientCapabilities;
+  clientInfo?: AcpImplementation | null;
+  protocolVersion: AcpProtocolVersion;
+}
+
+export interface AcpInitializeResponse {
+  agentCapabilities?: AcpAgentCapabilities;
+  agentInfo?: AcpImplementation | null;
+  authMethods?: AcpAuthMethod[];
+  protocolVersion: AcpProtocolVersion;
+}
+
+export interface AcpAuthenticateRequest {
+  methodId: string;
+}
+
+export type AcpAuthenticateResponse = Record<string, never>;
+
+export interface AcpEnvVariable {
+  name: string;
+  value: string;
+}
+
+export interface AcpHttpHeader {
+  name: string;
+  value: string;
+}
+
+export type AcpMcpServer =
+  | {
+    type: 'http';
+    headers?: AcpHttpHeader[];
+    name: string;
+    url: string;
+  }
+  | {
+    type: 'sse';
+    headers?: AcpHttpHeader[];
+    name: string;
+    url: string;
+  }
+  | {
+    type?: 'stdio';
+    args: string[];
+    command: string;
+    env?: AcpEnvVariable[];
+    name: string;
+  };
+
+export interface AcpSessionMode {
+  description?: string | null;
+  id: AcpSessionModeId;
+  name: string;
+}
+
+export interface AcpSessionModeState {
+  availableModes: AcpSessionMode[];
+  currentModeId: AcpSessionModeId;
+}
+
+export interface AcpModelInfo {
+  id: string;
+  name: string;
+  description?: string | null;
+}
+
+export interface AcpSessionModelState {
+  availableModels: AcpModelInfo[];
+  currentModelId: string;
+}
+
+export interface AcpSessionConfigSelectOption {
+  description?: string | null;
+  name: string;
+  value: AcpSessionConfigValueId;
+}
+
+export interface AcpSessionConfigSelectGroup {
+  group: string;
+  name: string;
+  options: AcpSessionConfigSelectOption[];
+}
+
+export type AcpSessionConfigSelectOptions =
+  | AcpSessionConfigSelectOption[]
+  | AcpSessionConfigSelectGroup[];
+
+export type AcpSessionConfigOption = {
+  category?: string | null;
+  description?: string | null;
+  id: AcpSessionConfigId;
+  name: string;
+} & (
+  | { type: 'boolean'; value: boolean }
+  | {
+    currentValue: AcpSessionConfigValueId;
+    options: AcpSessionConfigSelectOptions;
+    type: 'select';
+  }
+);
+
+export interface AcpNewSessionRequest {
+  additionalDirectories?: string[];
+  cwd: string;
+  mcpServers: AcpMcpServer[];
+}
+
+export interface AcpNewSessionResponse {
+  configOptions?: AcpSessionConfigOption[] | null;
+  models?: AcpSessionModelState | null;
+  modes?: AcpSessionModeState | null;
+  sessionId: AcpSessionId;
+}
+
+export interface AcpLoadSessionRequest {
+  additionalDirectories?: string[];
+  cwd: string;
+  mcpServers: AcpMcpServer[];
+  sessionId: AcpSessionId;
+}
+
+export interface AcpLoadSessionResponse {
+  configOptions?: AcpSessionConfigOption[] | null;
+  models?: AcpSessionModelState | null;
+  modes?: AcpSessionModeState | null;
+  sessionId: AcpSessionId;
+}
+
+export interface AcpListSessionsRequest {
+  additionalDirectories?: string[];
+  cursor?: string | null;
+  cwd?: string | null;
+}
+
+export interface AcpSessionInfo {
+  sessionId: AcpSessionId;
+  title?: string | null;
+  updatedAt?: string | null;
+}
+
+export interface AcpListSessionsResponse {
+  nextCursor?: string | null;
+  sessions: AcpSessionInfo[];
+}
+
+export interface AcpTextContent {
+  type: 'text';
+  text: string;
+}
+
+export interface AcpImageContent {
+  data: string;
+  mimeType: string;
+  type: 'image';
+  uri?: string | null;
+}
+
+export interface AcpAudioContent {
+  data: string;
+  mimeType: string;
+  type: 'audio';
+}
+
+export interface AcpResourceLink {
+  description?: string | null;
+  mimeType?: string | null;
+  name: string;
+  size?: number | null;
+  title?: string | null;
+  type: 'resource_link';
+  uri: string;
+}
+
+export type AcpEmbeddedResource =
+  | {
+    resource: {
+      mimeType?: string | null;
+      text: string;
+      uri: string;
+    };
+    type: 'resource';
+  }
+  | {
+    resource: {
+      blob: string;
+      mimeType?: string | null;
+      uri: string;
+    };
+    type: 'resource';
+  };
+
+export type AcpContentBlock =
+  | AcpTextContent
+  | AcpImageContent
+  | AcpAudioContent
+  | AcpResourceLink
+  | AcpEmbeddedResource;
+
+export interface AcpPromptRequest {
+  messageId?: string | null;
+  prompt: AcpContentBlock[];
+  sessionId: AcpSessionId;
+}
+
+export interface AcpUsage {
+  cachedReadTokens?: number | null;
+  cachedWriteTokens?: number | null;
+  inputTokens: number;
+  outputTokens: number;
+  thoughtTokens?: number | null;
+  totalTokens: number;
+}
+
+export interface AcpPromptResponse {
+  stopReason: AcpStopReason;
+  usage?: AcpUsage | null;
+  userMessageId?: string | null;
+}
+
+export interface AcpCancelNotification {
+  sessionId: AcpSessionId;
+}
+
+export interface AcpSetSessionModeRequest {
+  modeId: AcpSessionModeId;
+  sessionId: AcpSessionId;
+}
+
+export type AcpSetSessionModeResponse = Record<string, never>;
+
+export type AcpSetSessionConfigOptionRequest =
+  | {
+    configId: AcpSessionConfigId;
+    sessionId: AcpSessionId;
+    type: 'boolean';
+    value: boolean;
+  }
+  | {
+    configId: AcpSessionConfigId;
+    sessionId: AcpSessionId;
+    type: 'select';
+    value: AcpSessionConfigValueId;
+  };
+
+export interface AcpSetSessionConfigOptionResponse {
+  configOptions: AcpSessionConfigOption[];
+}
+
+export interface AcpContentChunk {
+  content: AcpContentBlock;
+  messageId?: string | null;
+}
+
+export type AcpToolKind =
+  | 'read'
+  | 'edit'
+  | 'delete'
+  | 'move'
+  | 'search'
+  | 'execute'
+  | 'think'
+  | 'fetch'
+  | 'switch_mode'
+  | 'other';
+
+export type AcpToolCallStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
+
+export interface AcpDiffToolContent {
+  newText: string;
+  oldText?: string | null;
+  path: string;
+  type: 'diff';
+}
+
+export interface AcpTerminalToolContent {
+  terminalId: string;
+  type: 'terminal';
+}
+
+export interface AcpWrappedContentToolContent {
+  content: AcpContentBlock;
+  type: 'content';
+}
+
+export type AcpToolCallContent =
+  | AcpDiffToolContent
+  | AcpTerminalToolContent
+  | AcpWrappedContentToolContent;
+
+export interface AcpToolCallLocation {
+  line?: number | null;
+  path: string;
+}
+
+export interface AcpToolCall {
+  content?: AcpToolCallContent[];
+  kind?: AcpToolKind | null;
+  locations?: AcpToolCallLocation[];
+  rawInput?: unknown;
+  rawOutput?: unknown;
+  status?: AcpToolCallStatus | null;
+  title: string;
+  toolCallId: AcpToolCallId;
+}
+
+export interface AcpToolCallUpdate {
+  content?: AcpToolCallContent[] | null;
+  kind?: AcpToolKind | null;
+  locations?: AcpToolCallLocation[] | null;
+  rawInput?: unknown;
+  rawOutput?: unknown;
+  status?: AcpToolCallStatus | null;
+  title?: string | null;
+  toolCallId: AcpToolCallId;
+}
+
+export type AcpPlanEntryPriority = 'high' | 'medium' | 'low';
+export type AcpPlanEntryStatus = 'pending' | 'in_progress' | 'completed';
+
+export interface AcpPlanEntry {
+  content: string;
+  priority: AcpPlanEntryPriority;
+  status: AcpPlanEntryStatus;
+}
+
+export interface AcpPlan {
+  entries: AcpPlanEntry[];
+}
+
+export interface AcpAvailableCommandInput {
+  hint: string;
+}
+
+export interface AcpAvailableCommand {
+  description?: string | null;
+  input?: AcpAvailableCommandInput | null;
+  name: string;
+}
+
+export interface AcpAvailableCommandsUpdate {
+  availableCommands: AcpAvailableCommand[];
+}
+
+export interface AcpCurrentModeUpdate {
+  currentModeId: AcpSessionModeId;
+}
+
+export interface AcpConfigOptionUpdate {
+  configOptions: AcpSessionConfigOption[];
+}
+
+export interface AcpSessionInfoUpdate {
+  title?: string | null;
+  updatedAt?: string | null;
+}
+
+export interface AcpUsageUpdate {
+  cost?: {
+    amount: number;
+    currency: string;
+  } | null;
+  size: number;
+  used: number;
+}
+
+export type AcpSessionUpdate =
+  | (AcpContentChunk & { sessionUpdate: 'user_message_chunk' })
+  | (AcpContentChunk & { sessionUpdate: 'agent_message_chunk' })
+  | (AcpContentChunk & { sessionUpdate: 'agent_thought_chunk' })
+  | (AcpToolCall & { sessionUpdate: 'tool_call' })
+  | (AcpToolCallUpdate & { sessionUpdate: 'tool_call_update' })
+  | (AcpPlan & { sessionUpdate: 'plan' })
+  | (AcpAvailableCommandsUpdate & { sessionUpdate: 'available_commands_update' })
+  | (AcpCurrentModeUpdate & { sessionUpdate: 'current_mode_update' })
+  | (AcpConfigOptionUpdate & { sessionUpdate: 'config_option_update' })
+  | (AcpSessionInfoUpdate & { sessionUpdate: 'session_info_update' })
+  | (AcpUsageUpdate & { sessionUpdate: 'usage_update' });
+
+export interface AcpSessionNotification {
+  sessionId: AcpSessionId;
+  update: AcpSessionUpdate;
+}
+
+export type AcpPermissionOptionKind =
+  | 'allow_once'
+  | 'allow_always'
+  | 'reject_once'
+  | 'reject_always';
+
+export interface AcpPermissionOption {
+  kind: AcpPermissionOptionKind;
+  name: string;
+  optionId: AcpPermissionOptionId;
+}
+
+export interface AcpRequestPermissionRequest {
+  options: AcpPermissionOption[];
+  sessionId: AcpSessionId;
+  toolCall: AcpToolCallUpdate;
+}
+
+export type AcpRequestPermissionResponse = {
+  outcome:
+    | {
+      outcome: 'cancelled';
+    }
+    | {
+      optionId: AcpPermissionOptionId;
+      outcome: 'selected';
+    };
+};
+
+export interface AcpReadTextFileRequest {
+  limit?: number | null;
+  line?: number | null;
+  path: string;
+  sessionId: AcpSessionId;
+}
+
+export interface AcpReadTextFileResponse {
+  content: string;
+}
+
+export interface AcpWriteTextFileRequest {
+  content: string;
+  path: string;
+  sessionId: AcpSessionId;
+}
+
+export type AcpWriteTextFileResponse = Record<string, never>;
+
+export interface AcpCreateTerminalRequest {
+  args?: string[];
+  command: string;
+  cwd?: string | null;
+  env?: AcpEnvVariable[];
+  outputByteLimit?: number | null;
+  sessionId: AcpSessionId;
+}
+
+export interface AcpCreateTerminalResponse {
+  terminalId: string;
+}
+
+export interface AcpTerminalOutputRequest {
+  sessionId: AcpSessionId;
+  terminalId: string;
+}
+
+export interface AcpTerminalExitStatus {
+  exitCode?: number | null;
+  signal?: string | null;
+}
+
+export interface AcpTerminalOutputResponse {
+  exitStatus?: AcpTerminalExitStatus | null;
+  output: string;
+  truncated: boolean;
+}
+
+export interface AcpWaitForTerminalExitRequest {
+  sessionId: AcpSessionId;
+  terminalId: string;
+}
+
+export interface AcpWaitForTerminalExitResponse {
+  exitCode?: number | null;
+  signal?: string | null;
+}
+
+export interface AcpKillTerminalRequest {
+  sessionId: AcpSessionId;
+  terminalId: string;
+}
+
+export type AcpKillTerminalResponse = Record<string, never>;
+
+export interface AcpReleaseTerminalRequest {
+  sessionId: AcpSessionId;
+  terminalId: string;
+}
+
+export type AcpReleaseTerminalResponse = Record<string, never>;

package/src/providers/claude/CLAUDE.md

@@ -0,0 +1,78 @@
+# Claude Provider
+
+SDK adaptor wrapping `@anthropic-ai/claude-agent-sdk` behind `ChatRuntime`, with Claude Code CLI compatibility layered around it.
+
+## Design Decisions
+
+### Persistent Query — Why Not Restart
+
+The persistent query stays alive across turns. Model, permission mode, MCP servers, and effort level are updated dynamically via SDK API calls (`setModel`, `setPermissionMode`, `setMcpServers`, `applyFlagSettings`). Restart is required when the effective system prompt, disabled-tool set, plugin set, settings source set, CLI path, Chrome enablement, or external context paths change.
+
+### Text Deduplication
+
+The SDK delivers assistant text twice: incrementally via `stream_event/content_block_delta`, and again as complete text in the `assistant` message. The handler tracks `sawStreamText` — if stream events were seen, the assistant message's text blocks are skipped. Without this, every response would render double.
+
+### Usage Chunk Two-Phase Buffering
+
+Usage info comes from two SDK messages:
+1. **Assistant message**: accurate input-side token counts (`input_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`), but only from main-agent messages (`parent_tool_use_id === null` filter) — subagent messages are excluded to avoid inflated counts
+2. **Result message**: authoritative `contextWindow` from `modelUsage` that corrects the estimated percentage
+
+Using result-message token counts would be wrong because they aggregate across subagents. Using assistant-message context window would be wrong because it's estimated. The two-phase merge gets the input-side counts plus the final context-window value.
+
+### Custom Spawn — Electron Workarounds
+
+`createCustomSpawnFunction()` works around two Obsidian/Electron-specific issues:
+- Resolves `node` to a full path because GUI apps don't inherit shell PATH
+- Does NOT pass `signal` to `spawn()` — Obsidian's Electron uses a different `AbortSignal` realm that breaks Node's internal `instanceof` check; manually calls `child.kill()` on abort instead
+
+## Non-Obvious Behaviors
+
+### SDK Amnesia Detection
+
+When the SDK returns a different session ID than the one provided in `resume`, `SessionManager.captureSession()` sets `needsHistoryRebuild = true`. `ClaudeChatRuntime` detects this and injects full conversation history into the next user message before dispatching the turn. This handles the case where the SDK silently lost context without explicit error signaling.
+
+**Fork interaction**: on the first `session_init` after a fork, `clearHistoryRebuild()` prevents the amnesia logic from triggering — the SDK legitimately returns a different session ID for forks.
+
+### Crash Recovery
+
+On consumer loop error, if `!crashRecoveryAttempted && lastSentMessage && !handler.sawAnyChunk` (first failure, message was sent, nothing was streamed yet): restart the persistent query with `preserveHandlers: true` and re-enqueue the message. Single retry only — second failure surfaces the error.
+
+### Auto-Triggered Turns
+
+The SDK can send messages without a registered handler (e.g., background subagent completion notifications). These chunks buffer in `_autoTurnBuffer` and deliver via `_autoTurnCallback` on the `result` event.
+
+### MessageChannel Queue
+
+- Text-only messages merge with `\n\n` up to 12000 chars while a turn is active (fast follow-up messages coalesce)
+- Attachment messages replace the previous queued attachment (one at a time)
+- Queue overflow beyond 8 messages drops the newest
+
+### Branch Filtering
+
+SDK session files are tree-structured — rewind + re-prompt creates branches. `sdkBranchFilter` finds the canonical branch by locating the latest leaf, walking ancestry to root, then including non-user-branch siblings (tool results belonging to ancestors). This is the most algorithmically complex part of the history layer.
+
+## Storage Traps
+
+### CC Settings Merge
+
+`CCSettingsStorage.save()` reads the existing `.claude/settings.json` first and merges — it only manages `permissions` and `enabledPlugins`. Without the merge, saving would clobber CC-owned fields (model, env, MCP settings) that users set via the CLI.
+
+### MCP Dual-Namespace
+
+`.claude/mcp.json` stores servers in two namespaces: `mcpServers` (CC-compatible, read by the CLI) and `_claudian.servers` (Claudian metadata: enabled, contextSaving, disabledTools, description). CC ignores the `_claudian` key. This avoids polluting the CC-compatible format with Claudian-specific data.
+
+### Plugin Dual-Write
+
+Plugin enabled state is written to both `.claude/settings.json` (so the CC CLI also respects it) and kept in `PluginManager.plugins[].enabled` (for Claudian's restart check). These must stay in sync.
+
+### Slash Command ID Encoding
+
+Dashes are escaped as `-_`, slashes become `--`. This is a reversible encoding for subdirectory support: `a/b-c.md` → `cmd-a--b-_c`.
+
+## Gotchas
+
+- `DISABLED_BUILTIN_SUBAGENTS = ['Task(statusline-setup)']` — disabled because it has no meaning in Obsidian
+- `previousProviderSessionIds` tracks all prior SDK sessions for a conversation (e.g., after forks). All are loaded during history hydration to build the complete message set — not just the current session
+- `EnterPlanMode` never hits `canUseTool` — the SDK auto-approves it; the runtime detects it in the stream to sync UI. `ExitPlanMode` does go through `canUseTool`
+- Context window `selectContextWindowEntry()` handles multi-model scenarios (subagent uses different model) by matching model signatures — exact match first, then family match (haiku/sonnet/opus + 1M flag), null if ambiguous