feat(sdk)!: remove retired agent helpers and mount examples (#21)

Author: tode-rl

EXAMPLES.md

@@ -9,7 +9,7 @@ Runnable examples live in [`examples/`](./examples).
 
 - [Blueprint with Build Context](#blueprint-with-build-context)
 - [Devbox From Blueprint (Run Command, Shutdown)](#devbox-from-blueprint-lifecycle)
-- [Devbox Mounts (Agent, Code, Object)](#devbox-mounts)
+- [Devbox Mounts (Code, Object)](#devbox-mounts)
 - [Devbox Snapshots (Suspend, Resume, Restore, Delete)](#devbox-snapshots)
 - [Devbox Tunnel (HTTP Server Access)](#devbox-tunnel)
 - [MCP Hub + Claude Code + GitHub](#mcp-github-tools)
@@ -77,17 +77,17 @@ yarn test:examples
 **Source:** [`examples/devbox-from-blueprint-lifecycle.ts`](./examples/devbox-from-blueprint-lifecycle.ts)
 
 <a id="devbox-mounts"></a>
-## Devbox Mounts (Agent, Code, Object)
+## Devbox Mounts (Code, Object)
 
-**Use case:** Launch a devbox that combines an agent mount for Claude Code, a code mount for the Runloop CLI repo, and an object mount for startup files.
+**Use case:** Launch a devbox with a code mount for the Runloop CLI repo and an object mount for startup files, then install Claude Code with a command.
 
 **Tags:** `devbox`, `mounts`, `agent`, `code`, `object`, `claude-code`, `agent-gateway`, `ttl`
 
 ### Workflow
-- Create or reuse an agent by name
 - Create a secret for an agent and route it through agent gateway
 - Upload a temporary directory as a storage object with a TTL
-- Launch a devbox with agent, code, and object mounts together
+- Launch a devbox with code and object mounts together
+- Install Claude Code with a command
 - Run Claude Code on Opus 4.5 through the Anthropic agent gateway
 - Verify the rl-cli repo and extracted object files are present on the devbox
 - Shutdown the devbox and delete the temporary secret and object

README.md

@@ -76,7 +76,7 @@ yarn generate:examples-md
 
 Use direct `secrets` injection when code inside the devbox legitimately needs the secret value. For third-party API credentials that should stay off the devbox, prefer wiring a Runloop secret through agent gateway instead. See [`examples/secrets-with-devbox.ts`](./examples/secrets-with-devbox.ts) for both patterns side by side using `devbox.create({ secrets: ... })` and `devbox.create({ gateways: ... })`.
 
-For mount patterns, see [`examples/devbox-mounts.ts`](./examples/devbox-mounts.ts). It shows when to use `agent_mount` for reusable agents like Claude Code, `code_mount` for Git repositories such as [`runloopai/rl-cli`](https://github.com/runloopai/rl-cli.git), and `object_mount` for blobs that should appear on the devbox at startup. The example also demonstrates agent gateway wiring for Anthropic credentials plus object TTL, `.tgz` compression, and extraction-on-mount behavior.
+For mount patterns, see [`examples/devbox-mounts.ts`](./examples/devbox-mounts.ts). It shows when to use `code_mount` for Git repositories such as [`runloopai/rl-cli`](https://github.com/runloopai/rl-cli.git), and `object_mount` for blobs that should appear on the devbox at startup. The example installs Claude Code with a command and demonstrates agent gateway wiring for Anthropic credentials plus object TTL, `.tgz` compression, and extraction-on-mount behavior.
 
 For snapshot workflows, see [`examples/devbox-snapshots.ts`](./examples/devbox-snapshots.ts). It uploads a file to a source devbox, shows `suspend()` plus `resume()`, takes a disk snapshot, restores multiple devboxes from the same snapshot baseline, mutates the file independently in each devbox, and deletes the snapshot after the demo completes.
 
@@ -107,7 +107,6 @@ complete, and do not forward API authentication or request-option headers to sto
 Treat signed URLs and headers as credentials. Signed PUTs do not follow redirects or
 retry, and their error messages exclude signed credentials and storage response bodies.
 
-- **[`runloop.agent`](https://runloopai.github.io/api-client-ts/stable/classes/sdk.AgentOps.html)** - Agent management (create, list agents from npm/pip/git)
 - **[`runloop.axon`](https://runloopai.github.io/api-client-ts/stable/classes/sdk.AxonOps.html)** - [Beta] Axon management (create, publish events, subscribe via SSE)
 - **[`runloop.networkPolicy`](https://runloopai.github.io/api-client-ts/stable/classes/sdk.NetworkPolicyOps.html)** - Network policy management (create, list, update egress rules)
 - **[`runloop.gatewayConfig`](https://runloopai.github.io/api-client-ts/stable/classes/sdk.GatewayConfigOps.html)** - Gateway config management (create, list API proxy configurations)

examples/devbox-mounts.ts

@@ -2,14 +2,14 @@
 
 /**
 ---
-title: Devbox Mounts (Agent, Code, Object)
+title: Devbox Mounts (Code, Object)
 slug: devbox-mounts
-use_case: Launch a devbox that combines an agent mount for Claude Code, a code mount for the Runloop CLI repo, and an object mount for startup files.
+use_case: Launch a devbox with a code mount for the Runloop CLI repo and an object mount for startup files, then install Claude Code with a command.
 workflow:
-  - Create or reuse an agent by name
   - Create a secret for an agent and route it through agent gateway
   - Upload a temporary directory as a storage object with a TTL
-  - Launch a devbox with agent, code, and object mounts together
+  - Launch a devbox with code and object mounts together
+  - Install Claude Code with a command
   - Run Claude Code on Opus 4.5 through the Anthropic agent gateway
   - Verify the rl-cli repo and extracted object files are present on the devbox
   - Shutdown the devbox and delete the temporary secret and object
@@ -37,8 +37,6 @@ import { RunloopSDK } from '@runloop/api-client';
 import { wrapRecipe, runAsCli } from './_harness';
 import type { RecipeContext, RecipeOutput } from './types';
 
-const CLAUDE_CODE_AGENT_NAME = 'example-claude-code-agent';
-const CLAUDE_CODE_AGENT_VERSION = '1.0.0';
 const CLAUDE_CODE_PACKAGE = '@anthropic-ai/claude-code';
 const CLAUDE_MODEL = 'claude-opus-4-5';
 const OBJECT_TTL_MS = 60 * 60 * 1000;
@@ -50,34 +48,6 @@ function uniqueName(prefix: string): string {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
 
-// example setup: get or create an agent so we can mount it
-async function ensureClaudeCodeAgent(sdk: RunloopSDK): Promise<{ agentId: string; reused: boolean }> {
-  const existingAgentsList = await sdk.agent.list({ name: CLAUDE_CODE_AGENT_NAME, limit: 20 });
-  const existingAgentDetails = await Promise.all(existingAgentsList.map((candidate) => candidate.getInfo()));
-
-  const matchingAgent = existingAgentDetails
-    .filter(
-      (info) =>
-        info.name === CLAUDE_CODE_AGENT_NAME &&
-        info.version === CLAUDE_CODE_AGENT_VERSION &&
-        info.source?.type === 'npm' &&
-        info.source?.npm?.package_name === CLAUDE_CODE_PACKAGE,
-    )
-    .sort((left, right) => right.create_time_ms - left.create_time_ms)[0];
-
-  if (matchingAgent) {
-    return { agentId: matchingAgent.id, reused: true };
-  }
-
-  const createdAgent = await sdk.agent.createFromNpm({
-    name: CLAUDE_CODE_AGENT_NAME,
-    version: CLAUDE_CODE_AGENT_VERSION,
-    package_name: CLAUDE_CODE_PACKAGE,
-  });
-
-  return { agentId: createdAgent.id, reused: false };
-}
-
 export async function recipe(ctx: RecipeContext): Promise<RecipeOutput> {
   const { cleanup } = ctx;
   const anthropicApiKey = process.env['ANTHROPIC_API_KEY'];
@@ -92,9 +62,6 @@ export async function recipe(ctx: RecipeContext): Promise<RecipeOutput> {
 
   const resourcesCreated: string[] = [];
 
-  const { agentId, reused } = await ensureClaudeCodeAgent(sdk);
-  resourcesCreated.push(reused ? `agent:${agentId}:reused` : `agent:${agentId}`);
-
   // best practice: create a secret for the agent's credentials and use agent gateway to route it through
   // so that credentials are not exposed to the agent.
   const anthropicSecret = await sdk.secret.create({
@@ -128,14 +95,7 @@ export async function recipe(ctx: RecipeContext): Promise<RecipeOutput> {
 
   const devbox = await sdk.devbox.create({
     name: uniqueName('mounts-example-devbox'),
-    // Use agent mounts for reusable tools or agents that should be installed onto the devbox.
-    // For npm-based agents like Claude Code, mounting by name makes it easy to reuse the latest matching agent.
     mounts: [
-      {
-        type: 'agent_mount',
-        agent_id: null,
-        agent_name: CLAUDE_CODE_AGENT_NAME,
-      },
       // Use code mounts for Git projects that should be cloned onto the devbox.
       {
         type: 'code_mount',
@@ -171,6 +131,11 @@ export async function recipe(ctx: RecipeContext): Promise<RecipeOutput> {
   const gatewayTokenResult = await devbox.cmd.exec(`echo $${GATEWAY_ENV_PREFIX}`);
   const gatewayToken = (await gatewayTokenResult.stdout()).trim();
 
+  const installResult = await devbox.cmd.exec(`npm install -g ${CLAUDE_CODE_PACKAGE}`);
+  if (installResult.exitCode !== 0) {
+    throw new Error(`Claude Code installation failed: ${await installResult.stderr()}`);
+  }
+
   const claudeVersionResult = await devbox.cmd.exec('claude --version');
   const claudeVersion = (await claudeVersionResult.stdout()).trim();
 
@@ -228,7 +193,7 @@ export async function recipe(ctx: RecipeContext): Promise<RecipeOutput> {
       {
         name: 'object mount extracted the uploaded example file onto the devbox',
         passed:
-          mountedExampleContents.includes('title: Devbox Mounts (Agent, Code, Object)') &&
+          mountedExampleContents.includes('title: Devbox Mounts (Code, Object)') &&
           mountedExampleContents.startsWith('#!/usr/bin/env -S npm run tsn -T'),
         details: mountedExamplePath,
       },

examples/registry.ts

@@ -36,7 +36,7 @@ export const exampleRegistry: ExampleRegistryEntry[] = [
   },
   {
     slug: 'devbox-mounts',
-    title: 'Devbox Mounts (Agent, Code, Object)',
+    title: 'Devbox Mounts (Code, Object)',
     fileName: 'devbox-mounts.ts',
     requiredEnv: ['RUNLOOP_API_KEY', 'ANTHROPIC_API_KEY'],
     run: runDevboxMountsExample,

llms.txt

@@ -10,7 +10,7 @@
 ## Core Patterns
 
 - [Devbox lifecycle example](examples/devbox-from-blueprint-lifecycle.ts): Create blueprint, launch devbox, run commands, cleanup
-- [Devbox mounts example](examples/devbox-mounts.ts): Show `agent_mount`, `code_mount`, and `object_mount` together, including Claude Code via Anthropic agent gateway, the `runloopai/rl-cli` repo, and object TTL/compression/extraction behavior
+- [Devbox mounts example](examples/devbox-mounts.ts): Show `code_mount` and `object_mount` together, including command-installed Claude Code via Anthropic agent gateway, the `runloopai/rl-cli` repo, and object TTL/compression/extraction behavior
 - [Devbox snapshots example](examples/devbox-snapshots.ts): Upload a file, suspend and resume the source devbox, snapshot the shared baseline, restore multiple devboxes from it, mutate each copy independently, and delete the snapshot
 - [MCP GitHub example](examples/mcp-github-tools.ts): MCP Hub integration with Claude Code
 - [Secrets with Devbox example](examples/secrets-with-devbox.ts): Show direct secret injection for app data alongside agent gateway for upstream credentials that should stay off the devbox