@preapexis/piexis 0.2.2 → 0.2.4

package/skills/claude-api/shared/managed-agents-environments.md

@@ -1,226 +0,0 @@
-# Managed Agents - Environments & Resources
-
-## Environments
-
-Creating a session requires an `environment_id`. Environments are **reusable configuration templates** for spinning up containers in Anthropic's infrastructure - you might create different environments for different use cases (e.g. data visualization vs web development, with different package sets). Anthropic handles scaling, container lifecycle, and work orchestration.
-
-**Environment names must be unique.** Creating an environment with an existing name returns 409.
-
-### Networking
-
-| Network Policy   | Description                                                   |
-| ---------------- | ------------------------------------------------------------- |
-| `unrestricted`   | Full egress (except legal blocklist)                          |
-| `limited`        | Deny-by-default; opt in via `allowed_hosts` / `allow_package_managers` / `allow_mcp_servers` |
-
-```json
-{
-  "networking": {
-    "type": "limited",
-    "allow_package_managers": true,
-    "allow_mcp_servers": true,
-    "allowed_hosts": ["api.example.com"]
-  }
-}
-```
-
-All three `limited` fields are optional. `allow_package_managers` (default `false`) permits PyPI/npm/etc.; `allow_mcp_servers` (default `false`) permits the agent's configured MCP server endpoints without listing them in `allowed_hosts`.
-
-**MCP caveat:** Under `limited` networking, either set `allow_mcp_servers: true` or add each MCP server domain to `allowed_hosts`. Otherwise the container can't reach them and tools silently fail.
-
-**Packages caveat:** Under `limited` networking, `packages` requires `allow_package_managers: true`; otherwise the request fails with a 400. Listing the registry in `allowed_hosts` is not enough.
-
-**`networking` does not govern `web_search` / `web_fetch`.** Those tools run on Anthropic's servers (in cloud *and* self-hosted environments), so `limited` egress and `allowed_hosts` don't restrict them. To restrict the sites they can reach, set `allowed_domains` / `blocked_domains` on the tool's `configs` entry in the agent toolset - see `shared/managed-agents-tools.md` § Web search & web fetch settings.
-
-### Creating an environment
-
-The SDK adds `managed-agents-2026-04-01` automatically. TypeScript:
-
-```ts
-const env = await client.beta.environments.create({
-  name: "my_env",
-  config: {
-    type: "cloud",
-    networking: { type: "unrestricted" },
-  },
-});
-```
-
-### Self-hosted sandboxes
-
-To run tool execution in **your own infrastructure** instead of Anthropic's, set `config: {type: "self_hosted"}` - the agent loop stays on Anthropic's side, but `bash` / file ops / code execute in a container you control via an outbound-polling worker. The `networking` block does not apply (you control egress). Resource mounting (`file`, `github_repository`) and memory stores behave differently - see `shared/managed-agents-self-hosted-sandboxes.md` for the worker, credentials, and cloud-vs-self-hosted comparison.
-
-### Environment CRUD
-
-| Operation        | Method   | Path                                       | Notes |
-| ---------------- | -------- | ------------------------------------------ | ----- |
-| Create           | `POST`   | `/v1/environments`                         | |
-| List             | `GET`    | `/v1/environments`                         | Paginated (`limit`, `after_id`, `before_id`) |
-| Get              | `GET`    | `/v1/environments/{id}`                    | |
-| Update           | `POST`   | `/v1/environments/{id}`                    | Changes apply only to **new** containers; existing sessions keep their original config |
-| Delete           | `DELETE` | `/v1/environments/{id}`                    | Returns 204. |
-| Archive          | `POST`   | `/v1/environments/{id}/archive`            | Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive - terminal state. |
-
----
-
-## Resources
-
-Attach files, GitHub repositories, and memory stores to a session. Resources are resolved during session creation, so a bad `file_id` or an unreachable repo surfaces on the create call rather than mid-run. Creating a session does **not** by itself start work or provision the sandbox - without `initial_events` the session is only registered, and the sandbox comes up when the session first needs it (see `shared/managed-agents-core.md` -> Seeding a session with `initial_events`). Max **999 file resources** per session. Multiple GitHub repositories per session are supported. For `type: "memory_store"` resources (persistent cross-session memory - max 8 per session), see `shared/managed-agents-memory.md`.
-
-### File Uploads (input - host -> agent)
-
-Upload a file first via the Files API, then reference by `file_id` + `mount_path`:
-
-```ts
-// 1. Upload
-const file = await client.beta.files.upload({
-  file: fs.createReadStream("data.csv"),
-  purpose: "agent",
-});
-
-// 2. Attach as a session resource
-const session = await client.beta.sessions.create({
-  agent: agent.id,
-  environment_id: envId,
-  resources: [
-    { type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }
-  ],
-});
-```
-
-**`mount_path` is required** and must be absolute. Parent directories are created automatically. Agent working directory defaults to `/workspace`. Files are mounted read-only - the agent writes modified versions to new paths.
-
-### Session outputs (output - agent -> host)
-
-The agent can write files to `/mnt/session/outputs/` during a session. These are automatically captured by the Files API and can be listed and downloaded afterwards:
-
-```ts
-// After the turn completes, list output files scoped to this session:
-for await (const f of client.beta.files.list({
-  scope_id: session.id,
-  betas: ["managed-agents-2026-04-01"],
-})) {
-  console.log(f.filename, f.size_bytes);
-  const resp = await client.beta.files.download(f.id);
-  const text = await resp.text();
-}
-```
-
-**Requirements:**
-- The `write` tool (or `bash`) must be enabled for the agent to create output files.
-- Session-scoped `files.list` / `files.download` captures outputs written to `/mnt/session/outputs/`.
-- The filter parameter is **`scope_id`** (REST query param `?scope_id=<session_id>`). The SDK's files resource auto-adds only the `files-api-2025-04-14` header, so pass `betas: ["managed-agents-2026-04-01"]` explicitly (or both headers on raw HTTP) - without it the API may reject `scope_id` as an unknown field. Requires `@anthropic-ai/sdk` >= 0.88.0 / `anthropic` (Python) >= 0.92.0 - older versions don't type `scope_id`. The `ant` CLI does **not** expose this flag yet; use the SDK or curl.
-- Pass the session ID returned by `sessions.create()` verbatim (e.g. `sesn_011CZx...`) - the API validates the prefix.
-- There's a brief indexing lag (~1-3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if empty.
-
-> **Fallback when `scope_id` filtering is unavailable** (older SDK, or endpoint returns an error): send a follow-up `user.message` asking the agent to `read` each file under `/mnt/session/outputs/` and return the contents. The agent streams the file bodies back as `agent.message` text. This works for text files only and costs output tokens - use it to unblock, not as the primary path.
-
-This gives you a bidirectional file bridge: upload reference data in, download agent artifacts out.
-
-### GitHub Repositories
-
-Clones a GitHub repository into the session container during initialization, before the agent begins execution. The agent can read, edit, commit, and push via `bash` (`git`). Multiple repositories per session are supported - add one `resources` entry per repo. Repositories are cached, so future sessions that use the same repository start faster.
-
-Mounting a repository also loads any skills stored in its root `.claude/skills` directory - discovered once per session, from the repository state checked out at session start (cloud sandboxes only). See `shared/managed-agents-tools.md` -> Skills from a GitHub repository.
-
-Repositories are attached for the lifetime of the session - to change which repositories are mounted, create a new session. You **can** rotate a repository's `authorization_token` on a running session via `client.beta.sessions.resources.update(resource_id, {session_id, authorization_token})`; the resource `id` is returned at session creation and by `resources.list()`.
-
-**Fields:**
-
-| Field | Required | Notes |
-|---|---|---|
-| `type` | Yes | `"github_repository"` |
-| `url` | Yes | The GitHub repository URL |
-| `authorization_token` | Yes | GitHub Personal Access Token with repository access. **Never echoed in API responses.** |
-| `mount_path` | No | Path where the repository will be cloned. Defaults to `/workspace/<repo-name>`. |
-| `checkout` | No | `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Defaults to the repo's default branch. |
-
-**Token permission levels** (fine-grained PATs):
-- `Contents: Read` - clone only
-- `Contents: Read and write` - push changes and create pull requests
-
-**How auth works:** `authorization_token` is never placed inside the container. `git pull` / `git push` and GitHub REST calls against the attached repository are routed through an Anthropic-side git proxy that injects the token after the request leaves the sandbox. Code running in the container - including anything the agent writes - cannot read or exfiltrate it.
-
-> Important: **To generate pull requests** you also need GitHub **MCP server** access - the `github_repository` resource gives filesystem + git access only. See `shared/managed-agents-tools.md` -> MCP Servers. The PR workflow is: edit files in the mounted repo -> push branch via `bash` (authenticated via the git proxy using `authorization_token`) -> create PR via the MCP `create_pull_request` tool (authenticated via the vault).
-
-**TypeScript:**
-
-```ts
-// 1. Create the agent - declare GitHub MCP (no auth here)
-const agent = await client.beta.agents.create(
-  {
-    name: 'GitHub Agent',
-    model: 'claude-opus-5',
-    mcp_servers: [
-      { type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' },
-    ],
-    tools: [
-      { type: 'agent_toolset_20260401', default_config: { enabled: true } },
-      { type: 'mcp_toolset', mcp_server_name: 'github' },
-    ],
-  },
-);
-
-// 2. Start a session - attach vault for MCP auth + mount the repo
-const session = await client.beta.sessions.create({
-  agent: agent.id,
-  environment_id: envId,
-  vault_ids: [vaultId],  // vault contains the GitHub MCP OAuth credential
-  resources: [
-    {
-      type: 'github_repository',
-      url: 'https://github.com/owner/repo',
-      authorization_token: process.env.GITHUB_TOKEN,  // repo clone token (!= MCP auth)
-      checkout: { type: 'branch', name: 'main' },
-    },
-  ],
-});
-```
-
-**Python:**
-
-```python
-import os
-
-agent = client.beta.agents.create(
-    name="GitHub Agent",
-    model="claude-opus-5",
-    mcp_servers=[{
-        "type": "url",
-        "name": "github",
-        "url": "https://api.githubcopilot.com/mcp/",
-    }],
-    tools=[
-        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
-        {"type": "mcp_toolset", "mcp_server_name": "github"},
-    ],
-)
-
-session = client.beta.sessions.create(
-    agent=agent.id,
-    environment_id=env_id,
-    vault_ids=[vault_id],  # vault contains the GitHub MCP OAuth credential
-    resources=[{
-        "type": "github_repository",
-        "url": "https://github.com/owner/repo",
-        "authorization_token": os.environ["GITHUB_TOKEN"],  # repo clone token (!= MCP auth)
-        "checkout": {"type": "branch", "name": "main"},
-    }],
-)
-```
-
----
-
-## Files API
-
-Upload and manage files for use as session resources, and download files the agent wrote to `/mnt/session/outputs/`.
-
-| Operation        | Method   | Path                                  | SDK |
-| ---------------- | -------- | ------------------------------------- | --- |
-| Upload           | `POST`   | `/v1/files`                           | `client.beta.files.upload({ file })` |
-| List             | `GET`    | `/v1/files?scope_id=...`              | `client.beta.files.list({ scope_id, betas: ["managed-agents-2026-04-01"] })` |
-| Get Metadata     | `GET`    | `/v1/files/{id}`                      | `client.beta.files.retrieveMetadata(id)` |
-| Download         | `GET`    | `/v1/files/{id}/content`              | `client.beta.files.download(id)` -> `Response` |
-| Delete           | `DELETE` | `/v1/files/{id}`                      | `client.beta.files.delete(id)` |
-
-The `scope_id` filter on List scopes the results to files written to `/mnt/session/outputs/` by that session. Without the filter, you get all files uploaded to your account.

package/skills/claude-api/shared/managed-agents-events.md

@@ -1,290 +0,0 @@
-# Managed Agents - Events & Steering
-
-## Events
-
-### Sending Events
-
-Send events to a session via `POST /v1/sessions/{id}/events`.
-
-| Event Type                | When to Send                                        |
-| ------------------------- | --------------------------------------------------- |
-| `user.message`            | Send a user message |
-| `user.interrupt`          | Interrupt the agent while it's running |
-| `user.tool_confirmation`  | Approve/deny a tool call that paused for approval (`always_ask`, or `auto` when the server reached no determination) |
-| `user.custom_tool_result` | Provide result for a custom tool call |
-| `user.define_outcome`     | Start a rubric-graded iterate loop - see `shared/managed-agents-outcomes.md` |
-| `system.message`          | Append privileged system-level context for this turn and every turn after it; see § Adding system context mid-session |
-
-#### Adding system context mid-session (`system.message`)
-
-The `system` field on the agent definition sets the top-level system prompt and is fixed for the session's lifetime. A `system.message` event **appends** to the session's system context as a `role: "system"` turn - it does not replace that prompt. The content applies to the accompanying turn and all subsequent turns. Use it for a different persona, revised constraints, or runtime-fetched context that should shape behavior going forward:
-
-```python
-client.beta.sessions.events.send(
-    session.id,
-    events=[
-        {
-            "type": "system.message",
-            "content": [
-                {"type": "text", "text": "The user's current timezone is America/New_York."},
-            ],
-        },
-    ],
-)
-```
-
-Constraints:
-
-- **Model-gated: Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5.1, and Claude Mythos 5.1.** Only the agent's **primary** model is checked - `system.message` lands on the primary thread only, so subagent models are not considered. On an unsupported primary model the event is rejected with a `model_does_not_support_mid_conversation_system` validation error.
-- **While the session is idle with `stop_reason: requires_action`** (blocked on `user.custom_tool_result` / `user.tool_confirmation`), a `system.message` is accepted **only when it trails a tool result event in the same request**. Sent on its own - or alongside a `user.message` - it is rejected until the pending tool events are resolved.
-- `content` accepts 1-1000 text items.
-
-### Receiving Events
-
-Three methods:
-
-1. **Streaming (SSE)**: `GET /v1/sessions/{id}/events/stream` - real-time Server-Sent Events. **Long-lived** - the server sends periodic heartbeats to keep the connection alive.
-2. **Polling**: `GET /v1/sessions/{id}/events` - paginated event list (query params: `limit` default 1000, `page`). **Returns immediately** - this is a plain paginated GET, not a long-poll.
-3. **Webhooks**: Anthropic POSTs session state transitions to your HTTPS endpoint - thin payloads (IDs only), HMAC-signed, Console-registered. See `shared/managed-agents-webhooks.md`.
-
-**No-code inspection - the Console session viewer** (Console sidebar -> **Managed Agents** -> **Sessions**; Developers and Admins only). Point users here for debugging before they parse the stream themselves: a session list (ID, name, status, agent, tokens in/out, cost; filter by status/created, search by ID); a **timeline minimap** with one lane per thread in multiagent sessions; the **transcript** grouped by model request (thinking, tool calls with inputs/results, streaming text) with a **Filter events** box (matches ID, type, tool name, or text; Enter steps between matches) and copy/download-as-JSON (filtered export when a filter is active); and an **Inspector** side panel (toggle with `d`) with five tabs - **Session** (details, metadata, cumulative-cost chart vs. budget), **Events** (raw events in server order, JSON per event, plus a **Deltas** view for messages that streamed while the page was open), **Tools** (every configured tool with call counts, failures, median duration; jump to any call), **Resources** (mounted files, repos, memory stores with per-session memory changes, `/mnt/session/outputs` files, skills under `/workspace/skills`), **Threads** (status, context size, cost per thread; context-size chart for the current thread; switch threads). Deep-link with `?event={event_id}` on the session URL - handy to include in error reports alongside the Console link from `shared/managed-agents-core.md`.
-
-All **persisted** events carry `id`, `type`, and `processed_at` (ISO 8601), set when the event finishes processing. On events you send, `processed_at` is `null` while the event is still queued behind earlier ones - **except** `user.define_outcome`, `user.custom_tool_result`, and `user.tool_result`, which are processed on receipt and echoed back with `processed_at` already populated. The stream-only `event_start` / `event_delta` preview events (see § Live previews) carry only the `id` of the event they preview.
-
-> Warning: **Robust polling (raw HTTP).** If you bypass the SDK and roll your own poll loop, don't rely on `requests` or `httpx` timeouts as wall-clock caps - they're **per-chunk** read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even with `timeout=(5, 60)` or `httpx.Timeout(120)`. Neither library has a "total wall-clock" timeout built in. For a hard deadline: track `time.monotonic()` at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, or `asyncio.wait_for()` around async httpx). **Prefer the SDK** - `client.beta.sessions.events.stream()` and `client.beta.sessions.events.list()` handle timeout + retry sanely.
->
-> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events/stream` by mistake or a server-side stall - report it; don't treat it as a client-config problem.
-
-### Event Types (Received)
-
-Event types use dot notation, grouped by namespace:
-
-| Event Type | Description |
-| --- | --- |
-| `agent.message` | Agent text output |
-| `agent.thinking` | Progress signal that the agent is thinking - it does **not** carry the thinking content |
-| `agent.tool_use` | Agent used a built-in tool (`agent_toolset_20260401`). Carries `evaluated_permission` (`allow`/`ask`/`deny`) and usually `evaluation` - see `shared/managed-agents-tools.md` § `evaluated_permission` and `evaluation` |
-| `agent.tool_result` | Result from a built-in tool |
-| `agent.mcp_tool_use` | Agent used an MCP tool. Carries `evaluated_permission` and usually `evaluation`, same as `agent.tool_use` |
-| `agent.mcp_tool_result` | Result from an MCP tool |
-| `agent.custom_tool_use` | Agent invoked a custom tool - session goes idle, you respond with `user.custom_tool_result` |
-| `agent.thread_context_compacted` | Conversation context was compacted |
-| `session.status_idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message`, blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`, or paused because the session budget cap was reached. The `stop_reason` attached contains more information about why the Agent has stopped working. |
-| `session.status_running` | Session has starting running, and the Agent is actively doing work. |
-| `session.status_rescheduled` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
-| `session.status_terminated` | Session ended and is irreversibly unusable - **on completion or on error**, not error-only. |
-| `session.updated` | A session update changed at least one field - carries only the changed fields (a budget removal carries `budget: null`) |
-| `session.usage` | Snapshot of the session's cumulative usage and tracked list cost - see § Reaching a session budget below |
-| `session.error` | Error occurred during processing |
-| `span.model_request_start` | Model inference started |
-| `span.model_request_end` | Model inference completed |
-| `span.outcome_evaluation_start` / `_ongoing` / `_end` | Grader progress for outcome-oriented sessions - see `shared/managed-agents-outcomes.md` |
-| `session.thread_created` | Subagent thread spawned (multiagent), or an advisor consultation started (thread name `anthropic.advisor`) - see `shared/managed-agents-multiagent.md` |
-| `session.thread_status_running` / `_idle` / `_rescheduled` / `_terminated` | Thread status transitions - mostly seen in multiagent sessions, but a single-agent session's primary thread also emits `_idle` when pausing at a session budget (§ Reaching a session budget). `_idle` carries `stop_reason`. |
-| `agent.thread_message_sent` / `_received` | Cross-thread message, carries `to_session_thread_id` / `from_session_thread_id` (multiagent) |
-
-The stream also echoes back user-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.tool_result`, `user.custom_tool_result`, `user.define_outcome`) - except a `user.interrupt` sent while the session is paused at its budget, which is accepted and ignored and never appears (§ Reaching a session budget).
-
-Stream-only delta preview events (`event_start`, `event_delta`) are the one exception to the `{domain}.{action}` naming convention - see § Live previews below; they never appear in `GET /v1/sessions/{id}/events`.
-
----
-
-## Live previews
-
-By default, assistant text reaches the stream as buffered `agent.message` events - emitted only after the model request that produced them finishes. **Live previews** let you render that text incrementally while the model is still generating. The buffered `agent.message` is always the authoritative record; a client that ignores previews still receives a complete, correct stream. The wire format is **not** Messages-API streaming: the delta type is `content_delta`, not `content_block_delta`, so Messages-API accumulator code does not carry over unchanged.
-
-**Opt in per stream connection** by adding the `event_deltas[]` query parameter, repeated once per event type to preview. Accepted values: `agent.message`, `agent.thinking` - any other value returns a 400, as does a request with more than 100 values. **Both stream endpoints accept it:** the session-level stream (`GET /v1/sessions/{id}/events/stream`) and each session thread's own stream (`GET /v1/sessions/{sid}/threads/{tid}/stream`). In a shell, quote the URL or percent-encode the brackets as `%5B%5D` - bare `[]` is a glob pattern.
-
-**Previews are thread-scoped.** A connection previews only the thread it is reading. A child thread's previews are delivered on that child's stream and are *never* cross-posted to the session-level stream, whose previews stay scoped to the primary thread. To watch a subagent's text as the model generates it, open that subagent's thread stream - see `shared/managed-agents-multiagent.md`. Run one accumulator instance per connection.
-
-```python
-stream = client.beta.sessions.events.stream(
-    session_id=session.id,
-    event_deltas=["agent.message"],
-)
-```
-
-When a previewed event begins, the stream emits an `event_start` carrying the upcoming event's `type` and `id`; for `agent.message` it's followed by `event_delta` events carrying incremental text:
-
-```json
-{"type": "event_start", "event": {"type": "agent.message", "id": "sevt_01abc..."}}
-{"type": "event_delta", "event_id": "sevt_01abc...", "delta": {"type": "content_delta", "index": 0, "content": {"type": "text", "text": "Here is the summary"}}}
-```
-
-`event_start` and `event_delta` have no `id` or `processed_at` of their own - the only identifier they carry is the `id` of the event they preview. For `agent.thinking`, **only** the `event_start` is emitted (a "thinking has started" signal) - no deltas follow, and the buffered `agent.thinking` that concludes the preview carries no thinking content either. It is a progress signal, not a content carrier; there is nothing to read out of it.
-
-**Accumulate-and-reconcile pattern.** Treat the preview as a scratch buffer keyed by `(event_id, index)`. On `event_start`, create an empty entry for the announced `id`. On each `event_delta`, append `delta.content.text` to `(event_id, delta.index)` and render the running text. When the buffered `agent.message` arrives, match it by `id`, **discard the accumulated preview**, and render the message's content instead. The identifiers always line up: `event_start.event.id`, every `event_delta.event_id`, and the buffered event's `id` are the same value. On a normal turn the order is fixed: `session.status_running` -> `span.model_request_start` -> `event_start` -> `event_delta`* -> buffered `agent.message` -> `span.model_request_end`. If the turn errors or is interrupted the buffered event may never arrive, but `span.model_request_end` still does - close any unreconciled preview when you see it. Python/TypeScript/Go SDKs ship an accumulator helper that implements this; in other SDKs apply the manual pattern to the generated event types.
-
-**Two guarantees the pattern relies on:** concatenating a preview's deltas in arrival order, keyed by `(event_id, index)`, yields a *prefix* of `content[index].text` in the buffered event (a prefix, not necessarily the whole text - deltas may be shed under load); and a connection emits at most one `event_start` per `event_id`, with the buffered event as the last thing that connection delivers for that `id`.
-
-**Limitations:**
-- **Best effort** - under load the server may shed deltas for an event; you receive a contiguous prefix and then no further deltas for that event. The buffered `agent.message` still arrives complete. Never treat an accumulated preview as final.
-- **No replay on reconnect** - deltas are delivered only to the connection that opted in, while it's open; this holds for the session-level stream and each thread stream alike. A connection opened after a model request started receives no deltas for that in-flight event. After a drop, follow the consolidation pattern in § Reconnecting after a dropped stream - the history fetch returns any buffered events emitted during the gap; missed deltas cannot be re-requested.
-- **One thread, text only** - previews cover assistant text on the thread the connection is reading. Tool use, tool results, MCP results, and activity on any *other* thread are never previewed on that connection.
-- **Never persisted** - `event_start` / `event_delta` exist only on the live SSE stream, never in `GET /v1/sessions/{id}/events` or any thread's event history.
-
-**Troubleshooting:**
-
-| You see | What it means |
-| --- | --- |
-| Buffered events but no `event_start` / `event_delta` | This connection didn't opt in (`event_deltas[]` is per connection, not per session), or the turn ran on a different thread. List `GET /v1/sessions/{sid}/threads` to find which one ran. |
-| 404 on the stream URL | Wrong path or ID, or the request carries no managed-agents beta header - the thread endpoints are beta-gated, so without it they don't exist. The thread path is `/threads/{tid}/stream`, **not** `/threads/{tid}/events/stream` (which doesn't exist) and not `/events/stream` (session level only). |
-| 400 naming `event_deltas` | Only `agent.message` and `agent.thinking` are accepted, max 100 values. |
-
----
-
-## Steering Patterns
-
-Practical patterns for driving a session via the events surface.
-
-### Stream-first ordering
-
-**Open the stream before sending events.** The stream only delivers events that occur *after* it's opened - it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time.
-
-```ts
-// Correct - stream and send concurrently
-const [response] = await Promise.all([
-  streamEvents(sessionId),   // opens SSE connection
-  sendMessage(sessionId, text),
-]);
-
-// Wrong - events before stream opens arrive as a single buffered batch
-await sendMessage(sessionId, text);
-const response = await streamEvents(sessionId);
-```
-
-**For full history,** use `GET /v1/sessions/{id}/events` (paginated list) - the stream only gives you live events from connection onward.
-
-### Reconnecting after a dropped stream
-
-**The SSE stream has no replay.** If your connection drops (httpx read timeout, network blip) and you reconnect, you only get events emitted *after* reconnection. Any events emitted during the gap are lost from the stream.
-
-**The consolidation pattern:** on every (re)connect, overlap the stream with a history fetch and dedupe by event ID:
-
-```python
-def connect_with_consolidation(client, session_id):
-    # 1. Open the SSE stream first
-    stream = client.beta.sessions.events.stream(session_id=session_id)
-
-    # 2. Fetch history to cover any gap
-    history = client.beta.sessions.events.list(
-        session_id=session_id,
-    )
-
-    # 3. Yield history first, then stream - dedupe by event.id
-    seen = set()
-    for ev in history.data:
-        seen.add(ev.id)
-        yield ev
-    for ev in stream:
-        if ev.id not in seen:
-            seen.add(ev.id)
-            yield ev
-```
-
-### Message queuing
-
-**You don't have to wait for a response before sending the next message.** User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups:
-
-```ts
-// All three go into one session; agent processes them in order
-await sendMessage(sessionId, "Summarize the README");
-await sendMessage(sessionId, "Actually also check the CONTRIBUTING guide");
-await sendMessage(sessionId, "And compare the two");
-// Stream once - agent responds to all three as a coherent turn
-```
-
-Events can be sent up to the Session at any time. There is no need to wait on a specific session status to enqueue new events via `client.beta.sessions.events.send()`. One exception: a session paused at its budget (`stop_reason: budget_reached`) accepts only settle events - a `user.message` there is a 400. See § Reaching a session budget.
-
-### Interrupt
-
-A `user.interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. Exception: while the session is paused at its budget, an interrupt is accepted and ignored - it is never persisted and changes nothing (§ Reaching a session budget). Use this for "stop" / "nevermind" / "cancel" commands:
-
-```ts
-await client.beta.sessions.events.send(sessionId, {
-  events: [{ type: 'user.interrupt' }],
-});
-```
-
-The agent stops mid-task. It does not see the interrupt as a message - it just halts. Send a follow-up `user` event to explain what to do instead. If an outcome is active, the interrupt also marks `span.outcome_evaluation_end.result: "interrupted"` (see `shared/managed-agents-outcomes.md`) - though not at a budget pause, where the interrupt is accepted and ignored (see § Reaching a session budget).
-
-**The interrupted turn ends with `stop_reason: end_turn`** - the same value a turn that finishes on its own carries. There is no interruption-specific stop reason, so a drain loop can't distinguish the two from `stop_reason` alone; track that you sent the interrupt.
-
-**Against an already-`idle` session an interrupt is normally a no-op.** The exception is a session on a self-hosted environment whose worker failed the claimed work item (a memory-store mount error, for instance): it sits `idle` with `stop_reason: requires_action` and no error event, and `user.interrupt` re-queues the work for the next worker claim (`shared/managed-agents-self-hosted-sandboxes.md` § Memory stores -> Troubleshooting).
-
-**In a multiagent session, omitting `session_thread_id` interrupts every non-archived thread, including the primary** - it is not primary-only. Pass `session_thread_id` to stop one thread. See `shared/managed-agents-multiagent.md`.
-
-> **Note**: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the `processed_at` timestamp along with surrounding event IDs. (Not applicable to an interrupt sent at the budget cap - that event is never persisted, so there is nothing to locate.)
-
-### Reaching a session budget
-
-A session created with a budget (see `shared/managed-agents-core.md` § Session budgets) pauses instead of overspending. Before every model request the platform checks whether consumed list cost has reached the cap and pauses the thread if it has, and the session goes idle with `stop_reason: budget_reached` rather than terminating. On the stream, the pause arrives as three events, in order:
-
-1. `session.thread_status_idle` with `stop_reason: budget_reached`, for each thread as it pauses. When a thread's final request both crosses the cap and finishes its turn, that thread reports `stop_reason: end_turn` while the session still reports `budget_reached` - key on the **session-level** `stop_reason`, not thread-level ones, to detect the pause.
-2. `session.usage` - a snapshot of the session's cumulative usage and tracked list cost.
-3. `session.status_idle` with `stop_reason: budget_reached`. The `session.usage` event always immediately precedes this idle.
-
-While at the cap the session accepts **only settle events** (`user.tool_confirmation`, `user.tool_result`, `user.custom_tool_result`, `user.interrupt`); anything that starts new work, including `user.message`, is a 400 naming that list. A `user.interrupt` sent while the session is paused at its budget (all threads paused at the cap) is accepted and ignored: it does not appear in the event list and changes nothing. Raise or remove the budget to continue. When one thread waits on a tool ask and another is paused at the cap, the session-level `stop_reason` is `requires_action`, not `budget_reached` - settling the ask doesn't trigger a model request, so respond as usual.
-
-**No event resumes a session paused at its cap.** Update the session's budget instead: change it to a value above the consumed list cost (higher or lower than the old cap), or remove it with `"budget": null`. An accepted update resumes the paused work automatically.
-
-**`session.usage`** carries the session's cumulative token totals, `list_cost` (`{amount, currency}`, rounded to the nearest cent), `active_seconds` (concurrent-thread overlap counted once - the figure runtime cost is priced on), `server_tool_use` counts (`web_search_requests`, and `web_fetch_requests` - informational, currently always 0 since web fetch is not metered), and an echo of the session's `budget` when one is set. It appears in the events list and the session stream - a stream reader sees the final cost of the work that hit the cap without an extra fetch; child threads' own streams do not carry it. The same totals live on the session object's `usage` field, and each thread's own `usage` carries per-thread `list_cost` and `active_seconds` - but per-thread costs do **not** sum to the session total: the session figure additionally includes session running time and each figure is rounded independently, so the session figure is the authoritative one. To enforce a spend limit, set a budget rather than polling usage and interrupting the session yourself - the platform's gate runs before each model request.
-
-### Event payloads
-
-some events carry useful metadata beyond the status change itself:
-
-`session.status_idle` - includes a `stop_reason` field which elaborates on why the session stopped and what type of further action is required by the user.
-```json
-{
-  "id": "sevt_456",
-  "processed_at": "2026-04-07T04:27:43.197Z",
-  "stop_reason": {
-    "event_ids": [
-      "sevt_123"
-    ],
-    "type": "requires_action"
-  },
-  "type": "status_idle"
-}
-```
-
-`span.model_request_end` contains a `model_usage` field for cost tracking and efficiency analysis:
-
-```json
-{
-  "type": "span.model_request_end",
-  "id": "sevt_456",
-  "is_error": false,
-  "model_request_start_id": "sevt_123",
-  "model_usage": {
-    "cache_creation_input_tokens": 0,
-    "cache_read_input_tokens": 6656,
-    "input_tokens": 3571,
-    "output_tokens": 727
-  },
-  "processed_at": "2026-04-07T04:11:32.189Z"
-}
-```
-
-**`agent.thread_context_compacted`** - emitted when the conversation history was summarized to fit context. Includes `pre_compaction_tokens` so you know how much was squeezed:
-
-```json
-{
-  "id": "sevt_abc123",
-  "processed_at": "2026-03-24T14:05:15.787Z",
-  "type": "agent.thread_context_compacted"
-}
-```
-
-### Archive
-
-When done with a session, archive it to free resources:
-
-```ts
-await client.beta.sessions.archive(sessionId);
-```
-
-> Archiving a **session** is routine cleanup - sessions are per-run and disposable. **Do not generalize this to agents or environments**: those are persistent, reusable resources, and archiving them is permanent (no unarchive; new sessions cannot reference them). See `shared/managed-agents-overview.md` -> Common Pitfalls.
-
-