docs: add 11 new documentation files across all categories
New reference docs: - agents/ref-btmsg.md: inter-agent messaging schema and CLI - agents/ref-bttask.md: kanban task board operations - providers/ref-providers.md: Claude/Codex/Ollama/Aider comparison - config/ref-settings.md: (already committed) New guides: - contributing/dual-repo-workflow.md: community vs commercial repos - plugins/guide-developing.md: Web Worker sandbox API and publishing New pro docs: - pro/features/knowledge-base.md: persistent memory + symbol graph - pro/features/git-integration.md: context injection + branch policy - pro/marketplace/README.md: 13 plugins catalog Split files: - architecture/data-model.md: from architecture.md (schemas, layout) - production/hardening.md: from production.md (supervisor, sandbox, WAL) - production/features.md: from production.md (FTS5, plugins, secrets, audit)
This commit is contained in:
Hibryda
parent
8251321dac
commit
b6c1d4b6af
11 changed files with 2198 additions and 0 deletions
184
docs/providers/ref-providers.md
Normal file
184
docs/providers/ref-providers.md
Normal file
|
|
@ -0,0 +1,184 @@
|
|||
# Provider Reference
|
||||
|
||||
Agents Orchestrator supports 4 agent providers. Each provider has its own sidecar
|
||||
runner, message adapter, and capability set. Providers are selected per-project
|
||||
in `groups.json` or via the Settings tab.
|
||||
|
||||
## Provider summary
|
||||
|
||||
| Provider | ID | Default Model | Sidecar Runner | API |
|
||||
|----------|----|---------------|----------------|-----|
|
||||
| Claude Code | `claude` | claude-opus-4-6 | `claude-runner.mjs` | Claude Agent SDK |
|
||||
| Codex CLI | `codex` | gpt-5.4 | `codex-runner.mjs` | @openai/codex-sdk |
|
||||
| Ollama | `ollama` | qwen3:8b | `ollama-runner.mjs` | REST (localhost:11434) |
|
||||
| Aider | `aider` | openrouter/anthropic/claude-sonnet-4 | `aider-runner.mjs` | OpenRouter / direct |
|
||||
|
||||
## Capabilities
|
||||
|
||||
Each provider declares capabilities that gate UI features:
|
||||
|
||||
| Capability | Claude | Codex | Ollama | Aider |
|
||||
|------------|--------|-------|--------|-------|
|
||||
| `hasProfiles` | Yes | No | No | No |
|
||||
| `hasSkills` | Yes | No | No | No |
|
||||
| `hasModelSelection` | Yes | Yes | Yes | Yes |
|
||||
| `hasSandbox` | No | Yes | No | No |
|
||||
| `supportsSubagents` | Yes | No | No | No |
|
||||
| `supportsCost` | Yes | No | No | No |
|
||||
| `supportsResume` | Yes | Yes | No | No |
|
||||
|
||||
When a capability is `false`, the corresponding UI element is hidden. For
|
||||
example, profile selectors and skill autocomplete only appear for Claude.
|
||||
|
||||
## Provider type
|
||||
|
||||
```typescript
|
||||
type ProviderId = 'claude' | 'codex' | 'ollama' | 'aider';
|
||||
```
|
||||
|
||||
Defined in `src/lib/providers/types.ts`.
|
||||
|
||||
## Provider selection
|
||||
|
||||
Set `provider` on a `ProjectConfig` in `groups.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "my-project",
|
||||
"name": "My Project",
|
||||
"cwd": "/home/user/code/project",
|
||||
"provider": "codex",
|
||||
"model": "o3"
|
||||
}
|
||||
```
|
||||
|
||||
If omitted, defaults to `claude`.
|
||||
|
||||
## Claude Code
|
||||
|
||||
- **Source:** `src/lib/providers/claude.ts`
|
||||
- **Runner:** `sidecar/claude-runner.ts` (compiled to `sidecar/dist/claude-runner.mjs`)
|
||||
- **SDK:** `@anthropic-ai/claude-agent-sdk` `query()` function
|
||||
- **CLI detection:** Auto-detects Claude CLI at startup. Checks paths in order:
|
||||
`~/.local/bin/claude`, `~/.claude/local/claude`, `/usr/local/bin/claude`,
|
||||
`/usr/bin/claude`, then `which claude`. Agent errors immediately if not found.
|
||||
- **Config dir:** Override with `CLAUDE_CONFIG_DIR` for multi-account setups.
|
||||
Mapped to `claude_config_dir` in `AgentQueryOptions`.
|
||||
|
||||
Available models:
|
||||
|
||||
| Model ID | Label |
|
||||
|----------|-------|
|
||||
| `claude-opus-4-6` | Opus 4.6 |
|
||||
| `claude-sonnet-4-6` | Sonnet 4.6 |
|
||||
| `claude-haiku-4-5-20251001` | Haiku 4.5 |
|
||||
|
||||
## Codex CLI
|
||||
|
||||
- **Source:** `src/lib/providers/codex.ts`
|
||||
- **Runner:** `sidecar/codex-runner.ts` (compiled to `sidecar/dist/codex-runner.mjs`)
|
||||
- **SDK:** `@openai/codex-sdk` (dynamic import; graceful failure if not installed)
|
||||
- **Sandbox:** Maps agor sandbox settings to Codex approval modes.
|
||||
- **Env:** Requires `OPENAI_API_KEY`.
|
||||
|
||||
Available models:
|
||||
|
||||
| Model ID | Label |
|
||||
|----------|-------|
|
||||
| `gpt-5.4` | GPT-5.4 |
|
||||
| `o3` | o3 |
|
||||
| `o4-mini` | o4-mini |
|
||||
|
||||
## Ollama
|
||||
|
||||
- **Source:** `src/lib/providers/ollama.ts`
|
||||
- **Runner:** `sidecar/ollama-runner.ts` (compiled to `sidecar/dist/ollama-runner.mjs`)
|
||||
- **API:** Direct HTTP to `localhost:11434` (native fetch, zero external deps)
|
||||
- **Prereq:** Ollama must be running locally before starting an agent session.
|
||||
|
||||
Available models:
|
||||
|
||||
| Model ID | Label |
|
||||
|----------|-------|
|
||||
| `qwen3:8b` | Qwen3 8B |
|
||||
| `qwen3:32b` | Qwen3 32B |
|
||||
| `llama3.3:70b` | Llama 3.3 70B |
|
||||
| `deepseek-r1:14b` | DeepSeek R1 14B |
|
||||
| `codellama:13b` | Code Llama 13B |
|
||||
|
||||
## Aider
|
||||
|
||||
- **Source:** `src/lib/providers/aider.ts`
|
||||
- **Runner:** `sidecar/aider-runner.ts` (compiled to `sidecar/dist/aider-runner.mjs`)
|
||||
- **Routing:** Supports OpenRouter, OpenAI direct, Anthropic direct, and Ollama
|
||||
local models via model ID prefixes.
|
||||
- **Env:** Requires `OPENROUTER_API_KEY` for OpenRouter models, `OPENAI_API_KEY`
|
||||
for OpenAI direct, `ANTHROPIC_API_KEY` for Anthropic direct.
|
||||
- **Autonomous mode:** Supports `restricted` (surfaces commands for approval) and
|
||||
`autonomous` (auto-executes with audit logging) via `autonomousMode` project
|
||||
config.
|
||||
|
||||
Available models:
|
||||
|
||||
| Model ID | Label |
|
||||
|----------|-------|
|
||||
| `openrouter/anthropic/claude-sonnet-4` | Claude Sonnet 4 (OpenRouter) |
|
||||
| `openrouter/anthropic/claude-haiku-4` | Claude Haiku 4 (OpenRouter) |
|
||||
| `openrouter/openai/gpt-4.1` | GPT-4.1 (OpenRouter) |
|
||||
| `openrouter/openai/o3` | o3 (OpenRouter) |
|
||||
| `openrouter/google/gemini-2.5-pro` | Gemini 2.5 Pro (OpenRouter) |
|
||||
| `openrouter/deepseek/deepseek-r1` | DeepSeek R1 (OpenRouter) |
|
||||
| `openrouter/meta-llama/llama-4-maverick` | Llama 4 Maverick (OpenRouter) |
|
||||
| `anthropic/claude-sonnet-4-5-20250514` | Claude Sonnet 4.5 (direct) |
|
||||
| `o3` | o3 (OpenAI direct) |
|
||||
| `ollama/qwen3:8b` | Qwen3 8B (Ollama) |
|
||||
|
||||
## Sidecar architecture
|
||||
|
||||
Each provider has a runner script compiled to a standalone ESM bundle in
|
||||
`sidecar/dist/`. The sidecar communicates with the Rust backend via stdio
|
||||
NDJSON.
|
||||
|
||||
Build all runners:
|
||||
|
||||
```bash
|
||||
npm run build:sidecar
|
||||
```
|
||||
|
||||
### Provider routing
|
||||
|
||||
`SidecarManager.resolve_sidecar_for_provider(provider)` selects the runner file
|
||||
based on `ProviderId`. The sidecar process runs under Deno (preferred, faster
|
||||
startup) with Node.js as fallback.
|
||||
|
||||
### Environment stripping
|
||||
|
||||
The sidecar strips provider-specific environment variables to prevent
|
||||
cross-contamination. The function `strip_provider_env_var()` in
|
||||
`agor-core/src/sidecar.rs` filters the process environment:
|
||||
|
||||
- **Stripped:** `CLAUDE_*`, `CODEX_*`, `OLLAMA_*` (and similar provider vars)
|
||||
- **Preserved:** `CLAUDE_CODE_EXPERIMENTAL_*` (whitelist for experimental flags)
|
||||
- **Preserved:** Standard vars (`HOME`, `PATH`, `USER`, `SHELL`, `TERM`,
|
||||
`XDG_*`, `RUST_LOG`, etc.)
|
||||
|
||||
This is applied in two layers:
|
||||
|
||||
1. **Rust:** `env_clear()` + filtered `clean_env` on the spawned process
|
||||
2. **JavaScript:** Runner SDK `env` option for provider-specific overrides
|
||||
|
||||
## Message adapters
|
||||
|
||||
Each provider has a message adapter that parses provider-specific output into a
|
||||
common `AgentMessage` format:
|
||||
|
||||
| Provider | Adapter | Tests |
|
||||
|----------|---------|-------|
|
||||
| Claude | `src/lib/adapters/claude-messages.ts` | 25 tests |
|
||||
| Codex | `src/lib/adapters/codex-messages.ts` | 19 tests |
|
||||
| Ollama | `src/lib/adapters/ollama-messages.ts` | 11 tests |
|
||||
| Aider | `sidecar/aider-parser.ts` | 72 tests |
|
||||
|
||||
Adapters are registered in `src/lib/adapters/message-adapters.ts` and routed by
|
||||
`ProviderId`. The dispatcher (`src/lib/agent-dispatcher.ts`) delegates to the
|
||||
correct adapter based on the session's provider.
|
||||
Loading…
Add table
Add a link
Reference in a new issue