agent-first-http 0.3.2

Persistent HTTP client for AI agents — one request, one JSON line
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# Agent-First HTTP

Persistent HTTP client for AI agents — one request, one JSON line.

Supported platforms: macOS, Linux, Windows.

Modes (single entrypoint):
- `--mode cli` (default)
- `--mode pipe`
- `--mode mcp`
- `--mode curl`

The key contract for agents is protocol determinism: `stdout` is always structured JSON, and failures are always structured `{"code":"error",...}` events with stable `error_code` values. No human-only text parsing, no mixed output channels, no ad-hoc error shapes.

## CLI Mode

The default mode — one request, one JSON response, exit:

```bash
afhttp GET https://api.example.com/users
# {"code":"response","status":200,"body":[...],"trace":{"duration_ms":120,...}}

afhttp POST https://api.example.com/users --body '{"name":"Alice","email":"alice@example.com"}'
# {"code":"response","status":201,"body":{"id":42},...}

afhttp GET https://api.example.com/data --header "Authorization: Bearer sk-xxx"
# {"code":"response","status":200,...}
```

Structured error output examples:

```json
{"code":"error","error_code":"connect_timeout","error":"request timed out after 30s","retryable":true,"trace":{"duration_ms":30012}}
```

```json
{"code":"error","error_code":"invalid_request","error":"invalid --output format 'xml': expected json, yaml, or plain","retryable":false,"trace":{"duration_ms":0}}
```

## Pipe Mode

For long-lived sessions with connection reuse, concurrent requests, and WebSocket — use `afhttp --mode pipe`:

```bash
afhttp --mode pipe <<'EOF'
{"code":"config","host_defaults":{"api.example.com":{"headers":{"x-api-key":"sk-xxx","api-version":"2023-06-01"}}}}
{"code":"request","id":"models","method":"GET","url":"https://api.example.com/v1/models"}
{"code":"request","id":"usage","method":"GET","url":"https://api.example.com/v1/usage"}
{"code":"request","id":"chat","method":"POST","url":"https://api.example.com/v1/messages","body":{"model":"general-chat-model","max_tokens":256,"messages":[{"role":"user","content":"Hello"}],"stream":true},"options":{"chunked":true,"chunked_delimiter":"\n\n"}}
EOF
```

**output:**
```json
{"code":"config","host_defaults":{"api.example.com":{"headers":{"x-api-key":"[redacted]","api-version":"2023-06-01"}}},...}
{"code":"response","id":"models","status":200,"body":{"data":[{"id":"general-chat-model",...}]},"trace":{"duration_ms":92,"http_version":"h2","redirects":0,"remote_addr":"13.32.4.10"}}
{"code":"response","id":"usage","status":403,"body":{"error":{"type":"permission_error","message":"Your API key does not have permission"}},"trace":{"duration_ms":87,"http_version":"h2","redirects":0}}
{"code":"chunk_start","id":"chat","status":200,"headers":{"content-type":"text/event-stream"}}
{"code":"chunk_data","id":"chat","data":"event: content_block_delta\ndata: {\"delta\":{\"text\":\"Hello\"}}"}
{"code":"chunk_data","id":"chat","data":"event: content_block_delta\ndata: {\"delta\":{\"text\":\" there\"}}"}
{"code":"chunk_data","id":"chat","data":"event: message_stop\ndata: {}"}
{"code":"chunk_end","id":"chat","trace":{"duration_ms":834,"chunks":8}}
```

What just happened:

- **One bash call** — the heredoc sends all requests into one `afhttp` process; afhttp exits when stdin closes
- **Auth set once per host** — `host_defaults` applies auth only to matching host; credentials do not leak to other domains
- **Three requests fired without waiting** — `models`, `usage`, and `chat` all in-flight simultaneously
- **Connection reuse is automatic** — requests to the same host can reuse pooled connections without extra agent logic
- **Out-of-order responses** — `usage` arrived before `chat` finished; the agent matches by `id`
- **Streaming inline** — `chat` delivers events as they arrive, no buffering, no special setup
- **HTTP errors are data** — `usage` returned 403; afhttp delivers it as `code: "response"` with `status: 403`; the agent checks `status`, not exception types or text patterns

## MCP Mode

`afhttp --mode mcp` runs as a [Model Context Protocol](https://modelcontextprotocol.io) server, letting AI tools like Claude Desktop make HTTP requests directly:

```json
{
  "mcpServers": {
    "afhttp": { "command": "afhttp", "args": ["--mode", "mcp"] }
  }
}
```

Claude can then call `http_request` and `http_config` tools. See [docs/mcp.md](docs/mcp.md) for the full setup guide.

## curl Compatibility

Use explicit curl mode. afhttp understands a subset of curl flags and returns structured JSON:

```bash
afhttp --mode curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer sk-xxx" \
  -d '{"name":"Alice"}'
# {"code":"response","status":201,"body":{"id":42},...}
```

## Install

**macOS / Linux — Homebrew**

```bash
brew install cmnspore/tap/afhttp
```

**Windows — Scoop**

```powershell
scoop bucket add cmnspore https://github.com/cmnspore/scoop-bucket
scoop install afhttp
```

**Any platform — Cargo**

```bash
cargo install agent-first-http
```

## Docs

- [CLI Manual](docs/cli.md) — CLI, MCP, and curl compat modes
- [MCP Reference](docs/mcp.md) — MCP tool reference and Claude Desktop setup
- [Protocol Reference](docs/reference.md) — full field specification
- [Testing Strategy](docs/testing.md) — layered tests, coverage gate, regression policy
- [Design](docs/design.md) — architecture and principles

## License

MIT