@mseep/claudian 2.0.25

package/src/core/types/mcp.ts

@@ -0,0 +1,97 @@
+/** MCP (Model Context Protocol) type definitions used by the shared manager/UI. */
+
+/** Stdio server configuration (local command-line programs). */
+export interface McpStdioServerConfig {
+  type?: 'stdio';
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+/** Server-Sent Events remote server configuration. */
+export interface McpSSEServerConfig {
+  type: 'sse';
+  url: string;
+  headers?: Record<string, string>;
+}
+
+/** HTTP remote server configuration. */
+export interface McpHttpServerConfig {
+  type: 'http';
+  url: string;
+  headers?: Record<string, string>;
+}
+
+/** Union type for all MCP server configurations. */
+export type McpServerConfig =
+  | McpStdioServerConfig
+  | McpSSEServerConfig
+  | McpHttpServerConfig;
+
+/** Server type identifier. */
+export type McpServerType = 'stdio' | 'sse' | 'http';
+
+/** Managed MCP server configuration with UI/runtime metadata. */
+export interface ManagedMcpServer {
+  /** Unique server name (key in mcpServers record). */
+  name: string;
+  config: McpServerConfig;
+  enabled: boolean;
+  /** Context-saving mode: hide tools unless @-mentioned. */
+  contextSaving: boolean;
+  /** Tool names disabled for this server. */
+  disabledTools?: string[];
+  description?: string;
+}
+
+/** MCP configuration file format used by the current CLI integrations. */
+export interface McpConfigFile {
+  mcpServers: Record<string, McpServerConfig>;
+}
+
+/** Extended config file with app-owned server metadata. */
+export interface ManagedMcpConfigFile extends McpConfigFile {
+  _claudian?: {
+    /** Per-server UI/runtime settings. */
+    servers: Record<
+      string,
+      {
+        enabled?: boolean;
+        contextSaving?: boolean;
+        disabledTools?: string[];
+        description?: string;
+      }
+    >;
+  };
+}
+
+/** Result of parsing clipboard config. */
+export interface ParsedMcpConfig {
+  servers: Array<{ name: string; config: McpServerConfig }>;
+  needsName: boolean;
+}
+
+export function getMcpServerType(config: McpServerConfig): McpServerType {
+  if (config.type === 'sse') return 'sse';
+  if (config.type === 'http') return 'http';
+  if ('url' in config) return 'http'; // URL without explicit type defaults to http
+  return 'stdio';
+}
+
+export function isValidMcpServerConfig(obj: unknown): obj is McpServerConfig {
+  if (!obj || typeof obj !== 'object') return false;
+  const config = obj as Record<string, unknown>;
+
+  // Check for stdio (command required)
+  if (config.command && typeof config.command === 'string') return true;
+
+  // Check for sse/http (url required, type is optional - defaults to http)
+  if (config.url && typeof config.url === 'string') return true;
+
+  return false;
+}
+
+export const DEFAULT_MCP_SERVER: Omit<ManagedMcpServer, 'name' | 'config'> = {
+  enabled: true,
+  contextSaving: true,
+};

package/src/core/types/plugins.ts

@@ -0,0 +1,9 @@
+export type PluginScope = 'user' | 'project';
+
+export interface PluginInfo {
+  id: string;
+  name: string;
+  enabled: boolean;
+  scope: PluginScope;
+  installPath: string;
+}

package/src/core/types/provider.ts

@@ -0,0 +1 @@
+export type ProviderId = string;

package/src/core/types/settings.ts

@@ -0,0 +1,152 @@
+export type HiddenProviderCommands = Record<string, string[]>;
+
+export interface ApprovalSelectionDecision {
+  type: 'select-option';
+  value: string;
+}
+
+/** User decision from the approval modal. */
+export type ApprovalDecision =
+  | 'allow'
+  | 'allow-always'
+  | 'deny'
+  | 'cancel'
+  | ApprovalSelectionDecision;
+
+/** Saved environment variable configuration. */
+export interface EnvSnippet {
+  id: string;
+  name: string;
+  description: string;
+  envVars: string;
+  scope?: EnvironmentScope;
+  contextLimits?: Record<string, number>;  // Optional: context limits for custom models
+  modelAliases?: Record<string, string>;   // Optional: display aliases for custom models
+}
+
+/** Source of a slash command. */
+export type SlashCommandSource = 'builtin' | 'user' | 'plugin' | 'sdk';
+
+/** Slash command configuration shared by the UI, storage, and runtime boundary. */
+export interface SlashCommand {
+  id: string;
+  name: string;                // Command name used after / (e.g., "review-code")
+  description?: string;        // Optional description shown in dropdown
+  argumentHint?: string;       // Placeholder text for arguments (e.g., "[file] [focus]")
+  allowedTools?: string[];     // Restrict tools when command is used
+  model?: string;              // Optional provider-specific model override
+  content: string;             // Prompt template with placeholders
+  source?: SlashCommandSource; // Origin of the command (builtin, user, plugin, sdk)
+  kind?: 'command' | 'skill';  // Explicit type — replaces id-prefix heuristic
+  // Provider-owned command metadata that the UI preserves and round-trips.
+  disableModelInvocation?: boolean;  // Disable model invocation for this skill
+  userInvocable?: boolean;           // Whether user can invoke this skill directly
+  context?: 'fork';                  // Subagent execution mode
+  agent?: string;                    // Subagent type when context='fork'
+  hooks?: Record<string, unknown>;   // Pass-through to SDK
+}
+
+/** Keyboard navigation settings for vim-style scrolling. */
+export interface KeyboardNavigationSettings {
+  scrollUpKey: string;         // Key to scroll up when focused on messages (default: 'w')
+  scrollDownKey: string;       // Key to scroll down when focused on messages (default: 's')
+  focusInputKey: string;       // Key to focus input (default: 'i', like vim insert mode)
+}
+
+export const CHAT_VIEW_PLACEMENTS = [
+  'right-sidebar',
+  'left-sidebar',
+  'main-tab',
+] as const;
+
+/** Workspace location used when opening the Claudian chat view. */
+export type ChatViewPlacement = typeof CHAT_VIEW_PLACEMENTS[number];
+
+/** Result from instruction refinement agent query. */
+export interface InstructionRefineResult {
+  success: boolean;
+  refinedInstruction?: string;  // The refined instruction text
+  clarification?: string;       // Agent's clarifying question (if any)
+  error?: string;               // Error message (if failed)
+}
+
+/** Permission mode for tool execution. */
+export type PermissionMode = 'yolo' | 'plan' | 'normal';
+
+/** Scope for environment variable storage and snippets. */
+export type EnvironmentScope = 'shared' | `provider:${string}`;
+
+/** Opaque device-keyed CLI paths for per-device configuration. */
+export type HostnameCliPaths = Record<string, string>;
+
+/** Opaque provider-owned settings bags keyed by provider id. */
+export type ProviderConfigMap = Partial<Record<string, Record<string, unknown>>>;
+
+/**
+ * Application settings stored in .claudian/claudian-settings.json.
+ *
+ * Provider-specific fields (model, thinkingBudget, effortLevel, serviceTier, etc.) use
+ * `string` here.  The active provider casts internally when it needs
+ * narrower types.
+ */
+export interface ClaudianSettings {
+  // User preferences
+  userName: string;
+
+  // Security
+  permissionMode: PermissionMode;
+
+  // Model & thinking (provider interprets values)
+  model: string;
+  thinkingBudget: string;
+  effortLevel: string;
+  serviceTier: string;
+  enableAutoTitleGeneration: boolean;
+  titleGenerationModel: string;
+
+  // Content settings
+  excludedTags: string[];
+  mediaFolder: string;
+  systemPrompt: string;
+  persistentExternalContextPaths: string[];
+
+  // Environment
+  sharedEnvironmentVariables: string;
+  envSnippets: EnvSnippet[];
+  customContextLimits: Record<string, number>;
+  customModelAliases: Record<string, string>;
+
+  // UI settings
+  keyboardNavigation: KeyboardNavigationSettings;
+  requireCommandOrControlEnterToSend: boolean;
+
+  // Internationalization
+  locale: string;
+
+  // Provider-owned settings
+  providerConfigs: ProviderConfigMap;
+
+  // Provider selection
+  settingsProvider: string;  // ProviderId — which provider's model/effort/budget is projected to top-level fields
+  savedProviderModel: Partial<Record<string, string>>;
+  savedProviderEffort: Partial<Record<string, string>>;
+  savedProviderServiceTier: Partial<Record<string, string>>;
+  savedProviderThinkingBudget: Partial<Record<string, string>>;
+  savedProviderPermissionMode: Partial<Record<string, string>>;
+
+  // State (provider-specific, round-tripped opaquely)
+  lastCustomModel?: string;
+
+  // UI preferences
+  maxTabs: number;
+  enableAutoScroll: boolean;
+  deferMathRenderingDuringStreaming: boolean;
+  expandFileEditsByDefault: boolean;
+  chatViewPlacement: ChatViewPlacement;
+
+  // Provider command visibility
+  hiddenProviderCommands: HiddenProviderCommands;
+
+  // Allow provider-specific extension fields
+  [key: string]: unknown;
+}

package/src/core/types/tools.ts

@@ -0,0 +1,80 @@
+import type { DiffLine, DiffStats } from './diff';
+
+/** Diff data for Write/Edit tool operations (pre-computed from SDK structuredPatch). */
+export interface ToolDiffData {
+  filePath: string;
+  diffLines: DiffLine[];
+  stats: DiffStats;
+}
+
+/** Parsed option for AskUserQuestion tool. */
+export interface AskUserQuestionOption {
+  label: string;
+  description: string;
+  value?: string;
+}
+
+/** Parsed question for AskUserQuestion tool. */
+export interface AskUserQuestionItem {
+  question: string;
+  id?: string;
+  header: string;
+  options: AskUserQuestionOption[];
+  multiSelect: boolean;
+  isOther?: boolean;
+  isSecret?: boolean;
+}
+
+/** User-provided answers keyed by question text or stable question id. */
+export type AskUserAnswers = Record<string, string | string[]>;
+
+/** Tool call tracking with status and result. */
+export interface ToolCallInfo {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+  status: 'running' | 'completed' | 'error' | 'blocked';
+  result?: string;
+  isExpanded?: boolean;
+  diffData?: ToolDiffData;
+  resolvedAnswers?: AskUserAnswers;
+  subagent?: SubagentInfo;
+}
+
+export type ExitPlanModeDecision =
+  | { type: 'approve' }
+  | { type: 'approve-new-session'; planContent: string }
+  | { type: 'feedback'; text: string };
+
+export type ExitPlanModeCallback = (
+  input: Record<string, unknown>,
+  signal?: AbortSignal,
+) => Promise<ExitPlanModeDecision | null>;
+
+/** Subagent execution mode: sync (nested tools) or async (background). */
+export type SubagentMode = 'sync' | 'async';
+
+/** Async subagent lifecycle states. */
+export type AsyncSubagentStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'error'
+  | 'orphaned';
+
+/** Subagent (Agent tool, legacy Task) tracking for sync and async modes. */
+export interface SubagentInfo {
+  id: string;
+  description: string;
+  prompt?: string;
+  mode?: SubagentMode;
+  isExpanded: boolean;
+  result?: string;
+  status: 'running' | 'completed' | 'error';
+  toolCalls: ToolCallInfo[];
+  asyncStatus?: AsyncSubagentStatus;
+  agentId?: string;
+  outputToolId?: string;
+  startedAt?: number;
+  completedAt?: number;
+}

package/src/features/chat/CLAUDE.md

@@ -0,0 +1,136 @@
+# Chat Feature
+
+Main sidebar chat interface. `ClaudianView` assembles tabs, controllers, renderers, and provider-backed services around the shared `ChatRuntime` boundary.
+
+## Provider Boundary Status
+
+- Chat features depend on `ChatRuntime`, `ProviderCapabilities`, and provider-neutral conversation data. `InputController` builds `ChatTurnRequest`; runtimes own prompt encoding through `prepareTurn()`.
+- Session bookkeeping lives in `Conversation.providerState` and is usually updated through `ChatRuntime.buildSessionUpdates()`, with fork/bootstrap state also seeded through provider history services. Feature code must not read provider-specific fields directly.
+- Provider-owned services are resolved through registries
+  - `ProviderRegistry`: runtime, title generation, instruction refinement, inline edit, task-result interpretation
+  - `ProviderWorkspaceRegistry`: command catalogs, agent mention providers, MCP managers, CLI resolution
+- Current feature split
+  - Claude exposes rewind, instruction mode, runtime command discovery, and in-app MCP controls
+  - Codex exposes fork, history reload, plan mode, instruction mode, images, inline edit, `$` skills, and subagents, but not rewind
+
+## Architecture
+
+```text
+ClaudianView (lifecycle + assembly)
+├── ChatState
+├── Controllers
+│   ├── ConversationController
+│   ├── StreamController
+│   ├── InputController
+│   ├── SelectionController
+│   ├── BrowserSelectionController
+│   ├── CanvasSelectionController
+│   └── NavigationController
+├── Services
+│   ├── SubagentManager
+│   └── BangBashService
+├── Rendering
+│   ├── MessageRenderer
+│   ├── ToolCallRenderer
+│   ├── ThinkingBlockRenderer
+│   ├── WriteEditRenderer
+│   ├── DiffRenderer
+│   ├── TodoListRenderer
+│   ├── SubagentRenderer
+│   ├── InlineExitPlanMode
+│   ├── InlinePlanApproval
+│   └── InlineAskUserQuestion
+├── Tabs
+│   ├── TabManager
+│   ├── TabBar
+│   └── Tab
+└── UI Components
+    ├── InputToolbar
+    ├── FileContextManager
+    ├── ImageContextManager
+    ├── StatusPanel
+    ├── NavigationSidebar
+    ├── InstructionModeManager
+    └── BangBashModeManager
+```
+
+## State Flow
+
+```text
+User Input
+  -> InputController
+  -> ensure runtime for active provider
+  -> ChatRuntime.prepareTurn()
+  -> ChatRuntime.query()
+  -> StreamController
+  -> MessageRenderer + ChatState persistence
+```
+
+The feature layer consumes provider-neutral `StreamChunk` values. Providers own prompt encoding, history/session fallback, and task-result interpretation.
+
+## Controllers
+
+| Controller | Responsibility |
+|------------|----------------|
+| `ConversationController` | Session switching, history reload, save, and rewind |
+| `StreamController` | Consume stream chunks, update streaming state, auto-scroll, abort handling |
+| `InputController` | Text input, mentions, images, resume dispatch, command dispatch, and post-plan approval flow |
+| `SelectionController` | Editor selection polling and CM6 decorations |
+| `BrowserSelectionController` | Browser view selection tracking |
+| `CanvasSelectionController` | Canvas selection tracking |
+| `NavigationController` | Vim-style keyboard navigation |
+
+## Rendering Pipeline
+
+| Renderer | Handles |
+|----------|---------|
+| `MessageRenderer` | Main message orchestration, rewind/fork affordances, interrupt markers |
+| `ToolCallRenderer` | Tool blocks and tool state |
+| `ThinkingBlockRenderer` | Thinking / reasoning summaries |
+| `WriteEditRenderer` | File writes and edits with diff previews |
+| `DiffRenderer` | Inline diff rendering |
+| `InlineExitPlanMode` | Claude tool-driven exit-plan approval |
+| `InlinePlanApproval` | Shared post-plan approval flow driven by consumed turn metadata (currently Codex) |
+| `InlineAskUserQuestion` | Ask-user cards emitted by provider runtimes |
+| `TodoListRenderer` | Todo items and status icons |
+| `SubagentRenderer` | Background agent lifecycle rendering |
+
+## Key Patterns
+
+### Lazy Runtime Initialization
+
+Tabs stay cold until the first send. The tab wiring exposes `ensureServiceInitialized()` so provider runtime creation happens only when needed.
+
+### Message Streaming
+
+```typescript
+const preparedTurn = runtime.prepareTurn(request);
+
+for await (const chunk of runtime.query(preparedTurn, history)) {
+  streamController.handleStreamChunk(chunk);
+}
+```
+
+### Auto-Scroll
+
+- Enabled by default during streaming
+- User scroll-up disables it
+- Scroll-to-bottom re-enables it
+- Resets to the saved setting on a new query
+
+## Gotchas
+
+- `ClaudianView.onClose()` must abort active tabs and dispose runtimes
+- `ChatState` is per-tab; `TabManager` coordinates tab-level operations such as fork targets and provider-aware command catalogs
+- Title generation runs concurrently per conversation and routes by the global title-generation model selection, not by the active chat tab provider
+- `/compact`
+  - Claude skips context injection so the provider recognizes the built-in command and persists the compaction boundary
+  - Codex routes compact turns to `thread/compact/start` and persists the durable `context_compacted` boundary from JSONL history
+- Plan mode
+  - Claude uses provider/runtime events for enter and exit plan mode
+  - Codex sets `collaborationMode` on `turn/start` and triggers shared post-plan approval from consumed turn metadata
+- Bang-bash mode bypasses provider runtimes and executes a local shell command directly
+  - It is available only when an enabled provider exposes it in `ProviderChatUIConfig` (currently Claude)
+- Forking is provider-owned under the hood
+  - Both Claude and Codex support fork
+  - `ChatRuntime.resolveSessionIdForFork()` and provider history services own the provider-specific fork/session mapping