winter-super-cli 2026.5.25 → 2026.5.27

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

@@ -1,209 +0,0 @@
-# Managed Agents — Common Client Patterns
-
-Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.
-
-Code samples are TypeScript — Python and cURL follow the same shape; see `python/managed-agents/README.md` and `curl/managed-agents.md` for equivalents.
-
----
-
-## 1. Lossless stream reconnect
-
-**Problem:** SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between.
-
-**Solution:** on reconnect, fetch the full event history via `events.list()` *before* consuming the live stream, and dedupe on event ID as the live stream catches up.
-
-```ts
-const seenEventIds = new Set<string>()
-const stream = await client.beta.sessions.events.stream(session.id)
-
-// Stream is now open and buffering server-side. Read history first.
-for await (const event of client.beta.sessions.events.list(session.id)) {
-  seenEventIds.add(event.id)
-  handle(event)
-}
-
-// Tail the live stream. Dedupe only gates handle() — terminal checks must run
-// even for already-seen events, or a terminal event that was in the history
-// response gets skipped by `continue` and the loop never exits.
-for await (const event of stream) {
-  if (!seenEventIds.has(event.id)) {
-    seenEventIds.add(event.id)
-    handle(event)
-  }
-  if (event.type === 'session.status_terminated') break
-  if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break
-}
-```
-
----
-
-## 2. `processed_at` — queued vs processed
-
-Every event on the stream carries `processed_at` (ISO 8601). For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`) it's `null` when the event has been queued but not yet picked up by the agent, and populated once the agent processes it. The same event appears on the stream twice — once with `processed_at: null`, once with a timestamp.
-
-```ts
-for await (const event of stream) {
-  if (event.type === 'user.message') {
-    if (event.processed_at == null) onQueued(event.id)
-    else onProcessed(event.id, event.processed_at)
-  }
-}
-```
-
-Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned `event.id` is application-specific (typically via the return value of `events.send()` or FIFO ordering).
-
----
-
-## 3. Interrupt a running session
-
-Send `user.interrupt` as a normal event. The session keeps running until it reaches a safe boundary, then goes idle.
-
-```ts
-await client.beta.sessions.events.send(session.id, {
-  events: [{ type: 'user.interrupt' }],
-})
-
-// Drain until the session is truly done — see Pattern 5 for the full gate.
-for await (const event of stream) {
-  if (event.type === 'session.status_terminated') break
-  if (
-    event.type === 'session.status_idle' &&
-    event.stop_reason.type !== 'requires_action'
-  ) break
-}
-```
-
-Reference: `interrupt.ts` — sends the interrupt the moment it sees `span.model_request_start`, drains to idle, then verifies via `sessions.retrieve()`.
-
----
-
-## 4. `tool_confirmation` round-trip
-
-When the agent has `permission_policy: { type: 'always_ask' }`, any call to that tool fires an `agent.tool_use` event with `evaluated_permission === 'ask'` and the session goes idle waiting for a decision. Respond with `user.tool_confirmation`.
-
-```ts
-for await (const event of stream) {
-  if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') {
-    await client.beta.sessions.events.send(session.id, {
-      events: [{
-        type: 'user.tool_confirmation',
-        tool_use_id: event.id,         // not a toolu_ id — use event.id
-        result: 'allow',               // or 'deny'
-        // deny_message: '...',        // optional, only with result: 'deny'
-      }],
-    })
-  }
-}
-```
-
-Key points:
-- `tool_use_id` is `event.id` (typically `sevt_...`), **not** a `toolu_...` ID.
-- `result` is `'allow' | 'deny'`. Use `deny_message` to tell the model *why* you denied — it gets surfaced back to the agent.
-- Multiple pending tools: respond once per `agent.tool_use` event with `evaluated_permission === 'ask'`.
-
-Reference: `tool-permissions.ts`.
-
----
-
-## 5. Correct idle-break gate
-
-Do not break on `session.status_idle` alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a `user.tool_confirmation`, or while awaiting a `user.custom_tool_result`. Break when idle with a terminal `stop_reason`, or on `session.status_terminated`.
-
-```ts
-for await (const event of stream) {
-  handle(event)
-  if (event.type === 'session.status_terminated') break
-  if (event.type === 'session.status_idle') {
-    if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it
-    break // end_turn or retries_exhausted — both terminal
-  }
-}
-```
-
-`stop_reason.type` values on `session.status_idle`:
-- `requires_action` — agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break.
-- `retries_exhausted` — terminal failure. Break, then check `sessions.retrieve()` for the error state.
-- `end_turn` — normal completion.
-
----
-
-## 6. Post-idle status-write race
-
-The SSE stream emits `session.status_idle` slightly before the session's queryable status reflects it. Clients that break on idle and immediately call `sessions.delete()` or `sessions.archive()` will intermittently 400 with "cannot delete/archive while running."
-
-Poll before cleanup:
-
-```ts
-let s
-for (let i = 0; i < 10; i++) {
-  s = await client.beta.sessions.retrieve(session.id)
-  if (s.status !== 'running') break
-  await new Promise(r => setTimeout(r, 200))
-}
-if (s?.status !== 'running') {
-  await client.beta.sessions.archive(session.id)
-} // else: still running after 2s — don't archive, let it settle or escalate
-```
-
----
-
-## 7. Stream-first, then send
-
-Always open the stream **before** sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them.
-
-```ts
-const stream = await client.beta.sessions.events.stream(session.id)
-await client.beta.sessions.events.send(session.id, {
-  events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }],
-})
-for await (const event of stream) { /* ... */ }
-```
-
-The `Promise.all([stream, send])` shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened.
-
----
-
-## 8. File-mount gotchas
-
-**The mounted resource has a different `file_id` than the file you uploaded.** Session creation makes a session-scoped copy.
-
-```ts
-const uploaded = await client.beta.files.upload({ file })
-// uploaded.id         → the original file
-const session = await client.beta.sessions.create({
-  /* ... */
-  resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }],
-})
-// session.resources[0].file_id !== uploaded.id  ← different IDs
-```
-
-Delete the original via `files.delete(uploaded.id)`; the session-scoped copy is garbage-collected with the session. `mount_path` must be absolute — see `shared/managed-agents-environments.md`.
-
----
-
-## 9. Secrets for non-MCP APIs and CLIs — keep them host-side via custom tools
-
-**Problem:** you want the agent to call a third-party API or run a CLI that needs a secret (API key, token, service-account credential), but there is currently no way to set environment variables inside the session container, and vaults currently hold MCP credentials only — they are not exposed to the container's shell. So `curl`, installed CLIs, or SDK clients running via the `bash` tool have no first-class place to read a secret from.
-
-**Solution:** move the authenticated call to your side. Declare a custom tool on the agent; when the agent emits `agent.custom_tool_use`, your orchestrator (the process reading the SSE stream) executes the call with its own credentials and responds with `user.custom_tool_result`. The container never sees the key.
-
-```ts
-// Agent template: declare the tool, no credentials
-tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }]
-
-// Orchestrator: handle the call with host-side creds
-for await (const event of stream) {
-  if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
-    const result = await linear.request(event.input.query, event.input.vars) // host's key
-    await client.beta.sessions.events.send(session.id, {
-      events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }],
-    })
-  }
-}
-```
-
-Same shape works for `gh` CLI, local eval scripts, or anything else that needs host-side auth or binaries.
-
-**Security note:** this does not expose a public endpoint. `agent.custom_tool_use` arrives on the SSE stream your orchestrator already holds open with your Anthropic API key, and `user.custom_tool_result` goes back via `events.send()` under the same key. Your orchestrator is a client, not a server — nothing unauthenticated is listening.
-
-**Do not embed API keys in the system prompt or user messages as a workaround.** Prompts and messages are stored in the session's event history, returned by `events.list()`, and included in compaction summaries — a secret placed there is durably persisted and readable via the API for the life of the session.

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

@@ -1,218 +0,0 @@
-# Managed Agents — Core Concepts
-
-## Architecture
-
-Managed Agents is built around four core concepts:
-
-| Concept | Endpoint | What it is |
-|---|---|---|
-| **Agent** | `/v1/agents` | A persisted, versioned object defining the agent's capabilities and persona: model, system prompt, tools, MCP servers, skills. **Must be created before starting a session.** See the Agents section below. |
-| **Session** | `/v1/sessions` | A stateful interaction with an agent. References a pre-created agent by ID + an environment + initial instructions. Produces an event stream. |
-| **Environment** | `/v1/environments` | A template defining the configuration for container provisioning. |
-| **Container** | N/A | An isolated compute instance where the agent's **tools** execute (bash, file ops, code). The agent loop does not run here — it runs on Anthropic's orchestration layer and acts on the container via tool calls. |
-
-```
-                       ┌─────────────────────────────────────┐
-                       │  Anthropic orchestration layer      │
-Agent (config) ───────▶│  (agent loop: Claude + tool calls)  │
-                       └──────────────┬──────────────────────┘
-                                      │ tool calls
-                                      ▼
-Environment (template) ──▶ Container (tool execution workspace)
-                                 │
-                         Session ─┤
-                                 ├── Resources (files, repos, memory stores — attached at startup)
-                                 ├── Vault IDs (MCP credential references)
-                                 └── Conversation (event stream in/out)
-```
-
-> **Agent creation is a prerequisite.** Sessions reference a pre-created agent by ID — `model`/`system`/`tools` live on the agent object, never on the session. Every flow starts with `POST /v1/agents`.
-
----
-
-## Session Lifecycle
-
-```
-rescheduling → running ↔ idle → terminated
-```
-
-| Status         | Description                                                        |
-| -------------- | ------------------------------------------------------------------ |
-| `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. |
-| `running` | Session has starting running, and the Agent is actively doing work. |
-| `rescheduling` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
-| `terminated` | Session has terminated, entering an irreversible and unusable state.  |
-
-- Events can be sent when the session is `running` or `idle`. Messages are queued and processed in order.
-- The agent transitions `idle → running` when it receives a new event, then back to `idle` when done.
-- Errors surface as `session.error` events in the stream, not as a status value.
-
-### Built-in session features
-
-- **Context compaction** — if you approach max context, the API automatically condenses session history to keep the interaction going
-- **Prompt caching** — historical repeated tokens are cached, reducing processing time and cost
-- **Extended thinking** — on by default, returned as `agent.thinking` events
-
-### Session operations
-
-| Operation | Notes |
-|---|---|
-| List / fetch | Paginated list or single resource by ID |
-| Update | Only `title` is updatable |
-| Archive | Session becomes **read-only**. Not reversible. |
-| Delete | Permanently deletes session, event history, container, and checkpoints. |
-
----
-
-## Sessions
-
-A session is a running agent instance inside an environment.
-
-### Session Object
-
-Key fields returned by the API:
-
-| Field           | Type     | Description                                         |
-| --------------- | -------- | --------------------------------------------------- |
-| `type` | string | Always `"session"` |
-| `id` | string | Unique session ID |
-| `title` | string | Human-readable title |
-| `status` | string | `idle`, `running`, `rescheduling`, `terminated` |
-| `created_at` | string | ISO 8601 timestamp |
-| `updated_at` | string | ISO 8601 timestamp |
-| `archived_at` | string | ISO 8601 timestamp (nullable) |
-| `environment_id` | string | Environment ID |
-| `agent` | object | Agent configuration |
-| `resources` | array | Attached files, repos, and memory stores |
-| `metadata` | object | User-provided key-value pairs (max 8 keys) |
-| `usage` | object | Token usage statistics |
-
-### Creating a session
-
-**A session is meaningless without an agent.** Sessions reference a pre-created agent by ID. Create the agent first via `agents.create()`, then reference it:
-
-```ts
-// 1. Create the agent (reusable, versioned)
-const agent = await client.beta.agents.create(
-  {
-    name: "Coding Assistant",
-    model: "claude-opus-4-7",
-    system: "You are a helpful coding agent.",
-    tools: [{ type: "agent_toolset_20260401"}],
-  },
-);
-
-// 2. Start a session that references it
-const session = await client.beta.sessions.create(
-  {
-    agent: agent.id,  // string shorthand → latest version. Or: { type: "agent", id: agent.id, version: agent.version }
-    environment_id: environmentId,
-    title: "Hello World Session",
-  },
-);
-```
-
-**Session creation parameters:**
-
-| Field           | Type     | Required | Description                                    |
-| --------------- | -------- | -------- | ---------------------------------------------- |
-| `agent`         | string or object | **Yes** | String shorthand `"agent_abc123"` (latest version) or `{type: "agent", id, version}` |
-| `environment_id`| string   | **Yes**  | Environment ID                                 |
-| `title`         | string   | No       | Human-readable name (appears in logs/dashboards) |
-| `resources`     | array    | No       | Files, GitHub repos, or memory stores, attached to the container at startup. Memory stores are session-create-only (not addable via `resources.add()`). |
-| `vault_ids`     | array    | No       | Vault IDs (`vlt_*`) — MCP credentials with auto-refresh. See `shared/managed-agents-tools.md` → Vaults. |
-| `metadata`      | object   | No       | User-provided key-value pairs                  |
-
-**Agent configuration fields** (passed to `agents.create()`, not `sessions.create()`):
-
-| Field         | Type     | Required | Description                                    |
-| ------------- | -------- | -------- | ---------------------------------------------- |
-| `name`        | string   | **Yes**  | Human-readable name (1-256 chars)              |
-| `model`       | string or object | **Yes** | Claude model ID (bare string, or `{id, speed}` object). All Claude 4.5+ models supported. |
-| `system`      | string   | No       | System prompt — defines the agent's behavior (up to 100K chars) |
-| `tools`       | array    | No       | Encompasses three kinds: (1) pre-built Claude Agent tools (`agent_toolset_20260401`), (2) MCP tools (`mcp_toolset`), and (3) custom client-side tools. Max 128. |
-| `mcp_servers` | array    | No       | MCP server connections — standardized third-party capabilities (e.g. GitHub, Asana). Max 20, unique names. See `shared/managed-agents-tools.md` → MCP Servers. |
-| `skills`      | array    | No       | Customized "best-practices" context with progressive disclosure. Max 64. See `shared/managed-agents-tools.md` → Skills. |
-| `description` | string   | No       | Description of the agent (up to 2048 chars)    |
-| `metadata`    | object   | No       | Arbitrary key-value pairs (max 16, keys ≤64 chars, values ≤512 chars) |
-
----
-
-## Agents
-
-**This is where every Managed Agents flow begins.** The agent object is a persisted, versioned configuration — you create it once, then reference it by ID every time you start a session. No agent → no session.
-
-### Agent Object
-
-The API is **flat** — `model`, `system`, `tools` etc. are top-level fields, not wrapped in an `agent:{}` sub-object.
-
-| Field              | Type     | Required | Description                                        |
-| ------------------ | -------- | -------- | -------------------------------------------------- |
-| `name`             | string   | Yes      | Human-readable name                                |
-| `model`            | string   | Yes      | Claude model ID                                    |
-| `system`           | string   | No       | System prompt                                      |
-| `tools`            | array    | No       | Agent toolset / MCP toolset / custom tools         |
-| `mcp_servers`      | array    | No       | MCP server connections                             |
-| `skills`           | array    | No       | Skill references (max 64)                          |
-| `description`      | string   | No       | Description of the agent                           |
-| `metadata`         | object   | No       | Arbitrary key-value pairs                          |
-
-### Lifecycle: create once, run many, update in place
-
-The agent is a **persistent resource**, not a per-run parameter. The intended pattern:
-
-```
-┌─ setup (once) ─────────┐     ┌─ runtime (every invocation) ─┐
-│ agents.create()        │     │ sessions.create(             │
-│   → store agent_id     │ ──→ │   agent={type:..., id: ID}   │
-│     in config/env/db   │     │ )                            │
-└────────────────────────┘     └──────────────────────────────┘
-```
-
-**Anti-pattern:** calling `agents.create()` at the top of every script run. This accumulates orphaned agent objects, pays create latency on every invocation, and defeats the versioning model. If you see `agents.create()` in a function that's called per-request or per-cron-tick, that's wrong — hoist it to one-time setup and persist the ID.
-
-### Versioning
-
-Each `POST /v1/agents/{id}` (update) creates a new immutable version (numeric timestamp, e.g. `1772585501101368014`). The agent's history is append-only — you can't edit a past version.
-
-**Why version:**
-- **Reproducibility** — pin a session to a known-good config: `{type: "agent", id, version: 3}`
-- **Safe iteration** — update the agent without breaking sessions already running on the old version
-- **Rollback** — if a new system prompt regresses, pin new sessions back to the prior version while you debug
-
-**`version` is optional.** Omit it (or use the string shorthand `agent="agent_abc123"`) to get the latest version at session-creation time. Pass it explicitly (`{type: "agent", id, version: N}`) to pin for reproducibility.
-
-**Getting the version to pin:** `agents.create()` and `agents.update()` both return `version` in the response. Store it alongside `agent_id`. To fetch the current latest for an existing agent: `GET /v1/agents/{id}` → `.version`.
-
-**When to update vs create new:** Update (`POST /v1/agents/{id}`) when it's conceptually the same agent with tweaked behavior (better prompt, extra tool). Create a new agent when it's a different persona/purpose. Rule of thumb: if you'd give it the same `name`, update.
-
-### Agent Endpoints
-
-| Operation        | Method   | Path                                  |
-| ---------------- | -------- | ------------------------------------- |
-| Create           | `POST`   | `/v1/agents`                          |
-| List             | `GET`    | `/v1/agents`                          |
-| Get              | `GET`    | `/v1/agents/{id}`                     |
-| Update           | `POST`   | `/v1/agents/{id}`                     |
-| Archive          | `POST`   | `/v1/agents/{id}/archive`             |
-
-> ⚠️ **Archive is permanent.** Archiving makes the agent read-only: existing sessions continue to run, but **new sessions cannot reference it**, and there is no unarchive. Since agents have no `delete`, this is the terminal lifecycle state. Never archive a production agent as routine cleanup — confirm with the user first.
-
-### Using an Agent in a Session
-
-Reference the agent by string ID (latest version) or by object with an explicit version:
-
-```python
-# String shorthand — uses the agent's latest version
-session = client.beta.sessions.create(
-    agent=agent.id,
-    environment_id=environment_id,
-)
-
-# Or pin to a specific version (int)
-session = client.beta.sessions.create(
-    agent={"type": "agent", "id": agent.id, "version": agent.version},
-    environment_id=environment_id,
-)
-```
-

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

@@ -1,211 +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)                          |
-| `package_managers_and_custom`   | Package managers + custom `allowed_hosts`                      |
-
-```json
-{
-  "networking": {
-    "type": "package_managers_and_custom",
-    "allowed_hosts": ["api.example.com"]
-  }
-}
-```
-
-**MCP caveat:** If using restricted networking, make sure `allowed_hosts` includes your MCP server domains. 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" },
-  },
-});
-```
-
-### 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. **Session creation blocks until all resources are mounted** — the container won't go `running` until every file and repo is in place. 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-4-7',
-    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-4-7",
-    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.