Skip to content

Commit 4ba369d

Browse files
nficanoclaude
nficano
and
claude
committed
docs: align with implementation and trim aspirational APIs
Cross-referenced docs/ against src/ and PublicAPI.Unshipped.txt; fixed references to types, methods, and CLI flags that don't exist in the current build. Rewrote guides where the documented surface diverged from what code provides (auth principal access, session resume, CLI), expanded the Runtime project doc with the full JobContext API, and updated the project graph to reflect the actual src tree. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 44a579f commit 4ba369d

20 files changed

Lines changed: 463 additions & 447 deletions

‎docs/architecture.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,9 @@ Neither peer may use a feature outside the negotiated set.
117117
| `list_jobs` | §6.6 | `session.list_jobs` / `session.jobs`. |
118118
| `subscribe` | §7.6 | Cross-session job observation. |
119119
| `agent_versions` | §7.5 | `name@version` pinning. |
120-
| `progress` | §8.2.1 | `progress` job-event kind. |
121-
| `result_chunk` | §8.4 | Streamed multi-chunk results. |
122-
| `lease_expires_at` | §9.5 | Time-bounded lease constraints. |
123-
| `cost.budget` | §9.6 | Per-currency cost ceilings. |
120+
| `progress` | §8.2.1 | `progress` job-event kind. |
121+
| `result_chunk` | §8.4 | Streamed multi-chunk results. |
122+
| `lease_expires_at` | §9.5 | Time-bounded lease constraints. |
123+
| `cost.budget` | §9.6 | Per-currency cost ceilings. |
124+
| `model.use` | §9.7 | `model.use` lease constraint. |
125+
| `provisioned_credentials`| §9.8 | Runtime-issued short-lived credentials. |

‎docs/cli.md‎

Lines changed: 36 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# CLI
22

33
`Arcp.Cli` ships an `arcp` executable. It is a thin operational tool
4-
for running runtimes, submitting jobs, and inspecting the SDK version.
4+
for running a demo runtime, submitting one-off jobs, and printing the
5+
SDK version.
56

67
## Install
78

@@ -17,28 +18,27 @@ dotnet add package Arcp.Cli
1718

1819
## `arcp serve`
1920

20-
Start a runtime that hosts a single named echo agent over WebSocket or
21-
stdio. Most production deployments embed `ArcpServer` programmatically;
22-
`serve` is for ad-hoc testing and reproductions.
21+
Start a runtime that hosts a single `echo` agent over WebSocket. Most
22+
production deployments embed `ArcpServer` programmatically; `serve` is
23+
for ad-hoc testing and reproductions.
2324

2425
```sh
2526
arcp serve \
2627
--host 127.0.0.1 \
2728
--port 7777 \
28-
--token tok \
29-
--principal me@example.com
29+
--token tok
3030
```
3131

3232
Flags:
3333

34-
| Flag | Default | Notes |
35-
| --------------------------- | ----------- | ----- |
36-
| `--transport <ws\|stdio>` | `ws` | `stdio` makes this a subprocess runtime. |
37-
| `--host <host>` | `127.0.0.1` | Bind address for WebSocket. |
38-
| `--port <port>` | `7777` | Bind port for WebSocket. |
39-
| `--path <path>` | `/arcp` | URL path for the WebSocket upgrade. |
40-
| `--token <token>` | — | Required. Static bearer accepted by the verifier. |
41-
| `--principal <id>` | — | Principal returned when the token verifies. |
34+
| Flag | Default | Notes |
35+
| ----------------- | ----------- | ----- |
36+
| `--host <host>` | `127.0.0.1` | Bind address for WebSocket. |
37+
| `--port <port>` | `7777` | Bind port for WebSocket. |
38+
| `--token <token>` | `tok-demo` | Static bearer accepted by the verifier. |
39+
40+
The runtime accepts WebSocket upgrades at the path `/arcp` and exposes
41+
`/healthz` for liveness probes.
4242

4343
## `arcp submit`
4444

@@ -49,66 +49,41 @@ and CI.
4949
arcp submit \
5050
--url ws://127.0.0.1:7777/arcp \
5151
--token tok \
52-
--agent my-agent \
53-
--input '{"hi":1}' \
54-
--idempotency-key run-2026-W19
52+
--agent echo \
53+
--input '{"hi":1}'
5554
```
5655

5756
Flags:
5857

59-
| Flag | Notes |
60-
| ------------------------- | ----- |
61-
| `--url <ws-url>` | Runtime URL. |
62-
| `--token <token>` | Bearer token. |
63-
| `--agent <name[@ver]>` | Registered agent name, optionally pinned to a version. |
64-
| `--input <json>` | Inline JSON payload. |
65-
| `--input-file <path>` | Read payload from a file (mutually exclusive with `--input`). |
66-
| `--idempotency-key <key>` | Optional deduplication key (spec §7.2). |
67-
| `--max-runtime-sec <n>` | Hard wall-clock timeout for the job. |
68-
| `--lease <json>` | Lease object as JSON (spec §9). |
69-
| `--trace-id <hex>` | 32-hex W3C trace ID to propagate. |
70-
71-
Stdout receives the final `job.result` payload as JSON. Events are
72-
streamed to stderr in human-readable form (`[seq] kind message`).
58+
| Flag | Default | Notes |
59+
| ----------------- | -------------------------- | ----- |
60+
| `--url <ws-url>` | `ws://127.0.0.1:7777/arcp` | Runtime URL. |
61+
| `--token <token>` | `tok-demo` | Bearer token. |
62+
| `--agent <name>` | `echo` | Registered agent name. |
63+
| `--input <json>` | `{}` | Inline JSON payload. |
64+
65+
Stdout receives `connected:` and `accepted:` status lines plus the
66+
final `result: status=...` line.
7367

7468
## `arcp version`
7569

76-
Print the SDK and wire-format versions:
70+
Print the protocol version:
7771

7872
```sh
7973
arcp version
80-
# Arcp.Cli 1.0.0 (wire 1.1)
74+
# arcp 1.1
8175
```
8276

8377
## Exit codes
8478

8579
| Code | Meaning |
8680
| ---- | ------- |
87-
| `0` | Job completed with `final_status: "success"`. |
88-
| `1` | Runtime/server error (auth failure, bind failure, unknown agent). |
89-
| `2` | Job terminated with `error`, `cancelled`, or `timed_out`. |
90-
| `64` | Bad CLI arguments. |
91-
92-
## stdio mode
93-
94-
`--transport stdio` makes `arcp serve` read envelopes from stdin and
95-
write them to stdout, turning the process into a child-agent runtime.
96-
The parent is the ARCP client. Pipe agent logs to stderr or silence
97-
them — any non-envelope byte on stdout corrupts the channel.
98-
99-
```csharp
100-
// Parent process in C#:
101-
using var proc = Process.Start(new ProcessStartInfo
102-
{
103-
FileName = "arcp",
104-
Arguments = "serve --transport stdio --token tok --principal me",
105-
RedirectStandardInput = true,
106-
RedirectStandardOutput = true,
107-
UseShellExecute = false,
108-
});
109-
var transport = new StdioTransport(
110-
proc!.StandardOutput.BaseStream,
111-
proc.StandardInput.BaseStream);
112-
```
113-
114-
See [Transports — stdio](./transports.md#stdio) for the full pattern.
81+
| `0` | Command succeeded (`submit` requires `final_status: "success"`). |
82+
| `1` | Submit terminated with a non-success status. |
83+
| `2` | Unknown subcommand. |
84+
85+
For richer flags (idempotency keys, stdio transport, lease constraints,
86+
trace IDs, file-based input), drive `ArcpClient` directly from a small
87+
host program — the CLI is intentionally minimal. See
88+
[Recipes](./recipes.md) and the [samples](../samples/) for end-to-end
89+
examples.

‎docs/diagrams/arcp-projects-dark.dot‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ digraph ArcpProjects {
4343
AspNetCore [label="Arcp.AspNetCore"];
4444
Otel [label="Arcp.Otel"];
4545
Hosting [label="Arcp.Hosting"];
46+
Cli [label="Arcp.Cli"];
4647
}
4748

4849
subgraph cluster_samples {
@@ -52,7 +53,7 @@ digraph ArcpProjects {
5253
fontname="TT Commons Pro Trial"; fontcolor="#94A3B8";
5354
margin=14; labeljust=l; penwidth=1.0;
5455

55-
Samples [label="20 samples", shape=box];
56+
Samples [label="21 samples", shape=box];
5657
}
5758

5859
subgraph cluster_tests {
@@ -76,6 +77,9 @@ digraph ArcpProjects {
7677
AspNetCore -> Core;
7778
Otel -> Core;
7879
Hosting -> Runtime;
80+
Hosting -> Core;
81+
Cli -> Arcp;
82+
Cli -> AspNetCore;
7983

8084
Samples -> Client;
8185
Samples -> Runtime;

0 commit comments

Comments
 (0)