anymous 1.2.6 → 1.3.0

package/skills/claude-api/ruby/managed-agents/README.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. **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
+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-5",
+  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}"  # swap 'default' for your workspace ID if the API key is not in the Default workspace
+```
+
+### 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-5",
+  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/skills/claude-api/shared/agent-design.md

@@ -0,0 +1,101 @@
+# Agent Design Patterns
+
+This file covers decision heuristics for building agents on the Claude API: which primitives to reach for, how to design your tool surface, and how to manage context and cost over long runs. For per-tool mechanics and code examples, see `tool-use-concepts.md` and the language-specific folders.
+
+---
+
+## Model Parameters
+
+| Parameter | When to use it | What to expect |
+| --- | --- | --- |
+| **Adaptive thinking** (`thinking: {type: "adaptive"}`) | When you want Claude to control when and how much to think. | Claude determines thinking depth per request and automatically interleaves thinking between tool calls. No token budget to tune. |
+| **Effort** (`output_config: {effort: ...}`) | When adjusting the tradeoff between thoroughness and token efficiency. | Lower effort → fewer and more-consolidated tool calls, less preamble, terser confirmations. `medium` is often a favorable balance. Use `max` when correctness matters more than cost. |
+
+See `SKILL.md` §Thinking & Effort for model support and parameter details.
+
+---
+
+## Designing Your Tool Surface
+
+### Bash vs. dedicated tools
+
+Claude doesn't know your application's security boundary, approval policy, or UX surface. Claude emits tool calls; your harness handles them. The shape of those tool calls determines what the harness can do.
+
+A **bash tool** gives Claude broad programmatic leverage — it can perform almost any action. But it gives the harness only an opaque command string, the same shape for every action. Promoting an action to a **dedicated tool** gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit.
+
+**When to promote an action to a dedicated tool:**
+
+- **Security boundary.** Actions that require gating are natural candidates. Reversibility is a useful criterion: hard-to-reverse actions (external API calls, sending messages, deleting data) can be gated behind user confirmation. A `send_email` tool is easy to gate; `bash -c "curl -X POST ..."` is not.
+- **Staleness checks.** A dedicated `edit` tool can reject writes if the file changed since Claude last read it. Bash can't enforce that invariant.
+- **Rendering.** Some actions benefit from custom UI. Claude Code promotes question-asking to a tool so it can render as a modal, present options, and block the agent loop until answered.
+- **Scheduling.** Read-only tools like `glob` and `grep` can be marked parallel-safe. When the same actions run through bash, the harness can't tell a parallel-safe `grep` from a parallel-unsafe `git push`, so it must serialize.
+
+**Rule of thumb:** Start with bash for breadth. Promote to dedicated tools when you need to gate, render, audit, or parallelize the action.
+
+---
+
+## Anthropic-Provided Tools
+
+| Tool | Side | When to use it | What to expect |
+| --- | --- | --- | --- |
+| **Bash** | Client | Claude needs to execute shell commands. | Claude emits commands; your harness executes them. Reference implementation provided. |
+| **Text editor** | Client | Claude needs to read or edit files. | Claude views, creates, and edits files via your implementation. Reference implementation provided. |
+| **Computer use** | Client or Server | Claude needs to interact with GUIs, web apps, or visual interfaces. | Claude takes screenshots and issues mouse/keyboard commands. Can be self-hosted (you run the environment) or Anthropic-hosted. |
+| **Code execution** | Server | Claude needs to run code in a sandbox you don't want to manage. | Anthropic-hosted container with built-in file and bash sub-tools. No client-side execution. |
+| **Web search / fetch** | Server | Claude needs information past its training cutoff (news, current events, recent docs) or the content of a specific URL. | Claude issues a query or URL; Anthropic executes it and returns results with citations. |
+| **Memory** | Client | Claude needs to save context across sessions. | Claude reads/writes a `/memories` directory. You implement the storage backend. |
+
+**Client-side** tools are defined by Anthropic (name, schema, Claude's usage pattern) but executed by your harness. Anthropic provides reference implementations. **Server-side** tools run entirely on Anthropic infrastructure — declare them in `tools` and Claude handles the rest.
+
+---
+
+## Composing Tool Calls: Programmatic Tool Calling
+
+With standard tool use, each tool call is a round trip: Claude calls the tool, the result lands in Claude's context, Claude reasons about it, then calls the next tool. Three sequential actions (read profile → look up orders → check inventory) means three round trips. Each adds latency and tokens, and most of the intermediate data is never needed again.
+
+**Programmatic tool calling (PTC)** lets Claude compose those calls into a script instead. The script runs in the code execution container. When the script calls a tool, the container pauses, the call is executed (client-side or server-side), and the result returns to the running code — not to Claude's context. The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude.
+
+| When to use it | What to expect |
+| --- | --- |
+| Many sequential tool calls, or large intermediate results you want filtered before they hit the context window. | Claude writes code that invokes tools as functions. Runs in the code execution container. Token cost scales with final output, not intermediate results. |
+
+---
+
+## Scaling the Tool and Instruction Set
+
+| Feature | When to use it | What to expect |
+| --- | --- | --- |
+| **Tool search** | Many tools available, but only a few relevant per request. Don't want all schemas in context upfront. | Claude searches the tool set and loads only relevant schemas. Tool definitions are appended, not swapped — preserves cache (see Caching below). |
+| **Skills** | Task-specific instructions Claude should load only when relevant. | Each skill is a folder with a `SKILL.md`. The skill's description sits in context by default; Claude reads the full file when the task calls for it. |
+
+Both patterns keep the fixed context small and load detail on demand.
+
+---
+
+## Long-Running Agents: Managing Context
+
+| Pattern | When to use it | What to expect |
+| --- | --- | --- |
+| **Context editing** | Context grows stale over many turns (old tool results, completed thinking). | Tool results and thinking blocks are cleared based on configurable thresholds. Keeps the transcript lean without summarizing. |
+| **Compaction** | Conversation likely to reach or exceed the context window limit. | Earlier context is summarized into a compaction block server-side. See `SKILL.md` §Compaction for the critical `response.content` handling. |
+| **Memory** | State must persist across sessions (not just within one conversation). | Claude reads/writes files in a memory directory. Survives process restarts. |
+
+**Choosing between them:** Context editing and compaction operate within a session — editing prunes stale turns, compaction summarizes when you're near the limit. Memory is for cross-session persistence. Many long-running agents use all three.
+
+---
+
+## Caching for Agents
+
+**Read `prompt-caching.md` first.** It covers the prefix-match invariant, breakpoint placement, the silent-invalidator audit, and why changing tools or models mid-session breaks the cache. This section covers only the agent-specific workarounds for those constraints.
+
+| Constraint (from `prompt-caching.md`) | Agent-specific workaround |
+| --- | --- |
+| Editing the system prompt mid-session invalidates the cache. | Append a `{"role": "system", ...}` message to `messages[]` instead (no beta header; on supporting models — see `prompt-caching.md` § Mid-conversation system messages). The cached prefix stays intact, and the model treats it as an operator-authority instruction rather than user text. On models that don't support it, fall back to a `<system-reminder>` text block in the user turn. |
+| Switching models mid-session invalidates the cache. | Spawn a **subagent** with the cheaper model for the sub-task; keep the main loop on one model. |
+| Adding/removing tools mid-session invalidates the cache. | Use **tool search** for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved. |
+
+For multi-turn breakpoint placement, use top-level auto-caching — see `prompt-caching.md` §Placement patterns.
+
+---
+
+For live documentation on any of these features, see `live-sources.md`.