anymous 1.3.0 → 1.3.2

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

@@ -1,219 +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.
-
-### 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"),
-});
-
-// 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.
-
-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` | ✅ | `"github_repository"` |
-| `url` | ✅ | The GitHub repository URL |
-| `authorization_token` | ✅ | GitHub Personal Access Token with repository access. **Never echoed in API responses.** |
-| `mount_path` | ❌ | Path where the repository will be cloned. Defaults to `/workspace/<repo-name>`. |
-| `checkout` | ❌ | `{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.
-
-> ‼️ **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,270 +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 (when `always_ask` policy) |
-| `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, and Claude Mythos 5.** 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`.
-
-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.
-
-> ⚠️ **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`) |
-| `agent.tool_result` | Result from a built-in tool |
-| `agent.mcp_tool_use` | Agent used an MCP tool |
-| `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` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. 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.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) — see `shared/managed-agents-multiagent.md` |
-| `session.thread_status_running` / `_idle` / `_rescheduled` / `_terminated` | Subagent thread status transitions (multiagent). `_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.custom_tool_result`, `user.define_outcome`).
-
-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()`
-
-### Interrupt
-
-A `user.interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. 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`).
-
-**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.
-
-**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.
-
-### 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.
-
-