ralph.rb 1.2.435535439 → 2.0.0

data/specs/agents.md

@@ -1,172 +1,478 @@
 # Agents Specification
 
-The `Ralph::Agents` module provides a polymorphic abstraction over the external AI coding CLIs that Ralph can invoke. Each supported agent is a subclass of `Ralph::Agents::Base`, encapsulating its CLI invocation details, output parsing, and validation.
+How will we interact with console agents?
 
-## Namespace & File Layout
+## Overview
+
+We will simply run opencode in headless mode, and pass in the prompt, model, and other options.
+
+## Architecture
+
+Opencode will have it's own object that will call the command. The Opencode object will have configuration options that will be passed to the command.
+
+## Opencode CLI docs
+
+These are the official opencode cli docs. We want ot use `opencode run`. And not much else really. Don't add stupid features we don't need.
+Specify:
+- model
+- agent
+- prompt
+- format (JSON STREAM)
 
 ```
-lib/ralph/agents/
-  base.rb          # Ralph::Agents::Base (abstract), module-level resolve/valid_agent_names
-  open_code.rb     # Ralph::Agents::OpenCode
-  claude_code.rb   # Ralph::Agents::ClaudeCode
-  codex.rb         # Ralph::Agents::Codex
-```
+CLI
+OpenCode CLI options and commands.
 
-Each file defines exactly one class inside `module Ralph; module Agents; ... end; end`, except `base.rb` which also defines the module-level lookup functions and the `AGENT_NAME_MAP` constant.
+The OpenCode CLI by default starts the TUI when run without any arguments.
 
-## Module Interface
+Terminal window
+opencode
 
-The `Ralph::Agents` module exposes two module-level functions for agent discovery and resolution.
+But it also accepts commands as documented on this page. This allows you to interact with OpenCode programmatically.
 
-### `Agents.resolve(name_str) -> Base | nil`
+Terminal window
+opencode run "Explain how closures work in JavaScript"
 
-Maps a CLI name string to a new agent instance.
+tui
+Start the OpenCode terminal user interface.
 
-- **Parameter:** `name_str` — String, one of the keys in `AGENT_NAME_MAP`
-- **Returns:** A new instance of the matching agent subclass, or `nil` if the name is unknown
-- **Consumers:** `Loop#resolve_agent!`, `Output::Status`
+Terminal window
+opencode [project]
 
-### `Agents.valid_agent_names -> Array<String>`
+Flags
+Flag	Short	Description
+--continue	-c	Continue the last session
+--session	-s	Session ID to continue
+--prompt		Prompt to use
+--model	-m	Model to use in the form of provider/model
+--agent		Agent to use
+--port		Port to listen on
+--hostname		Hostname to listen on
+Commands
+The OpenCode CLI also has the following commands.
 
-Returns the list of accepted CLI agent name strings for option parsing.
+agent
+Manage agents for OpenCode.
 
-- **Returns:** `["opencode", "claude-code", "codex"]`
-- **Consumer:** `CLI` (used in OptionParser `--agent` validation and help text)
+Terminal window
+opencode agent [command]
 
-### `AGENT_NAME_MAP`
+attach
+Attach a terminal to an already running OpenCode backend server started via serve or web commands.
 
-Frozen hash mapping CLI strings to internal symbols used for subclass dispatch.
+Terminal window
+opencode attach [url]
 
-```ruby
-AGENT_NAME_MAP = {
-  "opencode"   => :opencode,
-  "claude-code" => :claude_code,
-  "codex"      => :codex
-}.freeze
-```
+This allows using the TUI with a remote OpenCode backend. For example:
+
+Terminal window
+# Start the backend server for web/mobile access
+opencode web --port 4096 --hostname 0.0.0.0
+
+# In another terminal, attach the TUI to the running backend
+opencode attach http://10.20.30.40:4096
+
+Flags
+Flag	Short	Description
+--dir		Working directory to start TUI in
+--session	-s	Session ID to continue
+create
+Create a new agent with custom configuration.
+
+Terminal window
+opencode agent create
+
+This command will guide you through creating a new agent with a custom system prompt and tool configuration.
+
+list
+List all available agents.
+
+Terminal window
+opencode agent list
+
+auth
+Command to manage credentials and login for providers.
+
+Terminal window
+opencode auth [command]
+
+login
+OpenCode is powered by the provider list at Models.dev, so you can use opencode auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/opencode/auth.json.
+
+Terminal window
+opencode auth login
+
+When OpenCode starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project.
+
+list
+Lists all the authenticated providers as stored in the credentials file.
+
+Terminal window
+opencode auth list
+
+Or the short version.
+
+Terminal window
+opencode auth ls
+
+logout
+Logs you out of a provider by clearing it from the credentials file.
+
+Terminal window
+opencode auth logout
 
-## Base Class
+github
+Manage the GitHub agent for repository automation.
 
-`Ralph::Agents::Base` is an abstract class that includes `Ralph::Helpers` and defines the interface every agent subclass must implement.
+Terminal window
+opencode github [command]
 
-### Abstract Methods
+install
+Install the GitHub agent in your repository.
 
-Subclasses must override all of the following. The base implementations raise `NotImplementedError`.
+Terminal window
+opencode github install
 
-| Method | Signature | Returns | Purpose |
-|--------|-----------|---------|---------|
-| `type` | `-> Symbol` | `:opencode`, `:claude_code`, or `:codex` | Internal identifier used for agent-specific branching |
-| `command` | `-> String` | CLI binary name | The executable name looked up on `$PATH` |
-| `config_name` | `-> String` | Human-readable name | Display name used in banners, warnings, status output |
-| `build_args` | `(prompt, model, options) -> Array<String>` | CLI argument array | Constructs the argument list for the agent subprocess |
-| `parse_tool_output` | `(line) -> String or nil` | Tool name or nil | Extracts a tool invocation name from a single output line |
+This sets up the necessary GitHub Actions workflow and guides you through the configuration process. Learn more.
 
-### Concrete Methods
+run
+Run the GitHub agent. This is typically used in GitHub Actions.
 
-| Method | Signature | Returns | Purpose |
-|--------|-----------|---------|---------|
-| `build_env` | `(options) -> Hash<String, String>` | Environment hash | Returns `ENV.to_h.dup`. Subclasses may override to customise the subprocess environment |
-| `validate!` | `-> void` | — | Checks that `command` is found on `$PATH` via `which`. Prints an error to `$stderr` and calls `exit 1` if missing |
+Terminal window
+opencode github run
 
-### `build_args` Parameters
+Flags
+Flag	Description
+--event	GitHub mock event to run the agent for
+--token	GitHub personal access token
+mcp
+Manage Model Context Protocol servers.
 
-- `prompt` — String, the full prompt text to send to the agent
-- `model` — String, model identifier (may be `nil` or empty to use the agent's default)
-- `options` — Hash with execution options:
-  - `:allow_all_permissions` — Boolean, whether to pass auto-approve flags
+Terminal window
+opencode mcp [command]
 
-### `parse_tool_output` Behaviour
+add
+Add an MCP server to your configuration.
 
-- Strips ANSI escape sequences from the line via `strip_ansi` (from `Ralph::Helpers`)
-- Applies an agent-specific regex to extract a tool name
-- Returns the tool name `String` if matched, `nil` otherwise
-- **Consumers:** `Iteration#stream_agent` (real-time tool counting), `Helpers.collect_tool_summary_from_text` (post-hoc counting)
+Terminal window
+opencode mcp add
 
-## Agent Subclasses
+This command will guide you through adding either a local or remote MCP server.
 
-### `Ralph::Agents::OpenCode`
+list
+List all configured MCP servers and their connection status.
 
-| Property | Value |
-|----------|-------|
-| `type` | `:opencode` |
-| `command` | `"opencode"` |
-| `config_name` | `"OpenCode"` |
+Terminal window
+opencode mcp list
 
-**`build_args` behaviour:**
-1. Starts with `["run"]`
-2. Appends `["-m", model]` if model is non-empty
-3. Appends the prompt as the final argument
+Or use the short version.
 
-**`parse_tool_output` regex:** `/^\|\s{2}([A-Za-z0-9_-]+)/`
+Terminal window
+opencode mcp ls
 
-Matches OpenCode's tool output format where tool names appear after a pipe and two spaces at the start of a line.
+auth
+Authenticate with an OAuth-enabled MCP server.
 
-### `Ralph::Agents::ClaudeCode`
+Terminal window
+opencode mcp auth [name]
 
-| Property | Value |
-|----------|-------|
-| `type` | `:claude_code` |
-| `command` | `"claude"` |
-| `config_name` | `"Claude Code"` |
+If you don’t provide a server name, you’ll be prompted to select from available OAuth-capable servers.
 
-**`build_args` behaviour:**
-1. Starts with `["-p", prompt]`
-2. Appends `["--model", model]` if model is non-empty
-3. Appends `"--dangerously-skip-permissions"` if `options[:allow_all_permissions]` is truthy
+You can also list OAuth-capable servers and their authentication status.
 
-**`parse_tool_output` regex:** `/(?:Using|Called|Tool:)\s+([A-Za-z0-9_-]+)/i`
+Terminal window
+opencode mcp auth list
 
-Matches Claude Code's tool output format where tool names follow "Using", "Called", or "Tool:" prefixes (case-insensitive).
+Or use the short version.
 
-### `Ralph::Agents::Codex`
+Terminal window
+opencode mcp auth ls
 
-| Property | Value |
-|----------|-------|
-| `type` | `:codex` |
-| `command` | `"codex"` |
-| `config_name` | `"Codex"` |
+logout
+Remove OAuth credentials for an MCP server.
 
-**`build_args` behaviour:**
-1. Starts with `["exec"]`
-2. Appends `["--model", model]` if model is non-empty
-3. Appends `"--full-auto"` if `options[:allow_all_permissions]` is truthy
-4. Appends the prompt as the final argument
+Terminal window
+opencode mcp logout [name]
 
-**`parse_tool_output` regex:** `/(?:Tool:|Using|Calling|Running)\s+([A-Za-z0-9_-]+)/i`
+debug
+Debug OAuth connection issues for an MCP server.
 
-Matches Codex's tool output format where tool names follow "Tool:", "Using", "Calling", or "Running" prefixes (case-insensitive).
+Terminal window
+opencode mcp debug <name>
 
-## Consumers
+models
+List all available models from configured providers.
 
-| Consumer | What it uses | How |
-|----------|-------------|-----|
-| `Loop#resolve_agent!` | `Agents.resolve`, `agent.validate!` | Resolves CLI name to instance, validates binary exists |
-| `Loop#initialize` | `agent.type`, `agent.config_name` | Agent-specific branching (plugin warnings), display name for banner/warnings |
-| `Iteration#execute_agent` | `agent.build_args`, `agent.build_env`, `agent.command` | Constructs and spawns the agent subprocess |
-| `Iteration#stream_agent` | `agent.parse_tool_output` | Real-time tool counting during streaming output |
-| `Helpers.collect_tool_summary_from_text` | `agent.parse_tool_output` | Post-hoc tool counting from buffered output |
-| `Output::Status` | `Agents.resolve`, `agent.config_name` | Display name in `--status` dashboard |
-| `CLI` | `Agents.valid_agent_names` | OptionParser validation and help text for `--agent` flag |
+Terminal window
+opencode models [provider]
 
-## Adding a New Agent
+This command displays all models available across your configured providers in the format provider/model.
 
-To add support for a new AI coding CLI:
+This is useful for figuring out the exact model name to use in your config.
 
-1. Create `lib/ralph/agents/<name>.rb` with a class inheriting from `Base`
-2. Implement all abstract methods: `type`, `command`, `config_name`, `build_args`, `parse_tool_output`
-3. Override `build_env` if the agent requires custom environment variables
-4. Add an entry to `AGENT_NAME_MAP` in `base.rb`
-5. Add a constructor lambda to the dispatch hash in `Agents.resolve`
+You can optionally pass a provider ID to filter models by that provider.
 
-## Testing Strategy
+Terminal window
+opencode models anthropic
 
-### Unit Tests
-- Verify each subclass returns correct `type`, `command`, and `config_name`
-- Test `build_args` with combinations of: empty model, non-empty model, permissions on/off
-- Test `parse_tool_output` with matching lines, non-matching lines, and lines containing ANSI escapes
-- Test `Agents.resolve` returns correct class for each valid name, `nil` for unknown names
-- Test `Agents.valid_agent_names` returns expected list
+Flags
+Flag	Description
+--refresh	Refresh the models cache from models.dev
+--verbose	Use more verbose model output (includes metadata like costs)
+Use the --refresh flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in OpenCode.
 
-### Integration Tests
-- Test `validate!` with a mocked `which` that returns nil (expect stderr output and `SystemExit`)
-- Test `validate!` with a mocked `which` that returns a path (expect no error)
+Terminal window
+opencode models --refresh
+
+run
+Run opencode in non-interactive mode by passing a prompt directly.
+
+Terminal window
+opencode run [message..]
+
+This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.
+
+Terminal window
+opencode run Explain the use of context in Go
+
+You can also attach to a running opencode serve instance to avoid MCP server cold boot times on every run:
+
+Terminal window
+# Start a headless server in one terminal
+opencode serve
+
+# In another terminal, run commands that attach to it
+opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"
+
+Flags
+Flag	Short	Description
+--command		The command to run, use message for args
+--continue	-c	Continue the last session
+--session	-s	Session ID to continue
+--share		Share the session
+--model	-m	Model to use in the form of provider/model
+--agent		Agent to use
+--file	-f	File(s) to attach to message
+--format		Format: default (formatted) or json (raw JSON events)
+--title		Title for the session (uses truncated prompt if no value provided)
+--attach		Attach to a running opencode server (e.g., http://localhost:4096)
+--port		Port for the local server (defaults to random port)
+serve
+Start a headless OpenCode server for API access. Check out the server docs for the full HTTP interface.
+
+Terminal window
+opencode serve
+
+This starts an HTTP server that provides API access to opencode functionality without the TUI interface. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to opencode).
+
+Flags
+Flag	Description
+--port	Port to listen on
+--hostname	Hostname to listen on
+--mdns	Enable mDNS discovery
+--cors	Additional browser origin(s) to allow CORS
+session
+Manage OpenCode sessions.
+
+Terminal window
+opencode session [command]
+
+list
+List all OpenCode sessions.
+
+Terminal window
+opencode session list
+
+Flags
+Flag	Short	Description
+--max-count	-n	Limit to N most recent sessions
+--format		Output format: table or json (table)
+stats
+Show token usage and cost statistics for your OpenCode sessions.
+
+Terminal window
+opencode stats
+
+Flags
+Flag	Description
+--days	Show stats for the last N days (all time)
+--tools	Number of tools to show (all)
+--models	Show model usage breakdown (hidden by default). Pass a number to show top N
+--project	Filter by project (all projects, empty string: current project)
+export
+Export session data as JSON.
+
+Terminal window
+opencode export [sessionID]
+
+If you don’t provide a session ID, you’ll be prompted to select from available sessions.
+
+import
+Import session data from a JSON file or OpenCode share URL.
+
+Terminal window
+opencode import <file>
+
+You can import from a local file or an OpenCode share URL.
+
+Terminal window
+opencode import session.json
+opencode import https://opncd.ai/s/abc123
+
+web
+Start a headless OpenCode server with a web interface.
+
+Terminal window
+opencode web
+
+This starts an HTTP server and opens a web browser to access OpenCode through a web interface. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to opencode).
+
+Flags
+Flag	Description
+--port	Port to listen on
+--hostname	Hostname to listen on
+--mdns	Enable mDNS discovery
+--cors	Additional browser origin(s) to allow CORS
+acp
+Start an ACP (Agent Client Protocol) server.
+
+Terminal window
+opencode acp
+
+This command starts an ACP server that communicates via stdin/stdout using nd-JSON.
+
+Flags
+Flag	Description
+--cwd	Working directory
+--port	Port to listen on
+--hostname	Hostname to listen on
+uninstall
+Uninstall OpenCode and remove all related files.
+
+Terminal window
+opencode uninstall
+
+Flags
+Flag	Short	Description
+--keep-config	-c	Keep configuration files
+--keep-data	-d	Keep session data and snapshots
+--dry-run		Show what would be removed without removing
+--force	-f	Skip confirmation prompts
+upgrade
+Updates opencode to the latest version or a specific version.
+
+Terminal window
+opencode upgrade [target]
+
+To upgrade to the latest version.
+
+Terminal window
+opencode upgrade
+
+To upgrade to a specific version.
+
+Terminal window
+opencode upgrade v0.1.48
+
+Flags
+Flag	Short	Description
+--method	-m	The installation method that was used; curl, npm, pnpm, bun, brew
+Global Flags
+The opencode CLI takes the following global flags.
+
+Flag	Short	Description
+--help	-h	Display help
+--version	-v	Print version number
+--print-logs		Print logs to stderr
+--log-level		Log level (DEBUG, INFO, WARN, ERROR)
+Environment variables
+OpenCode can be configured using environment variables.
+
+Variable	Type	Description
+OPENCODE_AUTO_SHARE	boolean	Automatically share sessions
+OPENCODE_GIT_BASH_PATH	string	Path to Git Bash executable on Windows
+OPENCODE_CONFIG	string	Path to config file
+OPENCODE_CONFIG_DIR	string	Path to config directory
+OPENCODE_CONFIG_CONTENT	string	Inline json config content
+OPENCODE_DISABLE_AUTOUPDATE	boolean	Disable automatic update checks
+OPENCODE_DISABLE_PRUNE	boolean	Disable pruning of old data
+OPENCODE_DISABLE_TERMINAL_TITLE	boolean	Disable automatic terminal title updates
+OPENCODE_PERMISSION	string	Inlined json permissions config
+OPENCODE_DISABLE_DEFAULT_PLUGINS	boolean	Disable default plugins
+OPENCODE_DISABLE_LSP_DOWNLOAD	boolean	Disable automatic LSP server downloads
+OPENCODE_ENABLE_EXPERIMENTAL_MODELS	boolean	Enable experimental models
+OPENCODE_DISABLE_AUTOCOMPACT	boolean	Disable automatic context compaction
+OPENCODE_DISABLE_CLAUDE_CODE	boolean	Disable reading from .claude (prompt + skills)
+OPENCODE_DISABLE_CLAUDE_CODE_PROMPT	boolean	Disable reading ~/.claude/CLAUDE.md
+OPENCODE_DISABLE_CLAUDE_CODE_SKILLS	boolean	Disable loading .claude/skills
+OPENCODE_CLIENT	string	Client identifier (defaults to cli)
+OPENCODE_ENABLE_EXA	boolean	Enable Exa web search tools
+OPENCODE_SERVER_PASSWORD	string	Enable basic auth for serve/web
+OPENCODE_SERVER_USERNAME	string	Override basic auth username (default opencode)
+Experimental
+These environment variables enable experimental features that may change or be removed.
+
+Variable	Type	Description
+OPENCODE_EXPERIMENTAL	boolean	Enable all experimental features
+OPENCODE_EXPERIMENTAL_ICON_DISCOVERY	boolean	Enable icon discovery
+OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT	boolean	Disable copy on select in TUI
+OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS	number	Default timeout for bash commands in ms
+OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX	number	Max output tokens for LLM responses
+OPENCODE_EXPERIMENTAL_FILEWATCHER	boolean	Enable file watcher for entire dir
+OPENCODE_EXPERIMENTAL_OXFMT	boolean	Enable oxfmt formatter
+OPENCODE_EXPERIMENTAL_LSP_TOOL	boolean	Enable experimental LSP tool
+OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER	boolean	Disable file watcher
+OPENCODE_EXPERIMENTAL_EXA	boolean	Enable experimental Exa features
+OPENCODE_EXPERIMENTAL_LSP_TY	boolean	Enable experimental LSP type checking
+OPENCODE_EXPERIMENTAL_MARKDOWN	boolean	Enable experimental markdown features
+OPENCODE_EXPERIMENTAL_PLAN_MODE	boolean	Enable plan mode
+```
+
+## JSON streams
+
+Opencode will output JSON streams from the cli, which we will read to determine the metrics from the iteration.
+
+### Events
+
+These are the events that the opencode docs spcify for plugins.
+
+```
+Command Events
+command.executed
+File Events
+file.edited
+file.watcher.updated
+Installation Events
+installation.updated
+LSP Events
+lsp.client.diagnostics
+lsp.updated
+Message Events
+message.part.removed
+message.part.updated
+message.removed
+message.updated
+Permission Events
+permission.asked
+permission.replied
+Server Events
+server.connected
+Session Events
+session.created
+session.compacted
+session.deleted
+session.diff
+session.error
+session.idle
+session.status
+session.updated
+Todo Events
+todo.updated
+Tool Events
+tool.execute.after
+tool.execute.before
+TUI Events
+tui.prompt.append
+tui.command.execute
+tui.toast.show
+```