@botpress/adk-cli 1.11.8 → 1.11.9

package/dist/cli.js

@@ -348574,7 +348574,7 @@ var init_internal = __esm(() => {
   });
   init_define_PACKAGE_VERSIONS = __esm2({
     "<define:__PACKAGE_VERSIONS__>"() {
-      define_PACKAGE_VERSIONS_default = { runtime: "1.11.8", adk: "1.11.8", sdk: "4.20.2", llmz: "0.0.33", zai: "2.5.0", cognitive: "0.2.0" };
+      define_PACKAGE_VERSIONS_default = { runtime: "1.11.9", adk: "1.11.9", sdk: "4.20.2", llmz: "0.0.33", zai: "2.5.0", cognitive: "0.2.0" };
     }
   });
   init_asset = __esm2({
@@ -654980,7 +654980,7 @@ var init_library2 = __esm(() => {
   });
   init_define_PACKAGE_VERSIONS2 = __esm4({
     "<define:__PACKAGE_VERSIONS__>"() {
-      define_PACKAGE_VERSIONS_default2 = { runtime: "1.11.8", adk: "1.11.8", sdk: "4.20.2", llmz: "0.0.33", zai: "2.5.0", cognitive: "0.2.0" };
+      define_PACKAGE_VERSIONS_default2 = { runtime: "1.11.9", adk: "1.11.9", sdk: "4.20.2", llmz: "0.0.33", zai: "2.5.0", cognitive: "0.2.0" };
     }
   });
   init_assets2 = __esm4({
@@ -696621,7 +696621,6 @@ import { EventEmitter as EventEmitter24 } from "events";
 import path14 from "path";
 import * as fs11 from "fs";
 import * as path15 from "path";
-import { fileURLToPath as fileURLToPath7 } from "url";
 import path16 from "path";
 import crypto24 from "crypto";
 import path17 from "path";
@@ -696650,14 +696649,14 @@ import { existsSync as existsSync52 } from "fs";
 import crypto42 from "crypto";
 import path332 from "path";
 import fs16 from "fs/promises";
-import { readFileSync as readFileSync22 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { join as join72 } from "path";
 import { watch as watch2, readdirSync as readdirSync22 } from "fs";
 import { EventEmitter as EventEmitter32 } from "events";
 import { join as join82, relative as relative3 } from "path";
 import { existsSync as existsSync7 } from "fs";
 import path342 from "path";
-import { readFileSync as readFileSync32 } from "fs";
+import { readFileSync as readFileSync22 } from "fs";
 import { join as join9 } from "path";
 
 class ValidationErrors {
@@ -699802,7 +699801,7 @@ class AgentProjectGenerator {
         deploy: "adk deploy"
       },
       dependencies: {
-        "@botpress/runtime": "^1.11.8"
+        "@botpress/runtime": "^1.11.9"
       },
       devDependencies: {
         typescript: "^5.9.3"
@@ -699966,9 +699965,7 @@ A Botpress Agent built with the ADK.
     await this.writeFormattedFile("README.md", readme);
   }
   createClaudeMd() {
-    const templatePath = path15.join(__dirname2, "CLAUDE.template.md");
-    const claudeMd = fs11.readFileSync(templatePath, "utf-8");
-    this.writeFile("CLAUDE.md", claudeMd);
+    this.writeFile("CLAUDE.md", CLAUDE_template_default);
   }
   async createSourceStructure() {
     const srcPath = path15.join(this.projectPath, "src");
@@ -704057,11 +704054,1271 @@ var import_ts_morph, __defProp11, __commonJS7 = (cb4, mod) => () => (mod || cb4(
 `));
     return code;
   }
-}, ADK_VERSION = "1.11.8", relative22 = (from, to3) => {
+}, ADK_VERSION = "1.11.9", relative22 = (from, to3) => {
   const fromDir = path102.dirname(from);
   const relative32 = path102.relative(fromDir, to3);
   return relative32.startsWith(".") ? relative32 : `./${relative32}`;
-}, init_utils8, exports_action_types, init_action_types, exports_integration_action_types, init_integration_action_types, require_package3, bpCliImporter, auth, BP_CLI_VERSION = "4.27.3", BP_CLI_INSTALL_ALL, BP_CLI_INSTALL_DIR, BP_CLI_BIN_PATH, BpAddCommand, BpBuildCommand, BpDeployCommand, BpDevCommand, BpChatCommand, workspaceCache, agentInfoKeyOrder, dependenciesKeyOrder, integrationKeyOrder, defaultAdkFolder = ".adk", integrationRefSchema, versionSchema, HubCache, AgentProject, FileWatcher, __filename2, __dirname2, getIntegrationHash = (integration) => {
+}, init_utils8, exports_action_types, init_action_types, exports_integration_action_types, init_integration_action_types, require_package3, bpCliImporter, auth, BP_CLI_VERSION = "4.27.3", BP_CLI_INSTALL_ALL, BP_CLI_INSTALL_DIR, BP_CLI_BIN_PATH, BpAddCommand, BpBuildCommand, BpDeployCommand, BpDevCommand, BpChatCommand, workspaceCache, agentInfoKeyOrder, dependenciesKeyOrder, integrationKeyOrder, defaultAdkFolder = ".adk", integrationRefSchema, versionSchema, HubCache, AgentProject, FileWatcher, CLAUDE_template_default = `# Botpress ADK Project Context
+
+This project is built with the **Botpress Agent Development Kit (ADK)** - a TypeScript-first framework for building AI agents.
+
+## Table of Contents
+
+- [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)
+
+## Quick Reference: Use the Botpress MCP Server
+
+**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.
+
+## What is the ADK?
+
+The ADK allows developers to build Botpress agents using **code instead of the Studio interface**. It provides:
+
+- Project scaffolding with TypeScript
+- Hot reloading development server (\`adk dev\`)
+- Type-safe APIs and auto-generated types
+- Build and deploy to Botpress Cloud
+
+## ADK CLI
+
+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\`
+
+## Core Concepts
+
+### 1. Agent Configuration (\`agent.config.ts\`)
+
+The main configuration file defines:
+
+- **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.)
+
+\`\`\`typescript
+export default defineConfig({
+  name: "my-agent",
+  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:
+
+\`\`\`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],
+    });
+  },
+});
+\`\`\`
+
+### 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)
+
+\`\`\`typescript
+export default new Workflow({
+  name: "periodic-indexing",
+  schedule: "0 */6 * * *",
+  handler: async ({ step }) => {
+    await step("task-name", async () => {
+      // Your logic here
+    });
+  },
+});
+\`\`\`
+
+#### 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 }
+)
+\`\`\`
+
+**Workflow Coordination:**
+
+- \`step.waitForWorkflow()\` - Wait for another workflow to complete
+- \`step.executeWorkflow()\` - Start and wait in one call
+
+\`\`\`typescript
+const result = await step.executeWorkflow('run-child', ChildWorkflow, { input })
+\`\`\`
+
+**Timing Control:**
+
+- \`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
+
+\`\`\`typescript
+await step.sleep('wait-5s', 5000)
+await step.sleepUntil('wait-until-noon', new Date('2025-01-15T12:00:00Z'))
+\`\`\`
+
+**Request Data from Conversation:**
+
+\`\`\`typescript
+// In workflow
+const { topic } = await step.request('topic', 'What topic should I research?')
+
+// In conversation
+if (isWorkflowDataRequest(event)) {
+  await workflow.provide(event, { topic: userInput })
+}
+\`\`\`
+
+**Execution Control:**
+
+- \`step.fail()\` - Mark workflow as failed
+- \`step.abort()\` - Abort without failing
+- \`step.progress()\` - Record progress checkpoint
+
+### 4. Tools (\`src/tools/\`)
+
+**AI-callable functions** that enable agents to perform actions:
+
+- 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
+})
+
+// \u2705 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')
+}
+
+// \u274C 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
+// \u2705 CORRECT - Name must end with "Table"
+export const MyDataTable = new Table({
+  name: "mydataTable",  // Must end with "Table"
+  columns: { ... }
+});
+
+// \u274C 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
+// \u274C WRONG - Using reserved column name
+columns: {
+  createdAt: z.string()  // Reserved!
+}
+
+// \u2705 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
+// \u274C WRONG - Causes duplicate registration errors
+export { MyTable } from "./myTable";
+
+// \u2705 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
+// \u274C WRONG
+import { zai } from '@botpress/runtime'
+const result = await zai.extract(...)
+
+// \u2705 CORRECT
+import { adk } from '@botpress/runtime'
+const result = await adk.zai.extract(...)
+\`\`\`
+
+### 2. Expecting \`.output\` from zai.extract
+\`\`\`typescript
+// \u274C WRONG - zai.extract returns data directly
+const result = await adk.zai.extract(input, schema)
+console.log(result.output)  // undefined!
+
+// \u2705 CORRECT
+const result = await adk.zai.extract(input, schema)
+console.log(result)  // { name: "John", age: 30 }
+\`\`\`
+
+### 3. Wrong Exit Result Handling
+\`\`\`typescript
+// \u274C WRONG
+if (result.exit?.name === 'my_exit') {
+  const data = result.exit.value
+}
+
+// \u2705 CORRECT
+if (result.is(MyExit)) {
+  const data = result.output  // Type-safe!
+}
+\`\`\`
+
+### 4. Reserved Table Column Names
+\`\`\`typescript
+// \u274C WRONG - These are reserved
+columns: {
+  id: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+}
+
+// \u2705 CORRECT - Use alternatives
+columns: {
+  visibleId: z.string(),
+  savedAt: z.string(),
+  modifiedAt: z.string()
+}
+\`\`\`
+
+### 5. Re-exporting Auto-Registered Files
+\`\`\`typescript
+// \u274C WRONG - src/tables/index.ts
+export { MyTable } from "./myTable"  // Causes duplicates!
+
+// \u2705 CORRECT - Leave index.ts empty
+// Files in src/tables/, src/conversations/, etc. are auto-registered
+\`\`\`
+
+### 6. Table Name Missing "Table" Suffix
+\`\`\`typescript
+// \u274C WRONG
+name: "users"
+name: "user_data"
+
+// \u2705 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
+
+## 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)
+`, getIntegrationHash = (integration) => {
   return crypto24.createHash("sha256").update(`${integration.alias}|${integration.definition?.id}|${integration.definition?.version}|${integration.definition?.updatedAt}`).digest("hex");
 }, getPascalAlias = (integration) => pascalCase(getIntegrationAlias(integration.alias)), getIntegrationNames = (integration) => ({
   typings: {
@@ -704106,7 +705363,7 @@ var import_ts_morph, __defProp11, __commonJS7 = (cb4, mod) => () => (mod || cb4(
   } catch {
     try {
       const adkPackagePath = join72(process.cwd(), "node_modules/@botpress/adk/package.json");
-      const pkg = JSON.parse(readFileSync22(adkPackagePath, "utf-8"));
+      const pkg = JSON.parse(readFileSync6(adkPackagePath, "utf-8"));
       return pkg.version;
     } catch {
       return "unknown";
@@ -704119,7 +705376,7 @@ var import_ts_morph, __defProp11, __commonJS7 = (cb4, mod) => () => (mod || cb4(
   } catch {
     try {
       const adkPackagePath = join9(process.cwd(), "node_modules/@botpress/adk/package.json");
-      const pkg = JSON.parse(readFileSync32(adkPackagePath, "utf-8"));
+      const pkg = JSON.parse(readFileSync22(adkPackagePath, "utf-8"));
       return pkg.version;
     } catch {
       return "unknown";
@@ -704273,7 +705530,7 @@ var init_dist17 = __esm(() => {
   require_package3 = __commonJS7((exports7, module) => {
     module.exports = {
       name: "@botpress/adk",
-      version: "1.11.8",
+      version: "1.11.9",
       description: "Core ADK library for building AI agents on Botpress",
       type: "module",
       main: "dist/index.js",
@@ -704320,7 +705577,7 @@ var init_dist17 = __esm(() => {
         "@botpress/cli": "^4.27.3",
         "@botpress/client": "^1.27.2",
         "@botpress/cognitive": "^0.2.0",
-        "@botpress/runtime": "^1.11.8",
+        "@botpress/runtime": "^1.11.9",
         "@botpress/sdk": "^4.18.1",
         "@bpinternal/jex": "^1.2.4",
         "@bpinternal/yargs-extra": "^0.0.21",
@@ -705679,8 +706936,6 @@ ${this.stderrLines.join(`
   init_agent_resolver();
   init_types6();
   init_utils8();
-  __filename2 = fileURLToPath7(import.meta.url);
-  __dirname2 = path15.dirname(__filename2);
   init_fs();
   init_utils8();
   init_utils8();
@@ -706086,7 +707341,7 @@ function pathKey2(options = {}) {
 // ../../node_modules/clipboardy/node_modules/execa/node_modules/npm-run-path/index.js
 import process26 from "process";
 import path35 from "path";
-import { fileURLToPath as fileURLToPath8 } from "url";
+import { fileURLToPath as fileURLToPath7 } from "url";
 var npmRunPath2 = ({
   cwd: cwd4 = process26.cwd(),
   path: pathOption = process26.env[pathKey2()],
@@ -706094,7 +707349,7 @@ var npmRunPath2 = ({
   execPath: execPath3 = process26.execPath,
   addExecPath = true
 } = {}) => {
-  const cwdString = cwd4 instanceof URL ? fileURLToPath8(cwd4) : cwd4;
+  const cwdString = cwd4 instanceof URL ? fileURLToPath7(cwd4) : cwd4;
   const cwdPath = path35.resolve(cwdString);
   const result = [];
   if (preferLocal) {
@@ -706112,7 +707367,7 @@ var npmRunPath2 = ({
     cwdPath = path35.resolve(cwdPath, "..");
   }
 }, applyExecPath2 = (result, execPath3, cwdPath) => {
-  const execPathString = execPath3 instanceof URL ? fileURLToPath8(execPath3) : execPath3;
+  const execPathString = execPath3 instanceof URL ? fileURLToPath7(execPath3) : execPath3;
   result.push(path35.resolve(cwdPath, execPathString, ".."));
 }, npmRunPathEnv2 = ({ env: env6 = process26.env, ...options } = {}) => {
   env6 = { ...env6 };
@@ -707447,8 +708702,8 @@ var init_termux = __esm(() => {
 
 // ../../node_modules/clipboardy/lib/linux.js
 import path38 from "path";
-import { fileURLToPath as fileURLToPath9 } from "url";
-var __dirname3, xsel = "xsel", xselFallback, copyArguments, pasteArguments, makeError3 = (xselError, fallbackError) => {
+import { fileURLToPath as fileURLToPath8 } from "url";
+var __dirname2, xsel = "xsel", xselFallback, copyArguments, pasteArguments, makeError3 = (xselError, fallbackError) => {
   let error;
   if (xselError.code === "ENOENT") {
     error = new Error("Couldn't find the `xsel` binary and fallback didn't work. On Debian/Ubuntu you can install xsel with: sudo apt install xsel");
@@ -707483,8 +708738,8 @@ var __dirname3, xsel = "xsel", xselFallback, copyArguments, pasteArguments, make
 }, clipboard2, linux_default;
 var init_linux = __esm(() => {
   init_execa2();
-  __dirname3 = path38.dirname(fileURLToPath9(import.meta.url));
-  xselFallback = path38.join(__dirname3, "../fallbacks/linux/xsel");
+  __dirname2 = path38.dirname(fileURLToPath8(import.meta.url));
+  xselFallback = path38.join(__dirname2, "../fallbacks/linux/xsel");
   copyArguments = ["--clipboard", "--input"];
   pasteArguments = ["--clipboard", "--output"];
   clipboard2 = {
@@ -707565,14 +708820,14 @@ var init_is64bit = __esm(() => {
 
 // ../../node_modules/clipboardy/lib/windows.js
 import path39 from "path";
-import { fileURLToPath as fileURLToPath10 } from "url";
-var __dirname5, binarySuffix, windowBinaryPath, clipboard4, windows_default;
+import { fileURLToPath as fileURLToPath9 } from "url";
+var __dirname3, binarySuffix, windowBinaryPath, clipboard4, windows_default;
 var init_windows = __esm(() => {
   init_execa2();
   init_is64bit();
-  __dirname5 = path39.dirname(fileURLToPath10(import.meta.url));
+  __dirname3 = path39.dirname(fileURLToPath9(import.meta.url));
   binarySuffix = is64bitSync() ? "x86_64" : "i686";
-  windowBinaryPath = path39.join(__dirname5, `../fallbacks/windows/clipboard_${binarySuffix}.exe`);
+  windowBinaryPath = path39.join(__dirname3, `../fallbacks/windows/clipboard_${binarySuffix}.exe`);
   clipboard4 = {
     copy: async (options) => execa2(windowBinaryPath, ["--copy"], options),
     async paste(options) {
@@ -709284,7 +710539,7 @@ var init_default_browser = __esm(() => {
 import process36 from "process";
 import { Buffer as Buffer8 } from "buffer";
 import path40 from "path";
-import { fileURLToPath as fileURLToPath11 } from "url";
+import { fileURLToPath as fileURLToPath10 } from "url";
 import { promisify as promisify9 } from "util";
 import childProcess3 from "child_process";
 import fs25, { constants as fsConstants2 } from "fs/promises";
@@ -709328,7 +710583,7 @@ function detectPlatformBinary({ [platform4]: platformBinary }, { wsl }) {
   }
   return detectArchBinary(platformBinary);
 }
-var execFile5, __dirname6, localXdgOpenPath, platform4, arch3, pTryEach = async (array, mapper) => {
+var execFile5, __dirname4, localXdgOpenPath, platform4, arch3, pTryEach = async (array, mapper) => {
   let latestError;
   for (const item of array) {
     try {
@@ -709441,7 +710696,7 @@ var execFile5, __dirname6, localXdgOpenPath, platform4, arch3, pTryEach = async
     if (app) {
       command = app;
     } else {
-      const isBundled = !__dirname6 || __dirname6 === "/";
+      const isBundled = !__dirname4 || __dirname4 === "/";
       let exeLocalXdgOpen = false;
       try {
         await fs25.access(localXdgOpenPath, fsConstants2.X_OK);
@@ -709493,8 +710748,8 @@ var init_open = __esm(() => {
   init_default_browser();
   init_is_inside_container();
   execFile5 = promisify9(childProcess3.execFile);
-  __dirname6 = path40.dirname(fileURLToPath11(import.meta.url));
-  localXdgOpenPath = path40.join(__dirname6, "xdg-open");
+  __dirname4 = path40.dirname(fileURLToPath10(import.meta.url));
+  localXdgOpenPath = path40.join(__dirname4, "xdg-open");
   ({ platform: platform4, arch: arch3 } = process36);
   apps = {};
   defineLazyProperty(apps, "chrome", () => detectPlatformBinary({
@@ -710869,7 +712124,7 @@ var init_Separator = __esm(async () => {
 var require_package4 = __commonJS((exports7, module) => {
   module.exports = {
     name: "@botpress/adk",
-    version: "1.11.8",
+    version: "1.11.9",
     description: "Core ADK library for building AI agents on Botpress",
     type: "module",
     main: "dist/index.js",
@@ -710916,7 +712171,7 @@ var require_package4 = __commonJS((exports7, module) => {
       "@botpress/cli": "^4.27.3",
       "@botpress/client": "^1.27.2",
       "@botpress/cognitive": "^0.2.0",
-      "@botpress/runtime": "^1.11.8",
+      "@botpress/runtime": "^1.11.9",
       "@botpress/sdk": "^4.18.1",
       "@bpinternal/jex": "^1.2.4",
       "@bpinternal/yargs-extra": "^0.0.21",
@@ -712856,7 +714111,7 @@ function checkRuntimeVersion(agentRoot) {
 `));
   }
 }
-var semver2, EXPECTED_RUNTIME_VERSION = "1.11.8", SUPPORTED_RUNTIME_RANGE = ">=1.11.0";
+var semver2, EXPECTED_RUNTIME_VERSION = "1.11.9", SUPPORTED_RUNTIME_RANGE = ">=1.11.0";
 var init_runtime_version_check = __esm(() => {
   init_source();
   semver2 = __toESM(require_semver2(), 1);
@@ -716634,17 +717889,17 @@ function getContentType(pathname) {
 import { readFileSync as readFileSync14, existsSync as existsSync15 } from "fs";
 import { join as join16, resolve as resolve5 } from "path";
 import path41 from "path";
-import { fileURLToPath as fileURLToPath12 } from "url";
+import { fileURLToPath as fileURLToPath11 } from "url";
 function getUIDistPath() {
-  const __filename3 = fileURLToPath12(import.meta.url);
-  const __dirname4 = path41.dirname(__filename3);
-  const isBinary = !__filename3.endsWith(".js") && !__filename3.endsWith(".ts");
+  const __filename2 = fileURLToPath11(import.meta.url);
+  const __dirname5 = path41.dirname(__filename2);
+  const isBinary = !__filename2.endsWith(".js") && !__filename2.endsWith(".ts");
   if (isBinary) {
     const execDir = path41.dirname(process.execPath);
     return resolve5(execDir, "assets/ui-dist");
   } else {
-    const isCompiledDist = __filename3.includes("/dist/");
-    return isCompiledDist ? resolve5(__dirname4, "../assets/ui-dist") : resolve5(__dirname4, "../../assets/ui-dist");
+    const isCompiledDist = __filename2.includes("/dist/");
+    return isCompiledDist ? resolve5(__dirname5, "../assets/ui-dist") : resolve5(__dirname5, "../../assets/ui-dist");
   }
 }
 function serveStaticFile(pathname, uiDistPath) {
@@ -722736,7 +723991,7 @@ var stripTrailingSlashes = (str) => {
 
 // ../../node_modules/tar/dist/esm/list.js
 import fs28 from "fs";
-import { dirname as dirname5, parse as parse9 } from "path";
+import { dirname as dirname4, parse as parse9 } from "path";
 var onReadEntryFunction = (opt) => {
   const onReadEntry = opt.onReadEntry;
   opt.onReadEntry = onReadEntry ? (e6) => {
@@ -722756,7 +724011,7 @@ var onReadEntryFunction = (opt) => {
       if (m2 !== undefined) {
         ret = m2;
       } else {
-        ret = mapHas(dirname5(file), root5);
+        ret = mapHas(dirname4(file), root5);
       }
     }
     map.set(file, ret);
@@ -727969,7 +729224,7 @@ __export(exports_upgrade, {
   adkSelfUpgrade: () => adkSelfUpgrade
 });
 import { existsSync as existsSync17, writeFileSync as writeFileSync6, chmodSync, renameSync, unlinkSync, readFileSync as readFileSync16, mkdirSync as mkdirSync5, rmdirSync, accessSync, constants as constants8 } from "fs";
-import { join as join19, dirname as dirname6 } from "path";
+import { join as join19, dirname as dirname5 } from "path";
 import { tmpdir } from "os";
 import { execSync as execSync4 } from "child_process";
 function getPlatformInfo() {
@@ -728057,7 +729312,7 @@ function getCurrentBinaryPath() {
 }
 function checkWritePermissions(path36) {
   try {
-    const dir = dirname6(path36);
+    const dir = dirname5(path36);
     accessSync(dir, constants8.W_OK);
     if (existsSync17(path36)) {
       accessSync(path36, constants8.W_OK);
@@ -872045,7 +873300,7 @@ function dew18() {
   exports$114.Url = Url2;
   return exports$114;
 }
-function fileURLToPath13(path210) {
+function fileURLToPath12(path210) {
   if (typeof path210 === "string")
     path210 = new URL(path210);
   else if (!(path210 instanceof URL)) {
@@ -896753,7 +898008,7 @@ Use Chrome, Firefox or Internet Explorer 11`);
     URL: () => _URL,
     Url: () => Url,
     default: () => exports19,
-    fileURLToPath: () => fileURLToPath13,
+    fileURLToPath: () => fileURLToPath12,
     format: () => format23,
     parse: () => parse17,
     pathToFileURL: () => pathToFileURL,
@@ -896796,7 +898051,7 @@ Use Chrome, Firefox or Internet Explorer 11`);
       processPlatform = typeof Deno !== "undefined" ? Deno.build.os === "windows" ? "win32" : Deno.build.os : undefined;
       exports19.URL = typeof URL !== "undefined" ? URL : null;
       exports19.pathToFileURL = pathToFileURL;
-      exports19.fileURLToPath = fileURLToPath13;
+      exports19.fileURLToPath = fileURLToPath12;
       Url = exports19.Url;
       format23 = exports19.format;
       resolve7 = exports19.resolve;
@@ -905193,14 +906448,14 @@ var init_tools = __esm(() => {
 });
 
 // src/mcp/server.ts
-import { fileURLToPath as fileURLToPath14 } from "url";
-import { dirname as dirname7, join as join25 } from "path";
+import { fileURLToPath as fileURLToPath13 } from "url";
+import { dirname as dirname6, join as join25 } from "path";
 import { readFileSync as readFileSync18 } from "fs";
 function getMcpServerVersion() {
   try {
-    const __filename3 = fileURLToPath14(import.meta.url);
-    const __dirname4 = dirname7(__filename3);
-    const packageJsonPath = join25(__dirname4, "../../package.json");
+    const __filename2 = fileURLToPath13(import.meta.url);
+    const __dirname5 = dirname6(__filename2);
+    const packageJsonPath = join25(__dirname5, "../../package.json");
     const packageJson = JSON.parse(readFileSync18(packageJsonPath, "utf-8"));
     return packageJson.version ?? "0.0.0";
   } catch {
@@ -905267,7 +906522,7 @@ var init_adk_mcp = __esm(() => {
 
 // src/mcp/config-generator.ts
 import { existsSync as existsSync22, mkdirSync as mkdirSync6, writeFileSync as writeFileSync7, readFileSync as readFileSync19 } from "fs";
-import { dirname as dirname8, resolve as resolve9 } from "path";
+import { dirname as dirname7, resolve as resolve9 } from "path";
 function validatePath(basePath, relativePath) {
   const resolvedBase = resolve9(basePath);
   const resolvedPath = resolve9(basePath, relativePath);
@@ -905360,7 +906615,7 @@ function generateConfig(tool, cwd5, options = {}) {
     };
   }
   try {
-    const dir = dirname8(configPath);
+    const dir = dirname7(configPath);
     if (!existsSync22(dir)) {
       mkdirSync6(dir, { recursive: true });
     }
@@ -906116,8 +907371,8 @@ var {
 
 // src/cli.ts
 import { readFileSync as readFileSync20 } from "fs";
-import { join as join28, dirname as dirname9 } from "path";
-import { fileURLToPath as fileURLToPath15 } from "url";
+import { join as join28, dirname as dirname8 } from "path";
+import { fileURLToPath as fileURLToPath14 } from "url";
 
 // src/utils/version-check.tsx
 await init_build2();
@@ -906547,12 +907802,12 @@ if (!checkNodeVersion(true)) {
   checkNodeVersion(false);
   process.exit(1);
 }
-var CLI_VERSION = "1.11.8";
+var CLI_VERSION = "1.11.9";
 if (CLI_VERSION.startsWith("<<") && CLI_VERSION.endsWith(">>")) {
   try {
-    const __filename3 = fileURLToPath15(import.meta.url);
-    const __dirname4 = dirname9(__filename3);
-    const packageJson = JSON.parse(readFileSync20(join28(__dirname4, "../package.json"), "utf-8"));
+    const __filename2 = fileURLToPath14(import.meta.url);
+    const __dirname5 = dirname8(__filename2);
+    const packageJson = JSON.parse(readFileSync20(join28(__dirname5, "../package.json"), "utf-8"));
     CLI_VERSION = packageJson.version;
   } catch {}
 }