feat: acp http adapter

docs/credentials.mdx

@@ -1,55 +1,115 @@
 ---
 title: "Credentials"
-description: "How sandbox-agent discovers and exposes provider credentials."
-icon: "key"
+description: "How Sandbox Agent discovers and uses provider credentials."
 ---
 
-`sandbox-agent` can discover provider credentials from environment variables and local agent config files.
+Sandbox Agent discovers API credentials from environment variables and local agent config files.
+These credentials are passed through to underlying agent runtimes.
 
-## Supported providers
+## Credential sources
 
-- Anthropic
-- OpenAI
-- Additional provider entries discovered via OpenCode config
+Credentials are discovered in priority order.
 
-## Common environment variables
+### Environment variables (highest priority)
+
+API keys first:
 
 | Variable | Provider |
-| --- | --- |
+|----------|----------|
 | `ANTHROPIC_API_KEY` | Anthropic |
 | `CLAUDE_API_KEY` | Anthropic fallback |
 | `OPENAI_API_KEY` | OpenAI |
 | `CODEX_API_KEY` | OpenAI fallback |
 
-## Extract credentials (CLI)
+OAuth tokens (used when OAuth extraction is enabled):
 
-Show discovered credentials (redacted by default):
+| Variable | Provider |
+|----------|----------|
+| `CLAUDE_CODE_OAUTH_TOKEN` | Anthropic |
+| `ANTHROPIC_AUTH_TOKEN` | Anthropic fallback |
 
-```bash
-sandbox-agent credentials extract
+### Agent config files
+
+| Agent | Config path | Provider |
+|-------|-------------|----------|
+| Amp | `~/.amp/config.json` | Anthropic |
+| Claude Code | `~/.claude.json`, `~/.claude/.credentials.json` | Anthropic |
+| Codex | `~/.codex/auth.json` | OpenAI |
+| OpenCode | `~/.local/share/opencode/auth.json` | Anthropic/OpenAI |
+
+## Provider requirements by agent
+
+| Agent | Required provider |
+|-------|-------------------|
+| Claude Code | Anthropic |
+| Amp | Anthropic |
+| Codex | OpenAI |
+| OpenCode | Anthropic or OpenAI |
+| Mock | None |
+
+## Error handling behavior
+
+Credential extraction is best-effort:
+
+- Missing or malformed files are skipped.
+- Discovery continues to later sources.
+- Missing credentials mark providers unavailable instead of failing server startup.
+
+When prompting, Sandbox Agent does not pre-validate provider credentials. Agent-native authentication errors surface through session events/output.
+
+## Checking credential status
+
+### API
+
+`GET /v1/agents` includes `credentialsAvailable` per agent.
+
+```json
+{
+  "agents": [
+    {
+      "id": "claude",
+      "installed": true,
+      "credentialsAvailable": true
+    },
+    {
+      "id": "codex",
+      "installed": true,
+      "credentialsAvailable": false
+    }
+  ]
+}
 ```
 
-Reveal raw values:
+### TypeScript SDK
 
-```bash
-sandbox-agent credentials extract --reveal
+```typescript
+const result = await sdk.listAgents();
+
+for (const agent of result.agents) {
+  console.log(`${agent.id}: ${agent.credentialsAvailable ? "authenticated" : "no credentials"}`);
+}
 ```
 
-Filter by agent/provider:
+## Passing credentials explicitly
+
+Set environment variables before starting Sandbox Agent:
 
 ```bash
-sandbox-agent credentials extract --agent codex
-sandbox-agent credentials extract --provider openai
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENAI_API_KEY=sk-...
+sandbox-agent daemon start
 ```
 
-Emit shell exports:
+Or with SDK-managed local spawn:
 
-```bash
-sandbox-agent credentials extract-env --export
+```typescript
+import { SandboxAgent } from "sandbox-agent";
+
+const sdk = await SandboxAgent.start({
+  spawn: {
+    env: {
+      ANTHROPIC_API_KEY: process.env.MY_ANTHROPIC_KEY,
+    },
+  },
+});
 ```
-
-## Notes
-
-- Discovery is best-effort: missing/invalid files do not crash extraction.
-- v2 does not expose legacy v1 `credentialsAvailable` agent fields.
-- Authentication failures are surfaced by the selected ACP agent process/agent during ACP requests.