@emaxe/agento 0.1.1 → 0.2.0

package/README.md

@@ -7,14 +7,16 @@
 
 AgentO is a CLI tool that centralizes configuration management for popular AI coding agents. Define your API providers once, create profiles with different model combinations, and switch between them with a single command.
 
+**Русская версия:** [README.ru.md](README.ru.md)
+
 ## Supported Agents
 
-| Agent | Command | Config Format | Special Features |
-|-------|---------|---------------|------------------|
-| [Claude Code](https://github.com/anthropics/claude-code) | `claude` | JSON | Multi-tier support (small/base/smart) |
-| [OpenCode](https://github.com/opencode-ai/opencode) | `opencode` | JSON | Custom provider prefix |
-| [Qwen CLI](https://github.com/QwenLM/qwen) | `qwen` | JSON | OpenAI-compatible providers |
-| [Codex CLI](https://github.com/openai/codex) | `codex` | TOML | Environment variable injection. Hidden by default (`--dev` to show). |
+| Agent | Command | Config Format | Supported Providers | Special Features |
+|-------|---------|---------------|---|------------------|
+| [Claude Code](https://github.com/anthropics/claude-code) | `claude` | JSON | `anthropic`, `fireworks` | Multi-tier support (small/base/smart) |
+| [OpenCode](https://github.com/opencode-ai/opencode) | `opencode` | JSON | `anthropic`, `openai-compatible`, `fireworks` | Full function calling support via Vercel AI SDK |
+| [Qwen CLI](https://github.com/QwenLM/qwen) | `qwen` | JSON | `openai-compatible`, `fireworks` | OpenAI-compatible API structure |
+| [Codex CLI](https://github.com/openai/codex) | `codex` | TOML | All types | Environment variable injection. Hidden by default (`--dev` to show). |
 
 ## Installation
 
@@ -36,25 +38,63 @@ npx @emaxe/agento
 - Node.js ≥ 18
 - One or more supported AI agent CLI tools installed
 
+## Supported Provider Types
+
+| Provider Type | Compatible Agents | Examples |
+|---|---|---|
+| `anthropic` | claude-code | Anthropic |
+| `openai-compatible` | opencode, qwen | OpenAI, Together.ai, Cerebras, Perplexity, DeepSeek, etc. |
+| `fireworks` | claude-code, opencode, qwen, codex | Fireworks AI (supports all 3 API types) |
+
+**Note:** `claude-code` only works with `anthropic` and `fireworks` types (Anthropic SDK requirement). Use `opencode` or `qwen` for other OpenAI-compatible providers.
+
+## Model Capability Flags
+
+Every model in a provider carries three capability flags that describe which modalities it supports:
+
+- **`image`** — model can process image inputs
+- **`video`** — model can process video inputs
+- **`audio`** — model can process audio inputs
+
+Defaults when adding a model: `image=true`, `video=false`, `audio=false`.
+
+**Marker format:** in the TUI and `agento provider list`, capabilities render as `[iva]` (all on), `[i--]` (image only), `[---]` (text only), etc. The marker is informational and is **never** written into the launched agent's config.
+
+**Why it matters:**
+- **Qwen** receives `generationConfig.modalities` derived from these flags (previously hardcoded to `false` — images didn't work).
+- **OpenCode** emits per-model `modalities: { input: ["text", "image", ...], output: ["text"] }` so the agent knows what the model accepts.
+- **Claude Code** and **Codex** ignore these flags today (Anthropic SDK and Codex `responses` API don't expose modality config).
+
+**Toggling capabilities:** open the TUI → Providers → Edit, navigate to a model row, press `i` / `v` / `a` to toggle each flag. Add new models via the `[+ add model]` row (Enter). The CLI `provider add -M ...` creates models with default capabilities.
+
+> Existing configs from older versions (with `string[]` models) are auto-migrated on first read with default capabilities.
+
 ## Quick Start
 
-### 1. Add an API Provider
+### 1. Add API Providers
 
 ```bash
-# OpenAI-compatible provider (e.g., Fireworks AI)
-agento provider add \
-  -n "Fireworks AI" \
-  -t openai-compatible \
-  -k "sk-your-api-key" \
-  -u "https://api.fireworks.ai/inference/v1" \
-  -M "accounts/fireworks/models/llama-v3p1-70b-instruct,accounts/fireworks/models/kimi-k2p6"
-
 # Anthropic provider
 agento provider add \
   -n "Anthropic" \
   -t anthropic \
   -k "sk-ant-your-key" \
   -M "claude-sonnet-4-20250514,claude-3-5-haiku-20241022"
+
+# Fireworks AI provider (works with all agents)
+agento provider add \
+  -n "Fireworks" \
+  -t fireworks \
+  -k "fw-your-key" \
+  -M "accounts/fireworks/models/llama-v3p1-70b-instruct,accounts/fireworks/models/kimi-k2p6"
+
+# Other OpenAI-compatible providers (use with opencode or qwen)
+agento provider add \
+  -n "Together" \
+  -t openai-compatible \
+  -k "your-api-key" \
+  -u "https://api.together.xyz/v1" \
+  -M "meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo"
 ```
 
 ### 2. Create a Profile
@@ -73,19 +113,24 @@ agento profile add -n "multi" -m "provider-id:claude-3-5-haiku-20241022:small,pr
 # Interactive TUI mode (default)
 agento
 
-# Direct launch
+# Direct launch with Anthropic/Fireworks provider
 agento launch -p default -a claude-code
 
+# Launch with OpenAI-compatible provider (use opencode or qwen)
+agento launch -p openai-profile -a opencode
+
 # Launch with specific mode and scope
 agento launch -p default -a qwen -m child -s project
 ```
 
 ## Interactive TUI
 
-Running `agento` without arguments launches an interactive Terminal User Interface:
+Running `agento` without arguments launches an interactive Terminal User Interface built with [Ink](https://github.com/vadimdemedes/ink) and React.
+
+### Main Menu
 
 ```
-┌────────── AgentO v0.1.0 ──────────┐
+┌────────── AgentO v0.2.0 ──────────┐
 │                                   │
 │ ▶  Launch Agent                   │
 │    Providers                      │
@@ -96,9 +141,100 @@ Running `agento` without arguments launches an interactive Terminal User Interfa
 └───────────────────────────────────┘
 ```
 
-- **↑↓** Navigate
-- **Enter** Select
-- **Esc / q** Back/Quit
+**Navigation:** **↑↓** to move, **Enter** to select, **Esc / q** to quit.
+
+### Screens Overview
+
+| Screen | What You Can Do | Key Shortcuts |
+|--------|----------------|---------------|
+| **Launch Agent** | Select profile → select agent → choose mode/scope → launch | **Enter** select, **Esc** back |
+| **Providers** | View, add, edit, delete API providers; toggle model capabilities | **Enter** details / add model, **a** add provider, **e** edit, **d** delete, **i/v/a** toggle capability, **Esc** back |
+| **Profiles** | View, add, delete profiles. In profile details: add/remove/edit models | **Enter** details, **a** add, **d** delete, **Esc** back |
+| **Agents** | Check config status (global/project), backup availability | **Enter** details, **Esc** back |
+| **Settings** | Change default launch mode, default config scope, independent mode | **↑↓** change, **Enter** toggle, **Esc** save & back |
+
+### Launch Agent Workflow
+
+1. **Select Profile** — Choose from your saved profiles
+2. **Select Agent** — Pick which agent to launch (claude-code, opencode, qwen, or codex with `--dev`)
+3. **Optional:** Adjust **Mode** (child/independent) and **Scope** (global/project)
+4. **Launch** — AgentO patches the agent config and starts the agent
+
+```
+Profile: default
+├─ Agent: claude-code
+├─ Mode: child
+├─ Scope: global
+└─ [ Launch ]
+```
+
+In **child mode**, you'll be returned to AgentO when the agent exits, and the original config is automatically restored.
+
+In **independent mode**, AgentO exits immediately and leaves the patched config in place.
+
+### Providers Screen
+
+Manage your API providers without memorizing CLI flags:
+
+- **View** all providers with their type, models, capability markers, and base URL
+- **Add** a new provider with guided prompts (name, type, API key, models, base URL)
+- **Edit** existing provider details — including per-model capability flags (`i`/`v`/`a` toggles)
+- **Delete** providers you no longer need
+
+In edit view, models render as `▶ [i--] model-name`. Press `i` / `v` / `a` while a model row is highlighted to toggle image / video / audio capabilities. Use the `[+ add model]` row (Enter) to append models, `d` to delete, `e` to rename.
+
+### Profiles Screen
+
+Organize your model configurations:
+
+- **View** all profiles with their models and tiers
+- **Add** profiles with single or multi-tier model configurations
+- **In profile details:** add/remove/edit individual model assignments
+
+### Agents Screen
+
+Monitor the status of your agent configurations:
+
+- See if each agent has a **global** or **project** config
+- Check if **backups** exist (indicating AgentO has previously patched the config)
+- View config file paths for each agent
+
+### Settings Screen
+
+Configure defaults for AgentO behavior:
+
+| Setting | Options | Description |
+|---------|---------|-------------|
+| **Default Launch Mode** | `child` / `independent` | How agents are launched by default |
+| **Default Config Scope** | `global` / `project` | Where agent configs are written |
+| **Independent Mode** | `spawn-detached` / `pty` | How independent mode spawns agents |
+
+**Controls:** **↑↓** navigate between settings, **Enter** or **Space** toggle values, **Esc** save and return.
+
+### TUI vs CLI
+
+| Task | TUI | CLI |
+|------|-----|-----|
+| Explore providers visually | ✅ | — |
+| Quick one-off launch | — | `agento launch -p <p> -a <a>` |
+| Script automation | — | ✅ |
+| Check agent config status | ✅ | `agento agent status` |
+| Guided provider/profile creation | ✅ | Manual flag composition |
+
+Use **TUI** for exploration and interactive workflows. Use **CLI** for scripting, aliases, and quick launches.
+
+## Provider & Agent Compatibility Matrix
+
+| Provider Type | claude-code | opencode | qwen | codex |
+|---|---|---|---|---|
+| **anthropic** | ✅ Full support | ✅ (via SDK) | ❌ Not supported | ✅ (via Responses API) |
+| **openai-compatible** | ❌ Not supported | ✅ Full support | ✅ Full support | ✅ (via Responses API) |
+| **fireworks** | ✅ (Anthropic API) | ✅ (OpenAI API) | ✅ (OpenAI API) | ✅ (Responses API) |
+
+**Key Constraints:**
+- `claude-code` uses **Anthropic SDK** and only works with `anthropic` or `fireworks` types
+- Other OpenAI-compatible providers must use `opencode` or `qwen` agents
+- `fireworks` type is the most flexible — works with all agents through native Fireworks APIs
 
 ## CLI Reference
 
@@ -140,13 +276,18 @@ Options:
 agento provider list                          # List all providers
 agento provider add [options]                 # Add a new provider
   -n, --name <name>         Provider display name (required)
-  -t, --type <type>         Provider type: openai-compatible or anthropic (required)
+  -t, --type <type>         Provider type: anthropic, openai-compatible, or fireworks (required)
   -k, --api-key <key>       API key (required)
-  -u, --base-url <url>      Base URL (for openai-compatible)
+  -u, --base-url <url>      Base URL (required for openai-compatible, optional for others)
   -M, --models <models>     Comma-separated list of model names (required)
 agento provider remove <name>                 # Remove a provider
 ```
 
+**Base URL Defaults:**
+- `anthropic`: Uses Anthropic's default endpoint
+- `fireworks`: Auto-defaults to `https://api.fireworks.ai/inference` if not specified
+- `openai-compatible`: Must be explicitly provided with `-u`
+
 ### `agento profile` — Manage Profiles
 
 ```bash
@@ -185,11 +326,32 @@ AgentO stores its configuration in `~/.agento/config.json`:
   "providers": [
     {
       "id": "uuid",
-      "name": "Fireworks AI",
+      "name": "Anthropic",
+      "type": "anthropic",
+      "apiKey": "sk-ant-...",
+      "models": [
+        { "name": "claude-opus-4-20250514", "capabilities": { "image": true, "video": false, "audio": false } },
+        { "name": "claude-sonnet-4-20250514", "capabilities": { "image": true, "video": false, "audio": false } }
+      ]
+    },
+    {
+      "id": "uuid",
+      "name": "Fireworks",
+      "type": "fireworks",
+      "apiKey": "fw-...",
+      "models": [
+        { "name": "accounts/fireworks/models/llama-v3p1-70b-instruct", "capabilities": { "image": false, "video": false, "audio": false } }
+      ]
+    },
+    {
+      "id": "uuid",
+      "name": "Together",
       "type": "openai-compatible",
-      "apiKey": "sk-...",
-      "baseUrl": "https://api.fireworks.ai/inference/v1",
-      "models": ["accounts/fireworks/models/llama-v3p1-70b-instruct"]
+      "apiKey": "your-api-key",
+      "baseUrl": "https://api.together.xyz/v1",
+      "models": [
+        { "name": "meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo", "capabilities": { "image": false, "video": false, "audio": false } }
+      ]
     }
   ],
   "profiles": [
@@ -213,16 +375,23 @@ AgentO stores its configuration in `~/.agento/config.json`:
 }
 ```
 
+> Configs created with AgentO < 0.2.0 use bare `string[]` for `models`. They are migrated automatically on read; capabilities default to `{ image: true, video: false, audio: false }` and can be adjusted in the TUI.
+
 ## How It Works
 
 ### Agent Adapters
 
 Each supported agent has a dedicated adapter that translates AgentO's generic config format into the agent's specific configuration:
 
-- **Claude Code**: Generates `~/.claude/settings.json` with tier-based model selection
-- **OpenCode**: Generates `~/.config/opencode/config.json` with provider-prefixed model names
-- **Qwen CLI**: Generates `~/.qwen/settings.json` with OpenAI-compatible provider structure
-- **Codex CLI** (`--dev` to show): Generates `~/.codex/config.toml` with `wire_api: responses`, profiles, and environment variable references. In project scope, splits config between global (`model_providers`) and project (`model`) configs.
+- **Claude Code** (supports `anthropic`, `fireworks`): Generates `~/.claude/settings.json` with tier-based model selection and ANTHROPIC_* env vars. Uses Anthropic SDK.
+  - ⚠️ **Does NOT support** `openai-compatible` providers (Anthropic SDK incompatibility)
+  - Capability flags are not propagated (Anthropic SDK doesn't expose modality config)
+  
+- **OpenCode** (supports `anthropic`, `openai-compatible`, `fireworks`): Generates `~/.config/opencode/config.json` using Vercel AI SDK with provider-prefixed model names. Full function calling support via `@ai-sdk/openai-compatible`. Emits per-model `modalities: { input: [...], output: ["text"] }` derived from capability flags.
+  
+- **Qwen CLI** (supports `openai-compatible`, `fireworks`): Generates `~/.qwen/settings.json` with OpenAI-compatible provider structure. Requires `baseUrl` for all providers. Auto-defaults for `fireworks` type. Passes capability flags via `generationConfig.modalities`.
+  
+- **Codex CLI** (`--dev` to show): Generates `~/.codex/config.toml` with `wire_api: responses`, profiles, and environment variable references. In project scope, splits config between global (`model_providers`) and project (`model`) configs. Supports all provider types. Capability flags are not propagated (Codex `responses` API has no modality config).
 
 ### Backup & Restore
 
@@ -267,6 +436,37 @@ src/
 └── tui/              # Terminal UI (Ink + React)
 ```
 
+## Limitations & Known Issues
+
+### Claude Code with OpenAI-Compatible Providers
+
+**Problem:** Claude Code only works with Anthropic API due to hard dependency on Anthropic SDK.
+
+**Solution:** Use `opencode` or `qwen` agents instead:
+```bash
+# ❌ This won't work:
+agento launch -p myprofile -a claude-code  # (if profile uses openai-compatible provider)
+
+# ✅ Use OpenCode instead:
+agento launch -p myprofile -a opencode
+```
+
+### Qwen CLI with Missing Base URL
+
+**Problem:** Qwen requires `baseUrl` for all providers. Using `anthropic` type without URL will error.
+
+**Solution:** Always provide `-u` for Qwen with non-standard providers, or use `fireworks` type which auto-defaults.
+
+### Codex CLI Hidden by Default
+
+**Problem:** Codex is a development agent and hidden in TUI/CLI by default.
+
+**Solution:** Add `--dev` flag to show it:
+```bash
+agento --dev                # TUI with Codex
+agento launch -a codex --dev  # CLI with Codex
+```
+
 ## Troubleshooting
 
 ### Changes in `src/` not applied