{
  "id": "page:docs-agent-mux-archive-superpowers-plans-2026-04-19-provider-mux-tech-debt",
  "_kind": "Page",
  "_file": "wiki/docs/agent-mux/archive/superpowers/plans/2026-04-19-provider-mux-tech-debt.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/agent-mux/archive/superpowers/plans/2026-04-19-provider-mux-tech-debt.md",
    "sourceKind": "repo-docs",
    "title": "Provider Mux & Launcher — Remaining Work",
    "displayName": "Provider Mux & Launcher — Remaining Work",
    "slug": "docs/agent-mux/archive/superpowers/plans/2026-04-19-provider-mux-tech-debt",
    "articlePath": "wiki/docs/agent-mux/archive/superpowers/plans/2026-04-19-provider-mux-tech-debt.md",
    "article": "\n# Provider Mux & Launcher — Remaining Work\n\n49 open items ordered by dependency. Items earlier in the list unblock items later.\n\n---\n\n## Tier 0: Cleanup & Fixes (no dependencies, unblocks everything)\n\nThese are quick fixes that remove confusion and unblock correct work downstream.\n\n| # | Task | Files | Depends on |\n|---|---|---|---|\n| 1 | Remove dead `OllamaManager` class and its tests — `OllamaServerManager` is the real implementation | `providers/ollama_mgr.py`, `tests/test_ollama_mgr.py` | — |\n| 2 | Remove stale re-exports in `launch.ts` (`isNativelySupported`, `getRequiredProxyTransport` imported but only re-exported, never used in resolution) | `packages/cli/src/commands/launch.ts:22-24` | — |\n| 3 | Remove `a2a` from `TransportId` type and config validator (no implementation, misleads users) | `packages/core/src/provider-config.ts`, `packages/amux-proxy/src/amux_proxy/config.py` | — |\n| 4 | Update spec: `docs/provider-mux.md` §2 lists `translate.py` and `health.py` as separate files — they're inline in transport endpoints and `server.py`. Update spec to match | `docs/provider-mux.md` | — |\n| 5 | Update spec: `docs/amux-provider-config.md` §8.2 says \"single-use bearer token\" — it's session-scoped. Fix wording | `docs/amux-provider-config.md` | — |\n| 6 | Delete or populate empty `tests/conftest.py` (contains only `import pytest`) | `packages/amux-proxy/tests/conftest.py` | — |\n| 7 | Fix `/v1/count_tokens` to return HTTP 400/500 on error instead of `{\"count\": -1, \"error\": \"...\"}` with 200 | `packages/amux-proxy/src/amux_proxy/server.py` | — |\n| 8 | Fix `ollama list` string matching — parse line-by-line and check first column instead of `includes()` | `packages/cli/src/commands/launch.ts` | — |\n| 9 | Fix default `proxyMode` — should be `'never'` when no `--with-proxy*` flag is given, with clear error when proxy is needed | `packages/cli/src/commands/launch.ts` | — |\n| 10 | Add `--resume` validation — check `adapter.capabilities.canResume`, error for unsupported harnesses | `packages/cli/src/commands/launch.ts` | — |\n| 11 | Migrate FastAPI `@app.on_event(\"startup\"/\"shutdown\")` to `lifespan` context manager (deprecated API) | `packages/amux-proxy/src/amux_proxy/server.py` | — |\n\n---\n\n## Tier 1: Core Infrastructure (unblocks most feature work)\n\n| # | Task | Files | Depends on |\n|---|---|---|---|\n| 12 | Fix Python env: CI workflow must use isolated venv (`python -m venv` or `uv`) to avoid pydantic v1/v2 conflict | `.github/workflows/amux-proxy-ci.yml` | — |\n| 13 | `ProviderConfig.params` → `Record<string, unknown>` — support rich LiteLLM config (RPM/TPM, custom headers, retry policies, `aws_bedrock_runtime_endpoint`, `vertex_credentials`) | `packages/core/src/provider-config.ts`, `provider-resolver.ts`, all translators | — |\n| 14 | Add `--provider-arg key=value` repeatable CLI flag — flows arbitrary key-value pairs into `ProviderConfig.params` | `packages/cli/src/commands/launch.ts` | 13 |\n| 15 | Dynamic provider detection — pass `provider/model` string to LiteLLM directly via `custom` provider instead of maintaining static `ProviderId` union. Keep named providers for defaults but let unknown prefixes pass through | `packages/core/src/provider-config.ts`, `provider-resolver.ts` | 13 |\n| 16 | Transport-level redundancy detection — if harness's native transport matches provider's API format, skip proxy even when provider isn't in the native support matrix | `packages/core/src/provider-support-matrix.ts`, `packages/cli/src/commands/launch.ts` | — |\n| 17 | Proxy installation pre-check — `--with-proxy-if-needed` should verify `amux-proxy` is installed before attempting spawn, with `pip install amux-proxy` guidance | `packages/cli/src/commands/launch.ts` | — |\n| 18 | PTY allocation for interactive mode — use `node-pty` for TUI harnesses (Claude, Codex, Gemini) | `packages/cli/src/commands/launch.ts` | — |\n| 19 | JSON schema file for `providers.json` — create schema, reference from spec | `packages/core/schemas/amux-providers.schema.json`, `docs/amux-provider-config.md` | — |\n\n---\n\n## Tier 2: Transport Endpoints (unblocks cloud-provider fidelity)\n\n| # | Task | Files | Depends on |\n|---|---|---|---|\n| 20 | Passthrough transport — forward requests in provider's native format (no translation). Add `passthrough` to `TransportId`. URL pattern: `PROXY/anthropic/v1/messages` → `api.anthropic.com/v1/messages` | `packages/amux-proxy/src/amux_proxy/transports/passthrough.py`, `packages/core/src/provider-config.ts` | — |\n| 21 | Bedrock Converse native endpoint — `POST /converse` mapping to Bedrock's Converse API. Avoids double-translation. Supports guardrails, document blocks | `packages/amux-proxy/src/amux_proxy/transports/bedrock_converse.py` | — |\n| 22 | Vertex AI native endpoint — Vertex-specific `generateContent` with grounding, safety settings, cached content. Differs from public Gemini format for Claude-on-Vertex | `packages/amux-proxy/src/amux_proxy/transports/vertex_native.py` | — |\n| 23 | Azure AI Foundry endpoint — distinct from Azure OpenAI. Foundry-specific features via LiteLLM `azure_ai` provider | `packages/amux-proxy/src/amux_proxy/transports/azure_foundry.py` | — |\n| 24 | Add `passthrough`, `bedrock-converse`, `vertex-native`, `azure-foundry` to `--transport` CLI option and `TransportId` type | `packages/core/src/provider-config.ts`, `packages/cli/src/commands/launch.ts` | 20, 21, 22, 23 |\n\n---\n\n## Tier 3: Provider Coverage (unblocks broader model access)\n\n| # | Task | Files | Depends on |\n|---|---|---|---|\n| 25 | LM Studio as first-class local provider — `'lmstudio'`, `apiBase: 'http://localhost:1234'`, OpenAI-compatible | `packages/core/src/provider-config.ts` | 15 |\n| 26 | vLLM as first-class local provider — `'vllm'`, configurable endpoint, OpenAI-compatible | `packages/core/src/provider-config.ts` | 15 |\n| 27 | Additional cloud providers — `nvidia-nim`, `databricks`, `cloudflare`, `replicate`, `anyscale`, `huggingface`, `perplexity`, `cohere` with proper defaults | `packages/core/src/provider-config.ts` | 15 |\n\n---\n\n## Tier 4: Harness Translation Completeness (unblocks full harness coverage)\n\n| # | Task | Files | Depends on |\n|---|---|---|---|\n| 28 | Claude translator: add `CLAUDE_CODE_AUTO_COMPACT_WINDOW` for Ollama context window config (from `ollama/cmd/launch/claude.go`) | `packages/adapters/src/translations/claude-translation.ts` | — |\n| 29 | Codex translator: add version check (minimum v0.81.0) and `config.toml` profile generation (from `ollama/cmd/launch/codex.go`) | `packages/adapters/src/translations/codex-translation.ts` | — |\n| 30 | OpenCode translator: merge generated config with existing `opencode.json` (preserve agents, tools, permissions); add state management for `~/.local/state/opencode/model.json` (from `ollama/cmd/launch/opencode.go`) | `packages/adapters/src/translations/opencode-translation.ts` | — |\n| 31 | OpenCode prompt injection — `appendHarnessSessionArgs()` has no OpenCode path for `-p` prompt delivery. Research OpenCode's non-interactive API | `packages/cli/src/commands/launch.ts` | — |\n| 32 | Translators for remaining harnesses: Copilot, Cursor, Pi, OMP, OpenClaw, Hermes, Droid, Amp, Qwen — detect native provider support where possible | `packages/adapters/src/translations/` | — |\n\n---\n\n## Tier 5: Launch Orchestration (unblocks full original request flow)\n\n| # | Task | Files | Depends on |\n|---|---|---|---|\n| 33 | End-to-end Ollama lifecycle — `amux launch claude ollama --model qwen3:32b` should: check Ollama running → start if needed → check model pulled → pull if needed → launch proxy → launch harness. Wire `OllamaManager` (model pull) into the flow alongside `OllamaServerManager` (server lifecycle) | `packages/cli/src/commands/launch.ts`, `packages/amux-proxy/` | 1, 8 |\n| 34 | Full auth validation — STS check for Bedrock, ADC check for Vertex, key format validation. Error before spawning instead of letting harness fail | `packages/cli/src/commands/launch.ts` | 14 |\n| 35 | LiteLLM Router for multi-deployment fallback — support `AMUX_PROXY_ROUTER_CONFIG` env var for `litellm.Router` with fallback chains (primary Bedrock → fallback Anthropic) | `packages/amux-proxy/src/amux_proxy/server.py` | 13 |\n\n---\n\n## Tier 6: Test Coverage (unblocks confidence for all above)\n\n| # | Task | Files | Depends on |\n|---|---|---|---|\n| 36 | Python transport endpoint tests — unit tests for all 4 transports (Anthropic, OpenAI Chat, OpenAI Responses, Google): request parsing, response formatting, streaming, error handling | `packages/amux-proxy/tests/test_anthropic_transport.py`, `test_openai_chat.py`, `test_openai_responses.py`, `test_google.py` | 12 |\n| 37 | Python CLI tests — missing args validation, config construction, `--version` | `packages/amux-proxy/tests/test_cli.py` | 12 |\n| 38 | Python server tests — transport router mounting, `/v1/count_tokens`, `/v1/models`, Ollama lifecycle hooks | `packages/amux-proxy/tests/test_server.py` | 12 |\n| 39 | Integration tests with real LiteLLM — at least one test calling a real provider (Ollama local or Groq with test key) | `packages/amux-proxy/tests/test_integration.py` | 12, 36 |\n| 40 | TypeScript launch e2e with mock harness — test full spawn + proxy lifecycle + cleanup + signal forwarding using `harness-mock` | `packages/cli/tests/launch-e2e.test.ts` | 9, 17 |\n\n---\n\n## Tier 7: CI/CD & Packaging (unblocks distribution)\n\n| # | Task | Files | Depends on |\n|---|---|---|---|\n| 41 | PyPI trusted publisher — configure PyPI project with GitHub repo as trusted publisher | PyPI admin, `.github/workflows/amux-proxy-publish.yml` | 12 |\n| 42 | GHCR Docker registry — create repo, configure `packages: write` permission | GitHub repo settings | — |\n| 43 | amux-proxy version sync — strategy for coordinating Python version with TS changesets (manual tag? script?) | `packages/amux-proxy/pyproject.toml`, `__init__.py` | — |\n\n---\n\n## Tier 8: Docs (can run anytime)\n\n| # | Task | Files | Depends on |\n|---|---|---|---|\n| 44 | Update `docs/provider-mux.md` §2 package structure to match reality (no `translate.py`, no `health.py`, add `errors.py`, `providers/ollama_server.py`) | `docs/provider-mux.md` | 4 |\n| 45 | Update `docs/amux-provider-config.md` §8.2 bearer token wording | `docs/amux-provider-config.md` | 5 |\n| 46 | Create JSON schema file for providers.json | `packages/core/schemas/` or `docs/schemas/` | 19 |\n\n---\n\n## Tier 9: Future Enhancements (nice-to-have, no blockers)\n\n| # | Task | Files | Depends on |\n|---|---|---|---|\n| 47 | Response caching — `AMUX_PROXY_CACHE=true` with SQLite/file cache for repeated dev prompts | `packages/amux-proxy/` | — |\n| 48 | Cost tracking — aggregate LiteLLM cost data, expose via `/metrics` | `packages/amux-proxy/` | — |\n| 49 | `--observe` mode — tee harness output to stdout (raw) + internal parser (cost/session tracking) without transforming output | `packages/cli/src/commands/launch.ts` | — |\n\n---\n\n## Summary\n\n| Tier | Description | Count |\n|---|---|---|\n| 0 | Cleanup & fixes | 11 |\n| 1 | Core infrastructure | 8 |\n| 2 | Cloud transport endpoints | 5 |\n| 3 | Provider coverage | 3 |\n| 4 | Harness translation completeness | 5 |\n| 5 | Launch orchestration | 3 |\n| 6 | Test coverage | 5 |\n| 7 | CI/CD & packaging | 3 |\n| 8 | Docs | 3 |\n| 9 | Future | 3 |\n| **Total** | | **49** |\n\n**Dependency highlights:**\n- Tier 0 is all independent — can parallelize freely\n- #13 (rich params) unblocks #14 (CLI args), #15 (dynamic providers), #35 (Router)\n- #12 (CI env fix) unblocks all Python test work (#36-39, #41)\n- #15 (dynamic detection) unblocks #25-27 (new providers)\n- Transport endpoints (#20-23) are independent of each other\n- Harness translators (#28-32) are independent of each other\n- #33 (Ollama e2e) depends on #1 (dead code cleanup) and #8 (string matching fix)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-agent-mux-archive-superpowers",
      "to": "page:docs-agent-mux-archive-superpowers-plans-2026-04-19-provider-mux-tech-debt",
      "kind": "contains_page"
    }
  ]
}