@botpress/adk-cli 1.19.0-beta.3 → 1.19.0-beta.5

package/dist/model-configuration-f273kgd0.md

@@ -0,0 +1,201 @@
+# Model Configuration Reference
+
+Quick reference for configuring AI models at different levels in ADK agents.
+
+---
+
+## 1. Global Defaults (agent.config.ts)
+
+```typescript
+import { defineConfig } from "@botpress/runtime";
+
+export default defineConfig({
+  name: "my-agent",
+
+  defaultModels: {
+    autonomous: "openai:gpt-4o",        // Used by execute()
+    zai: "openai:gpt-4o-mini"           // Used by Zai operations
+  }
+});
+```
+
+### With Fallback Arrays
+
+```typescript
+defaultModels: {
+  autonomous: [
+    "openai:gpt-4o",
+    "anthropic:claude-3-5-sonnet",
+    "openai:gpt-4o-mini"
+  ],
+  zai: "openai:gpt-4o-mini"
+}
+```
+
+---
+
+## 2. Per-Call Override (execute)
+
+```typescript
+await execute({
+  instructions: "You are a helpful assistant",
+  model: "anthropic:claude-3-5-sonnet",
+  temperature: 0.7
+});
+```
+
+### With Fallback Array
+
+```typescript
+await execute({
+  instructions: "You are a helpful assistant",
+  model: [
+    "openai:gpt-4o",
+    "anthropic:claude-3-5-sonnet"
+  ]
+});
+```
+
+---
+
+## 3. Zai Model Override
+
+Override the default Zai model per-instance using `.with()`:
+
+```typescript
+import { adk } from "@botpress/runtime";
+
+const preciseZai = adk.zai.with({ modelId: "openai:gpt-4o" });
+await preciseZai.extract(text, schema);
+```
+
+> For full Zai configuration (initialization, chaining, learning, operations), see [zai-agent-reference.md](./zai-agent-reference.md) and [zai-complete-guide.md](./zai-complete-guide.md).
+
+---
+
+## 4. Available Models
+
+### Model Name Format
+
+Models follow the pattern: `{provider}:{model-name}`
+
+```typescript
+"openai:gpt-4o"                    // Short name
+"openai:gpt-4.1-2025-04-14"        // Dated version (more specific)
+"anthropic:claude-3-5-sonnet"      // Short name
+"anthropic:claude-sonnet-4-5-20250929"  // Dated version
+"best"                             // Zai shortcut (highest quality)
+"fast"                             // Zai shortcut (fastest/cheapest)
+```
+
+**Finding Available Models:**
+- The Models type accepts any string, so new models work automatically
+- For current available models, check the `Models` type in `@botpress/cognitive`
+- Use TypeScript autocomplete: Start typing a provider name to see suggestions
+- Dated versions (e.g., `gpt-4.1-2025-04-14`) are more explicit about which version you're using
+
+### Common Models
+
+### OpenAI
+```
+openai:gpt-4o
+openai:gpt-4o-mini
+openai:gpt-4-turbo
+openai:gpt-3.5-turbo
+```
+
+### Anthropic
+```
+anthropic:claude-3-5-sonnet
+anthropic:claude-3-opus
+anthropic:claude-3-haiku
+```
+
+### Google
+```
+google:gemini-1.5-pro
+google:gemini-1.5-flash
+```
+
+### Cerebras
+```
+cerebras:gpt-oss-120b
+```
+
+### Zai Shortcuts
+```
+best    # Highest quality model
+fast    # Fastest/cheapest model
+```
+
+---
+
+## 5. Precedence Order
+
+**For execute():**
+1. `execute({ model: "..." })` - Per-call override
+2. `agent.config.ts defaultModels.autonomous` - Global default
+
+**For Zai:**
+1. `zai.with({ modelId: "..." })` - Instance override
+2. `new Zai({ modelId: "..." })` - Constructor config
+3. `agent.config.ts defaultModels.zai` - Global default
+
+---
+
+## 6. Environment-Based Configuration
+
+```typescript
+export default defineConfig({
+  name: "my-agent",
+  defaultModels: {
+    autonomous: process.env.AI_MODEL || "openai:gpt-4o",
+    zai: process.env.ZAI_MODEL || "openai:gpt-4o-mini"
+  }
+});
+```
+
+---
+
+## Quick Examples
+
+### Conversation with Custom Model
+
+```typescript
+export default new Conversation({
+  channel: "*",
+  handler: async ({ execute }) => {
+    await execute({
+      instructions: "You are a helpful assistant",
+      model: "anthropic:claude-3-5-sonnet"
+    });
+  }
+});
+```
+
+### Workflow with Model Override
+
+```typescript
+export default Workflow({
+  name: "research",
+  handler: async ({ step, execute }) => {
+    const result = await step("analyze", async () => {
+      return await execute({
+        instructions: "Analyze this data",
+        model: "openai:gpt-4o"
+      });
+    });
+    return result;
+  }
+});
+```
+
+### Zai Operation with Specific Model
+
+```typescript
+import { adk } from "@botpress/runtime";
+
+const analysis = await adk.zai
+  .with({ modelId: "anthropic:claude-3-5-sonnet" })
+  .extract(document, schema);
+```

package/dist/multi-agent-dashboard-1mdfjdts.md

@@ -0,0 +1,70 @@
+# Multi-Agent Dashboard
+
+The Dev Console is a **singleton shared dashboard** that coordinates multiple running agents. Each `adk dev` process registers its agent with the shared DevConsole, and the UI lets developers switch between them instantly.
+
+## How It Works
+
+Running `adk dev` in multiple project directories registers each agent with a single shared DevConsole. The UI automatically updates to show all running agents, and developers can switch between them from the sidebar.
+
+Each agent shows a status indicator:
+
+| Status | Meaning |
+|--------|---------|
+| `starting` | Agent is initializing (building, syncing) |
+| `ready` | Agent is running and accepting requests |
+| `error` | Agent encountered a fatal error |
+
+If all agents are stopped, the DevConsole exits automatically (unless started in standalone mode via `adk dashboard`).
+
+## Console Modes
+
+The Dev Console supports two orthogonal concepts:
+
+### Console Mode — where is the console operating?
+
+- **Local Dev Console** — selects a local project registered over the socket. This is the default during `adk dev`.
+- **Cloud Dev Console** — selects a deployed Botpress Cloud prod bot from the prod bot picker. No local project backend needed.
+
+### Target — which bot data is used?
+
+- **Dev target** — uses the local project's dev bot ID and local backend. All pages available.
+- **Prod target** — uses the deployed prod bot data. Hides dev-only pages (Actions, Workflows, Triggers, Evals, Files, Conversations, Traces, Logs).
+
+| Console Mode | Dev Target | Prod Target |
+|-------------|------------|-------------|
+| Local | Local dev bot + all pages | Prod bot data + restricted pages |
+| Cloud | Not available | Prod bot data + restricted pages |
+
+Prod views that need ADK source-shaped definitions (actions, workflows, triggers, tables, knowledge) read **deployed metadata** published by `adk deploy`, not local source files. This is true in both local-prod and cloud-prod modes.
+
+## Agent Selector UI
+
+### Sidebar Header
+
+Full-width dropdown trigger showing: ADK logo, status ring (color matches agent status), agent name, mode pill (dev/prod/cloud), chevron.
+
+### Dropdown Content
+
+- **Active agents section** — lists running local agents with status dot, name, project path (truncated right-to-left), and close button
+- **Cloud Dev Console** — switches to the prod bot picker (workspace dropdown → bot list), shows recent prod bots
+- **Recent projects** — projects previously opened but not currently running
+- **Footer actions** — Create new project, Open existing project, Switch environment (dev↔prod), About
+
+### Topbar Agent Picker
+
+Compact pill in the top navigation center: status dot + agent name + mode pill + chevron. Opens the same dropdown content. Falls back to a non-interactive label if no agents are connected.
+
+## CLI Commands
+
+See the [CLI Reference](../../adk/references/cli.md) for full options and examples.
+
+| Command | What it does |
+|---------|-------------|
+| `adk ps` | List running agents and processes |
+| `adk dashboard` | Open Dev Console without an agent |
+| `adk kill` | Stop agents or the Dev Console |
+| `adk status` | Show project health info |
+
+## Data Isolation
+
+Each agent's data is isolated to its own project directory (`.adk/`). Traces, logs, eval results, and dev bot IDs stay per-project — switching agents in the UI switches the data you see.

package/dist/pages-xn18xn73.md

@@ -0,0 +1,273 @@
+# Dev Console Pages
+
+Every page accessible from the ADK Dev Console at `http://localhost:3001`.
+
+Pages marked **(dev only)** are hidden when the environment toggle is set to Production.
+Pages marked **(experimental)** are behind a feature flag and may change.
+
+---
+
+## Multi-Agent Navigation
+
+The Dev Console is a shared singleton — multiple `adk dev` agents register with one UI server. The sidebar agent selector switches between running agents, and the environment toggle switches between dev and prod targets. See [multi-agent-dashboard.md](./multi-agent-dashboard.md) for details.
+
+---
+
+## Chat (`/chat`)
+
+Real-time conversation interface for testing the agent.
+
+**Layout:** Webchat embed (left) + Agent Steps visualization (right)
+
+**Features:**
+- Webchat panel for sending messages to the agent
+- Agent Steps panel showing execution flow (see `agent-steps.md`)
+- Conversation picker dropdown (filters to webchat conversations)
+- "Open conversation traces" link to jump to full Traces view
+- Download transcript button
+
+---
+
+## Agent Map (`/agent-map`) — dev only, experimental
+
+Interactive bird's-eye visualization of the agent's architecture as a graph. Feature-flagged behind `enable_agent_forge`.
+
+**Layout:** Full-screen React Flow canvas with auto-layout (elkjs) + detail panel
+
+**Features:**
+- Graph nodes for agent primitives: triggers, actions, workflows, autonomous handlers, knowledge bases, tables
+- Edges showing relationships between primitives
+- Auto-layout with elkjs; user can drag nodes (positions persist to localStorage per agent)
+- Detail panel: click a node to inspect metadata (description, knowledge counts, table schemas)
+- Hover cards with node summary
+- Change pulse animation when the agent snapshot updates (e.g., after file save)
+- Data from `/api/agent-map/snapshot` (one-shot) and `/api/agent-map/stream` (SSE for live updates)
+- "Experimental feature" badge — the map is compiled by parsing code and may be incomplete or inaccurate
+
+---
+
+## Components
+
+### Webchat Components (`/components`)
+
+Browse the component registry and inspect components installed in the agent.
+
+**Layout:** Two-tab interface (Installed / Registry) + masonry card grid + detail overlay
+
+**Tabs:**
+
+**Installed** — Components present in the agent's `src/components/` directory:
+- Masonry card layout with component preview (rendered in shadow DOM)
+- Click a card to open overlay with full details
+- Empty state: "No components installed yet" with guidance
+
+**Registry** — Available components from the external component registry:
+- Same masonry layout
+- Click a card to open overlay with installation instructions and metadata
+- Empty state: "Registry is empty"
+
+**Features:**
+- Live reload on component source changes
+- Preview rendering via shadow DOM isolation
+- Error states for load/fetch failures
+- Loading skeletons while fetching
+
+See `component-registry.md` for details on the registry model and component lifecycle.
+
+### Actions (`/actions`) — dev only
+
+Browse and test bot actions and integration actions.
+
+**Layout:** Sidebar (action list) + detail pane
+
+**Features:**
+- Bot custom actions with input/output schema visualization
+- Integration actions grouped by integration (icon, title, description)
+- "Invoke action" button opens a modal to test with live inputs
+- Schema view for input/output types
+
+### Workflows (`/workflows`) — dev only
+
+Browse workflows and view execution history.
+
+**Layout:** Sidebar (workflow list) + detail pane
+
+**Features:**
+- Workflow name, path, description, timeout badge
+- "Invoke workflow" button to trigger manually
+- Workflow definition schema
+- **Runs tab** (`/workflows/runs`): execution history table with status, duration, timestamp
+- Click a run to open WorkflowRunDetail modal
+
+### Triggers (`/triggers`) — dev only
+
+Browse event triggers defined in the agent.
+
+**Layout:** Sidebar (trigger list) + detail pane
+
+**Features:**
+- Trigger names and event types
+- Trigger metadata and status
+
+---
+
+## Test
+
+### RAG Search (`/search`)
+
+Test knowledge base search interactively.
+
+**Layout:** Sidebar (KB filter + content tree) + search input + results area + detail drawer
+
+**Features:**
+- Dropdown to filter by specific knowledge base
+- Query input with advanced settings (result limit, context depth)
+- Search results as cards: relevance score, source file, text snippet
+- Content tree sidebar showing hierarchical KB structure
+- Click a result to open detail drawer with full document + highlighted passages
+- Real-time search as you type
+
+### Evals (`/evals`) — dev only
+
+Run and inspect automated conversation tests.
+
+**Layout:** Sidebar (eval list) + detail pane
+
+**Features:**
+- Eval definitions with run history
+- Run status: pending, in-progress, completed
+- Per-turn assertion results with pass/fail badges
+- Assertion types: response content, tool usage, state changes, table data, workflow triggers
+- Outcome summary (passed/failed/pending counts)
+- Elapsed time, turn counts
+- **Runs tab** (`/evals/runs`): run history with timestamps and status
+- Download results button
+
+---
+
+## Data
+
+### Knowledge (`/knowledge`)
+
+Manage knowledge bases and uploaded files.
+
+**Layout:** Sidebar (KB list) + toolbar + file grid
+
+**Features:**
+- Knowledge base list with icons and descriptions
+- File grid: name, size, upload date, status badge (synced/syncing/error/local)
+- Filter by name, source, status, date range
+- Sort by name, date, or size
+- File detail drawer: metadata, embedding status, delete/sync/copy path
+- KB sync dialog to upload and sync files
+- Pagination for large file lists
+
+### Tables (`/tables`)
+
+Manage agent data tables.
+
+**Layout:** Sidebar (table list) + toolbar + data grid + pagination
+
+**Features:**
+- Table definitions with row counts
+- Sortable, filterable data grid (100 rows/page)
+- Add/edit/delete rows
+- Import/export data
+- "Transfer to prod" option (with confirmation modal)
+- "Recreate table" for schema changes
+- Column headers with sort indicators
+
+### Files (`/files`) — dev only
+
+Browse agent files.
+
+**Layout:** Folder browser
+
+**Features:**
+- Folder tree: All Files, Knowledge Base, System, Webchat
+- File list with name, size, modification time
+- Copy file path button
+- Hover cards with full file info
+- Browser-style navigation (back/forward/refresh)
+
+---
+
+## Observe
+
+### Conversations (`/conversations`) — dev only
+
+View all conversations with the agent.
+
+**Layout:** Full-page table
+
+**Features:**
+- Table columns: ID, Integration → Channel, Created, Updated, Preview
+- Sortable columns
+- Real-time polling for new conversations
+- Click row to inspect conversation
+
+### Traces (`/traces`) — dev only
+
+Deep execution trace inspection. More detailed than Agent Steps — shows the full span tree including internal runtime spans.
+
+**Layout:** Full-page trace viewer
+
+**Features:**
+- Hierarchical span tree grouped by parent
+- Span detail panel: name, timing, status, full data payload
+- JSON and tree view of span data
+- Filter by trace ID or conversation ID
+- Auto-refresh
+- Trace-level cost calculation
+- Timeline visualization showing concurrent spans
+
+### Logs (`/logs`) — dev only
+
+Agent runtime logs.
+
+**Layout:** Full-page log viewer
+
+**Features:**
+- Real-time log stream (stdout, stderr, info)
+- Time range filters: 5m, 15m, 1h, 6h, all
+- Text search/filter
+- Color-coded: green (stdout), red (stderr), blue (info)
+- ANSI color support (terminal-style rendering)
+- Pause/play, clear, copy buttons
+- Collapsible JSON payload inspection
+
+---
+
+## Config
+
+### Settings (`/settings`)
+
+Agent configuration management.
+
+**Sections (sidebar navigation):**
+1. **Overview** — Agent metadata: name, Bot ID, Workspace ID, file path, created/updated dates. Copy buttons for IDs.
+2. **Configuration Variables** (dev only) — Runtime config schema and values. Add/edit/delete variables.
+3. **Secrets** (dev only) — Secret schema and values. Add/edit/delete secrets.
+4. **LLM Config** (dev only) — Model selection and parameters.
+
+### Integrations (`/integrations`)
+
+Install, configure, and manage integrations.
+
+**Features:**
+- Integration Hub UI (Botpress component)
+- OAuth redirect handling
+- Integration name and alias resolution
+- Configuration editing via UI
+- Installation status per integration
+- Configured integrations' actions appear on the Actions page
+
+---
+
+## Dev vs. Production Mode
+
+The environment toggle in the top navigation switches between dev and prod:
+
+**Dev mode** (default during `adk dev`): All pages and features available.
+
+**Production mode**: Hides development-only pages (Actions, Workflows, Triggers, Evals, Files, Conversations, Traces, Logs) and restricts some Settings sections. Chat, Search, Knowledge, Tables, Integrations, and Settings Overview remain available.