@an-sdk/cli 0.0.8 → 0.0.9

package/AGENTS.md

@@ -0,0 +1,19 @@
+# @an-sdk/cli
+
+CLI tool for deploying AI agents to the AN platform. Two commands: `an login` and `an deploy`.
+
+## Docs
+
+Full documentation: `./docs/` directory (8 guides covering the entire AN platform).
+
+## Source
+
+Source code: `./src/` directory.
+
+## Key Entry Points
+
+- `src/index.ts` — Command router (dispatches to login/deploy)
+- `src/login.ts` — API key auth flow, saves to `~/.an/credentials`
+- `src/deploy.ts` — Bundles agent code with esbuild, deploys to AN platform
+- `src/config.ts` — Reads/writes credentials and project config
+- `src/bundler.ts` — esbuild wrapper (externalizes `@an-sdk/agent`)

package/docs/01-overview.md

@@ -0,0 +1,61 @@
+# AN Platform Overview
+
+AN is a platform for building, deploying, and embedding AI agents. You define an agent in TypeScript, deploy it with one command, and embed a chat UI in any React app.
+
+## Architecture
+
+```
+Your Code (agent.ts)
+    |
+    v
+an deploy (CLI)
+    |
+    v
+AN Platform
+    |
+    +---> E2B Sandbox (isolated Node.js environment)
+    |         |
+    |         +---> Claude Agent SDK / Codex (executes your agent)
+    |         |
+    |         +---> Your custom tools run here
+    |
+    +---> AN Relay (relay.an.dev)
+              |
+              +---> SSE streaming to clients
+              |
+              +---> Token exchange (API key -> short-lived JWT)
+```
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| `@an-sdk/agent` | Define agents and tools with type inference |
+| `@an-sdk/cli` | Deploy agents from your terminal |
+| `@an-sdk/react` | Chat UI components (theming, tool renderers) |
+| `@an-sdk/nextjs` | Next.js server-side token handler |
+| `@an-sdk/node` | Server-side SDK (sandboxes, threads, tokens) |
+
+## Key Concepts
+
+- **Agent**: A TypeScript config defining model, system prompt, tools, and hooks. Runs in a cloud sandbox.
+- **Tool**: A function your agent can call, with a Zod schema for input validation and full type inference.
+- **Sandbox**: An isolated E2B cloud environment where your agent executes. Has Node.js, git, and system tools.
+- **Thread**: A conversation within a sandbox. One sandbox can have multiple threads.
+- **Relay**: The streaming gateway at `relay.an.dev`. Handles auth, routing, and SSE streaming.
+
+## Runtimes
+
+AN supports two runtimes:
+
+- **`claude-code`** (default) — Uses the Claude Agent SDK. Full tool use, file editing, bash execution.
+- **`codex`** — Uses OpenAI Codex via ACP provider.
+
+## Auth Model
+
+Two layers of authentication:
+
+1. **Client -> Relay**: API key (`an_sk_...`) or short-lived JWT (via token exchange)
+2. **Sandbox -> AI Provider**: Handled internally by the platform (Claude Proxy)
+
+For web apps, use `@an-sdk/nextjs` to exchange your API key for a short-lived JWT on the server, so the key never reaches the browser.

package/docs/02-getting-started.md

@@ -0,0 +1,110 @@
+# Getting Started
+
+## 1. Get an API Key
+
+Sign up at [an.dev](https://an.dev) and get your API key from [an.dev/agents/dashboard/api](https://an.dev/agents/dashboard/api).
+
+## 2. Install
+
+```bash
+npm install @an-sdk/agent zod
+```
+
+## 3. Define Your Agent
+
+Create `src/agent.ts`:
+
+```ts
+import { agent, tool } from "@an-sdk/agent"
+import { z } from "zod"
+
+export default agent({
+  model: "claude-sonnet-4-6",
+  systemPrompt: "You are a helpful coding assistant.",
+  tools: {
+    greet: tool({
+      description: "Greet a user by name",
+      inputSchema: z.object({ name: z.string() }),
+      execute: async ({ name }) => ({
+        content: [{ type: "text", text: `Hello, ${name}!` }],
+      }),
+    }),
+  },
+})
+```
+
+## 4. Login & Deploy
+
+```bash
+npx @an-sdk/cli login
+# Enter your API key: an_sk_...
+
+npx @an-sdk/cli deploy
+# Bundling src/agent.ts...
+# Deploying my-agent...
+# https://api.an.dev/v1/chat/my-agent
+```
+
+Your agent is live.
+
+## 5. Embed in a React App
+
+```bash
+npm install @an-sdk/nextjs @an-sdk/react ai @ai-sdk/react
+```
+
+Create a token route (keeps your API key on the server):
+
+```ts
+// app/api/an/token/route.ts
+import { createAnTokenHandler } from "@an-sdk/nextjs/server"
+
+export const POST = createAnTokenHandler({
+  apiKey: process.env.AN_API_KEY!,
+})
+```
+
+Add the chat UI:
+
+```tsx
+// app/page.tsx
+"use client"
+
+import { useChat } from "@ai-sdk/react"
+import { AnAgentChat, createAnChat } from "@an-sdk/nextjs"
+import "@an-sdk/react/styles.css"
+import { useMemo } from "react"
+
+export default function Chat() {
+  const chat = useMemo(
+    () => createAnChat({
+      agent: "your-agent-slug",
+      tokenUrl: "/api/an/token",
+    }),
+    [],
+  )
+
+  const { messages, sendMessage, status, stop, error } = useChat({ chat })
+
+  return (
+    <AnAgentChat
+      messages={messages}
+      onSend={(msg) =>
+        sendMessage({ parts: [{ type: "text", text: msg.content }] })
+      }
+      status={status}
+      onStop={stop}
+      error={error}
+    />
+  )
+}
+```
+
+## Next Steps
+
+- [Defining Agents](./03-defining-agents.md) — Models, tools, hooks, permissions
+- [React UI](./04-react-ui.md) — Theming, slots, tool renderers
+- [Next.js Integration](./05-nextjs.md) — Server-side token handler
+- [Node SDK](./06-node-sdk.md) — Sandboxes, threads, tokens from server code
+- [CLI Reference](./07-cli.md) — All CLI commands
+- [Custom Tools](./08-custom-tools.md) — Build custom tool renderers

package/docs/03-defining-agents.md

@@ -0,0 +1,159 @@
+# Defining Agents
+
+Agents are defined with the `agent()` and `tool()` functions from `@an-sdk/agent`. These are config-only — they return exactly what you pass in, with type inference added. The actual execution happens in the AN runtime (E2B sandbox).
+
+## `agent(config)`
+
+```ts
+import { agent } from "@an-sdk/agent"
+
+export default agent({
+  // Model (default: "claude-sonnet-4-6")
+  model: "claude-sonnet-4-6",
+
+  // System prompt
+  systemPrompt: "You are a PR reviewer...",
+
+  // Custom tools (see below)
+  tools: { /* ... */ },
+
+  // Runtime: "claude-code" (default) or "codex"
+  runtime: "claude-code",
+
+  // Permission mode: "default", "acceptEdits", or "bypassPermissions"
+  permissionMode: "default",
+
+  // Max conversation turns (default: 50)
+  maxTurns: 50,
+
+  // Max budget in USD
+  maxBudgetUsd: 5,
+
+  // Lifecycle hooks (see below)
+  onStart: async () => {},
+  onToolCall: async ({ toolName, input }) => {},
+  onToolResult: async ({ toolName, input, output }) => {},
+  onStepFinish: async ({ step }) => {},
+  onFinish: async ({ result }) => {},
+  onError: async ({ error }) => {},
+})
+```
+
+### Defaults
+
+| Field | Default |
+|-------|---------|
+| `model` | `"claude-sonnet-4-6"` |
+| `runtime` | `"claude-code"` |
+| `permissionMode` | `"default"` |
+| `maxTurns` | `50` |
+| `tools` | `{}` |
+
+## `tool(definition)`
+
+```ts
+import { tool } from "@an-sdk/agent"
+import { z } from "zod"
+
+const myTool = tool({
+  description: "What this tool does",
+  inputSchema: z.object({
+    path: z.string(),
+    verbose: z.boolean().optional(),
+  }),
+  execute: async (args) => {
+    // args is fully typed: { path: string; verbose?: boolean }
+    return {
+      content: [{ type: "text", text: "result" }],
+    }
+  },
+})
+```
+
+The `execute` function receives args typed from the Zod schema. Return value must have `content` array with `{ type: "text", text: string }` items.
+
+## Hooks
+
+### `onToolCall`
+
+Runs before a tool executes. Return `false` to block it.
+
+```ts
+onToolCall: async ({ toolName, input }) => {
+  if (toolName === "Bash" && input.command?.includes("rm -rf")) {
+    return false // blocked
+  }
+}
+```
+
+### `onToolResult`
+
+Runs after a tool executes with the result.
+
+```ts
+onToolResult: async ({ toolName, input, output }) => {
+  console.log(`Tool ${toolName} returned:`, output)
+}
+```
+
+### `onFinish`
+
+Runs when the agent completes successfully.
+
+```ts
+onFinish: async ({ result }) => {
+  await fetch("https://my-api.com/webhook", {
+    method: "POST",
+    body: JSON.stringify({ done: true }),
+  })
+}
+```
+
+### `onError`
+
+Runs when the agent encounters an error.
+
+```ts
+onError: async ({ error }) => {
+  console.error("Agent failed:", error)
+}
+```
+
+## Permission Modes
+
+| Mode | Behavior |
+|------|----------|
+| `"default"` | Agent asks for confirmation on risky operations |
+| `"acceptEdits"` | Auto-approve file edits, still confirm other actions |
+| `"bypassPermissions"` | Auto-approve everything (use with caution) |
+
+## Type Reference
+
+```ts
+// Agent config (all fields required — defaults filled by agent())
+interface AgentConfig {
+  model: string
+  systemPrompt: string
+  tools: ToolSet
+  runtime: "claude-code" | "codex"
+  permissionMode: "default" | "acceptEdits" | "bypassPermissions"
+  maxTurns: number
+  maxBudgetUsd?: number
+  onStart?: () => Promise<void>
+  onToolCall?: (payload: { toolName: string; input: any }) => Promise<boolean | void>
+  onToolResult?: (payload: { toolName: string; input: any; output: any }) => Promise<void>
+  onStepFinish?: (payload: { step: any }) => Promise<void>
+  onFinish?: (payload: { result: any }) => Promise<void>
+  onError?: (payload: { error: Error }) => Promise<void>
+}
+
+// Tool definition — generic over Zod schema
+interface ToolDefinition<TInput> {
+  description: string
+  inputSchema: ZodType<TInput>
+  execute: (args: TInput) => Promise<{ content: { type: string; text: string }[] }>
+}
+
+// Tool set
+type ToolSet = Record<string, ToolDefinition<any>>
+```

package/docs/04-react-ui.md

@@ -0,0 +1,186 @@
+# React UI
+
+`@an-sdk/react` provides a full chat UI for AN agents. Built on [Vercel AI SDK v5](https://sdk.vercel.ai) — uses standard `useChat()` from `@ai-sdk/react`.
+
+## Install
+
+```bash
+npm install @an-sdk/react ai @ai-sdk/react
+```
+
+## Basic Usage
+
+```tsx
+"use client"
+
+import { useChat } from "@ai-sdk/react"
+import { AnAgentChat, createAnChat } from "@an-sdk/react"
+import "@an-sdk/react/styles.css"
+import { useMemo } from "react"
+
+export default function Chat() {
+  const chat = useMemo(
+    () => createAnChat({
+      agent: "your-agent-slug",
+      getToken: async () => "your_an_sk_token",
+    }),
+    [],
+  )
+
+  const { messages, sendMessage, status, stop, error } = useChat({ chat })
+
+  return (
+    <AnAgentChat
+      messages={messages}
+      onSend={(msg) =>
+        sendMessage({ parts: [{ type: "text", text: msg.content }] })
+      }
+      status={status}
+      onStop={stop}
+      error={error}
+    />
+  )
+}
+```
+
+## `createAnChat(options)`
+
+Creates an AI SDK `Chat` instance pointed at the AN Relay.
+
+```ts
+createAnChat({
+  agent: string              // Agent slug from dashboard
+  getToken: () => Promise<string>  // Returns an_sk_ key or JWT
+  apiUrl?: string            // Default: "https://relay.an.dev"
+  projectId?: string         // Session persistence key
+  onFinish?: () => void
+  onError?: (error: Error) => void
+})
+```
+
+For Next.js apps, use `tokenUrl` instead of `getToken` — see [Next.js Integration](./05-nextjs.md).
+
+## `<AnAgentChat />` Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `messages` | `UIMessage[]` | From `useChat()` |
+| `onSend` | `(msg) => void` | Send handler |
+| `status` | `ChatStatus` | `"ready" \| "submitted" \| "streaming" \| "error"` |
+| `onStop` | `() => void` | Stop generation |
+| `error` | `Error` | Error to display |
+| `theme` | `AnTheme` | Theme from playground |
+| `colorMode` | `"light" \| "dark" \| "auto"` | Color mode |
+| `classNames` | `Partial<AnClassNames>` | Per-element CSS overrides |
+| `slots` | `Partial<AnSlots>` | Component swapping |
+| `className` | `string` | Root element class |
+| `style` | `CSSProperties` | Root element style |
+
+## Customization
+
+Four levels, from simple to full control:
+
+### 1. Theme tokens
+
+Apply a theme JSON from the [AN Playground](https://an.dev/an/playground):
+
+```tsx
+<AnAgentChat theme={playgroundTheme} colorMode="dark" />
+```
+
+### 2. Class overrides
+
+```tsx
+<AnAgentChat
+  classNames={{
+    root: "rounded-2xl border",
+    messageList: "px-8",
+    inputBar: "bg-gray-50",
+    userMessage: "bg-blue-100",
+  }}
+/>
+```
+
+### 3. Slot components
+
+Swap sub-components:
+
+```tsx
+<AnAgentChat
+  slots={{
+    InputBar: MyCustomInput,
+    UserMessage: MyUserBubble,
+    ToolRenderer: MyToolRenderer,
+  }}
+/>
+```
+
+### 4. Individual component imports
+
+```tsx
+import { MessageList, InputBar, ToolRenderer } from "@an-sdk/react"
+```
+
+## CSS
+
+Import once in your app:
+
+```tsx
+import "@an-sdk/react/styles.css"
+```
+
+No Tailwind peer dependency — CSS is pre-compiled. All elements have stable `an-*` class names:
+
+```css
+.an-root { }
+.an-message-list { }
+.an-user-message { }
+.an-assistant-message { }
+.an-input-bar { }
+.an-send-button { }
+.an-tool-bash { }
+.an-tool-edit { }
+```
+
+## Theme Type
+
+```ts
+interface AnTheme {
+  theme: Record<string, string>  // Shared: font, spacing, accent
+  light: Record<string, string>  // Light mode CSS vars
+  dark: Record<string, string>   // Dark mode CSS vars
+}
+```
+
+## `applyTheme(element, theme, colorMode?)`
+
+Manually inject CSS variables from a theme JSON onto a DOM element.
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `MessageList` | Auto-scrolling message container with grouping |
+| `UserMessage` | User message bubble |
+| `AssistantMessage` | Assistant response with parts routing |
+| `StreamingMarkdown` | Markdown renderer with syntax highlighting |
+| `InputBar` | Text input with send/stop buttons |
+| `MessageActions` | Copy button |
+| `ToolRenderer` | Routes tool parts to the correct component |
+
+## Built-in Tool Renderers
+
+| Component | Renders |
+|-----------|---------|
+| `BashTool` | Terminal commands with output |
+| `EditTool` | File edits with diff display |
+| `WriteTool` | File creation |
+| `SearchTool` | Web search results |
+| `TodoTool` | Task checklists |
+| `PlanTool` | Step-by-step plans |
+| `TaskTool` | Sub-agent tasks |
+| `McpTool` | MCP protocol calls |
+| `ThinkingTool` | Reasoning/thinking indicator |
+| `GenericTool` | Fallback for unknown tools |
+
+See [Custom Tools](./08-custom-tools.md) for building your own tool renderers.

package/docs/05-nextjs.md

@@ -0,0 +1,117 @@
+# Next.js Integration
+
+`@an-sdk/nextjs` provides a server-side token handler so your `an_sk_` API key never reaches the browser. It also re-exports everything from `@an-sdk/react` for convenience.
+
+## Install
+
+```bash
+npm install @an-sdk/nextjs @an-sdk/react ai @ai-sdk/react
+```
+
+## Setup
+
+### 1. Set your API key
+
+```env
+# .env.local
+AN_API_KEY=an_sk_your_key_here
+```
+
+Get your API key from [an.dev/agents/dashboard/api](https://an.dev/agents/dashboard/api).
+
+### 2. Create the token route
+
+```ts
+// app/api/an/token/route.ts
+import { createAnTokenHandler } from "@an-sdk/nextjs/server"
+
+export const POST = createAnTokenHandler({
+  apiKey: process.env.AN_API_KEY!,
+})
+```
+
+### 3. Use in your page
+
+```tsx
+// app/page.tsx
+"use client"
+
+import { useChat } from "@ai-sdk/react"
+import { AnAgentChat, createAnChat } from "@an-sdk/nextjs"
+import "@an-sdk/react/styles.css"
+import { useMemo } from "react"
+
+export default function Chat() {
+  const chat = useMemo(
+    () => createAnChat({
+      agent: "your-agent-slug",
+      tokenUrl: "/api/an/token",
+    }),
+    [],
+  )
+
+  const { messages, sendMessage, status, stop, error } = useChat({ chat })
+
+  return (
+    <AnAgentChat
+      messages={messages}
+      onSend={(msg) =>
+        sendMessage({ parts: [{ type: "text", text: msg.content }] })
+      }
+      status={status}
+      onStop={stop}
+      error={error}
+    />
+  )
+}
+```
+
+## How It Works
+
+```
+Browser                     Your Next.js Server              AN Relay
+  |                                |                            |
+  |-- POST /api/an/token --------->|                            |
+  |                                |-- POST /v1/tokens -------->|
+  |                                |   (with an_sk_ key)        |
+  |                                |<-- { token, expiresAt } ---|
+  |<-- { token, expiresAt } ------|                            |
+  |                                                             |
+  |-- POST /v1/chat/:agent ------(with short-lived JWT)------->|
+  |<-- streaming response -----(SSE)---------------------------|
+```
+
+The client only receives short-lived JWTs. Your API key stays on the server.
+
+## API
+
+### `createAnTokenHandler(options)`
+
+Returns a Next.js `POST` route handler.
+
+```ts
+createAnTokenHandler({
+  apiKey: string       // Your an_sk_ API key
+  relayUrl?: string    // Default: "https://relay.an.dev"
+  expiresIn?: string   // Default: "1h"
+})
+```
+
+### `exchangeToken(options)`
+
+Lower-level function for custom token exchange logic.
+
+```ts
+import { exchangeToken } from "@an-sdk/nextjs/server"
+
+const { token, expiresAt } = await exchangeToken({
+  apiKey: process.env.AN_API_KEY!,
+  relayUrl: "https://relay.an.dev",
+  expiresIn: "1h",
+})
+```
+
+## Entry Points
+
+- `@an-sdk/nextjs` — Re-exports everything from `@an-sdk/react` (components, types, `createAnChat`)
+- `@an-sdk/nextjs/server` — Server-only: `createAnTokenHandler`, `exchangeToken`

package/docs/06-node-sdk.md

@@ -0,0 +1,125 @@
+# Node SDK
+
+`@an-sdk/node` is a server-side client for the AN API. Use it to manage sandboxes, threads, and tokens programmatically.
+
+## Install
+
+```bash
+npm install @an-sdk/node
+```
+
+## Quick Start
+
+```ts
+import { AnClient } from "@an-sdk/node"
+
+const an = new AnClient({
+  apiKey: process.env.AN_API_KEY!, // an_sk_...
+})
+
+// Create a sandbox for your agent
+const sandbox = await an.sandboxes.create({ agent: "my-agent" })
+
+// Create a thread
+const thread = await an.threads.create({
+  sandboxId: sandbox.sandboxId,
+  name: "Review PR #42",
+})
+
+// Generate a short-lived token for browser clients
+const { token, expiresAt } = await an.tokens.create({
+  agent: "my-agent",
+  expiresIn: "1h",
+})
+```
+
+## `AnClient`
+
+```ts
+new AnClient({
+  apiKey: string     // Your an_sk_ API key
+  baseUrl?: string   // Default: "https://relay.an.dev"
+})
+```
+
+## Resources
+
+### `client.sandboxes`
+
+| Method | Description |
+|--------|-------------|
+| `create({ agent })` | Create a new sandbox for an agent |
+| `get(sandboxId)` | Get sandbox details (status, threads, agent info) |
+| `delete(sandboxId)` | Delete a sandbox |
+
+### `client.threads`
+
+| Method | Description |
+|--------|-------------|
+| `list({ sandboxId })` | List all threads in a sandbox |
+| `create({ sandboxId, name? })` | Create a new thread |
+| `get({ sandboxId, threadId })` | Get thread with messages |
+| `delete({ sandboxId, threadId })` | Delete a thread |
+
+### `client.tokens`
+
+| Method | Description |
+|--------|-------------|
+| `create({ agent?, userId?, expiresIn? })` | Create a short-lived JWT |
+
+Default `expiresIn` is `"1h"`.
+
+## Types
+
+```ts
+interface Sandbox {
+  id: string
+  sandboxId: string
+  status: string
+  createdAt: string
+}
+
+interface SandboxDetail {
+  id: string
+  sandboxId: string
+  status: string
+  error?: string | null
+  agent: { slug: string; name: string }
+  threads: ThreadSummary[]
+  createdAt: string
+  updatedAt: string
+}
+
+interface ThreadSummary {
+  id: string
+  name?: string | null
+  status: string
+  createdAt: string
+}
+
+interface Thread {
+  id: string
+  name?: string | null
+  status: string
+  messages?: unknown
+  createdAt: string
+  updatedAt: string
+}
+
+interface Token {
+  token: string
+  expiresAt: string
+}
+```
+
+## Error Handling
+
+All methods throw on non-2xx responses. The error message comes from the API response body when available.
+
+```ts
+try {
+  const sandbox = await an.sandboxes.get("nonexistent")
+} catch (err) {
+  console.error(err.message) // "Sandbox not found" or similar
+}
+```

package/docs/07-cli.md

@@ -0,0 +1,88 @@
+# CLI Reference
+
+`@an-sdk/cli` provides the `an` command for deploying agents.
+
+## Install
+
+```bash
+npm install -g @an-sdk/cli
+# or use npx
+npx @an-sdk/cli <command>
+```
+
+## Commands
+
+### `an login`
+
+Authenticate with the AN platform.
+
+```bash
+npx @an-sdk/cli login
+# Enter your API key: an_sk_...
+# Authenticated as John (team: my-team)
+```
+
+Your key is saved to `~/.an/credentials`.
+
+### `an deploy`
+
+Bundle and deploy your agent.
+
+```bash
+npx @an-sdk/cli deploy
+# Bundling src/agent.ts...
+# Bundled (12.3kb)
+# Deploying my-agent...
+# https://api.an.dev/v1/chat/my-agent
+```
+
+The CLI:
+1. Finds your entry point (see detection order below)
+2. Bundles your code + dependencies with esbuild
+3. Deploys to a secure cloud sandbox
+4. Returns your agent's URL
+
+## Entry Point Detection
+
+The CLI looks for your agent file in this order:
+
+1. `src/agent.ts`
+2. `src/index.ts`
+3. `agent.ts`
+4. `index.ts`
+
+Your entry file must `export default agent(...)`.
+
+## Project Linking
+
+After first deploy, the CLI saves `.an/project.json` in your project directory:
+
+```json
+{
+  "agentId": "abc123",
+  "slug": "my-agent"
+}
+```
+
+Subsequent deploys update the existing agent.
+
+## Bundling
+
+The CLI uses esbuild to bundle your agent code:
+
+- Target: Node 22, ESM
+- `@an-sdk/agent` is externalized (provided by the sandbox runtime)
+- All other dependencies are bundled into a single file
+
+## Configuration Files
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `~/.an/credentials` | Global | API key (`{ "apiKey": "an_sk_..." }`) |
+| `.an/project.json` | Per-project | Agent ID and slug for redeployment |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AN_API_URL` | `https://an.dev/api/v1` | Override API endpoint |

package/docs/08-custom-tools.md

@@ -0,0 +1,88 @@
+# Custom Tool Renderers
+
+The `@an-sdk/react` chat UI automatically renders tool calls from your agent. It includes built-in renderers for all standard Claude tools and supports custom renderers for your own tools.
+
+## Built-in Tool Renderers
+
+These are rendered automatically when your agent uses standard tools:
+
+| Tool | Renderer | Display |
+|------|----------|---------|
+| `Bash` | `BashTool` | Terminal card with command and output |
+| `Edit` | `EditTool` | Diff card with file path and changes |
+| `Write` | `WriteTool` | File creation card |
+| `WebSearch` | `SearchTool` | Search results list |
+| `TodoWrite` | `TodoTool` | Task checklist with progress |
+| `EnterPlanMode` | `PlanTool` | Step list with progress bar |
+| `Task` | `TaskTool` | Sub-agent task with nested tools |
+| `mcp__*` | `McpTool` | MCP tool call with params and output |
+| `thinking` | `ThinkingTool` | Collapsible reasoning block |
+| Other | `GenericTool` | Fallback JSON display |
+
+## Custom Tool Renderers via Slots
+
+To render your custom tools differently, use the `slots.ToolRenderer` prop:
+
+```tsx
+import { AnAgentChat, ToolRenderer } from "@an-sdk/react"
+import type { ToolPart } from "@an-sdk/react"
+
+function MyToolRenderer(props: { part: ToolPart; status: string }) {
+  const { part, status } = props
+
+  // Handle your custom tool
+  if (part.toolInvocation.toolName === "weather") {
+    const args = part.toolInvocation.args
+    const result = part.toolInvocation.state === "result"
+      ? part.toolInvocation.result
+      : null
+
+    return (
+      <div className="weather-card">
+        <h3>Weather for {args.city}</h3>
+        {result ? <p>{result.content[0].text}</p> : <p>Loading...</p>}
+      </div>
+    )
+  }
+
+  // Fall back to default renderer for standard tools
+  return <ToolRenderer part={part} status={status} />
+}
+
+<AnAgentChat
+  slots={{ ToolRenderer: MyToolRenderer }}
+  // ... other props
+/>
+```
+
+## MCP Tool Naming
+
+MCP (Model Context Protocol) tools follow the naming pattern `mcp__<server>__<tool>`. The built-in `McpTool` renderer parses this automatically and shows the server name and tool name.
+
+## Tool States
+
+Each tool invocation has a state:
+
+| State | Meaning |
+|-------|---------|
+| `"call"` | Tool has been called, waiting for execution |
+| `"result"` | Tool has returned a result |
+
+During streaming, tools may be in `"call"` state before transitioning to `"result"`.
+
+## CSS Classes
+
+All tool renderers have stable CSS class names for custom styling:
+
+```css
+.an-tool-bash { }
+.an-tool-edit { }
+.an-tool-write { }
+.an-tool-search { }
+.an-tool-todo { }
+.an-tool-plan { }
+.an-tool-task { }
+.an-tool-mcp { }
+.an-tool-thinking { }
+.an-tool-generic { }
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@an-sdk/cli",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "AN CLI — deploy AI agents",
   "type": "module",
   "bin": {
@@ -8,9 +8,18 @@
   },
   "files": [
     "dist",
+    "docs/**/*",
+    "src",
+    "!src/**/*.test.ts",
+    "AGENTS.md",
     "README.md"
   ],
+  "directories": {
+    "doc": "./docs"
+  },
   "scripts": {
+    "prepack": "cp -r ../docs ./docs",
+    "postpack": "rm -rf ./docs",
     "build": "tsup",
     "dev": "tsx src/index.ts"
   },

package/src/bundler.ts

@@ -0,0 +1,63 @@
+import esbuild from "esbuild"
+
+export type AgentEntryPoint = { slug: string; entryPoint: string }
+
+export async function findAgentEntryPoints(): Promise<AgentEntryPoint[]> {
+  const { existsSync, readdirSync, statSync } = await import("fs")
+  const { join, basename, extname } = await import("path")
+
+  if (!existsSync("agents") || !statSync("agents").isDirectory()) {
+    throw new Error("No agents/ directory found. See https://an.dev/docs to get started.")
+  }
+
+  const entries: AgentEntryPoint[] = []
+  const items = readdirSync("agents")
+
+  for (const item of items) {
+    const fullPath = join("agents", item)
+    const stat = statSync(fullPath)
+
+    if (stat.isDirectory()) {
+      for (const indexFile of ["index.ts", "index.js"]) {
+        const indexPath = join(fullPath, indexFile)
+        if (existsSync(indexPath)) {
+          entries.push({ slug: item, entryPoint: indexPath })
+          break
+        }
+      }
+    } else if (stat.isFile()) {
+      const ext = extname(item)
+      if (ext === ".ts" || ext === ".js") {
+        entries.push({ slug: basename(item, ext), entryPoint: fullPath })
+      }
+    }
+  }
+
+  if (entries.length === 0) {
+    throw new Error("No agents found in agents/ directory. See https://an.dev/docs to get started.")
+  }
+
+  return entries
+}
+
+export async function bundleAgent(entryPoint: string): Promise<Buffer> {
+  const result = await esbuild.build({
+    entryPoints: [entryPoint],
+    bundle: true,
+    platform: "node",
+    target: "node22",
+    format: "esm",
+    write: false,
+    external: ["@an-sdk/agent"],
+    minify: true,
+    sourcemap: false,
+  })
+
+  if (result.errors.length > 0) {
+    throw new Error(
+      `Bundle failed:\n${result.errors.map((e) => e.text).join("\n")}`,
+    )
+  }
+
+  return Buffer.from(result.outputFiles[0].contents)
+}

package/src/config.ts

@@ -0,0 +1,46 @@
+import { readFileSync, writeFileSync, mkdirSync } from "fs"
+import { join } from "path"
+import { homedir } from "os"
+
+const AN_DIR = join(homedir(), ".an")
+const CREDENTIALS_PATH = join(AN_DIR, "credentials")
+const PROJECT_PATH = join(process.cwd(), ".an", "project.json")
+
+// --- Credentials (global, ~/.an/credentials) ---
+
+export function getApiKey(): string | null {
+  // Env var takes priority (CI mode)
+  if (process.env.AN_API_KEY) return process.env.AN_API_KEY
+  try {
+    const data = JSON.parse(readFileSync(CREDENTIALS_PATH, "utf-8"))
+    return data.apiKey || null
+  } catch {
+    return null
+  }
+}
+
+export function saveApiKey(apiKey: string): void {
+  mkdirSync(AN_DIR, { recursive: true })
+  writeFileSync(CREDENTIALS_PATH, JSON.stringify({ apiKey }, null, 2))
+}
+
+// --- Project linking (local, .an/project.json) ---
+
+export type ProjectConfig = { projectId: string; projectSlug: string }
+
+export function getProject(): ProjectConfig | null {
+  try {
+    const data = JSON.parse(readFileSync(PROJECT_PATH, "utf-8"))
+    // Backward compat: old format had { agentId, slug }
+    if (data.projectId && data.projectSlug) return data
+    if (data.slug) return { projectId: data.agentId ?? "", projectSlug: data.slug }
+    return null
+  } catch {
+    return null
+  }
+}
+
+export function saveProject(data: ProjectConfig): void {
+  mkdirSync(join(process.cwd(), ".an"), { recursive: true })
+  writeFileSync(PROJECT_PATH, JSON.stringify(data, null, 2))
+}

package/src/deploy.ts

@@ -0,0 +1,177 @@
+import { getApiKey, getProject, saveProject } from "./config.js"
+import { findAgentEntryPoints, bundleAgent } from "./bundler.js"
+import { basename } from "path"
+import * as p from "@clack/prompts"
+
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+}
+
+const API_BASE = process.env.AN_API_URL || "https://an.dev/api/v1"
+const AN_BASE = process.env.AN_URL || "https://an.dev"
+
+type ProjectInfo = { id: string; slug: string; name: string }
+
+async function fetchProjects(apiKey: string): Promise<ProjectInfo[]> {
+  const res = await fetch(`${API_BASE}/projects`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  })
+  if (!res.ok) return []
+  const data = await res.json()
+  return data.projects ?? []
+}
+
+async function linkProject(apiKey: string): Promise<{ projectId: string; projectSlug: string }> {
+  const projects = await fetchProjects(apiKey)
+
+  if (projects.length === 0) {
+    // No existing projects — just ask for a name
+    const name = await p.text({
+      message: "Project name",
+      defaultValue: basename(process.cwd()),
+      placeholder: basename(process.cwd()),
+    })
+    if (p.isCancel(name)) {
+      p.cancel("Deploy cancelled.")
+      process.exit(0)
+    }
+    return { projectId: "", projectSlug: slugify(name) }
+  }
+
+  // Has existing projects — let them pick or create new
+  const options = [
+    { value: "__new__", label: "Create a new project" },
+    ...projects.map((proj) => ({ value: proj.slug, label: proj.name || proj.slug })),
+  ]
+
+  const choice = await p.select({
+    message: "Link to a project",
+    options,
+  })
+  if (p.isCancel(choice)) {
+    p.cancel("Deploy cancelled.")
+    process.exit(0)
+  }
+
+  if (choice === "__new__") {
+    const name = await p.text({
+      message: "Project name",
+      defaultValue: basename(process.cwd()),
+      placeholder: basename(process.cwd()),
+    })
+    if (p.isCancel(name)) {
+      p.cancel("Deploy cancelled.")
+      process.exit(0)
+    }
+    return { projectId: "", projectSlug: slugify(name) }
+  }
+
+  // Linked to existing project
+  const selected = projects.find((proj) => proj.slug === choice)!
+  return { projectId: selected.id, projectSlug: selected.slug }
+}
+
+export async function deploy() {
+  p.intro("an deploy")
+
+  // 1. Check auth
+  const apiKey = getApiKey()
+  if (!apiKey) {
+    p.log.error("Not logged in. Run `an login` first, or set AN_API_KEY env var.")
+    process.exit(1)
+  }
+
+  // 2. Find agent entry points
+  let agents
+  try {
+    agents = await findAgentEntryPoints()
+  } catch (err: any) {
+    p.log.error(err.message)
+    process.exit(1)
+  }
+  p.log.info(`Found ${agents.length} agent${agents.length > 1 ? "s" : ""}`)
+
+  // 3. Determine project
+  let project = getProject()
+  let projectSlug: string
+  let projectId: string
+
+  if (project) {
+    projectSlug = project.projectSlug
+    projectId = project.projectId
+  } else if (process.stdin.isTTY) {
+    // Interactive linking
+    const linked = await linkProject(apiKey)
+    projectSlug = linked.projectSlug
+    projectId = linked.projectId
+  } else {
+    // Non-interactive: auto-create from cwd name
+    projectSlug = slugify(basename(process.cwd()))
+    projectId = ""
+  }
+
+  // 4. Deploy each agent
+  const deployed: { slug: string }[] = []
+
+  for (const agent of agents) {
+    const s = p.spinner()
+    s.start(`Bundling ${agent.slug}...`)
+    const bundle = await bundleAgent(agent.entryPoint)
+    s.stop(`Bundled ${agent.slug} (${(bundle.length / 1024).toFixed(1)}kb)`)
+
+    const s2 = p.spinner()
+    s2.start(`Deploying ${agent.slug}...`)
+    const res = await fetch(`${API_BASE}/agents/deploy`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        projectSlug,
+        slug: agent.slug,
+        bundle: bundle.toString("base64"),
+      }),
+    })
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}))
+      s2.stop(`Failed to deploy ${agent.slug}`)
+      p.log.error((err as any).message || "Deploy failed")
+
+      if (deployed.length > 0) {
+        p.log.info(`\nDeployed before failure:`)
+        for (const a of deployed) {
+          p.log.info(`  ${a.slug}  →  ${AN_BASE}/a/${projectSlug}/${a.slug}`)
+        }
+      }
+      process.exit(1)
+    }
+
+    const result = await res.json()
+    projectId = result.projectId
+    projectSlug = result.projectSlug
+    deployed.push({ slug: agent.slug })
+    s2.stop(`${agent.slug} deployed`)
+  }
+
+  // 5. Save project link
+  saveProject({ projectId, projectSlug })
+
+  // 6. Output
+  p.log.success(`Deployed ${deployed.length} agent${deployed.length > 1 ? "s" : ""} to ${projectSlug}`)
+  console.log()
+  for (const agent of deployed) {
+    console.log(`  ${agent.slug}  →  ${AN_BASE}/a/${projectSlug}/${agent.slug}`)
+  }
+  console.log()
+  p.log.info("Next steps:")
+  console.log("  · Open the link above to test your agent")
+  console.log("  · Run `an deploy` again after changes")
+  console.log(`  · View all deployments: ${AN_BASE}/an/deployments`)
+
+  p.outro("Done")
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+import { login } from "./login.js"
+import { deploy } from "./deploy.js"
+import { createRequire } from "module"
+
+const require = createRequire(import.meta.url)
+const { version } = require("../package.json")
+
+const command = process.argv[2]
+const args = process.argv.slice(3)
+const hasFlag = (flag: string) => args.includes(flag)
+
+function showHelp() {
+  console.log(`AN CLI v${version} — deploy AI agents\n`)
+  console.log("Usage: an <command>\n")
+  console.log("Commands:")
+  console.log("  an login      Authenticate with AN platform")
+  console.log("  an deploy     Bundle and deploy your agent")
+  console.log("\nOptions:")
+  console.log("  --help, -h    Show help")
+  console.log("  --version, -v Show version")
+  console.log("\nGet started: an login")
+  console.log("Docs: https://an.dev/docs")
+}
+
+function showLoginHelp() {
+  console.log("Usage: an login\n")
+  console.log("Authenticate with the AN platform using an API key.")
+  console.log("Get your API key at https://an.dev/api-keys")
+}
+
+function showDeployHelp() {
+  console.log("Usage: an deploy\n")
+  console.log("Bundle and deploy agents from the ./agents/ directory.\n")
+  console.log("Agent structure:")
+  console.log("  agents/")
+  console.log("    my-agent/")
+  console.log("      index.ts       agent entry point")
+  console.log("    another.ts       single-file agent")
+  console.log("\nDocs: https://an.dev/docs")
+}
+
+if (command === "login") {
+  if (hasFlag("--help") || hasFlag("-h")) {
+    showLoginHelp()
+  } else {
+    await login()
+  }
+} else if (command === "deploy") {
+  if (hasFlag("--help") || hasFlag("-h")) {
+    showDeployHelp()
+  } else {
+    await deploy()
+  }
+} else if (command === "--version" || command === "-v") {
+  console.log(version)
+} else {
+  showHelp()
+}

package/src/login.ts

@@ -0,0 +1,48 @@
+import * as p from "@clack/prompts"
+import { getApiKey, saveApiKey } from "./config.js"
+
+const API_BASE = process.env.AN_API_URL || "https://an.dev/api/v1"
+
+export async function login() {
+  p.intro("an login")
+
+  const existing = getApiKey()
+  if (existing) {
+    p.log.info("Already logged in. Continuing will re-authenticate.")
+  }
+  p.log.info("Get your API key at https://an.dev/api-keys")
+
+  const apiKey = await p.text({
+    message: "Enter your API key",
+    validate: (val) => {
+      if (!val.trim()) return "API key cannot be empty"
+    },
+  })
+
+  if (p.isCancel(apiKey)) {
+    p.cancel("Login cancelled.")
+    process.exit(0)
+  }
+
+  const s = p.spinner()
+  s.start("Verifying API key...")
+
+  const res = await fetch(`${API_BASE}/me`, {
+    headers: { Authorization: `Bearer ${apiKey.trim()}` },
+  })
+
+  if (!res.ok) {
+    s.stop("Invalid API key")
+    p.log.error("Invalid API key. Get a new one at https://an.dev/api-keys")
+    process.exit(1)
+  }
+
+  const { user, team } = await res.json()
+  saveApiKey(apiKey.trim())
+  s.stop("Verified")
+
+  p.log.success(`Authenticated as ${user.displayName || user.email} (team: ${team.name})`)
+  p.log.info("Key saved to ~/.an/credentials")
+
+  p.outro("Done")
+}