feat!: sandbox images for AgentCore and Lambda MicroVM; per-session agent, SSE keepalive fix, session_id-keyed store

CHANGELOG.md

@@ -16,6 +16,11 @@ Every call the SDK makes now matches a route the CAS egress proxy serves (plan
   (`Healthy` / `HealthyBusy`) and `POST /invocations` (relay envelope v1,
   dispatched in-process; streamed answers keep the `: ca-relay` head frame).
   One image covers Lambda MicroVM and AgentCore (`computeragent.server.relay`).
+  CAS can close an abandoned relayed stream: the `x-ca-relay-stream` envelope
+  header (a UUID v4) is stripped before dispatch and `DELETE /_relay/streams/<id>`
+  closes that answer (relayed 204, unknown id 404). A JSON envelope over
+  AgentCore's 100 MiB cap becomes a relayed 502 `AGENTCORE_RESPONSE_TOO_LARGE`.
+  The relay logs `relay.instance id=…` once, and stream open/close with the id only.
 - **The app server for stage images** (`computeragent.server`, extra `server`).
   `python -m computeragent.server` serves CAS's harness REST API on `0.0.0.0:8080`:
   - the Lambda MicroVM lifecycle hooks, health, sessions, messages, events,
@@ -33,7 +38,7 @@ Every call the SDK makes now matches a route the CAS egress proxy serves (plan
   expiry, on a request sent with the newest token) makes every later egress
   request carry the new token: the agent-document read, the guardrails checks,
   gitagent's Anthropic/OpenAI clients and injected httpx clients.
-  `Settings.api_key()` returns the newest token and `LYZR_API_KEY` is updated
+  `Settings.api_key()` returns the newest token and `COMPUTER_AGENT_EGRESS_PROXY_SECRET` is updated
   (`computeragent.harness.egress_token`).
 - **A loopback forwarder for the Claude CLI.** On the `claude-agent-sdk` engine
   the CLI's `ANTHROPIC_BASE_URL` and MCP server URLs on an egress origin point at
@@ -46,19 +51,53 @@ Every call the SDK makes now matches a route the CAS egress proxy serves (plan
   Span and log processors export 128 records at a time. The OTLP exporters set
   `x-api-key` on every request through a stamping `requests` session, so a
   reissued sandbox token applies to telemetry too.
-- **`COMPUTERAGENT_SESSION_STORE_URL` / `session_store_url`.** The base URL of
+- **`COMPUTER_AGENT_EGRESS_SESSION_STORE_URL` / `session_store_url`.** The base URL of
   the `http` session store behind the egress proxy
   (`http://egress/computer-agent-api`); it overrides a descriptor's `base_url`
   for kind `http` and is ignored for other kinds and store instances
   (`computeragent.session_stores.with_base_url`).
 
 ### Changed
 
+- **`session_id` keys the session store.** With `ComputerAgent(session_id=…,
+  session_store=…)`, every `append` and `load` carries that id instead of the
+  Claude CLI's per-process UUID (`project_key` and `subpath` are kept), and
+  the CLI runs under a UUID derived from it. A new process or sandbox with the
+  same `session_id` resumes the conversation on its first turn. The app server
+  builds each session with `session_id = sessionId`, so the `http` store is
+  keyed by the CAS session, which agentos expects (old-CAS plan 10). Without
+  `session_id` nothing changes.
+
+- **BREAKING: the settings' environment variables are renamed**, so the names
+  say what each one is; the constructor arguments are unchanged. No old name is
+  read any more:
+
+  | Argument | Was | Now |
+  |---|---|---|
+  | `agent_id` | `COMPUTERAGENT_AGENT_ID` | `COMPUTER_AGENT_ID` |
+  | `engine` | `COMPUTERAGENT_ENGINE` | `COMPUTER_AGENT_ENGINE` |
+  | `api_key` | `LYZR_API_KEY` | `COMPUTER_AGENT_EGRESS_PROXY_SECRET` |
+  | `base_url` | `COMPUTERAGENT_BASE_URL` | `COMPUTER_AGENT_EGRESS_API_URL` |
+  | `llm_url` | `COMPUTERAGENT_LLM_URL` | `COMPUTER_AGENT_EGRESS_LLM_URL` |
+  | `mcp_url` | `COMPUTERAGENT_MCP_URL` | `COMPUTER_AGENT_EGRESS_MCP_URL` |
+  | `guardrails_url` | `COMPUTERAGENT_GUARDRAILS_URL` | `COMPUTER_AGENT_EGRESS_GUARDRAILS_URL` |
+  | `telemetry_url` | `COMPUTERAGENT_TELEMETRY_URL` | `COMPUTER_AGENT_EGRESS_TELEMETRY_URL` |
+  | `session_store_url` | `COMPUTERAGENT_SESSION_STORE_URL` | `COMPUTER_AGENT_EGRESS_SESSION_STORE_URL` |
+  | `gap_dir` | `COMPUTERAGENT_GAP_DIR` | `COMPUTER_AGENT_GAP_DIR` |
+
+  Old CAS passes the same names in `POST /v1/sessions` `envs`: the app server
+  seeds `COMPUTER_AGENT_EGRESS_PROXY_SECRET` from it (the `LYZR_API_KEY` field
+  is no longer read), builds the session's agent from `COMPUTER_AGENT_ID`
+  (falling back to the image's own), and takes each
+  `COMPUTER_AGENT_EGRESS_*_URL` route the image's own environment or the agent
+  factory does not set. The engine's per-turn environment carries the token as
+  `COMPUTER_AGENT_EGRESS_PROXY_SECRET`.
+
 - **BREAKING: guardrails go through the egress proxy.** The user's message and
   every tool call are checked with `POST {guardrails_url}/v1/check` (ops
   `input` and `tool-input`); the agent gateway applies the org's and the
   agent's RAI policies and owns fail-open. `guardrails_url` /
-  `COMPUTERAGENT_GUARDRAILS_URL` is required and replaces `srs_url` /
+  `COMPUTER_AGENT_EGRESS_GUARDRAILS_URL` is required and replaces `srs_url` /
   `COMPUTERAGENT_SRS_URL` and `agent_api_url` / `COMPUTERAGENT_AGENT_API_URL`,
   which are no longer read.
 - A check that reaches no verdict (unreachable, 5 s timeout, non-2xx, a
@@ -69,9 +108,9 @@ Every call the SDK makes now matches a route the CAS egress proxy serves (plan
   policy input as `call_id`, and a call without one is denied.
 - A rewritten message carries the gateway's masked text (`[EMAIL]`).
 - **The Lyzr key is read at every turn.** The engine's `ANTHROPIC_API_KEY`,
-  `OPENAI_API_KEY` and `LYZR_API_KEY` and the bound MCP servers' `x-api-key`
+  `OPENAI_API_KEY` and `COMPUTER_AGENT_EGRESS_PROXY_SECRET` and the bound MCP servers' `x-api-key`
   are set from `Settings.api_key()` when each turn starts (and at boot), so a
-  key replaced in `LYZR_API_KEY` between turns, or a reissued token, is used
+  key replaced in `COMPUTER_AGENT_EGRESS_PROXY_SECRET` between turns, or a reissued token, is used
   by the next turn. A missing key fails the turn with `SettingsError` before
   the engine starts. `build_gateway_envs` no longer takes `api_key`;
   `key_envs(api_key)` returns the three variables.
@@ -84,18 +123,23 @@ Every call the SDK makes now matches a route the CAS egress proxy serves (plan
 - **BREAKING: MCP servers are addressed by name.** Each bound server is
   `{mcp_url}/{tool_name}` (one percent-encoded segment) with no query; the
   server id path and the `?tools=` query are gone, since the gateway resolves
-  both from its registry. Behind the egress proxy `COMPUTERAGENT_MCP_URL` is
+  both from its registry. Behind the egress proxy `COMPUTER_AGENT_EGRESS_MCP_URL` is
   `http://egress/mcp/v1`.
 - **BREAKING: the `http` session store sends only `x-api-key`.** The store
   token (`x-ca-session-store-token`), its refresh against `/v1/auth/token`, the
   `token` / `auto_refresh` arguments, `TOKEN_HEADER` and `expiry_of` are gone;
-  a `token` option is ignored. The key is `LYZR_API_KEY` at each request, as
+  a `token` option is ignored. The key is `COMPUTER_AGENT_EGRESS_PROXY_SECRET` at each request, as
   the newest sandbox token.
 - A session-store descriptor without a `kind` is reported by its keys, never
   its values.
 
 ### Removed
 
+- **`computeragent.agentos.policy_config_url` and `fetch_policy_binding`.** Nothing
+  in the SDK called them since 0.4.0, and AgentOS has dropped the
+  `ingest/policy-config/{name}` route they read (the agent gateway applies org
+  and agent policies), so a direct caller got a 404 that looked like "no policy".
+
 - **BREAKING: the SDK's own policy resolution.** No org RAI policies are read
   (`/v3/org/rai-policy`), the agent document's `rai_policy_id` is ignored and
   `ResolvedAgent.rai_policy_id` is gone, and no SRS route

README.md

@@ -11,16 +11,16 @@ permission mode — except the engine runs here.
 and telemetry are each reached at a URL you configure, with no direct path to any of them.
 
 ```bash
-export COMPUTERAGENT_AGENT_ID=6aa93f1b3817a13d3103d2c1
-export COMPUTERAGENT_ENGINE=claude-agent-sdk
-export COMPUTERAGENT_BASE_URL=http://egress/agentos/api     # agent config, MCP bindings
-export COMPUTERAGENT_GUARDRAILS_URL=http://egress/guardrails # guardrail checks
-export COMPUTERAGENT_LLM_URL=http://egress/llm              # every model call
-export COMPUTERAGENT_MCP_URL=http://egress/mcp/v1           # MCP servers bound in AgentOS
-export LYZR_API_KEY=...                                     # sent as x-api-key; swapped by the proxy
-# optional: COMPUTERAGENT_TELEMETRY_URL=http://egress/otlp (OTLP),
-#   COMPUTERAGENT_SESSION_STORE_URL=http://egress/computer-agent-api (http session store),
-#   COMPUTERAGENT_GAP_DIR (GAP mode)
+export COMPUTER_AGENT_ID=6aa93f1b3817a13d3103d2c1
+export COMPUTER_AGENT_ENGINE=claude-agent-sdk
+export COMPUTER_AGENT_EGRESS_API_URL=http://egress/computer-agent-api/agentos/api  # agent config, MCP bindings
+export COMPUTER_AGENT_EGRESS_GUARDRAILS_URL=http://egress/guardrails                # guardrail checks
+export COMPUTER_AGENT_EGRESS_LLM_URL=http://egress/llm                              # every model call
+export COMPUTER_AGENT_EGRESS_MCP_URL=http://egress/mcp/v1                           # MCP servers bound in AgentOS
+export COMPUTER_AGENT_EGRESS_PROXY_SECRET=...  # the sandbox token: sent as x-api-key, swapped by the proxy
+# optional: COMPUTER_AGENT_EGRESS_TELEMETRY_URL=http://egress/otlp (OTLP),
+#   COMPUTER_AGENT_EGRESS_SESSION_STORE_URL=http://egress/computer-agent-api (http session store),
+#   COMPUTER_AGENT_GAP_DIR (GAP mode)
 ```
 
 ```python
@@ -67,6 +67,10 @@ telemetry, `[gap]` for GAP mode, and `[server]` for the app server a stage image
 **[`docs/USING_THE_SDK.md`](docs/USING_THE_SDK.md)** is the developer reference: every setting and
 the requests made from it, the guardrail flow, MCP, session stores, errors and troubleshooting.
 
+**[`docs/DEPLOYING_ON_AGENTCORE_AND_MICROVM.md`](docs/DEPLOYING_ON_AGENTCORE_AND_MICROVM.md)** walks
+through integrating the SDK into an existing service, building a sandbox image with the app server,
+and registering it as a Lambda MicroVM image or an AgentCore runtime for an AgentOS agent.
+
 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) covers how the pieces fit together, for anyone
 changing the SDK rather than using it.