@mseep/obsidian-agent-client 0.10.6

package/src/types/chat.ts

@@ -0,0 +1,351 @@
+/**
+ * Domain Models for Chat Messages
+ *
+ * These types are independent of the Agent Client Protocol (ACP) library.
+ * They represent the core domain concepts of this plugin and remain stable
+ * even if the underlying protocol changes. The Adapter layer handles conversion
+ * between these domain types and ACP protocol types.
+ */
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+/**
+ * Message role in a conversation.
+ * - assistant: AI agent's messages
+ * - user: User's messages
+ */
+export type Role = "assistant" | "user";
+
+/**
+ * Status of a tool call execution.
+ */
+export type ToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
+
+/**
+ * Categories of tool operations.
+ */
+export type ToolKind =
+	| "read" // Reading files or data
+	| "edit" // Modifying existing content
+	| "delete" // Removing files or data
+	| "move" // Moving or renaming
+	| "search" // Searching through content
+	| "execute" // Running commands or scripts
+	| "think" // Agent reasoning/planning
+	| "fetch" // Fetching external resources
+	| "switch_mode" // Changing operation mode
+	| "other"; // Other operations
+
+// ============================================================================
+// Tool Call Content Types
+// ============================================================================
+
+/**
+ * Content that can be included in a tool call result.
+ * Currently supports diffs and terminal output.
+ */
+export type ToolCallContent = DiffContent | TerminalContent;
+
+/**
+ * Represents a file modification with before/after content.
+ */
+export interface DiffContent {
+	type: "diff";
+	path: string;
+	newText: string;
+	oldText?: string | null; // null or undefined for new files
+}
+
+/**
+ * Reference to a terminal session created by a tool call.
+ */
+export interface TerminalContent {
+	type: "terminal";
+	terminalId: string;
+}
+
+// ============================================================================
+// Supporting Types
+// ============================================================================
+
+/**
+ * Location information for tool operations (e.g., which file/line was affected).
+ */
+export interface ToolCallLocation {
+	path: string;
+	line?: number | null; // null if the entire file is affected
+}
+
+/**
+ * User's choice for permission requests.
+ */
+export interface PermissionOption {
+	optionId: string;
+	name: string;
+	kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+}
+
+/**
+ * Active permission request information.
+ * Derived from messages by scanning for tool_call content with isActive permission.
+ */
+export interface ActivePermission {
+	/** Permission request ID */
+	requestId: string;
+	/** Tool call ID that triggered the request */
+	toolCallId: string;
+	/** Available permission options */
+	options: PermissionOption[];
+}
+
+/**
+ * Entry in an agent's plan/task list.
+ */
+export interface PlanEntry {
+	content: string;
+	status: "pending" | "in_progress" | "completed";
+	priority: "high" | "medium" | "low";
+}
+
+/**
+ * Tool call information for permission requests.
+ * Contains details about the operation being requested for user approval.
+ */
+export interface ToolCallInfo {
+	toolCallId: string;
+	title?: string | null;
+	status?: ToolCallStatus | null;
+	kind?: ToolKind | null;
+	content?: ToolCallContent[] | null;
+	locations?: ToolCallLocation[] | null;
+	rawInput?: { [k: string]: unknown }; // Tool's input parameters
+	rawOutput?: { [k: string]: unknown }; // Tool's output data
+}
+
+// ============================================================================
+// Chat Message
+// ============================================================================
+
+/**
+ * A single message in the chat history.
+ *
+ * Messages can contain multiple content blocks of different types
+ * (text, images, tool calls, etc.) to represent rich conversations.
+ */
+export interface ChatMessage {
+	id: string;
+	role: Role;
+	content: MessageContent[];
+	timestamp: Date;
+}
+
+/**
+ * Different types of content that can appear in a message.
+ *
+ * This union type represents all possible content blocks:
+ * - text: Plain text from user or agent
+ * - agent_thought: Agent's internal reasoning (often collapsed in UI)
+ * - image: Visual content (base64 encoded)
+ * - resource_link: Reference to a file the agent can access (URI only)
+ * - tool_call: Agent's tool execution with results
+ * - plan: Agent's task breakdown
+ * - permission_request: Request for user approval
+ * - terminal: Reference to a terminal session
+ */
+export type MessageContent =
+	| {
+			type: "text";
+			text: string;
+	  }
+	| {
+			type: "text_with_context";
+			text: string;
+			autoMentionContext?: {
+				noteName: string;
+				notePath: string;
+				selection?: {
+					fromLine: number;
+					toLine: number;
+				};
+			};
+	  }
+	| {
+			type: "agent_thought";
+			text: string;
+	  }
+	| {
+			type: "image";
+			data: string; // Base64 encoded image data
+			mimeType: string; // e.g., "image/png"
+			uri?: string; // Optional source URI
+	  }
+	| {
+			type: "resource_link";
+			uri: string; // Resource URI (e.g., "file:///path/to/file.pdf")
+			name: string; // Human-readable file name
+			mimeType?: string; // e.g., "application/pdf"
+			size?: number; // File size in bytes
+	  }
+	| {
+			type: "tool_call";
+			toolCallId: string;
+			title?: string | null;
+			status: ToolCallStatus;
+			kind?: ToolKind;
+			content?: ToolCallContent[];
+			locations?: ToolCallLocation[];
+			rawInput?: { [k: string]: unknown };
+			rawOutput?: { [k: string]: unknown };
+			permissionRequest?: {
+				requestId: string;
+				options: PermissionOption[];
+				selectedOptionId?: string;
+				isCancelled?: boolean;
+				isActive?: boolean;
+			};
+	  }
+	| {
+			type: "plan";
+			entries: PlanEntry[];
+	  }
+	| {
+			type: "permission_request";
+			toolCall: ToolCallInfo;
+			options: PermissionOption[];
+			selectedOptionId?: string;
+			isCancelled?: boolean;
+			isActive?: boolean;
+	  }
+	| {
+			type: "terminal";
+			terminalId: string;
+	  };
+/**
+ * Attached file for ChatInput.
+ *
+ * Two kinds:
+ * - "image": Base64 embedded image (from paste or D&D with image capability)
+ * - "file": File reference by path (D&D non-image, or D&D image without capability)
+ */
+export interface AttachedFile {
+	id: string;
+	kind: "image" | "file";
+	mimeType: string;
+
+	/** Base64-encoded data (only for kind === "image") */
+	data?: string;
+
+	/** File name for display (only for kind === "file") */
+	name?: string;
+
+	/** Absolute file path (only for kind === "file") */
+	path?: string;
+
+	/** File size in bytes (only for kind === "file", for display + resource_link) */
+	size?: number;
+}
+
+/**
+ * ChatInput component state that can be shared between views.
+ * Used for broadcast-prompt command.
+ */
+export interface ChatInputState {
+	/** Text content in the input field */
+	text: string;
+	/** Attached files (images and non-image files) */
+	files: AttachedFile[];
+}
+/**
+ * Prompt Content Types
+ *
+ * Types representing content that can be included in a prompt sent to the agent.
+ * These correspond to ACP ContentBlock types but are defined independently
+ * to maintain domain layer isolation.
+ */
+
+/**
+ * Text content in a prompt
+ */
+export interface TextPromptContent {
+	type: "text";
+	text: string;
+}
+
+/**
+ * Image content in a prompt
+ *
+ * Images are sent as Base64-encoded data with their MIME type.
+ * Supported MIME types: image/png, image/jpeg, image/gif, image/webp
+ */
+export interface ImagePromptContent {
+	type: "image";
+	/** Base64-encoded image data (without data: prefix) */
+	data: string;
+	/** MIME type of the image */
+	mimeType: string;
+}
+
+/**
+ * Annotations for resource content (ACP spec compliant)
+ *
+ * Provides hints to the agent about how to use or prioritize the resource.
+ */
+export interface ResourceAnnotations {
+	/** Intended audience(s) for this resource */
+	audience?: ("user" | "assistant")[];
+	/** Importance (0.0 = least important, 1.0 = most important) */
+	priority?: number;
+	/** Last modified timestamp (ISO 8601) */
+	lastModified?: string;
+}
+
+/**
+ * Embedded resource content in a prompt
+ *
+ * Used when agent supports embeddedContext capability.
+ * Contains file content with URI and metadata.
+ * This allows the agent to receive structured context about referenced files.
+ */
+export interface ResourcePromptContent {
+	type: "resource";
+	resource: {
+		/** Resource URI (e.g., "file:///path/to/note.md") */
+		uri: string;
+		/** MIME type of the resource */
+		mimeType: string;
+		/** Text content of the resource */
+		text: string;
+	};
+	/** Optional annotations for the resource */
+	annotations?: ResourceAnnotations;
+}
+
+/**
+ * Resource link content in a prompt
+ *
+ * References a file by URI without embedding its contents.
+ * The agent is expected to access the file itself.
+ * No prompt capability is required (unlike image/audio/resource).
+ */
+export interface ResourceLinkPromptContent {
+	type: "resource_link";
+	/** Resource URI (e.g., "file:///path/to/document.pdf") */
+	uri: string;
+	/** Human-readable file name */
+	name: string;
+	/** MIME type of the resource */
+	mimeType?: string;
+	/** File size in bytes */
+	size?: number;
+}
+
+/**
+ * Union type for all prompt content types
+ */
+export type PromptContent =
+	| TextPromptContent
+	| ImagePromptContent
+	| ResourcePromptContent
+	| ResourceLinkPromptContent;

package/src/types/errors.ts

@@ -0,0 +1,136 @@
+/**
+ * Domain Models for Agent Errors
+ *
+ * This module defines error types for the Agent Client plugin:
+ * - AcpError: ACP protocol errors (JSON-RPC based)
+ * - ProcessError: Node.js process-level errors
+ *
+ * These types are based on the ACP (Agent Client Protocol) specification
+ * and JSON-RPC 2.0 error object specification.
+ */
+
+// ============================================================================
+// ACP Error Codes
+// ============================================================================
+
+/**
+ * ACP Error Codes based on JSON-RPC 2.0 and ACP protocol extensions.
+ * https://agentclientprotocol.com/
+ *
+ * Standard JSON-RPC 2.0 errors: -32700 to -32600
+ * ACP protocol-specific errors: -32000 to -32099 (reserved range)
+ */
+export const AcpErrorCode = {
+	// JSON-RPC 2.0 standard errors
+	PARSE_ERROR: -32700,
+	INVALID_REQUEST: -32600,
+	METHOD_NOT_FOUND: -32601,
+	INVALID_PARAMS: -32602,
+	INTERNAL_ERROR: -32603,
+
+	// ACP protocol-specific errors (reserved range -32000 to -32099)
+	AUTHENTICATION_REQUIRED: -32000,
+	RESOURCE_NOT_FOUND: -32002,
+} as const;
+
+export type AcpErrorCodeValue =
+	(typeof AcpErrorCode)[keyof typeof AcpErrorCode];
+
+// ============================================================================
+// User-Facing Error Information
+// ============================================================================
+
+/**
+ * User-facing error information for UI display.
+ *
+ * This is the common interface used by all error types to provide
+ * consistent error information to the user.
+ */
+export interface ErrorInfo {
+	/** Short, user-friendly error title */
+	title: string;
+
+	/** Detailed error message explaining what went wrong */
+	message: string;
+
+	/** Optional suggestion on how to resolve the error */
+	suggestion?: string;
+
+	/** Optional external link rendered as an actionable anchor (e.g. docs). */
+	link?: { text: string; url: string };
+}
+
+// ============================================================================
+// ACP Error (Protocol-level)
+// ============================================================================
+
+/**
+ * ACP protocol error from agent communication.
+ *
+ * Based on JSON-RPC 2.0 error object specification with ACP extensions.
+ * The `message` field contains the agent's error message and should be
+ * displayed directly to the user for detailed error information.
+ */
+export interface AcpError extends ErrorInfo {
+	/** ACP/JSON-RPC error code */
+	code: number;
+
+	/** Additional error data from agent (for debugging) */
+	data?: unknown;
+
+	/** Session ID where the error occurred */
+	sessionId?: string | null;
+
+	/** Original error object for debugging */
+	originalError?: unknown;
+}
+
+// ============================================================================
+// Process Error (System-level)
+// ============================================================================
+
+/**
+ * Process-level error types.
+ *
+ * These represent Node.js/system errors that occur during
+ * agent process management, not ACP protocol errors.
+ */
+export type ProcessErrorType =
+	| "spawn_failed" // Process spawn failed (ENOENT, etc.)
+	| "command_not_found" // Exit code 127
+	| "process_crashed" // Abnormal termination
+	| "process_timeout"; // Timeout
+
+/**
+ * Process-level error from agent process management.
+ *
+ * These are Node.js/system errors, not ACP protocol errors.
+ * Used for errors that occur before or outside of ACP communication.
+ */
+export interface ProcessError extends ErrorInfo {
+	/** Error type classification */
+	type: ProcessErrorType;
+
+	/** Agent ID where the error occurred */
+	agentId: string;
+
+	/** Exit code (if applicable) */
+	exitCode?: number;
+
+	/** Node.js error code (e.g., "ENOENT") */
+	errorCode?: string;
+
+	/** Original error object for debugging */
+	originalError?: unknown;
+}
+
+// ============================================================================
+// UI Display Types
+// ============================================================================
+
+/**
+ * Visual variant for error/notification banners.
+ * - "error": Red/critical styling
+ * - "info": Subtle/informational styling
+ */
+export type OverlayVariant = "error" | "info";

package/src/types/obsidian-internals.d.ts

@@ -0,0 +1,14 @@
+export {};
+
+/**
+ * Type augmentation for unofficial Obsidian APIs.
+ *
+ * These methods exist at runtime but are not in the public type definitions.
+ * Only add methods that are widely used by the plugin community and unlikely
+ * to be removed without notice.
+ */
+declare module "obsidian" {
+	interface Vault {
+		getConfig(key: string): unknown;
+	}
+}