hive-skills 0.1.0

package/assets/skills/converted/claude-api/composable/mini/39-managed-agents-scheduled-deployments.md

@@ -0,0 +1,146 @@
+# Managed Agents — Scheduled Deployments
+
+A **scheduled deployment** runs an agent on a recurring cron schedule — each firing creates a session autonomously. Use it for predictable-cadence work: nightly triage, weekly compliance scans, hourly monitors.
+
+Requires the `managed-agents-2026-04-01` beta header (the SDK sets it automatically for `client.beta.deployments.*` / `client.beta.deployment_runs.*` calls).
+
+## Create a deployment
+
+A deployment bundles everything a session needs (agent, environment, optional files / GitHub / memory stores / vaults) plus a `schedule` and the `initial_events` that kick off each run:
+
+- `agent` and `environment_id` are required — same shapes as `sessions.create` (see `shared/managed-agents-core.md`).
+- `initial_events` must contain the starting `user.message`.
+- `schedule` takes a cron `expression` and an IANA `timezone`. Minute-level granularity is the maximum.
+
+```bash
+curl -fsSL https://api.anthropic.com/v1/deployments \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "anthropic-beta: managed-agents-2026-04-01" \
+  -H "content-type: application/json" \
+  -d @- <<EOF
+{
+  "name": "Weekly compliance scan",
+  "agent": "$AGENT_ID",
+  "environment_id": "$ENVIRONMENT_ID",
+  "initial_events": [
+    {"type": "user.message", "content": [{"type": "text", "text": "Run the weekly compliance scan."}]}
+  ],
+  "schedule": {
+    "type": "cron",
+    "expression": "0 20 * * 5",
+    "timezone": "America/New_York"
+  }
+}
+EOF
+```
+
+```python
+deployment = client.beta.deployments.create(
+    name="Weekly compliance scan",
+    agent=agent.id,
+    environment_id=environment.id,
+    initial_events=[
+        {
+            "type": "user.message",
+            "content": [{"type": "text", "text": "Run the weekly compliance scan."}],
+        },
+    ],
+    schedule={
+        "type": "cron",
+        "expression": "0 20 * * 5",
+        "timezone": "America/New_York",
+    },
+)
+```
+
+The response is a deployment object (`depl_` ID prefix). Check `schedule.upcoming_runs_at` — the next fire times — to confirm the schedule parses the way you intended:
+
+```json
+{
+  "id": "depl_01xyz",
+  "status": "active",
+  "paused_reason": null,
+  "schedule": {
+    "type": "cron",
+    "expression": "0 20 * * 5",
+    "timezone": "America/New_York",
+    "last_run_at": null,
+    "upcoming_runs_at": ["2026-05-09T00:00:00Z", "2026-05-16T00:00:00Z", "2026-05-23T00:00:00Z"]
+  }
+}
+```
+
+Deployments may apply up to **10 seconds of jitter** to distribute load. Maximum **1000 scheduled deployments per organization** (contact Anthropic support for more).
+
+### Cron and timezone semantics
+
+- **Expression:** standard POSIX cron (`minute hour day-of-month month day-of-week`).
+- **Timezone:** IANA identifier (e.g. `"America/Los_Angeles"`).
+- **DST:** literal wall-clock matching — `"0 20 * * *"` in `America/New_York` fires at 8:00 PM local regardless of EST/EDT.
+
+> ⚠️ **DST edge:** wall-clock times that don't exist on a spring-forward day (e.g. 2AM) are **skipped**; times that occur twice on a fall-back day **fire twice**. Schedule outside the 1–3AM local window, or use UTC, when missed or duplicate executions are unacceptable.
+
+## Deployment runs
+
+Every trigger attempt — successful or not — writes a **deployment run** record (`drun_` prefix), so you can audit failures independent of the session lifecycle. A successful run carries the created `session_id`; follow that session via the event stream (`shared/managed-agents-events.md`) or webhooks (`shared/managed-agents-webhooks.md`) as usual. A failed run carries an `error` whose `type` explains why session creation was rejected.
+
+```python
+# All runs for a deployment
+for run in client.beta.deployment_runs.list(deployment_id=deployment.id):
+    print(run.created_at, run.session_id or run.error.type)
+
+# Failures only
+for run in client.beta.deployment_runs.list(deployment_id=deployment.id, has_error=True):
+    print(run.created_at, run.error.type, run.error.message)
+```
+
+```typescript
+for await (const run of client.beta.deploymentRuns.list({
+  deployment_id: deployment.id,
+  has_error: true,
+})) {
+  console.log(run.created_at, run.error?.type, run.error?.message);
+}
+```
+
+Raw HTTP: `GET /v1/deployment_runs?deployment_id=...&has_error=true`. To retrieve a single run by ID, `GET /v1/deployment_runs/{deployment_run_id}` (SDK: `client.beta.deployment_runs.retrieve(run_id)`) — a `deployment_run.*` webhook event carries the run ID as its `data.id`.
+
+A failed run looks like:
+
+```json
+{
+  "type": "deployment_run",
+  "id": "drun_01abc124",
+  "deployment_id": "depl_01xyz",
+  "trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
+  "session_id": null,
+  "error": { "type": "environment_archived", "message": "environment `env_01abc` is archived" },
+  "agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 },
+  "created_at": "2026-05-09T00:00:01Z"
+}
+```
+
+Error types include `environment_archived`, `agent_archived`, `vault_not_found`, `session_rate_limited`, and `service_unavailable`.
+
+The outcome of each **scheduled** run (started/succeeded/failed) and each deployment lifecycle change (created/updated/paused/unpaused/archived/deleted) is also delivered as a webhook event — see `shared/managed-agents-webhooks.md` for the `deployment.*` and `deployment_run.*` event types — so you can react without polling. Manual runs do **not** emit `deployment_run.*` webhook events.
+
+## Lifecycle: pause / unpause / archive
+
+| Operation | SDK | Effect |
+|---|---|---|
+| Pause | `client.beta.deployments.pause(id)` | Suppresses scheduled triggers go-forward. Sessions already running continue. **Manual runs are still permitted while paused.** Sets `paused_reason: {"type": "manual"}`. |
+| Unpause | `client.beta.deployments.unpause(id)` | Resumes from the next scheduled occurrence. **Missed triggers are not backfilled.** Clears `paused_reason`. |
+| Archive | `client.beta.deployments.archive(id)` | **Terminal** — the schedule stops and the deployment can no longer be modified. Use pause for anything reversible. |
+
+Raw HTTP: `POST /v1/deployments/{deployment_id}/pause` (likewise `/unpause`, `/archive`).
+
+### Failure behavior
+
+- **Rate-limited:** recorded immediately as a `session_rate_limited` run, **no retry** — the schedule simply tries again at the next occurrence. (Rate limits on API calls *inside* a session are handled by the session itself.)
+- **Other failed runs** (e.g. `environment_archived`, `vault_not_found`, `service_unavailable`): the run records the `error.type` — monitor runs and fix the referenced resource, or pause the deployment.
+- **Agent archived or deleted:** the deployment is automatically **archived** (terminal) and no further sessions are created.
+
+## Manual runs
+
+`POST /v1/deployments/{deployment_id}/run` (SDK: `client.beta.deployments.run(id)`) creates a session immediately and writes a run with `trigger_context.type: "manual"`. Use it to **test a deployment before committing to the schedule** — and remember it works even while the deployment is paused.

package/assets/skills/converted/claude-api/composable/mini/40-managed-agents-client-patterns.md

@@ -0,0 +1,211 @@
+# 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 — other languages follow the same shape; see `{lang}/managed-agents/README.md` (cURL and C#: `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 you can't or don't want to hand the secret to a vault.
+
+**First check:** for cloud environments, the first-class answer is now a vault `environment_variable` credential — the agent's shell sees an opaque placeholder and the real secret is substituted at egress. See `shared/managed-agents-tools.md` → Vaults. Use this pattern instead when that doesn't fit: **self-hosted sandboxes** (env-var credentials not yet supported there), clients that reject the placeholder via local format validation, secrets that must never leave your infrastructure, or calls that need host-side binaries.
+
+**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/assets/skills/converted/claude-api/composable/mini/41-managed-agents-onboarding.md

@@ -0,0 +1,82 @@
+# 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.
+
+Claude Managed Agents is a hosted agent: Anthropic runs the agent loop and provisions a sandboxed container per session where the agent's tools execute (or your own worker, with a `self_hosted` environment — see `shared/managed-agents-self-hosted-sandboxes.md`). You supply an **agent config** (tools, skills, model, system prompt — reusable, versioned) and an **environment config** (the sandbox — reusable across agents). Each run is a **session**.
+
+The flow is four beats — **describe → agent → environment → session** — the same arc as the Console quickstart, and the same philosophy: **value before credentials**. The user goes from idea to a runnable session before any auth ask; each credential is *flagged* at the moment the design makes it relevant (§2) and *collected* once, at session setup (§4), where it binds (`sessions.create()`) and gets exercised (smoke-test). Read `shared/managed-agents-core.md` alongside this — it has full detail for each knob; this doc is the interview script.
+
+---
+
+## 1. Describe the task
+
+**Open with a one-breath signpost and a single open prompt — don't guess, don't questionnaire.** In your own words:
+
+> Managed Agents is hosted — Anthropic runs the agent loop, the sandbox, and the infrastructure; you just define the agent. We'll do this in three moves: the agent, the environment it runs in, then a live test session. So: describe the agent you want — what should it do, and what kicks it off (a person, an event, a schedule)?
+
+Let them answer in full before configuring anything.
+
+## 2. Configure the agent — propose, don't interrogate
+
+Their description does the interview's work. Draft the agent config from it and **present it as a proposal with your suggestions inline** — the user reacts to a concrete config instead of answering a question list. At most one batched follow-up for true gaps. Suggest where the description gives you an opening:
+
+- **Tools** — enable the full prebuilt toolset by default (`agent_toolset_20260401`: `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`). **Suggest MCP servers** for any third-party service the job names (GitHub, Linear, Slack, …) — and flag the credential each one implies as you suggest it ("Linear MCP → you'll need a Linear API token at kickoff"), so §4's auth step is a formality, not a surprise. Collection itself waits for §4. Custom tools only if the user's own app must answer calls (name, description, input schema — their handler code is theirs; don't generate it).
+- **Skills** — **suggest** prebuilt `xlsx`/`docx`/`pptx`/`pdf` when the job produces those artifacts; custom by `skill_id` (max 20 total per agent, prebuilt + custom combined).
+- **Outcome** — if the description implies checkable "done" criteria (or you can elicit them in the follow-up: not "a good report" but "a CSV with a numeric `price` column per SKU"), **suggest an Outcome kickoff** — the harness grades and iterates against a rubric (`shared/managed-agents-outcomes.md`).
+- **On-hand resources** — repos on disk (`github_repository`: URL, optional `mount_path`/`checkout`; token comes in §4), files to seed (Files API upload → `{type: "file", file_id, mount_path}`; read-only), if the job references them.
+- **Model** — default `claude-opus-4-8`; `claude-fable-5` for the hardest long-horizon work (`shared/model-migration.md` → Migrating to Claude Fable 5).
+
+> ‼️ **PR creation needs the GitHub MCP server too** — a `github_repository` mount is filesystem-only. Edit in the mount → push branch via `bash` → open the PR via the MCP `create_pull_request` tool.
+
+Full detail per knob: `shared/managed-agents-tools.md` (toolset, MCP, custom tools, skills), `shared/managed-agents-environments.md` (repos, files).
+
+## 3. Environment
+
+Usually zero or one question:
+
+- **Reuse or create?** Environments are shared across agents — check for an existing one first.
+- **Networking** — default unrestricted egress. Switch to `limited` only if the user wants egress control — then set `allow_mcp_servers: true` or list every MCP server domain in `allowed_hosts`, or those tools fail silently.
+- **Suggest `self_hosted`** when the signals are there: tools must run on their own infra, secrets can't leave it, or they need binaries/data the cloud container won't have (`shared/managed-agents-self-hosted-sandboxes.md`; not available on Claude Platform on AWS). Otherwise `cloud` — don't raise it unprompted for simple jobs.
+
+## 4. Session — auth, then test run
+
+**Auth happens here — collect the credentials flagged in §2, now that the config is settled:** a vault (existing or `vaults.create()`) + `vaults.credentials.create()` for each MCP server declared in §2, `environment_variable` credentials for API keys the job uses (substituted at egress; the sandbox sees a placeholder), and the `authorization_token` for each repo mount. Credentials are write-only; MCP credentials match servers by URL and auto-refresh. See `shared/managed-agents-tools.md` → Vaults.
+
+**Silent viability gate — run this yourself before emitting anything; surface only the gaps.** Walk the job clause by clause: every verb maps to an enabled tool or MCP server ("open a PR" → GitHub MCP, not just the mount); every MCP server and repo mount has its credential from the auth step; every external host is reachable under the networking choice; every file/repo/dataset the job references is mounted; "done" is checkable. If something's missing, say so and resolve it — don't emit a config you already know is under-resourced.
+
+**Kickoff — pick one, never both:**
+- `user.message` — conversational.
+- `user.define_outcome` + rubric — when §2 settled on an Outcome; the harness iterates and grades until the rubric passes.
+- **Scheduled shape?** Skip per-session kickoff entirely — create a **deployment** (`deployments.create()` with `schedule` + `initial_events`); each firing creates the session autonomously. See `shared/managed-agents-scheduled-deployments.md`.
+
+Mechanics to bake into the runtime code: session creation blocks until resources mount (bad mounts surface there, before tokens); open the event stream *before* sending the kickoff; break on `session.status_terminated`, or `session.status_idle` with a terminal `stop_reason` — anything except `requires_action` (`shared/managed-agents-client-patterns.md` Pattern 5); usage lands on `span.model_request_end`; artifacts land in `/mnt/session/outputs/` (`files.list({scope_id: session.id, ...})`).
+
+## 5. Integrate — emit the code
+
+Go straight from the last answer to the code — no preamble, no lecture about setup-vs-runtime; the two-block structure shows it. Generate **two clearly-separated blocks**:
+
+**Block 1 — Setup (run once, store the IDs).** Prefer **YAML files + `ant` CLI** — agents and environments are version-controlled definitions users should check in and apply from CI:
+
+1. `<name>.agent.yaml` (flat: `name`, `model`, `system`, `tools`, `mcp_servers`, `skills`) and `<name>.environment.yaml`
+2. ```sh
+   AGENT_ID=$(ant beta:agents create < <name>.agent.yaml --transform id -r)
+   ENV_ID=$(ant beta:environments create < <name>.environment.yaml --transform id -r)
+   # CI sync: ant beta:agents update --agent-id "$AGENT_ID" --version N < <name>.agent.yaml
+   ```
+
+SDK fallback if the user asks — and **required on Claude Platform on AWS**, where auth is SigV4 and the `ant` CLI has no SigV4 mode (use the platform client from `shared/claude-platform-on-aws.md`): label it `# ONE-TIME SETUP — run once, save the IDs` and call `environments.create()` → `agents.create()`.
+
+> ⚠️ **Deployments are newer than the rest of the MA surface.** Before emitting `ant beta:deployments …` or `client.beta.deployments` / `client.beta.deployment_runs` calls, verify the user's installed CLI/SDK exposes them (`ant beta:deployments --help`; `hasattr(client.beta, "deployments")`). If not, emit raw HTTP against `POST /v1/deployments` with the `managed-agents-2026-04-01` beta header (plus `oauth-2025-04-20` when authenticating with a Bearer token from `ant auth print-credentials`), and leave an upgrade note marking what simplifies to SDK calls.
+
+**Scheduled shape? The deployment is setup, not runtime.** Create it in Block 1, after the agent/environment IDs exist (`deployments.create()` with `schedule` + `initial_events`). Block 2 is then **not** a session loop — there is no per-run kickoff to send. Emit instead: a manual-run trigger (`POST /v1/deployments/{id}/run`) so the user can test now rather than wait for the first firing — the manual run doubles as the smoke test — plus a fetch helper (latest `deployment_runs` entry → `session_id` → Console URL + `files.list(scope_id=session_id)` for the artifacts).
+
+**Block 2 — Runtime (every invocation; conversational and Outcome shapes).** SDK code in the detected language (Python/TS/cURL — SKILL.md → Language Detection); don't emit shell loops here:
+
+1. Load `agent_id` + `env_id` from config/env
+2. `sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])`, then print the Console URL so the user can watch live: `https://platform.claude.com/workspaces/default/sessions/{session.id}` (swap `default` for their workspace slug)
+3. **Smoke-test when the job depends on MCP servers, credentials, or locked-down hosts** — those failures don't surface at `sessions.create()`, only on first use. One cheap probe turn ("Confirm you can reach <service> and list 1–2 items; don't start the task"), verify, then send the real kickoff. Skip when there are no external dependencies.
+4. Open stream → send the §4 kickoff → loop with the terminal gate from §4.
+
+> ⚠️ **Never emit `agents.create()` and `sessions.create()` in the same unguarded block** — that teaches creating a new agent per run, the #1 anti-pattern. Single-script requests: wrap creation in `if not os.getenv("AGENT_ID"):`.
+
+Pull exact syntax from `{lang}/managed-agents/README.md` for your detected language (cURL and C#: use `curl/managed-agents.md` as the wire-level reference). Don't invent field names.