Add Warp ACP provider design and ops docs

shared/long-term/projects/warp-acp-integration.md

@@ -0,0 +1,200 @@
+# Warp ACP Integration
+
+## Purpose
+
+This document defines the long-term design for routing ACP harnesses through Warp-managed cloud providers. Phase 1 standardizes `opencode`; future phases may extend the same pattern to `gemini cli` and `claude code`.
+
+## Scope
+
+- Control plane: OpenClaw on `mac-5`
+- Execution nodes: `mac-6`, `mac-7`
+- Current phase: `opencode`
+- Future candidates: `gemini cli`, `claude code`
+
+## Core Design Principles
+
+1. **Provider identity and model identity are different things.**
+   - Model names can repeat across providers.
+   - Environment variables and agent ids must therefore encode the **provider**, not just the model.
+2. **Do not rely on `~/.zshrc` for ACP runtime secrets.**
+   - ACP / acpx / harness execution may not inherit interactive shell startup files.
+   - Secrets should be loaded explicitly.
+3. **Secrets and routing rules should be separated.**
+   - Secrets live in `~/.openclaw/.env`.
+   - Routing / alias / model selection live in ACP config, wrapper scripts, and documented policy.
+4. **Wrapper scripts are the stable injection point.**
+   - Wrapper scripts should explicitly load `~/.openclaw/.env`, validate required variables, and then exec the target harness.
+5. **Fallback must be designed up front.**
+   - Cloud provider quota exhaustion and rate limiting are expected operating conditions, not edge cases.
+
+## Secret Storage Standard
+
+Primary local secret file:
+
+- `~/.openclaw/.env`
+
+Recommended format:
+
+```bash
+WARP_INFINI_API_KEY=
+WARP_INFINI_BASE_URL=https://cloud.infini-ai.com/maas/coding/v1
+WARP_CKIMI_API_KEY=
+WARP_CKIMI_BASE_URL=
+```
+
+Notes:
+
+- Use plain `KEY=value` lines.
+- Do not store secrets in `~/.openclaw/openclaw.json`, `~/.acpx/config.json`, or long-term memory files.
+- Restrict file permissions: `chmod 600 ~/.openclaw/.env`.
+
+## Environment Variable Naming Rule
+
+Use the pattern:
+
+- `WARP_<PROVIDER>_API_KEY`
+- `WARP_<PROVIDER>_BASE_URL`
+
+Examples:
+
+- `WARP_INFINI_API_KEY`
+- `WARP_INFINI_BASE_URL`
+- `WARP_CKIMI_API_KEY`
+- `WARP_CKIMI_BASE_URL`
+
+Do **not** name variables by model alone, because identical model names may exist on multiple providers.
+
+## Agent Naming Standard
+
+For Warp-backed ACP harnesses, use:
+
+- `<harness>-warp-<provider>-<model-family>`
+
+Phase 1 examples for `opencode`:
+
+- `opencode-warp-infini-kimi`
+- `opencode-warp-infini-minimax`
+- `opencode-warp-infini-glm`
+
+Future examples:
+
+- `gemini-warp-infini-kimi`
+- `claude-warp-ckimi-kimi`
+
+## Configuration Layer Responsibilities
+
+### OpenClaw
+
+Responsible for:
+
+- Allowing ACP agent ids to be called
+- High-level routing policy
+
+Key file:
+
+- `~/.openclaw/openclaw.json`
+
+### acpx
+
+Responsible for:
+
+- Mapping ACP `agentId` to a concrete command
+
+Key file:
+
+- `~/.acpx/config.json`
+
+### Wrapper scripts
+
+Responsible for:
+
+- Loading `~/.openclaw/.env`
+- Validating provider secrets / URLs
+- Fixing provider and model selection
+- Launching the harness ACP command
+
+Suggested location:
+
+- `~/.local/bin/`
+
+### Harness config (`opencode` in phase 1)
+
+Responsible for:
+
+- Harness-specific provider usage and model invocation details
+
+Key file:
+
+- `~/.config/opencode/opencode.json`
+
+## Wrapper Contract
+
+Every Warp-backed ACP wrapper should:
+
+1. Load `~/.openclaw/.env`
+2. Validate that required variables exist
+3. Select the target provider
+4. Pin the intended model
+5. Launch the harness ACP entrypoint
+6. Fail fast with a readable error if env/config is missing
+
+Pseudo-flow:
+
+```bash
+set -a
+source ~/.openclaw/.env
+set +a
+
+# validate WARP_<PROVIDER>_API_KEY and WARP_<PROVIDER>_BASE_URL
+# select model
+exec opencode-ai acp
+```
+
+## Fallback Policy
+
+### Why fallback exists
+
+Warp-backed cloud providers may fail due to:
+
+- 5-hour quota exhaustion
+- weekly quota exhaustion
+- rate limiting / throttling
+- transient upstream 5xx
+- model retirement or temporary unavailability
+- provider auth / billing issues
+
+These are normal operational conditions and must be documented as first-class routing rules.
+
+### Fallback priority
+
+When a primary provider/model is unavailable, use this order:
+
+1. **Same model, different provider**
+2. **Same provider, adjacent model**
+3. **Different provider, adjacent model**
+
+This preserves behavior consistency as much as possible before changing model family.
+
+### Example fallback chain
+
+For `opencode-warp-infini-kimi`:
+
+1. primary: `infini / kimi-k2.5`
+2. fallback-1: another provider offering `kimi-k2.5` (for example `ckimi / kimi-k2.5`)
+3. fallback-2: `infini / glm-5`
+4. fallback-3: `infini / minimax-m2.5`
+
+Exact fallback order should be documented per agent as providers are added.
+
+## Operational Reminder
+
+If runtime errors show quota exhaustion or provider-specific capacity limits during an ACP task, the operator should treat that as a routing event, not just a task failure. The next step is to move to the documented fallback provider/model path.
+
+## Extension Path
+
+After `opencode` stabilizes, the same naming / secret-loading / fallback framework should be reused for:
+
+- `gemini cli`
+- `claude code`
+
+The framework should stay provider-centric and wrapper-based even as the harnesses differ.