@botpress/adk 1.15.4 → 1.16.1

package/dist/index.js

@@ -718,7 +718,7 @@ var PRETTIER_CONFIG, formatCode = async (code, filepath) => {
 `));
     return code;
   }
-}, ADK_VERSION = "1.15.4", relative2 = (from, to) => {
+}, ADK_VERSION = "1.16.1", relative2 = (from, to) => {
   const fromDir = path10.dirname(from);
   const relative3 = path10.relative(fromDir, to);
   return relative3.startsWith(".") ? relative3 : `./${relative3}`;
@@ -861,7 +861,7 @@ var init_integration_action_types = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@botpress/adk",
-    version: "1.15.4",
+    version: "1.16.1",
     description: "Core ADK library for building AI agents on Botpress",
     type: "module",
     main: "dist/index.js",
@@ -905,10 +905,11 @@ var require_package = __commonJS((exports, module) => {
       url: "https://github.com/botpress/adk"
     },
     dependencies: {
+      "@botpress/chat": "^0.5.5",
       "@botpress/cli": "^5.2.0",
       "@botpress/client": "^1.35.0",
       "@botpress/cognitive": "^0.3.14",
-      "@botpress/runtime": "^1.15.4",
+      "@botpress/runtime": "^1.16.1",
       "@botpress/sdk": "^5.4.3",
       "@bpinternal/jex": "^1.2.4",
       "@bpinternal/yargs-extra": "^0.0.21",
@@ -3280,6 +3281,62 @@ class ConfigWriter {
     }
     await this.saveConfig(sourceFile);
   }
+  async updateConfiguration(updates) {
+    const { sourceFile, configObject } = this.loadConfig();
+    const hasAdds = updates.some((u) => u.action === "add");
+    let configProp = configObject.getProperty("configuration");
+    if (!configProp) {
+      if (!hasAdds)
+        return;
+      configProp = configObject.addPropertyAssignment({
+        name: "configuration",
+        initializer: "{ schema: z.object({}) }"
+      });
+    }
+    const configInit = configProp.getInitializerIfKind(SyntaxKind.ObjectLiteralExpression);
+    if (!configInit)
+      return;
+    let schemaProp = configInit.getProperty("schema");
+    if (!schemaProp) {
+      if (!hasAdds)
+        return;
+      schemaProp = configInit.addPropertyAssignment({
+        name: "schema",
+        initializer: "z.object({})"
+      });
+    }
+    const schemaCall = schemaProp.getInitializerIfKind(SyntaxKind.CallExpression);
+    if (!schemaCall)
+      return;
+    const schemaArg = schemaCall.getArguments()[0];
+    if (!schemaArg || !schemaArg.isKind(SyntaxKind.ObjectLiteralExpression))
+      return;
+    const schemaObject = schemaArg;
+    for (const update of updates) {
+      const existing = schemaObject.getProperty(update.field);
+      switch (update.action) {
+        case "add":
+          if (!existing && update.definition) {
+            schemaObject.addPropertyAssignment({
+              name: update.field,
+              initializer: update.definition
+            });
+          }
+          break;
+        case "update":
+          if (existing && update.definition) {
+            existing.setInitializer(update.definition);
+          }
+          break;
+        case "remove":
+          if (existing) {
+            existing.remove();
+          }
+          break;
+      }
+    }
+    await this.saveConfig(sourceFile);
+  }
 }
 
 // src/integrations/operations.ts
@@ -5112,6 +5169,45 @@ init_types();
 // src/config/manager.ts
 import { Client as Client12 } from "@botpress/client";
 import { sync as jex } from "@bpinternal/jex";
+
+// src/config/coerce-config-value.ts
+function coerceConfigValue(value, fieldSchema) {
+  const typeName = getInnerTypeName(fieldSchema);
+  switch (typeName) {
+    case "ZodNumber": {
+      const num = Number(value);
+      if (Number.isNaN(num)) {
+        return value;
+      }
+      return num;
+    }
+    case "ZodBoolean": {
+      const lower = value.toLowerCase();
+      if (lower === "true" || lower === "1" || lower === "yes") {
+        return true;
+      }
+      if (lower === "false" || lower === "0" || lower === "no") {
+        return false;
+      }
+      return value;
+    }
+    default:
+      return value;
+  }
+}
+function getInnerTypeName(schema) {
+  const def = schema?._def;
+  if (!def) {
+    return "unknown";
+  }
+  const typeName = def.typeName ?? "unknown";
+  if ((typeName === "ZodOptional" || typeName === "ZodNullable" || typeName === "ZodDefault") && def.innerType) {
+    return getInnerTypeName(def.innerType);
+  }
+  return typeName;
+}
+
+// src/config/manager.ts
 class ConfigManager {
   botId;
   client;
@@ -5201,1552 +5297,328 @@ class ConfigManager {
     const validation = await this.validate(schema);
     return validation.valid;
   }
+  async describeSchema(schema) {
+    const stored = await this.load();
+    const shape = schema.shape;
+    const fields = [];
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+      const innerType = getInnerTypeName(fieldSchema);
+      const def = fieldSchema?._def;
+      let type = "unknown";
+      if (innerType === "ZodString")
+        type = "string";
+      else if (innerType === "ZodNumber")
+        type = "number";
+      else if (innerType === "ZodBoolean")
+        type = "boolean";
+      const typeName = def?.typeName ?? "";
+      const isOptional = typeName === "ZodOptional" || typeName === "ZodNullable";
+      const hasDefault = typeName === "ZodDefault";
+      const required = !isOptional && !hasDefault;
+      let defaultValue = undefined;
+      if (hasDefault) {
+        defaultValue = def.defaultValue?.();
+      }
+      const description = fieldSchema.description ?? undefined;
+      fields.push({
+        key,
+        type,
+        required,
+        description,
+        defaultValue,
+        currentValue: stored[key]
+      });
+    }
+    return fields;
+  }
+  async setWithValidation(key, value, schema) {
+    const shape = schema.shape;
+    const fieldSchema = shape[key];
+    if (!fieldSchema) {
+      return { success: false, error: `Key "${key}" not found in configuration schema` };
+    }
+    const coerced = typeof value === "string" ? coerceConfigValue(value, fieldSchema) : value;
+    const result = fieldSchema.safeParse(coerced);
+    if (!result.success) {
+      const messages = result.error.issues.map((i) => i.message);
+      return { success: false, error: messages.join("; ") };
+    }
+    await this.set(key, result.data);
+    return { success: true, data: result.data };
+  }
 }
 // src/agent-init/agent-project-generator.ts
 init_utils();
 import * as fs11 from "fs";
 import * as path15 from "path";
 
-// src/agent-init/CLAUDE.template.md
-var CLAUDE_template_default = `# Botpress ADK Project Context
+// src/agent-init/ai-assistant-instructions.template.md
+var ai_assistant_instructions_template_default = `# Botpress ADK Agent
 
-This project is built with the **Botpress Agent Development Kit (ADK)** - a TypeScript-first framework for building AI agents.
+> This project is built with the **Botpress Agent Development Kit (ADK)** — a TypeScript-first framework for building AI agents.
 
-## Table of Contents
+## Key Files
 
-- [Quick Reference: Use the Botpress MCP Server](#quick-reference-use-the-botpress-mcp-server)
-- [What is the ADK?](#what-is-the-adk)
-- [ADK CLI](#adk-cli)
-- [Core Concepts](#core-concepts)
-  - [1. Agent Configuration](#1-agent-configuration-agentconfigts)
-  - [2. Conversations](#2-conversations-srcconversations)
-  - [3. Workflows](#3-workflows-srcworkflows)
-  - [4. Tools](#4-tools-srctools)
-  - [5. Knowledge Bases](#5-knowledge-bases-srcknowledge)
-  - [6. Actions](#6-actions-srcactions)
-  - [7. Zai Library](#7-zai-library)
-- [Project Structure](#project-structure)
-- [Development Workflow](#development-workflow)
-- [Examples](#examples)
-- [Best Practices](#best-practices)
-- [Common APIs](#common-apis)
-- [Advanced Autonomous Execution](#advanced-autonomous-execution)
-- [State and Metadata Management](#state-and-metadata-management)
-- [Advanced Table Operations](#advanced-table-operations)
-- [Knowledge Base Operations](#knowledge-base-operations)
-- [Advanced Conversation Patterns](#advanced-conversation-patterns)
-- [Citations System](#citations-system)
-- [When Making Changes](#when-making-changes)
-- [Resources](#resources)
+- \`agent.config.ts\` — Agent configuration, models, state schemas, and dependencies
+- \`src/conversations/\` — Message handlers (primary user interaction)
+- \`src/workflows/\` — Long-running background processes
+- \`src/tools/\` — AI-callable functions
+- \`src/actions/\` — Reusable business logic
+- \`src/knowledge/\` — RAG knowledge base sources
+- \`src/tables/\` — Database table definitions
+- \`src/triggers/\` — Event-based triggers
 
-## Quick Reference: Use the Botpress MCP Server
+## Development
 
-**IMPORTANT**: When working on this project, always search the Botpress documentation using the \`mcp__botpress-docs__SearchBotpress\` tool before making changes. The ADK has specific patterns and APIs that are well-documented.
+\`\`\`bash
+adk dev      # Start dev server with hot reload
+adk build    # Build and generate types
+adk deploy   # Deploy to Botpress Cloud
+adk chat     # Chat with your agent in the terminal
+\`\`\`
 
-## What is the ADK?
+## AI Coding Assistant Skills
 
-The ADK allows developers to build Botpress agents using **code instead of the Studio interface**. It provides:
+This project uses the Botpress ADK. Before making changes, use the relevant skill:
 
-- Project scaffolding with TypeScript
-- Hot reloading development server (\`adk dev\`)
-- Type-safe APIs and auto-generated types
-- Build and deploy to Botpress Cloud
+| Skill              | Use for                                          |
+| ------------------ | ------------------------------------------------ |
+| \`/adk\`             | ADK concepts, patterns, and API reference        |
+| \`/adk-integration\` | Finding and using Botpress integrations           |
+| \`/adk-debugger\`    | Debugging with traces and test conversations      |
+| \`/adk-frontend\`    | Building frontends that connect to ADK bots       |
 
-## ADK CLI
+If these skills are not installed, install them:
 
-The ADK CLI is installed globally. You can run it using \`adk <command>\`.
-Always use bash to run ADK. (\`Bash(adk)\`)
-To install an integration: \`adk install <integration>\`
-To generate types without running in dev mode: \`adk build\`
+\`\`\`
+npx skills add botpress/skills --skill adk
+\`\`\`
 
-## Core Concepts
+## Project Overview
 
-### 1. Agent Configuration (\`agent.config.ts\`)
+<!-- Describe what your agent does -->
 
-The main configuration file defines:
+## Architecture & Conventions
 
-- **Agent name and description**
-- **Default models** for autonomous and zai operations
-- **State schemas** (bot-level and user-level state using Zod)
-- **Configuration variables** (encrypted, secure storage for API keys)
-- **Integration dependencies** (webchat, chat, etc.)
+<!-- Add project-specific patterns, decisions, and conventions -->
 
-\`\`\`typescript
-export default defineConfig({
-  name: "my-agent",
+## Notes
+
+<!-- Add anything else relevant to your project -->
+`;
+
+// src/agent-init/agent-project-generator.ts
+class AgentProjectGenerator {
+  projectPath;
+  projectName;
+  packageManager;
+  template;
+  constructor(projectPath, packageManager = "bun", template = "blank") {
+    this.projectPath = path15.resolve(projectPath);
+    this.projectName = path15.basename(this.projectPath);
+    this.packageManager = packageManager;
+    this.template = template;
+  }
+  async generate() {
+    this.ensureEmptyDirectory();
+    this.createPackageJson();
+    await this.createAgentConfig();
+    this.createTsConfig();
+    this.createAgentJson();
+    this.createGitIgnore();
+    await this.createReadme();
+    this.createAIAssistantInstructions();
+    await this.createSourceStructure();
+  }
+  ensureEmptyDirectory() {
+    if (!fs11.existsSync(this.projectPath)) {
+      fs11.mkdirSync(this.projectPath, { recursive: true });
+    }
+    const files = fs11.readdirSync(this.projectPath);
+    if (files.length > 0) {
+      throw new Error(`Directory ${this.projectPath} is not empty. Please use an empty directory.`);
+    }
+  }
+  createPackageJson() {
+    const packageJson = {
+      name: this.projectName,
+      version: "1.0.0",
+      description: `A Botpress Agent built with the ADK`,
+      type: "module",
+      packageManager: this.packageManager === "npm" ? undefined : `${this.packageManager}@latest`,
+      scripts: {
+        dev: "adk dev",
+        build: "adk build",
+        deploy: "adk deploy"
+      },
+      dependencies: {
+        "@botpress/runtime": `^${"1.16.1"}`
+      },
+      devDependencies: {
+        typescript: "^5.9.3"
+      }
+    };
+    if (packageJson.packageManager === undefined) {
+      delete packageJson.packageManager;
+    }
+    this.writeJsonFile("package.json", packageJson);
+  }
+  getDefaultDependencies() {
+    const dependencies = {
+      integrations: {}
+    };
+    if (this.template === "hello-world") {
+      dependencies.integrations = {
+        chat: {
+          version: "chat@latest",
+          enabled: true
+        },
+        webchat: {
+          version: "webchat@latest",
+          enabled: true
+        }
+      };
+    }
+    return dependencies;
+  }
+  async createAgentConfig() {
+    const dependencies = this.getDefaultDependencies();
+    const integrationsJson = JSON.stringify(dependencies.integrations, null, 4).replace(/\n/g, `
+    `);
+    const defaultModels = this.template === "hello-world" ? `
   defaultModels: {
     autonomous: "cerebras:gpt-oss-120b",
     zai: "cerebras:gpt-oss-120b",
   },
-  bot: { state: z.object({}) },
-  user: { state: z.object({}) },
-  dependencies: {
-    integrations: {
-      webchat: { version: "webchat@0.3.0", enabled: true },
-    },
-  },
-});
-\`\`\`
-
-### 2. Conversations (\`src/conversations/\`)
-
-**Primary way agents handle user messages**. Each conversation handler:
-
-- Responds to messages from specific channels
-- Uses \`execute()\` to run autonomous AI logic
-- Can access conversation state, send messages, and call tools
-
-**Key Pattern**: The \`execute()\` function runs the agent's AI loop:
+` : "";
+    const agentConfig = `import { z, defineConfig } from '@botpress/runtime';
 
-\`\`\`typescript
-export default new Conversation({
-  channel: "webchat.channel",
-  handler: async ({ execute, conversation, state }) => {
-    await execute({
-      instructions: "Your agent's instructions here",
-      tools: [myTool1, myTool2],
-      knowledge: [myKnowledgeBase],
-    });
+export default defineConfig({
+  name: '${this.projectName}',
+  description: 'An AI agent built with Botpress ADK',
+${defaultModels}
+  bot: {
+    state: z.object({}),
   },
-});
-\`\`\`
-
-### 3. Workflows (\`src/workflows/\`)
-
-**Long-running processes** for complex, multi-step operations:
 
-- Can run on schedules (cron syntax)
-- Run independently or triggered by events
-- NOT the same as Studio Workflows
-- Use \`step()\` for durable execution (survives restarts)
+  user: {
+    state: z.object({}),
+  },
 
-\`\`\`typescript
-export default new Workflow({
-  name: "periodic-indexing",
-  schedule: "0 */6 * * *",
-  handler: async ({ step }) => {
-    await step("task-name", async () => {
-      // Your logic here
-    });
+  dependencies: {
+    integrations: ${integrationsJson},
   },
 });
-\`\`\`
-
-#### Advanced Workflow Step Methods
-
-Beyond basic \`step()\`, workflows have powerful methods for complex orchestration:
-
-**Parallel Processing:**
-
-- \`step.map()\` - Process array items in parallel with concurrency control
-- \`step.forEach()\` - Like map but for side effects (returns void)
-- \`step.batch()\` - Process in sequential batches
-
-\`\`\`typescript
-// Process items in parallel
-const results = await step.map(
-  'process-items',
-  items,
-  async (item, { i }) => processItem(item),
-  { concurrency: 5, maxAttempts: 3 }
-)
-
-// Batch processing
-await step.batch(
-  'bulk-insert',
-  records,
-  async (batch) => database.bulkInsert(batch),
-  { batchSize: 100 }
-)
-\`\`\`
+`;
+    await this.writeFormattedFile("agent.config.ts", agentConfig);
+  }
+  createTsConfig() {
+    const tsConfig = {
+      compilerOptions: {
+        target: "ES2022",
+        module: "ES2022",
+        moduleResolution: "Bundler",
+        lib: ["ES2022", "DOM"],
+        outDir: "./dist",
+        rootDir: ".",
+        strict: true,
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+        skipLibCheck: true,
+        forceConsistentCasingInFileNames: true,
+        moduleDetection: "force",
+        resolveJsonModule: true,
+        paths: {
+          "@botpress/runtime/_types/*": ["./.adk/*-types"]
+        }
+      },
+      include: ["src/**/*", ".adk/**/*"],
+      exclude: ["node_modules", "dist"]
+    };
+    this.writeJsonFile("tsconfig.json", tsConfig);
+  }
+  createAgentJson() {
+    const agentJson = {};
+    this.writeJsonFile("agent.json", agentJson);
+  }
+  createGitIgnore() {
+    const gitIgnore = `# Dependencies
+node_modules/
+.pnpm-store/
 
-**Workflow Coordination:**
+# Build outputs
+dist/
+.adk/
 
-- \`step.waitForWorkflow()\` - Wait for another workflow to complete
-- \`step.executeWorkflow()\` - Start and wait in one call
+# Environment files
+.env
+.env.local
+.env.production
 
-\`\`\`typescript
-const result = await step.executeWorkflow('run-child', ChildWorkflow, { input })
-\`\`\`
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
 
-**Timing Control:**
+# OS files
+.DS_Store
+Thumbs.db
 
-- \`step.sleep()\` - Pause execution (< 10s in-memory, >= 10s uses listening mode)
-- \`step.sleepUntil()\` - Sleep until specific time
-- \`step.listen()\` - Pause and wait for external event
+# Logs
+*.log
+logs/
 
-\`\`\`typescript
-await step.sleep('wait-5s', 5000)
-await step.sleepUntil('wait-until-noon', new Date('2025-01-15T12:00:00Z'))
-\`\`\`
+# Runtime files
+*.pid
+*.seed
+*.pid.lock
+`;
+    this.writeFile(".gitignore", gitIgnore);
+  }
+  async createReadme() {
+    const installCommand = this.packageManager === "npm" ? "npm install" : this.packageManager === "yarn" ? "yarn install" : `${this.packageManager} install`;
+    const readme = `# ${this.projectName}
 
-**Request Data from Conversation:**
+A Botpress Agent built with the ADK.
 
-\`\`\`typescript
-// In workflow
-const { topic } = await step.request('topic', 'What topic should I research?')
+## Getting Started
 
-// In conversation
-if (isWorkflowDataRequest(event)) {
-  await workflow.provide(event, { topic: userInput })
-}
-\`\`\`
+1. Install dependencies:
+   \`\`\`bash
+   ${installCommand}
+   \`\`\`
 
-**Execution Control:**
+2. Start development server:
+   \`\`\`bash
+   adk dev
+   \`\`\`
 
-- \`step.fail()\` - Mark workflow as failed
-- \`step.abort()\` - Abort without failing
-- \`step.progress()\` - Record progress checkpoint
+3. Deploy your agent:
+   \`\`\`bash
+   adk deploy
+   \`\`\`
 
-### 4. Tools (\`src/tools/\`)
+## Project Structure
 
-**AI-callable functions** that enable agents to perform actions:
+- \`src/actions/\` - Define callable functions
+- \`src/workflows/\` - Define long-running processes
+- \`src/conversations/\` - Define conversation handlers
+- \`src/tables/\` - Define data storage schemas
+- \`src/triggers/\` - Define event subscriptions
+- \`src/knowledge/\` - Add knowledge base files
 
-- Must have clear name and description
-- Use Zod schemas for input/output
-- Can be passed to \`execute()\`
-
-\`\`\`typescript
-export default new Autonomous.Tool({
-  name: "searchDatabase",
-  description: "Search the database",
-  input: z.object({ query: z.string() }),
-  output: z.object({ results: z.array(z.any()) }),
-  handler: async ({ query }) => {
-    // Tool logic
-    return { results: [] };
-  },
-});
-\`\`\`
-
-### 5. Knowledge Bases (\`src/knowledge/\`)
-
-**RAG (Retrieval-Augmented Generation)** for providing context:
-
-- Website scraping
-- Document ingestion
-- Can be passed to \`execute()\` via \`knowledge\` parameter
-
-### 6. Actions (\`src/actions/\`)
-
-**Reusable business logic** that can:
-
-- Be called from anywhere (import \`actions\` from \`@botpress/runtime\`)
-- Be converted to tools with \`.asTool()\`
-- Encapsulate logic not tied to conversational flow
-
-### 7. Zai Library
-
-**Zai** is an LLM utility library that provides a clean, type-safe API for common AI operations. It's designed to work seamlessly with the ADK and SDK to process LLM inputs and outputs programmatically.
-
-#### Importing Zai in ADK
-
-In the ADK, Zai is available from \`@botpress/runtime\`:
-
-\`\`\`typescript
-import { adk } from '@botpress/runtime'
-// then adk.zai.<method_name>
-\`\`\`
-
-The default model for Zai operations is configured in \`agent.config.ts\`:
-
-\`\`\`typescript
-export default defineConfig({
-  defaultModels: {
-    autonomous: "cerebras:gpt-oss-120b",
-    zai: "cerebras:gpt-oss-120b", // Model used for Zai operations
-  },
-})
-\`\`\`
-
-#### When to Use Zai
-
-Use Zai when you need to:
-- Extract structured data from unstructured text
-- Answer questions from documents with source citations
-- Verify Boolean conditions in content
-- Summarize long text into concise summaries
-- Generate text programmatically based on prompts
-
-**Use Zai instead of \`execute()\` when**: You need deterministic, structured outputs for specific AI tasks (extraction, validation, summarization) rather than conversational interactions.
-
-#### Zai Methods
-
-**1. \`answer()\` - Answer Questions with Citations**
-
-Answers questions from documents with intelligent source citations.
-
-\`\`\`typescript
-const documents = [
-  'Botpress was founded in 2016.',
-  'The company is based in Quebec, Canada.',
-]
-
-const result = await zai.answer(documents, 'When was Botpress founded?')
-
-if (result.type === 'answer') {
-  console.log(result.answer) // "Botpress was founded in 2016."
-  console.log(result.citations) // Array of citations with source references
-}
-\`\`\`
-
-**When to use**: When you need to answer questions from a set of documents with traceable sources (e.g., custom RAG implementations, document Q&A).
-
-**2. \`extract()\` - Extract Structured Data**
-
-Extracts structured data from unstructured input using Zod schemas.
-
-\`\`\`typescript
-import { z, adk } from '@botpress/runtime'
-
-const userSchema = z.object({
-  name: z.string(),
-  email: z.string().email(),
-  age: z.number()
-})
-
-const input = "My name is John Doe, I'm 30 years old and my email is john@example.com"
-// zai.extract returns the extracted data DIRECTLY (not wrapped in { output: ... })
-const result = await adk.zai.extract(input, userSchema)
-
-console.log(result)
-// { name: "John Doe", email: "john@example.com", age: 30 }
-\`\`\`
-
-**When to use**: When you need to parse unstructured user input into structured data (e.g., form extraction from natural language, parsing contact information).
-
-**3. \`check()\` - Verify Boolean Conditions**
-
-Verifies a condition against some input and returns a boolean with explanation.
-
-\`\`\`typescript
-const email = "Get rich quick! Click here now!!!"
-const { output } = await zai.check(email, 'is spam').result()
-
-console.log(output.value) // true
-console.log(output.explanation) // "This email contains typical spam indicators..."
-\`\`\`
-
-**When to use**: When you need to validate content or make binary decisions (e.g., content moderation, intent verification, condition checking).
-
-**4. \`summarize()\` - Summarize Text**
-
-Creates concise summaries of lengthy text to a desired length.
-
-\`\`\`typescript
-const longArticle = "..." // Long article content
-
-const summary = await zai.summarize(longArticle, {
-  length: 100, // tokens
-  prompt: 'key findings and main conclusions'
-})
-\`\`\`
-
-**When to use**: When you need to condense long content (e.g., article summaries, transcript summaries, document overviews).
-
-**5. \`text()\` - Generate Text**
-
-Generates text of the desired length according to a prompt.
-
-\`\`\`typescript
-const generated = await zai.text('Write a welcome message for new users', {
-  length: 50 // tokens
-})
-\`\`\`
-
-**When to use**: When you need to generate specific text content programmatically (e.g., dynamic content generation, templated responses).
-
-#### Response Methods
-
-All Zai operations return a Response object with promise-like behavior and additional functionality:
-
-\`\`\`typescript
-// Await the result directly
-const result = await zai.extract(input, schema)
-
-// Or use .result() for explicit promise handling
-const { output } = await zai.check(content, 'is valid').result()
-\`\`\`
-
-## Project Structure
-
-\`\`\`
-agent.config.ts          # Main configuration
-src/
-  conversations/         # Message handlers (primary user interaction)
-  workflows/            # Long-running processes
-  tools/                # AI-callable functions
-  actions/              # Reusable business logic
-  knowledge/            # Knowledge bases for RAG
-  triggers/             # Event-based triggers
-  tables/               # Database tables
-.botpress/              # Auto-generated types (DO NOT EDIT)
-\`\`\`
-
-## Development Workflow
-
-1. **Start dev server**: \`adk dev\` (http://localhost:3001 for console)
-2. **Add integrations**: \`adk add webchat@latest\`
-3. **Build**: \`adk build\`
-4. **Deploy**: \`adk deploy\`
-5. **Chat in CLI**: \`adk chat\`
-
-## Examples
-
-Official examples: https://github.com/botpress/adk/tree/main/examples
-
-### subagents
-
-**What you'll learn:** How to build a multi-agent system where an orchestrator delegates to specialists.
-
-Shows the \`SubAgent\` pattern where each specialist (HR, IT, Sales, etc.) runs in its own context with \`mode: "worker"\`, returns structured results via custom exits, and reports progress through \`onTrace\` hooks.
-
-### webchat-rag
-
-**What you'll learn:** How to build a RAG assistant with scheduled indexing, guardrails, and admin features.
-
-Shows \`Autonomous.Object\` for dynamic tool grouping, \`onBeforeTool\` hooks to enforce knowledge search before answering, scheduled workflows for KB refresh, and \`ThinkSignal\` for interrupting execution.
-
-### deep-research
-
-**What you'll learn:** How to build complex, long-running workflows with progress tracking.
-
-Shows \`step()\` and \`step.map()\` for workflow phases, \`Reference.Workflow\` for conversation-workflow linking, Tables for activity tracking, and extensive Zai usage (\`extract\`, \`answer\`, \`filter\`, \`text\`).
-
-## Best Practices
-
-1. **Search Botpress docs first** - Use the MCP tool before implementing
-2. **Keep tools focused** - Single responsibility per tool
-3. **Use Zod schemas** with \`.describe()\` for clarity
-4. **State management** - Minimize large variables in main workflow
-5. **Type safety** - Run \`adk dev\` or \`adk build\` to regenerate types after config changes
-6. **Conversations vs Workflows**:
-   - Conversations: User interactions, real-time responses
-   - Workflows: Background tasks, scheduled jobs, long-running processes
-
-## Common APIs
-
-### Conversation Handler
-
-\`\`\`typescript
-handler: async ({
-  execute, // Run autonomous AI loop
-  conversation, // Send messages, manage conversation
-  state, // Conversation state (persisted)
-  message, // Incoming message
-  client, // Botpress API client
-}) => {};
-\`\`\`
-
-### Execute Function
-
-\`\`\`typescript
-await execute({
-  instructions: "String or function returning instructions",
-  tools: [tool1, tool2], // Optional tools
-  knowledge: [kb1, kb2], // Optional knowledge bases
-  exits: [customExit], // Optional custom exits
-  hooks: { onTrace, onBeforeTool }, // Optional hooks
-  mode: "worker", // Optional: autonomous until exit
-  iterations: 10, // Max loops (default 10)
-});
-\`\`\`
-
-## Advanced Autonomous Execution
-
-### Autonomous Namespace
-
-The \`Autonomous\` namespace provides powerful primitives for controlling LLM behavior:
-
-#### Autonomous.Exit - Custom Exit Conditions
-
-Define custom exits for autonomous execution loops:
-
-\`\`\`typescript
-import { Autonomous, z } from '@botpress/runtime'
-
-const AnswerExit = new Autonomous.Exit({
-  name: 'answer',
-  description: 'Return when you have the final answer',
-  schema: z.object({
-    answer: z.string(),
-    confidence: z.number()
-  })
-})
-
-const NoAnswerExit = new Autonomous.Exit({
-  name: 'no_answer',
-  description: 'No answer could be found'
-})
-
-const result = await execute({
-  instructions: 'Research and answer the question',
-  exits: [AnswerExit, NoAnswerExit],
-  mode: 'worker' // Run until exit triggered
-})
-
-// ✅ CORRECT - Use result.is() and result.output
-if (result.is(AnswerExit)) {
-  console.log(result.output.answer)      // Type-safe access
-  console.log(result.output.confidence)
-} else if (result.is(NoAnswerExit)) {
-  console.log('No answer found')
-}
-
-// ❌ WRONG - Don't use result.exit.name or result.exit.value
-// if (result.exit?.name === 'answer') { ... }
-\`\`\`
-
-#### Autonomous.ThinkSignal - Inject Context
-
-Provide context to the LLM without continuing execution:
-
-\`\`\`typescript
-const results = await fetchData()
-
-if (!results.length) {
-  throw new ThinkSignal('error', 'No results found')
-}
-
-// Inject formatted results into LLM context
-throw new ThinkSignal('results ready', formatResults(results))
-\`\`\`
-
-#### Autonomous.Object - Dynamic Tool Grouping
-
-Group tools dynamically based on state:
-
-\`\`\`typescript
-const adminTools = new Autonomous.Object({
-  name: 'admin',
-  description: user.isAdmin ? 'Admin tools available' : 'Login required',
-  tools: user.isAdmin ? [refreshKB, manageBots] : [generateLoginCode]
-})
-
-await execute({
-  objects: [adminTools]
-})
-\`\`\`
-
-### Execution Hooks
-
-Full control over the autonomous execution loop:
-
-\`\`\`typescript
-await execute({
-  instructions: '...',
-  hooks: {
-    // Before tool execution - can modify input
-    onBeforeTool: async ({ iteration, tool, input, controller }) => {
-      console.log(\`About to call \${tool.name}\`)
-      return { input: modifiedInput } // Optional: transform input
-    },
-
-    // After tool execution - can modify output
-    onAfterTool: async ({ iteration, tool, input, output, controller }) => {
-      console.log(\`\${tool.name} returned:\`, output)
-      return { output: modifiedOutput } // Optional: transform output
-    },
-
-    // Before code execution in iteration
-    onBeforeExecution: async (iteration, controller) => {
-      return { code: modifiedCode } // Optional: transform generated code
-    },
-
-    // When exit is triggered
-    onExit: async (result) => {
-      console.log('Exited with:', result)
-    },
-
-    // After each iteration completes
-    onIterationEnd: async (iteration, controller) => {
-      if (iteration > 5) {
-        controller.abort() // Stop execution
-      }
-    },
-
-    // On trace events (synchronous, non-blocking)
-    onTrace: ({ trace, iteration }) => {
-      if (trace.type === 'comment') {
-        console.log('LLM thinking:', trace.comment)
-      }
-      if (trace.type === 'tool_call') {
-        console.log('Calling:', trace.tool_name)
-      }
-    }
-  }
-})
-\`\`\`
-
-**Hook use cases:**
-- Logging and debugging
-- Input/output validation and transformation
-- Rate limiting tool calls
-- Custom abort conditions
-- Injecting dynamic context
-
-## State and Metadata Management
-
-### Tags - Key-Value Metadata
-
-Track metadata for any entity (bot, user, conversation, workflow):
-
-\`\`\`typescript
-import { TrackedTags } from '@botpress/runtime'
-
-// Create tags instance
-const tags = TrackedTags.create({
-  type: 'bot', // or 'user' | 'conversation' | 'workflow'
-  id: entityId,
-  client: botClient,
-  initialTags: { status: 'active' }
-})
-
-// Load from server
-await tags.load()
-
-// Modify tags
-tags.tags = {
-  ...tags.tags,
-  lastSync: new Date().toISOString()
-}
-
-// Check if modified
-if (tags.isDirty()) {
-  await tags.save()
-}
-
-// Batch operations
-await TrackedTags.saveAllDirty()
-await TrackedTags.loadAll()
-\`\`\`
-
-**Access via workflow instance:**
-
-\`\`\`typescript
-workflow.tags = { status: 'processing' }
-await workflow.save()
-\`\`\`
-
-### Reference.Workflow - Typed Workflow References
-
-Serialize workflow references in state that auto-hydrate on access:
-
-\`\`\`typescript
-import { Reference, z } from '@botpress/runtime'
-
-// In conversation state schema
-state: z.object({
-  research: Reference.Workflow('deep_research').optional()
-  // or untyped: Reference.Workflow().optional()
-})
-
-// In handler - always a WorkflowInstance
-handler: async ({ state }) => {
-  if (state.research) {
-    // state.research is typed WorkflowInstance
-    console.log(state.research.status) // 'running' | 'completed' | etc
-    console.log(state.research.output) // Typed output
-
-    if (state.research.status === 'completed') {
-      // Access completed workflow data
-    }
-  }
-}
-\`\`\`
-
-### Context Object - Runtime Access
-
-Global context for accessing runtime information:
-
-\`\`\`typescript
-import { context } from '@botpress/runtime'
-
-// Get specific context
-const client = context.get('client')
-const citations = context.get('citations')
-const logger = context.get('logger')
-
-// Get all context
-const { client, cognitive, logger, operation } = context.getAll()
-\`\`\`
-
-**Available context properties:**
-- \`client\` - Botpress API client
-- \`cognitive\` - LLM access
-- \`logger\` - Logging
-- \`operation\` - Current operation info
-- \`citations\` - Citation tracking
-- \`chat\` - Chat interface
-- \`bot\` - Bot tags and metadata
-- \`user\` - User information
-- \`conversation\` - Current conversation
-- \`message\` - Incoming message
-- \`event\` - Current event
-- \`workflow\` - Current workflow
-- \`workflowControlContext\` - Workflow control (abort, fail, restart)
-
-### State Management
-
-Access and modify tracked state:
-
-\`\`\`typescript
-import { bot, user } from '@botpress/runtime'
-
-// Bot state
-bot.state.lastIndexed = new Date().toISOString()
-bot.state.config = { theme: 'dark' }
-
-// User state
-user.state.preferences = { notifications: true }
-user.state.lastActive = Date.now()
-\`\`\`
-
-State persists automatically across executions.
-
-## Advanced Table Operations
-
-### Table Naming Rules
-
-**IMPORTANT**: Tables have strict naming requirements:
-
-\`\`\`typescript
-// ✅ CORRECT - Name must end with "Table"
-export const MyDataTable = new Table({
-  name: "mydataTable",  // Must end with "Table"
-  columns: { ... }
-});
-
-// ❌ WRONG - Missing "Table" suffix
-name: "mydata"
-name: "my_data"
-\`\`\`
-
-**Reserved column names** - Cannot use these as column names:
-- \`id\` (auto-generated)
-- \`createdAt\` (auto-generated)
-- \`updatedAt\` (auto-generated)
-- \`computed\`
-- \`stale\`
-
-\`\`\`typescript
-// ❌ WRONG - Using reserved column name
-columns: {
-  createdAt: z.string()  // Reserved!
-}
-
-// ✅ CORRECT - Use alternative name
-columns: {
-  savedAt: z.string()
-}
-\`\`\`
-
-### Auto-Registration
-
-Files in \`src/tables/\` are **auto-registered** by the ADK. Do NOT re-export from index.ts:
-
-\`\`\`typescript
-// src/tables/index.ts
-// ❌ WRONG - Causes duplicate registration errors
-export { MyTable } from "./myTable";
-
-// ✅ CORRECT - Leave empty or add comment
-// Tables are auto-registered from src/tables/*.ts files
-\`\`\`
-
-Same applies to \`src/conversations/\`, \`src/workflows/\`, \`src/triggers/\`, etc.
-
-Beyond basic CRUD, Tables support powerful query and manipulation features:
-
-### Complex Filtering
-
-Use logical operators and conditions:
-
-\`\`\`typescript
-await MyTable.findRows({
-  filter: {
-    $and: [
-      { status: 'open' },
-      { priority: { $in: ['high', 'urgent'] } }
-    ],
-    $or: [
-      { assignee: userId },
-      { reporter: userId }
-    ],
-    title: { $regex: 'bug|error', $options: 'i' }
-  }
-})
-\`\`\`
-
-**Filter operators:**
-- \`$eq\`, \`$ne\` - Equal, not equal
-- \`$gt\`, \`$gte\`, \`$lt\`, \`$lte\` - Comparisons
-- \`$in\`, \`$nin\` - In array, not in array
-- \`$exists\` - Field exists
-- \`$regex\` - Regular expression match
-- \`$options\` - Regex options (e.g., 'i' for case-insensitive)
-- \`$and\`, \`$or\` - Logical operators
-
-### Full-Text Search
-
-Search across searchable columns:
-
-\`\`\`typescript
-await MyTable.findRows({
-  search: 'query string',
-  filter: { status: 'active' }
-})
-\`\`\`
-
-Mark columns as searchable in schema:
-
-\`\`\`typescript
-columns: {
-  title: z.string().searchable(),
-  description: z.string().searchable()
-}
-\`\`\`
-
-### Aggregation and Grouping
-
-Group and aggregate data:
-
-\`\`\`typescript
-await MyTable.findRows({
-  group: {
-    status: 'count',
-    priority: ['sum', 'avg'],
-    complexity: ['max', 'min']
-  }
-})
-\`\`\`
-
-**Aggregation operations:** \`key\`, \`count\`, \`sum\`, \`avg\`, \`max\`, \`min\`, \`unique\`
-
-### Computed Columns
-
-Columns with values computed from row data:
-
-\`\`\`typescript
-columns: {
-  fullName: {
-    computed: true,
-    schema: z.string(),
-    dependencies: ['firstName', 'lastName'],
-    value: async (row) => \`\${row.firstName} \${row.lastName}\`
-  },
-  age: {
-    computed: true,
-    schema: z.number(),
-    dependencies: ['birthDate'],
-    value: async (row) => {
-      const today = new Date()
-      const birth = new Date(row.birthDate)
-      return today.getFullYear() - birth.getFullYear()
-    }
-  }
-}
-\`\`\`
-
-### Upsert Operations
-
-Insert or update based on key column:
-
-\`\`\`typescript
-await MyTable.upsertRows({
-  rows: [
-    { externalId: '123', name: 'Item 1' },
-    { externalId: '456', name: 'Item 2' }
-  ],
-  keyColumn: 'externalId', // Update if exists, insert if not
-  waitComputed: true // Wait for computed columns to update
-})
-\`\`\`
-
-### Bulk Operations
-
-Efficient batch operations:
-
-\`\`\`typescript
-// Delete by filter
-await MyTable.deleteRows({
-  filter: { status: 'archived', createdAt: { $lt: '2024-01-01' } }
-})
-
-// Delete by IDs
-await MyTable.deleteRowIds([1, 2, 3])
-
-// Delete all
-await MyTable.deleteAllRows()
-
-// Update multiple
-await MyTable.updateRows({
-  rows: [
-    { id: 1, status: 'active' },
-    { id: 2, status: 'inactive' }
-  ],
-  waitComputed: true
-})
-\`\`\`
-
-### Error Handling
-
-Collect errors and warnings from bulk operations:
-
-\`\`\`typescript
-const { errors, warnings } = await MyTable.createRows({
-  rows: data,
-  waitComputed: true
-})
-
-if (errors?.length) {
-  console.error('Failed rows:', errors)
-}
-if (warnings?.length) {
-  console.warn('Warnings:', warnings)
-}
-\`\`\`
-
-## Knowledge Base Operations
-
-### Data Sources
-
-Multiple source types for knowledge bases:
-
-#### Directory Source
-
-\`\`\`typescript
-import { DataSource } from '@botpress/runtime'
-
-const docs = DataSource.Directory.fromPath('src/knowledge', {
-  id: 'docs',
-  filter: (path) => path.endsWith('.md') || path.endsWith('.txt')
-})
-\`\`\`
-
-#### Website Source
-
-\`\`\`typescript
-const siteDocs = DataSource.Website.fromSitemap('https://example.com/sitemap.xml', {
-  id: 'website',
-  maxPages: 500,
-  fetch: 'node:fetch' // or custom fetch implementation
-})
-\`\`\`
-
-### Knowledge Base Definition
-
-\`\`\`typescript
-import { Knowledge } from '@botpress/runtime'
-
-export default new Knowledge({
-  name: 'docs',
-  description: 'Product documentation',
-  sources: [docsDirectory, websiteSource]
-})
-\`\`\`
-
-### Refresh Operations
-
-Manually refresh knowledge base content:
-
-\`\`\`typescript
-// Refresh entire knowledge base
-await DocsKB.refresh({ force: true })
-
-// Refresh specific source
-await DocsKB.refreshSource('website', { force: true })
-\`\`\`
-
-**Options:**
-- \`force: true\` - Force refresh even if recently updated
-- Automatic refresh via scheduled workflows recommended
-
-### Using Knowledge in Execute
-
-\`\`\`typescript
-await execute({
-  instructions: 'Answer using the documentation',
-  knowledge: [DocsKB, APIKB],
-  tools: [searchTool]
-})
-\`\`\`
-
-Knowledge bases are automatically searchable via the \`search_knowledge\` tool.
-
-## Advanced Conversation Patterns
-
-### Multiple Channel Support
-
-Handle messages from multiple channels in one handler:
-
-\`\`\`typescript
-export default new Conversation({
-  channel: ['chat.channel', 'webchat.channel', 'slack.dm'],
-  handler: async ({ channel, execute }) => {
-    console.log(\`Message from: \${channel}\`)
-    await execute({ instructions: '...' })
-  }
-})
-\`\`\`
-
-### Event Handling
-
-Subscribe to integration events:
-
-\`\`\`typescript
-export default new Conversation({
-  channel: 'webchat.channel',
-  events: ['webchat:conversationStarted', 'webchat:conversationEnded'],
-  handler: async ({ type, event, message }) => {
-    if (type === 'event' && event.type === 'webchat:conversationStarted') {
-      // Send welcome message
-      await conversation.send({
-        type: 'text',
-        payload: { text: 'Welcome!' }
-      })
-    }
-
-    if (type === 'message' && message?.type === 'text') {
-      // Handle regular messages
-      await execute({ instructions: '...' })
-    }
-  }
-})
-\`\`\`
-
-### Workflow Request Handling
-
-Handle data requests from workflows:
-
-\`\`\`typescript
-import { isWorkflowDataRequest } from '@botpress/runtime'
-
-handler: async ({ type, event, execute }) => {
-  // Check if this is a workflow requesting data
-  if (type === 'workflow_request' && isWorkflowDataRequest(event)) {
-    const userInput = await promptUser(event.payload.message)
-
-    // Provide data back to workflow
-    await workflow.provide(event, { topic: userInput })
-    return
-  }
-
-  // Regular message handling
-  await execute({ instructions: '...' })
-}
-\`\`\`
-
-### Typed Workflow Interactions
-
-Work with typed workflow instances:
-
-\`\`\`typescript
-import { isWorkflow, ResearchWorkflow } from '@botpress/runtime'
-
-handler: async ({ state }) => {
-  if (state.research && isWorkflow(state.research, 'research')) {
-    // state.research is now typed as ResearchWorkflow
-    console.log(state.research.status)
-    console.log(state.research.output) // Typed output
-
-    if (state.research.status === 'completed') {
-      await conversation.send({
-        type: 'text',
-        payload: { text: state.research.output.result }
-      })
-    }
-  }
-}
-\`\`\`
-
-### Dynamic Tools Based on State
-
-Provide different tools based on conversation state:
-
-\`\`\`typescript
-handler: async ({ state, execute }) => {
-  const tools = () => {
-    if (state.workflowRunning) {
-      return [cancelWorkflowTool, checkStatusTool]
-    } else {
-      return [startWorkflowTool, browseTool, searchTool]
-    }
-  }
-
-  await execute({
-    instructions: '...',
-    tools: tools()
-  })
-}
-\`\`\`
-
-### Message Sending
-
-Send different message types:
-
-\`\`\`typescript
-// Text message
-await conversation.send({
-  type: 'text',
-  payload: { text: 'Hello!' }
-})
-
-// Custom message type (integration-specific)
-await conversation.send({
-  type: 'custom:messageType',
-  payload: { data: 'custom payload' }
-})
-\`\`\`
-
-## Citations System
-
-Track and manage source citations for LLM responses:
-
-### CitationsManager
-
-Access via context:
-
-\`\`\`typescript
-import { context } from '@botpress/runtime'
-
-const citations = context.get('citations')
-\`\`\`
-
-### Registering Sources
-
-Register sources that can be cited:
-
-\`\`\`typescript
-// Register with URL
-const { tag } = citations.registerSource({
-  url: 'https://example.com/doc',
-  title: 'Documentation Page'
-})
-
-// Register with file reference
-const { tag } = citations.registerSource({
-  file: fileKey,
-  title: 'Internal Document'
-})
-\`\`\`
-
-### Using Citation Tags
-
-Inject citation tags into LLM content:
-
-\`\`\`typescript
-const results = await searchKnowledgeBase(query)
-
-for (const result of results) {
-  const { tag } = citations.registerSource({
-    file: result.file.key,
-    title: result.file.name
-  })
-
-  content += \`\${result.content} \${tag}\\n\`
-}
-
-// Return cited content
-throw new ThinkSignal('results', content)
-\`\`\`
-
-### Citation Format
-
-Citations are automatically formatted with tags like \`[1]\`, \`[2]\`, etc., and tracked by the system for reference.
-
-### Example: Tool with Citations
-
-\`\`\`typescript
-export default new Autonomous.Tool({
-  name: 'search_docs',
-  description: 'Search documentation',
-  handler: async ({ query }) => {
-    const citations = context.get('citations')
-    const results = await searchDocs(query)
-
-    let response = ''
-    for (const doc of results) {
-      const { tag } = citations.registerSource({
-        url: doc.url,
-        title: doc.title
-      })
-      response += \`\${doc.content} \${tag}\\n\\n\`
-    }
-
-    return response
-  }
-})
-\`\`\`
-
-## Common Mistakes to Avoid
-
-### 1. Wrong Zai Import
-\`\`\`typescript
-// ❌ WRONG
-import { zai } from '@botpress/runtime'
-const result = await zai.extract(...)
-
-// ✅ CORRECT
-import { adk } from '@botpress/runtime'
-const result = await adk.zai.extract(...)
-\`\`\`
-
-### 2. Expecting \`.output\` from zai.extract
-\`\`\`typescript
-// ❌ WRONG - zai.extract returns data directly
-const result = await adk.zai.extract(input, schema)
-console.log(result.output)  // undefined!
-
-// ✅ CORRECT
-const result = await adk.zai.extract(input, schema)
-console.log(result)  // { name: "John", age: 30 }
-\`\`\`
-
-### 3. Wrong Exit Result Handling
-\`\`\`typescript
-// ❌ WRONG
-if (result.exit?.name === 'my_exit') {
-  const data = result.exit.value
-}
-
-// ✅ CORRECT
-if (result.is(MyExit)) {
-  const data = result.output  // Type-safe!
-}
-\`\`\`
-
-### 4. Reserved Table Column Names
-\`\`\`typescript
-// ❌ WRONG - These are reserved
-columns: {
-  id: z.string(),
-  createdAt: z.string(),
-  updatedAt: z.string()
-}
-
-// ✅ CORRECT - Use alternatives
-columns: {
-  visibleId: z.string(),
-  savedAt: z.string(),
-  modifiedAt: z.string()
-}
-\`\`\`
-
-### 5. Re-exporting Auto-Registered Files
-\`\`\`typescript
-// ❌ WRONG - src/tables/index.ts
-export { MyTable } from "./myTable"  // Causes duplicates!
-
-// ✅ CORRECT - Leave index.ts empty
-// Files in src/tables/, src/conversations/, etc. are auto-registered
-\`\`\`
-
-### 6. Table Name Missing "Table" Suffix
-\`\`\`typescript
-// ❌ WRONG
-name: "users"
-name: "user_data"
-
-// ✅ CORRECT
-name: "usersTable"
-name: "userdataTable"
-\`\`\`
-
-## When Making Changes
-
-1. **Always search Botpress docs** using \`mcp__botpress-docs__SearchBotpress\`
-2. **Check examples** for patterns
-3. **Regenerate types** after changing \`agent.config.ts\` (run \`adk dev\`)
-4. **Test in dev mode** with hot reloading (\`adk dev\`)
-5. **Follow TypeScript types** - They're auto-generated from integrations
-
-## Running Tests
-
-The ADK provides \`setupTestRuntime()\` to initialize the full ADK runtime within your test process. This sets up all environment variables, generates types, and imports the runtime so your tests can use actions, tools, workflows, etc.
-
-### Bun Test
-
-\`\`\`toml
-# bunfig.toml
-[test]
-preload = ["./test-setup.ts"]
-\`\`\`
-
-\`\`\`typescript
-// test-setup.ts
-import { beforeAll } from "bun:test";
-import { setupTestRuntime } from "@botpress/adk";
-
-beforeAll(async () => {
-  const runtime = await setupTestRuntime();
-  await runtime.initialize();
-});
-\`\`\`
-
-### Vitest
-
-\`\`\`typescript
-// vitest.setup.ts
-import { beforeAll } from "vitest";
-import { setupTestRuntime } from "@botpress/adk";
-
-beforeAll(async () => {
-  const runtime = await setupTestRuntime();
-  await runtime.initialize();
-});
-\`\`\`
-
-\`\`\`typescript
-// vitest.config.ts
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    setupFiles: ["./vitest.setup.ts"],
-  },
-});
-\`\`\`
-
-### Options
-
-\`setupTestRuntime()\` auto-detects project path and credentials, but you can override:
-
-\`\`\`typescript
-const runtime = await setupTestRuntime({
-  projectPath: "/path/to/agent", // defaults to auto-detect from CWD
-  credentials: { token: "...", apiUrl: "..." }, // defaults to ~/.adk/credentials
-  prod: true, // use production bot instead of dev bot
-  forceRegenerate: true, // force regenerate bot project
-  env: { CUSTOM_VAR: "value" }, // additional env vars
-});
-\`\`\`
-
-### Prerequisites
-
-- Must have \`@botpress/adk\` installed as a dev dependency (\`bun add -d @botpress/adk\`)
-- Must have run \`adk dev\` at least once (to create the dev bot)
-- Must be logged in (\`adk login\`) or provide credentials explicitly
-
-## Resources
-
-- [ADK Overview](https://botpress.com/docs/for-developers/adk/overview)
-- [ADK Getting Started](https://botpress.com/docs/for-developers/adk/getting-started)
-- [Project Structure](https://botpress.com/docs/for-developers/adk/project-structure)
-- [Conversations](https://botpress.com/docs/for-developers/adk/concepts/conversations)
-- [Workflows](https://botpress.com/docs/for-developers/adk/concepts/workflows)
-`;
-
-// src/agent-init/agent-project-generator.ts
-class AgentProjectGenerator {
-  projectPath;
-  projectName;
-  packageManager;
-  template;
-  constructor(projectPath, packageManager = "bun", template = "blank") {
-    this.projectPath = path15.resolve(projectPath);
-    this.projectName = path15.basename(this.projectPath);
-    this.packageManager = packageManager;
-    this.template = template;
-  }
-  async generate() {
-    this.ensureEmptyDirectory();
-    this.createPackageJson();
-    await this.createAgentConfig();
-    this.createTsConfig();
-    this.createAgentJson();
-    this.createGitIgnore();
-    await this.createReadme();
-    this.createClaudeMd();
-    await this.createSourceStructure();
-  }
-  ensureEmptyDirectory() {
-    if (!fs11.existsSync(this.projectPath)) {
-      fs11.mkdirSync(this.projectPath, { recursive: true });
-    }
-    const files = fs11.readdirSync(this.projectPath);
-    if (files.length > 0) {
-      throw new Error(`Directory ${this.projectPath} is not empty. Please use an empty directory.`);
-    }
-  }
-  createPackageJson() {
-    const packageJson = {
-      name: this.projectName,
-      version: "1.0.0",
-      description: `A Botpress Agent built with the ADK`,
-      type: "module",
-      packageManager: this.packageManager === "npm" ? undefined : `${this.packageManager}@latest`,
-      scripts: {
-        dev: "adk dev",
-        build: "adk build",
-        deploy: "adk deploy"
-      },
-      dependencies: {
-        "@botpress/runtime": `^${"1.15.4"}`
-      },
-      devDependencies: {
-        typescript: "^5.9.3"
-      }
-    };
-    if (packageJson.packageManager === undefined) {
-      delete packageJson.packageManager;
-    }
-    this.writeJsonFile("package.json", packageJson);
-  }
-  getDefaultDependencies() {
-    const dependencies = {
-      integrations: {}
-    };
-    if (this.template === "hello-world") {
-      dependencies.integrations = {
-        chat: {
-          version: "chat@latest",
-          enabled: true
-        },
-        webchat: {
-          version: "webchat@latest",
-          enabled: true
-        }
-      };
-    }
-    return dependencies;
-  }
-  async createAgentConfig() {
-    const dependencies = this.getDefaultDependencies();
-    const integrationsJson = JSON.stringify(dependencies.integrations, null, 4).replace(/\n/g, `
-    `);
-    const defaultModels = this.template === "hello-world" ? `
-  defaultModels: {
-    autonomous: "cerebras:gpt-oss-120b",
-    zai: "cerebras:gpt-oss-120b",
-  },
-` : "";
-    const agentConfig = `import { z, defineConfig } from '@botpress/runtime';
-
-export default defineConfig({
-  name: '${this.projectName}',
-  description: 'An AI agent built with Botpress ADK',
-${defaultModels}
-  bot: {
-    state: z.object({}),
-  },
-
-  user: {
-    state: z.object({}),
-  },
-
-  dependencies: {
-    integrations: ${integrationsJson},
-  },
-});
-`;
-    await this.writeFormattedFile("agent.config.ts", agentConfig);
-  }
-  createTsConfig() {
-    const tsConfig = {
-      compilerOptions: {
-        target: "ES2022",
-        module: "ES2022",
-        moduleResolution: "Bundler",
-        lib: ["ES2022"],
-        outDir: "./dist",
-        rootDir: ".",
-        strict: true,
-        esModuleInterop: true,
-        allowSyntheticDefaultImports: true,
-        skipLibCheck: true,
-        forceConsistentCasingInFileNames: true,
-        moduleDetection: "force",
-        resolveJsonModule: true,
-        paths: {
-          "@botpress/runtime/_types/*": ["./.adk/*-types"]
-        }
-      },
-      include: ["src/**/*", ".adk/**/*"],
-      exclude: ["node_modules", "dist"]
-    };
-    this.writeJsonFile("tsconfig.json", tsConfig);
-  }
-  createAgentJson() {
-    const agentJson = {};
-    this.writeJsonFile("agent.json", agentJson);
-  }
-  createGitIgnore() {
-    const gitIgnore = `# Dependencies
-node_modules/
-.pnpm-store/
-
-# Build outputs
-dist/
-.adk/
-
-# Environment files
-.env
-.env.local
-.env.production
-
-# IDE files
-.vscode/
-.idea/
-*.swp
-*.swo
-
-# OS files
-.DS_Store
-Thumbs.db
-
-# Logs
-*.log
-logs/
-
-# Runtime files
-*.pid
-*.seed
-*.pid.lock
-`;
-    this.writeFile(".gitignore", gitIgnore);
-  }
-  async createReadme() {
-    const installCommand = this.packageManager === "npm" ? "npm install" : this.packageManager === "yarn" ? "yarn install" : `${this.packageManager} install`;
-    const readme = `# ${this.projectName}
-
-A Botpress Agent built with the ADK.
-
-## Getting Started
-
-1. Install dependencies:
-   \`\`\`bash
-   ${installCommand}
-   \`\`\`
-
-2. Start development server:
-   \`\`\`bash
-   adk dev
-   \`\`\`
-
-3. Deploy your agent:
-   \`\`\`bash
-   adk deploy
-   \`\`\`
-
-## Project Structure
-
-- \`src/actions/\` - Define callable functions
-- \`src/workflows/\` - Define long-running processes
-- \`src/conversations/\` - Define conversation handlers
-- \`src/tables/\` - Define data storage schemas
-- \`src/triggers/\` - Define event subscriptions
-- \`src/knowledge/\` - Add knowledge base files
-
-## Learn More
+## Learn More
 
 - [ADK Documentation](https://botpress.com/docs/adk)
 - [Botpress Platform](https://botpress.com)
 `;
     await this.writeFormattedFile("README.md", readme);
   }
-  createClaudeMd() {
-    this.writeFile("CLAUDE.md", CLAUDE_template_default);
+  createAIAssistantInstructions() {
+    const content = ai_assistant_instructions_template_default;
+    this.writeFile("CLAUDE.md", content);
+    this.writeFile("AGENTS.md", content);
   }
   async createSourceStructure() {
     const srcPath = path15.join(this.projectPath, "src");
@@ -12443,158 +11315,1239 @@ class ScriptRunner {
     for (const [key, value] of Object.entries(envVars)) {
       process.env[key] = value;
     }
-    const runtimePath = path41.join(botPath, "src", "index.ts");
-    return {
-      botPath,
-      runtimePath,
-      botId,
-      workspaceId,
-      isProd: this.prod,
-      project,
-      initialize: async () => {
-        const botModule = await import(runtimePath);
-        const runtimeModule = await import("@botpress/runtime/runtime");
-        const { Autonomous } = await import("@botpress/runtime");
-        const { context, agentRegistry } = runtimeModule;
-        const { Client: Client18 } = await import("@botpress/client");
-        const { BotSpecificClient, BotLogger } = await import("@botpress/sdk");
-        const { Cognitive } = await import("@botpress/cognitive");
-        const vanillaClient = new Client18({
-          token: this.credentials.token,
-          apiUrl: this.credentials.apiUrl,
-          botId
-        });
-        const client = new BotSpecificClient(vanillaClient);
-        const cognitive = new Cognitive({
-          client,
-          __experimental_beta: true
-        });
-        const logger = new BotLogger({});
-        context.setDefaultContext({
-          executionId: "test-execution",
-          executionFinished: false,
-          botId,
-          client,
-          cognitive,
-          citations: new Autonomous.CitationsManager,
-          logger,
-          configuration: configuration ?? {},
-          integrations: agentRegistry.integrations,
-          interfaces: agentRegistry.interfaces,
-          states: [],
-          tags: [],
-          scheduledHeavyImports: new Set
-        });
-        return botModule.default;
+    const runtimePath = path41.join(botPath, "src", "index.ts");
+    return {
+      botPath,
+      runtimePath,
+      botId,
+      workspaceId,
+      isProd: this.prod,
+      project,
+      initialize: async () => {
+        const botModule = await import(runtimePath);
+        const runtimeModule = await import("@botpress/runtime/runtime");
+        const { Autonomous } = await import("@botpress/runtime");
+        const { context, agentRegistry } = runtimeModule;
+        const { Client: Client18 } = await import("@botpress/client");
+        const { BotSpecificClient, BotLogger } = await import("@botpress/sdk");
+        const { Cognitive } = await import("@botpress/cognitive");
+        const vanillaClient = new Client18({
+          token: this.credentials.token,
+          apiUrl: this.credentials.apiUrl,
+          botId
+        });
+        const client = new BotSpecificClient(vanillaClient);
+        const cognitive = new Cognitive({
+          client,
+          __experimental_beta: true
+        });
+        const logger = new BotLogger({});
+        context.setDefaultContext({
+          executionId: "test-execution",
+          executionFinished: false,
+          botId,
+          client,
+          cognitive,
+          citations: new Autonomous.CitationsManager,
+          logger,
+          configuration: configuration ?? {},
+          integrations: agentRegistry.integrations,
+          interfaces: agentRegistry.interfaces,
+          states: [],
+          tags: [],
+          scheduledHeavyImports: new Set
+        });
+        return botModule.default;
+      }
+    };
+  }
+  async run(scriptPath, options = {}) {
+    const { botPath, runnerPath, project } = await this.prepare();
+    const absoluteScriptPath = path41.isAbsolute(scriptPath) ? scriptPath : path41.resolve(this.projectPath, scriptPath);
+    if (!existsSync10(absoluteScriptPath)) {
+      throw new Error(`Script not found: ${absoluteScriptPath}`);
+    }
+    const botId = this.prod ? project.agentInfo?.botId : project.agentInfo?.devId || project.agentInfo?.botId;
+    const workspaceId = project.agentInfo?.workspaceId;
+    if (!botId) {
+      const idType = this.prod ? "botId" : "devId";
+      throw new Error(`No ${idType} found in agent.json. ` + (this.prod ? 'Please deploy your agent first with "adk deploy".' : 'Please run "adk dev" first to create a development bot, or use --prod to use the production bot.'));
+    }
+    const args = ["run", runnerPath, absoluteScriptPath, ...options.args || []];
+    let configuration;
+    try {
+      const manager3 = new ConfigManager(botId);
+      configuration = await manager3.getAll();
+    } catch {}
+    const env = {
+      ...process.env,
+      ADK_PROJECT_PATH: this.projectPath,
+      ADK_BOT_PATH: botPath,
+      ADK_BOT_ID: botId,
+      ADK_WORKSPACE_ID: workspaceId || "",
+      ADK_IS_PROD: this.prod ? "true" : "false",
+      BP_DISABLE_WORKER_MODE: "true",
+      ...options.env,
+      ADK_SCRIPT_MODE: "true",
+      ADK_SCRIPT_PATH: absoluteScriptPath,
+      ADK_TOKEN: this.credentials.token,
+      ADK_API_URL: this.credentials.apiUrl,
+      ...configuration && { ADK_CONFIGURATION: JSON.stringify(configuration) }
+    };
+    return new Promise((resolve3, reject) => {
+      const child = spawn("bun", args, {
+        cwd: botPath,
+        env,
+        stdio: options.inheritStdio !== false ? "inherit" : "pipe"
+      });
+      child.on("error", (error) => {
+        reject(error);
+      });
+      child.on("close", (code) => {
+        resolve3(code ?? 0);
+      });
+    });
+  }
+}
+async function runScript(options) {
+  const runner = new ScriptRunner({
+    projectPath: options.projectPath,
+    forceRegenerate: options.forceRegenerate,
+    prod: options.prod,
+    credentials: options.credentials
+  });
+  return runner.run(options.scriptPath, {
+    args: options.args,
+    env: options.env,
+    inheritStdio: options.inheritStdio
+  });
+}
+async function setupTestRuntime(options = {}) {
+  let projectPath = options.projectPath;
+  if (!projectPath) {
+    const detected = await findAgentRoot(process.cwd());
+    if (!detected) {
+      throw new Error(`Could not find ADK agent project. No agent.config.ts found in current directory or parents.
+Either run from within an agent project directory, or provide projectPath explicitly.`);
+    }
+    projectPath = detected;
+  }
+  let credentials = options.credentials;
+  if (!credentials) {
+    const credentialsManager = new CredentialsManager;
+    const loadedCredentials = await credentialsManager.getCredentials();
+    if (!loadedCredentials) {
+      throw new Error('No credentials found. Please run "adk login" first, or provide credentials explicitly.');
+    }
+    credentials = {
+      token: loadedCredentials.token,
+      apiUrl: loadedCredentials.apiUrl
+    };
+  }
+  const runner = new ScriptRunner({
+    projectPath,
+    forceRegenerate: options.forceRegenerate,
+    prod: options.prod,
+    credentials
+  });
+  return runner.setupTestRuntime({ env: options.env });
+}
+// src/eval/types.ts
+function defineEval(def) {
+  return def;
+}
+// src/eval/loader.ts
+import { readdirSync as readdirSync3, existsSync as existsSync11 } from "fs";
+import { resolve as resolve3 } from "path";
+async function loadEvalFile(filePath) {
+  const absPath = resolve3(filePath);
+  const mod = await import(absPath);
+  const def = mod.default;
+  if (!def || typeof def !== "object" || !def.name || !Array.isArray(def.conversation)) {
+    throw new Error(`Invalid eval file ${filePath}: must export default a defineEval({...}) object with name and conversation`);
+  }
+  return def;
+}
+async function loadEvalsFromDir(dirPath) {
+  const absDir = resolve3(dirPath);
+  if (!existsSync11(absDir)) {
+    return [];
+  }
+  const files = readdirSync3(absDir).filter((f) => f.endsWith(".eval.ts"));
+  const evals = [];
+  for (const f of files) {
+    evals.push(await loadEvalFile(`${absDir}/${f}`));
+  }
+  return evals;
+}
+async function loadEvalByName(dirPath, name) {
+  const absDir = resolve3(dirPath);
+  if (!existsSync11(absDir))
+    return null;
+  const files = readdirSync3(absDir).filter((f) => f.endsWith(".eval.ts"));
+  for (const f of files) {
+    const def = await loadEvalFile(`${absDir}/${f}`);
+    if (def.name === name)
+      return def;
+  }
+  return null;
+}
+function filterEvals(evals, filter) {
+  if (!filter)
+    return evals;
+  return evals.filter((e) => {
+    if (filter.names && filter.names.length > 0) {
+      if (!filter.names.includes(e.name))
+        return false;
+    }
+    if (filter.tags && filter.tags.length > 0) {
+      if (!e.tags || !filter.tags.some((t) => e.tags.includes(t)))
+        return false;
+    }
+    if (filter.type) {
+      if (e.type !== filter.type)
+        return false;
+    }
+    return true;
+  });
+}
+// src/eval/runner.ts
+import { Client as BpClient2 } from "@botpress/client";
+
+// src/eval/client.ts
+import { Client as BpClient } from "@botpress/client";
+import { Client as ChatClient } from "@botpress/chat";
+
+class ChatSession {
+  webhookId;
+  client = null;
+  conversationId = null;
+  constructor(webhookId) {
+    this.webhookId = webhookId;
+  }
+  async connect() {
+    this.client = await ChatClient.connect({ webhookId: this.webhookId });
+  }
+  get userId() {
+    if (!this.client) {
+      throw new Error("ChatSession not connected. Call connect() first.");
+    }
+    return this.client.user.id;
+  }
+  async sendMessage(message, options = {}) {
+    if (!this.client) {
+      throw new Error("ChatSession not connected. Call connect() first.");
+    }
+    const { timeout = 30000, idleTimeout = 3000 } = options;
+    if (!this.conversationId) {
+      const conv = await this.client.createConversation({});
+      this.conversationId = conv.conversation.id;
+    }
+    const conversationId = this.conversationId;
+    const responses = [];
+    const listener = await this.client.listenConversation({
+      id: conversationId
+    });
+    return new Promise((resolve4, reject) => {
+      let idleTimer = null;
+      let resolved = false;
+      const done = () => {
+        if (resolved)
+          return;
+        resolved = true;
+        if (idleTimer)
+          clearTimeout(idleTimer);
+        clearTimeout(overallTimer);
+        resolve4({ conversationId, responses });
+      };
+      const resetIdle = () => {
+        if (idleTimer)
+          clearTimeout(idleTimer);
+        idleTimer = setTimeout(done, idleTimeout);
+      };
+      const overallTimer = setTimeout(() => {
+        if (!resolved) {
+          if (responses.length > 0) {
+            done();
+          } else {
+            resolved = true;
+            reject(new Error(`Timed out after ${timeout}ms with no bot response.`));
+          }
+        }
+      }, timeout);
+      listener.on("message_created", (event) => {
+        if (resolved)
+          return;
+        if (event.isBot) {
+          const payload = event?.payload;
+          const text = typeof payload === "string" ? payload : payload?.text || JSON.stringify(payload);
+          responses.push({ text, raw: payload });
+          resetIdle();
+        }
+      });
+      listener.on("event_created", (event) => {
+        if (event?.payload?.done) {
+          done();
+        }
+      });
+      this.client.createMessage({
+        conversationId,
+        payload: { type: "text", text: message }
+      }).then(() => {
+        resetIdle();
+      }).catch((err) => {
+        clearTimeout(overallTimer);
+        if (!resolved) {
+          resolved = true;
+          reject(err);
+        }
+      });
+    });
+  }
+}
+async function discoverWebhookId(botId, token, apiUrl) {
+  const client = new BpClient({ token, botId, apiUrl });
+  const { bot } = await client.getBot({ id: botId });
+  const integrations = bot.integrations || {};
+  const chat = Object.values(integrations).find((int) => int.name === "chat");
+  const webhookId = chat?.webhookId;
+  if (!webhookId) {
+    throw new Error("No chat integration found on bot. Make sure the bot has the chat integration enabled.");
+  }
+  return webhookId;
+}
+
+// src/eval/traces.ts
+async function fetchTraceSpans(conversationId, devServerUrl) {
+  const url = `${devServerUrl}/api/traces/query?attributeName=conversationId&attributeValue=${encodeURIComponent(conversationId)}&count=1000`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch traces: ${res.status} ${res.statusText}`);
+  }
+  const data = await res.json();
+  return Array.isArray(data) ? data : data.spans || [];
+}
+function extractToolCalls(spans) {
+  const toolEndSpans = spans.filter((span) => span.name === "autonomous.tool" && span.t === "end" && span.attrs?.["autonomous.tool.name"]);
+  const seen = new Set;
+  const unique = toolEndSpans.filter((span) => {
+    if (seen.has(span.spanId))
+      return false;
+    seen.add(span.spanId);
+    return true;
+  });
+  return unique.sort((a, b) => (a.endNs ?? 0) - (b.endNs ?? 0)).map((span) => {
+    const attrs = span.attrs;
+    let input = {};
+    try {
+      input = JSON.parse(attrs["autonomous.tool.input"]);
+    } catch {}
+    return {
+      name: attrs["autonomous.tool.name"],
+      input,
+      output: attrs["autonomous.tool.output"] || "",
+      status: attrs["autonomous.tool.status"] || "unknown"
+    };
+  });
+}
+async function getTraceData(conversationId, devServerUrl, options = {}) {
+  const previousCount = options.previousToolCallCount || 0;
+  const expectNew = options.expectNewCalls ?? false;
+  const maxRetries = expectNew ? 5 : 0;
+  const retryDelay = 500;
+  let allToolCalls = [];
+  let spans = [];
+  for (let attempt = 0;attempt <= maxRetries; attempt++) {
+    if (attempt > 0) {
+      await new Promise((resolve4) => setTimeout(resolve4, retryDelay));
+    }
+    spans = await fetchTraceSpans(conversationId, devServerUrl);
+    allToolCalls = extractToolCalls(spans);
+    if (!expectNew || allToolCalls.length > previousCount) {
+      break;
+    }
+  }
+  const toolCalls = allToolCalls.slice(previousCount);
+  return { toolCalls, totalToolCallCount: allToolCalls.length, raw: spans };
+}
+
+// src/eval/graders/llm.ts
+import { Cognitive } from "@botpress/cognitive";
+import { Client as Client18 } from "@botpress/client";
+var JUDGE_SYSTEM_PROMPT = `You are an evaluation judge for a chatbot. You will be given:
+- The user's message
+- The bot's response
+- Grading criteria
+
+Your job is to determine if the bot's response meets the criteria.
+
+Respond with a JSON object:
+{
+  "pass": true/false,
+  "score": 1-5,
+  "reason": "brief explanation"
+}
+
+Scoring guide:
+- 5: Fully meets criteria, excellent response
+- 4: Mostly meets criteria, minor issues
+- 3: Partially meets criteria, notable gaps
+- 2: Barely meets criteria, significant issues
+- 1: Does not meet criteria
+
+A score of 3 or above is a pass.`;
+var _cognitive = null;
+function getCognitive() {
+  if (_cognitive)
+    return _cognitive;
+  const token = process.env.BP_TOKEN || process.env.ADK_TOKEN;
+  const botId = process.env.ADK_BOT_ID;
+  const apiUrl = process.env.ADK_API_URL || "https://api.botpress.cloud";
+  if (!token || !botId)
+    return null;
+  const client = new Client18({ token, apiUrl, botId });
+  _cognitive = new Cognitive({ client, __experimental_beta: true });
+  return _cognitive;
+}
+function initLLMJudge(credentials) {
+  const client = new Client18({
+    token: credentials.token,
+    apiUrl: credentials.apiUrl,
+    botId: credentials.botId
+  });
+  _cognitive = new Cognitive({ client, __experimental_beta: true });
+}
+async function gradeLLMJudge(botResponse, criteria, context) {
+  try {
+    const cognitive = getCognitive();
+    if (!cognitive) {
+      return {
+        assertion: `llm_judge: "${criteria}"`,
+        pass: true,
+        expected: criteria,
+        actual: "SKIPPED — LLM judge unavailable: no credentials configured"
+      };
+    }
+    const { output } = await cognitive.generateContent({
+      model: "fast",
+      temperature: 0,
+      responseFormat: "json_object",
+      systemPrompt: JUDGE_SYSTEM_PROMPT,
+      messages: [
+        {
+          role: "user",
+          content: `User message: ${context.userMessage}
+
+Bot response: ${botResponse}
+
+Criteria: ${criteria}`
+        }
+      ]
+    });
+    const rawContent = output?.choices?.[0]?.content;
+    const content = typeof rawContent === "string" ? rawContent : null;
+    if (!content) {
+      return {
+        assertion: `llm_judge: "${criteria}"`,
+        pass: true,
+        expected: criteria,
+        actual: "SKIPPED — LLM judge returned empty response"
+      };
+    }
+    const verdict = JSON.parse(content);
+    return {
+      assertion: `llm_judge: "${criteria}"`,
+      pass: verdict.score >= 3,
+      expected: criteria,
+      actual: `Score ${verdict.score}/5 — ${verdict.reason}`
+    };
+  } catch (err) {
+    return {
+      assertion: `llm_judge: "${criteria}"`,
+      pass: true,
+      expected: criteria,
+      actual: `SKIPPED — LLM judge unavailable: ${err.message}`
+    };
+  }
+}
+
+// src/eval/graders/response.ts
+async function gradeResponse(botResponse, assertions, context) {
+  const results = [];
+  for (const assertion of assertions) {
+    if ("contains" in assertion) {
+      const pass = botResponse.toLowerCase().includes(assertion.contains.toLowerCase());
+      results.push({
+        assertion: `contains "${assertion.contains}"`,
+        pass,
+        expected: `Response contains "${assertion.contains}"`,
+        actual: pass ? `Found in response` : `Not found in response`
+      });
+      continue;
+    }
+    if ("not_contains" in assertion) {
+      const pass = !botResponse.toLowerCase().includes(assertion.not_contains.toLowerCase());
+      results.push({
+        assertion: `not_contains "${assertion.not_contains}"`,
+        pass,
+        expected: `Response does not contain "${assertion.not_contains}"`,
+        actual: pass ? `Not found in response` : `Found in response`
+      });
+      continue;
+    }
+    if ("matches" in assertion) {
+      const regex = new RegExp(assertion.matches, "i");
+      const pass = regex.test(botResponse);
+      results.push({
+        assertion: `matches ${assertion.matches}`,
+        pass,
+        expected: `Response matches /${assertion.matches}/`,
+        actual: pass ? `Matched` : `No match`
+      });
+      continue;
+    }
+    if ("llm_judge" in assertion) {
+      const result = await gradeLLMJudge(botResponse, assertion.llm_judge, context);
+      results.push(result);
+      continue;
+    }
+    if ("similar_to" in assertion) {
+      results.push({
+        assertion: `similar_to: "${assertion.similar_to}"`,
+        pass: true,
+        expected: assertion.similar_to,
+        actual: "SKIPPED — similar_to not yet implemented"
+      });
+      continue;
+    }
+    results.push({
+      assertion: "unknown",
+      pass: false,
+      expected: "known assertion type",
+      actual: `Unknown assertion: ${JSON.stringify(assertion)}`
+    });
+  }
+  return results;
+}
+
+// src/eval/graders/match.ts
+function matchValue(operator, actual) {
+  if (typeof operator === "string") {
+    return String(actual) === operator;
+  }
+  if ("equals" in operator) {
+    return actual === operator.equals;
+  }
+  if ("contains" in operator) {
+    return String(actual).toLowerCase().includes(operator.contains.toLowerCase());
+  }
+  if ("not_contains" in operator) {
+    return !String(actual).toLowerCase().includes(operator.not_contains.toLowerCase());
+  }
+  if ("matches" in operator) {
+    return new RegExp(operator.matches, "i").test(String(actual));
+  }
+  if ("in" in operator) {
+    return operator.in.includes(actual);
+  }
+  if ("exists" in operator) {
+    return operator.exists ? actual !== undefined && actual !== null : actual === undefined || actual === null;
+  }
+  if ("gte" in operator) {
+    return Number(actual) >= operator.gte;
+  }
+  if ("lte" in operator) {
+    return Number(actual) <= operator.lte;
+  }
+  return false;
+}
+function operatorToString(operator) {
+  if (typeof operator === "string")
+    return `equals "${operator}"`;
+  if ("equals" in operator)
+    return `equals ${JSON.stringify(operator.equals)}`;
+  if ("contains" in operator)
+    return `contains "${operator.contains}"`;
+  if ("not_contains" in operator)
+    return `not_contains "${operator.not_contains}"`;
+  if ("matches" in operator)
+    return `matches /${operator.matches}/`;
+  if ("in" in operator)
+    return `in [${operator.in.map((v) => JSON.stringify(v)).join(", ")}]`;
+  if ("exists" in operator)
+    return operator.exists ? "exists" : "does not exist";
+  if ("gte" in operator)
+    return `>= ${operator.gte}`;
+  if ("lte" in operator)
+    return `<= ${operator.lte}`;
+  return JSON.stringify(operator);
+}
+
+// src/eval/graders/tools.ts
+function gradeTools(toolCalls, assertions) {
+  return assertions.map((assertion) => {
+    if ("called" in assertion && !("not_called" in assertion) && !("call_order" in assertion)) {
+      const matches = toolCalls.filter((tc) => tc.name === assertion.called);
+      const wasCalled = matches.length > 0;
+      if (!wasCalled) {
+        return {
+          assertion: `tool called: ${assertion.called}`,
+          pass: false,
+          expected: `${assertion.called} was called`,
+          actual: `Not called. Tools called: [${toolCalls.map((tc) => tc.name).join(", ") || "none"}]`
+        };
+      }
+      if (assertion.params) {
+        const paramResults = [];
+        for (const [key, operator] of Object.entries(assertion.params)) {
+          const anyMatch = matches.some((tc) => matchValue(operator, tc.input[key]));
+          paramResults.push({
+            key,
+            pass: anyMatch,
+            detail: anyMatch ? `matched` : `expected ${key} ${operatorToString(operator)}, got ${JSON.stringify(matches.map((tc) => tc.input[key]))}`
+          });
+        }
+        const allParamsPass = paramResults.every((p) => p.pass);
+        const failedParams = paramResults.filter((p) => !p.pass);
+        return {
+          assertion: `tool called: ${assertion.called} with params`,
+          pass: allParamsPass,
+          expected: `${assertion.called} called with ${Object.entries(assertion.params).map(([k, v]) => `${k} ${operatorToString(v)}`).join(", ")}`,
+          actual: allParamsPass ? `Matched` : failedParams.map((p) => p.detail).join("; ")
+        };
+      }
+      return {
+        assertion: `tool called: ${assertion.called}`,
+        pass: true,
+        expected: `${assertion.called} was called`,
+        actual: `Called ${matches.length} time(s)`
+      };
+    }
+    if ("not_called" in assertion) {
+      const wasCalled = toolCalls.some((tc) => tc.name === assertion.not_called);
+      return {
+        assertion: `tool not_called: ${assertion.not_called}`,
+        pass: !wasCalled,
+        expected: `${assertion.not_called} was NOT called`,
+        actual: wasCalled ? `Was called` : `Not called`
+      };
+    }
+    if ("call_order" in assertion) {
+      const calledNames = toolCalls.map((tc) => tc.name);
+      const expectedOrder = assertion.call_order;
+      let cursor = 0;
+      for (const name of calledNames) {
+        if (cursor < expectedOrder.length && name === expectedOrder[cursor]) {
+          cursor++;
+        }
       }
+      const inOrder = cursor === expectedOrder.length;
+      return {
+        assertion: `call_order: [${expectedOrder.join(" → ")}]`,
+        pass: inOrder,
+        expected: `Tools called in order: [${expectedOrder.join(" → ")}]`,
+        actual: `Actual order: [${calledNames.join(" → ") || "none"}]`
+      };
+    }
+    return {
+      assertion: "unknown tool assertion",
+      pass: false,
+      expected: "known assertion type",
+      actual: `Unknown: ${JSON.stringify(assertion)}`
     };
+  });
+}
+
+// src/eval/graders/state.ts
+function parseStatePath(path42) {
+  const dot = path42.indexOf(".");
+  if (dot === -1) {
+    throw new Error(`Invalid state path "${path42}" — expected "type.field" format`);
   }
-  async run(scriptPath, options = {}) {
-    const { botPath, runnerPath, project } = await this.prepare();
-    const absoluteScriptPath = path41.isAbsolute(scriptPath) ? scriptPath : path41.resolve(this.projectPath, scriptPath);
-    if (!existsSync10(absoluteScriptPath)) {
-      throw new Error(`Script not found: ${absoluteScriptPath}`);
+  const prefix = path42.slice(0, dot);
+  const field = path42.slice(dot + 1);
+  switch (prefix) {
+    case "bot":
+      return { type: "bot", stateName: "botState", stateId: (ctx) => ctx.botId, field };
+    case "user":
+      return { type: "user", stateName: "userState", stateId: (ctx) => ctx.userId, field };
+    case "conversation":
+      return { type: "conversation", stateName: "conversationState", stateId: (ctx) => ctx.conversationId, field };
+    default:
+      throw new Error(`Unknown state type "${prefix}" in path "${path42}" — expected bot, user, or conversation`);
+  }
+}
+async function fetchState(client, type, id, name) {
+  try {
+    const result = await client.getState({ type, id, name });
+    const payload = result.state?.payload;
+    return payload?.value ?? payload ?? null;
+  } catch (err) {
+    if (err?.code === 404 || err?.message?.includes("404") || err?.message?.includes("doesn't exist")) {
+      return null;
     }
-    const botId = this.prod ? project.agentInfo?.botId : project.agentInfo?.devId || project.agentInfo?.botId;
-    const workspaceId = project.agentInfo?.workspaceId;
-    if (!botId) {
-      const idType = this.prod ? "botId" : "devId";
-      throw new Error(`No ${idType} found in agent.json. ` + (this.prod ? 'Please deploy your agent first with "adk deploy".' : 'Please run "adk dev" first to create a development bot, or use --prod to use the production bot.'));
+    throw err;
+  }
+}
+async function fetchStateWithRetry(client, type, id, name, field, maxRetries = 3, retryDelay = 1000) {
+  for (let attempt = 0;attempt <= maxRetries; attempt++) {
+    const payload = await fetchState(client, type, id, name);
+    if (payload && payload[field] !== undefined) {
+      return payload;
     }
-    const args = ["run", runnerPath, absoluteScriptPath, ...options.args || []];
-    let configuration;
+    if (attempt < maxRetries) {
+      await new Promise((resolve4) => setTimeout(resolve4, retryDelay));
+    }
+  }
+  return null;
+}
+async function snapshotState(client, assertions, ctx) {
+  const snapshots = new Map;
+  for (const assertion of assertions) {
+    if (assertion.changed === undefined)
+      continue;
+    const parsed = parseStatePath(assertion.path);
+    if (parsed.type === "conversation")
+      continue;
+    const payload = await fetchState(client, parsed.type, parsed.stateId(ctx), parsed.stateName);
+    snapshots.set(assertion.path, payload ? payload[parsed.field] : undefined);
+  }
+  return snapshots;
+}
+async function gradeState(client, assertions, ctx, preSnapshots) {
+  const results = [];
+  for (const assertion of assertions) {
+    const parsed = parseStatePath(assertion.path);
+    const stateId = parsed.stateId(ctx);
+    let payload;
     try {
-      const manager3 = new ConfigManager(botId);
-      configuration = await manager3.getAll();
-    } catch {}
-    const env = {
-      ...process.env,
-      ADK_PROJECT_PATH: this.projectPath,
-      ADK_BOT_PATH: botPath,
-      ADK_BOT_ID: botId,
-      ADK_WORKSPACE_ID: workspaceId || "",
-      ADK_IS_PROD: this.prod ? "true" : "false",
-      BP_DISABLE_WORKER_MODE: "true",
-      ...options.env,
-      ADK_SCRIPT_MODE: "true",
-      ADK_SCRIPT_PATH: absoluteScriptPath,
-      ADK_TOKEN: this.credentials.token,
-      ADK_API_URL: this.credentials.apiUrl,
-      ...configuration && { ADK_CONFIGURATION: JSON.stringify(configuration) }
-    };
-    return new Promise((resolve3, reject) => {
-      const child = spawn("bun", args, {
-        cwd: botPath,
-        env,
-        stdio: options.inheritStdio !== false ? "inherit" : "pipe"
+      payload = await fetchStateWithRetry(client, parsed.type, stateId, parsed.stateName, parsed.field);
+    } catch (err) {
+      results.push({
+        assertion: `state: ${assertion.path}`,
+        pass: false,
+        expected: `Fetch state for ${assertion.path}`,
+        actual: `Error fetching state: ${err.message}`
       });
-      child.on("error", (error) => {
-        reject(error);
+      continue;
+    }
+    const actualValue = payload ? payload[parsed.field] : undefined;
+    if (assertion.equals !== undefined) {
+      const pass = deepEqual(actualValue, assertion.equals);
+      results.push({
+        assertion: `state: ${assertion.path} equals`,
+        pass,
+        expected: JSON.stringify(assertion.equals),
+        actual: JSON.stringify(actualValue)
       });
-      child.on("close", (code) => {
-        resolve3(code ?? 0);
+    }
+    if (assertion.changed !== undefined) {
+      const preValue = preSnapshots?.get(assertion.path);
+      const didChange = !deepEqual(actualValue, preValue);
+      const pass = assertion.changed ? didChange : !didChange;
+      results.push({
+        assertion: `state: ${assertion.path} ${assertion.changed ? "changed" : "unchanged"}`,
+        pass,
+        expected: assertion.changed ? `Value changed from ${JSON.stringify(preValue)}` : `Value unchanged from ${JSON.stringify(preValue)}`,
+        actual: didChange ? `Changed to ${JSON.stringify(actualValue)}` : `Unchanged: ${JSON.stringify(actualValue)}`
       });
+    }
+  }
+  return results;
+}
+function deepEqual(a, b) {
+  if (a === b)
+    return true;
+  if (a === null || b === null)
+    return false;
+  if (typeof a !== typeof b)
+    return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length)
+      return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+      return false;
+    return keysA.every((k) => deepEqual(a[k], b[k]));
+  }
+  return false;
+}
+
+// src/eval/graders/tables.ts
+function buildFilter(conditions) {
+  const filter = {};
+  for (const [column, op] of Object.entries(conditions)) {
+    if (typeof op === "string") {
+      filter[column] = op;
+    } else if ("equals" in op) {
+      filter[column] = op.equals;
+    } else if ("contains" in op) {
+      filter[column] = { $regex: op.contains };
+    } else if ("matches" in op) {
+      filter[column] = { $regex: op.matches };
+    } else if ("gte" in op) {
+      filter[column] = { $gte: op.gte };
+    } else if ("lte" in op) {
+      filter[column] = { $lte: op.lte };
+    }
+  }
+  return filter;
+}
+async function gradeRowExists(client, assertion) {
+  const conditionDesc = Object.entries(assertion.row_exists).map(([k, v]) => `${k} ${operatorToString(v)}`).join(", ");
+  try {
+    const filter = buildFilter(assertion.row_exists);
+    const result = await client.findTableRows({
+      table: assertion.table,
+      filter,
+      limit: 10
     });
+    const rows = result.rows || [];
+    const matchingRows = rows.filter((row) => {
+      for (const [column, op] of Object.entries(assertion.row_exists)) {
+        if (!matchValue(op, row[column]))
+          return false;
+      }
+      return true;
+    });
+    const pass = matchingRows.length > 0;
+    return {
+      assertion: `table: ${assertion.table} row_exists`,
+      pass,
+      expected: `Row exists in ${assertion.table} where ${conditionDesc}`,
+      actual: pass ? `Found ${matchingRows.length} matching row(s)` : `No matching rows found`
+    };
+  } catch (err) {
+    return {
+      assertion: `table: ${assertion.table} row_exists`,
+      pass: false,
+      expected: `Row exists in ${assertion.table} where ${conditionDesc}`,
+      actual: `Error querying table: ${err.message}`
+    };
   }
 }
-async function runScript(options) {
-  const runner = new ScriptRunner({
-    projectPath: options.projectPath,
-    forceRegenerate: options.forceRegenerate,
-    prod: options.prod,
-    credentials: options.credentials
-  });
-  return runner.run(options.scriptPath, {
-    args: options.args,
-    env: options.env,
-    inheritStdio: options.inheritStdio
-  });
+async function gradeRowCount(client, assertion) {
+  const countDesc = operatorToString(assertion.row_count);
+  const whereDesc = assertion.where ? ` where ${Object.entries(assertion.where).map(([k, v]) => `${k} ${operatorToString(v)}`).join(", ")}` : "";
+  try {
+    const filter = assertion.where ? buildFilter(assertion.where) : {};
+    const result = await client.findTableRows({
+      table: assertion.table,
+      filter,
+      limit: 1000
+    });
+    const rows = result.rows || [];
+    let count;
+    if (assertion.where) {
+      count = rows.filter((row) => {
+        for (const [column, op] of Object.entries(assertion.where)) {
+          if (!matchValue(op, row[column]))
+            return false;
+        }
+        return true;
+      }).length;
+    } else {
+      count = rows.length;
+    }
+    const pass = matchValue(assertion.row_count, count);
+    return {
+      assertion: `table: ${assertion.table} row_count`,
+      pass,
+      expected: `Row count in ${assertion.table}${whereDesc} ${countDesc}`,
+      actual: `Count: ${count}`
+    };
+  } catch (err) {
+    return {
+      assertion: `table: ${assertion.table} row_count`,
+      pass: false,
+      expected: `Row count in ${assertion.table}${whereDesc} ${countDesc}`,
+      actual: `Error querying table: ${err.message}`
+    };
+  }
 }
-async function setupTestRuntime(options = {}) {
-  let projectPath = options.projectPath;
-  if (!projectPath) {
-    const detected = await findAgentRoot(process.cwd());
-    if (!detected) {
-      throw new Error(`Could not find ADK agent project. No agent.config.ts found in current directory or parents.
-Either run from within an agent project directory, or provide projectPath explicitly.`);
+async function gradeTables(client, assertions) {
+  const results = [];
+  for (const assertion of assertions) {
+    if ("row_exists" in assertion) {
+      results.push(await gradeRowExists(client, assertion));
+    } else if ("row_count" in assertion) {
+      results.push(await gradeRowCount(client, assertion));
     }
-    projectPath = detected;
   }
-  let credentials = options.credentials;
-  if (!credentials) {
-    const credentialsManager = new CredentialsManager;
-    const loadedCredentials = await credentialsManager.getCredentials();
-    if (!loadedCredentials) {
-      throw new Error('No credentials found. Please run "adk login" first, or provide credentials explicitly.');
+  return results;
+}
+
+// src/eval/graders/workflow.ts
+function gradeWorkflows(spans, assertions) {
+  const results = [];
+  for (const assertion of assertions) {
+    const workflowSpans = spans.filter((span) => {
+      const wfName = span.attrs?.["workflow.name"] || span.attrs?.["workflowName"];
+      return wfName === assertion.name;
+    });
+    if (assertion.entered !== undefined) {
+      const wasEntered = workflowSpans.length > 0;
+      const pass = assertion.entered ? wasEntered : !wasEntered;
+      results.push({
+        assertion: `workflow: ${assertion.name} ${assertion.entered ? "entered" : "not entered"}`,
+        pass,
+        expected: assertion.entered ? `Workflow "${assertion.name}" was entered` : `Workflow "${assertion.name}" was not entered`,
+        actual: wasEntered ? `Found ${workflowSpans.length} workflow span(s)` : `No workflow spans found`
+      });
     }
-    credentials = {
-      token: loadedCredentials.token,
-      apiUrl: loadedCredentials.apiUrl
+    if (assertion.completed !== undefined) {
+      const completedSpans = workflowSpans.filter((span) => {
+        const status = span.attrs?.["workflow.status"];
+        return status === "completed" || span.t === "end" && span.name?.includes("workflow");
+      });
+      const didComplete = completedSpans.length > 0;
+      const pass = assertion.completed ? didComplete : !didComplete;
+      results.push({
+        assertion: `workflow: ${assertion.name} ${assertion.completed ? "completed" : "not completed"}`,
+        pass,
+        expected: assertion.completed ? `Workflow "${assertion.name}" completed` : `Workflow "${assertion.name}" did not complete`,
+        actual: didComplete ? `Completed` : `Not completed`
+      });
+    }
+  }
+  return results;
+}
+
+// src/eval/graders/outcome.ts
+async function snapshotOutcomeState(client, evalDef, ctx) {
+  if (!evalDef.outcome?.state) {
+    return new Map;
+  }
+  return snapshotState(client, evalDef.outcome.state, ctx);
+}
+async function gradeOutcome(client, evalDef, ctx, traceSpans, preSnapshots) {
+  const outcome = evalDef.outcome;
+  if (!outcome)
+    return [];
+  const results = [];
+  if (outcome.state && outcome.state.length > 0) {
+    const stateResults = await gradeState(client, outcome.state, ctx, preSnapshots);
+    results.push(...stateResults);
+  }
+  if (outcome.tables && outcome.tables.length > 0) {
+    const tableResults = await gradeTables(client, outcome.tables);
+    results.push(...tableResults);
+  }
+  if (outcome.workflow && outcome.workflow.length > 0) {
+    const workflowResults = gradeWorkflows(traceSpans, outcome.workflow);
+    results.push(...workflowResults);
+  }
+  return results;
+}
+
+// src/eval/runner.ts
+import { randomUUID } from "crypto";
+async function runEval(evalDef, connection, options = {}) {
+  const devServerUrl = options.devServerUrl || "http://localhost:3001";
+  const start = Date.now();
+  const turns = [];
+  let outcomeAssertions = [];
+  try {
+    const session = new ChatSession(connection.webhookId);
+    await session.connect();
+    let bpClient = null;
+    const getBpClient = () => {
+      if (!bpClient) {
+        bpClient = new BpClient2({
+          token: connection.token,
+          botId: connection.botId,
+          apiUrl: connection.apiUrl
+        });
+      }
+      return bpClient;
+    };
+    let preSnapshots = new Map;
+    if (evalDef.outcome?.state) {
+      const ctx = {
+        botId: connection.botId,
+        userId: session.userId,
+        conversationId: ""
+      };
+      preSnapshots = await snapshotOutcomeState(getBpClient(), evalDef, ctx);
+    }
+    let previousToolCallCount = 0;
+    let lastConversationId = "";
+    let allTraceSpans = [];
+    for (let i = 0;i < evalDef.conversation.length; i++) {
+      const turn = evalDef.conversation[i];
+      const turnStart = Date.now();
+      const result = await session.sendMessage(turn.user, {
+        timeout: 30000,
+        idleTimeout: 3000
+      });
+      const botDuration = Date.now() - turnStart;
+      lastConversationId = result.conversationId;
+      const botResponse = result.responses.map((r) => r.text).join(`
+`);
+      const evalStart = Date.now();
+      let assertions = [];
+      if (turn.assert?.response) {
+        assertions = await gradeResponse(botResponse, turn.assert.response, {
+          userMessage: turn.user
+        });
+      }
+      if (turn.assert?.tools) {
+        try {
+          const expectNewCalls = turn.assert.tools.some((a) => ("called" in a) || ("call_order" in a));
+          const traceData = await getTraceData(result.conversationId, devServerUrl, {
+            previousToolCallCount,
+            expectNewCalls
+          });
+          previousToolCallCount = traceData.totalToolCallCount;
+          allTraceSpans = traceData.raw;
+          const toolResults = gradeTools(traceData.toolCalls, turn.assert.tools);
+          assertions = [...assertions, ...toolResults];
+        } catch (err) {
+          for (const toolAssert of turn.assert.tools) {
+            const name = "called" in toolAssert ? toolAssert.called : ("not_called" in toolAssert) ? toolAssert.not_called : "call_order";
+            assertions.push({
+              assertion: `tool: ${name}`,
+              pass: false,
+              expected: `Tool assertion on ${name}`,
+              actual: `Failed to fetch traces: ${err.message}`
+            });
+          }
+        }
+      }
+      if (turn.assert?.state) {
+        try {
+          const ctx = {
+            botId: connection.botId,
+            userId: session.userId,
+            conversationId: result.conversationId
+          };
+          const stateResults = await gradeState(getBpClient(), turn.assert.state, ctx, preSnapshots);
+          assertions.push(...stateResults);
+        } catch (err) {
+          assertions.push({
+            assertion: "state",
+            pass: false,
+            expected: "State assertions executed",
+            actual: `Error: ${err.message}`
+          });
+        }
+      }
+      if (turn.assert?.tables) {
+        try {
+          const tableResults = await gradeTables(getBpClient(), turn.assert.tables);
+          assertions.push(...tableResults);
+        } catch (err) {
+          assertions.push({
+            assertion: "tables",
+            pass: false,
+            expected: "Table assertions executed",
+            actual: `Error: ${err.message}`
+          });
+        }
+      }
+      if (turn.assert?.workflow) {
+        if (allTraceSpans.length === 0) {
+          try {
+            const traceData = await getTraceData(result.conversationId, devServerUrl);
+            allTraceSpans = traceData.raw;
+          } catch {}
+        }
+        const workflowResults = gradeWorkflows(allTraceSpans, turn.assert.workflow);
+        assertions.push(...workflowResults);
+      }
+      const turnPass = assertions.every((a) => a.pass);
+      const evalDuration = Date.now() - evalStart;
+      turns.push({
+        turnNumber: i + 1,
+        userMessage: turn.user,
+        botResponse,
+        assertions,
+        pass: turnPass,
+        botDuration,
+        evalDuration
+      });
+    }
+    if (evalDef.outcome) {
+      if (allTraceSpans.length === 0 && lastConversationId && evalDef.outcome.workflow) {
+        try {
+          const traceData = await getTraceData(lastConversationId, devServerUrl);
+          allTraceSpans = traceData.raw;
+        } catch {}
+      }
+      const ctx = {
+        botId: connection.botId,
+        userId: session.userId,
+        conversationId: lastConversationId
+      };
+      try {
+        outcomeAssertions = await gradeOutcome(getBpClient(), evalDef, ctx, allTraceSpans, preSnapshots);
+      } catch (err) {
+        outcomeAssertions = [
+          {
+            assertion: "outcome",
+            pass: false,
+            expected: "Outcome assertions executed",
+            actual: `Error: ${err.message}`
+          }
+        ];
+      }
+    }
+    const turnsPass = turns.every((t) => t.pass);
+    const outcomePass = outcomeAssertions.every((a) => a.pass);
+    return {
+      name: evalDef.name,
+      description: evalDef.description,
+      type: evalDef.type,
+      tags: evalDef.tags,
+      turns,
+      outcomeAssertions,
+      pass: turnsPass && outcomePass,
+      duration: Date.now() - start
+    };
+  } catch (err) {
+    return {
+      name: evalDef.name,
+      description: evalDef.description,
+      type: evalDef.type,
+      tags: evalDef.tags,
+      turns,
+      outcomeAssertions,
+      pass: false,
+      duration: Date.now() - start,
+      error: err.message
     };
   }
-  const runner = new ScriptRunner({
-    projectPath,
-    forceRegenerate: options.forceRegenerate,
-    prod: options.prod,
-    credentials
+}
+async function runEvalSuite(config, filter) {
+  const start = Date.now();
+  const runId = randomUUID().replace(/-/g, "").slice(0, 26);
+  initLLMJudge({
+    token: config.credentials.token,
+    apiUrl: config.credentials.apiUrl,
+    botId: config.credentials.botId
   });
-  return runner.setupTestRuntime({ env: options.env });
+  const evalsDir = `${config.agentPath}/evals`;
+  const allEvals = await loadEvalsFromDir(evalsDir);
+  const evals = filterEvals(allEvals, filter);
+  if (evals.length === 0) {
+    return {
+      id: runId,
+      timestamp: new Date().toISOString(),
+      evals: [],
+      passed: 0,
+      failed: 0,
+      total: 0,
+      duration: 0,
+      filter
+    };
+  }
+  let webhookId = config.credentials.webhookId;
+  if (!webhookId) {
+    webhookId = await discoverWebhookId(config.credentials.botId, config.credentials.token, config.credentials.apiUrl);
+  }
+  const connection = {
+    webhookId,
+    botId: config.credentials.botId,
+    token: config.credentials.token,
+    apiUrl: config.credentials.apiUrl
+  };
+  const devServerUrl = config.devServerUrl || "http://localhost:3001";
+  const reports = [];
+  config.onProgress?.({ type: "suite_start", totalEvals: evals.length });
+  for (let i = 0;i < evals.length; i++) {
+    const evalDef = evals[i];
+    config.onProgress?.({ type: "eval_start", evalName: evalDef.name, index: i });
+    const report = await runEval(evalDef, connection, { devServerUrl });
+    reports.push(report);
+    config.onProgress?.({ type: "eval_complete", evalName: evalDef.name, index: i, report });
+  }
+  const runReport = {
+    id: runId,
+    timestamp: new Date().toISOString(),
+    evals: reports,
+    passed: reports.filter((r) => r.pass).length,
+    failed: reports.filter((r) => !r.pass).length,
+    total: reports.length,
+    duration: Date.now() - start,
+    filter
+  };
+  config.onProgress?.({ type: "suite_complete", report: runReport });
+  return runReport;
+}
+// src/eval/store.ts
+import { existsSync as existsSync12, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, readFileSync as readFileSync3, readdirSync as readdirSync4 } from "fs";
+import { join as join10 } from "path";
+function getRunsDir(agentPath) {
+  const dir = join10(agentPath, ".adk", "evals", "runs");
+  if (!existsSync12(dir)) {
+    mkdirSync2(dir, { recursive: true });
+  }
+  return dir;
+}
+function saveRunResult(agentPath, report) {
+  const dir = getRunsDir(agentPath);
+  const filename = `${report.timestamp.replace(/[:.]/g, "-")}-${report.id}.json`;
+  const filepath = join10(dir, filename);
+  writeFileSync2(filepath, JSON.stringify(report, null, 2));
+  return filepath;
+}
+function loadRunResult(agentPath, runId) {
+  const dir = getRunsDir(agentPath);
+  const files = readdirSync4(dir).filter((f) => f.endsWith(".json"));
+  for (const file of files) {
+    if (file.includes(runId)) {
+      const filepath = join10(dir, file);
+      return JSON.parse(readFileSync3(filepath, "utf-8"));
+    }
+  }
+  return null;
+}
+function listRunResults(agentPath, limit = 50) {
+  const dir = getRunsDir(agentPath);
+  if (!existsSync12(dir))
+    return [];
+  const files = readdirSync4(dir).filter((f) => f.endsWith(".json")).sort().reverse().slice(0, limit);
+  return files.map((file) => {
+    const filepath = join10(dir, file);
+    return JSON.parse(readFileSync3(filepath, "utf-8"));
+  });
+}
+function getLatestRun(agentPath) {
+  const runs = listRunResults(agentPath, 1);
+  return runs[0] || null;
 }
 export {
   workspaceCache,
   stringifyWithOrder,
   setupTestRuntime,
+  saveRunResult,
   runScript,
+  runEvalSuite,
+  runEval,
   orderKeys,
+  loadRunResult,
+  loadEvalsFromDir,
+  loadEvalFile,
+  loadEvalByName,
+  listRunResults,
   integrationKeyOrder,
   initAssets,
   getRelativeTime,
+  getLatestRun,
+  getInnerTypeName,
   generateIntegrationTypes,
   generateClientWrapper,
   generateBotProject,
   generateAssetsTypes,
   generateAssetsRuntime,
+  filterEvals,
   dependenciesKeyOrder,
+  defineEval,
+  coerceConfigValue,
   bpCliImporter,
   auth,
   agentInfoKeyOrder,
@@ -12642,4 +12595,4 @@ export {
   AgentProject
 };
 
-//# debugId=A068F5974643B24F64756E2164756E21
+//# debugId=D97F506CD3BBA90E64756E2164756E21