II.
Page overview
Reference · livepage:docs-agent-mux-archive-superpowers-plans-2026-04-19-provider-mux-tech-debt
Provider Mux & Launcher — Remaining Work overview
Inspect the raw attributes, linked wiki pages, and inbound or outbound graph edges for page:docs-agent-mux-archive-superpowers-plans-2026-04-19-provider-mux-tech-debt.
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
# Provider Mux & Launcher — Remaining Work
49 open items ordered by dependency. Items earlier in the list unblock items later.
---
## Tier 0: Cleanup & Fixes (no dependencies, unblocks everything)
These are quick fixes that remove confusion and unblock correct work downstream.
| # | Task | Files | Depends on |
|---|---|---|---|
| 1 | Remove dead `OllamaManager` class and its tests — `OllamaServerManager` is the real implementation | `providers/ollama_mgr.py`, `tests/test_ollama_mgr.py` | — |
| 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` | — |
| 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` | — |
| 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` | — |
| 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` | — |
| 6 | Delete or populate empty `tests/conftest.py` (contains only `import pytest`) | `packages/amux-proxy/tests/conftest.py` | — |
| 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` | — |
| 8 | Fix `ollama list` string matching — parse line-by-line and check first column instead of `includes()` | `packages/cli/src/commands/launch.ts` | — |
| 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` | — |
| 10 | Add `--resume` validation — check `adapter.capabilities.canResume`, error for unsupported harnesses | `packages/cli/src/commands/launch.ts` | — |
| 11 | Migrate FastAPI `@app.on_event("startup"/"shutdown")` to `lifespan` context manager (deprecated API) | `packages/amux-proxy/src/amux_proxy/server.py` | — |
---
## Tier 1: Core Infrastructure (unblocks most feature work)
| # | Task | Files | Depends on |
|---|---|---|---|
| 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` | — |
| 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 | — |
| 14 | Add `--provider-arg key=value` repeatable CLI flag — flows arbitrary key-value pairs into `ProviderConfig.params` | `packages/cli/src/commands/launch.ts` | 13 |
| 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 |
| 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` | — |
| 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` | — |
| 18 | PTY allocation for interactive mode — use `node-pty` for TUI harnesses (Claude, Codex, Gemini) | `packages/cli/src/commands/launch.ts` | — |
| 19 | JSON schema file for `providers.json` — create schema, reference from spec | `packages/core/schemas/amux-providers.schema.json`, `docs/amux-provider-config.md` | — |
---
## Tier 2: Transport Endpoints (unblocks cloud-provider fidelity)
| # | Task | Files | Depends on |
|---|---|---|---|
| 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` | — |
| 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` | — |
| 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` | — |
| 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` | — |
| 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 |
---
## Tier 3: Provider Coverage (unblocks broader model access)
| # | Task | Files | Depends on |
|---|---|---|---|
| 25 | LM Studio as first-class local provider — `'lmstudio'`, `apiBase: 'http://localhost:1234'`, OpenAI-compatible | `packages/core/src/provider-config.ts` | 15 |
| 26 | vLLM as first-class local provider — `'vllm'`, configurable endpoint, OpenAI-compatible | `packages/core/src/provider-config.ts` | 15 |
| 27 | Additional cloud providers — `nvidia-nim`, `databricks`, `cloudflare`, `replicate`, `anyscale`, `huggingface`, `perplexity`, `cohere` with proper defaults | `packages/core/src/provider-config.ts` | 15 |
---
## Tier 4: Harness Translation Completeness (unblocks full harness coverage)
| # | Task | Files | Depends on |
|---|---|---|---|
| 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` | — |
| 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` | — |
| 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` | — |
| 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` | — |
| 32 | Translators for remaining harnesses: Copilot, Cursor, Pi, OMP, OpenClaw, Hermes, Droid, Amp, Qwen — detect native provider support where possible | `packages/adapters/src/translations/` | — |
---
## Tier 5: Launch Orchestration (unblocks full original request flow)
| # | Task | Files | Depends on |
|---|---|---|---|
| 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 |
| 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 |
| 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 |
---
## Tier 6: Test Coverage (unblocks confidence for all above)
| # | Task | Files | Depends on |
|---|---|---|---|
| 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 |
| 37 | Python CLI tests — missing args validation, config construction, `--version` | `packages/amux-proxy/tests/test_cli.py` | 12 |
| 38 | Python server tests — transport router mounting, `/v1/count_tokens`, `/v1/models`, Ollama lifecycle hooks | `packages/amux-proxy/tests/test_server.py` | 12 |
| 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 |
| 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 |
---
## Tier 7: CI/CD & Packaging (unblocks distribution)
| # | Task | Files | Depends on |
|---|---|---|---|
| 41 | PyPI trusted publisher — configure PyPI project with GitHub repo as trusted publisher | PyPI admin, `.github/workflows/amux-proxy-publish.yml` | 12 |
| 42 | GHCR Docker registry — create repo, configure `packages: write` permission | GitHub repo settings | — |
| 43 | amux-proxy version sync — strategy for coordinating Python version with TS changesets (manual tag? script?) | `packages/amux-proxy/pyproject.toml`, `__init__.py` | — |
---
## Tier 8: Docs (can run anytime)
| # | Task | Files | Depends on |
|---|---|---|---|
| 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 |
| 45 | Update `docs/amux-provider-config.md` §8.2 bearer token wording | `docs/amux-provider-config.md` | 5 |
| 46 | Create JSON schema file for providers.json | `packages/core/schemas/` or `docs/schemas/` | 19 |
---
## Tier 9: Future Enhancements (nice-to-have, no blockers)
| # | Task | Files | Depends on |
|---|---|---|---|
| 47 | Response caching — `AMUX_PROXY_CACHE=true` with SQLite/file cache for repeated dev prompts | `packages/amux-proxy/` | — |
| 48 | Cost tracking — aggregate LiteLLM cost data, expose via `/metrics` | `packages/amux-proxy/` | — |
| 49 | `--observe` mode — tee harness output to stdout (raw) + internal parser (cost/session tracking) without transforming output | `packages/cli/src/commands/launch.ts` | — |
---
## Summary
| Tier | Description | Count |
|---|---|---|
| 0 | Cleanup & fixes | 11 |
| 1 | Core infrastructure | 8 |
| 2 | Cloud transport endpoints | 5 |
| 3 | Provider coverage | 3 |
| 4 | Harness translation completeness | 5 |
| 5 | Launch orchestration | 3 |
| 6 | Test coverage | 5 |
| 7 | CI/CD & packaging | 3 |
| 8 | Docs | 3 |
| 9 | Future | 3 |
| **Total** | | **49** |
**Dependency highlights:**
- Tier 0 is all independent — can parallelize freely
- #13 (rich params) unblocks #14 (CLI args), #15 (dynamic providers), #35 (Router)
- #12 (CI env fix) unblocks all Python test work (#36-39, #41)
- #15 (dynamic detection) unblocks #25-27 (new providers)
- Transport endpoints (#20-23) are independent of each other
- Harness translators (#28-32) are independent of each other
- #33 (Ollama e2e) depends on #1 (dead code cleanup) and #8 (string matching fix)
documents
[]
Outgoing edges
None.
Incoming edges
contains_page1
- page:docs-agent-mux-archive-superpowers·Pageagent-mux archive: superpowers