Merge pull request #198 from bramses/agents

Add Agents system with AI Wizard, fix streaming markdown corruption

Author: DenizOkcu

.gitignore

@@ -27,6 +27,9 @@ coverage/
 # TypeScript
 *.tsbuildinfo
 
+# agents
+.claude
+
 # obsidian
 data.json
 

CHANGELOG.md

@@ -1,5 +1,46 @@
 # ChatGPT MD Changelog
 
+## v3.1.0 - Agents System
+
+### 🤖 Major Features
+
+- **Agents System**: Create reusable AI personas with custom system prompts, models, and temperature settings
+  - Agent files are Markdown notes with frontmatter (model, temperature, stream) and a body that serves as the system prompt
+  - Agents live in a configurable folder (default: `ChatGPT_MD/agents`)
+- **Choose Agent Command**: Select an agent from your agent folder and apply it to the current note
+  - Sets the `agent` field in the note's frontmatter
+  - Agent settings (model, temperature) and system prompt are merged into the chat configuration at runtime
+- **Create Agent Command**: Two creation modes:
+  - **Manual**: Configure name, model (with autocomplete), temperature (slider), and system prompt yourself
+  - **AI Wizard**: Describe what you want the agent to do, and an AI generates the name, temperature, and a comprehensive system prompt
+  - The wizard pre-fills the manual form so you can review and edit before saving
+
+### 🏗️ Technical Architecture
+
+- **AgentService**: New service for agent file CRUD and resolution (`getAgentFiles`, `readAgent`, `resolveAgentByName`, `createAgentFile`)
+- **Agent Resolution in SettingsService**: When a note has `agent: AgentName` in frontmatter, the agent's frontmatter and body are resolved and merged into the configuration
+- **Merge Priority**: `defaultConfig < defaultFrontmatter < settings < agentFrontmatter < noteFrontmatter`
+- **System Message Injection**: Agent body is prepended as a system message before `system_commands` entries in ChatHandler
+
+### 🎨 User Interface
+
+- **AgentSuggestModal**: Fuzzy-search modal for picking agents from the configured folder
+- **CreateAgentModal**: Multi-step wizard modal with mode selection, AI generation, loading state, and manual form
+- **Settings**: New "Agent Folder" setting in the Folders section
+
+### 🔧 Streaming Improvements
+
+- **Line-Boundary Flushing**: StreamingHandler now flushes only up to the last newline to prevent cursor offset race conditions during markdown re-rendering
+- **Safety Valve**: MAX_BUFFER_SIZE (10KB) forces flush even without newlines to prevent unbounded buffer growth
+- **Force Flush on End**: Remaining partial line is written when streaming completes
+
+### 📦 Under the Hood
+
+- **New Files**: `AgentService.ts`, `AgentHandlers.ts`, `AgentSuggestModal.ts`, `CreateAgentModal.ts`
+- **Constants**: `AGENT_FOLDER_TYPE`, `CHOOSE_AGENT_COMMAND_ID`, `CREATE_AGENT_COMMAND_ID`, `AGENT_WIZARD_SYSTEM_PROMPT`
+- **ServiceContainer**: AgentService wired with late-binding to SettingsService (same pattern as TemplateService)
+- **StreamingHandler Tests**: New test suite for line-boundary flushing behavior
+
 ## v3.0.0 - Privacy-First AI Tool Calling
 
 ### 🎯 Major Features

CLAUDE.md

@@ -6,9 +6,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ChatGPT MD is an Obsidian plugin that integrates multiple AI providers (OpenAI, OpenRouter, Anthropic, Gemini, Ollama, LM Studio) into Obsidian for seamless chat interactions within markdown notes. Users can have AI conversations directly in their notes, with support for note linking, streaming responses, and per-note configuration via frontmatter.
 
-## v3.0.0 - Privacy-First AI Tool Calling
+## v3.1.0 - Agents System
+
+- **Agent files**: Markdown files in a configurable agent folder with frontmatter (model, temperature, stream) and a body that becomes the system prompt
+- **Choose Agent command**: Select an agent to apply to the current note (sets `agent` frontmatter field)
+- **Create Agent command**: Create agents manually or via AI Wizard (AI generates name, temperature, system prompt from a description)
+- **Agent resolution**: When a note has `agent: AgentName` in frontmatter, the agent's settings (model, temperature) and body (system message) are merged into the chat configuration
+- **Merge priority**: defaultConfig < defaultFrontmatter < settings < agentFrontmatter < noteFrontmatter
 
-Major feature: **Privacy-first AI tool calling** with human-in-the-loop approval:
+## v3.0.0 - Privacy-First AI Tool Calling
 
 - **Vault Search**: AI can search your notes (you approve which files to share)
 - **File Reading**: AI can request access to specific files (you select which ones)
@@ -25,39 +31,42 @@ Major feature: **Privacy-first AI tool calling** with human-in-the-loop approval
 ```bash
 yarn dev           # Development with watch mode
 yarn build         # Production build with TypeScript checks
+yarn build:analyze # Build with bundle analysis
+yarn analyze       # Analyze bundle size without rebuilding
 yarn lint          # Check code quality
 yarn lint:fix      # Auto-fix linting issues
-yarn analyze       # Bundle size analysis
 yarn test          # Run tests
 yarn test:watch    # Run tests in watch mode
 yarn test:coverage # Run tests with coverage
 ```
 
-**Test suite**: This project uses Jest with 104 passing tests covering utility functions.
+**Run single test file**: `yarn test path/to/test.test.ts`
+
+**Test suite**: Uses Jest with tests in `src/**/*.test.ts`. Tests cover utility functions and pure functions. Tests are NOT used for services or command handlers (those are tested manually).
 
 ## Architecture Overview
 
-The plugin uses **constructor injection** via `ServiceContainer`:
+The plugin uses **constructor injection** via a centralized `ServiceContainer`:
 
 - `src/core/ServiceContainer.ts` - DI container with readonly service instances
-- `src/Commands/` - Command handlers (extracted from old CommandRegistry)
-- `src/Services/AiProviderService.ts` - Unified AI service with adapter pattern
+- **Only place** where dependencies are defined via `ServiceContainer.create()`
+- All services receive dependencies through constructors (no service locator pattern)
 
 **AI SDK**: Uses Vercel AI SDK (`ai` package) with provider-specific adapters (`@ai-sdk/openai`, `@ai-sdk/anthropic`, `@ai-sdk/google`, `@openrouter/ai-sdk-provider`).
 
-**Message flow**: User command → EditorService extracts messages → MessageService parses → AiProviderService calls API → Response streamed to editor
+**Message flow**: User invokes chat command → EditorService extracts messages → MessageService parses (splits by `<hr class="__chatgpt_plugin">`, extracts `role::assistant` format, resolves wiki links) → FrontmatterManager merges per-note settings → AiProviderService selects adapter → API call → StreamingHandler streams response → EditorService inserts into editor
 
 ## Code Organization
 
 Each directory has its own CLAUDE.md with detailed context:
 
-- `src/core/` - ServiceContainer (DI)
-- `src/Commands/` - Obsidian command handlers
+- `src/core/` - ServiceContainer (DI), plugin initialization
+- `src/Commands/` - Obsidian command handlers (ChatHandler, ModelSelectHandler, AgentHandlers, etc.)
 - `src/Services/` - Service implementations + `Adapters/` subdirectory
 - `src/Views/` - UI components and modals
 - `src/Models/` - TypeScript interfaces
 - `src/Types/` - AI service type definitions
-- `src/Utilities/` - Pure helper functions
+- `src/Utilities/` - Pure helper functions (well-tested)
 
 ## Cross-cutting Documentation
 
@@ -66,8 +75,28 @@ Each directory has its own CLAUDE.md with detailed context:
 
 ## Key Design Patterns
 
-1. **Constructor Injection** - Dependencies passed via ServiceContainer
-2. **Adapter Pattern** - Provider-specific adapters implement common interface
-3. **Frontmatter-driven config** - Per-note settings override globals
-4. **Streaming responses** - Real-time AI output via Vercel AI SDK
-5. **Link context injection** - Auto-include `[[Wiki Links]]` in prompts
+1. **Constructor Injection** - Dependencies passed via ServiceContainer; never instantiate services directly outside `ServiceContainer.create()`
+2. **Adapter Pattern** - `AiProviderService` uses provider-specific adapters (OpenAI, Anthropic, Gemini, Ollama, OpenRouter, LM Studio) implementing `ProviderAdapter` interface
+3. **Frontmatter-driven config** - Per-note settings override globals; merged at runtime by FrontmatterManager
+4. **Streaming responses** - Real-time AI output via Vercel AI SDK with platform-specific handling (desktop Node.js vs mobile Web API)
+5. **Link context injection** - Wiki links `[[Note Name]]` are resolved and content injected into prompts
+6. **Command Handler Interface** - Commands implement `CommandHandler` with metadata; registered via `CommandRegistrar`
+7. **Agent system** - Agent files (markdown with frontmatter + body) override model/temperature and provide system prompts; resolved at runtime via `agent` frontmatter field
+
+## Adding a New AI Provider
+
+1. Create adapter in `src/Services/Adapters/` implementing `ProviderAdapter`
+2. Add provider-specific configuration to settings
+3. Register adapter in `AiProviderService` (provider selection by model prefix: `ollama@`, `openrouter@`, etc.)
+4. Add URL configuration parameter (e.g., `providerUrl`)
+
+## Model Selection
+
+Models are specified with provider prefix:
+
+- OpenAI: `gpt-4o` (no prefix, default)
+- Ollama: `ollama@llama3.2`
+- OpenRouter: `openrouter@anthropic/claude-3-5-sonnet`
+- LM Studio: `lmstudio@model-name`
+
+The prefix determines which adapter handles the request in `AiProviderService`.

README.md

@@ -4,11 +4,19 @@
 
 ![Chatting with links about vacation plans](images/chat-with-link.gif)
 
-## 🚀 What's New in v3.0.0: Privacy-First AI Tool Calling (off by default - Settings → ChatGPT MD → Tool Calling)
+## 🚀 What's New
+
+### v3.1.0: Agents System
+
+**Create reusable AI personas with custom system prompts, models, and temperature settings.**
+
+Define agents as Markdown files with frontmatter and a system prompt body. Apply an agent to any note with the `Choose Agent` command, or create new agents with the **AI Wizard**—describe what you want, and AI generates the name, temperature, and a comprehensive system prompt for you.
+
+### v3.0.0: Privacy-First AI Tool Calling (off by default - Settings → ChatGPT MD → Tool Calling)
 
 **Your AI assistant can now actively search your vault, read files, and query the web—with a human-in-the-loop architecture that keeps you in control.**
 
-v3.0.0 introduces a **tool calling system** built on privacy-first principles. When your AI needs information, it requests permission to use tools—you approve execution, review results, and control exactly what gets shared back to the model. Nothing leaves your vault without explicit consent.
+Tool calling built on privacy-first principles. When your AI needs information, it requests permission to use tools—you approve execution, review results, and control exactly what gets shared back to the model. Nothing leaves your vault without explicit consent.
 
 
 ## A simple and quick Start 🏁