botinabox 2.5.3 → 2.6.0

package/bin/botinabox.mjs

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import('../dist/cli.js').then(m => m.main(process.argv.slice(2)));

package/dist/chat-pipeline-BWrtVqEP.d.ts

@@ -0,0 +1,652 @@
+import * as better_sqlite3 from 'better-sqlite3';
+import { I as InboundMessage } from './channel-06G0vbIn.js';
+import { C as ChatMessage } from './provider-DLGUfnNx.js';
+
+type HookHandler = (context: Record<string, unknown>) => Promise<void> | void;
+type Unsubscribe = () => void;
+interface HookOptions {
+    /** 0–100, default 50. Lower = runs first. */
+    priority?: number;
+    /** Auto-unsubscribe after first invocation. */
+    once?: boolean;
+    /** Only fire if context matches all filter key/value pairs. */
+    filter?: Record<string, unknown>;
+}
+interface HookRegistration {
+    event: string;
+    handler: HookHandler;
+    priority: number;
+    once: boolean;
+    filter?: Record<string, unknown>;
+    /** Internal auto-increment for stable sort within same priority */
+    id: number;
+}
+
+/**
+ * Priority-ordered event bus for decoupled inter-layer communication.
+ * Story 1.1 — handlers run in priority order, errors are isolated,
+ * and registrations are unsubscribable.
+ */
+declare class HookBus {
+    private readonly registrations;
+    private nextId;
+    register(event: string, handler: HookHandler, opts?: HookOptions): Unsubscribe;
+    emit(event: string, context: Record<string, unknown>): Promise<void>;
+    /** Emit synchronously (use only when async is not needed) */
+    emitSync(event: string, context: Record<string, unknown>): void;
+    hasListeners(event: string): boolean;
+    listRegistered(): string[];
+    /** Remove all handlers for an event, or all handlers if no event given */
+    clear(event?: string): void;
+}
+
+interface TableDefinition {
+    columns: Record<string, string>;
+    primaryKey?: string | string[];
+    tableConstraints?: string[];
+    relations?: Record<string, RelationDef>;
+    render?: string | ((rows: Row[]) => string);
+    outputFile?: string;
+    filter?: (rows: Row[]) => Row[];
+}
+interface RelationDef {
+    type: 'belongsTo' | 'hasMany';
+    table: string;
+    foreignKey: string;
+    references?: string;
+}
+interface EntityContextDef {
+    table: string;
+    directory: string;
+    slugColumn: string;
+    files: Record<string, EntityFileSpec>;
+    indexFile?: string;
+    /** Custom index render function. If omitted, a default listing is generated. */
+    indexRender?: (rows: Row[]) => string;
+    protectedFiles?: string[];
+    /** When true, this entity's data is never rendered into other entities' context files. */
+    protected?: boolean;
+    /** Enable at-rest encryption. Requires encryptionKey in Lattice options. */
+    encrypted?: boolean | {
+        columns: string[];
+    };
+}
+interface EntityFileSpec {
+    source: EntitySource;
+    render: string | ((rows: Row[]) => string);
+    junctionColumns?: string[];
+    omitIfEmpty?: boolean;
+}
+type EntitySource = {
+    type: 'self';
+} | {
+    type: 'hasMany';
+    table: string;
+    foreignKey: string;
+    filters?: Filter[];
+    softDelete?: boolean;
+    orderBy?: string;
+    limit?: number;
+} | {
+    type: 'manyToMany';
+    junctionTable: string;
+    localKey: string;
+    remoteKey: string;
+    remoteTable: string;
+    filters?: Filter[];
+    softDelete?: boolean;
+    orderBy?: string;
+    limit?: number;
+} | {
+    type: 'belongsTo';
+    table: string;
+    foreignKey: string;
+} | {
+    type: 'enriched';
+    include: Record<string, EntitySource>;
+} | {
+    type: 'custom';
+    resolve: (row: Row, adapter: SqliteAdapter) => Row[];
+};
+interface Filter {
+    col: string;
+    op: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'in' | 'isNull' | 'isNotNull';
+    val?: unknown;
+}
+interface QueryOptions {
+    where?: Record<string, unknown>;
+    filters?: Filter[];
+    orderBy?: string | Array<{
+        col: string;
+        dir: 'asc' | 'desc';
+    }>;
+    orderDir?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+type Row = Record<string, unknown>;
+type PkLookup = string | Record<string, unknown>;
+interface SqliteAdapter {
+    run(sql: string, params?: unknown[]): better_sqlite3.RunResult;
+    get<T = Row>(sql: string, params?: unknown[]): T | undefined;
+    all<T = Row>(sql: string, params?: unknown[]): T[];
+    tableInfo(table: string): TableInfoRow[];
+    invalidateTableCache(table: string): void;
+}
+interface TableInfoRow {
+    cid: number;
+    name: string;
+    type: string;
+    notnull: number;
+    dflt_value: unknown;
+    pk: number;
+}
+interface SeedItem {
+    table: string;
+    rows: Row[];
+    naturalKey?: string | string[];
+    junctions?: Array<{
+        table: string;
+        items: Array<Row>;
+    }>;
+    softDeleteMissing?: boolean;
+}
+
+declare class DataStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thin wrapper around Lattice that provides the botinabox DataStore API.
+ *
+ * Delegates all data operations to the latticesql package. Application-level
+ * events (task.created, run.completed, etc.) remain on the HookBus — they are
+ * emitted by orchestrator modules, not the data layer.
+ */
+declare class DataStore {
+    private lattice;
+    private readonly hooks;
+    private readonly outputDir;
+    private _initialized;
+    private readonly deferredStatements;
+    constructor(opts: {
+        dbPath: string;
+        outputDir?: string;
+        wal?: boolean;
+        hooks?: HookBus;
+    });
+    /**
+     * Register a table definition. Must be called before init().
+     *
+     * tableConstraints may contain both inline constraints (FOREIGN KEY, UNIQUE)
+     * and standalone SQL statements (CREATE INDEX). Standalone statements are
+     * deferred and executed after init() creates the tables.
+     */
+    define(name: string, def: TableDefinition): void;
+    /**
+     * Register an entity context definition for per-entity file rendering.
+     */
+    defineEntityContext(name: string, def: EntityContextDef): void;
+    init(opts?: {
+        migrations?: Array<{
+            version: string;
+            sql: string;
+        }>;
+    }): Promise<void>;
+    private assertInitialized;
+    insert(table: string, row: Row): Promise<Row>;
+    upsert(table: string, row: Row): Promise<Row>;
+    update(table: string, pk: PkLookup, changes: Row): Promise<Row>;
+    delete(table: string, pk: PkLookup): Promise<void>;
+    /**
+     * Get a single row by primary key.
+     * Returns undefined if not found (Lattice returns null).
+     */
+    get(table: string, pk: PkLookup): Promise<Row | undefined>;
+    query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    count(table: string, opts?: QueryOptions): Promise<number>;
+    link(junctionTable: string, row: Row): Promise<void>;
+    unlink(junctionTable: string, row: Row): Promise<void>;
+    migrate(migrations: Array<{
+        version: string;
+        sql: string;
+    }>): Promise<void>;
+    seed(items: SeedItem[]): Promise<void>;
+    render(): Promise<void>;
+    reconcile(): Promise<void>;
+    tableInfo(table: string): TableInfoRow[];
+    close(): void;
+    on(event: string, handler: (context: Record<string, unknown>) => void): void;
+}
+
+/**
+ * MessageStore — store-before-respond guarantee for all chat interactions.
+ * Story 7.1
+ *
+ * Every inbound message (with attachments) is stored BEFORE the bot responds.
+ * Every outbound message is stored BEFORE it is sent to the user.
+ * Storage confirmation is required before any response flows.
+ */
+
+interface StoredAttachment {
+    fileType: string;
+    filename?: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    contents?: string;
+    summary?: string;
+    url?: string;
+}
+interface StoreResult {
+    messageId: string;
+    attachmentIds: string[];
+}
+declare class MessageStore {
+    private db;
+    private hooks;
+    constructor(db: DataStore, hooks: HookBus);
+    /**
+     * Store an inbound message and its attachments.
+     * Must complete successfully before any bot response is generated.
+     */
+    storeInbound(msg: InboundMessage): Promise<StoreResult>;
+    /**
+     * Store an outbound message BEFORE sending it.
+     * Returns the message ID for confirmation tracking.
+     */
+    storeOutbound(opts: {
+        channel: string;
+        text: string;
+        threadId?: string;
+        agentId?: string;
+        agentSlug?: string;
+        taskId?: string;
+    }): Promise<string>;
+    /**
+     * Store an attachment linked to a message.
+     */
+    storeAttachment(messageId: string, att: StoredAttachment): Promise<string>;
+    /**
+     * Get recent messages in a thread for context building.
+     */
+    getThreadHistory(threadId: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Get recent outbound messages in a thread for redundancy checking.
+     */
+    getRecentOutbound(threadId: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Get recent messages in a channel (all threads combined).
+     * More reliable than getThreadHistory for DMs where thread_ids are inconsistent.
+     */
+    getChannelHistory(channel: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Get recent messages from a specific user across all threads.
+     */
+    getUserHistory(userId: string, channel: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Get attachments for a message.
+     */
+    getAttachments(messageId: string): Promise<Array<Record<string, unknown>>>;
+}
+
+/**
+ * ChatResponder — fast conversational layer with LLM-filtered responses.
+ * Story 7.2
+ *
+ * Provides rapid (<2s) conversational responses using a cheap LLM (Haiku).
+ * The responder has awareness of tools and capabilities but does NOT execute
+ * anything — it keeps the conversation going while work happens async.
+ *
+ * All outbound messages (direct, post-interpretation, task execution) are
+ * filtered through this layer for human readability and redundancy checking.
+ */
+
+interface ChatResponderConfig {
+    /** System prompt for the conversational responder */
+    systemPrompt?: string;
+    /** Max tokens for context window. Default: 4000 */
+    contextWindowTokens?: number;
+    /** Max recent outbound messages to check for redundancy. Default: 10 */
+    redundancyWindow?: number;
+    /** Model to use for responses. Default: 'fast' (resolved via ModelRouter) */
+    model?: string;
+    /** Caller-provided LLM call function */
+    llmCall: (params: {
+        model: string;
+        messages: ChatMessage[];
+        system?: string;
+        maxTokens?: number;
+    }) => Promise<{
+        content: string;
+    }>;
+}
+declare class ChatResponder {
+    private db;
+    private hooks;
+    private messageStore;
+    private readonly systemPrompt;
+    private readonly contextWindowTokens;
+    private readonly redundancyWindow;
+    private readonly model;
+    private readonly llmCall;
+    constructor(db: DataStore, hooks: HookBus, messageStore: MessageStore, config: ChatResponderConfig);
+    /**
+     * Generate a fast conversational response to an inbound message.
+     * Uses rolling context window from thread history.
+     */
+    respond(opts: {
+        messageBody: string;
+        threadId: string;
+        channel: string;
+        userName?: string;
+        capabilities?: string;
+        additionalContext?: string;
+    }): Promise<string>;
+    /**
+     * Filter any outbound message through the LLM for human readability.
+     * This is the single funnel ALL responses pass through.
+     */
+    filterResponse(text: string, context?: {
+        channel?: string;
+        threadId?: string;
+        source?: string;
+    }): Promise<string>;
+    /**
+     * Check if a candidate outbound message is redundant with recent messages.
+     * Returns true if the message should be suppressed.
+     */
+    isRedundant(text: string, threadId: string): Promise<boolean>;
+    /**
+     * Full send pipeline: check redundancy → filter → store → deliver.
+     * Returns the message ID, or undefined if suppressed as redundant.
+     */
+    sendResponse(opts: {
+        text: string;
+        channel: string;
+        threadId: string;
+        agentId?: string;
+        agentSlug?: string;
+        taskId?: string;
+        source?: string;
+        skipRedundancyCheck?: boolean;
+        skipFilter?: boolean;
+    }): Promise<string | undefined>;
+    /**
+     * Build a context window from thread history, trimmed to token limit.
+     *
+     * Only includes inbound (user) messages. Outbound (bot) messages are
+     * excluded to prevent the ack layer from mimicking prior verbose responses,
+     * which caused hallucinated system state and walls of text.
+     */
+    private buildContextWindow;
+}
+
+/**
+ * TriageRouter — content-based routing with deterministic-first resolution.
+ * Story 6.3
+ *
+ * Replaces the simple channel→agent binding with intelligent routing:
+ * 1. Keyword/regex rules evaluated first (deterministic, ~4ms)
+ * 2. LLM classification only for ambiguous messages (async, ~2-4s)
+ * 3. Ownership chain logged for every routing decision
+ *
+ * Key constraint: specialists return to triage, never to another specialist.
+ */
+
+interface RoutingRule {
+    /** Target agent slug */
+    agentSlug: string;
+    /** Keywords that trigger this rule (case-insensitive) */
+    keywords?: string[];
+    /** Regex patterns that trigger this rule */
+    patterns?: string[];
+    /** Priority — lower number wins ties. Default: 50 */
+    priority?: number;
+}
+interface RoutingDecision {
+    timestamp: string;
+    source: string;
+    target: string;
+    reason: string;
+    method: 'deterministic' | 'llm';
+    messageId?: string;
+    channel?: string;
+}
+interface TriageRouterConfig {
+    /** Static routing rules evaluated deterministically */
+    rules: RoutingRule[];
+    /** Fallback agent if no rule matches and LLM is unavailable */
+    fallbackAgent?: string;
+    /** Whether to use LLM for ambiguous messages. Default: true */
+    llmFallback?: boolean;
+    /** Log decisions to the database. Default: true */
+    persist?: boolean;
+}
+declare class TriageRouter {
+    private db;
+    private hooks;
+    private readonly rules;
+    private readonly fallbackAgent?;
+    private readonly llmFallback;
+    private readonly persist;
+    private readonly compiledRules;
+    constructor(db: DataStore, hooks: HookBus, config: TriageRouterConfig);
+    /**
+     * Route an inbound message to the best agent.
+     * Returns the agent slug and the routing decision.
+     */
+    route(msg: InboundMessage): Promise<{
+        agentSlug: string | undefined;
+        decision: RoutingDecision;
+    }>;
+    /**
+     * Query the ownership chain for a given message or channel.
+     */
+    getDecisionHistory(filter?: {
+        channel?: string;
+        limit?: number;
+    }): Promise<RoutingDecision[]>;
+    /**
+     * LLM classification — emits a hook for external LLM integration.
+     * Returns agent slug + reason, or undefined if LLM is unavailable.
+     */
+    private classifyWithLLM;
+    private buildDecision;
+    private logDecision;
+}
+
+/**
+ * MessageInterpreter — async structured extraction from messages.
+ * Story 7.3
+ *
+ * After every message is stored, the interpreter runs async to extract
+ * structured data types: tasks, memories, files, user context, and custom types.
+ *
+ * Uses a cheap LLM (Haiku) for classification and extraction.
+ * Pluggable extractors allow apps to add custom data types.
+ */
+
+interface ExtractedTask {
+    title: string;
+    description?: string;
+    dueDate?: string;
+    scheduled?: boolean;
+    priority?: number;
+}
+interface ExtractedMemory {
+    summary: string;
+    contents: string;
+    tags?: string[];
+    category?: string;
+}
+interface ExtractedFile {
+    filename: string;
+    fileType: string;
+    contents: string;
+    summary: string;
+}
+interface ExtractedUserContext {
+    trait: string;
+    value: string;
+}
+interface InterpretationResult {
+    messageId: string;
+    tasks: ExtractedTask[];
+    memories: ExtractedMemory[];
+    files: ExtractedFile[];
+    userContext: ExtractedUserContext[];
+    custom: Record<string, unknown[]>;
+    isTaskRequest: boolean;
+}
+type LLMCallFn = (params: {
+    model: string;
+    messages: ChatMessage[];
+    system?: string;
+    maxTokens?: number;
+}) => Promise<{
+    content: string;
+}>;
+/**
+ * Pluggable extractor interface for custom data types.
+ */
+interface Extractor {
+    readonly type: string;
+    extract(message: {
+        body: string;
+        attachments?: Array<Record<string, unknown>>;
+    }, llmCall: LLMCallFn): Promise<unknown[]>;
+}
+interface MessageInterpreterConfig {
+    /** Additional custom extractors beyond built-in ones */
+    extractors?: Extractor[];
+    /** Model for interpretation LLM calls. Default: 'fast' */
+    model?: string;
+    /** LLM call function */
+    llmCall: LLMCallFn;
+    /** Auto-create tasks from extracted tasks. Default: false */
+    autoCreateTasks?: boolean;
+}
+declare class MessageInterpreter {
+    private db;
+    private hooks;
+    private readonly extractors;
+    private readonly model;
+    private readonly llmCall;
+    private readonly autoCreateTasks;
+    constructor(db: DataStore, hooks: HookBus, config: MessageInterpreterConfig);
+    /**
+     * Interpret a stored message asynchronously.
+     * Extracts tasks, memories, files, user context, and custom types.
+     */
+    interpret(messageId: string): Promise<InterpretationResult>;
+    /**
+     * Extract structured data from message text using LLM.
+     */
+    private extractWithLLM;
+}
+
+/**
+ * ChatPipeline — configurable 6-layer chat orchestration.
+ * Story 7.4
+ *
+ * Replaces duplicated handler code across apps with a single configurable
+ * pipeline. Apps provide: system prompt, routing rules, LLM call function,
+ * and optional message filter. Everything else is framework-level.
+ *
+ * Layers:
+ *   1. Dedup + Storage (MessageStore)
+ *   2. Fast Response (ChatResponder)
+ *   3. Interpretation (MessageInterpreter)
+ *   4. Post-Interpretation Response
+ *   5. Task Dispatch (TriageRouter)
+ *   6. Task Execution Response
+ */
+
+interface ChatPipelineConfig {
+    /** LLM call function for chat responses and interpretation */
+    llmCall: ChatResponderConfig['llmCall'];
+    /** System prompt for the conversational responder */
+    systemPrompt: string;
+    /** Agent routing rules for task dispatch */
+    routingRules: RoutingRule[];
+    /** Default agent when no rule matches */
+    fallbackAgent: string;
+    /** Optional message filter — return false to ignore a message */
+    messageFilter?: (msg: InboundMessage) => boolean;
+    /** Optional capabilities description for the responder */
+    capabilities?: string;
+    /** Channel this pipeline handles (default: 'slack') */
+    channel?: string;
+    /** Custom extractors for MessageInterpreter */
+    extractors?: Extractor[];
+    /** Dedup window in ms (default: 300_000 = 5 min) */
+    dedupWindowMs?: number;
+    /** Model for fast responses (default: 'fast') */
+    model?: string;
+    /** Enable LLM fallback routing (default: false) */
+    llmRouting?: boolean;
+    /** TaskQueue instance — required for task dispatch */
+    tasks: {
+        create(task: Record<string, unknown>): Promise<string>;
+        update(id: string, changes: Record<string, unknown>): Promise<void>;
+        get(id: string): Promise<Record<string, unknown> | undefined>;
+    };
+    /** WakeupQueue instance — required for agent waking */
+    wakeups: {
+        enqueue(agentId: string, source: string, context?: Record<string, unknown>): Promise<string>;
+    };
+}
+declare class ChatPipeline {
+    private db;
+    private hooks;
+    readonly messageStore: MessageStore;
+    readonly responder: ChatResponder;
+    readonly interpreter: MessageInterpreter;
+    readonly router: TriageRouter;
+    private readonly channel;
+    private readonly messageFilter?;
+    private readonly capabilities?;
+    private readonly dedupWindowMs;
+    private readonly tasks;
+    private readonly wakeups;
+    private readonly threadChannelMap;
+    /** Last dispatch promise — exposed for testing. */
+    lastDispatch: Promise<void>;
+    constructor(db: DataStore, hooks: HookBus, config: ChatPipelineConfig);
+    /**
+     * Resolve the Slack channel ID for a thread (for response delivery).
+     */
+    resolveChannel(threadId: string, taskId?: string): Promise<string | undefined>;
+    /**
+     * Register the 6-layer pipeline on the HookBus.
+     */
+    private registerHandlers;
+    /**
+     * Check and record message dedup (SHA256 hash, configurable window).
+     */
+    private isDuplicate;
+    /**
+     * Async interpretation + task dispatch (Layers 3-5).
+     *
+     * ALWAYS creates a task programmatically — task creation does not depend
+     * on LLM classification. Interpretation enriches but never gates dispatch.
+     */
+    private interpretAndDispatch;
+    /**
+     * Programmatic task creation — guaranteed, no LLM dependency.
+     */
+    private guaranteedTaskDispatch;
+    /**
+     * Route and dispatch extracted tasks.
+     */
+    private dispatchTasks;
+    /**
+     * Resolve Slack channel ID from thread_task_map or in-memory fallback.
+     */
+    private resolveChannelId;
+    /**
+     * Build human-readable interpretation summary.
+     */
+    private buildSummary;
+}
+
+export { type ChatResponderConfig as C, DataStore as D, type Extractor as E, type Filter as F, HookBus as H, type InterpretationResult as I, type LLMCallFn as L, MessageStore as M, type PkLookup as P, type QueryOptions as Q, type RelationDef as R, type SeedItem as S, type TableDefinition as T, type Unsubscribe as U, ChatResponder as a, MessageInterpreter as b, ChatPipeline as c, type ChatPipelineConfig as d, DataStoreError as e, type EntityContextDef as f, type EntityFileSpec as g, type EntitySource as h, type ExtractedFile as i, type ExtractedMemory as j, type ExtractedTask as k, type ExtractedUserContext as l, type HookHandler as m, type HookOptions as n, type HookRegistration as o, type MessageInterpreterConfig as p, type RoutingDecision as q, type RoutingRule as r, type Row as s, type SqliteAdapter as t, type StoreResult as u, type StoredAttachment as v, type TableInfoRow as w, TriageRouter as x, type TriageRouterConfig as y };

package/dist/index.d.ts

@@ -950,6 +950,12 @@ interface ToolContext {
     /** Resolve a relative file path to an absolute path (environment-aware). */
     resolveFilePath?: (path: string) => string;
 }
+interface ContextFile {
+    /** Absolute path, used as the `path` attribute in the wrapped XML tag. */
+    path: string;
+    /** Raw file contents (UTF-8). The engine does not read the filesystem itself. */
+    content: string;
+}
 interface ExecutionEngineConfig {
     /** Anthropic client instance */
     client: {
@@ -985,6 +991,23 @@ interface ExecutionEngineConfig {
     includeSystemContext?: boolean;
     /** Resolve file paths from DB-relative to absolute (for cross-environment support). */
     resolveFilePath?: (path: string) => string;
+    /**
+     * Optional per-dispatch context resolver. Called once per task pickup with
+     * the resolved agent and task rows. Returned files are wrapped in
+     * `<file path="...">...</file>` XML tags and inserted into the system
+     * prompt between the static `buildSystemContext` block and the tool
+     * listing. Intended for apps that want to inject per-agent or per-project
+     * rendered context (rules, playbooks, agent definitions) that is not
+     * already covered by `buildSystemContext`.
+     *
+     * The resolver owns all filesystem / database lookups — the engine does
+     * not touch the disk. If the resolver throws, the task fails loudly per
+     * Rule-16-style fail-loud semantics; there is no silent fallback.
+     */
+    resolveContextFiles?: (ctx: {
+        agent: Record<string, unknown>;
+        task: Record<string, unknown>;
+    }) => Promise<ContextFile[]> | ContextFile[];
 }
 declare function registerExecutionEngine(opts: {
     db: DataStore;
@@ -1663,6 +1686,27 @@ declare class ApiExecutionAdapter {
     }>;
 }
 
+/**
+ * Inputs to the CLI argument builder. Kept as a separate type so the
+ * pure arg-construction function is unit-testable without spawning a process.
+ */
+interface CliArgBuildInput {
+    prompt: string;
+    skipPermissions?: boolean;
+    sessionId?: string;
+    settings?: string;
+    appendSystemPrompt?: string;
+    addDirs?: string[];
+    extraArgs?: string[];
+}
+/**
+ * Build the argv array passed to the `claude` binary.
+ *
+ * Order matters for the `claude` CLI: flags come first, then `--print` with
+ * the prompt as the final positional argument. This function exists so the
+ * argv shape can be asserted in tests without a real subprocess.
+ */
+declare function buildCliArgs(input: CliArgBuildInput): string[];
 declare class CliExecutionAdapter {
     readonly type = "cli";
     execute(ctx: {
@@ -1677,6 +1721,25 @@ declare class CliExecutionAdapter {
             description?: string;
             context?: string;
         };
+        /**
+         * Optional Claude Code session UUID. When provided, passed as `--session-id`
+         * so the same UUID on subsequent calls resumes the same conversation.
+         * Callers typically derive this deterministically from a stable conversation
+         * key (e.g. thread identifier) so multi-turn exchanges maintain history.
+         */
+        sessionId?: string;
+        /**
+         * Value for `--settings`. Accepts a JSON string or a path to a settings
+         * file. Use this to override settings like `autoMemoryDirectory` without
+         * mutating the caller's global config.
+         */
+        settings?: string;
+        /** Value for `--append-system-prompt`. */
+        appendSystemPrompt?: string;
+        /** Additional directories passed via `--add-dir`. */
+        addDirs?: string[];
+        /** Extra CLI flags appended before the positional prompt. */
+        extraArgs?: string[];
         logPath?: string;
         onLog?: (stream: string, chunk: string) => void;
         abortSignal?: AbortSignal;
@@ -2300,4 +2363,4 @@ declare function isLoginRequired(stdout: string): boolean;
 /** Rewrite local image paths to prevent CLI auto-embedding as vision content. */
 declare function deactivateLocalImagePaths(prompt: string): string;
 
-export { AGENT_STATUSES, type AgentConfig, type AgentDefinition, type AgentFilter, type AgentRecord, AgentRegistry, type AgentStatus, ApiExecutionAdapter, type ApprovalResponse, type ApprovalStatus, AuditEmitter, type AuditEvent, BackupManager, type BotConfig, BreakerState, type BudgetCheck, type BudgetConfig, BudgetController, CORE_MIGRATIONS, ChannelAdapter, ChannelRegistry, ChannelRegistryError, type ChatConfig, ChatMessage, ChatPipelineV2, type ChatPipelineV2Config, ChatResponder, ChatResponderConfig, ChatSessionManager, CircuitBreaker, type CircuitBreakerConfig, CliExecutionAdapter, type ColumnValidator, ColumnValidatorImpl, type ConfigLoadError, type ConfigLoadResult, ConnectorConfig, DEFAULTS, DEFAULT_CONFIG, type DataConfig, DataStore, type DefaultLLMCallConfig, DeterministicAdapter, type DeterministicConfig, type DomainEntityContextOptions, type DomainSchemaOptions, DriftGate, EVENTS, type EntityColumnDef, type EntityConfig, type ExecutionAdapter, type ExecutionConfig, type ExecutionEngineConfig, Extractor, type FeedbackEntry, type GateFinding, type GateInput, type GateResult, GateRunner, type GateVerdict, GovernanceGate, HealthStatus, HookBus, InboundMessage, LLMProvider, LearningPipeline, type LearningPipelineConfig, type LoopDetection, LoopDetector, type LoopDetectorConfig, LoopType, MAX_CHAIN_DEPTH, MessageInterpreter, MessagePipeline, MessageStore, type ModelConfig, ModelInfo, ModelRouter, NdjsonLogger, NotificationQueue, type PackageMigration, type PackageUpdate, type ParsedStream, type PermissionPrompt, type PermissionProvider, PermissionRelay, type PermissionRelayConfig, type PlaybookEntry, ProviderRegistry, QAGate, QualityGate, RUN_STATUSES, type RenderConfig, ResolvedModel, type RetryPolicy, type RoutingConfig, type RunContext, RunManager, type RunResult, type RunStatus, type SafetyConfig, type SanitizerOptions, type Schedule, type ScheduleDef, Scheduler, type SchemaError, type SecretInput, type SecretMeta, SecretStore, type SecurityConfig, SessionKey, SessionManager, type SkillEntry, type StepRef, type SystemContextOptions, TASK_STATUSES, type TaskDefinition, TaskQueue, type TaskRecord, type TaskStatus, TokenUsage, type ToolContext, type ToolDefinition, type ToolHandler, UpdateChecker, type UpdateConfig, UpdateManager, type UpdateManifest, type UsageSummary, type User, type UserInput, UserRegistry, WakeupQueue, type WorkflowConfigEntry, type WorkflowDefinition$1 as WorkflowDefinition, WorkflowEngine, type WorkflowRunRecord, type WorkflowRunStatus, type WorkflowStep$1 as WorkflowStep, type WorkflowStepConfig, type WorkflowTrigger, _resetConfig, addTaskCommentTool, areDependenciesMet, autoUpdate, buildAgentBindings, buildChainOrigin, buildProcessEnv, buildSystemContext, cancelTaskTool, checkAllowlist, checkChainDepth, checkMentionGate, chunkText, classifyUpdate, compareVersions, coordinatorTools, createAgentTool, createConfigRevision, createDefaultLLMCall, createProjectTool, deactivateLocalImagePaths, defineCoreEntityContexts, defineCoreTables, defineDomainEntityContexts, defineDomainTables, detectCycle, discoverChannels, discoverProviders, dispatchTaskTool, formatText, getActiveTasksTool, getAgentDetailTool, getAgentStatusTool, getConfig, getSystemStatusTool, getTaskStatusTool, initConfig, interpolate, interpolateEnv, isLoginRequired, isMaxTurns, listAgentsTool, listFilesTool, listProjectsTool, loadConfig, nativeTools, parseClaudeStream, parseVersion, readConversationTool, readFileTool, reassignTaskTool, registerExecutionEngine, registerFileTool, resolveAgent, runPackageMigrations, sanitize, searchConversationTool, sendFileTool, sendMessageTool, topologicalSort, truncateAtWord, validateConfig };
+export { AGENT_STATUSES, type AgentConfig, type AgentDefinition, type AgentFilter, type AgentRecord, AgentRegistry, type AgentStatus, ApiExecutionAdapter, type ApprovalResponse, type ApprovalStatus, AuditEmitter, type AuditEvent, BackupManager, type BotConfig, BreakerState, type BudgetCheck, type BudgetConfig, BudgetController, CORE_MIGRATIONS, ChannelAdapter, ChannelRegistry, ChannelRegistryError, type ChatConfig, ChatMessage, ChatPipelineV2, type ChatPipelineV2Config, ChatResponder, ChatResponderConfig, ChatSessionManager, CircuitBreaker, type CircuitBreakerConfig, type CliArgBuildInput, CliExecutionAdapter, type ColumnValidator, ColumnValidatorImpl, type ConfigLoadError, type ConfigLoadResult, ConnectorConfig, DEFAULTS, DEFAULT_CONFIG, type DataConfig, DataStore, type DefaultLLMCallConfig, DeterministicAdapter, type DeterministicConfig, type DomainEntityContextOptions, type DomainSchemaOptions, DriftGate, EVENTS, type EntityColumnDef, type EntityConfig, type ExecutionAdapter, type ExecutionConfig, type ExecutionEngineConfig, Extractor, type FeedbackEntry, type GateFinding, type GateInput, type GateResult, GateRunner, type GateVerdict, GovernanceGate, HealthStatus, HookBus, InboundMessage, LLMProvider, LearningPipeline, type LearningPipelineConfig, type LoopDetection, LoopDetector, type LoopDetectorConfig, LoopType, MAX_CHAIN_DEPTH, MessageInterpreter, MessagePipeline, MessageStore, type ModelConfig, ModelInfo, ModelRouter, NdjsonLogger, NotificationQueue, type PackageMigration, type PackageUpdate, type ParsedStream, type PermissionPrompt, type PermissionProvider, PermissionRelay, type PermissionRelayConfig, type PlaybookEntry, ProviderRegistry, QAGate, QualityGate, RUN_STATUSES, type RenderConfig, ResolvedModel, type RetryPolicy, type RoutingConfig, type RunContext, RunManager, type RunResult, type RunStatus, type SafetyConfig, type SanitizerOptions, type Schedule, type ScheduleDef, Scheduler, type SchemaError, type SecretInput, type SecretMeta, SecretStore, type SecurityConfig, SessionKey, SessionManager, type SkillEntry, type StepRef, type SystemContextOptions, TASK_STATUSES, type TaskDefinition, TaskQueue, type TaskRecord, type TaskStatus, TokenUsage, type ToolContext, type ToolDefinition, type ToolHandler, UpdateChecker, type UpdateConfig, UpdateManager, type UpdateManifest, type UsageSummary, type User, type UserInput, UserRegistry, WakeupQueue, type WorkflowConfigEntry, type WorkflowDefinition$1 as WorkflowDefinition, WorkflowEngine, type WorkflowRunRecord, type WorkflowRunStatus, type WorkflowStep$1 as WorkflowStep, type WorkflowStepConfig, type WorkflowTrigger, _resetConfig, addTaskCommentTool, areDependenciesMet, autoUpdate, buildAgentBindings, buildChainOrigin, buildCliArgs, buildProcessEnv, buildSystemContext, cancelTaskTool, checkAllowlist, checkChainDepth, checkMentionGate, chunkText, classifyUpdate, compareVersions, coordinatorTools, createAgentTool, createConfigRevision, createDefaultLLMCall, createProjectTool, deactivateLocalImagePaths, defineCoreEntityContexts, defineCoreTables, defineDomainEntityContexts, defineDomainTables, detectCycle, discoverChannels, discoverProviders, dispatchTaskTool, formatText, getActiveTasksTool, getAgentDetailTool, getAgentStatusTool, getConfig, getSystemStatusTool, getTaskStatusTool, initConfig, interpolate, interpolateEnv, isLoginRequired, isMaxTurns, listAgentsTool, listFilesTool, listProjectsTool, loadConfig, nativeTools, parseClaudeStream, parseVersion, readConversationTool, readFileTool, reassignTaskTool, registerExecutionEngine, registerFileTool, resolveAgent, runPackageMigrations, sanitize, searchConversationTool, sendFileTool, sendMessageTool, topologicalSort, truncateAtWord, validateConfig };

package/dist/index.js

@@ -5555,6 +5555,29 @@ function extractOutput(ndjsonContent) {
 }
 
 // src/core/orchestrator/adapters/cli-adapter.ts
+function buildCliArgs(input) {
+  const args = [];
+  if (input.skipPermissions) {
+    args.push("--dangerously-skip-permissions");
+  }
+  if (input.sessionId) {
+    args.push("--session-id", input.sessionId);
+  }
+  if (input.settings) {
+    args.push("--settings", input.settings);
+  }
+  if (input.appendSystemPrompt) {
+    args.push("--append-system-prompt", input.appendSystemPrompt);
+  }
+  if (input.addDirs && input.addDirs.length > 0) {
+    args.push("--add-dir", ...input.addDirs);
+  }
+  if (input.extraArgs && input.extraArgs.length > 0) {
+    args.push(...input.extraArgs);
+  }
+  args.push("--print", input.prompt);
+  return args;
+}
 var CliExecutionAdapter = class {
   type = "cli";
   async execute(ctx) {
@@ -5567,16 +5590,16 @@ var CliExecutionAdapter = class {
       }
     }
     const skipPermissions = ctx.agent.skip_permissions ?? config["skip_permissions"] ?? false;
-    const args = [];
-    if (skipPermissions) {
-      args.push("--dangerously-skip-permissions");
-    }
-    const prompt = [
-      ctx.task.title,
-      ctx.task.description,
-      ctx.task.context
-    ].filter(Boolean).join("\n\n");
-    args.push("--print", prompt);
+    const prompt = [ctx.task.title, ctx.task.description, ctx.task.context].filter(Boolean).join("\n\n");
+    const args = buildCliArgs({
+      prompt,
+      skipPermissions,
+      sessionId: ctx.sessionId,
+      settings: ctx.settings,
+      appendSystemPrompt: ctx.appendSystemPrompt,
+      addDirs: ctx.addDirs,
+      extraArgs: ctx.extraArgs
+    });
     const child = spawnProcess("claude", args, { cwd });
     const stdoutChunks = [];
     let logStream = null;
@@ -6417,6 +6440,12 @@ var GateRunner = class {
 };
 
 // src/core/orchestrator/execution-engine.ts
+function formatContextFilesBlock(files) {
+  if (!files || files.length === 0) return "";
+  return files.map((f) => `<file path="${f.path}">
+${f.content}
+</file>`).join("\n\n");
+}
 async function registerExecutionEngine(opts) {
   const { db, hooks, runs, config } = opts;
   const model = config.model ?? "claude-sonnet-4-20250514";
@@ -6445,6 +6474,8 @@ async function registerExecutionEngine(opts) {
     }
     const prompt = task.description ?? task.title ?? "";
     try {
+      const contextFiles = config.resolveContextFiles ? await config.resolveContextFiles({ agent, task }) : [];
+      const contextFilesBlock = formatContextFilesBlock(contextFiles);
       const toolListing = toolDefs.length > 0 ? `
 ## Available Tools
 ${toolDefs.map((t) => `- **${t.name}**: ${t.description}`).join("\n")}
@@ -6454,6 +6485,8 @@ Use your tools to take action. Do NOT describe what you would do \u2014 call the
         `You are ${agent.name}, an AI agent with role: ${agent.role}.`,
         systemContext ? `
 ${systemContext}` : "",
+        contextFilesBlock ? `
+${contextFilesBlock}` : "",
         toolListing,
         config.systemPromptSuffix ?? ""
       ].filter(Boolean).join("\n");
@@ -7535,6 +7568,7 @@ export {
   autoUpdate,
   buildAgentBindings,
   buildChainOrigin,
+  buildCliArgs,
   buildProcessEnv,
   buildSystemContext,
   cancelTaskTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botinabox",
-  "version": "2.5.3",
+  "version": "2.6.0",
   "description": "Bot in a Box — framework for building multi-agent bots",
   "type": "module",
   "main": "./dist/index.js",