jaato-sdk 0.16.0__tar.gz

jaato_sdk-0.16.0/PKG-INFO

@@ -0,0 +1,783 @@
+Metadata-Version: 2.4
+Name: jaato-sdk
+Version: 0.16.0
+Summary: Jaato SDK - Protocol and client library for jaato server
+Author: apanoia
+License-Expression: BUSL-1.1
+Project-URL: Repository, https://github.com/Jaato-framework-and-examples/jaato
+Project-URL: Issues, https://github.com/Jaato-framework-and-examples/jaato/issues
+Keywords: jaato,sdk,ipc,client
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: python-dotenv
+Requires-Dist: pydantic<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Provides-Extra: ws
+Requires-Dist: websockets>=12.0; extra == "ws"
+
+# Changelog
+
+## 0.16.0 (2026-09-09)
+
+- ci: publish to PyPI, and add jaato-eval to the release set (#923)
+- fix(enrichment): every dict tool result reaches the enrichment chain (#922) (#924)
+- fix(session): record signal_completion's tool result so a completed session stays revivable (#913) (#915)
+- feat(resume): both resume verbs carry an attachment (#845) (#914)
+- feat(web): replace the web-client PoC with jaato-web, a browser client on @jaato/sdk
+- fix(runner): carry slot-scoped plugin instances across cascade sessions (#890) (#891)
+- fix(service_connector): mark call_service results untrusted (#857) (#878)
+- feat(permission): the resolved event, the ledger and the session record name who decided (#859) (#876)
+- feat(security): scrub secret env vars from model-driven subprocesses by default (#863) (#872)
+- fix(media): the spoken transcript rides the final media chunk to the client (#869) (#871)
+- fix(gc): evict consumed inbound media, and let GC see media at all (#850) (#853)
+- feat(scaffold): the sweep gate as one set, and make its ceiling actually work (#768 #769 #770 #772) (#849)
+- fix(scaffold): the templates take their turn from the SDK facade (#820 #821 #825 #826 #827 #822)
+- feat(media): deliver binary media chunks, and know when a spoken turn ended (#824)
+- chore: normalise line endings to LF, once, in one commit (#794) (#807)
+- feat(events): carry the billed prompt/output split on the wire (#802) (#803)
+- fix(providers): a stream that dies mid-response is not a finished turn (#687) (#786)
+- fix(tui,clarification): answer a batched clarification instead of hanging (#704) (#783)
+- fix(sdk,session): a turn boundary is not the session's terminus (#767) (#774)
+- fix(providers): one prompt-token convention, converted at the seam (#758) (#763)
+- fix(session): a turn cut off at the output cap must be continued, not lost (#749) (#759)
+- fix(session): a call the severed turn never ran must still be answered (#751) (#757)
+- fix(providers): unreadable tool-call arguments must not become a call (#750) (#753)
+- fix(providers): a truncated turn must not report as a tool-use turn (#745) (#747)
+- fix(daemon): refuse a relative path at the process boundary (#742) (#744)
+- fix(cache): model tiers × prompt caching — the knobs never arrived, and the cost was invisible (#737)
+- feat(plugins): declare the session-persistence contract, and use it for permissions (#708)
+- fix(memory): list_memory_tags reported an empty store while holding a raw queue (#664)
+- ci: run the SDK's package-internal tests, and refreeze the 102 baselines nobody was running (#661)
+- ci: cyclomatic-complexity ratchet, fixed so it cannot silently skip (#656)
+- feat(events): a stage that was asked twice to signal completion, and never did, says so (#654)
+- feat(doctor): point at the generator, and spot a driver that has gone stale (#651)
+- feat(scaffold): a `sweep` archetype for N independent arms (#649)
+- feat(sdk): the completeness rule ships as a function, not as advice (#648)
+- feat(sdk): a live conformance suite, run against a real daemon in CI (#646)
+- feat(sdk): one pairing rule, in the layer consumers can import (#640)
+- fix(sdk): the breaking change needs a version that says so (#636)
+- feat(sdk)!: create_session says which failure happened (#635)
+- fix(delivery): unreachable was five outcomes wearing one word (#634)
+- fix(inject): an inject into an idle session was a black hole, and said "ok" (#619)
+- fix(executor): two 2-tuple conventions shared one representation (#608)
+- feat(protocol): every event says which session it is about (#603)
+- feat(protocol): correlate session.new with the event that answers it (#598)
+- fix(sdk): sibling_name reaches the facade — and peer→sibling for the coordination surface (#593)
+- feat(queue): SourceType.PEER, idle-only, and tier membership declared once (#590)
+- feat(gc): typed GC lifecycle events on the bus (#587)
+- fix(sdk): IPCRecoveryClient accepts config_root/apparmor; parity test covers ctor args (#585)
+- fix(budget): surface a ceiling refusal as a terminal, typed event (#584)
+- IPCRecoveryClient: catch up to IPCClient, and a test so it cannot drift again
+- Cascade refusal must reach the client, not just the daemon log
+- IPC verbs for cascade budgets: set / get / clear
+- Thread spend_total_tokens to the client (UsageBreakdown)
+- Fix: envelope producer never populated budget_control (feature was dead)
+- feat(session): surface abnormal finish reasons to clients
+- HistoryEvent: accept the runner's rich turn_accounting (relax Dict[str,int]→Any)
+- refactor(facade): ship the `jaato` convenience facade in jaato-sdk (sdk-only client) (#527)
+- test(events): add missing wire-format baselines for session.restored/woken/wake_bind_result (#528)
+- feat(sdk): typed client wake methods — bind_wake / unbind_wake / cascade_register (#525)
+- feat(sdk): public open_event_stream() — synchronous-subscribe event iterator (#524)
+- fix(wake): headless client-tool dispatch — whitelist sync + drive-after-wiring (#521)
+- feat(server): durable deferred-turn wake (Option 2 — cold-revive-and-act) (#520)
+- feat(server): surface daemon wake endpoint on bind_wake (production routing) (#519)
+- feat(server): wake binding registry + bind_wake/unbind_wake (PR 2a, mode-B foundation) (#517)
+- security: untrusted-content trust boundary for web_fetch/web_search/MCP (#495)
+- Security hardening + per-session egress confinement (proxy + cgroup-nft) (#492)
+- fix(tool-results): keep result STRUCTURED; move model-facing steering to ToolResult.model_suffix (#490)
+- fix(sdk): register session.restored in the deserializer dispatch table (#467)
+- docs: resync README + web docs to WS-recovery / TLS / scaffold / presentation surface (#466)
+- feat(sdk): presentation= override + recovery host-tool/batch proxies (Telegram WS migration) (#465)
+- fix(sdk): IPCRecoveryClient.create_session accepts timeout — drop-in parity with IPCClient (#397)
+- feat(sdk): ssl=/ca= on WSClient + WSRecoveryClient for wss:// (self-signed / dev CAs) (#462)
+- feat(sdk): WSRecoveryClient — auto-reconnect for a remote WS daemon (#459)
+- docs+scaffold: multi-transport (in-process / IPC / WebSocket) (#445)
+- feat(sdk): WSClient — WebSocket transport for the facade (remote daemon) (#444)
+- fix(sdk): facade never deadlocks on a raising on_permission callback (#434)
+- docs(sdk): complete the convenience-facade docstring — client-agnostic (#432)
+- fix(sdk): IPCRecoveryClient background event pump (facade-over-recovery hang) + workspace_path str coerce
+- feat(sdk): Session.client — public accessor for mixing facade + low-level
+- feat(sdk): facade gaps — config_root/apparmor, per-turn parallel_tools/attachments
+- feat(sdk): client_tools= on IPCClient.session — host tools via the facade
+- feat(sdk): convenience facade Phase 2 — Session.stream() + IPCRecoveryClient.session()
+- test(sdk): refresh stale gate.released wire baseline (session_id field)
+- feat(sdk): high-level convenience facade (IPCClient.session / ask / complete)
+- feat(events): bridge gate.released onto the reactor event bus
+- feat(doctor): stale premium-reactor detection + reuse-vs-fresh advisory
+- feat(multimodal): ferry user-message attachments to the runner-tier model
+- feat(client-tools): IPC transport support + SDK register_client_tools + host-tools scaffold
+- feat(tooling): runtime-entity debugging — explain runtime + doctor --session
+- feat(tooling): WebSocket awareness in doctor, scaffold, and the client skill
+- feat(cli): jaato-doctor console script + document both dev-tool shortcuts
+- test(sdk): regenerate event wire-format baselines after additive field changes
+- fix(sdk): client connection resilience — env_file=None, cold-start timeout, stale-pidfile
+- feat(sdk): doctor daemon-env report drives off the introspected read-set
+- feat(sdk): doctor reports the JAATO_* env vars the daemon was fired with
+- feat(sdk): client doctor + jaato-scaffold tool + provider knob/quirk contract
+- feat(reliability): compute is_error_result on tool.call_completed
+- feat(sdk): reliability reactor event types (emit substrate)
+- fix(sdk): add session_id to AgentCreatedPayload to match the server event
+- feat(events): SlotSettledEvent.terminal_reason — fixes slot.settled-vs-recovery double-advance
+- feat(events): AgentErrorEvent + on_agent_error recovery contract
+- feat(result_grep): model-directed tool-result grep filtering + greppable_content trait
+- feat(events): SlotSettledEvent — universal per-cascade-stage handoff signal (replaces SlotReusableEvent)
+- feat(events): add agent_id (stage name) to SlotReusableEvent payload
+- feat(events): SlotReusableEvent — emit when a pool slot is reusable (cascade warm-reuse)
+- feat(lifecycle): processor-gated is_complete + server-side auto-finalize
+- fix(sdk): create_session surfaces all ErrorEvents, not only non-recoverable
+- feat(sdk+core): expose ToolResult.enrichment_metadata on the tool-call ledger
+- feat(core): cascade.cancel(cid) IPC verb + reactor-suppression predicate
+- feat(sdk): add session_id field to AgentCreatedEvent (#205)
+- fix(sdk): cascade_events filters by event_type client-side (#191)
+- fix(bus): bridge SessionTerminatedEvent to EventBus (Bug C) (#189)
+- feat(processor): ProcessorResult TypedDict + jaato_sdk.cascade_authoring umbrella (#187)
+- feat(events): carry error context onto SessionTerminatedEvent (Q2) (#186)
+- feat(sdk): expose ToolCallEntry TypedDict for completion processors (#184)
+- feat(cascade-as-client): Phase 2 — SDK IPC RPC verbs + disconnect cleanup (#180)
+- fix(sdk): plumb cascade_driver_id kwarg through IPCClient.create_session (#170)
+- feat(cascade-sharing): Phase 1a — reset_for_next_session protocol + 8-plugin audit (#160)
+- feat(apparmor): plugin-contribution hook (Phase 0, template v20)
+- session_manager: defer-and-flush foundation for disk-restored sessions (Phase 3 §3.12 + peer-review M5/N1)
+- sdk 0.13.0: replace single-reader gate with drain-task + subscriber queues
+- sdk 0.12.0: client_type is mandatory on IPCClient and IPCRecoveryClient
+- sdk 0.11.0: relocate classify_template_evaluation_kind to SDK boundary
+- server 0.6.27 + sdk 0.10.0: SessionTerminatedEvent + cancellation-aware end_session
+- sdk 0.9.0: minor bump for AppArmor dispatch + bridged-payload alignment
+- server 0.6.1: AppArmor dispatch + subagent profile resolution + completion-nudge guard (#49)
+- sdks: align bridged payloads + tests with gap 1-5 wire shapes
+- release: coordinated bump for gap 1-5 SDK release
+- sdks: protocol-version compat (gap 5)
+- sdks: subscribe API, profile picker, inline session spec, cost/usage refactor
+- SDK + TUI parity: end_session / delete_session typed methods
+- SDK parity: complete TS surface + tool-execute-result on both sides
+- SDK helpers: compute_cache_hit_percent + TUI adoption
+- Phase 1: SDK feature parity — typed WS verbs + JaatoClient methods
+- Phase 0: Migrate jaato-sdk events.py from @dataclass to pydantic
+- Document WebSocket transport in jaato-sdk README
+- Expand jaato-sdk README with protocol and client reference
+- SDK file staging: binary-framed StageFilesRequest for WS clients
+- signal_completion: typed payloads from profile-declared schema
+- Permission timeout configurable per-client via ClientConfigRequest
+- Bundle tool_id_mappings in SessionInfoEvent for guaranteed delivery
+- ToolIdRegistryEvent: server pushes ID→name mapping to clients
+- WS: read category descriptions from tools.register_client message
+- Fork-replay primitives: 5 general-purpose capabilities for session manipulation
+- Confine tool execution by default; opt out via TRAIT_FRAMEWORK_LEVEL
+- Fix: resolve relative trace paths against JAATO_WORKSPACE_ROOT
+- Include comment in PermissionResolvedEvent for WS clients
+- Migrate plugin config schemas from PluginSetting to JSON Schema
+- Add introspectable plugin settings via PluginSetting and get_config_schema()
+- Complete agent/profile split: SDK, TUI, and deprecation warning
+- Remove icon and icon_name from profiles
+- Emit events.subscribed notification for external event subscriptions
+- Add event.external WS handler for client-to-agent event injection
+- Add error field to AgentCompletedPayload
+- Include cancellation reason in [Generation cancelled] messages
+
+---
+
+# jaato-sdk
+
+Python client SDK for connecting to a [jaato](https://github.com/Jaato-framework-and-examples/jaato) server. Provides the wire protocol, async IPC client, and an auto-reconnecting recovery client.
+
+## Installation
+
+```bash
+pip install jaato-sdk
+```
+
+## Quick Start
+
+The simplest path is the **convenience facade** — `jaato.session(mode=...)` + `Session.ask` / `.complete` / `.stream`. The same code runs the agent embedded in your process, against a local daemon, or against a remote one — flip `mode` (see [Transports](#transports--three-ways-to-run-the-same-agent)):
+
+```python
+import asyncio
+import jaato
+
+async def main():
+    async with jaato.session(mode="in_process",
+                             profile={"model": "...", "provider": "..."}) as s:
+        print(await s.ask("Hello!"))
+        async for chunk in s.stream("Tell me a story."):
+            print(chunk, end="", flush=True)
+
+asyncio.run(main())
+```
+
+For full control over the event stream, permissions, and the connection lifecycle, use a client directly:
+
+```python
+import asyncio
+from jaato_sdk import IPCRecoveryClient, EventType
+
+async def main():
+    client = IPCRecoveryClient()  # default: /tmp/jaato.sock (Windows: \\.\pipe\jaato)
+
+    # Typed event handlers — register before connect() to capture
+    # the inaugural ConnectedEvent.
+    client.subscribe(EventType.AGENT_OUTPUT, lambda e: print(e.text, end=""))
+    client.subscribe(EventType.TOOL_CALL_START, lambda e: print(f"\n[tool: {e.tool_name}]"))
+
+    await client.connect()
+    await client.create_session()
+    await client.send_message("Hello!")
+
+    # Drive the event loop so the dispatcher fires.  Either iterate
+    # client.events() (legacy style) or await client.drain_events()
+    # to let your subscribers do the work.
+    await client.drain_events()
+
+asyncio.run(main())
+```
+
+## Core Concepts
+
+### Server-first architecture
+
+In the daemon transports (`ipc` / `ws`), the agent runs in a separate **jaato server** process; the SDK is a transport layer that ships JSON-encoded events to the server and yields them back to your code as Python dataclasses. The `in_process` transport is the embedded alternative — the agent runs *in your process* with no daemon — and exposes the **same** facade, so you can develop embedded and deploy behind a daemon (or the reverse) without changing your agent code.
+
+```
+your code  ──►  IPCRecoveryClient  ──►  /tmp/jaato.sock  ──►  jaato server (agent loop)
+                                                                    │
+your code  ◄──  IPCRecoveryClient  ◄──  /tmp/jaato.sock  ◄──────────┘
+                       (events)
+```
+
+If no server is running and `auto_start=True` (the default), the client launches `python -m server --daemon` for you.
+
+### Transports — three ways to run the same agent
+
+The convenience facade (`Session.ask` / `.complete` / `.stream`) runs over **three transports**. Pick one with `jaato.session(mode=...)`: the session spec and the facade are identical — `mode` is the only thing that changes.
+
+| Mode | Transport | Client | Use when |
+|---|---|---|---|
+| `in_process` | none — embedded in your process | `InProcessClient` | No daemon, no socket. The agent runs *in your Python process* — lowest latency, simplest deploy. |
+| `ipc` | Unix domain socket / Windows named pipe | `IPCClient` | A daemon on the **same machine** (TUI, scripts, local tooling). Auto-start, framing, multi-session. |
+| `ws` | WebSocket (`ws://` / `wss://`) | `WSClient` | A **remote** daemon (and the protocol any browser / JavaScript client speaks). Bearer-authenticated. |
+
+```python
+import jaato
+
+# Embedded — no daemon, the agent runs in your process:
+async with jaato.session(mode="in_process",
+                         profile={"model": "...", "provider": "..."}) as s:
+    print(await s.ask("Hi"))
+
+# Local daemon over a Unix socket:
+async with jaato.session(mode="ipc", profile="researcher") as s:
+    print(await s.ask("Hi"))
+
+# Remote daemon over WebSocket:
+async with jaato.session(mode="ws", url="wss://host:8080", token="...",
+                         profile="researcher") as s:
+    print(await s.ask("Hi"))
+```
+
+The wire protocol *above* the transport is identical — the same `Event` JSON frames — so `WSClient` is `IPCClient` with only the transport swapped (WS frames self-delimit; no length prefix), and `InProcessClient` is the embedded analog that replicates in-process what the daemon does for a connected session. One example runs every way by flipping `mode`.
+
+To start the server with WebSocket enabled:
+
+```bash
+python -m server --ipc-socket /tmp/jaato.sock --web-socket :8080 --daemon
+```
+
+WS clients authenticate with a bearer token (auto-generated to `~/.jaato/ws.token` on first start) sent either as `Authorization: Bearer <token>` on the upgrade request or as `?token=<token>` for browsers that can't set headers. The server stores only the SHA-256 digest and rejects bad tokens with WS close code 1008 before any session work happens. The Python `WSClient` ships in this SDK — install the optional `websockets` dependency with `pip install 'jaato-sdk[ws]'`.
+
+### Clients
+
+| Client | Transport | Use when |
+|---|---|---|
+| `InProcessClient` | embedded (no daemon) | Run the agent in your own process — `jaato.session(mode="in_process")`. |
+| `IPCClient` | Unix socket | A thin, transparent connection to a **local** daemon. No retries — if the server goes away, your iterator ends. |
+| `WSClient` | WebSocket | A **remote** daemon over `ws://` / `wss://`. `IPCClient` with the transport swapped; needs the `jaato-sdk[ws]` extra. |
+| `IPCRecoveryClient` | Unix socket | Automatic reconnection with exponential backoff + session reattachment. Recommended for long-running IPC apps. |
+| `WSRecoveryClient` | WebSocket | Automatic reconnection + session reattachment over WebSocket — a `WSClient` subclass with the same recovery machinery (and `on_status_change`) as `IPCRecoveryClient`. Recommended for long-running remote apps; needs the `jaato-sdk[ws]` extra. |
+
+All five expose the **same facade-client contract**, so the convenience `Session` (`ask` / `complete` / `stream`) and the transport-agnostic `jaato.session(mode=...)` entry ride on any of them. The recovery clients wrap their base transport with a state machine and a configurable retry policy; they expose the same request methods plus connection-lifecycle hooks. With the facade, pass `recovery=True` on a daemon transport to get the recovery client:
+
+```python
+import jaato
+
+# IPCRecoveryClient — auto-reconnect over the local socket:
+async with jaato.session(mode="ipc", recovery=True, profile="researcher",
+                         on_status_change=lambda st: print(st.state)) as s:
+    print(await s.ask("Long task..."))
+
+# WSRecoveryClient — auto-reconnect over WebSocket, trusting a self-signed
+# wss:// cert via a per-connection CA bundle:
+async with jaato.session(mode="ws", url="wss://host:8080", token="...",
+                         recovery=True, ca="/etc/jaato/dev-ca.pem",
+                         on_status_change=lambda st: print(st.state)) as s:
+    print(await s.ask("Long task..."))
+```
+
+`recovery=True` works on the two daemon transports (`ipc` / `ws`); `mode="in_process", recovery=True` raises `ValueError` (no daemon to reconnect to). `IPCRecoveryClient.create_session(timeout=...)` mirrors `IPCClient.create_session` for drop-in parity.
+
+### WS TLS (`ssl=` / `ca=`)
+
+For a self-signed or internal `wss://` endpoint, `WSClient` / `WSRecoveryClient` (and `jaato.session(mode="ws", ...)`) accept `ssl=` (an `ssl.SSLContext`, or `True`/`False`) and `ca=` (a CA-bundle path). A `ca` path is loaded into a default verifying context; `ssl` wins if both are set. They are scoped **per connection** — loaded into the connection's `SSLContext`, never `os.environ` — so, unlike an `SSL_CERT_FILE` env hack, they cannot leak into a subprocess-restarted daemon's outbound HTTPS (the Python analog of Node's `NODE_EXTRA_CA_CERTS`).
+
+### Events vs requests
+
+Everything on the wire is an `Event` dataclass.
+
+- **Server → Client events** describe what the agent is doing: `AgentOutputEvent`, `ToolCallStartEvent`, `PermissionRequestedEvent`, `PlanUpdatedEvent`, `TurnCompletedEvent`, `ErrorEvent`, …
+- **Client → Server requests** are the same `Event` shape but flow the other way: `SendMessageRequest`, `PermissionResponseRequest`, `StopRequest`, `CommandRequest`, …
+
+You never construct request events directly in normal usage — the client provides typed methods like `send_message()`, `respond_to_permission()`, `stop()`. Construct the request dataclasses only when you need to send something the convenience methods don't cover (use `client.execute_command()` for that).
+
+## Event Flow
+
+### connect() sequence
+
+```
+client.connect()
+├─ open socket / pipe
+├─ wait for ConnectedEvent           # carries client_id + server_version
+├─ send CommandRequest(set_workspace) # client cwd
+└─ send ClientConfigRequest          # env file + PresentationContext
+```
+
+After `connect()` returns `True`, the server has accepted the connection but no session is attached yet. Either call `create_session()` to spawn a new one or `attach_session(id)` to resume an existing one.
+
+### send_message() sequence
+
+```
+client.send_message("Read config.json")
+├─ SendMessageRequest                  # → server
+│
+├─ AgentOutputEvent     {source: "model", text: "I'll read..."}
+├─ AgentOutputEvent     {source: "model", text: " the file."}
+├─ ToolCallStartEvent   {tool_name: "read", tool_args: {...}, call_id: "..."}
+├─ ToolOutputEvent      {chunk: "..."}                      # if the tool streams
+├─ ToolCallEndEvent     {call_id: "...", success: true}
+├─ AgentOutputEvent     {source: "model", text: "The file..."}
+└─ TurnCompletedEvent   {usage: UsageBreakdown(...), duration_seconds: 1.5}
+```
+
+`AgentOutputEvent.mode` is `"write"` for a new block of output and `"append"` for streaming continuation chunks. `source` is one of `"model"`, `"tool"`, `"system"`, or a plugin name.
+
+The three usage-bearing events (`TurnCompletedEvent`, `TurnProgressEvent`, `ContextUpdatedEvent`) all carry the same `UsageBreakdown` shape — token counts, cache hits, reasoning/thinking tokens, and `cost_usd` populated when the daemon can derive it. Cost resolution: provider-reported (e.g. claude_cli) wins over pricing-table computed from `.jaato/pricing.json`; otherwise `None` (never silently zero). See [docs/sdk-pricing.md](../docs/sdk-pricing.md) for the full pricing contract.
+
+GC configuration is its own event (`GCConfigEvent`) since v1.0 — subscribe to that for status-bar GC display rather than reading from `ContextUpdatedEvent`.
+
+### Permission flow
+
+When a tool needs approval, the server pauses and emits a permission request. The client responds with one of the offered keys.
+
+```
+ToolCallStartEvent
+PermissionRequestedEvent   { request_id, tool_name, tool_args, response_options, prompt_lines }
+PermissionInputModeEvent   { request_id }                  # signal: take input now
+        │
+        │ client.respond_to_permission(request_id, "y")    # → server
+        ▼
+PermissionResolvedEvent    { request_id, response, granted }
+ToolCallEndEvent           { ... }                          # tool runs
+```
+
+Permission response keys (returned in `response_options`):
+
+| Key | Meaning |
+|-----|---------|
+| `y` | allow this tool execution |
+| `n` | deny this tool execution |
+| `a` / `always` | allow and whitelist the tool for this session |
+| `t` / `turn` | allow remaining tool calls this turn |
+| `i` / `idle` | allow until the session goes idle |
+| `once` | allow once without remembering |
+| `all` | allow all future requests in this session |
+| `never` | deny and blacklist the tool for this session |
+| `c:<text>` | deny **with feedback** the model sees as the tool result |
+| `yc:<text>` | allow **with feedback** the model sees alongside the tool result |
+| `e` | edit the arguments and re-prompt (pass `edited_arguments=...`); only offered when the request has editable content |
+
+The two comment variants let you steer the model without simply rejecting the call. Pass them to `respond_to_permission` as a single string with the prefix and the text:
+
+```python
+await client.respond_to_permission(request_id, "c:please check the file size first")
+await client.respond_to_permission(request_id, "yc:ok but write the result to /tmp/audit.log")
+```
+
+The server strips the `c:` / `yc:` prefix and forwards the comment to the model alongside the deny/allow decision. Empty text after the prefix falls back to plain `n` / `y`.
+
+### Cancellation
+
+`await client.stop()` sends a `StopRequest`. The server cancels in-flight tool calls and the streaming model call; expect to see an `AgentStatusChangedEvent(status="error")` or a `TurnCompletedEvent` with cancellation metadata, then the iterator continues normally.
+
+## Client Options
+
+```python
+client = IPCRecoveryClient(
+    socket_path="/tmp/jaato.sock",   # Unix socket or Windows pipe name
+    config=RecoveryConfig(...),       # see "Auto-reconnection" below
+    auto_start=True,                  # spawn server daemon if not running
+    env_file=".env",                  # client env forwarded to server (relative to workspace)
+    workspace_path=Path.cwd(),        # what the server sees as the working directory
+    config_root=None,                 # optional: <path>/.jaato override for read-only config
+    apparmor=False,                   # optional: opt into per-session AppArmor confinement
+    on_status_change=lambda s: ...,   # ConnectionStatus callback
+)
+```
+
+`IPCClient` takes the same parameters minus `config` and `on_status_change`.
+
+### `config_root`
+
+When set, decouples *where the agent runs* (`workspace_path`) from *where the daemon reads its read-only framework config* — profiles, agent .md files, prompts, references, completion_schemas, instructions, scripts, services. The daemon scans `<config_root>` instead of `<workspace_path>/.jaato/`. The user-tier `~/.jaato/` is always honored.
+
+Pair with a `workspace_path` that does **not** contain a `.jaato/` symlink to give the agent's filesystem tools no visibility into the framework config.
+
+### `apparmor`
+
+Default `False`. Set to `True` to ask the daemon to confine each session created on this connection with a per-session AppArmor profile. Useful for orchestrator-driven harnesses where the LLM-driven tool plugins (`cli`, `file_edit`, `interactive_shell`) are the threat surface and a hallucinated path should be blocked at the kernel level rather than only inside the sandbox dir.
+
+The profile grants:
+- `workspace_path` — read/write
+- `config_root` — read-only (when set)
+- `~/.jaato/{agents,profiles,prompts,...}` — read-only
+- `~/.jaato/memories` — read/write
+- venv + jaato source tree — read-only
+
+When AppArmor is unavailable on the host (non-Linux, kernel module not loaded, `apparmor_parser` missing) the session falls back to running unconfined — but **does not** fail silently. The daemon always emits a `SystemMessageEvent` to the client describing the outcome: style `"info"` with prefix `[apparmor] confinement applied (...)` when enforcement is in effect, or style `"warning"` with prefix `[apparmor] requested but ...` when it isn't (and why). Print these in your event-handling loop so the user can see at a glance whether kernel confinement is really active for the run, instead of having to tail `/tmp/jaato.log`. See [`docs/apparmor-setup.md`](../docs/apparmor-setup.md) for prerequisites.
+
+The default remains `False` so today's TUI / IPC behavior is unchanged: a local user already has full filesystem access and confining their sessions adds friction without adding security.
+
+## Client State
+
+```python
+client.is_connected         # bool
+client.is_reconnecting      # bool (recovery client only)
+client.is_closed            # bool (recovery client only)
+client.state                # ConnectionState enum (recovery client only)
+client.session_id           # currently attached session, or None
+client.client_id            # assigned by the server on connect
+client.server_version       # server package version, or None on pre-0.2.28 servers
+client.get_status()         # → ConnectionStatus dataclass (recovery client only)
+```
+
+`ConnectionState` values: `DISCONNECTED`, `CONNECTING`, `CONNECTED`, `RECONNECTING`, `DISCONNECTING`, `CLOSED`.
+
+The recovery client refuses to send while reconnecting and raises `ReconnectingError`. Once `state == CLOSED` (max attempts exceeded, or `close()` called), it raises `ConnectionClosedError` and cannot be revived — construct a new instance.
+
+## Methods
+
+### Lifecycle
+
+```python
+await client.connect(timeout=5.0)
+await client.disconnect()       # graceful, can be reconnected
+await client.close()            # permanent (recovery client only)
+```
+
+### Sessions
+
+```python
+# By profile name — references .jaato/profiles/<name>.json on the server
+await client.create_session(
+    name="my-session",
+    profile="researcher",
+    agent="reviewer",
+    agent_params={"focus": "security"},
+)
+
+# By inline spec — same shape as a profile JSON, no disk file needed
+await client.create_session(
+    name="ops-task",
+    profile={
+        "model": "claude-sonnet-4-5",
+        "provider": "anthropic",
+        "plugins": ["cli", "web_search"],
+        "system_instructions": "You are an operations engineer.",
+        # Any other field a profile JSON accepts: plugin_configs, gc,
+        # env, max_turns, runtime_limits, model_tiers, ...
+    },
+)
+
+await client.attach_session(session_id)
+await client.get_default_session()
+await client.list_sessions()           # response arrives as SessionListEvent
+await client.list_profiles()           # response arrives as SessionProfilesEvent
+```
+
+#### Profile picker — SessionProfilesEvent shape
+
+`list_profiles()` triggers a `SessionProfilesEvent` with a stable, versioned shape — pin against `schema_version` if you build a profile-picker UI:
+
+```python
+event.schema_version       # "1.0" — bumped only on breaking shape changes
+event.profiles             # List[ProfileSummary]
+event.parse_errors         # List[ProfileParseError] — broken files surface here, not in `profiles`
+```
+
+`ProfileSummary` exposes the safe-to-display subset of a profile (full field list in `jaato_sdk/events.py`):
+
+| Field | Purpose |
+|---|---|
+| `name`, `description` | identity |
+| `plugins`, `preloaded_plugins`, `plugin_configs` | capabilities |
+| `model`, `provider`, `max_turns`, `model_tiers` | runtime |
+| `gc`, `runtime_limits`, `completion_payload_schema` | structural config (dicts, expose as-is) |
+| `env_var_names` | **names only** — env values never leave the daemon |
+
+Deliberately **not** exposed: `system_instructions` (deprecated, now lives in agents), `icon_name` (deprecated), `inherits` (resolved during discovery), env values (sensitive). Profile-author secrets should always go through `${VAR}` indirection in `env`.
+
+#### `profile` parameter polymorphism
+
+The `profile` parameter is polymorphic:
+
+- **`str`** → references a profile JSON on the server's disk under `.jaato/profiles/`. Use this when an operator has curated profiles for human users.
+- **`dict`** → inline spec with the same shape. Use this when you're an orchestrator with your own governance layer and don't want to depend on disk files.
+
+The two forms are mutually exclusive — pass one or the other. The server validates inline specs and rejects them with an `ErrorEvent` if `model` is missing (no silent default fallback). `agent` and `agent_params` are independent of `profile` and compose with either form: profile decides *capabilities* (model, plugins, GC), agent decides *persona* (system instructions / personality).
+
+`create_session()` returns the new session id when no event iterator is active; otherwise it is fire-and-forget and the id arrives via the event stream as a `SessionInfoEvent`.
+
+### Messages and replies
+
+```python
+await client.send_message("Build the README", attachments=[...])
+await client.respond_to_permission(request_id, "y")
+await client.respond_to_permission(request_id, "e", edited_arguments={"path": "..."})
+await client.respond_to_clarification(request_id, "use json")
+await client.respond_to_clarification_batch(request_id, answers)   # one frame for a multi-question batch
+await client.respond_to_reference_selection(request_id, "1,3,4")
+await client.stop()
+```
+
+`respond_to_clarification_batch(request_id, answers)` emits a `ClarificationBatchResponseEvent` — the blessed batch form for WS / chat clients answering a whole question set at once, versus the per-question `respond_to_clarification`. `IPCRecoveryClient` also proxies `register_client_tools` (it remembers the registered tool set and re-registers on reconnect, so host tools survive a daemon restart) and `list_sessions`.
+
+### Commands and metadata
+
+```python
+await client.execute_command("model", ["claude-sonnet-4-5"])
+await client.request_command_list()    # response: CommandListEvent
+await client.request_history()         # response: HistoryEvent
+await client.disable_tool("bash")
+```
+
+### Event stream
+
+There are two ways to consume events: typed subscriptions (recommended) or the raw async iterator. They cooperate — subscribers always fire, and the iterator yields the same events.
+
+#### Typed subscriptions
+
+```python
+from jaato_sdk import EventType
+
+# One handler per type — only fires for that event type.
+unsub = client.subscribe(EventType.PERMISSION_REQUESTED, on_perm)
+
+# Fire once, then auto-unsubscribe.
+unsub = client.subscribe_once(EventType.AGENT_COMPLETED, on_done)
+
+# Catchall (every event regardless of type).
+unsub = client.subscribe_all(lambda e: log(e))
+
+# Register many in one call; unsub_all() removes them atomically.
+unsub_all = client.subscribe_many({
+    EventType.PERMISSION_REQUESTED: on_perm,
+    EventType.TOOL_CALL_START:      on_tool_start,
+    EventType.AGENT_COMPLETED:      on_done,
+})
+```
+
+Handlers may be sync (`def`) or async (`async def`). Async handlers are scheduled fire-and-forget on the current event loop — order of *delivery* is FIFO, but order of *completion* is not guaranteed. Exceptions and rejections are logged and swallowed; one bad handler never breaks the stream or affects others. Subscribing during dispatch only takes effect for the next event (the handler list is snapshotted before iterating).
+
+For the dispatcher to actually fire handlers, your code must drive the loop:
+
+```python
+# Option A — let subscribers do all the work
+await client.drain_events()
+
+# Option B — iterate and react to specific events directly
+async for event in client.events():
+    ...
+```
+
+The async iterator exits cleanly on disconnect. With `IPCRecoveryClient`, it survives reconnects: events from the new connection are yielded transparently after the gap, and subscribed handlers continue firing without re-registration.
+
+#### Migration from `set_event_callback`
+
+The old single-callback API was removed in jaato-sdk 0.4.0 — replace it with `subscribe_all`:
+
+```python
+# before
+client.set_event_callback(handle)
+await client.receive_events()
+
+# after
+client.subscribe_all(handle)
+await client.drain_events()
+```
+
+## Auto-reconnection
+
+`IPCRecoveryClient` retries with exponential backoff plus jitter and reattaches to the previous session on success.
+
+```python
+from jaato_sdk import RecoveryConfig
+
+config = RecoveryConfig(
+    enabled=True,
+    max_attempts=10,
+    base_delay=1.0,         # seconds
+    max_delay=60.0,
+    jitter_factor=0.3,      # ±30% random jitter
+    connection_timeout=5.0,
+    reattach_session=True,  # call attach_session() with the previous id after reconnect
+)
+```
+
+Status callback:
+
+```python
+from jaato_sdk import ConnectionState
+
+def on_status(status):
+    if status.state == ConnectionState.RECONNECTING:
+        print(f"reconnecting {status.attempt}/{status.max_attempts} "
+              f"in {status.next_retry_in:.1f}s ({status.last_error})")
+
+client = IPCRecoveryClient(on_status_change=on_status)
+```
+
+The recovery loop classifies errors as **transient** (retried — `ConnectionRefusedError`, `ConnectionResetError`, timeouts) or **permanent** (not retried — `IncompatibleServerError`, `FileNotFoundError`, permission/auth failures). Permanent errors transition straight to `CLOSED`.
+
+### Protocol version mismatch
+
+Each client pins a minimum **wire-protocol** version (`MIN_PROTOCOL_VERSION = "1.0"` on `IPCClient`, overridable per-instance via the `min_protocol_version=` constructor arg). On `connect()` the SDK reads `ConnectedEvent.protocol_version` from the daemon and runs a semver-flavoured compat check:
+
+- Server major must equal client major (otherwise wire shapes are incompatible)
+- Server minor must be ≥ client's required minor (otherwise daemon is missing fields the client expects)
+- Server with newer minor is fine — additive optional fields the client will ignore
+
+Mismatch raises `IncompatibleServerError` carrying both `server_protocol` and `min_protocol`, with a hint in the message about *why* (major mismatch vs missing minor). The recovery client classifies it as permanent — no retries. The daemon's package version (`server_version`) is reported for diagnostics but **not** used for the compat check; pin against `protocol_version` so a daemon bug-fix release doesn't require every client to re-pin.
+
+See [docs/sdk-protocol-versioning.md](../docs/sdk-protocol-versioning.md) for the bump policy and the CHANGELOG of past wire versions.
+
+## Configuration
+
+The recovery client picks up settings from these places, highest precedence first:
+
+1. Environment variables
+2. `<workspace>/.jaato/client.json`
+3. `~/.jaato/client.json`
+4. Built-in defaults
+
+```python
+from jaato_sdk.client import load_client_config, get_recovery_config
+
+config = load_client_config(workspace_path=Path.cwd())
+recovery = get_recovery_config(workspace_path=Path.cwd())
+```
+
+| Environment variable | RecoveryConfig field |
+|---|---|
+| `JAATO_IPC_AUTO_RECONNECT` | `enabled` |
+| `JAATO_IPC_RETRY_MAX_ATTEMPTS` | `max_attempts` |
+| `JAATO_IPC_RETRY_BASE_DELAY` | `base_delay` |
+| `JAATO_IPC_RETRY_MAX_DELAY` | `max_delay` |
+| `JAATO_IPC_RETRY_JITTER` | `jitter_factor` |
+| `JAATO_IPC_CONNECTION_TIMEOUT` | `connection_timeout` |
+| `JAATO_IPC_REATTACH_SESSION` | `reattach_session` |
+
+## Presentation Context
+
+Every client tells the server what its display surface looks like so the agent can adapt its output (avoid wide tables on a phone, skip mermaid on a TUI, etc.). The default is a generic terminal — override it before `connect()` if you're building a different kind of client.
+
+```python
+from jaato_sdk import PresentationContext, ClientType, CommunicationStyle
+
+presentation = PresentationContext(
+    content_width=72,
+    client_type=ClientType.CHAT,             # TERMINAL | WEB | CHAT | API
+    supports_tables=False,
+    supports_expandable_content=True,        # client wraps overflow itself
+    communication_style=CommunicationStyle.CONVERSATIONAL,
+)
+```
+
+`ClientType` describes the kind of surface, not a specific app. Telegram, Slack and WhatsApp bots are all `CHAT`. `CommunicationStyle.CONVERSATIONAL` tells the model to send short, frequent updates; `NARRATIVE` tells it to deliver one well-structured response at the end. When `communication_style` is left `None`, `CHAT` defaults to conversational and everything else to narrative.
+
+Pass a `PresentationContext` (or a plain `dict`) as `presentation=` to the client constructor — `IPCClient` / `WSClient` / `IPCRecoveryClient` / `WSRecoveryClient`, their `.session(...)`, or `jaato.session(mode="ipc"|"ws", presentation=...)`. It **replaces** the auto-derived terminal context at connect-time config-send, so a chat / web client whose capabilities differ from a TUI's (e.g. narrow `content_width`, `supports_tables=False`, `supports_images=True`, `supports_expandable_content=True`, `client_type=CHAT`) declares them once. A recovery client threads `presentation=` through every inner client it rebuilds, so it survives reconnection. (`presentation=` is not yet wired for `mode="in_process"`.)
+
+```python
+async with jaato.session(mode="ws", url="wss://host:8080", token="...",
+                         presentation={"client_type": "chat",
+                                       "content_width": 72,
+                                       "supports_tables": False}) as s:
+    print(await s.ask("Summarize the incident."))
+```
+
+## Building a Custom Client
+
+Everything you need to drive the server yourself:
+
+```python
+from jaato_sdk import IPCClient
+from jaato_sdk.events import (
+    # Server → Client
+    ConnectedEvent,
+    AgentOutputEvent,
+    ToolCallStartEvent, ToolCallEndEvent, ToolOutputEvent,
+    PermissionRequestedEvent, PermissionInputModeEvent, PermissionResolvedEvent,
+    ClarificationRequestedEvent, ReferenceSelectionRequestedEvent,
+    PlanUpdatedEvent, PlanStepUpdatedEvent, PlanClearedEvent,
+    ContextUpdatedEvent, TurnCompletedEvent, TurnProgressEvent,
+    UsageBreakdown, GCConfigEvent,
+    SystemMessageEvent, ErrorEvent, RetryEvent, InitProgressEvent,
+    SessionInfoEvent, SessionListEvent, SessionProfilesEvent,
+
+    # Client → Server
+    SendMessageRequest, PermissionResponseRequest, ClarificationResponseRequest,
+    ReferenceSelectionResponseRequest, StopRequest, CommandRequest,
+    HistoryRequest, ClientConfigRequest, ToolDisableRequest,
+)
+```
+
+A reference TUI implementation lives at [`jaato-tui`](../jaato-tui/) in the same repo.
+
+## Low-Level API
+
+Every event is a serializable dataclass. If you need to bypass the client (for example, embedding the protocol in a different transport), you can drive serialization directly:
+
+```python
+from jaato_sdk.events import serialize_event, deserialize_event, SendMessageRequest
+
+wire = serialize_event(SendMessageRequest(text="hi"))   # → JSON string
+event = deserialize_event(wire)                          # → typed dataclass
+```
+
+Framing differs by transport:
+
+- **IPC** — each frame is a 4-byte big-endian length prefix followed by the JSON payload. Max message size is 10 MiB. The Unix-socket variant uses `asyncio.open_unix_connection`; on Windows the SDK uses `loop.create_pipe_connection` against `\\.\pipe\<name>`.
+- **WebSocket** — one event per WS text frame, no length prefix (WS frames itself). Authenticate with a bearer token on the upgrade request or via `?token=...`.
+
+## Tracing
+
+The SDK ships a small tracing helper that the server picks up via `JAATO_TRACE_LOG` and `PROVIDER_TRACE_LOG`:
+
+```python
+from jaato_sdk import trace, provider_trace, trace_write, resolve_trace_path
+```
+
+These write JSONL records to per-agent files under the configured trace directory. Useful for offline replay and debugging — leave them off in production unless you need them.
+
+## Requirements
+
+- Python 3.10+
+- A reachable jaato server (auto-started by default)
+- `python-dotenv` (the only runtime dependency)
+
+## License
+
+BUSL-1.1