feat: complete ARCP v1.1 PHP support

Author: nficano

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- ARCP v1.1 feature coverage for `session.list_jobs` / `session.jobs`,
+  versioned `name@version` tool resolution, `job.result_chunk`, and
+  `cost.budget` enforcement.
+- `Arcp\Errors\BudgetExhaustedException` and
+  `Arcp\Errors\AgentVersionNotAvailableException` mapped to their v1.1
+  canonical wire codes.
 - `Arcp\Errors\ARCPExceptionInterface` — root marker for every exception
   the SDK can throw. Implemented by the existing abstract
   `Arcp\Errors\ARCPException` (no migration needed for existing catch
@@ -39,5 +45,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial reference SDK release aligned with ARCP protocol v1.0 (see README status).
-
+- Initial reference SDK release aligned with ARCP protocol v1.1 (see README status).

README.md

@@ -133,14 +133,21 @@ to keep the example self-contained:
 
 Topic guides under [docs/](docs/):
 
-- [docs/authentication.md](docs/authentication.md) — built-in schemes,
+- [docs/getting-started.md](docs/getting-started.md) — install and run
+  an in-process client/runtime demo.
+- [docs/architecture.md](docs/architecture.md) — PHP namespace layout
+  and runtime/client layering.
+- [docs/transports.md](docs/transports.md) — WebSocket, stdio, and
+  in-memory transports.
+- [docs/guides/auth.md](docs/guides/auth.md) — built-in schemes,
   AuthRouter wiring, custom schemes, failure semantics.
-- [docs/errors.md](docs/errors.md) — full exception hierarchy, retry
-  defaults, code-driven dispatch.
-- [docs/retries.md](docs/retries.md) — when to retry, backoff with
-  jitter, idempotency keys.
-- [docs/subscriptions.md](docs/subscriptions.md) — subscribe API,
-  filter shape, backfill markers, backpressure.
+- [docs/guides/errors.md](docs/guides/errors.md) — full exception
+  hierarchy, retry defaults, code-driven dispatch.
+- [docs/guides/jobs.md](docs/guides/jobs.md) — tool invocation, job
+  state, cancellation, budgets, and agent versions.
+- [docs/guides/job-events.md](docs/guides/job-events.md) — progress,
+  metrics, streams, subscriptions, and result chunks.
+- [docs/recipes.md](docs/recipes.md) — PHP recipes for common flows.
 
 ## Supported PHP versions
 

docs/README.md

@@ -0,0 +1,63 @@
+# ARCP PHP SDK documentation
+
+Reference docs for the ARCP PHP SDK. The top-level
+[README](../README.md) is the front door; these pages go deeper into
+the runtime, client, transports, and protocol features.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./diagrams/architecture-dark.svg">
+  <img alt="ARCP PHP SDK architecture" src="./diagrams/architecture-light.svg">
+</picture>
+
+## Start here
+
+- [Getting started](./getting-started.md) - install, create an in-process runtime + client, run the checks.
+- [Architecture](./architecture.md) - how the PHP namespaces fit together.
+- [Transports](./transports.md) - WebSocket, stdio, and memory transports.
+- [CLI](./cli.md) - the `bin/arcp` command shipped by `arcp/arcp`.
+
+## Guides (one per spec section)
+
+| Page | Spec |
+| --- | --- |
+| [Sessions](./guides/sessions.md) | §6 |
+| [Resume](./guides/resume.md) | §6.3 |
+| [Authentication](./guides/auth.md) | §6.1 |
+| [Jobs](./guides/jobs.md) | §7 |
+| [Job events](./guides/job-events.md) | §8 |
+| [Leases](./guides/leases.md) | §9 |
+| [Delegation](./guides/delegation.md) | §10 |
+| [Observability](./guides/observability.md) | §11 |
+| [Errors](./guides/errors.md) | §12 |
+| [Vendor extensions](./guides/vendor-extensions.md) | §15 |
+
+## PHP Namespaces
+
+The TypeScript SDK has package-specific docs because its code is split
+across multiple npm packages. PHP ships as one Composer package,
+`arcp/arcp`, so this documentation follows the namespace layout under
+`src/`.
+
+| Namespace | Purpose |
+| --- | --- |
+| `Arcp\Envelope`, `Arcp\Json` | Wire envelope model and serialization |
+| `Arcp\Messages` | Typed protocol payloads |
+| `Arcp\Errors` | Canonical error codes and exceptions |
+| `Arcp\Client` | `ARCPClient` and client-side handlers |
+| `Arcp\Runtime` | `ARCPRuntime`, jobs, leases, artifacts, subscriptions |
+| `Arcp\Transport` | WebSocket, stdio, and in-memory transports |
+| `Arcp\Auth` | Built-in auth schemes and `AuthRouter` |
+| `Arcp\Store` | Event log and idempotency persistence |
+| `Arcp\Extensions` | Vendor extension classification |
+| `Arcp\Cli` | `bin/arcp` commands |
+
+## Reference
+
+- [Recipes](./recipes.md) - copy-paste PHP solutions to common problems.
+- [Conformance](./conformance.md) - implemented and deferred protocol surfaces.
+- [Troubleshooting](./troubleshooting.md) - error codes and fixes.
+
+## Diagrams
+
+The diagram above is generated from Graphviz. Source files and the
+authoring guide live in [`./diagrams/`](./diagrams/).

docs/architecture.md

@@ -0,0 +1,79 @@
+# Architecture
+
+The PHP SDK is a single Composer package, `arcp/arcp`, with namespaces
+that map to the same layers as the TypeScript SDK packages.
+
+## Layering
+
+| Layer | PHP namespace |
+| --- | --- |
+| Wire/core | `Arcp\Envelope`, `Arcp\Messages`, `Arcp\Errors`, `Arcp\Ids` |
+| Client | `Arcp\Client` |
+| Runtime | `Arcp\Runtime`, `Arcp\Internal\Runtime` |
+| Transports | `Arcp\Transport` |
+| Persistence | `Arcp\Store` |
+| Extensions | `Arcp\Extensions` |
+
+The public surface is intentionally small: `ARCPClient`, `ARCPRuntime`,
+the message DTOs, transports, typed errors, and IDs. Internal dispatch
+collaborators live under `Arcp\Internal`.
+
+## Core
+
+`Arcp\Envelope\Envelope` is the top-level wire object. Payload
+polymorphism is handled by `MessageTypeRegistry`; the default registry is
+created by `MessageCatalog::create()`.
+
+Serialization is handled by `Arcp\Json\EnvelopeSerializer`, which turns
+envelopes into protocol JSON and back without reflection.
+
+## Client
+
+`Arcp\Client\ARCPClient` owns:
+
+- session handshake,
+- the background read loop,
+- correlated response routing,
+- subscription callbacks,
+- helper APIs such as `invokeTool()`, `listJobs()`, `subscribe()`,
+  `cancelJob()`, `putArtifact()`, and `fetchArtifact()`.
+
+## Runtime
+
+`Arcp\Runtime\ARCPRuntime` owns:
+
+- registered tools and versioned tool resolution,
+- session negotiation,
+- job lifecycle,
+- permissions and leases,
+- artifacts,
+- subscriptions,
+- event logging.
+
+Tool handlers implement `Arcp\Runtime\ToolHandler` and receive a
+`JobContext` for progress, streams, metrics, permissions, artifacts, and
+result chunks.
+
+## CLI
+
+The aggregate package exposes `bin/arcp`, implemented with Symfony
+Console under `Arcp\Cli`.
+
+## Middleware
+
+There are no separate PHP middleware packages. PHP hosts should adapt
+`Arcp\Transport\Transport` to their framework or process model.
+
+## Wire format
+
+All messages are PHP value objects extending `MessageType`. Unknown core
+types are rejected as `UNIMPLEMENTED`; extension handling is delegated to
+`ExtensionRegistry`.
+
+## Where to read the code
+
+- `src/Client/ARCPClient.php`
+- `src/Runtime/ARCPRuntime.php`
+- `src/Envelope/MessageCatalog.php`
+- `src/Internal/Runtime/Dispatcher.php`
+- `src/Internal/Runtime/ToolInvocationHandler.php`

docs/authentication.md

@@ -0,0 +1,62 @@
+# CLI
+
+The PHP SDK ships `bin/arcp`, registered as a Composer binary.
+
+## Install
+
+```sh
+composer install
+bin/arcp --help
+```
+
+## `arcp serve`
+
+Run a WebSocket runtime:
+
+```sh
+bin/arcp serve --host 127.0.0.1 --port 8765
+```
+
+Useful options:
+
+| Option | Meaning |
+| --- | --- |
+| `--host` | Bind address. |
+| `--port` | TCP port. |
+
+## `arcp send`
+
+Invoke a tool and print the terminal result:
+
+```sh
+bin/arcp send ws://127.0.0.1:8765 echo -a '{"message":"hello"}'
+```
+
+Arguments are JSON objects.
+
+## `arcp tail`
+
+Subscribe to envelopes and print events:
+
+```sh
+bin/arcp tail ws://127.0.0.1:8765
+```
+
+## `arcp replay`
+
+Replay an event log file:
+
+```sh
+bin/arcp replay events.sqlite -a msg_previous
+```
+
+## stdio
+
+Use `StdioTransport` directly from PHP when the runtime is a child
+process. The CLI focuses on WebSocket serving, sending, tailing, and log
+replay.
+
+## Exit codes
+
+The command exits non-zero on invalid input, failed connection, failed
+serialization, or a protocol error returned by the runtime.