Repository navigation
feat: provider architecture consolidation (Phase 0-3) #27
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 7 commits
777a220
2117acc
c222a97
3f5d32d
d1aebef
d4197f1
6ae1544
83ce718
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| # Provider Failure Matrix | ||
|
|
||
| Populated failure matrix mapping operations, providers, error types, and recovery behavior. | ||
|
|
||
| ## Error Categories | ||
|
|
||
| | Category | Description | Recovery Strategy | | ||
| |-----------------|--------------------------------------------|--------------------------------------------| | ||
| | `transient` | Temporary failure, may succeed on retry | Retry with exponential backoff (max 3) | | ||
| | `permanent` | Unrecoverable error | Fail immediately, surface to user | | ||
| | `configuration` | Misconfigured provider/environment | Re-resolve config, prompt user to fix | | ||
| | `unavailable` | Provider is down or unreachable | Degrade gracefully, suggest fallback | | ||
|
|
||
| ## Failure Matrix | ||
|
|
||
| | Operation | Provider | Error Class | Category | Current Behavior | Desired Behavior | | ||
| |--------------------|----------------|--------------------------------------|-----------------|---------------------------------|-------------------------------------------| | ||
| | `startSession` | codex (harness)| `ProviderAdapterProcessError` | `configuration` | Error propagated to transport | Check binary exists before spawn | | ||
| | `startSession` | codex (harness)| `ProviderAdapterRequestError` | `transient` | Error propagated to transport | Retry spawn with backoff | | ||
| | `startSession` | claudeAgent | `ProviderAdapterProcessError` | `configuration` | Error propagated to transport | Validate API key before spawn | | ||
| | `startSession` | claudeAgent | `ProviderAdapterRequestError` | `transient` | Error propagated to transport | Retry with backoff | | ||
| | `startSession` | cursor (harness)| `ProviderAdapterProcessError` | `configuration` | Error propagated to transport | Check cursor binary path | | ||
| | `startSession` | opencode (harness)| `ProviderAdapterProcessError` | `configuration` | Error propagated to transport | Check opencode binary path | | ||
| | `startSession` | any | `ProviderValidationError` | `permanent` | Error propagated to transport | Correct (no change needed) | | ||
| | `startSession` | any | `ProviderUnsupportedError` | `configuration` | Error propagated to transport | Suggest enabling provider in settings | | ||
| | `sendTurn` | codex (harness)| `ProviderAdapterRequestError` | `transient` | Error propagated to transport | Auto-retry once, then surface | | ||
| | `sendTurn` | codex (harness)| `ProviderAdapterSessionNotFoundError`| `permanent` | Recovery via `recoverSessionForThread` | Correct (recovery already implemented) | | ||
| | `sendTurn` | claudeAgent | `ProviderAdapterRequestError` | `transient` | Error propagated to transport | Auto-retry once, then surface | | ||
| | `sendTurn` | claudeAgent | `ProviderAdapterSessionClosedError` | `permanent` | Error propagated to transport | Prompt user to start new session | | ||
| | `sendTurn` | any | `ProviderValidationError` | `permanent` | Error propagated to transport | Correct (validation is permanent) | | ||
| | `interruptTurn` | codex (harness)| `ProviderAdapterRequestError` | `transient` | Error propagated to transport | Best-effort interrupt, log failure | | ||
| | `interruptTurn` | claudeAgent | `ProviderAdapterRequestError` | `transient` | Error propagated to transport | Best-effort interrupt, log failure | | ||
| | `respondToRequest` | codex (harness)| `ProviderAdapterRequestError` | `transient` | Error propagated to transport | Retry once for approval responses | | ||
| | `respondToRequest` | claudeAgent | `ProviderAdapterRequestError` | `transient` | Error propagated to transport | Retry once for approval responses | | ||
| | `stopSession` | codex (harness)| `ProviderAdapterRequestError` | `transient` | Error propagated to transport | Force-stop on timeout | | ||
| | `stopSession` | claudeAgent | `ProviderAdapterProcessError` | `unavailable` | Error propagated to transport | Kill process, mark session closed | | ||
| | `rollbackConversation` | codex (harness)| `ProviderAdapterRequestError` | `transient` | Recovery via resume + rollback | Correct (already recovers) | | ||
| | `rollbackConversation` | claudeAgent | `ProviderAdapterRequestError` | `transient` | Error propagated to transport | Resume session first, then rollback | | ||
| | `listSessions` | any | (no errors expected) | - | Returns empty on failure | Correct | | ||
| | `getCapabilities` | any | `ProviderUnsupportedError` | `configuration` | Error propagated to transport | Return empty capabilities for unknown | | ||
|
|
||
| ## Error Classification by `_tag` | ||
|
|
||
| | Error `_tag` | Default Category | Notes | | ||
| |----------------------------------------------|------------------|--------------------------------------------| | ||
| | `ProviderAdapterRequestError` | `transient` | Promoted to `permanent` if detail contains "not found", "unauthorized", "forbidden" | | ||
| | `ProviderAdapterProcessError` | `transient` | Promoted to `configuration` if ENOENT/permission; `unavailable` if crashed/signal | | ||
| | `ProviderAdapterValidationError` | `permanent` | Invalid input to adapter API | | ||
| | `ProviderAdapterSessionNotFoundError` | `permanent` | Session ID does not exist | | ||
| | `ProviderAdapterSessionClosedError` | `permanent` | Session exists but is closed | | ||
| | `ProviderValidationError` | `permanent` | Invalid input to ProviderService API | | ||
| | `ProviderUnsupportedError` | `configuration` | Provider not registered | | ||
| | `ProviderSessionNotFoundError` | `permanent` | Thread not found in session directory | | ||
| | `ProviderSessionDirectoryPersistenceError` | `transient` | SQLite/persistence layer failure | |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,158 @@ | ||
| # Provider Onboarding Playbook | ||
|
|
||
| Guide for adding a new coding agent provider to T3 Code. | ||
|
|
||
| ## Architecture Overview | ||
|
|
||
| T3 Code uses a layered adapter architecture: | ||
|
|
||
| ``` | ||
| Transport (WebSocket/RPC) | ||
| | | ||
| ProviderService (cross-provider facade) | ||
| | | ||
| ProviderAdapterRegistry (adapter lookup) | ||
| | | ||
| ProviderAdapter (provider-specific runtime) | ||
| | | ||
| Provider CLI/SDK (codex, claude, cursor, opencode, ...) | ||
| ``` | ||
|
|
||
| **Two runtime paths**: | ||
|
|
||
| - **Node SDK adapters** (ClaudeAdapter, CodexAdapter) -- run in-process via JS/TS SDKs | ||
| - **Harness adapters** (HarnessClientAdapter) -- bridge to Elixir GenServer sessions via WebSocket | ||
|
|
||
| Most new providers will use the **harness path** (Elixir GenServer) unless they have a first-class Node.js SDK. | ||
|
|
||
| ## Step 1: Declare Provider Kind | ||
|
|
||
| Add the new provider to the `ProviderKind` schema in `packages/contracts/src/orchestration.ts`: | ||
|
|
||
| ```typescript | ||
| export const ProviderKind = Schema.Literal( | ||
| "codex", | ||
| "claudeAgent", | ||
| "cursor", | ||
| "opencode", | ||
| "YOUR_PROVIDER", | ||
| ); | ||
| ``` | ||
|
|
||
| ## Step 2: Choose Runtime Path | ||
|
|
||
| ### Path A: Elixir Harness (recommended for CLI-based providers) | ||
|
|
||
| 1. **Create session module**: `apps/harness/lib/harness/providers/your_session.ex` | ||
| - Implement `@behaviour Harness.Providers.ProviderBehaviour` | ||
| - All 8 callbacks: `start_link/1`, `send_turn/2`, `interrupt_turn/3`, `respond_to_approval/3`, `respond_to_user_input/3`, `read_thread/2`, `rollback_thread/3`, `stop/1` | ||
| - Use `GenServer, restart: :temporary` | ||
| - Register via `{:via, Registry, {Harness.SessionRegistry, thread_id, "your_provider"}}` | ||
|
|
||
| 2. **Register in SessionManager**: `apps/harness/lib/harness/session_manager.ex` | ||
| - Add clause to `provider_module/1`: `defp provider_module("your_provider"), do: {:ok, YourSession}` | ||
|
|
||
| 3. **Declare capabilities**: Add entry in `HARNESS_PROVIDER_CAPABILITIES` in `apps/server/src/provider/Layers/HarnessClientAdapter.ts` | ||
|
|
||
| 4. **Register in serverLayers.ts**: Add the provider to the `HARNESS_PROVIDERS` array in `makeServerProviderLayer()` | ||
|
|
||
| ### Path B: Node SDK Adapter (for providers with JS/TS SDKs) | ||
|
|
||
| 1. **Create service tag**: `apps/server/src/provider/Services/YourAdapter.ts` | ||
| - Follow `ClaudeAdapter.ts` pattern | ||
| - Extend `ProviderAdapterShape<ProviderAdapterError>` | ||
|
|
||
| 2. **Create layer**: `apps/server/src/provider/Layers/YourAdapter.ts` | ||
| - Implement all methods of `ProviderAdapterShape` | ||
| - Include `translateMcpConfig` (return null if provider manages its own MCP) | ||
|
|
||
| 3. **Register in adapter registry**: Update `ProviderAdapterRegistryLive` or `makeServerProviderLayer()` | ||
|
|
||
| ## Step 3: Implement ProviderAdapterShape Methods | ||
|
|
||
| Every adapter must implement these methods (see `apps/server/src/provider/Services/ProviderAdapter.ts`): | ||
|
|
||
| | Method | Description | | ||
| | -------------------- | ---------------------------------------------- | | ||
| | `startSession` | Start a provider-backed session | | ||
| | `sendTurn` | Send a conversational turn | | ||
| | `interruptTurn` | Interrupt an active turn | | ||
| | `respondToRequest` | Respond to approval requests | | ||
| | `respondToUserInput` | Respond to user input requests | | ||
| | `stopSession` | Stop one session | | ||
| | `listSessions` | List active sessions | | ||
| | `hasSession` | Check session ownership | | ||
| | `readThread` | Read thread snapshot | | ||
| | `rollbackThread` | Roll back N turns | | ||
| | `stopAll` | Stop all sessions | | ||
| | `translateMcpConfig` | Translate MCP config to provider-native format | | ||
|
|
||
| ## Step 4: Declare Capabilities | ||
|
|
||
| Set `ProviderAdapterCapabilities` for your provider: | ||
|
|
||
| ```typescript | ||
| { | ||
| sessionModelSwitch: "in-session" | "restart-session" | "unsupported", | ||
| supportsUserInput: boolean, | ||
| supportsRollback: boolean, | ||
| supportsFileChangeApproval: boolean, | ||
| } | ||
| ``` | ||
|
|
||
| The contract test suite (`apps/server/integration/contract.integration.test.ts`) uses these to auto-skip tests for unsupported capabilities. | ||
|
|
||
| ## Step 5: Runtime Event Mapping | ||
|
|
||
| Your adapter must emit `ProviderRuntimeEvent` objects with these core event types: | ||
|
|
||
| - `turn.started` / `turn.completed` -- turn lifecycle | ||
| - `content.delta` -- streaming text output | ||
| - `item.started` / `item.completed` -- tool/file-change items | ||
| - `request.opened` / `request.resolved` -- approval flow | ||
| - `session.status` -- session state changes | ||
|
|
||
| See `packages/contracts/src/providerRuntime.ts` for the full event schema. | ||
|
|
||
| ## Step 6: MCP Configuration | ||
|
|
||
| If your provider supports external MCP servers: | ||
|
|
||
| - Implement `translateMcpConfig()` to convert `ResolvedMcpConfig` to provider-native format | ||
| - The harness path stores `mcp_config` in the session state (see `codex_session.ex`) | ||
|
|
||
| If your provider manages its own MCP (like Claude): | ||
|
|
||
| - Return `null` from `translateMcpConfig()` | ||
|
|
||
| ## Step 7: Settings Integration | ||
|
|
||
| Add provider entry in `packages/contracts/src/settings.ts` server settings schema so users can enable/disable and configure the provider. | ||
|
|
||
| ## Step 8: Testing | ||
|
|
||
| 1. **Unit tests**: Add adapter-level tests in `apps/server/src/provider/Layers/YourAdapter.test.ts` | ||
| 2. **Contract tests**: The contract suite auto-includes all registered providers | ||
| 3. **Integration tests**: Add provider-specific integration scenarios if needed | ||
|
|
||
| ## Step 9: Model Discovery (Optional) | ||
|
|
||
| If your provider supports model listing: | ||
|
|
||
| - Elixir: implement model discovery in the session module or a separate GenServer | ||
| - Node: expose via the adapter shape | ||
|
|
||
| Register in `ProviderRegistry` (`apps/server/src/provider/Services/ProviderRegistry.ts`) for the UI model picker. | ||
|
|
||
| ## Checklist | ||
|
|
||
| - [ ] Provider kind added to `ProviderKind` schema | ||
| - [ ] Session module created (Elixir) or adapter layer created (Node) | ||
| - [ ] `@behaviour ProviderBehaviour` implemented (Elixir path) | ||
| - [ ] Capabilities declared | ||
| - [ ] Runtime event mapping implemented | ||
| - [ ] MCP config translator implemented | ||
| - [ ] Registered in SessionManager (Elixir) or adapter registry (Node) | ||
| - [ ] Settings entry added | ||
| - [ ] Unit tests passing | ||
| - [ ] Contract tests passing (or properly skipping unsupported capabilities) | ||
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -13,6 +13,7 @@ defmodule Harness.Application do | |||||
| {Registry, keys: :unique, name: Harness.SessionRegistry}, | ||||||
| {DynamicSupervisor, name: Harness.SessionSupervisor, strategy: :one_for_one}, | ||||||
| Harness.Storage, | ||||||
| Harness.Metrics, | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 Harness.Metrics placed before critical services under rest_for_one supervisor causes cascading restarts In the supervision tree,
Suggested change
Was this helpful? React with 👍 or 👎 to provide feedback. |
||||||
| Harness.SnapshotServer, | ||||||
| HarnessWeb.Endpoint | ||||||
| ] | ||||||
|
|
||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add language specifier to fenced code block.
The ASCII diagram code block is missing a language specifier, triggering markdownlint MD040. Use
textorplaintextfor compatibility.📝 Proposed fix
📝 Committable suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents