@q1k-oss/behaviour-tree-workflows 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -165,7 +165,7 @@ interface TemporalContext extends TickContext {
     tokenProvider?: TokenProvider;
 }
 /**
- * Activity capabilities that can be provided to btree
+ * Activity capabilities that can be provided to behaviour-tree
  * Controlplane creates these via proxyActivities() and passes to context
  */
 interface BtreeActivities {
@@ -189,6 +189,18 @@ interface BtreeActivities {
     deleteFile?: (request: DeleteFileRequest) => Promise<DeleteFileResult>;
     /** Check if file exists in storage */
     fileExists?: (request: FileExistsRequest) => Promise<FileExistsResult>;
+    /** Execute LLM chat completion */
+    llmChat?: (request: LLMChatRequest) => Promise<LLMChatResult>;
+    /** Execute autonomous browser agent via Browserbase + Stagehand */
+    browserAgent?: (request: BrowserAgentRequest) => Promise<BrowserAgentResult>;
+    /** Execute autonomous Claude agent via Claude Agent SDK */
+    claudeAgent?: (request: ClaudeAgentRequest) => Promise<ClaudeAgentResult>;
+    /** Execute GitHub operations (create branch, PR, merge, etc.) */
+    githubAction?: (request: GitHubActionRequest) => Promise<GitHubActionResult>;
+    /** Create a human task (inserts into tasks table, returns taskId) */
+    createHumanTask?: (request: CreateHumanTaskRequest) => Promise<CreateHumanTaskResult>;
+    /** Wait for a human task to be completed (implemented as Temporal condition in workflow) */
+    waitForHumanTask?: (request: WaitForHumanTaskRequest) => Promise<WaitForHumanTaskResult>;
 }
 /**
  * Authentication credentials for a piece
@@ -383,6 +395,299 @@ interface CodeExecutionResult {
     /** Total execution time in milliseconds */
     executionTimeMs: number;
 }
+/**
+ * Supported LLM providers
+ */
+type LLMProvider = "anthropic" | "openai" | "google" | "ollama";
+/**
+ * Message role in conversation
+ */
+type MessageRole = "system" | "user" | "assistant";
+/**
+ * Single message in a conversation
+ */
+interface LLMMessage {
+    role: MessageRole;
+    content: string;
+}
+/**
+ * Request for LLM chat completion
+ */
+interface LLMChatRequest {
+    /** LLM provider to use */
+    provider: LLMProvider;
+    /** Model identifier (e.g., "claude-sonnet-4-20250514", "gpt-4", "gemini-pro") */
+    model: string;
+    /** Conversation messages */
+    messages: LLMMessage[];
+    /** Optional system prompt (prepended as system message) */
+    systemPrompt?: string;
+    /** Sampling temperature (0-2, default: 1) */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Response format: "text" or "json" */
+    responseFormat?: "text" | "json";
+    /** JSON schema for structured output (when responseFormat is "json") */
+    jsonSchema?: Record<string, unknown>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Ollama-specific: base URL for local instance */
+    baseUrl?: string;
+}
+/**
+ * Result from LLM chat completion
+ */
+interface LLMChatResult {
+    /** Generated response content */
+    content: string;
+    /** Parsed JSON if responseFormat was "json" */
+    parsed?: unknown;
+    /** Token usage statistics */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** Model used for completion */
+    model: string;
+    /** Finish reason */
+    finishReason: "stop" | "length" | "content_filter" | "tool_calls" | "error";
+}
+/**
+ * Request for autonomous browser agent execution
+ */
+interface BrowserAgentRequest {
+    /** Goal/instruction for the agent to achieve */
+    goal: string;
+    /** Starting URL (optional - agent may navigate) */
+    startUrl?: string;
+    /** Context ID for persisting cookies/auth/cache (server-side) */
+    contextId?: string;
+    /** Whether to persist context changes (default: false) */
+    persistContext?: boolean;
+    /** Timeout for entire agent execution (ms) */
+    timeout?: number;
+    /** Max steps/actions the agent can take */
+    maxSteps?: number;
+    /** LLM provider for agent reasoning */
+    llmProvider?: LLMProvider;
+    /** LLM model for agent reasoning */
+    llmModel?: string;
+}
+/**
+ * Result from browser agent execution
+ */
+interface BrowserAgentResult {
+    /** Whether the agent achieved the goal (from Stagehand) */
+    success: boolean;
+    /** Whether execution completed (false if hit maxSteps limit) */
+    completed: boolean;
+    /** Human-readable summary of what was accomplished */
+    message: string;
+    actions: Array<{
+        type: string;
+        reasoning?: string;
+        taskCompleted: boolean;
+        pageUrl: string;
+        timestamp: number;
+    }>;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        reasoningTokens: number;
+    };
+    /** Browserbase session ID */
+    sessionId: string;
+    /** URL to view session recording */
+    debugUrl: string;
+    /** Final URL after agent execution */
+    finalUrl: string;
+    /** Context ID (for use in subsequent calls) */
+    contextId?: string;
+    executionTimeMs: number;
+}
+/**
+ * MCP server configuration for ClaudeAgent
+ */
+type ClaudeAgentMcpServerConfig = {
+    type?: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+} | {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+} | {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+};
+/**
+ * Subagent definition for ClaudeAgent
+ */
+interface ClaudeAgentSubagent {
+    description: string;
+    prompt: string;
+    tools?: string[];
+    model?: "sonnet" | "opus" | "haiku" | "inherit";
+}
+/**
+ * Request for autonomous Claude agent execution
+ */
+interface ClaudeAgentRequest {
+    /** Task prompt for the agent */
+    prompt: string;
+    /** Model to use (e.g., "claude-sonnet-4-5-20250929") */
+    model?: string;
+    /** System prompt for agent behavior */
+    systemPrompt?: string;
+    /** Tools the agent can use (e.g., ["Read", "Write", "Edit", "Bash"]) */
+    allowedTools?: string[];
+    /** Permission mode: default, acceptEdits, bypassPermissions */
+    permissionMode?: "default" | "acceptEdits" | "bypassPermissions";
+    /** Maximum conversation turns */
+    maxTurns?: number;
+    /** Maximum budget in USD */
+    maxBudgetUsd?: number;
+    /** Working directory for the agent */
+    cwd?: string;
+    /** MCP server configurations */
+    mcpServers?: Record<string, ClaudeAgentMcpServerConfig>;
+    /** Subagent definitions */
+    agents?: Record<string, ClaudeAgentSubagent>;
+    /** Extra context data passed from blackboard */
+    context?: Record<string, unknown>;
+}
+/**
+ * Result from Claude agent execution
+ */
+interface ClaudeAgentResult {
+    /** Final text result from the agent */
+    result: string;
+    /** Session ID for resuming/continuing */
+    sessionId: string;
+    /** Whether the agent completed successfully */
+    success: boolean;
+    /** Number of conversation turns used */
+    numTurns: number;
+    /** Total cost in USD */
+    totalCostUsd: number;
+    /** Token usage statistics */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheCreationTokens: number;
+    };
+    /** Execution duration in milliseconds */
+    durationMs: number;
+    /** Errors encountered during execution */
+    errors?: string[];
+}
+/**
+ * Supported GitHub operations
+ */
+type GitHubOperation = "createBranch" | "createPullRequest" | "getPullRequest" | "mergePullRequest" | "closePullRequest" | "createReview" | "listIssues" | "addLabels" | "createComment" | "createRelease";
+/**
+ * Request for a GitHub operation
+ */
+interface GitHubActionRequest {
+    /** The operation to perform */
+    operation: GitHubOperation;
+    /** Repository in "owner/repo" format */
+    repo: string;
+    /** Operation-specific parameters */
+    params: Record<string, unknown>;
+}
+/**
+ * Result of a GitHub operation
+ */
+interface GitHubActionResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Operation-specific response data */
+    data: unknown;
+    /** The operation that was performed */
+    operation: GitHubOperation;
+}
+/**
+ * A2UI component definition for human task surfaces
+ */
+interface A2UIComponent {
+    id: string;
+    component: Record<string, unknown>;
+    weight?: number;
+}
+/**
+ * Request to create a human task
+ */
+interface CreateHumanTaskRequest {
+    /** Btree node ID that created this task */
+    nodeId: string;
+    /** Tenant ID for multi-tenancy */
+    tenantId: string;
+    /** Execution/workflow ID */
+    executionId: string;
+    /** Task title */
+    title: string;
+    /** Task description */
+    description?: string;
+    /** Direct assignee email */
+    assigneeEmail?: string;
+    /** Role-based assignment */
+    assigneeRole?: string;
+    /** A2UI component definitions (the frozen surface template) */
+    a2uiComponents: A2UIComponent[];
+    /** Resolved A2UI data model (bindings already evaluated) */
+    a2uiDataModel: Record<string, unknown>;
+    /** Timeout in milliseconds before task expires */
+    timeoutMs?: number;
+    /** What to do on timeout: 'expire' | 'approve' | 'reject' */
+    onTimeout?: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result from creating a human task
+ */
+interface CreateHumanTaskResult {
+    /** Generated task ID (UUID) */
+    taskId: string;
+    /** URL where the task can be accessed */
+    taskUrl: string;
+}
+/**
+ * Request to wait for a human task to be completed
+ */
+interface WaitForHumanTaskRequest {
+    /** Task ID to wait for */
+    taskId: string;
+    /** Node ID (for signal routing) */
+    nodeId: string;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** What to do on timeout */
+    onTimeout?: string;
+}
+/**
+ * Result from a completed human task
+ */
+interface WaitForHumanTaskResult {
+    /** Whether the task was completed (vs timed out) */
+    completed: boolean;
+    /** Submitted form data from the user */
+    submittedData?: Record<string, unknown>;
+    /** Decision string (e.g., 'approved', 'rejected') */
+    decision?: string;
+    /** User ID who completed the task */
+    completedBy?: string;
+    /** Timestamp when completed */
+    completedAt?: string;
+    /** Whether the task timed out */
+    timedOut?: boolean;
+}
 /**
  * Port definition for typed inputs/outputs
  */
@@ -738,9 +1043,9 @@ declare class BehaviorTree {
      *
      * @example
      * ```typescript
-     * import { BehaviorTree } from '@wayfarer-ai/btree';
-     * import { Sequence } from '@wayfarer-ai/btree';
-     * import { PrintAction } from '@wayfarer-ai/btree';
+     * import { BehaviorTree } from '@q1k-oss/behaviour-tree-workflows';
+     * import { Sequence } from '@q1k-oss/behaviour-tree-workflows';
+     * import { PrintAction } from '@q1k-oss/behaviour-tree-workflows';
      *
      * const root = new Sequence({ id: 'root' });
      * root.addChild(new PrintAction({ id: 'step1', message: 'Hello' }));
@@ -1421,7 +1726,7 @@ declare class Registry {
  *
  * @example
  * ```typescript
- * import { Registry, registerStandardNodes } from '@wayfarer-ai/btree';
+ * import { Registry, registerStandardNodes } from '@q1k-oss/behaviour-tree-workflows';
  *
  * const registry = new Registry();
  * registerStandardNodes(registry);
@@ -2426,7 +2731,7 @@ declare const schemaRegistry: SchemaRegistry;
 
 /**
  * Template Loader
- * Load YAML template files from a directory and register them in the btree Registry.
+ * Load YAML template files from a directory and register them in the behaviour-tree Registry.
  * Templates can then be referenced by SubTree nodes using their template ID.
  */
 
@@ -2596,7 +2901,7 @@ declare const envTokenProvider: TokenProvider;
  * Dynamically executes Active Pieces actions
  *
  * Active Pieces is an open-source automation platform with 440+ connectors.
- * This module wraps their npm packages for use in btree workflows.
+ * This module wraps their npm packages for use in behaviour-tree workflows.
  *
  * @see https://activepieces.com/docs
  */
@@ -3038,6 +3343,481 @@ declare class CodeExecution extends ActionNode {
     protected executeTick(context: TemporalContext): Promise<NodeStatus>;
 }
 
+/**
+ * LLMChat Node
+ *
+ * Executes LLM chat completion via a Temporal activity.
+ * This node requires the `llmChat` activity to be configured in the context -
+ * it does not support standalone/inline execution because LLM API calls require
+ * capabilities outside the workflow sandbox.
+ *
+ * Features:
+ * - Multi-provider support (Anthropic, OpenAI, Google, Ollama)
+ * - Variable resolution in messages and system prompt
+ * - JSON response format with schema validation
+ * - Token usage tracking
+ * - Result stored in blackboard
+ */
+
+/**
+ * Configuration for LLMChat node
+ */
+interface LLMChatConfig extends NodeConfiguration {
+    /** LLM provider: anthropic, openai, google, ollama */
+    provider: LLMProvider;
+    /** Model identifier (supports ${bb.model} resolution) */
+    model: string;
+    /** Conversation messages (supports variable resolution in content) */
+    messages: Array<{
+        role: MessageRole;
+        content: string;
+    }>;
+    /** Optional system prompt (supports variable resolution) */
+    systemPrompt?: string;
+    /** Sampling temperature (0-2) */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Response format */
+    responseFormat?: "text" | "json";
+    /** JSON schema for structured output */
+    jsonSchema?: Record<string, unknown>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Ollama base URL for local instance */
+    baseUrl?: string;
+    /** Output key on blackboard for response */
+    outputKey: string;
+}
+/**
+ * LLMChat Node
+ *
+ * Executes LLM chat completion via a Temporal activity and stores the response in blackboard.
+ * Requires the `llmChat` activity to be configured.
+ *
+ * @example YAML - Basic Usage
+ * ```yaml
+ * type: LLMChat
+ * id: summarize
+ * props:
+ *   provider: anthropic
+ *   model: claude-sonnet-4-20250514
+ *   systemPrompt: "You are a helpful assistant."
+ *   messages:
+ *     - role: user
+ *       content: "Summarize: ${bb.documentText}"
+ *   temperature: 0.7
+ *   maxTokens: 1000
+ *   outputKey: summary
+ * ```
+ *
+ * @example YAML - JSON Response
+ * ```yaml
+ * type: LLMChat
+ * id: extract-entities
+ * props:
+ *   provider: openai
+ *   model: gpt-4
+ *   messages:
+ *     - role: user
+ *       content: "Extract entities from: ${bb.text}"
+ *   responseFormat: json
+ *   jsonSchema:
+ *     type: object
+ *     properties:
+ *       people: { type: array, items: { type: string } }
+ *       organizations: { type: array, items: { type: string } }
+ *   outputKey: entities
+ * ```
+ */
+declare class LLMChat extends ActionNode {
+    private provider;
+    private model;
+    private messages;
+    private systemPrompt?;
+    private temperature?;
+    private maxTokens?;
+    private responseFormat;
+    private jsonSchema?;
+    private timeout?;
+    private baseUrl?;
+    private outputKey;
+    constructor(config: LLMChatConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * BrowserAgent Node
+ *
+ * Executes autonomous browser agent via Browserbase + Stagehand.
+ * This node requires the `browserAgent` activity to be configured in the context -
+ * it does not support standalone/inline execution because browser automation requires
+ * capabilities outside the workflow sandbox.
+ *
+ * Features:
+ * - Goal-directed autonomous web navigation
+ * - Browserbase Contexts for session persistence (cookies, auth, cache)
+ * - Session recording via Browserbase for debugging/audit
+ * - Variable resolution in goal and startUrl
+ * - Result stored in blackboard with debugUrl for session replay
+ */
+
+/**
+ * Configuration for BrowserAgent node
+ */
+interface BrowserAgentConfig extends NodeConfiguration {
+    /** Goal for the agent to achieve (supports variable resolution) */
+    goal: string;
+    /** Starting URL (optional, supports variable resolution) */
+    startUrl?: string;
+    /** Blackboard key to store/retrieve contextId */
+    contextKey?: string;
+    /** Whether to persist context changes (cookies, auth, cache) */
+    persistContext?: boolean;
+    /** Timeout for entire agent execution (ms) */
+    timeout?: number;
+    /** Max steps/actions the agent can take */
+    maxSteps?: number;
+    /** LLM provider for Stagehand agent */
+    llmProvider?: LLMProvider;
+    /** LLM model for Stagehand agent */
+    llmModel?: string;
+    /** Output key on blackboard for result */
+    outputKey: string;
+}
+/**
+ * BrowserAgent Node
+ *
+ * Executes autonomous browser agent via Browserbase + Stagehand and stores the result in blackboard.
+ * Requires the `browserAgent` activity to be configured.
+ *
+ * @example YAML - Basic Usage
+ * ```yaml
+ * type: BrowserAgent
+ * id: search
+ * props:
+ *   goal: "Search for weather in NYC and extract the temperature"
+ *   startUrl: "https://google.com"
+ *   timeout: 60000
+ *   maxSteps: 15
+ *   outputKey: searchResult
+ * ```
+ *
+ * @example YAML - Multi-Step with Context Persistence
+ * ```yaml
+ * type: Sequence
+ * id: authenticated-scrape
+ * children:
+ *   - type: BrowserAgent
+ *     id: login
+ *     props:
+ *       goal: "Login with username ${input.user} and password ${input.pass}"
+ *       startUrl: "${input.loginUrl}"
+ *       contextKey: browserContext
+ *       persistContext: true
+ *       outputKey: loginResult
+ *
+ *   - type: BrowserAgent
+ *     id: scrape
+ *     props:
+ *       goal: "Navigate to dashboard and extract all data as JSON"
+ *       contextKey: browserContext
+ *       outputKey: scrapeResult
+ * ```
+ */
+declare class BrowserAgent extends ActionNode {
+    private goal;
+    private startUrl?;
+    private contextKey?;
+    private persistContext;
+    private timeout?;
+    private maxSteps?;
+    private llmProvider?;
+    private llmModel?;
+    private outputKey;
+    constructor(config: BrowserAgentConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * ClaudeAgent Node
+ *
+ * Executes an autonomous Claude agent via a Temporal activity.
+ * This node requires the `claudeAgent` activity to be configured in the context -
+ * it does not support standalone/inline execution because agent execution requires
+ * capabilities outside the workflow sandbox.
+ *
+ * Features:
+ * - Goal-driven autonomous coding agent (powered by Claude Agent SDK)
+ * - Configurable tools, permissions, and cost limits
+ * - MCP server integration for external tools
+ * - Subagent support for delegating specialized tasks
+ * - Variable resolution in prompt, systemPrompt, model, and cwd
+ * - Session ID returned for resuming/continuing agent conversations
+ * - Result stored in blackboard
+ */
+
+/**
+ * Configuration for ClaudeAgent node
+ */
+interface ClaudeAgentConfig extends NodeConfiguration {
+    /** Task prompt for the agent (supports variable resolution) */
+    prompt: string;
+    /** Model to use, e.g. "claude-sonnet-4-5-20250929" (supports variable resolution) */
+    model?: string;
+    /** System prompt for agent behavior (supports variable resolution) */
+    systemPrompt?: string;
+    /** Tools the agent can use (e.g., ["Read", "Write", "Edit", "Bash"]) */
+    allowedTools?: string[];
+    /** Permission mode: default, acceptEdits, bypassPermissions */
+    permissionMode?: "default" | "acceptEdits" | "bypassPermissions";
+    /** Maximum conversation turns */
+    maxTurns?: number;
+    /** Maximum budget in USD */
+    maxBudgetUsd?: number;
+    /** Working directory for the agent (supports variable resolution) */
+    cwd?: string;
+    /** MCP server configurations */
+    mcpServers?: Record<string, ClaudeAgentMcpServerConfig>;
+    /** Subagent definitions */
+    agents?: Record<string, ClaudeAgentSubagent>;
+    /** Output key on blackboard for result */
+    outputKey: string;
+}
+/**
+ * ClaudeAgent Node
+ *
+ * Executes an autonomous Claude agent via the Claude Agent SDK and stores
+ * the result in blackboard. Requires the `claudeAgent` activity to be configured.
+ *
+ * @example YAML - Basic coding task
+ * ```yaml
+ * type: ClaudeAgent
+ * id: implement-feature
+ * props:
+ *   prompt: "Add unit tests for the auth module"
+ *   allowedTools: [Read, Write, Edit, Bash, Glob, Grep]
+ *   permissionMode: acceptEdits
+ *   outputKey: agentResult
+ * ```
+ *
+ * @example YAML - Dev workflow with PR creation
+ * ```yaml
+ * type: ClaudeAgent
+ * id: dev-task
+ * props:
+ *   prompt: "${bb.taskDescription}"
+ *   systemPrompt: |
+ *     You are working on @q1k-oss/behaviour-tree-workflows.
+ *     Read CLAUDE.md for project conventions.
+ *     Create a branch, implement changes, commit, push, and create a PR.
+ *   allowedTools: [Read, Write, Edit, Bash, Glob, Grep]
+ *   permissionMode: acceptEdits
+ *   maxTurns: 100
+ *   maxBudgetUsd: 10.0
+ *   outputKey: agentResult
+ * ```
+ */
+declare class ClaudeAgent extends ActionNode {
+    private prompt;
+    private model?;
+    private systemPrompt?;
+    private allowedTools?;
+    private permissionMode;
+    private maxTurns;
+    private maxBudgetUsd?;
+    private agentCwd?;
+    private mcpServers?;
+    private agents?;
+    private outputKey;
+    constructor(config: ClaudeAgentConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * GitHubAction Node
+ *
+ * Executes deterministic GitHub operations via a Temporal activity.
+ * This node requires the `githubAction` activity to be configured in the context -
+ * it does not support standalone/inline execution because GitHub API access requires
+ * capabilities outside the workflow sandbox.
+ *
+ * Features:
+ * - 10 supported operations (branches, PRs, reviews, issues, releases)
+ * - Variable resolution in repo and params
+ * - Auth handled at activity layer — no tokens in YAML
+ * - Result stored in blackboard
+ *
+ * @example YAML - Create a PR
+ * ```yaml
+ * type: GitHubAction
+ * id: create-pr
+ * props:
+ *   operation: createPullRequest
+ *   repo: "${input.repo}"
+ *   params:
+ *     title: "feat: new feature"
+ *     body: "Description"
+ *     head: "feat/branch"
+ *     base: "main"
+ *   outputKey: prResult
+ * ```
+ */
+
+/**
+ * Configuration for GitHubAction node
+ */
+interface GitHubActionConfig extends NodeConfiguration {
+    /** The GitHub operation to perform */
+    operation: GitHubOperation;
+    /** Repository in "owner/repo" format (supports variable resolution) */
+    repo: string;
+    /** Operation-specific parameters (string values support variable resolution) */
+    params?: Record<string, unknown>;
+    /** Output key on blackboard for result */
+    outputKey: string;
+}
+/**
+ * GitHubAction Node
+ *
+ * Executes deterministic GitHub operations (branches, PRs, reviews, issues,
+ * releases) via an activity and stores the result in blackboard.
+ */
+declare class GitHubAction extends ActionNode {
+    private operation;
+    private repo;
+    private params;
+    private outputKey;
+    constructor(config: GitHubActionConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * HumanTask Node
+ *
+ * Pauses workflow execution to present an A2UI surface to a human user
+ * and waits for their response. This node requires the `createHumanTask`
+ * and `waitForHumanTask` activities to be configured in the context.
+ *
+ * Features:
+ * - A2UI component-based UI definition (frozen at design time)
+ * - Data bindings from workflow context (blackboard/input) to A2UI data model
+ * - Variable resolution in title, description, and assignee
+ * - Configurable timeout with onTimeout behavior
+ * - Response data stored in blackboard
+ *
+ * The actual waiting is handled by the Temporal workflow layer using
+ * condition() + signals, not by blocking the activity.
+ */
+
+/**
+ * Configuration for HumanTask node
+ */
+interface HumanTaskConfig extends NodeConfiguration {
+    /** Task title (supports ${bb.x} / ${input.x} resolution) */
+    title: string;
+    /** Task description (supports variable resolution) */
+    description?: string;
+    /** Assignee email (supports variable resolution) */
+    assignee?: string;
+    /** Role-based assignment */
+    assigneeRole?: string;
+    /** A2UI surface definition */
+    a2ui: {
+        /** Component tree definitions */
+        components: A2UIComponent[];
+        /** Maps A2UI JSON Pointer paths to btree expressions */
+        dataBindings?: Record<string, string>;
+    };
+    /** Timeout in milliseconds (default: 24h) */
+    timeoutMs?: number;
+    /** Behavior on timeout: 'expire' | 'approve' | 'reject' */
+    onTimeout?: string;
+    /** Blackboard key prefix for response data (default: node id) */
+    outputKey?: string;
+}
+/**
+ * HumanTask Node
+ *
+ * Creates a human task with an A2UI surface and waits for the user to respond.
+ *
+ * @example YAML
+ * ```yaml
+ * type: HumanTask
+ * id: expense-approval
+ * props:
+ *   title: "Expense Approval"
+ *   description: "Review expense request from ${input.employeeName}"
+ *   assignee: "${input.managerEmail}"
+ *   a2ui:
+ *     components:
+ *       - id: root
+ *         component:
+ *           Column:
+ *             children:
+ *               explicitList: [header, amount-field, actions]
+ *       - id: header
+ *         component:
+ *           Text:
+ *             text: { path: '/title' }
+ *       - id: amount-field
+ *         component:
+ *           TextField:
+ *             text: { path: '/form/amount' }
+ *             label: { literalString: 'Amount ($)' }
+ *       - id: actions
+ *         component:
+ *           Row:
+ *             children:
+ *               explicitList: [approve-btn, reject-btn]
+ *       - id: approve-btn
+ *         component:
+ *           Button:
+ *             child: approve-text
+ *             primary: true
+ *             action:
+ *               name: submit
+ *               context:
+ *                 - key: decision
+ *                   value: { literalString: approved }
+ *       - id: approve-text
+ *         component:
+ *           Text:
+ *             text: { literalString: Approve }
+ *       - id: reject-btn
+ *         component:
+ *           Button:
+ *             child: reject-text
+ *             action:
+ *               name: submit
+ *               context:
+ *                 - key: decision
+ *                   value: { literalString: rejected }
+ *       - id: reject-text
+ *         component:
+ *           Text:
+ *             text: { literalString: Reject }
+ *     dataBindings:
+ *       /title: "Expense Request from ${input.employeeName}"
+ *       /form/amount: "${input.requestedAmount}"
+ *   timeoutMs: 86400000
+ *   onTimeout: expire
+ *   outputKey: approval
+ * ```
+ */
+declare class HumanTask extends ActionNode {
+    private title;
+    private description?;
+    private assignee?;
+    private assigneeRole?;
+    private a2ui;
+    private timeoutMs;
+    private onTimeout;
+    private outputKey?;
+    constructor(config: HumanTaskConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
 /**
  * Observability types for workflow execution tracking
  * Used by ExecutionTracker and Analyzer Agent
@@ -3241,7 +4021,7 @@ declare class ExecutionTracker {
  * Usage in workflow:
  * ```typescript
  * import { proxySinks } from '@temporalio/workflow';
- * import type { ObservabilitySinks } from '@wayfarer-ai/btree-workflows';
+ * import type { ObservabilitySinks } from '@q1k-oss/behaviour-tree-workflows';
  *
  * const { events } = proxySinks<ObservabilitySinks>();
  * events.push(nodeEvent);  // Fire-and-forget
@@ -3301,7 +4081,7 @@ type InjectedObservabilitySinks = {
  *
  * Usage in worker:
  * ```typescript
- * import { createObservabilitySinkHandler } from '@wayfarer-ai/btree-workflows';
+ * import { createObservabilitySinkHandler } from '@q1k-oss/behaviour-tree-workflows';
  *
  * const sinks = createObservabilitySinkHandler({
  *   onEvent: (workflowId, runId, event) => {
@@ -3317,4 +4097,4 @@ type InjectedObservabilitySinks = {
  */
 declare function createObservabilitySinkHandler(config?: SinkHandlerConfig): InjectedObservabilitySinks;
 
-export { ActionNode, AlwaysCondition, BaseNode, BehaviorTree, type BtreeActivities, CheckCondition, CodeExecution, type CodeExecutionConfig, type CodeExecutionRequest, type CodeExecutionResult, CompositeNode, ConditionNode, Conditional, ConfigValidationError, ConfigurationError, CounterAction, type DataRef$1 as DataRef, type DataStore, DecoratorNode, Delay, type DeleteFileRequest, type DeleteFileResult, type DownloadFileRequest, type DownloadFileResult, type ExecutionProgress, ExecutionTracker, FailureNode, Fallback, type FileExistsRequest, type FileExistsResult, ForEach, ForceFailure, ForceSuccess, GenerateFile, type GenerateFileConfig, type GenerateFileRequest, type GenerateFileResult, HttpRequest, type HttpRequestActivity, type HttpRequestConfig, type HttpResponseActivity, type IScopedBlackboard, type ITreeRegistry, type InferSchema, type InjectedObservabilitySinks, IntegrationAction, type IntegrationActionConfig, type IntegrationContext, Invert, KeepRunningUntilFailure, type LoadOptions, type LogEventData, LogMessage, type LogMessageConfig, MemoryDataStore, MemorySequence, MockAction, type NodeConfiguration, type NodeConstructor, type NodeEvent, type NodeEventCallback, NodeEventEmitter, NodeEventType, type NodeMetadata, type NodeState, NodeStatus, type ObservabilitySinks, type ObservableNodeEvent, Parallel, type ParallelStrategy, ParseFile, type ParseFileConfig, type ParseFileRequest, type ParseFileResult, type ParsedPath, type PieceActivityRequest as PieceActionRequest, type PieceActivityRequest, type PieceAuth, type PortDefinition, Precondition, PrintAction, type PutOptions, PythonScript, type PythonScriptConfig, type PythonScriptRequest, type PythonScriptResult, ReactiveSequence, Recovery, RegexExtract, type RegexExtractConfig, Registry, Repeat, type ResolveOptions, ResumePoint, type ResumePointConfig, RunOnce, RunningNode, SchemaRegistry, ScopedBlackboard, Selector, SemanticValidationError, Sequence, SequenceWithMemory, type SinkHandlerConfig, SoftAssert, StructureValidationError, type StructuredError, SubTree, SuccessNode, type TemplateLoaderOptions, type TemporalContext, type TickContext, type TimelineEntry, Timeout, type TokenProvider, type TreeDefinition, type TreeNode, type UploadFileRequest, type UploadFileResult, type ValidatedNodeConfiguration, ValidationError, ValidationErrors, type ValidationOptions, type ValidationResult, type VariableContext, WaitAction, While, type WorkflowArgs, type WorkflowResult, YamlSyntaxError, clearPieceCache, createNodeSchema, createObservabilitySinkHandler, envTokenProvider, executePieceAction, extractVariables, getTemplateIds, hasTemplate, hasVariables, isDataRef, isPieceInstalled, listPieceActions, loadTemplate, loadTemplatesFromDirectory, loadTreeFromFile, loadTreeFromYaml, nodeConfigurationSchema, parseYaml, registerStandardNodes, resolveString, resolveValue, safeValidateConfiguration, schemaRegistry, semanticValidator, toYaml, treeDefinitionSchema, validateChildCount, validateChildCountRange, validateCompositeChildren, validateConfiguration, validateDecoratorChildren, validateTreeDefinition, validateYaml, validations, zodErrorToConfigurationError };
+export { type A2UIComponent, ActionNode, AlwaysCondition, BaseNode, BehaviorTree, BrowserAgent, type BrowserAgentConfig, type BrowserAgentRequest, type BrowserAgentResult, type BtreeActivities, CheckCondition, ClaudeAgent, type ClaudeAgentConfig, type ClaudeAgentMcpServerConfig, type ClaudeAgentRequest, type ClaudeAgentResult, type ClaudeAgentSubagent, CodeExecution, type CodeExecutionConfig, type CodeExecutionRequest, type CodeExecutionResult, CompositeNode, ConditionNode, Conditional, ConfigValidationError, ConfigurationError, CounterAction, type CreateHumanTaskRequest, type CreateHumanTaskResult, type DataRef$1 as DataRef, type DataStore, DecoratorNode, Delay, type DeleteFileRequest, type DeleteFileResult, type DownloadFileRequest, type DownloadFileResult, type ExecutionProgress, ExecutionTracker, FailureNode, Fallback, type FileExistsRequest, type FileExistsResult, ForEach, ForceFailure, ForceSuccess, GenerateFile, type GenerateFileConfig, type GenerateFileRequest, type GenerateFileResult, GitHubAction, type GitHubActionConfig, type GitHubActionRequest, type GitHubActionResult, type GitHubOperation, HttpRequest, type HttpRequestActivity, type HttpRequestConfig, type HttpResponseActivity, HumanTask, type HumanTaskConfig, type IScopedBlackboard, type ITreeRegistry, type InferSchema, type InjectedObservabilitySinks, IntegrationAction, type IntegrationActionConfig, type IntegrationContext, Invert, KeepRunningUntilFailure, LLMChat, type LLMChatConfig, type LLMChatRequest, type LLMChatResult, type LLMMessage, type LLMProvider, type LoadOptions, type LogEventData, LogMessage, type LogMessageConfig, MemoryDataStore, MemorySequence, type MessageRole, MockAction, type NodeConfiguration, type NodeConstructor, type NodeEvent, type NodeEventCallback, NodeEventEmitter, NodeEventType, type NodeMetadata, type NodeState, NodeStatus, type ObservabilitySinks, type ObservableNodeEvent, Parallel, type ParallelStrategy, ParseFile, type ParseFileConfig, type ParseFileRequest, type ParseFileResult, type ParsedPath, type PieceActivityRequest as PieceActionRequest, type PieceActivityRequest, type PieceAuth, type PortDefinition, Precondition, PrintAction, type PutOptions, PythonScript, type PythonScriptConfig, type PythonScriptRequest, type PythonScriptResult, ReactiveSequence, Recovery, RegexExtract, type RegexExtractConfig, Registry, Repeat, type ResolveOptions, ResumePoint, type ResumePointConfig, RunOnce, RunningNode, SchemaRegistry, ScopedBlackboard, Selector, SemanticValidationError, Sequence, SequenceWithMemory, type SinkHandlerConfig, SoftAssert, StructureValidationError, type StructuredError, SubTree, SuccessNode, type TemplateLoaderOptions, type TemporalContext, type TickContext, type TimelineEntry, Timeout, type TokenProvider, type TreeDefinition, type TreeNode, type UploadFileRequest, type UploadFileResult, type ValidatedNodeConfiguration, ValidationError, ValidationErrors, type ValidationOptions, type ValidationResult, type VariableContext, WaitAction, type WaitForHumanTaskRequest, type WaitForHumanTaskResult, While, type WorkflowArgs, type WorkflowResult, YamlSyntaxError, clearPieceCache, createNodeSchema, createObservabilitySinkHandler, envTokenProvider, executePieceAction, extractVariables, getTemplateIds, hasTemplate, hasVariables, isDataRef, isPieceInstalled, listPieceActions, loadTemplate, loadTemplatesFromDirectory, loadTreeFromFile, loadTreeFromYaml, nodeConfigurationSchema, parseYaml, registerStandardNodes, resolveString, resolveValue, safeValidateConfiguration, schemaRegistry, semanticValidator, toYaml, treeDefinitionSchema, validateChildCount, validateChildCountRange, validateCompositeChildren, validateConfiguration, validateDecoratorChildren, validateTreeDefinition, validateYaml, validations, zodErrorToConfigurationError };