winter-super-cli 2026.6.22 → 2026.6.23

package/resources/local/claude/plugins/marketplaces/anthropic-agent-skills/skills/claude-api/shared/managed-agents-events.md

@@ -0,0 +1,189 @@
+# 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 |
+
+### Receiving Events
+
+Two 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.
+
+All received events carry `id`, `type`, and `processed_at` (ISO 8601; `null` if not yet processed by the agent).
+
+> ⚠️ **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` 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` | Extended thinking blocks |
+| `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 has terminated, entering an irreversible and unusable state.  |
+| `session.error` | Error occurred during processing |
+| `span.model_request_start` | Model inference started |
+| `span.model_request_end` | Model inference completed |
+
+The stream also echoes back user-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`).
+
+---
+
+## 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
+
+An `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: '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.
+
+> **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.
+
+

package/resources/local/claude/plugins/marketplaces/anthropic-agent-skills/skills/claude-api/shared/managed-agents-memory.md

@@ -0,0 +1,197 @@
+# Managed Agents — Memory Stores
+
+> **Public beta.** Memory stores ship under the `managed-agents-2026-04-01` beta header; the SDK sets it automatically on all `client.beta.memory_stores.*` calls. If `client.beta.memory_stores` is missing, upgrade to the latest SDK release.
+
+Sessions are ephemeral by default — when one ends, anything the agent learned is gone. A **memory store** is a workspace-scoped collection of small text documents that persists across sessions. When a store is attached to a session (via `resources[]`), it is mounted into the container as a filesystem directory; the agent reads and writes it with the ordinary file tools, and a system-prompt note tells it the mount is there.
+
+Every mutation to a memory produces an immutable **memory version** (`memver_...`), giving you an audit trail and point-in-time rollback/redact.
+
+## Object model
+
+| Object | ID prefix | Scope | Notes |
+| --- | --- | --- | --- |
+| Memory store | `memstore_...` | Workspace | Attach to sessions via `resources[]` |
+| Memory | `mem_...` | Store | One text file, addressed by `path` (≤ 100KB each — prefer many small files) |
+| Memory version | `memver_...` | Memory | Immutable snapshot per mutation; `operation` ∈ `created` / `modified` / `deleted` |
+
+## Create a store
+
+`description` is passed to the agent so it knows what the store contains — write it for the model, not for humans.
+
+```python
+store = client.beta.memory_stores.create(
+    name="User Preferences",
+    description="Per-user preferences and project context.",
+)
+print(store.id)  # memstore_01Hx...
+```
+
+Other SDKs: TypeScript `client.beta.memoryStores.create({...})`; Go `client.Beta.MemoryStores.New(ctx, ...)`. See `shared/managed-agents-api-reference.md` → SDK Method Reference for the full per-language table.
+
+Stores support `retrieve` / `update` / `list` (with `include_archived`, `created_at_{gte,lte}` filters) / `delete` / **`archive`**. Archive makes the store read-only — existing session attachments continue, new sessions cannot reference it; no unarchive.
+
+### Seed with content (optional)
+
+Pre-load reference material before any session runs. `memories.create` creates a memory at the given `path`; if a memory already exists there the call returns `409` (`memory_path_conflict_error`, with the `conflicting_memory_id`). The store ID is the first positional argument.
+
+```python
+client.beta.memory_stores.memories.create(
+    store.id,
+    path="/formatting_standards.md",
+    content="All reports use GAAP formatting. Dates are ISO-8601...",
+)
+```
+
+## Attach to a session
+
+Memory stores go in the session's `resources[]` array alongside `file` and `github_repository` resources (see `shared/managed-agents-environments.md` → Resources). Memory stores attach at **session create time only** — `sessions.resources.add()` does not accept `memory_store`.
+
+```python
+session = client.beta.sessions.create(
+    agent=agent.id,
+    environment_id=environment.id,
+    resources=[
+        {
+            "type": "memory_store",
+            "memory_store_id": store.id,
+            "access": "read_write",  # or "read_only"; default is "read_write"
+            "instructions": "User preferences and project context. Check before starting any task.",
+        }
+    ],
+)
+```
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `type` | ✅ | `"memory_store"` |
+| `memory_store_id` | ✅ | `memstore_...` |
+| `access` | — | `"read_write"` (default) or `"read_only"` — enforced at the filesystem level on the mount |
+| `instructions` | — | Session-specific guidance for this store, in addition to the store's `name`/`description`. ≤ 4,096 chars. |
+
+**Max 8 memory stores per session.** Attach multiple when different slices of memory have different owners or lifecycles — e.g. one read-only shared-reference store plus one read-write per-user store, or one store per end-user/team/project sharing a single agent config.
+
+### How the agent sees it (FUSE mount)
+
+Each attached store is mounted in the session container at `/mnt/memory/<store-name>/`. The agent interacts with it using the standard file tools (`bash`, `read`, `write`, `edit`, `glob`, `grep`) — there are no dedicated memory tools. `access: "read_only"` makes the mount read-only at the filesystem level; `"read_write"` allows the agent to create, edit, and delete files under it. A short description of each mount (name, path, `instructions`, access) is automatically injected into the system prompt so the agent knows the store exists without you having to mention it.
+
+Writes the agent makes under the mount are persisted back to the store and produce memory versions just like host-side `memories.update` calls.
+
+## Manage memories directly (host-side)
+
+Use these for review workflows, correcting bad memories, or seeding stores out-of-band.
+
+### List
+
+Returns `Memory | MemoryPrefix` entries — a `MemoryPrefix` (`type: "memory_prefix"`, just a `path`) is a directory-like node when listing hierarchically. Use `path_prefix` to scope (include a trailing slash: `"/notes/"` matches `/notes/a.md` but not `/notes_backup/old.md`) and `depth` to bound the tree walk. `order_by` / `order` sort the result. Pass `view="full"` to include `content` in each item; the default `"basic"` returns metadata only.
+
+```python
+for m in client.beta.memory_stores.memories.list(store.id, path_prefix="/"):
+    if m.type == "memory":
+        print(f"{m.path}  ({m.content_size_bytes} bytes, sha={m.content_sha256[:8]})")
+    else:  # "memory_prefix"
+        print(f"{m.path}/")
+```
+
+### Read
+
+```python
+mem = client.beta.memory_stores.memories.retrieve(memory_id, memory_store_id=store.id)
+print(mem.content)
+```
+
+`retrieve` defaults to `view="full"` (content included); `view` matters mainly on list endpoints.
+
+### Create vs. update
+
+| Operation | Addressed by | Semantics |
+| --- | --- | --- |
+| `memories.create(store_id, path=..., content=...)` | **Path** | Create at `path`. `409` (`memory_path_conflict_error`, includes `conflicting_memory_id`) if the path is already occupied. |
+| `memories.update(mem_id, memory_store_id=..., path=..., content=...)` | **`mem_...` ID** | Mutate existing memory. Change `content`, `path` (rename), or both. Renaming onto an occupied path returns the same `409 memory_path_conflict_error`. |
+
+```python
+mem = client.beta.memory_stores.memories.create(
+    store.id,
+    path="/preferences/formatting.md",
+    content="Always use tabs, not spaces.",
+)
+
+client.beta.memory_stores.memories.update(
+    mem.id,
+    memory_store_id=store.id,
+    path="/archive/2026_q1_formatting.md",  # rename
+)
+```
+
+### Optimistic concurrency (precondition on `update`)
+
+`memories.update` accepts a `precondition` so you can read → modify → write back without clobbering a concurrent writer. The only supported type is `content_sha256`. On mismatch the API returns `409` (`memory_precondition_failed_error`) — re-read and retry against fresh state.
+
+```python
+client.beta.memory_stores.memories.update(
+    mem.id,
+    memory_store_id=store.id,
+    content="CORRECTED: Always use 2-space indentation.",
+    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
+)
+```
+
+### Delete
+
+```python
+client.beta.memory_stores.memories.delete(mem.id, memory_store_id=store.id)
+```
+
+Pass `expected_content_sha256` for a conditional delete.
+
+## Audit and rollback — memory versions
+
+Every mutation creates an immutable `memver_...` snapshot. Versions accumulate for the lifetime of the parent memory; `memories.retrieve` always returns the current head, the version endpoints give you history.
+
+| Operation that triggers it | `operation` field on the version |
+| --- | --- |
+| `memories.create` at a new path | `"created"` |
+| `memories.update` changing `content`, `path`, or both (or an agent-side write to the mount) | `"modified"` |
+| `memories.delete` | `"deleted"` |
+
+Each version also records `created_by` — an actor object with `type` ∈ `session_actor` / `api_actor` / `user_actor` — and, after redaction, `redacted_at` + `redacted_by`.
+
+### List versions
+
+Newest-first, paginated. Filter by `memory_id`, `operation`, `session_id`, `api_key_id`, or `created_at_gte` / `created_at_lte`. Pass `view="full"` to include `content`; default is metadata-only.
+
+```python
+for v in client.beta.memory_stores.memory_versions.list(store.id, memory_id=mem.id):
+    print(f"{v.id}: {v.operation}")
+```
+
+### Retrieve a version
+
+```python
+version = client.beta.memory_stores.memory_versions.retrieve(
+    version_id, memory_store_id=store.id
+)
+print(version.content)
+```
+
+### Redact a version
+
+Scrubs content from a historical version while preserving the audit trail (actor + timestamps). Clears `content`, `content_sha256`, `content_size_bytes`, and `path`; everything else stays. Use for leaked secrets, PII, or user-deletion requests.
+
+```python
+client.beta.memory_stores.memory_versions.redact(version_id, memory_store_id=store.id)
+```
+
+## Endpoint reference
+
+See `shared/managed-agents-api-reference.md` → Memory Stores / Memories / Memory Versions for the full HTTP method/path tables. Raw HTTP base path:
+
+```
+POST   /v1/memory_stores
+POST   /v1/memory_stores/{memory_store_id}/archive
+GET    /v1/memory_stores/{memory_store_id}/memories
+PATCH  /v1/memory_stores/{memory_store_id}/memories/{memory_id}
+GET    /v1/memory_stores/{memory_store_id}/memory_versions
+POST   /v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact
+```
+
+For cURL examples and the CLI (`ant beta:memory-stores ...`), WebFetch the Memory URL in `shared/live-sources.md` → Managed Agents.

package/resources/local/claude/plugins/marketplaces/anthropic-agent-skills/skills/claude-api/shared/managed-agents-onboarding.md

@@ -0,0 +1,114 @@
+# Managed Agents — Onboarding Flow
+
+> **Invoked via `/claude-api managed-agents-onboard`?** You're in the right place. Run the interview below — don't summarize it back to the user, ask the questions.
+
+Use this when a user wants to set up a Managed Agent from scratch. Three steps: **branch on know-vs-explore → configure the template → set up the session**. End by emitting working code.
+
+> Read `shared/managed-agents-core.md` alongside this — it has full detail for each knob. This doc is the interview script, not the reference.
+
+---
+
+Claude Managed Agents is a hosted agent: Anthropic runs the agent loop on its orchestration layer and provisions a sandboxed container per session where the agent's tools execute. You supply the agent config and the environment config; the harness — event stream, sandbox orchestration, prompt caching, context compaction, and extended thinking — is handled for you.
+
+**What you supply:**
+- **An agent config** — tools, skills, model, system prompt. Reusable and versioned.
+- **An environment config** — the sandbox your agent's tools execute in (networking, packages). Reusable across agents.
+
+Each run of the agent is a **session**.
+
+---
+
+## 1. Know or explore?
+
+Ask the user:
+
+> Do you already know the agent you want to build, or would you like to explore some common patterns first?
+
+### Explore path — show the patterns
+
+Four shapes, same runtime code path (`sessions.create()` → `sessions.events.send()` → stream). Only the trigger and sink differ.
+
+| Pattern | Trigger | Example |
+|---|---|---|
+| Event-triggered | Webhook | GitHub PR push → CMA (GitHub tool) → Slack | # <------ MC maybe delete?
+| Scheduled | Cron | Daily brief: browser + GitHub + Jira → CMA → Slack | # <------ MC maybe delete?
+| Fire-and-forget PR | Human | Slack slash-command → CMA (GitHub tool) → PR passing CI |
+| Research + dashboard | Human | Topic → CMA (web search + `frontend-design` skill) → HTML dashboard |
+
+Ask which shape fits, then continue with the Know path using it as the reference.
+
+### Know path — configure template
+
+Three rounds. Batch the questions in each round; don't ask them one at a time.
+
+**Round A — Tools.** Start here; it's the most concrete part. Three types; ask which the user wants (any combination):
+
+| Type | What it is | How to guide |
+|---|---|---|
+| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Ready-to-use: `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`. Enable all at once, or individually via `enabled: true/false`. | Recommend enabling the full toolset. List the 8 tools so the user knows what they're getting. Full detail: `shared/managed-agents-tools.md` → Agent Toolset. |
+| **MCP tools** | Third-party integrations (GitHub, Linear, Asana, etc.) via `mcp_toolset`. Credentials live in a vault, not inline. | Ask which services. For each, walk through MCP server URL + vault credentials. Full detail: `shared/managed-agents-tools.md` → MCP Servers + Vaults. |
+| **Custom tools** | The user's own app handles these tool calls — agent fires `agent.custom_tool_use`, the app sends a result message back. | Ask for each tool: name, description, input schema. The app code that handles the event is *their* code — don't generate it. Full detail: `shared/managed-agents-tools.md` → Custom Tools. |
+
+**Round B — Skills, files, and repos.** What the agent has on hand when it starts.
+
+*Skills* — two types; both work the same way — Claude auto-uses them when relevant. Max 64 per agent.
+- [ ] **Pre-built Agent Skills**: `xlsx`, `docx`, `pptx`, `pdf`. Reference by name.
+- [ ] **Custom Skills**: skills uploaded to the user's org via the Skills API. Reference by `skill_id` + optional `version`. If the skill doesn't exist yet, walk the user through `POST /v1/skills` + `POST /v1/skills/{id}/versions` (beta header `skills-2025-10-02`). Full detail: `shared/managed-agents-tools.md` → Skills + Skills API.
+
+*GitHub repositories* — any repos the agent needs on-disk? For each:
+- [ ] Repo URL (`https://github.com/org/repo`)
+- [ ] `authorization_token` (PAT or GitHub App token scoped to the repo)
+- [ ] Optional `mount_path` (defaults to `/workspace/<repo-name>`) and `checkout` (branch or SHA)
+
+Emit as `resources: [{type: "github_repository", url, authorization_token, ...}]`. Full detail: `shared/managed-agents-environments.md` → GitHub Repositories.
+
+> ‼️ **PR creation needs the GitHub MCP server too.** `github_repository` gives filesystem access only — to open PRs, also attach the GitHub MCP server in Round A and credential it via a vault. The workflow is: edit files in the mounted repo → push branch via `bash` → create PR via the MCP `create_pull_request` tool.
+
+*Files* — any local files to seed the session with? For each:
+- [ ] Upload via the Files API → persist `file_id`
+- [ ] Choose a `mount_path` — absolute, e.g. `/workspace/data.csv` (parents auto-created; files mount read-only)
+
+Emit as `resources: [{type: "file", file_id, mount_path}]`. Max 999 file resources. Agent working directory defaults to `/workspace`. Full detail: `shared/managed-agents-environments.md` → Files API.
+
+**Round C — Environment + identity:**
+- [ ] Networking: unrestricted internet from the container, or lock egress to specific hosts? (If locked, MCP server domains must be in `allowed_hosts` or tools silently fail.)
+- [ ] Name?
+- [ ] Job (one or two sentences — becomes the system prompt)?
+- [ ] Model? (default `claude-opus-4-7`)
+
+---
+
+## 2. Set up the session
+
+Per-run. Points at the agent + environment, attaches credentials, kicks off.
+
+**Vault credentials** (if the agent declared MCP servers):
+- [ ] Existing vault, or create one? (`client.beta.vaults.create()` + `vaults.credentials.create()`)
+
+Credentials are write-only, matched to MCP servers by URL, auto-refreshed. See `shared/managed-agents-tools.md` → Vaults.
+
+**Kickoff:**
+- [ ] First message to the agent?
+
+Session creation blocks until all resources mount. Open the event stream before sending the kickoff. Stream is SSE; break on `session.status_terminated`, or on `session.status_idle` with a terminal `stop_reason` — i.e. anything except `requires_action`, which fires transiently while the session waits on a tool confirmation or custom-tool result (see `shared/managed-agents-client-patterns.md` Pattern 5). Usage lands on `span.model_request_end`. Agent-written artifacts end up in `/mnt/session/outputs/` — download via `files.list({scope_id: session.id, betas: ["managed-agents-2026-04-01"]})`.
+
+---
+
+## 3. Emit the code
+
+Go straight from the last interview answer to the code — no preamble about the setup-vs-runtime split, no "the critical thing to internalize…", no lecture about `agents.create()` being one-time. The two-block structure below already shows that; don't narrate it. Generate **two clearly-separated blocks** per language detected (Python/TS/cURL — see SKILL.md → Language Detection):
+
+**Block 1 — Setup (run once, store the IDs):**
+1. `environments.create()` → persist `env_id`
+2. `agents.create()` with everything from §Round A–C → persist `agent_id` and `agent_version`
+
+Label: `# ONE-TIME SETUP — run once, save the IDs to config/.env`
+
+**Block 2 — Runtime (run on every invocation):**
+1. Load `env_id` + `agent_id` from config/env
+2. `sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])`
+3. Open stream, `events.send()` the kickoff, loop until `session.status_terminated` or `session.status_idle && stop_reason.type !== 'requires_action'` (see `shared/managed-agents-client-patterns.md` Pattern 5 for the full gate — do not break on bare `session.status_idle`)
+
+> ⚠️ **Never emit `agents.create()` and `sessions.create()` in the same unguarded block.** That teaches the user to create a new agent on every run — the #1 anti-pattern. If they need a single script, wrap agent creation in `if not os.getenv("AGENT_ID"):`.
+
+Pull exact syntax from `python/managed-agents/README.md`, `typescript/managed-agents/README.md`, or `curl/managed-agents.md`. Don't invent field names.

package/resources/local/claude/plugins/marketplaces/anthropic-agent-skills/skills/claude-api/shared/managed-agents-overview.md

@@ -0,0 +1,64 @@
+# Managed Agents — Overview
+
+Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's *tools* execute — bash commands, file operations, code. You create a persisted **Agent** config (model, system prompt, tools, MCP servers, skills), then start **Sessions** that reference it. The session streams events back to you; you send user messages and tool results in.
+
+## ⚠️ THE MANDATORY FLOW: Agent (once) → Session (every run)
+
+**Why agents are separate objects: versioning.** An agent is a persisted, versioned config — every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you `agents.create()` fresh on every run.
+
+Every session references a pre-created `/v1/agents` object. Create the agent once, store the ID, and reuse it across runs.
+
+| Step | Call | Frequency |
+|---|---|---|
+| 1 | `POST /v1/agents` — `model`, `system`, `tools`, `mcp_servers`, `skills` live here | **ONCE.** Store `agent.id` **and** `agent.version`. |
+| 2 | `POST /v1/sessions` — `agent: "agent_abc123"` or `{type: "agent", id, version}` | **Every run.** String shorthand uses latest version. |
+
+If you're about to write `sessions.create()` with `model`, `system`, or `tools` on the session body — **stop**. Those fields live on `agents.create()`. The session takes a *pointer* only.
+
+**When generating code, separate setup from runtime.** `agents.create()` belongs in a setup script (or a guarded `if agent_id is None:` block), not at the top of the hot path. If the user's code calls `agents.create()` on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: create once → persist the ID (config file, env var, secrets manager) → every run loads the ID and calls `sessions.create()`.
+
+**To change the agent's behavior, use `POST /v1/agents/{id}` — don't create a new one.** Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via `{type: "agent", id, version}`). See `shared/managed-agents-core.md` → Agents → Versioning.
+
+## Beta Headers
+
+Managed Agents is in beta. The SDK sets required beta headers automatically:
+
+| Beta Header                    | What it enables                                      |
+| ------------------------------ | ---------------------------------------------------- |
+| `managed-agents-2026-04-01`    | Agents, Environments, Sessions, Events, Session Resources, Vaults, Credentials, Memory Stores |
+| `skills-2025-10-02`            | Skills API (for managing custom skill definitions)   |
+| `files-api-2025-04-14`         | Files API for file uploads                           |
+
+**Which beta header goes where:** The SDK sets `managed-agents-2026-04-01` automatically on `client.beta.{agents,environments,sessions,vaults,memory_stores}.*` calls, and `files-api-2025-04-14` / `skills-2025-10-02` automatically on `client.beta.files.*` / `client.beta.skills.*` calls. You do NOT need to add the Skills or Files beta header when calling Managed Agents endpoints. **Exception — session-scoped file listing:** `client.beta.files.list({scope_id: session.id})` is a Files endpoint that takes a Managed Agents parameter, so it needs **both** headers. Pass `betas: ["managed-agents-2026-04-01"]` explicitly on that call (the SDK adds the Files header; you add the Managed Agents one). See `shared/managed-agents-environments.md` → Session outputs.
+
+
+## Reading Guide
+
+| User wants to...                       | Read these files                                        |
+| -------------------------------------- | ------------------------------------------------------- |
+| **Get started from scratch / "help me set up an agent"** | `shared/managed-agents-onboarding.md` — guided interview (WHERE→WHO→WHAT→WATCH), then emit code |
+| Understand how the API works           | `shared/managed-agents-core.md`                         |
+| See the full endpoint reference        | `shared/managed-agents-api-reference.md`                |
+| **Create an agent** (required first step) | `shared/managed-agents-core.md` (Agents section) + language file |
+| Update/version an agent                | `shared/managed-agents-core.md` (Agents → Versioning) — update, don't re-create |
+| Create a session                       | `shared/managed-agents-core.md` + `{lang}/managed-agents/README.md` |
+| Configure tools and permissions        | `shared/managed-agents-tools.md`                        |
+| Set up MCP servers                     | `shared/managed-agents-tools.md` (MCP Servers section)  |
+| Stream events / handle tool_use        | `shared/managed-agents-events.md` + language file       |
+| Set up environments                    | `shared/managed-agents-environments.md` + language file |
+| Upload files / attach repos            | `shared/managed-agents-environments.md` (Resources)     |
+| Give agents persistent memory across sessions | `shared/managed-agents-memory.md` — memory stores, `memory_store` session resource, preconditions, versions/redact |
+| Store MCP credentials                  | `shared/managed-agents-tools.md` (Vaults section)       |
+| Call a non-MCP API / CLI that needs a secret | `shared/managed-agents-client-patterns.md` Pattern 9 — no container env vars; vaults are MCP-only; keep the secret host-side via a custom tool |
+
+## Common Pitfalls
+
+- **Agent FIRST, then session — NO EXCEPTIONS** — the session's `agent` field accepts **only** a string ID or `{type: "agent", id, version}`. `model`, `system`, `tools`, `mcp_servers`, `skills` are **top-level fields on `POST /v1/agents`**, never on `sessions.create()`. If the user hasn't created an agent, that is step zero of every example.
+- **Agent ONCE, not every run** — `agents.create()` is a setup step. Store the returned `agent_id` and reuse it; don't call `agents.create()` at the top of your hot path. If the agent's config needs to change, `POST /v1/agents/{id}` — each update creates a new version, and sessions can pin to a specific version for reproducibility.
+- **MCP auth goes through vaults** — the agent's `mcp_servers` array declares `{type, name, url}` only (no auth). Credentials live in vaults (`client.beta.vaults.credentials.create`) and attach to sessions via `vault_ids`. Anthropic auto-refreshes OAuth tokens using the stored refresh token.
+- **Stream to get events** — `GET /v1/sessions/{id}/events/stream` is the primary way to receive agent output in real-time.
+- **SSE stream has no replay — reconnect with consolidation** — if the stream drops while a `agent.tool_use`, `agent.mcp_tool_use`, or `agent.custom_tool_use` is pending resolution (`user.tool_confirmation` for the first two, `user.custom_tool_result` for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with `GET /v1/sessions/{id}/events/stream` , fetch `GET /v1/sessions/{id}/events`, dedupe by event ID, then proceed. See `shared/managed-agents-events.md` → Reconnecting after a dropped stream.
+- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `session.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events.
+- **Messages queue** — you can send events while the session is `running` or `idle`; they're processed in order. No need to wait for a response before sending the next message.
+- **Cloud environments only** — `config.type: "cloud"` is the only supported environment type.
+- **Archive is permanent on every resource** — archiving an agent, environment, session, vault, credential, or memory store makes it read-only with no unarchive. For agents, environments, and memory stores specifically, archived resources cannot be referenced by new sessions (existing sessions continue). Do not call `.archive()` on a production agent, environment, or memory store as cleanup — **always confirm with the user before archiving**.