@an-sdk/cli 0.0.8 → 0.0.10

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.10",
   "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,156 @@
+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)
+}
+
+async function importBundle(bundle: Buffer): Promise<Record<string, unknown> | null> {
+  const { writeFileSync, unlinkSync, mkdirSync } = await import("fs")
+  const { join } = await import("path")
+
+  // Write to .an-tmp/ in cwd so ESM can resolve @an-sdk/agent from node_modules
+  const tmpDir = join(process.cwd(), ".an-tmp")
+  mkdirSync(tmpDir, { recursive: true })
+  const tmpPath = join(tmpDir, `an-bundle-${Date.now()}.mjs`)
+  try {
+    writeFileSync(tmpPath, bundle)
+    const mod = await import(tmpPath)
+    const config = mod.default
+    if (config?._type === "agent") return config
+    return null
+  } catch {
+    return null
+  } finally {
+    try { unlinkSync(tmpPath) } catch {}
+    try { const { rmdirSync } = await import("fs"); rmdirSync(tmpDir) } catch {}
+  }
+}
+
+export async function extractSandboxConfig(
+  bundle: Buffer,
+): Promise<Record<string, unknown> | null> {
+  const config = await importBundle(bundle)
+  if (!config) return null
+  const sandbox = config.sandbox as Record<string, unknown> | undefined
+  if (sandbox && (sandbox as any)._type === "sandbox") {
+    const { _type, ...sandboxConfig } = sandbox
+    return sandboxConfig
+  }
+  return null
+}
+
+export type AgentMetadata = {
+  model: string
+  systemPrompt?: string | { type: string; preset: string; append?: string }
+  permissionMode: string
+  maxTurns: number
+  maxBudgetUsd?: number
+  tools: { name: string; description: string }[]
+  hooks: string[]
+  sandbox?: { apt?: string[]; setup?: string[]; cwd?: string }
+}
+
+const HOOK_NAMES = ["onStart", "onToolCall", "onToolResult", "onStepFinish", "onFinish", "onError"]
+
+export async function extractAgentMetadata(
+  bundle: Buffer,
+): Promise<AgentMetadata | null> {
+  try {
+    const config = await importBundle(bundle)
+    if (!config) return null
+
+    const tools: { name: string; description: string }[] = []
+    if (config.tools && typeof config.tools === "object") {
+      for (const [name, def] of Object.entries(config.tools as Record<string, any>)) {
+        tools.push({ name, description: def?.description ?? "" })
+      }
+    }
+
+    const hooks = HOOK_NAMES.filter((h) => typeof (config as any)[h] === "function")
+
+    const metadata: AgentMetadata = {
+      model: (config.model as string) ?? "unknown",
+      permissionMode: (config.permissionMode as string) ?? "default",
+      maxTurns: (config.maxTurns as number) ?? 50,
+      tools,
+      hooks,
+    }
+
+    if (config.systemPrompt !== undefined) {
+      metadata.systemPrompt = config.systemPrompt as AgentMetadata["systemPrompt"]
+    }
+    if (config.maxBudgetUsd !== undefined) {
+      metadata.maxBudgetUsd = config.maxBudgetUsd as number
+    }
+
+    const sandbox = config.sandbox as Record<string, unknown> | undefined
+    if (sandbox && (sandbox as any)._type === "sandbox") {
+      metadata.sandbox = {}
+      if (sandbox.apt) metadata.sandbox.apt = sandbox.apt as string[]
+      if (sandbox.setup) metadata.sandbox.setup = sandbox.setup as string[]
+      if (sandbox.cwd) metadata.sandbox.cwd = sandbox.cwd as string
+    }
+
+    return metadata
+  } catch {
+    return null
+  }
+}

package/src/config.ts

@@ -0,0 +1,24 @@
+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")
+
+// --- 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))
+}

package/src/deploy.ts

@@ -0,0 +1,95 @@
+import { getApiKey } from "./config.js"
+import { findAgentEntryPoints, bundleAgent, extractSandboxConfig, extractAgentMetadata } from "./bundler.js"
+import { existsSync } from "fs"
+import { join } from "path"
+import * as p from "@clack/prompts"
+
+const API_BASE = process.env.AN_API_URL || "https://an.dev/api/v1"
+const AN_BASE = process.env.AN_URL || "https://an.dev"
+
+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)
+  }
+
+  // Deprecation notice for old project config
+  if (existsSync(join(process.cwd(), ".an", "project.json"))) {
+    p.log.warn(".an/project.json is no longer used and can be removed.")
+  }
+
+  // 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. 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)
+    const sandboxConfig = await extractSandboxConfig(bundle)
+    const metadata = await extractAgentMetadata(bundle)
+    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({
+        slug: agent.slug,
+        bundle: bundle.toString("base64"),
+        ...(sandboxConfig && { sandboxConfig }),
+        ...(metadata && { metadata }),
+      }),
+    })
+
+    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/${a.slug}`)
+        }
+      }
+      process.exit(1)
+    }
+
+    const result = await res.json()
+    deployed.push({ slug: agent.slug })
+    const versionTag = result.version ? ` (v${result.version})` : ""
+    s2.stop(`${agent.slug} deployed${versionTag}`)
+  }
+
+  // 4. Output
+  p.log.success(`Deployed ${deployed.length} agent${deployed.length > 1 ? "s" : ""}`)
+  console.log()
+  for (const agent of deployed) {
+    console.log(`  ${agent.slug}  →  ${AN_BASE}/a/${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/detect.ts

@@ -0,0 +1,16 @@
+// Detect AI agents running in pseudo-TTY
+export function isAgent(): boolean {
+  return !!(
+    process.env.CLAUDE_CODE ||
+    process.env.CLAUDECODE ||
+    process.env.CURSOR_TRACE_ID ||
+    process.env.CURSOR_AGENT ||
+    process.env.CODEX_SANDBOX ||
+    process.env.GEMINI_CLI ||
+    process.env.AI_AGENT
+  )
+}
+
+export function isInteractive(): boolean {
+  return !!process.stdin.isTTY && !isAgent()
+}

package/src/env.ts

@@ -0,0 +1,136 @@
+import { getApiKey } from "./config.js"
+import * as p from "@clack/prompts"
+
+const API_BASE = process.env.AN_API_URL || "https://an.dev/api/v1"
+
+function maskValue(value: string): string {
+  if (value.length <= 4) return "\u2022".repeat(value.length)
+  return value.slice(0, 2) + "\u2022".repeat(Math.min(value.length - 4, 12)) + value.slice(-2)
+}
+
+function requireAuth(): string {
+  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)
+  }
+  return apiKey
+}
+
+function requireAgentSlug(args: string[]): string {
+  const slug = args[0]
+  if (!slug || slug.startsWith("-")) {
+    p.log.error("Agent slug is required. Usage: an env list <agent-slug>")
+    process.exit(1)
+  }
+  return slug
+}
+
+async function fetchEnvVars(apiKey: string, agentSlug: string): Promise<Record<string, string>> {
+  const res = await fetch(`${API_BASE}/agents/${agentSlug}/env`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  })
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}))
+    throw new Error((err as any).message || `Failed to fetch env vars (${res.status})`)
+  }
+  const data = await res.json()
+  return data.envVars ?? {}
+}
+
+async function putEnvVars(apiKey: string, agentSlug: string, envVars: Record<string, string> | null): Promise<void> {
+  const res = await fetch(`${API_BASE}/agents/${agentSlug}/env`, {
+    method: "PUT",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ envVars }),
+  })
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}))
+    throw new Error((err as any).message || `Failed to update env vars (${res.status})`)
+  }
+}
+
+export async function envList(args: string[]) {
+  const apiKey = requireAuth()
+  const agentSlug = requireAgentSlug(args)
+  const showValues = args.includes("--show-values")
+
+  try {
+    const vars = await fetchEnvVars(apiKey, agentSlug)
+    const keys = Object.keys(vars)
+
+    if (keys.length === 0) {
+      p.log.info("No environment variables set.")
+      return
+    }
+
+    console.log()
+    for (const key of keys) {
+      const display = showValues ? vars[key] : maskValue(vars[key]!)
+      console.log(`  ${key}=${display}`)
+    }
+    console.log()
+    p.log.info(`${keys.length} variable${keys.length !== 1 ? "s" : ""}`)
+  } catch (err: any) {
+    p.log.error(err.message)
+    process.exit(1)
+  }
+}
+
+export async function envSet(args: string[]) {
+  const apiKey = requireAuth()
+  const agentSlug = requireAgentSlug(args)
+
+  const key = args[1]
+  const value = args.slice(2).join(" ")
+
+  if (!key || !value) {
+    p.log.error("Usage: an env set <agent-slug> KEY VALUE")
+    process.exit(1)
+  }
+
+  if (!/^[A-Z0-9_]+$/.test(key)) {
+    p.log.error("Invalid key. Use uppercase letters, numbers, and underscores only.")
+    process.exit(1)
+  }
+
+  try {
+    const vars = await fetchEnvVars(apiKey, agentSlug)
+    const existed = key in vars
+    vars[key] = value
+    await putEnvVars(apiKey, agentSlug, vars)
+    p.log.success(existed ? `Updated ${key}` : `Set ${key}`)
+  } catch (err: any) {
+    p.log.error(err.message)
+    process.exit(1)
+  }
+}
+
+export async function envRemove(args: string[]) {
+  const apiKey = requireAuth()
+  const agentSlug = requireAgentSlug(args)
+
+  const key = args[1]
+  if (!key) {
+    p.log.error("Usage: an env remove <agent-slug> KEY")
+    process.exit(1)
+  }
+
+  try {
+    const vars = await fetchEnvVars(apiKey, agentSlug)
+    if (!(key in vars)) {
+      p.log.info(`${key} not found`)
+      return
+    }
+    delete vars[key]
+    const envVars = Object.keys(vars).length > 0 ? vars : null
+    await putEnvVars(apiKey, agentSlug, envVars)
+    p.log.success(`Removed ${key}`)
+  } catch (err: any) {
+    p.log.error(err.message)
+    process.exit(1)
+  }
+}