@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/control-plane/scripts/skills/claude-api/python/managed-agents/README.md

@@ -0,0 +1,335 @@
+# Managed Agents - Python
+
+> **Bindings not shown here:** This README covers the most common managed-agents flows for Python. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Python 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 `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. **Recommended:** define agents and environments as version-controlled YAML applied with the `ant` CLI - see `shared/anthropic-cli.md` (its live-docs URL is in `shared/live-sources.md`). The CLI owns the control plane (create/update); your code owns the data plane (sessions with the stored ID). The examples below show in-code creation for when you must provision programmatically; in production the create call belongs in setup, not in the request path.
+
+## Installation
+
+```bash
+pip install anthropic
+```
+
+## Client Initialization
+
+```python
+import anthropic
+
+# Default - resolves credentials from the environment:
+# ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
+# Prefer this for local dev; don't hardcode a key.
+client = anthropic.Anthropic()
+
+# Explicit API key (only when you must inject a specific key)
+client = anthropic.Anthropic(api_key="your-api-key")
+```
+
+---
+
+## Create an Environment
+
+```python
+environment = client.beta.environments.create(
+    name="my-dev-env",
+    config={
+        "type": "cloud",
+        "networking": {"type": "unrestricted"},
+    },
+)
+print(environment.id)  # env_...
+```
+
+---
+
+## Create an Agent (required first step)
+
+> Warning: **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` - the session only takes `agent={"type": "agent", "id": agent.id}`.
+
+### Minimal
+
+```python
+# 1. Create the agent (reusable, versioned)
+agent = client.beta.agents.create(
+    name="Coding Assistant",
+    model="claude-opus-5",
+    tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}],
+)
+
+# 2. Start a session
+session = client.beta.sessions.create(
+    agent={"type": "agent", "id": agent.id, "version": agent.version},
+    environment_id=environment.id,
+)
+print(session.id, session.status)
+print(f"Trace: https://platform.claude.com/workspaces/default/sessions/{session.id}")  # swap 'default' for your workspace ID if the API key is not in the Default workspace
+```
+
+### With system prompt and custom tools
+
+```python
+import os
+
+agent = client.beta.agents.create(
+    name="Code Reviewer",
+    model="claude-opus-5",
+    system="You are a senior code reviewer.",
+    tools=[
+        {"type": "agent_toolset_20260401"},
+        {
+            "type": "custom",
+            "name": "run_tests",
+            "description": "Run the test suite",
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "test_path": {"type": "string", "description": "Path to test file"}
+                },
+                "required": ["test_path"],
+            },
+        },
+    ],
+)
+
+session = client.beta.sessions.create(
+    agent={"type": "agent", "id": agent.id, "version": agent.version},
+    environment_id=environment.id,
+    title="Code review session",
+    resources=[
+        {
+            "type": "github_repository",
+            "url": "https://github.com/owner/repo",
+            "mount_path": "/workspace/repo",
+            "authorization_token": os.environ["GITHUB_TOKEN"],
+            "branch": "main",
+        }
+    ],
+)
+```
+
+---
+
+## Send a User Message
+
+```python
+client.beta.sessions.events.send(
+    session_id=session.id,
+    events=[
+        {
+            "type": "user.message",
+            "content": [{"type": "text", "text": "Review the auth module"}],
+        }
+    ],
+)
+```
+
+> Tip: **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)
+
+```python
+import json
+
+# Stream-first: open stream, then send while stream is live
+with client.beta.sessions.events.stream(
+    session_id=session.id,
+) as stream:
+    client.beta.sessions.events.send(
+        session_id=session.id,
+        events=[{"type": "user.message", "content": [{"type": "text", "text": "..."}]}],
+    )
+    for event in stream:
+        ...  # process events
+
+# Standalone stream iteration:
+with client.beta.sessions.events.stream(
+    session_id=session.id,
+) as stream:
+    for event in stream:
+        if event.type == "agent.message":
+            for block in event.content:
+                if block.type == "text":
+                    print(block.text, end="", flush=True)
+        elif event.type == "agent.custom_tool_use":
+            # Custom tool invocation - session is now idle
+            print(f"\nCustom tool call: {event.name}")
+            print(f"Input: {json.dumps(event.input)}")
+            # Send result back (see below)
+        elif event.type == "session.status_idle":
+            print("\n--- Agent idle ---")
+        elif event.type == "session.status_terminated":
+            print("\n--- Session terminated ---")
+            break
+```
+
+---
+
+## Provide Custom Tool Result
+
+```python
+client.beta.sessions.events.send(
+    session_id=session.id,
+    events=[
+        {
+            "type": "user.custom_tool_result",
+            "custom_tool_use_id": "sevt_abc123",
+            "content": [{"type": "text", "text": "All 42 tests passed."}],
+        }
+    ],
+)
+```
+
+---
+
+## Poll Events
+
+```python
+events = client.beta.sessions.events.list(
+    session_id=session.id,
+)
+for event in events.data:
+    print(f"{event.type}: {event.id}")
+```
+
+> Warning: **Prefer the SDK over raw `requests`/`httpx`.** If you hand-roll a poll loop, don't assume `timeout=(5, 60)` or `httpx.Timeout(120)` caps total call duration - both are **per-chunk** read timeouts (reset on every byte), so a trickling response can block forever. For a hard wall-clock deadline, track `time.monotonic()` at the loop level and bail explicitly, or wrap with `asyncio.wait_for()`. See [Receiving Events](../../shared/managed-agents-events.md#receiving-events).
+
+---
+
+## Full Streaming Loop with Custom Tools
+
+```python
+import json
+
+
+def run_custom_tool(tool_name: str, tool_input: dict) -> str:
+    """Execute a custom tool and return the result."""
+    if tool_name == "run_tests":
+        # Your tool implementation here
+        return "All tests passed."
+    return f"Unknown tool: {tool_name}"
+
+
+def run_session(client, session_id: str):
+    """Stream events and handle custom tool calls."""
+    while True:
+        with client.beta.sessions.events.stream(
+            session_id=session_id,
+        ) as stream:
+            tool_calls = []
+            for event in stream:
+                if event.type == "agent.message":
+                    for block in event.content:
+                        if block.type == "text":
+                            print(block.text, end="", flush=True)
+                elif event.type == "agent.custom_tool_use":
+                    tool_calls.append(event)
+                elif event.type == "session.status_idle":
+                    break
+                elif event.type == "session.status_terminated":
+                    return
+
+        if not tool_calls:
+            break
+
+        # Process custom tool calls
+        results = []
+        for call in tool_calls:
+            result = run_custom_tool(call.name, call.input)
+            results.append({
+                "type": "user.custom_tool_result",
+                "custom_tool_use_id": call.id,
+                "content": [{"type": "text", "text": result}],
+            })
+
+        client.beta.sessions.events.send(
+            session_id=session_id,
+            events=results,
+        )
+```
+
+---
+
+## Upload a File
+
+```python
+with open("data.csv", "rb") as f:
+    file = client.beta.files.upload(
+        file=f,
+    )
+
+# Use in a session
+session = client.beta.sessions.create(
+    agent={"type": "agent", "id": agent.id, "version": agent.version},
+    environment_id=environment.id,
+    resources=[{"type": "file", "file_id": file.id, "mount_path": "/workspace/data.csv"}],
+)
+```
+
+---
+
+## List and Download Session Files
+
+List files the agent wrote to `/mnt/session/outputs/` during a session, then download them.
+
+```python
+# List files associated with a session
+files = client.beta.files.list(
+    scope_id=session.id,
+    betas=["managed-agents-2026-04-01"],
+)
+for f in files.data:
+    print(f.filename, f.size_bytes)
+    # Download each file and save to disk
+    file_content = client.beta.files.download(f.id)
+    file_content.write_to_file(f.filename)
+```
+
+> Tip: There's a brief indexing lag (~1-3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if the list is empty.
+
+---
+
+## Session Management
+
+```python
+# Get session details
+session = client.beta.sessions.retrieve(session_id="sesn_011CZxAbc123Def456")
+print(session.status, session.usage)
+
+# List sessions
+sessions = client.beta.sessions.list()
+
+# Delete a session
+client.beta.sessions.delete(session_id="sesn_011CZxAbc123Def456")
+
+# Archive a session
+client.beta.sessions.archive(session_id="sesn_011CZxAbc123Def456")
+```
+
+---
+
+## MCP Server Integration
+
+```python
+# Agent declares MCP server (no auth here - auth goes in a vault)
+agent = client.beta.agents.create(
+    name="MCP Agent",
+    model="claude-opus-5",
+    mcp_servers=[
+        {"type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse"},
+    ],
+    tools=[
+        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
+        {"type": "mcp_toolset", "mcp_server_name": "my-tools"},
+    ],
+)
+
+# Session attaches vault(s) containing credentials for those MCP server URLs
+session = client.beta.sessions.create(
+    agent=agent.id,
+    environment_id=environment.id,
+    vault_ids=[vault.id],
+)
+```
+
+See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.

package/control-plane/scripts/skills/claude-api/ruby/claude-api/README.md

@@ -0,0 +1,134 @@
+# Claude API - Ruby
+
+> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby.
+
+## 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")
+```
+
+---
+
+## Basic Message Request
+
+```ruby
+message = client.messages.create(
+  model: :"claude-opus-5",
+  max_tokens: 16000,
+  messages: [
+    { role: "user", content: "What is the capital of France?" }
+  ]
+)
+# content is an array of polymorphic block objects (TextBlock, ThinkingBlock,
+# ToolUseBlock, ...). .type is a Symbol - compare with :text, not "text".
+# .text raises NoMethodError on non-TextBlock entries.
+message.content.each do |block|
+  puts block.text if block.type == :text
+end
+```
+
+---
+
+## Extended Thinking
+
+> **Fable 5, Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Claude Opus 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Claude Opus 5:** thinking is on by default - omitting `thinking:` runs adaptive (`{ type: "adaptive" }` is equivalent), unlike Opus 4.8/4.7 where omitting it meant no thinking. `{ type: "disabled" }` is accepted only at effort `high` or lower; pairing it with `xhigh`/`max` returns a 400.
+> **Older models:** Use `thinking: { type: "enabled", budget_tokens: N }` (must be < `max_tokens`, min 1024).
+
+```ruby
+message = client.messages.create(
+  model: :"claude-opus-5",
+  max_tokens: 16000,
+  thinking: { type: "adaptive" },
+  messages: [{ role: "user", content: "Solve: 27 * 453" }]
+)
+
+message.content.each do |block|
+  case block.type
+  when :thinking then puts "Thinking: #{block.thinking}"
+  when :text then puts "Response: #{block.text}"
+  end
+end
+```
+
+---
+
+## Prompt Caching
+
+`system_:` (trailing underscore - avoids shadowing `Kernel#system`) takes an array of text blocks; set `cache_control` on the last block. Plain hashes work via the `OrHash` type alias. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
+
+```ruby
+message = client.messages.create(
+  model: :"claude-opus-5",
+  max_tokens: 16000,
+  system_: [
+    { type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } }
+  ],
+  messages: [{ role: "user", content: "Summarize the key points" }]
+)
+```
+
+For 1-hour TTL: `cache_control: { type: "ephemeral", ttl: "1h" }`. There's also a top-level `cache_control:` on `messages.create` that auto-places on the last cacheable block.
+
+Verify hits via `message.usage.cache_creation_input_tokens` / `message.usage.cache_read_input_tokens`.
+
+---
+
+## Stop Details
+
+When `stop_reason` is `:refusal`, the response includes structured `stop_details`:
+
+```ruby
+if message.stop_reason == :refusal && message.stop_details
+  puts "Category: #{message.stop_details.category}"     # e.g. :cyber, :bio, :reasoning_extraction, :frontier_llm, or nil - see docs for the full set
+  puts "Explanation: #{message.stop_details.explanation}"
+end
+```
+
+**Refusal fallbacks (Claude Fable 5.1) - opt in by default.** Fallbacks are opt-in: without them a refused request simply stops. New `claude-fable-5-1` code should include the server-side `fallbacks` parameter (beta header `server-side-fallback-2026-06-01`, `fallbacks: [{model: "claude-opus-4-8"}]` on the beta messages call) by default. The exact Ruby binding (and the client-side middleware for providers without server-side support) is not documented here - WebFetch the Ruby SDK repo's `examples/` from `shared/live-sources.md`; full semantics in `shared/model-migration.md` -> Migrating to Claude Fable 5.1 -> `refusal` stop reason.
+
+---
+
+## Beta Features
+
+`betas:` is only valid on `client.beta.messages.create`, not the non-beta path.
+
+### Task budgets
+
+```ruby
+response = client.beta.messages.create(
+  model: :"claude-opus-5",
+  max_tokens: 16000,
+  output_config: { task_budget: { type: :tokens, total: 64_000 } },
+  tools: [...],
+  messages: [...],
+  betas: ["task-budgets-2026-03-13"]
+)
+```
+
+---
+
+## Error Type
+
+`APIStatusError` exposes a `.type` field for programmatic error classification:
+
+```ruby
+begin
+  client.messages.create(...)
+rescue Anthropic::Errors::APIStatusError => e
+  puts e.type  # :rate_limit_error, :overloaded_error, etc.
+end
+```

package/control-plane/scripts/skills/claude-api/ruby/claude-api/streaming.md

@@ -0,0 +1,16 @@
+# Streaming - Ruby
+
+## Streaming
+
+```ruby
+stream = client.messages.stream(
+  model: :"claude-opus-5",
+  max_tokens: 64000,
+  messages: [{ role: "user", content: "Write a haiku" }]
+)
+
+stream.text.each { |text| print(text) }
+```
+
+---
+

package/control-plane/scripts/skills/claude-api/ruby/claude-api/tool-use.md

@@ -0,0 +1,41 @@
+# Tool Use - Ruby
+
+For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md).
+
+## Tool Use
+
+The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.
+
+### Tool Runner (Beta)
+
+```ruby
+class GetWeatherInput < Anthropic::BaseModel
+  required :location, String, doc: "City and state, e.g. San Francisco, CA"
+end
+
+class GetWeather < Anthropic::BaseTool
+  doc "Get the current weather for a location"
+
+  input_schema GetWeatherInput
+
+  def call(input)
+    "The weather in #{input.location} is sunny and 72°F."
+  end
+end
+
+client.beta.messages.tool_runner(
+  model: :"claude-opus-5",
+  max_tokens: 16000,
+  tools: [GetWeather.new],
+  messages: [{ role: "user", content: "What's the weather in San Francisco?" }]
+).each_message do |message|
+  puts message.content
+end
+```
+
+### Manual Loop
+
+See the [shared tool use concepts](../../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern.
+
+---
+