bernard-agent 0.8.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # Bernard
 
-A local CLI AI agent that executes terminal commands, manages scheduled tasks, remembers context across sessions, and connects to external tool servers — all through natural language. Supports multiple LLM providers (Anthropic, OpenAI, xAI) via the Vercel AI SDK.
+A local CLI AI agent that executes terminal commands, manages scheduled tasks, remembers context across sessions, and connects to external tool servers — all through natural language. Supports multiple LLM providers (Anthropic, OpenAI, xAI) via the Vercel AI SDK, plus user-registered **custom providers** that point those SDKs at any compatible endpoint (Ollama, LM Studio, OpenRouter, internal proxies, …).
 
 ## Table of Contents
 
@@ -125,6 +125,28 @@ Check which providers have keys configured:
 bernard providers
 ```
 
+### Custom Providers
+
+If you run your own LLM (Ollama, LM Studio, vLLM, ...) or use an OpenAI/Anthropic/xAI-compatible aggregator (OpenRouter, Together, Fireworks, internal proxies), register it as a **custom provider**. You pick a name, pick which of the three installed SDKs to wrap, supply a base URL, and Bernard treats that name like any other provider.
+
+```bash
+# CLI
+bernard add-provider ollama \
+  --sdk openai \
+  --base-url http://localhost:11434/v1 \
+  --model llama3.2 \
+  --key ollama          # any non-empty token; some local servers ignore the value
+bernard add-key ollama <token>   # if you skipped --key above
+bernard providers               # lists built-ins and custom side-by-side
+bernard remove-provider ollama  # removes the entry and its stored key
+```
+
+You can also add one interactively from the REPL: type `/provider`, scroll to **+ Add custom provider…**, and the wizard walks you through SDK, name, base URL, default model, and key. Once added, `/provider` switches to it like any built-in. In `/model`, the menu shows a remembered list of model names plus a `+ Type a new model name…` entry that adds whatever you type for next time.
+
+When the active provider is custom, the welcome banner prints an extra `Endpoint:` line so it's clear the session isn't hitting the SDK's default URL.
+
+Reserved names: `anthropic`, `openai`, `xai` (these are the built-ins). Custom-provider keys are stored in `keys.json` and are **not** read from environment variables.
+
 ### Environment Variables
 
 Bernard loads `.env` from the current directory first, then falls back to `~/.bernard/.env`.
@@ -198,14 +220,17 @@ bernard --alert <id>             # Open with cron alert context
 ### CLI Management Commands
 
 ```bash
-bernard add-key <provider> <key>   # Store an API key securely
-bernard remove-key <provider>      # Remove a stored API key
-bernard providers                  # List providers and key status
-bernard list-options               # Show configurable options
-bernard reset-option <option>      # Reset one option to default
-bernard reset-options              # Reset all options (with confirmation)
-bernard mcp-list                   # List configured MCP servers
-bernard remove-mcp <key>           # Remove an MCP server
+bernard add-key <provider> <key>                                # Store an API key securely
+bernard remove-key <provider>                                   # Remove a stored API key
+bernard providers                                               # List providers (built-in + custom) and key status
+bernard add-provider <name> --sdk <openai|anthropic|xai> \
+  --base-url <url> --model <model> [--key <key>]                # Register a custom provider
+bernard remove-provider <name>                                  # Remove a custom provider and its key
+bernard list-options                                            # Show configurable options
+bernard reset-option <option>                                   # Reset one option to default
+bernard reset-options                                           # Reset all options (with confirmation)
+bernard mcp-list                                                # List configured MCP servers
+bernard remove-mcp <key>                                        # Remove an MCP server
 
 # Cron management
 bernard cron-list                  # List all cron jobs with status
@@ -229,30 +254,28 @@ 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)                                |
-| `/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`)                                                  |
+| 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+)_                                                          |
+| `/agent-options`  | Toggle agent behaviors (critic mode, coordinator/ReAct, prompt rewriter, tool details, auto-create specialists)  |
+| `/options`        | View and modify runtime options (max-tokens, max-steps, shell-timeout, token-window); also includes debug report |
+| `/exit`           | Quit Bernard (also: `exit`, `quit`)                                                                              |
 
 Type `/{routine-id}` or `/{specialist-id}` to invoke a saved routine or specialist directly (e.g., `/deploy-staging`).
 
@@ -276,7 +299,7 @@ bernard> what git branch am I on?
 You're on the main branch.
 ```
 
-**Dangerous command protection:** Bernard detects risky patterns (`rm -rf`, `sudo`, `mkfs`, `dd`, `chmod 777`, `reboot`, `kill -9`, etc.) and asks for your confirmation before executing.
+**Dangerous command protection:** Bernard detects risky patterns (`rm -rf`, `sudo`, `mkfs`, `dd`, `chmod 777`, `reboot`, `kill -9`, etc.) and asks for your confirmation via an arrow-key menu before executing. `rm` calls scoped to Bernard's own scratch-script directory (`<os-tmpdir>/bernard-*`, e.g. `/tmp/bernard-*` on Linux — an internal constant, not configurable) and free of shell metacharacters skip the prompt, since that's just Bernard cleaning up after itself.
 
 **Timeout:** Commands time out after 30 seconds by default (configurable via `shell-timeout` option).
 
@@ -338,6 +361,23 @@ bernard> I need to migrate 5 database tables — track progress in scratch
 
 Actions: `list`, `read`, `write`, `delete`. Scratch notes are also injected into the system prompt, so Bernard always knows the current session state.
 
+### Asking the User
+
+When Bernard is missing information only you can provide — intent, preferences, a missing argument — it calls `ask_user` to pause the turn and prompt you directly, instead of writing the question as prose (which would leave the turn idle).
+
+```
+bernard> file an issue about the menu bug
+  ▶ ask_user: 3 questions
+  [1 ✓   ▸2◂   3]   Which labels apply?
+    ▸ bug
+      ui
+      Other (type a custom answer)
+
+Filed issue #214 with title, body, and the labels you picked.
+```
+
+A single call can batch up to 10 related questions (title + body + labels, say), each with free-form input or a fixed choice list plus an optional "Other" escape hatch. Hit Esc mid-batch and whatever you already answered is returned to the agent. In non-interactive sessions the tool reports `unavailable` so the agent can pick a sensible default.
+
 ### Date and Time
 
 Returns the current date, time, and timezone. Bernard calls this automatically when needed.
@@ -492,10 +532,7 @@ Use `/candidates` to see pending suggestions with their name, description, confi
 **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
+/agent-options    # Interactive menu to configure auto-create on/off and threshold
 ```
 
 Or via environment variables: `BERNARD_AUTO_CREATE_SPECIALISTS=true` and `BERNARD_AUTO_CREATE_THRESHOLD=0.85`.
@@ -509,9 +546,7 @@ Storage: one JSON file per candidate in `~/.local/share/bernard/specialist-candi
 Critic mode adds planning, proactive scratch/memory usage, and post-response verification. Toggle it during a session:
 
 ```bash
-/critic on    # Enable critic mode
-/critic off   # Disable critic mode
-/critic       # Show current status
+/agent-options   # Interactive menu; toggle "Critic mode"
 ```
 
 When enabled:
@@ -724,7 +759,7 @@ Summarization and domain-specific fact extraction run in parallel. Scratch notes
 
 **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).
+When critic mode is enabled (toggle via `/agent-options`), Bernard writes plans to scratch before complex tasks and verifies outcomes after tool use. See [Critic Mode](#critic-mode).
 
 ### RAG Memory
 
@@ -835,7 +870,7 @@ Logs are written to `.logs/YYYY-MM-DD.log` in JSON format, covering agent proces
 
 ### 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.
+Use `/options` in the REPL and select "Debug report" 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
 
@@ -858,6 +893,7 @@ src/
 ├── config.ts             # Config loading and validation
 ├── critic.ts             # Critic agent for response verification
 ├── output.ts             # Terminal formatting (Chalk)
+├── menu.ts               # Reusable numbered-list selection UI
 ├── theme.ts              # Color theme definitions and switching
 ├── memory.ts             # MemoryStore (persistent + scratch)
 ├── context.ts            # Context compression + domain fact extraction
@@ -929,7 +965,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 — run `/debug` in the REPL and paste the output
+- Your environment — run `/options` and select "Debug report" in the REPL, then paste the output
 - Any relevant logs (run with `BERNARD_DEBUG=1` for verbose output)
 
 ## Third-Party Licenses

package/dist/agent.d.ts

@@ -7,7 +7,11 @@ import type { RAGStore, RAGSearchResult } from './rag.js';
 import { RoutineStore, type RoutineSummary } from './routines.js';
 import { SpecialistStore, type SpecialistSummary } from './specialists.js';
 import type { CandidateStoreReader } from './specialist-candidates.js';
+import { CorrectionCandidateStore } from './correction-candidates.js';
 import { type SpecialistMatch } from './specialist-matcher.js';
+import { type ImageAttachment } from './image.js';
+import { type ResolvedEntry } from './reference-resolver.js';
+export { REACT_COORDINATOR_PROMPT, shouldEnforcePlan, REACT_MAX_STEPS_CEILING, computeEffectiveMaxSteps, REACT_ENFORCEMENT_MAX_RETRIES, REACT_AUTO_CANCEL_NOTE, buildEnforcementFeedback, } from './react.js';
 /**
  * Assembles the full system prompt including base instructions, memory context, and MCP status.
  * @internal Exported for testing only.
@@ -19,7 +23,7 @@ import { type SpecialistMatch } from './specialist-matcher.js';
  * @param specialistSummaries - Specialist summaries to list in the prompt
  * @param specialistMatches - Pre-computed specialist match results for the current input
  */
-export declare function buildSystemPrompt(config: BernardConfig, memoryStore: MemoryStore, mcpServerNames?: string[], ragResults?: RAGSearchResult[], routineSummaries?: RoutineSummary[], specialistSummaries?: SpecialistSummary[], specialistMatches?: SpecialistMatch[]): string;
+export declare function buildSystemPrompt(config: BernardConfig, memoryStore: MemoryStore, mcpServerNames?: string[], ragResults?: RAGSearchResult[], routineSummaries?: RoutineSummary[], specialistSummaries?: SpecialistSummary[], specialistMatches?: SpecialistMatch[], resolvedReferences?: ResolvedEntry[]): string;
 export interface CompactResult {
     compacted: boolean;
     tokensBefore: number;
@@ -49,11 +53,18 @@ export declare class Agent {
     private routineStore;
     private specialistStore;
     private candidateStore?;
+    private correctionStore;
+    private toolProfileStore;
     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);
+    private planStore;
+    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, correctionStore?: CorrectionCandidateStore);
     /** Returns the current conversation message history. */
     getHistory(): CoreMessage[];
+    /** Returns the store that queues tool-wrapper correction candidates for this session. */
+    getCorrectionStore(): CorrectionCandidateStore;
+    /** Returns the specialist store used by this agent. */
+    getSpecialistStore(): SpecialistStore;
     /** Returns the RAG search results from the most recent `processInput` call. */
     getLastRAGResults(): RAGSearchResult[];
     /** Cancels the in-flight LLM request, if any. Safe to call when no request is active. */
@@ -75,7 +86,7 @@ export declare class Agent {
      * @param userInput - The raw text from the user's REPL input
      * @throws Error wrapping the underlying API error if generation fails for non-abort, non-overflow reasons
      */
-    processInput(userInput: string): Promise<void>;
+    processInput(userInput: string, images?: ImageAttachment[], resolvedReferences?: ResolvedEntry[]): Promise<void>;
     /** 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. */