hive-skills 0.1.0

package/assets/skills/converted/claude-api/composable/mini/82-ruby-managed-agents.md

@@ -0,0 +1,394 @@
+# Managed Agents — Ruby
+
+> **Bindings not shown here:** This README covers the most common managed-agents flows for Ruby. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Ruby SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
+
+> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta.agents.create` and pass it to every subsequent `client.beta.sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
+
+## Installation
+
+```bash
+gem install anthropic
+```
+
+## Client Initialization
+
+```ruby
+require "anthropic"
+
+# Default (uses ANTHROPIC_API_KEY env var)
+client = Anthropic::Client.new
+
+# Explicit API key
+client = Anthropic::Client.new(api_key: "your-api-key")
+```
+
+> ⚠️ **Trailing underscores:** The Ruby SDK uses `system_:` and `send_(` (trailing underscore) to avoid shadowing `Kernel#system` and `Kernel#send`. Use these forms throughout managed-agents code.
+
+---
+
+## Create an Environment
+
+```ruby
+environment = client.beta.environments.create(
+  name: "my-dev-env",
+  config: {
+    type: "cloud",
+    networking: {type: "unrestricted"}
+  }
+)
+puts "Environment ID: #{environment.id}" # env_...
+```
+
+---
+
+## Create an Agent (required first step)
+
+> ⚠️ **There is no inline agent config.** `model`/`system_`/`tools` live on the agent object, not the session. Always start with `client.beta.agents.create()` — the session takes either `agent: agent.id` or the typed hash form `agent: {type: "agent", id: agent.id, version: agent.version}`.
+
+### Minimal
+
+```ruby
+# 1. Create the agent (reusable, versioned)
+agent = client.beta.agents.create(
+  name: "Coding Assistant",
+  model: :"claude-opus-4-8",
+  system_: "You are a helpful coding assistant.",
+  tools: [{type: "agent_toolset_20260401"}]
+)
+
+# 2. Start a session
+session = client.beta.sessions.create(
+  agent: {type: "agent", id: agent.id, version: agent.version},
+  environment_id: environment.id,
+  title: "Quickstart session"
+)
+puts "Session ID: #{session.id}"
+puts "Trace: https://platform.claude.com/workspaces/default/sessions/#{session.id}"
+```
+
+### Updating an Agent
+
+Updates create new versions; the agent object is immutable per version.
+
+```ruby
+updated_agent = client.beta.agents.update(
+  agent.id,
+  version: agent.version,
+  system_: "You are a helpful coding agent. Always write tests."
+)
+puts "New version: #{updated_agent.version}"
+
+# List all versions
+client.beta.agents.versions.list(agent.id).auto_paging_each do |version|
+  puts "Version #{version.version}: #{version.updated_at.iso8601}"
+end
+
+# Archive the agent
+archived = client.beta.agents.archive(agent.id)
+puts "Archived at: #{archived.archived_at.iso8601}"
+```
+
+---
+
+## Send a User Message
+
+```ruby
+client.beta.sessions.events.send_(
+  session.id,
+  events: [{
+    type: "user.message",
+    content: [{type: "text", text: "Review the auth module"}]
+  }]
+)
+```
+
+> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns).
+
+---
+
+## Stream Events (SSE)
+
+```ruby
+# Open the stream first, then send the user message
+stream = client.beta.sessions.events.stream_events(session.id)
+
+client.beta.sessions.events.send_(
+  session.id,
+  events: [{
+    type: "user.message",
+    content: [{type: "text", text: "Summarize the repo README"}]
+  }]
+)
+
+stream.each do |event|
+  case event.type
+  in :"agent.message"
+    event.content.each { |block| print block.text }
+  in :"agent.tool_use"
+    puts "\n[Using tool: #{event.name}]"
+  in :"session.status_idle"
+    break
+  in :"session.error"
+    puts "\n[Error: #{event.error&.message || "unknown"}]"
+    break
+  else
+    # ignore other event types
+  end
+end
+```
+
+> ℹ️ Event `.type` is a Symbol (compare with `:"agent.message"`, not `"agent.message"`).
+
+### Reconnecting and Tailing
+
+When reconnecting mid-session, list past events first to dedupe, then tail live events:
+
+```ruby
+require "set"
+
+stream = client.beta.sessions.events.stream_events(session.id)
+
+# Stream is open and buffering. List history before tailing live.
+seen_event_ids = Set.new
+client.beta.sessions.events.list(session.id).auto_paging_each { |past| seen_event_ids << past.id }
+
+# Tail live events, skipping anything already seen
+stream.each do |event|
+  next if seen_event_ids.include?(event.id)
+  seen_event_ids << event.id
+  case event.type
+  in :"agent.message"
+    event.content.each { |block| print block.text }
+  in :"session.status_idle"
+    break
+  else
+    # ignore other event types
+  end
+end
+```
+
+---
+
+## Provide Custom Tool Result
+
+> ℹ️ The Ruby managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic` Ruby gem repository for the corresponding params.
+
+---
+
+## Poll Events
+
+```ruby
+client.beta.sessions.events.list(session.id).auto_paging_each do |event|
+  puts "#{event.type}: #{event.id}"
+end
+```
+
+---
+
+## Upload a File
+
+```ruby
+require "pathname"
+
+file = client.beta.files.upload(file: Pathname("data.csv"))
+puts "File ID: #{file.id}"
+
+# Mount in a session
+session = client.beta.sessions.create(
+  agent: agent.id,
+  environment_id: environment.id,
+  resources: [
+    {
+      type: "file",
+      file_id: file.id,
+      mount_path: "/workspace/data.csv"
+    }
+  ]
+)
+```
+
+### Add and Manage Resources on an Existing Session
+
+```ruby
+# Attach an additional file to an open session
+resource = client.beta.sessions.resources.add(
+  session.id,
+  type: "file",
+  file_id: file.id
+)
+puts resource.id # "sesrsc_01ABC..."
+
+# List resources on the session
+listed = client.beta.sessions.resources.list(session.id)
+listed.data.each { |entry| puts "#{entry.id} #{entry.type}" }
+
+# Detach a resource
+client.beta.sessions.resources.delete(resource.id, session_id: session.id)
+```
+
+---
+
+## List and Download Session Files
+
+```ruby
+files = client.beta.files.list(scope_id: "sesn_abc123", betas: ["managed-agents-2026-04-01"])
+content = client.beta.files.download(files.data[0].id)
+File.binwrite("output.txt", content.read)
+```
+
+---
+
+## Session Management
+
+```ruby
+# List environments
+environments = client.beta.environments.list
+
+# Retrieve a specific environment
+env = client.beta.environments.retrieve(environment.id)
+
+# Archive an environment (read-only, existing sessions continue)
+client.beta.environments.archive(environment.id)
+
+# Delete an environment (only if no sessions reference it)
+client.beta.environments.delete(environment.id)
+
+# Delete a session
+client.beta.sessions.delete(session.id)
+```
+
+---
+
+## MCP Server Integration
+
+```ruby
+# Agent declares MCP server (no auth here — auth goes in a vault)
+agent = client.beta.agents.create(
+  name: "GitHub Assistant",
+  model: :"claude-opus-4-8",
+  mcp_servers: [
+    {
+      type: "url",
+      name: "github",
+      url: "https://api.githubcopilot.com/mcp/"
+    }
+  ],
+  tools: [
+    {type: "agent_toolset_20260401"},
+    {type: "mcp_toolset", mcp_server_name: "github"}
+  ]
+)
+
+# Session attaches vault(s) containing credentials for those MCP server URLs
+session = client.beta.sessions.create(
+  agent: {type: "agent", id: agent.id, version: agent.version},
+  environment_id: environment.id,
+  vault_ids: [vault.id]
+)
+```
+
+See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
+
+---
+
+## Vaults
+
+```ruby
+# Create a vault
+vault = client.beta.vaults.create(
+  display_name: "Alice",
+  metadata: {external_user_id: "usr_abc123"}
+)
+puts vault.id # "vlt_01ABC..."
+
+# Add an OAuth credential
+credential = client.beta.vaults.credentials.create(
+  vault.id,
+  display_name: "Alice's Slack",
+  auth: {
+    type: "mcp_oauth",
+    mcp_server_url: "https://mcp.slack.com/mcp",
+    access_token: "xoxp-...",
+    expires_at: "2026-04-15T00:00:00Z",
+    refresh: {
+      token_endpoint: "https://slack.com/api/oauth.v2.access",
+      client_id: "1234567890.0987654321",
+      scope: "channels:read chat:write",
+      refresh_token: "xoxe-1-...",
+      token_endpoint_auth: {
+        type: "client_secret_post",
+        client_secret: "abc123..."
+      }
+    }
+  }
+)
+
+# Rotate the credential (e.g., after a token refresh)
+client.beta.vaults.credentials.update(
+  credential.id,
+  vault_id: vault.id,
+  auth: {
+    type: "mcp_oauth",
+    access_token: "xoxp-new-...",
+    expires_at: "2026-05-15T00:00:00Z",
+    refresh: {refresh_token: "xoxe-1-new-..."}
+  }
+)
+
+# Archive a vault
+client.beta.vaults.archive(vault.id)
+```
+
+---
+
+## GitHub Repository Integration
+
+Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential):
+
+```ruby
+session = client.beta.sessions.create(
+  agent: agent.id,
+  environment_id: environment.id,
+  vault_ids: [vault.id],
+  resources: [
+    {
+      type: "github_repository",
+      url: "https://github.com/org/repo",
+      mount_path: "/workspace/repo",
+      authorization_token: "ghp_your_github_token"
+    }
+  ]
+)
+```
+
+Multiple repositories on the same session:
+
+```ruby
+resources = [
+  {
+    type: "github_repository",
+    url: "https://github.com/org/frontend",
+    mount_path: "/workspace/frontend",
+    authorization_token: "ghp_your_github_token"
+  },
+  {
+    type: "github_repository",
+    url: "https://github.com/org/backend",
+    mount_path: "/workspace/backend",
+    authorization_token: "ghp_your_github_token"
+  }
+]
+```
+
+Rotating a repository's authorization token:
+
+```ruby
+listed = client.beta.sessions.resources.list(session.id)
+repo_resource_id = listed.data.first.id
+
+client.beta.sessions.resources.update(
+  repo_resource_id,
+  session_id: session.id,
+  authorization_token: "ghp_your_new_github_token"
+)
+```

package/assets/skills/converted/claude-api/composable/mini/85-curl-examples.md

@@ -0,0 +1,255 @@
+# Claude API — cURL / Raw HTTP
+
+Use these examples when the user needs raw HTTP requests or is working in a language without an official SDK.
+
+## Setup
+
+```bash
+export ANTHROPIC_API_KEY="your-api-key"
+```
+
+---
+
+## Basic Message Request
+
+```bash
+curl https://api.anthropic.com/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -d '{
+    "model": "claude-opus-4-8",
+    "max_tokens": 16000,
+    "messages": [
+      {"role": "user", "content": "What is the capital of France?"}
+    ]
+  }'
+```
+
+### Parsing the response
+
+Use `jq` to extract fields from the JSON response. Do not use `grep`/`sed` —
+JSON strings can contain any character and regex parsing will break on quotes,
+escapes, or multi-line content.
+
+```bash
+# Capture the response, then extract fields
+response=$(curl -s https://api.anthropic.com/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -d '{"model":"claude-opus-4-8","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}')
+
+# Print the first text block (-r strips the JSON quotes)
+echo "$response" | jq -r '.content[0].text'
+
+# Read usage fields
+input_tokens=$(echo "$response" | jq -r '.usage.input_tokens')
+output_tokens=$(echo "$response" | jq -r '.usage.output_tokens')
+
+# Read stop reason (for tool-use loops)
+stop_reason=$(echo "$response" | jq -r '.stop_reason')
+
+# Extract all text blocks (content is an array; filter to type=="text")
+echo "$response" | jq -r '.content[] | select(.type == "text") | .text'
+```
+
+
+---
+
+## Streaming (SSE)
+
+```bash
+curl https://api.anthropic.com/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -d '{
+    "model": "claude-opus-4-8",
+    "max_tokens": 64000,
+    "stream": true,
+    "messages": [{"role": "user", "content": "Write a haiku"}]
+  }'
+```
+
+The response is a stream of Server-Sent Events:
+
+```
+event: message_start
+data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}}
+
+event: content_block_start
+data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
+
+event: content_block_stop
+data: {"type":"content_block_stop","index":0}
+
+event: message_delta
+data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}
+
+event: message_stop
+data: {"type":"message_stop"}
+```
+
+---
+
+## Tool Use
+
+```bash
+curl https://api.anthropic.com/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -d '{
+    "model": "claude-opus-4-8",
+    "max_tokens": 16000,
+    "tools": [{
+      "name": "get_weather",
+      "description": "Get current weather for a location",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "location": {"type": "string", "description": "City name"}
+        },
+        "required": ["location"]
+      }
+    }],
+    "messages": [{"role": "user", "content": "What is the weather in Paris?"}]
+  }'
+```
+
+When Claude responds with a `tool_use` block, send the result back:
+
+```bash
+curl https://api.anthropic.com/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -d '{
+    "model": "claude-opus-4-8",
+    "max_tokens": 16000,
+    "tools": [{
+      "name": "get_weather",
+      "description": "Get current weather for a location",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "location": {"type": "string", "description": "City name"}
+        },
+        "required": ["location"]
+      }
+    }],
+    "messages": [
+      {"role": "user", "content": "What is the weather in Paris?"},
+      {"role": "assistant", "content": [
+        {"type": "text", "text": "Let me check the weather."},
+        {"type": "tool_use", "id": "toolu_abc123", "name": "get_weather", "input": {"location": "Paris"}}
+      ]},
+      {"role": "user", "content": [
+        {"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "72°F and sunny"}
+      ]}
+    ]
+  }'
+```
+
+---
+
+## Prompt Caching
+
+Put `cache_control` on the last block of the stable prefix. See `shared/prompt-caching.md` for placement patterns and the silent-invalidator audit checklist.
+
+```bash
+curl https://api.anthropic.com/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -d '{
+    "model": "claude-opus-4-8",
+    "max_tokens": 16000,
+    "system": [
+      {"type": "text", "text": "<large shared prompt...>", "cache_control": {"type": "ephemeral"}}
+    ],
+    "messages": [{"role": "user", "content": "Summarize the key points"}]
+  }'
+```
+
+For 1-hour TTL: `"cache_control": {"type": "ephemeral", "ttl": "1h"}`. Top-level `"cache_control"` on the request body auto-places on the last cacheable block. Verify hits via the response `usage.cache_creation_input_tokens` / `usage.cache_read_input_tokens` fields.
+
+---
+
+## Extended Thinking
+
+> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Older models:** Use `"type": "enabled"` with `"budget_tokens": N` (must be < `max_tokens`, min 1024).
+
+```bash
+# Fable 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
+curl https://api.anthropic.com/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -d '{
+    "model": "claude-opus-4-8",
+    "max_tokens": 16000,
+    "thinking": {
+      "type": "adaptive",
+      "display": "summarized"
+    },
+    "output_config": {
+      "effort": "high"
+    },
+    "messages": [{"role": "user", "content": "Solve this step by step..."}]
+  }'
+```
+
+---
+
+## Refusal Fallbacks (Claude Fable 5) — opt in by default
+
+On `claude-fable-5`, safety classifiers may decline a request (HTTP 200 with `stop_reason: "refusal"`). Fallbacks are **opt-in**: without them the request simply stops. Include the `fallbacks` parameter and its beta header by default — on a policy decline the API re-runs the same request on the fallback model inside the same call. A decline before any output isn't billed (a mid-stream decline bills the streamed partial); the rescue bills at the fallback model's own rates.
+
+```bash
+response=$(curl -s https://api.anthropic.com/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "anthropic-beta: server-side-fallback-2026-06-01" \
+  -d '{
+    "model": "claude-fable-5",
+    "max_tokens": 16000,
+    "fallbacks": [{"model": "claude-opus-4-8"}],
+    "messages": [{"role": "user", "content": "Hello"}]
+  }')
+
+# Which model produced the message
+echo "$response" | jq -r '.model'
+
+# Refusal on the final response means the whole chain refused
+echo "$response" | jq -r '.stop_reason'
+
+# Switch points: one fallback block per model that ran and declined this turn
+echo "$response" | jq -r '.content[] | select(.type == "fallback") | "\(.from.model) declined; \(.to.model) continued"'
+
+# Served-by signal — covers sticky turns, which carry no fallback block.
+# Pair with stop_reason: the fallback model can itself refuse.
+if [ "$(echo "$response" | jq -r '.stop_reason')" != "refusal" ] && \
+   echo "$response" | jq -e '[.usage.iterations[]? | select(.type == "fallback_message")] | length > 0' > /dev/null; then
+  echo "fallback model served this turn"
+fi
+```
+
+The header must be exactly `server-side-fallback-2026-06-01`. The parameter is rejected on the Batches API and unavailable on Amazon Bedrock, Vertex AI, and Microsoft Foundry. Full semantics (sticky routing, billing, streaming, echoing fallback turns back): `shared/model-migration.md` → Migrating to Claude Fable 5 → `refusal` stop reason.
+
+---
+
+## Required Headers
+
+| Header              | Value              | Description                |
+| ------------------- | ------------------ | -------------------------- |
+| `Content-Type`      | `application/json` | Required                   |
+| `x-api-key`         | Your API key       | Authentication             |
+| `anthropic-version` | `2023-06-01`       | API version                |
+| `anthropic-beta`    | Beta feature IDs   | Required for beta features |