botinabox 2.9.1 → 2.9.3

package/dist/core/orchestrator/learning-pipeline.d.ts

@@ -0,0 +1,112 @@
+/**
+ * LearningPipeline — turns execution experience into durable knowledge.
+ * Story 6.5
+ *
+ * Promotion ladder:
+ *   Execution → Feedback (structured capture)
+ *     → 3+ similar → Playbook (generalized rule)
+ *       → 3+ projects → Skill (executable behavior)
+ *         → Agent-Skill Matrix → Per-Agent Context
+ *
+ * Two-axis evaluation:
+ *   - Accuracy: was the output correct?
+ *   - Efficiency: how fast / how many tokens?
+ */
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+export interface FeedbackEntry {
+    agentId: string;
+    userId?: string;
+    taskId?: string;
+    issue: string;
+    rootCause?: string;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    repeatable: boolean;
+    accuracyScore?: number;
+    efficiencyScore?: number;
+    tags?: string[];
+}
+export interface PlaybookEntry {
+    pattern: string;
+    rule: string;
+    feedbackIds: string[];
+    projectScoped: boolean;
+    clientId?: string;
+    agentIds?: string[];
+}
+export interface SkillEntry {
+    name: string;
+    slug: string;
+    description?: string;
+    behavior: string;
+    sourcePlaybookIds: string[];
+    category?: string;
+}
+export interface LearningPipelineConfig {
+    /** Feedback count threshold for playbook promotion. Default: 3 */
+    playbookThreshold?: number;
+    /** Project count threshold for skill promotion. Default: 3 */
+    skillThreshold?: number;
+    /** Auto-promote when thresholds are met. Default: false */
+    autoPromote?: boolean;
+}
+export declare class LearningPipeline {
+    private db;
+    private hooks;
+    private readonly playbookThreshold;
+    private readonly skillThreshold;
+    private readonly autoPromote;
+    constructor(db: DataStore, hooks: HookBus, config?: LearningPipelineConfig);
+    /**
+     * Capture a structured feedback record from an execution.
+     */
+    captureFeedback(entry: FeedbackEntry): Promise<string>;
+    /**
+     * Get all feedback records, optionally filtered.
+     */
+    listFeedback(filter?: {
+        agentId?: string;
+        userId?: string;
+        severity?: string;
+        repeatable?: boolean;
+    }): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Check if feedback records with similar issues should be promoted to a playbook.
+     * Groups by issue text similarity (exact match for now).
+     */
+    checkPlaybookPromotion(issue: string): Promise<string | undefined>;
+    /**
+     * Manually create a playbook from a set of feedback records.
+     */
+    promoteToPlaybook(entry: PlaybookEntry): Promise<string>;
+    /**
+     * List playbooks, optionally filtered.
+     */
+    listPlaybooks(filter?: {
+        projectScoped?: boolean;
+    }): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Check if a playbook should be promoted to a skill.
+     * A playbook becomes a skill when it works across multiple projects
+     * (indicated by being referenced by agents in different contexts).
+     */
+    checkSkillPromotion(playbookId: string): Promise<string | undefined>;
+    /**
+     * Manually promote a playbook to a reusable skill.
+     */
+    promoteToSkill(entry: SkillEntry): Promise<string>;
+    /**
+     * Assign a skill to an agent.
+     */
+    assignSkill(agentId: string, skillId: string): Promise<void>;
+    /**
+     * Get learning metrics for an agent.
+     */
+    getMetrics(agentId: string): Promise<{
+        feedbackCount: number;
+        avgAccuracy: number | null;
+        avgEfficiency: number | null;
+        playbookCount: number;
+        skillCount: number;
+    }>;
+}

package/dist/core/orchestrator/loop-detector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * LoopDetector — pattern-based loop detection for agent routing.
+ * Story 6.2
+ *
+ * Complements chain-guard's depth limit with active pattern detection:
+ * - Self-loop: agent routes a task back to itself
+ * - Ping-pong: two agents bounce tasks between each other (A→B→A→B)
+ * - Blocked re-entry: a task re-enters the system after being blocked
+ */
+import type { DataStore } from '../data/data-store.js';
+export declare enum LoopType {
+    SELF_LOOP = "self_loop",
+    PING_PONG = "ping_pong",
+    BLOCKED_REENTRY = "blocked_reentry"
+}
+export interface LoopDetection {
+    type: LoopType;
+    agents: string[];
+    taskId: string;
+    chainOriginId?: string;
+    message: string;
+}
+export interface LoopDetectorConfig {
+    /** Number of recent followup records to scan. Default: 10 */
+    windowSize?: number;
+    /** Minimum repetitions to confirm ping-pong. Default: 2 */
+    pingPongThreshold?: number;
+}
+export declare class LoopDetector {
+    private db;
+    private readonly windowSize;
+    private readonly pingPongThreshold;
+    constructor(db: DataStore, config?: LoopDetectorConfig);
+    /**
+     * Check for loops before creating a followup task.
+     * Returns a LoopDetection if a loop pattern is found, undefined otherwise.
+     */
+    check(sourceAgentId: string, targetAgentId: string, taskId: string, chainOriginId?: string): Promise<LoopDetection | undefined>;
+    /**
+     * Check if an agent is routing to itself.
+     */
+    private checkSelfLoop;
+    /**
+     * Check if a previously blocked task is being re-entered.
+     */
+    private checkBlockedReentry;
+    /**
+     * Check for A→B→A→B ping-pong by scanning recent tasks in the chain.
+     */
+    private checkPingPong;
+}

package/dist/core/orchestrator/ndjson-logger.d.ts

@@ -0,0 +1,6 @@
+export declare class NdjsonLogger {
+    private logPath;
+    constructor(logPath: string);
+    log(stream: 'stdout' | 'stderr', chunk: string): void;
+    close(): void;
+}

package/dist/core/orchestrator/permission-relay.d.ts

@@ -0,0 +1,72 @@
+/**
+ * PermissionRelay — remote approval for unattended agent execution.
+ * Story 6.6
+ *
+ * When an agent needs human approval but the operator is away:
+ * 1. Post the approval prompt to a messaging platform (Slack, Discord, etc.)
+ * 2. Poll for response (approve/deny)
+ * 3. Relay the decision back to the agent
+ *
+ * Dual approval: local terminal + remote messaging. First response wins.
+ * Race condition handled by atomic state transition.
+ */
+import type { HookBus } from '../hooks/hook-bus.js';
+export type ApprovalStatus = 'pending' | 'approved' | 'denied' | 'expired';
+export interface PermissionPrompt {
+    id: string;
+    agentId: string;
+    action: string;
+    context?: string;
+    requestedAt: string;
+    expiresAt?: string;
+}
+export interface ApprovalResponse {
+    promptId: string;
+    status: 'approved' | 'denied';
+    respondedBy: string;
+    respondedAt: string;
+    comment?: string;
+}
+/**
+ * Provider interface — implement for each messaging platform.
+ */
+export interface PermissionProvider {
+    readonly id: string;
+    /** Post an approval request, return a handle for polling. */
+    sendPrompt(prompt: PermissionPrompt): Promise<string>;
+    /** Check for a response. Returns undefined if still pending. */
+    pollResponse(handle: string): Promise<ApprovalResponse | undefined>;
+    /** Cancel a pending prompt (e.g. after local approval). */
+    cancelPrompt(handle: string): Promise<void>;
+}
+export interface PermissionRelayConfig {
+    /** Registered providers (e.g. Slack, Discord adapters) */
+    providers: PermissionProvider[];
+    /** Poll interval in ms. Default: 5000 */
+    pollIntervalMs?: number;
+    /** Timeout for pending approvals in ms. Default: 300_000 (5 min) */
+    timeoutMs?: number;
+}
+export declare class PermissionRelay {
+    private hooks;
+    private readonly providers;
+    private readonly pollIntervalMs;
+    private readonly timeoutMs;
+    private readonly pending;
+    constructor(hooks: HookBus, config: PermissionRelayConfig);
+    /**
+     * Request approval from all configured providers.
+     * Returns when the first provider responds (approve or deny).
+     */
+    requestApproval(prompt: PermissionPrompt): Promise<ApprovalResponse>;
+    /**
+     * Provide a local approval (from terminal).
+     * Resolves the pending request and cancels remote providers.
+     */
+    approveLocally(promptId: string, approved: boolean): Promise<void>;
+    /**
+     * Get all pending approval requests.
+     */
+    getPending(): PermissionPrompt[];
+    private cancelOtherProviders;
+}

package/dist/core/orchestrator/run-manager.d.ts

@@ -0,0 +1,31 @@
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+import type { CircuitBreaker } from './circuit-breaker.js';
+export declare class RunManager {
+    private db;
+    private hooks;
+    private config?;
+    private locks;
+    private orphanTimer;
+    private readonly staleThresholdMs;
+    private circuitBreaker?;
+    constructor(db: DataStore, hooks: HookBus, config?: {
+        staleThresholdMs?: number;
+        maxBackoffMs?: number;
+    } | undefined);
+    /**
+     * Attach a CircuitBreaker to prevent retries on broken agents.
+     */
+    setCircuitBreaker(cb: CircuitBreaker): void;
+    isLocked(agentId: string): boolean;
+    startRun(agentId: string, taskId: string, adapter?: string): Promise<string>;
+    finishRun(runId: string, result: {
+        exitCode: number;
+        output?: string;
+        costCents?: number;
+        usage?: unknown;
+    }): Promise<void>;
+    reapOrphans(): Promise<void>;
+    startOrphanReaper(intervalMs?: number): void;
+    stopOrphanReaper(): void;
+}

package/dist/core/orchestrator/scheduler.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Scheduler — database-backed job scheduling with cron expressions.
+ *
+ * Supports one-time and recurring schedules. When a schedule fires,
+ * it emits the schedule's `action` as a hook event with the
+ * `action_config` payload. Consumers subscribe to handle the action.
+ *
+ * Supports one-time and recurring use cases.
+ */
+import type { DataStore } from "../data/data-store.js";
+import type { HookBus } from "../hooks/hook-bus.js";
+import type { CircuitBreaker } from "./circuit-breaker.js";
+export interface ScheduleDef {
+    name: string;
+    description?: string;
+    /** Cron expression for recurring schedules */
+    cron?: string;
+    /** ISO 8601 datetime for one-time schedules */
+    runAt?: string;
+    /** Hook event name to emit when fired */
+    action: string;
+    /** JSON-serializable payload passed to the hook */
+    actionConfig?: Record<string, unknown>;
+    timezone?: string;
+}
+export interface Schedule {
+    id: string;
+    name: string;
+    description: string | null;
+    type: "one_time" | "recurring";
+    cron: string | null;
+    run_at: string | null;
+    timezone: string;
+    enabled: number;
+    action: string;
+    action_config: string;
+    last_fired_at: string | null;
+    next_fire_at: string | null;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+export declare class Scheduler {
+    private db;
+    private hooks;
+    private timer;
+    private breaker?;
+    constructor(db: DataStore, hooks: HookBus);
+    /** Wire a CircuitBreaker for connector.sync actions. */
+    setCircuitBreaker(cb: CircuitBreaker): void;
+    /**
+     * Start the scheduler. Computes initial next_fire_at for schedules
+     * that don't have one, then polls for due schedules.
+     */
+    start(pollIntervalMs?: number): Promise<void>;
+    stop(): void;
+    /** Check for and fire due schedules. */
+    tick(): Promise<void>;
+    /** Register a new schedule. */
+    register(def: ScheduleDef): Promise<string>;
+    /** Update an existing schedule. */
+    update(id: string, changes: Partial<Pick<ScheduleDef, "name" | "cron" | "runAt" | "action" | "actionConfig" | "timezone" | "description">> & {
+        enabled?: boolean;
+    }): Promise<void>;
+    /** Soft-delete a schedule. */
+    unregister(id: string): Promise<void>;
+    /** List schedules, optionally filtered. */
+    list(filter?: {
+        enabled?: boolean;
+        action?: string;
+    }): Promise<Schedule[]>;
+    /** Compute next_fire_at for any enabled schedule missing it. */
+    private initializeNextFireTimes;
+}

package/dist/core/orchestrator/secret-store.d.ts

@@ -0,0 +1,57 @@
+import type { DataStore } from "../data/data-store.js";
+import type { HookBus } from "../hooks/hook-bus.js";
+export interface SecretInput {
+    name: string;
+    type?: string;
+    environment?: string;
+    value?: string;
+    location?: string;
+    description?: string;
+    rotation_schedule?: string;
+    expires_at?: string;
+    notes?: string;
+    org_id?: string;
+}
+export interface SecretMeta {
+    id: string;
+    org_id: string | null;
+    name: string;
+    type: string;
+    environment: string;
+    location: string | null;
+    description: string | null;
+    rotation_schedule: string | null;
+    expires_at: string | null;
+    notes: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export declare class SecretStore {
+    private readonly db;
+    private readonly hooks;
+    private readonly encKey;
+    /**
+     * @param db - DataStore instance
+     * @param hooks - HookBus instance
+     * @param encryptionKey - Optional master key for encrypting secrets at rest.
+     *   When provided, all new secrets are encrypted with AES-256-GCM.
+     *   Existing plaintext secrets are read transparently (passthrough on decrypt).
+     */
+    constructor(db: DataStore, hooks: HookBus, encryptionKey?: string);
+    set(input: SecretInput): Promise<SecretMeta>;
+    get(name: string, environment?: string): Promise<string | null>;
+    getMeta(name: string, environment?: string): Promise<SecretMeta | null>;
+    list(): Promise<SecretMeta[]>;
+    rotate(name: string, newValue: string, environment?: string): Promise<void>;
+    delete(name: string, environment?: string): Promise<void>;
+    /**
+     * Load a sync cursor by key. Returns undefined if not found.
+     * Cursors are stored as secrets with type='sync_cursor'.
+     */
+    loadCursor(key: string): Promise<string | undefined>;
+    /**
+     * Persist a sync cursor by key. Creates or updates the secret.
+     */
+    saveCursor(key: string, value: string): Promise<void>;
+    private _toMeta;
+}

package/dist/core/orchestrator/session-manager.d.ts

@@ -0,0 +1,13 @@
+import type { DataStore } from '../data/data-store.js';
+export declare class SessionManager {
+    private db;
+    constructor(db: DataStore);
+    save(agentId: string, channelId: string, peerId: string, params: Record<string, unknown>): Promise<string>;
+    load(agentId: string, channelId: string, peerId: string): Promise<Record<string, unknown> | undefined>;
+    clear(agentId: string, channelId: string, peerId: string): Promise<void>;
+    shouldClear(session: Record<string, unknown>, opts: {
+        maxRuns?: number;
+        maxAgeHours?: number;
+    }): Promise<boolean>;
+    private _find;
+}

package/dist/core/orchestrator/task-queue.d.ts

@@ -0,0 +1,34 @@
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+import { MAX_CHAIN_DEPTH } from './chain-guard.js';
+export { MAX_CHAIN_DEPTH };
+export declare class TaskQueue {
+    private db;
+    private hooks;
+    private config?;
+    private pollTimer;
+    private readonly pollIntervalMs;
+    private readonly staleThresholdMs;
+    constructor(db: DataStore, hooks: HookBus, config?: {
+        pollIntervalMs?: number;
+        staleThresholdMs?: number;
+    } | undefined);
+    create(task: {
+        title: string;
+        description?: string;
+        assignee_id?: string;
+        priority?: number;
+        chain_depth?: number;
+        chain_origin_id?: string;
+        [key: string]: unknown;
+    }): Promise<string>;
+    update(id: string, changes: Record<string, unknown>): Promise<void>;
+    get(id: string): Promise<Record<string, unknown> | undefined>;
+    list(filter?: {
+        status?: string;
+        assignee_id?: string;
+    }): Promise<Record<string, unknown>[]>;
+    startPolling(): void;
+    stopPolling(): void;
+    private poll;
+}

package/dist/core/orchestrator/template-interpolate.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Simple template interpolation for workflow step templates.
+ * Supports {{key}} and {{steps.stepId.output}} patterns.
+ */
+export declare function interpolate(template: string, context: Record<string, unknown>): string;

package/dist/core/orchestrator/tools/file-ops.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Built-in tools: File operations — list, register, send, read.
+ */
+import type { ToolDefinition, ToolHandler } from '../execution-engine.js';
+export declare const listFilesTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const registerFileTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};

package/dist/core/orchestrator/tools/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Built-in tools for the ExecutionEngine.
+ * 20 tools across 6 modules. All channel-agnostic.
+ */
+import type { ToolDefinition, ToolHandler } from '../execution-engine.js';
+import { sendFileTool } from './send-file.js';
+import { readFileTool } from './read-file.js';
+import { listFilesTool, registerFileTool } from './file-ops.js';
+import { dispatchTaskTool, cancelTaskTool, reassignTaskTool } from './task-ops.js';
+import { getTaskStatusTool, getAgentStatusTool, getSystemStatusTool, getActiveTasksTool } from './status.js';
+import { listAgentsTool, listProjectsTool, getAgentDetailTool } from './roster.js';
+import { sendMessageTool, addTaskCommentTool, readConversationTool, searchConversationTool } from './messaging.js';
+import { resolveAgent } from './resolve-agent.js';
+import { createAgentTool, createProjectTool } from './management.js';
+export { sendFileTool, readFileTool, listFilesTool, registerFileTool, dispatchTaskTool, cancelTaskTool, reassignTaskTool, getTaskStatusTool, getAgentStatusTool, getSystemStatusTool, getActiveTasksTool, listAgentsTool, listProjectsTool, getAgentDetailTool, sendMessageTool, addTaskCommentTool, readConversationTool, searchConversationTool, createAgentTool, createProjectTool, resolveAgent, };
+/**
+ * All native tools bundled for convenience.
+ * Apps can pass this directly to ExecutionEngine config:
+ *   tools: nativeTools
+ * or spread to add custom tools:
+ *   tools: [...nativeTools, myCustomTool]
+ */
+export declare const nativeTools: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+}[];
+/**
+ * Coordinator tools for multi-agent primary agent.
+ * Orchestration + communication + awareness — no "work" tools.
+ * Use with ChatPipelineV2 in multi-agent mode.
+ *
+ * Single-agent mode should use `nativeTools` instead (all tools).
+ */
+export declare const coordinatorTools: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+}[];
+export type Tool = {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+/**
+ * Merge multiple tool sets into a single array with unique names.
+ * Later tool sets override earlier ones — consumer tools win over built-ins.
+ * Logs a warning on each override so the collision is visible in logs.
+ */
+export declare function mergeTools(...toolSets: ReadonlyArray<ReadonlyArray<Tool>>): Tool[];

package/dist/core/orchestrator/tools/management.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Built-in tools: Entity creation — agents, projects.
+ */
+import type { ToolDefinition, ToolHandler } from '../execution-engine.js';
+export declare const createAgentTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const createProjectTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};

package/dist/core/orchestrator/tools/messaging.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Built-in tools: Communication — send messages, read conversations, search history.
+ * All messaging is channel-agnostic: slack, email, discord, sms — same tools.
+ */
+import type { ToolDefinition, ToolHandler } from '../execution-engine.js';
+export declare const sendMessageTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const addTaskCommentTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const readConversationTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const searchConversationTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};

package/dist/core/orchestrator/tools/read-file.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDefinition, ToolHandler } from '../execution-engine.js';
+export declare const readFileTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};

package/dist/core/orchestrator/tools/resolve-agent.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared agent resolution: slug → role → name (case-insensitive).
+ *
+ * LLMs see list_agents output like "AgentName (role)" and naturally use
+ * the role as the identifier. All agent-resolving tools must accept
+ * slug, role, OR name — not just slug.
+ */
+import type { DataStore } from '../../data/data-store.js';
+export declare function resolveAgent(db: DataStore, ref: string): Promise<Record<string, unknown> | null>;

package/dist/core/orchestrator/tools/roster.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Built-in tools: Entity lookup — agents, projects, details.
+ */
+import type { ToolDefinition, ToolHandler } from '../execution-engine.js';
+export declare const listAgentsTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const listProjectsTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const getAgentDetailTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};

package/dist/core/orchestrator/tools/send-file.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDefinition, ToolHandler } from '../execution-engine.js';
+export declare const sendFileTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};

package/dist/core/orchestrator/tools/status.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Built-in tools: System awareness — task status, agent status, system health.
+ */
+import type { ToolDefinition, ToolHandler } from '../execution-engine.js';
+export declare const getTaskStatusTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const getAgentStatusTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const getSystemStatusTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const getActiveTasksTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};

package/dist/core/orchestrator/tools/task-ops.d.ts

@@ -0,0 +1,13 @@
+import type { ToolDefinition, ToolHandler } from '../execution-engine.js';
+export declare const dispatchTaskTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const cancelTaskTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};
+export declare const reassignTaskTool: {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+};