@mseep/claudian 2.0.25

package/src/core/tools/toolInput.ts

@@ -0,0 +1,119 @@
+/**
+ * Tool input helpers.
+ *
+ * Keeps parsing of common tool inputs consistent across services.
+ */
+
+import type { AskUserAnswers } from '../types/tools';
+import {
+  TOOL_EDIT,
+  TOOL_GLOB,
+  TOOL_GREP,
+  TOOL_LS,
+  TOOL_NOTEBOOK_EDIT,
+  TOOL_READ,
+  TOOL_WRITE,
+} from './toolNames';
+
+export function extractResolvedAnswers(toolUseResult: unknown): AskUserAnswers | undefined {
+  if (typeof toolUseResult !== 'object' || toolUseResult === null) return undefined;
+  const r = toolUseResult as Record<string, unknown>;
+  return normalizeAnswersObject(r.answers);
+}
+
+function normalizeAnswerValue(value: unknown): string | string[] | undefined {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) {
+    const normalized = value
+      .map((item) => (typeof item === 'string' ? item : String(item)))
+      .filter(Boolean)
+      .filter((item) => item.length > 0);
+    if (normalized.length === 0) return undefined;
+    return normalized.length === 1 ? normalized[0] : normalized;
+  }
+  if (typeof value === 'object' && value !== null) {
+    const record = value as Record<string, unknown>;
+    if ('answers' in record) return normalizeAnswerValue(record.answers);
+    if ('answer' in record) return normalizeAnswerValue(record.answer);
+    if ('value' in record) return normalizeAnswerValue(record.value);
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return undefined;
+}
+
+function normalizeAnswersObject(value: unknown): AskUserAnswers | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+
+  const answers: AskUserAnswers = {};
+  for (const [question, rawValue] of Object.entries(value as Record<string, unknown>)) {
+    const normalized = normalizeAnswerValue(rawValue);
+    if (normalized) {
+      answers[question] = normalized;
+    }
+  }
+
+  return Object.keys(answers).length > 0 ? answers : undefined;
+}
+
+function parseAnswersFromJsonObject(resultText: string): AskUserAnswers | undefined {
+  const start = resultText.indexOf('{');
+  const end = resultText.lastIndexOf('}');
+  if (start < 0 || end <= start) return undefined;
+
+  try {
+    const parsed = JSON.parse(resultText.slice(start, end + 1)) as unknown;
+    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+      const record = parsed as Record<string, unknown>;
+      return normalizeAnswersObject(record.answers) ?? normalizeAnswersObject(parsed);
+    }
+    return normalizeAnswersObject(parsed);
+  } catch {
+    return undefined;
+  }
+}
+
+function parseAnswersFromQuotedPairs(resultText: string): AskUserAnswers | undefined {
+  const answers: AskUserAnswers = {};
+  const pattern = /"([^"]+)"="([^"]*)"/g;
+
+  for (const match of resultText.matchAll(pattern)) {
+    const question = match[1]?.trim();
+    if (!question) continue;
+    answers[question] = match[2] ?? '';
+  }
+
+  return Object.keys(answers).length > 0 ? answers : undefined;
+}
+
+/**
+ * Fallback extractor for AskUserQuestion results when structured `toolUseResult.answers`
+ * is unavailable (for example after reload from JSONL history).
+ */
+export function extractResolvedAnswersFromResultText(result: unknown): AskUserAnswers | undefined {
+  if (typeof result !== 'string') return undefined;
+  const trimmed = result.trim();
+  if (!trimmed) return undefined;
+
+  return parseAnswersFromJsonObject(trimmed) ?? parseAnswersFromQuotedPairs(trimmed);
+}
+
+export function getPathFromToolInput(
+  toolName: string,
+  toolInput: Record<string, unknown>
+): string | null {
+  switch (toolName) {
+    case TOOL_READ:
+    case TOOL_WRITE:
+    case TOOL_EDIT:
+    case TOOL_NOTEBOOK_EDIT:
+      return (toolInput.file_path as string) || (toolInput.notebook_path as string) || null;
+    case TOOL_GLOB:
+      return (toolInput.path as string) || (toolInput.pattern as string) || null;
+    case TOOL_GREP:
+      return (toolInput.path as string) || null;
+    case TOOL_LS:
+      return (toolInput.path as string) || null;
+    default:
+      return null;
+  }
+}

package/src/core/tools/toolNames.ts

@@ -0,0 +1,149 @@
+export const TOOL_AGENT_OUTPUT = 'TaskOutput' as const;
+export const TOOL_ASK_USER_QUESTION = 'AskUserQuestion' as const;
+export const TOOL_BASH = 'Bash' as const;
+export const TOOL_BASH_OUTPUT = 'BashOutput' as const;
+export const TOOL_EDIT = 'Edit' as const;
+export const TOOL_GLOB = 'Glob' as const;
+export const TOOL_GREP = 'Grep' as const;
+export const TOOL_KILL_SHELL = 'KillShell' as const;
+export const TOOL_LS = 'LS' as const;
+export const TOOL_LIST_MCP_RESOURCES = 'ListMcpResources' as const;
+export const TOOL_MCP = 'Mcp' as const;
+export const TOOL_NOTEBOOK_EDIT = 'NotebookEdit' as const;
+export const TOOL_READ = 'Read' as const;
+export const TOOL_READ_MCP_RESOURCE = 'ReadMcpResource' as const;
+export const TOOL_SKILL = 'Skill' as const;
+export const TOOL_SUBAGENT = 'Agent' as const;
+export const TOOL_SUBAGENT_LEGACY = 'Task' as const;
+// Kept as an alias while the internal codebase is still named around "Task".
+export const TOOL_TASK = TOOL_SUBAGENT;
+export const TOOL_TODO_WRITE = 'TodoWrite' as const;
+export const TOOL_TOOL_SEARCH = 'ToolSearch' as const;
+export const TOOL_WEB_FETCH = 'WebFetch' as const;
+export const TOOL_WEB_SEARCH = 'WebSearch' as const;
+export const TOOL_WRITE = 'Write' as const;
+
+export const TOOL_ENTER_PLAN_MODE = 'EnterPlanMode' as const;
+export const TOOL_EXIT_PLAN_MODE = 'ExitPlanMode' as const;
+
+// Runtime-managed tools exposed through provider adapters.
+export const TOOL_APPLY_PATCH = 'apply_patch' as const;
+export const TOOL_WRITE_STDIN = 'write_stdin' as const;
+export const TOOL_SPAWN_AGENT = 'spawn_agent' as const;
+export const TOOL_SEND_INPUT = 'send_input' as const;
+export const TOOL_WAIT = 'wait' as const;
+export const TOOL_WAIT_AGENT = 'wait_agent' as const;
+export const TOOL_RESUME_AGENT = 'resume_agent' as const;
+export const TOOL_CLOSE_AGENT = 'close_agent' as const;
+
+export const AGENT_LIFECYCLE_TOOLS = [
+  TOOL_SPAWN_AGENT,
+  TOOL_SEND_INPUT,
+  TOOL_WAIT,
+  TOOL_WAIT_AGENT,
+  TOOL_RESUME_AGENT,
+  TOOL_CLOSE_AGENT,
+] as const;
+
+export function isAgentLifecycleTool(name: string): boolean {
+  return (AGENT_LIFECYCLE_TOOLS as readonly string[]).includes(name);
+}
+
+/** Tools that should be hidden from rendering when a provider subagent block is shown. */
+export const SUBAGENT_HIDDEN_TOOLS = [
+  TOOL_WAIT,
+  TOOL_WAIT_AGENT,
+  TOOL_CLOSE_AGENT,
+] as const;
+
+export function isSubagentSpawnTool(name: string): boolean {
+  return name === TOOL_SPAWN_AGENT;
+}
+
+export function isSubagentHiddenTool(name: string): boolean {
+  return (SUBAGENT_HIDDEN_TOOLS as readonly string[]).includes(name);
+}
+
+// These tools resolve via dedicated callbacks (not content-based), so their
+// tool_result should never be marked "blocked" based on result text.
+export const TOOLS_SKIP_BLOCKED_DETECTION = [
+  TOOL_ENTER_PLAN_MODE,
+  TOOL_EXIT_PLAN_MODE,
+  TOOL_ASK_USER_QUESTION,
+] as const;
+
+export const SUBAGENT_TOOL_NAMES = [
+  TOOL_SUBAGENT,
+  TOOL_SUBAGENT_LEGACY,
+] as const;
+export type SubagentToolName = (typeof SUBAGENT_TOOL_NAMES)[number];
+
+export function skipsBlockedDetection(name: string): boolean {
+  return (TOOLS_SKIP_BLOCKED_DETECTION as readonly string[]).includes(name);
+}
+
+export function isSubagentToolName(name: string): name is SubagentToolName {
+  return (SUBAGENT_TOOL_NAMES as readonly string[]).includes(name);
+}
+
+export const EDIT_TOOLS = [TOOL_WRITE, TOOL_EDIT, TOOL_NOTEBOOK_EDIT] as const;
+export type EditToolName = (typeof EDIT_TOOLS)[number];
+
+export const WRITE_EDIT_TOOLS = [TOOL_WRITE, TOOL_EDIT] as const;
+export type WriteEditToolName = (typeof WRITE_EDIT_TOOLS)[number];
+
+export const BASH_TOOLS = [TOOL_BASH, TOOL_BASH_OUTPUT, TOOL_KILL_SHELL] as const;
+export type BashToolName = (typeof BASH_TOOLS)[number];
+
+export const FILE_TOOLS = [
+  TOOL_READ,
+  TOOL_WRITE,
+  TOOL_EDIT,
+  TOOL_GLOB,
+  TOOL_GREP,
+  TOOL_LS,
+  TOOL_NOTEBOOK_EDIT,
+  TOOL_BASH,
+] as const;
+export type FileToolName = (typeof FILE_TOOLS)[number];
+
+export const MCP_TOOLS = [
+  TOOL_LIST_MCP_RESOURCES,
+  TOOL_READ_MCP_RESOURCE,
+  TOOL_MCP,
+] as const;
+export type McpToolName = (typeof MCP_TOOLS)[number];
+
+export const READ_ONLY_TOOLS = [
+  TOOL_READ,
+  TOOL_GREP,
+  TOOL_GLOB,
+  TOOL_LS,
+  TOOL_WEB_SEARCH,
+  TOOL_WEB_FETCH,
+] as const;
+export type ReadOnlyToolName = (typeof READ_ONLY_TOOLS)[number];
+
+export function isEditTool(toolName: string): toolName is EditToolName {
+  return (EDIT_TOOLS as readonly string[]).includes(toolName);
+}
+
+export function isWriteEditTool(toolName: string): toolName is WriteEditToolName {
+  return (WRITE_EDIT_TOOLS as readonly string[]).includes(toolName);
+}
+
+export function isFileTool(toolName: string): toolName is FileToolName {
+  return (FILE_TOOLS as readonly string[]).includes(toolName);
+}
+
+export function isBashTool(toolName: string): toolName is BashToolName {
+  return (BASH_TOOLS as readonly string[]).includes(toolName);
+}
+
+export function isMcpTool(toolName: string): toolName is McpToolName {
+  return (MCP_TOOLS as readonly string[]).includes(toolName);
+}
+
+export function isReadOnlyTool(toolName: string): toolName is ReadOnlyToolName {
+  return (READ_ONLY_TOOLS as readonly string[]).includes(toolName);
+}

package/src/core/tools/toolResultContent.ts

@@ -0,0 +1,26 @@
+export interface ToolResultContentOptions {
+  fallbackIndent?: number;
+}
+
+export function extractToolResultContent(
+  content: unknown,
+  options?: ToolResultContentOptions,
+): string {
+  if (typeof content === 'string') return content;
+  if (content == null) return '';
+
+  if (Array.isArray(content)) {
+    const textParts = content.filter(isTextBlock).map((block) => block.text);
+    if (textParts.length > 0) return textParts.join('\n');
+    if (content.length > 0) return JSON.stringify(content, null, options?.fallbackIndent);
+    return '';
+  }
+
+  return JSON.stringify(content, null, options?.fallbackIndent);
+}
+
+function isTextBlock(block: unknown): block is { type: 'text'; text: string } {
+  if (!block || typeof block !== 'object') return false;
+  const record = block as Record<string, unknown>;
+  return record.type === 'text' && typeof record.text === 'string';
+}

package/src/core/types/agent.ts

@@ -0,0 +1,28 @@
+export interface AgentDefinition {
+  id: string;
+  name: string;
+  description: string;
+  prompt: string;
+  tools?: string[];
+  disallowedTools?: string[];
+  model?: string;
+  source: 'plugin' | 'vault' | 'global' | 'builtin';
+  pluginName?: string;
+  filePath?: string;
+  skills?: string[];
+  permissionMode?: string;
+  hooks?: Record<string, unknown>;
+  extraFrontmatter?: Record<string, unknown>;
+}
+
+export interface AgentFrontmatter {
+  name: string;
+  description: string;
+  tools?: string | string[];
+  disallowedTools?: string | string[];
+  model?: string;
+  skills?: string[];
+  permissionMode?: string;
+  hooks?: Record<string, unknown>;
+  extraFrontmatter?: Record<string, unknown>;
+}

package/src/core/types/chat.ts

@@ -0,0 +1,177 @@
+import type { SDKToolUseResult } from './diff';
+import type { ProviderId } from './provider';
+import type { SubagentMode, ToolCallInfo } from './tools';
+
+/** Fork origin reference: identifies the source session and checkpoint. */
+export interface ForkSource {
+  sessionId: string;
+  resumeAt: string;
+}
+
+/** View type identifier for Obsidian. */
+export const VIEW_TYPE_CLAUDIAN = 'claudian-view';
+
+/** Supported image media types for attachments. */
+export type ImageMediaType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+
+/** Image attachment metadata. */
+export interface ImageAttachment {
+  id: string;
+  name: string;
+  mediaType: ImageMediaType;
+  /** Base64 encoded image data - single source of truth. */
+  data: string;
+  width?: number;
+  height?: number;
+  size: number;
+  source: 'file' | 'paste' | 'drop';
+}
+
+/** Content block for preserving streaming order in messages. */
+export type ContentBlock =
+  | { type: 'text'; content: string }
+  | { type: 'tool_use'; toolId: string }
+  | { type: 'thinking'; content: string; durationSeconds?: number }
+  | { type: 'subagent'; subagentId: string; mode?: SubagentMode }
+  | { type: 'context_compacted' };
+
+/** Chat message with content, tool calls, and attachments. */
+export interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  /** Display-only content (e.g., "/tests" when content is the expanded prompt). */
+  displayContent?: string;
+  timestamp: number;
+  toolCalls?: ToolCallInfo[];
+  contentBlocks?: ContentBlock[];
+  currentNote?: string;
+  images?: ImageAttachment[];
+  /** True if this message represents a user interrupt (from SDK storage). */
+  isInterrupt?: boolean;
+  /** True if this message is rebuilt context sent to SDK on session reset (should be hidden). */
+  isRebuiltContext?: boolean;
+  /** Duration in seconds from user send to response completion. */
+  durationSeconds?: number;
+  /** Flavor word used for duration display (e.g., "Baked", "Cooked"). */
+  durationFlavorWord?: string;
+  /** Provider-native user message identifier used for rewind. */
+  userMessageId?: string;
+  /** Provider-native assistant message identifier used for rewind/fork checkpoints. */
+  assistantMessageId?: string;
+}
+
+/** Persisted conversation with messages and session state. */
+export interface Conversation {
+  id: string;
+  providerId: ProviderId;
+  title: string;
+  createdAt: number;
+  updatedAt: number;
+  /** Timestamp when the last agent response completed. */
+  lastResponseAt?: number;
+  sessionId: string | null;
+  /** Opaque provider-owned state bag (session tracking, fork metadata, etc.). */
+  providerState?: Record<string, unknown>;
+  messages: ChatMessage[];
+  currentNote?: string;
+  /** Session-specific external context paths (directories with full access). Resets on new session. */
+  externalContextPaths?: string[];
+  /** Context window usage information. */
+  usage?: UsageInfo;
+  /** Status of AI title generation. */
+  titleGenerationStatus?: 'pending' | 'success' | 'failed';
+  /** UI-enabled MCP servers for this session (context-saving servers activated via selector). */
+  enabledMcpServers?: string[];
+  /** Assistant checkpoint identifier for resumeAtMessageId after rewind. */
+  resumeAtMessageId?: string;
+}
+
+/** Lightweight conversation metadata for the history dropdown. */
+export interface ConversationMeta {
+  id: string;
+  providerId: ProviderId;
+  title: string;
+  createdAt: number;
+  updatedAt: number;
+  /** Timestamp when the last agent response completed. */
+  lastResponseAt?: number;
+  messageCount: number;
+  preview: string;
+  /** Status of AI title generation. */
+  titleGenerationStatus?: 'pending' | 'success' | 'failed';
+}
+
+/**
+ * Session metadata overlay for provider-native storage.
+ * The provider handles message storage; this stores UI-only state.
+ */
+export interface SessionMetadata {
+  id: string;
+  providerId?: ProviderId;
+  title: string;
+  titleGenerationStatus?: 'pending' | 'success' | 'failed';
+  createdAt: number;
+  updatedAt: number;
+  lastResponseAt?: number;
+  /** Session ID used for provider resume (may be cleared when invalidated). */
+  sessionId?: string | null;
+  /** Opaque provider-owned state bag. */
+  providerState?: Record<string, unknown>;
+  currentNote?: string;
+  externalContextPaths?: string[];
+  enabledMcpServers?: string[];
+  usage?: UsageInfo;
+  /** Assistant checkpoint identifier for resumeAtMessageId after rewind. */
+  resumeAtMessageId?: string;
+}
+
+/**
+ * Normalized stream chunk emitted by the active provider runtime.
+ *
+ * All providers must emit: text, tool_use, tool_result, error, done, usage.
+ * Provider-specific behavior must be normalized before reaching this contract.
+ * Providers may keep provider-native turn metadata internally and expose it via
+ * runtime methods instead of encoding it as stream-control chunks.
+ */
+export type StreamChunk =
+  | { type: 'user_message_start'; content: string; itemId?: string }
+  | { type: 'assistant_message_start'; itemId?: string }
+  | { type: 'text'; content: string }
+  | { type: 'thinking'; content: string }
+  | { type: 'tool_use'; id: string; name: string; input: Record<string, unknown> }
+  | { type: 'tool_result'; id: string; content: string; isError?: boolean; toolUseResult?: SDKToolUseResult }
+  | { type: 'tool_output'; id: string; content: string }
+  | { type: 'error'; content: string }
+  | { type: 'notice'; content: string; level?: 'info' | 'warning' }
+  | { type: 'done' }
+  | { type: 'usage'; usage: UsageInfo; sessionId?: string | null }
+  | { type: 'context_compacted' }
+  | { type: 'async_subagent_result'; agentId: string; status: 'completed' | 'error'; result?: string }
+  | { type: 'subagent_tool_use'; subagentId: string; id: string; name: string; input: Record<string, unknown> }
+  | { type: 'subagent_tool_result'; subagentId: string; id: string; content: string; isError?: boolean; toolUseResult?: SDKToolUseResult };
+
+/**
+ * Context window usage information.
+ *
+ * `contextTokens` is the provider-computed total token count in the context window.
+ * Claude sets it to `inputTokens + cacheCreationInputTokens + cacheReadInputTokens`;
+ * other providers should set it to their equivalent total.
+ *
+ * Cache token fields are optional — only providers with prompt caching (Claude)
+ * populate them. Feature code should use `contextTokens` for display, not recompute
+ * from the cache breakdown.
+ */
+export interface UsageInfo {
+  model?: string;
+  inputTokens: number;
+  /** Prompt caching: tokens used to create cache entries. Claude-specific; 0 if omitted. */
+  cacheCreationInputTokens?: number;
+  /** Prompt caching: tokens read from cache. Claude-specific; 0 if omitted. */
+  cacheReadInputTokens?: number;
+  contextWindow: number;
+  /** True when `contextWindow` came from provider runtime data instead of a local heuristic. */
+  contextWindowIsAuthoritative?: boolean;
+  contextTokens: number;
+  percentage: number;
+}

package/src/core/types/diff.ts

@@ -0,0 +1,31 @@
+/**
+ * Diff-related type definitions.
+ */
+
+export interface DiffLine {
+  type: 'equal' | 'insert' | 'delete';
+  text: string;
+  oldLineNum?: number;
+  newLineNum?: number;
+}
+
+export interface DiffStats {
+  added: number;
+  removed: number;
+}
+
+/** A single hunk from the SDK's structuredPatch format. */
+export interface StructuredPatchHunk {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  lines: string[];
+}
+
+/** Shape of the SDK's toolUseResult object for Write/Edit tools. */
+export interface SDKToolUseResult {
+  structuredPatch?: StructuredPatchHunk[];
+  filePath?: string;
+  [key: string]: unknown;
+}

package/src/core/types/index.ts

@@ -0,0 +1,78 @@
+// Chat types
+export {
+  type ChatMessage,
+  type ContentBlock,
+  type Conversation,
+  type ConversationMeta,
+  type ForkSource,
+  type ImageAttachment,
+  type ImageMediaType,
+  type SessionMetadata,
+  type StreamChunk,
+  type UsageInfo,
+  VIEW_TYPE_CLAUDIAN,
+} from './chat';
+export { type ProviderId } from './provider';
+
+// Settings and command types
+export {
+  type ApprovalDecision,
+  type ClaudianSettings,
+  type EnvironmentScope,
+  type EnvSnippet,
+  type HostnameCliPaths,
+  type InstructionRefineResult,
+  type KeyboardNavigationSettings,
+  type PermissionMode,
+  type SlashCommand,
+} from './settings';
+
+// Diff types
+export {
+  type DiffLine,
+  type DiffStats,
+  type SDKToolUseResult,
+  type StructuredPatchHunk,
+} from './diff';
+
+// Tool types
+export {
+  type AskUserAnswers,
+  type AskUserQuestionItem,
+  type AskUserQuestionOption,
+  type AsyncSubagentStatus,
+  type ExitPlanModeCallback,
+  type ExitPlanModeDecision,
+  type SubagentInfo,
+  type SubagentMode,
+  type ToolCallInfo,
+  type ToolDiffData,
+} from './tools';
+
+// Agent types
+export {
+  type AgentDefinition,
+  type AgentFrontmatter,
+} from './agent';
+
+// Plugin types
+export {
+  type PluginInfo,
+  type PluginScope,
+} from './plugins';
+
+// MCP types
+export {
+  DEFAULT_MCP_SERVER,
+  getMcpServerType,
+  isValidMcpServerConfig,
+  type ManagedMcpConfigFile,
+  type ManagedMcpServer,
+  type McpConfigFile,
+  type McpHttpServerConfig,
+  type McpServerConfig,
+  type McpServerType,
+  type McpSSEServerConfig,
+  type McpStdioServerConfig,
+  type ParsedMcpConfig,
+} from './mcp';