bernard-agent 0.6.2 → 0.8.0

package/README.md

@@ -19,6 +19,7 @@ A local CLI AI agent that executes terminal commands, manages scheduled tasks, r
 - [Tools](#tools)
   - [Shell Execution](#shell-execution)
   - [Web Reading](#web-reading)
+  - [File Editing](#file-editing)
   - [Memory (Persistent)](#memory-persistent)
   - [Scratch Notes (Session)](#scratch-notes-session)
   - [Date and Time](#date-and-time)
@@ -128,19 +129,22 @@ bernard providers
 
 Bernard loads `.env` from the current directory first, then falls back to `~/.bernard/.env`.
 
-| Variable                | Description                                           | Default                   |
-| ----------------------- | ----------------------------------------------------- | ------------------------- |
-| `BERNARD_PROVIDER`      | LLM provider (`anthropic`, `openai`, `xai`)           | `anthropic`               |
-| `BERNARD_MODEL`         | Model name                                            | Provider-specific default |
-| `BERNARD_MAX_TOKENS`    | Max response tokens                                   | `4096`                    |
-| `BERNARD_SHELL_TIMEOUT` | Shell command timeout (ms)                            | `30000`                   |
-| `BERNARD_TOKEN_WINDOW`  | Context window size for compression (0 = auto-detect) | `0`                       |
-| `BERNARD_RAG_ENABLED`   | Enable the RAG memory system                          | `true`                    |
-| `BERNARD_CRITIC_MODE`   | Enable critic mode for response verification          | `false`                   |
-| `BERNARD_DEBUG`         | Enable debug logging                                  | unset                     |
-| `ANTHROPIC_API_KEY`     | Anthropic API key                                     | —                         |
-| `OPENAI_API_KEY`        | OpenAI API key                                        | —                         |
-| `XAI_API_KEY`           | xAI API key                                           | —                         |
+| Variable                          | Description                                              | Default                   |
+| --------------------------------- | -------------------------------------------------------- | ------------------------- |
+| `BERNARD_PROVIDER`                | LLM provider (`anthropic`, `openai`, `xai`)              | `anthropic`               |
+| `BERNARD_MODEL`                   | Model name                                               | Provider-specific default |
+| `BERNARD_MAX_TOKENS`              | Max response tokens                                      | `4096`                    |
+| `BERNARD_SHELL_TIMEOUT`           | Shell command timeout (ms)                               | `30000`                   |
+| `BERNARD_TOKEN_WINDOW`            | Context window size for compression (0 = auto-detect)    | `0`                       |
+| `BERNARD_MAX_STEPS`               | Max agent loop iterations per request                    | `25`                      |
+| `BERNARD_RAG_ENABLED`             | Enable the RAG memory system                             | `true`                    |
+| `BERNARD_CRITIC_MODE`             | Enable critic mode for response verification             | `false`                   |
+| `BERNARD_AUTO_CREATE_SPECIALISTS` | Auto-create specialists above confidence threshold       | `false`                   |
+| `BERNARD_AUTO_CREATE_THRESHOLD`   | Confidence threshold for auto-creating specialists (0-1) | `0.8`                     |
+| `BERNARD_DEBUG`                   | Enable debug logging                                     | unset                     |
+| `ANTHROPIC_API_KEY`               | Anthropic API key                                        | —                         |
+| `OPENAI_API_KEY`                  | OpenAI API key                                           | —                         |
+| `XAI_API_KEY`                     | xAI API key                                              | —                         |
 
 ### Providers and Models
 
@@ -156,11 +160,12 @@ You can switch providers and models at any time during a session with `/provider
 
 Options can be changed during a session with `/options` or persisted to `~/.bernard/preferences.json`:
 
-| Option          | Default | Description                                           |
-| --------------- | ------- | ----------------------------------------------------- |
-| `max-tokens`    | `4096`  | Maximum tokens per AI response                        |
-| `shell-timeout` | `30000` | Shell command timeout in milliseconds                 |
-| `token-window`  | `0`     | Context window size for compression (0 = auto-detect) |
+| Option          | Default | Description                                                  |
+| --------------- | ------- | ------------------------------------------------------------ |
+| `max-tokens`    | `4096`  | Maximum tokens per AI response                               |
+| `max-steps`     | `25`    | Maximum agent loop iterations per request (tool call chains) |
+| `shell-timeout` | `30000` | Shell command timeout in milliseconds                        |
+| `token-window`  | `0`     | Context window size for compression (0 = auto-detect)        |
 
 From the CLI:
 
@@ -224,28 +229,30 @@ Features:
 
 ### REPL Slash Commands
 
-| Command           | Description                                                               |
-| ----------------- | ------------------------------------------------------------------------- |
-| `/help`           | Show available commands                                                   |
-| `/clear`          | Clear conversation history and scratch notes                              |
-| `/compact`        | Compress conversation history in-place                                    |
-| `/task`           | Run an isolated task (no history, structured output)                      |
-| `/memory`         | List all persistent memories                                              |
-| `/scratch`        | List session scratch notes                                                |
-| `/mcp`            | List connected MCP servers and their tools                                |
-| `/cron`           | Show cron jobs and daemon status                                          |
-| `/rag`            | Show RAG memory stats and recent facts                                    |
-| `/provider`       | Switch LLM provider interactively                                         |
-| `/model`          | Switch model for the current provider                                     |
-| `/theme`          | Switch color theme                                                        |
-| `/routines`       | List saved routines                                                       |
-| `/create-routine` | Create a routine with guided AI assistance                                |
-| `/create-task`    | Create a task routine (`task-` prefixed) with guided AI assistance        |
-| `/specialists`    | List saved specialists                                                    |
-| `/candidates`     | Review auto-detected specialist suggestions _(v0.6.0+)_                   |
-| `/critic`         | Toggle critic mode for response verification (on/off)                     |
-| `/options`        | View and modify runtime options (max-tokens, shell-timeout, token-window) |
-| `/exit`           | Quit Bernard (also: `exit`, `quit`)                                       |
+| Command           | Description                                                                          |
+| ----------------- | ------------------------------------------------------------------------------------ |
+| `/help`           | Show available commands                                                              |
+| `/clear`          | Clear conversation history and scratch notes                                         |
+| `/compact`        | Compress conversation history in-place                                               |
+| `/task`           | Run an isolated task (no history, structured output)                                 |
+| `/memory`         | List all persistent memories                                                         |
+| `/scratch`        | List session scratch notes                                                           |
+| `/mcp`            | List connected MCP servers and their tools                                           |
+| `/cron`           | Show cron jobs and daemon status                                                     |
+| `/rag`            | Show RAG memory stats and recent facts                                               |
+| `/provider`       | Switch LLM provider interactively                                                    |
+| `/model`          | Switch model for the current provider                                                |
+| `/theme`          | Switch color theme                                                                   |
+| `/routines`       | List saved routines                                                                  |
+| `/create-routine` | Create a routine with guided AI assistance                                           |
+| `/create-task`    | Create a task routine (`task-` prefixed) with guided AI assistance                   |
+| `/specialists`    | List saved specialists                                                               |
+| `/candidates`     | Review auto-detected specialist suggestions _(v0.6.0+)_                              |
+| `/critic`         | Toggle critic mode for response verification (on/off)                                |
+| `/agent-options`  | Configure auto-creation for specialist agents                                        |
+| `/options`        | View and modify runtime options (max-tokens, max-steps, shell-timeout, token-window) |
+| `/debug`          | Print a diagnostic report for troubleshooting (no secrets leaked)                    |
+| `/exit`           | Quit Bernard (also: `exit`, `quit`)                                                  |
 
 Type `/{routine-id}` or `/{specialist-id}` to invoke a saved routine or specialist directly (e.g., `/deploy-staging`).
 
@@ -289,6 +296,22 @@ Here's a summary of the API docs: ...
 
 Supports an optional CSS selector to target specific content (e.g., `article`, `main`, `.post-body`). Strips scripts, styles, navigation, footers, and other non-content elements.
 
+### File Editing
+
+Read and edit files with precision using `file_read_lines` and `file_edit_lines` — no need to shell out to `sed` or `awk`.
+
+```
+bernard> show me lines 10-20 of src/config.ts
+  ▶ file_read_lines: src/config.ts (lines 10–20)
+  ...
+
+bernard> replace line 15 with "const timeout = 5000;"
+  ▶ file_edit_lines: src/config.ts [replace line 15]
+  Done — 1 edit applied.
+```
+
+`file_edit_lines` supports replace, insert, delete, and append operations. All edits in a single call are atomic — they all succeed or all fail. Binary files are detected and rejected. Files up to 50 MB are supported, with pagination for large reads.
+
 ### Memory (Persistent)
 
 Long-term memory that persists across sessions. Stored as markdown files in `~/.bernard/memory/`.
@@ -344,7 +367,7 @@ bernard> check the disk usage on /, look up the weather in Austin, and count lin
   ...
 ```
 
-Up to 4 concurrent sub-agents. Each gets 10 max steps. Color-coded output in the terminal.
+Up to 4 concurrent sub-agents. Each gets 50% of the main agent's step budget (e.g. 13 steps when `max-steps` is 25). Color-coded output in the terminal. Sub-agents accept per-invocation provider/model overrides to use a different LLM than the main session.
 
 ### Tasks _(v0.6.0+)_
 
@@ -361,8 +384,10 @@ Found 23 .ts files
 
 Key differences from sub-agents:
 
-- **5-step budget** (vs. 10 for sub-agents) — tasks are meant to be quick and focused
+- **Single-step budget** (`maxSteps: 2` — one tool-use round + structured result) — tasks are meant to be quick and deterministic
 - **Structured JSON output** — always returns `{status: "success"|"error", output: string, details?: string}`
+- **Saved tasks** — create task routines with `/create-task`, then invoke them by ID via `/task-{id}` or programmatically with the `taskId` parameter
+- **Auto-context injection** — working directory, available tools, memory, and RAG context are included automatically
 - **No conversation history** — completely isolated from the current session
 - **Available as both a tool and a command** — the agent can call `task` during routines for chaining, or users can run `/task` directly from the REPL
 - **Shared concurrency pool** — tasks and sub-agents share the same 4-slot limit
@@ -428,7 +453,7 @@ bernard> /code-reviewer review the changes in src/agent.ts
 └─ spec:1 done
 ```
 
-Each specialist run gets its own `generateText` loop with a 10-step budget, using the specialist's system prompt and guidelines as its persona. Specialists share the concurrency pool with sub-agents and tasks (4 slots max).
+Each specialist run gets its own `generateText` loop with a 10-step budget, using the specialist's system prompt and guidelines as its persona. Specialists can have per-specialist model overrides — set a default provider/model at creation time, and it will be used every time that specialist runs. Specialists share the concurrency pool with sub-agents and tasks (4 slots max).
 
 Manage specialists:
 
@@ -462,6 +487,19 @@ When candidates are detected, you'll see a notification at the start of your nex
 
 Use `/candidates` to see pending suggestions with their name, description, confidence score, and reasoning. You can then accept or reject candidates conversationally (e.g., "accept the code-review candidate"), and Bernard will create the specialist for you.
 
+**Overlap detection** — Before suggesting a new specialist, Bernard computes a token-based similarity score against all existing specialists and pending candidates. If the overlap exceeds 60%, the candidate is suppressed. When a candidate partially overlaps with an existing specialist, Bernard may suggest enhancing the existing specialist instead.
+
+**Auto-creation** — You can enable automatic specialist creation for high-confidence candidates:
+
+```bash
+/agent-options auto-create on       # Enable auto-creation
+/agent-options auto-create off      # Disable auto-creation
+/agent-options threshold 0.85       # Set confidence threshold (0-1)
+/agent-options                      # Show current settings
+```
+
+Or via environment variables: `BERNARD_AUTO_CREATE_SPECIALISTS=true` and `BERNARD_AUTO_CREATE_THRESHOLD=0.85`.
+
 Candidates are auto-dismissed after 30 days if not reviewed. Up to 10 pending candidates are stored at a time.
 
 Storage: one JSON file per candidate in `~/.local/share/bernard/specialist-candidates/`.
@@ -484,6 +522,12 @@ When enabled:
 
 The critic checks that claimed actions match actual tool calls and flags any discrepancies. It adds one extra LLM call after tool-using responses. Simple knowledge answers are not verified.
 
+**PAC System (Plan-Act-Critic)** — When critic mode is enabled, sub-agents and specialists also get critic verification via a reusable PAC loop. The PAC loop runs the critic after each sub-agent/specialist execution, and if the critic finds issues, it retries the task with feedback (up to 2 retries). This applies to:
+
+- Sub-agents (`agent` tool)
+- Specialist runs (`specialist_run` tool)
+- Cron job executions (daemon mode)
+
 Default: off. Recommended for high-stakes work (deployments, git operations, multi-file edits).
 
 ---
@@ -678,6 +722,8 @@ Bernard automatically compresses conversation history when it approaches 75% of
 
 Summarization and domain-specific fact extraction run in parallel. Scratch notes survive compression, so multi-step task progress is never lost.
 
+**Auto-continue on truncation:** If a response hits the `max-tokens` limit and is cut off, Bernard automatically continues where it left off (up to 3 continuations). After completing, it shows a recommended `max-tokens` value based on actual usage. If the response is still incomplete after 3 continuations, a warning is shown with instructions to increase the limit via `/options max-tokens <value>`.
+
 When critic mode is enabled (`/critic on`), Bernard writes plans to scratch before complex tasks and verifies outcomes after tool use. See [Critic Mode](#critic-mode).
 
 ### RAG Memory
@@ -722,17 +768,17 @@ Storage: `~/.bernard/conversation-history.json`
 
 ## File Structure
 
-Bernard stores all data in `~/.bernard/`:
+Bernard follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/), splitting files across four standard directories:
 
 ```
-~/.bernard/
-├── keys.json                    # API keys (mode 0600)
+~/.config/bernard/               # Config (XDG_CONFIG_HOME)
 ├── preferences.json             # Provider, model, options
+├── keys.json                    # API keys (mode 0600)
 ├── .env                         # Fallback environment config
-├── mcp.json                     # MCP server configuration
-├── conversation-history.json    # Last session (for --resume)
+└── mcp.json                     # MCP server configuration
+
+~/.local/share/bernard/          # Data (XDG_DATA_HOME)
 ├── memory/                      # Persistent memories (*.md)
-├── models/                      # Embedding model cache (fastembed)
 ├── routines/                    # Saved routines (*.json)
 ├── specialists/                 # Saved specialist profiles (*.json)
 ├── specialist-candidates/       # Auto-detected specialist suggestions (*.json)
@@ -740,12 +786,22 @@ Bernard stores all data in `~/.bernard/`:
 │   └── memories.json            # RAG fact embeddings
 └── cron/
     ├── jobs.json                # Scheduled jobs
-    ├── daemon.pid               # Daemon process ID
-    ├── daemon.log               # Daemon output (rotates at 1MB)
     ├── logs/                    # Per-job execution logs
     └── alerts/                  # Cron alert files
+
+~/.cache/bernard/                # Cache (XDG_CACHE_HOME)
+├── models/                      # Embedding model cache (fastembed)
+└── update-check.json            # Update check state
+
+~/.local/state/bernard/          # State (XDG_STATE_HOME)
+├── conversation-history.json    # Last session (for --resume)
+├── logs/                        # Debug log files (*.jsonl)
+├── cron-daemon.pid              # Daemon process ID
+└── cron-daemon.log              # Daemon output (rotates at 1MB)
 ```
 
+Override all directories with a single flat path: `BERNARD_HOME=/path`. On first run, files are auto-migrated from legacy `~/.bernard/` to XDG locations.
+
 ---
 
 ## Development
@@ -777,6 +833,10 @@ BERNARD_DEBUG=1 bernard
 
 Logs are written to `.logs/YYYY-MM-DD.log` in JSON format, covering agent processing, RAG operations, context compression, tool execution, and MCP operations.
 
+### Diagnostic Report
+
+Use `/debug` in the REPL to print a diagnostic report useful for troubleshooting. The report includes runtime info (Bernard version, Node.js version, OS), LLM configuration, API key status (configured/not set — keys are never shown), MCP server status, RAG/memory/cron state, conversation stats, active settings, and file paths. No secrets are included in the output.
+
 ### Adding a New Provider
 
 1. Install the AI SDK provider package (e.g., `npm install @ai-sdk/google`)
@@ -796,6 +856,7 @@ src/
 ├── repl.ts               # Interactive REPL loop
 ├── agent.ts              # Agent class (generateText loop)
 ├── config.ts             # Config loading and validation
+├── critic.ts             # Critic agent for response verification
 ├── output.ts             # Terminal formatting (Chalk)
 ├── theme.ts              # Color theme definitions and switching
 ├── memory.ts             # MemoryStore (persistent + scratch)
@@ -807,7 +868,11 @@ src/
 ├── specialists.ts        # SpecialistStore (reusable expert profiles)
 ├── specialist-candidates.ts  # CandidateStore (auto-detected suggestions)
 ├── specialist-detector.ts    # LLM-based specialist pattern detection
+├── specialist-matcher.ts    # Keyword scorer for specialist auto-dispatch
 ├── mcp.ts                # MCP server manager
+├── overlap-checker.ts    # Token-based Jaccard overlap for specialist dedup
+├── pac.ts                # Plan-Act-Critic loop wrapper
+├── paths.ts              # Centralized XDG file path resolution
 ├── rag-worker.ts         # Background RAG fact extraction + candidate detection
 ├── setup.ts              # First-time setup wizard
 ├── history.ts            # Conversation save/load
@@ -827,6 +892,7 @@ src/
 │   ├── cron-logs.ts      # Cron execution logs
 │   ├── mcp.ts            # MCP config (stdio)
 │   ├── mcp-url.ts        # MCP config (URL-based)
+│   ├── file.ts           # File reading and line-based editing
 │   ├── routine.ts        # Routine management tool
 │   ├── specialist.ts     # Specialist management tool
 │   ├── specialist-run.ts # Specialist execution (sub-agent with custom persona)
@@ -863,7 +929,7 @@ Found a bug? Please [open an issue](https://github.com/phillt/bernard/issues/new
 
 - Steps to reproduce the problem
 - Expected vs. actual behavior
-- Your environment (OS, Node version, Bernard version, provider/model)
+- Your environment — run `/debug` in the REPL and paste the output
 - Any relevant logs (run with `BERNARD_DEBUG=1` for verbose output)
 
 ## Third-Party Licenses

package/dist/agent.d.ts

@@ -49,6 +49,8 @@ export declare class Agent {
     private routineStore;
     private specialistStore;
     private candidateStore?;
+    private stepLimitHitCount;
+    private lastStepLimitHit;
     constructor(config: BernardConfig, toolOptions: ToolOptions, memoryStore: MemoryStore, mcpTools?: Record<string, any>, mcpServerNames?: string[], alertContext?: string, initialHistory?: CoreMessage[], ragStore?: RAGStore, routineStore?: RoutineStore, specialistStore?: SpecialistStore, candidateStore?: CandidateStoreReader);
     /** Returns the current conversation message history. */
     getHistory(): CoreMessage[];
@@ -56,6 +58,11 @@ export declare class Agent {
     getLastRAGResults(): RAGSearchResult[];
     /** Cancels the in-flight LLM request, if any. Safe to call when no request is active. */
     abort(): void;
+    /** Returns step limit hit info from last processInput, or null if limit wasn't hit. */
+    getStepLimitHit(): {
+        currentLimit: number;
+        hitCount: number;
+    } | null;
     /** Attaches a spinner stats object that will be updated with token usage during generation. */
     setSpinnerStats(stats: SpinnerStats): void;
     /** Updates the alert context injected into the system prompt (e.g., specialist candidates). */
@@ -69,10 +76,6 @@ export declare class Agent {
      * @throws Error wrapping the underlying API error if generation fails for non-abort, non-overflow reasons
      */
     processInput(userInput: string): Promise<void>;
-    /** Extracts a structured log of tool calls from generateText step results. */
-    private extractToolCallLog;
-    /** Runs the critic agent to verify the main agent's response against actual tool calls. */
-    private runCritic;
     /** Compresses conversation history in-place, returning token usage stats. */
     compactHistory(): Promise<CompactResult>;
     /** Resets conversation history, scratch notes, and RAG tracking state for a fresh session. */