botinabox 2.5.0 → 2.5.2

package/dist/core/orchestrator/learning-pipeline.js

@@ -0,0 +1,249 @@
+/**
+ * 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?
+ */
+const DEFAULT_PLAYBOOK_THRESHOLD = 3;
+const DEFAULT_SKILL_THRESHOLD = 3;
+export class LearningPipeline {
+    db;
+    hooks;
+    playbookThreshold;
+    skillThreshold;
+    autoPromote;
+    constructor(db, hooks, config) {
+        this.db = db;
+        this.hooks = hooks;
+        this.playbookThreshold = config?.playbookThreshold ?? DEFAULT_PLAYBOOK_THRESHOLD;
+        this.skillThreshold = config?.skillThreshold ?? DEFAULT_SKILL_THRESHOLD;
+        this.autoPromote = config?.autoPromote ?? false;
+    }
+    // --- Feedback Layer ---
+    /**
+     * Capture a structured feedback record from an execution.
+     */
+    async captureFeedback(entry) {
+        const row = await this.db.insert('feedback', {
+            agent_id: entry.agentId,
+            task_id: entry.taskId,
+            issue: entry.issue,
+            root_cause: entry.rootCause,
+            severity: entry.severity,
+            repeatable: entry.repeatable ? 1 : 0,
+            accuracy_score: entry.accuracyScore,
+            efficiency_score: entry.efficiencyScore,
+            tags: JSON.stringify(entry.tags ?? []),
+        });
+        const feedbackId = row['id'];
+        await this.hooks.emit('learning.feedback_captured', {
+            feedbackId,
+            agentId: entry.agentId,
+            issue: entry.issue,
+            severity: entry.severity,
+        });
+        // Check for auto-promotion
+        if (this.autoPromote) {
+            await this.checkPlaybookPromotion(entry.issue);
+        }
+        return feedbackId;
+    }
+    /**
+     * Get all feedback records, optionally filtered.
+     */
+    async listFeedback(filter) {
+        const where = {};
+        if (filter?.agentId)
+            where['agent_id'] = filter.agentId;
+        if (filter?.severity)
+            where['severity'] = filter.severity;
+        if (filter?.repeatable !== undefined)
+            where['repeatable'] = filter.repeatable ? 1 : 0;
+        return this.db.query('feedback', Object.keys(where).length ? { where } : undefined);
+    }
+    // --- Playbook Layer ---
+    /**
+     * Check if feedback records with similar issues should be promoted to a playbook.
+     * Groups by issue text similarity (exact match for now).
+     */
+    async checkPlaybookPromotion(issue) {
+        const allFeedback = await this.db.query('feedback', {
+            where: { issue },
+        });
+        if (allFeedback.length < this.playbookThreshold) {
+            return undefined;
+        }
+        // Check if a playbook already exists for this pattern
+        const existingPlaybooks = await this.db.query('playbooks', {
+            where: { pattern: issue },
+        });
+        if (existingPlaybooks.length > 0) {
+            return existingPlaybooks[0]['id'];
+        }
+        // Auto-promote: create a playbook from the feedback
+        const feedbackIds = allFeedback.map((f) => f['id']);
+        const rootCauses = allFeedback
+            .map((f) => f['root_cause'])
+            .filter(Boolean);
+        const rule = rootCauses.length > 0
+            ? `When encountering "${issue}": ${rootCauses[0]}`
+            : `Pattern detected: "${issue}" — review and add specific guidance.`;
+        const playbookId = await this.promoteToPlaybook({
+            pattern: issue,
+            rule,
+            feedbackIds,
+            projectScoped: true,
+        });
+        return playbookId;
+    }
+    /**
+     * Manually create a playbook from a set of feedback records.
+     */
+    async promoteToPlaybook(entry) {
+        const row = await this.db.insert('playbooks', {
+            pattern: entry.pattern,
+            rule: entry.rule,
+            feedback_ids: JSON.stringify(entry.feedbackIds),
+            project_scoped: entry.projectScoped ? 1 : 0,
+        });
+        const playbookId = row['id'];
+        // Link to agents if specified
+        if (entry.agentIds) {
+            for (const agentId of entry.agentIds) {
+                await this.db.insert('agent_playbooks', {
+                    agent_id: agentId,
+                    playbook_id: playbookId,
+                });
+            }
+        }
+        await this.hooks.emit('learning.playbook_promoted', {
+            playbookId,
+            pattern: entry.pattern,
+            feedbackCount: entry.feedbackIds.length,
+        });
+        return playbookId;
+    }
+    /**
+     * List playbooks, optionally filtered.
+     */
+    async listPlaybooks(filter) {
+        const where = {};
+        if (filter?.projectScoped !== undefined) {
+            where['project_scoped'] = filter.projectScoped ? 1 : 0;
+        }
+        return this.db.query('playbooks', Object.keys(where).length ? { where } : undefined);
+    }
+    // --- Skill Layer ---
+    /**
+     * 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).
+     */
+    async checkSkillPromotion(playbookId) {
+        const playbook = await this.db.get('playbooks', { id: playbookId });
+        if (!playbook)
+            return undefined;
+        // Count distinct agents using this playbook
+        const links = await this.db.query('agent_playbooks', {
+            where: { playbook_id: playbookId },
+        });
+        if (links.length < this.skillThreshold) {
+            return undefined;
+        }
+        // Check if skill already exists for this pattern
+        const pattern = playbook['pattern'];
+        const existingSkills = await this.db.query('skills', {
+            where: { name: pattern },
+        });
+        if (existingSkills.length > 0) {
+            return existingSkills[0]['id'];
+        }
+        // Promote to skill
+        const slug = pattern
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '')
+            .slice(0, 64);
+        const skillId = await this.promoteToSkill({
+            name: pattern,
+            slug,
+            description: `Auto-promoted from playbook: ${pattern}`,
+            behavior: playbook['rule'],
+            sourcePlaybookIds: [playbookId],
+        });
+        return skillId;
+    }
+    /**
+     * Manually promote a playbook to a reusable skill.
+     */
+    async promoteToSkill(entry) {
+        const row = await this.db.insert('skills', {
+            name: entry.name,
+            slug: entry.slug,
+            description: entry.description,
+            category: entry.category ?? 'learned',
+            definition: JSON.stringify({
+                behavior: entry.behavior,
+                source_playbook_ids: entry.sourcePlaybookIds,
+            }),
+        });
+        const skillId = row['id'];
+        await this.hooks.emit('learning.skill_promoted', {
+            skillId,
+            name: entry.name,
+            slug: entry.slug,
+            sourcePlaybookCount: entry.sourcePlaybookIds.length,
+        });
+        return skillId;
+    }
+    /**
+     * Assign a skill to an agent.
+     */
+    async assignSkill(agentId, skillId) {
+        await this.db.link('agent_skills', {
+            agent_id: agentId,
+            skill_id: skillId,
+        });
+        await this.hooks.emit('learning.skill_assigned', { agentId, skillId });
+    }
+    /**
+     * Get learning metrics for an agent.
+     */
+    async getMetrics(agentId) {
+        const feedback = await this.db.query('feedback', { where: { agent_id: agentId } });
+        const accuracyScores = feedback
+            .map((f) => f['accuracy_score'])
+            .filter((s) => s !== null && s !== undefined);
+        const efficiencyScores = feedback
+            .map((f) => f['efficiency_score'])
+            .filter((s) => s !== null && s !== undefined);
+        let playbookCount = 0;
+        try {
+            const links = await this.db.query('agent_playbooks', { where: { agent_id: agentId } });
+            playbookCount = links.length;
+        }
+        catch {
+            // Table may not exist
+        }
+        const skillLinks = await this.db.query('agent_skills', { where: { agent_id: agentId } });
+        return {
+            feedbackCount: feedback.length,
+            avgAccuracy: accuracyScores.length > 0
+                ? accuracyScores.reduce((a, b) => a + b, 0) / accuracyScores.length
+                : null,
+            avgEfficiency: efficiencyScores.length > 0
+                ? efficiencyScores.reduce((a, b) => a + b, 0) / efficiencyScores.length
+                : null,
+            playbookCount,
+            skillCount: skillLinks.length,
+        };
+    }
+}

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/loop-detector.js

@@ -0,0 +1,133 @@
+/**
+ * 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
+ */
+export var LoopType;
+(function (LoopType) {
+    LoopType["SELF_LOOP"] = "self_loop";
+    LoopType["PING_PONG"] = "ping_pong";
+    LoopType["BLOCKED_REENTRY"] = "blocked_reentry";
+})(LoopType || (LoopType = {}));
+const DEFAULT_WINDOW = 10;
+const DEFAULT_PING_PONG_THRESHOLD = 2;
+export class LoopDetector {
+    db;
+    windowSize;
+    pingPongThreshold;
+    constructor(db, config) {
+        this.db = db;
+        this.windowSize = config?.windowSize ?? DEFAULT_WINDOW;
+        this.pingPongThreshold = config?.pingPongThreshold ?? DEFAULT_PING_PONG_THRESHOLD;
+    }
+    /**
+     * Check for loops before creating a followup task.
+     * Returns a LoopDetection if a loop pattern is found, undefined otherwise.
+     */
+    async check(sourceAgentId, targetAgentId, taskId, chainOriginId) {
+        // 1. Self-loop: source == target
+        const selfLoop = this.checkSelfLoop(sourceAgentId, targetAgentId, taskId);
+        if (selfLoop)
+            return selfLoop;
+        // 2. Blocked re-entry
+        const blocked = await this.checkBlockedReentry(targetAgentId, taskId, chainOriginId);
+        if (blocked)
+            return blocked;
+        // 3. Ping-pong: look at recent chain history
+        const pingPong = await this.checkPingPong(sourceAgentId, targetAgentId, chainOriginId);
+        if (pingPong)
+            return pingPong;
+        return undefined;
+    }
+    /**
+     * Check if an agent is routing to itself.
+     */
+    checkSelfLoop(sourceAgentId, targetAgentId, taskId) {
+        if (sourceAgentId === targetAgentId) {
+            return {
+                type: LoopType.SELF_LOOP,
+                agents: [sourceAgentId],
+                taskId,
+                message: `Self-loop detected: agent ${sourceAgentId} is routing to itself`,
+            };
+        }
+        return undefined;
+    }
+    /**
+     * Check if a previously blocked task is being re-entered.
+     */
+    async checkBlockedReentry(targetAgentId, taskId, chainOriginId) {
+        // Look for blocked/failed tasks in the same chain
+        const originId = chainOriginId ?? taskId;
+        const chainTasks = await this.db.query('tasks', {
+            where: { chain_origin_id: originId },
+        });
+        const blockedInChain = chainTasks.filter((t) => (t['status'] === 'blocked' || t['status'] === 'failed') &&
+            t['assignee_id'] === targetAgentId);
+        if (blockedInChain.length > 0) {
+            return {
+                type: LoopType.BLOCKED_REENTRY,
+                agents: [targetAgentId],
+                taskId,
+                chainOriginId: originId,
+                message: `Blocked re-entry: agent ${targetAgentId} already has a blocked/failed task in chain ${originId}`,
+            };
+        }
+        return undefined;
+    }
+    /**
+     * Check for A→B→A→B ping-pong by scanning recent tasks in the chain.
+     */
+    async checkPingPong(sourceAgentId, targetAgentId, chainOriginId) {
+        if (!chainOriginId)
+            return undefined;
+        // Get recent tasks in this chain, ordered by creation
+        const chainTasks = await this.db.query('tasks', {
+            where: { chain_origin_id: chainOriginId },
+        });
+        // Sort by chain_depth (ascending) then created_at
+        const sorted = chainTasks
+            .sort((a, b) => {
+            const depthDiff = (a['chain_depth'] ?? 0) - (b['chain_depth'] ?? 0);
+            if (depthDiff !== 0)
+                return depthDiff;
+            return (a['created_at'] ?? '').localeCompare(b['created_at'] ?? '');
+        })
+            .slice(-this.windowSize);
+        // Extract the agent sequence
+        const agentSequence = sorted
+            .map((t) => t['assignee_id'])
+            .filter(Boolean);
+        // Add the proposed next hop
+        agentSequence.push(targetAgentId);
+        // Detect A→B→A→B pattern
+        if (agentSequence.length >= this.pingPongThreshold * 2) {
+            const tail = agentSequence.slice(-this.pingPongThreshold * 2);
+            const a = tail[0];
+            const b = tail[1];
+            if (a && b && a !== b) {
+                let isPingPong = true;
+                for (let i = 0; i < tail.length; i++) {
+                    if (tail[i] !== (i % 2 === 0 ? a : b)) {
+                        isPingPong = false;
+                        break;
+                    }
+                }
+                if (isPingPong) {
+                    return {
+                        type: LoopType.PING_PONG,
+                        agents: [a, b],
+                        taskId: sorted[sorted.length - 1]?.['id'] ?? '',
+                        chainOriginId,
+                        message: `Ping-pong detected: agents ${a} and ${b} are bouncing tasks in chain ${chainOriginId}`,
+                    };
+                }
+            }
+        }
+        return undefined;
+    }
+}

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/ndjson-logger.js

@@ -0,0 +1,18 @@
+import { appendFileSync } from 'node:fs';
+export class NdjsonLogger {
+    logPath;
+    constructor(logPath) {
+        this.logPath = logPath;
+    }
+    log(stream, chunk) {
+        const line = JSON.stringify({
+            timestamp: new Date().toISOString(),
+            stream,
+            chunk,
+        });
+        appendFileSync(this.logPath, line + '\n', 'utf8');
+    }
+    close() {
+        // No-op — synchronous writes flush immediately
+    }
+}

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/permission-relay.js

@@ -0,0 +1,164 @@
+/**
+ * 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.
+ */
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1_000;
+export class PermissionRelay {
+    hooks;
+    providers;
+    pollIntervalMs;
+    timeoutMs;
+    pending = new Map();
+    constructor(hooks, config) {
+        this.hooks = hooks;
+        this.providers = config.providers;
+        this.pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /**
+     * Request approval from all configured providers.
+     * Returns when the first provider responds (approve or deny).
+     */
+    async requestApproval(prompt) {
+        // Set expiry
+        const expiresAt = new Date(Date.now() + this.timeoutMs).toISOString();
+        const promptWithExpiry = { ...prompt, expiresAt };
+        await this.hooks.emit('permission.requested', {
+            promptId: prompt.id,
+            agentId: prompt.agentId,
+            action: prompt.action,
+        });
+        // Send to all providers
+        const handles = new Map();
+        for (const provider of this.providers) {
+            try {
+                const handle = await provider.sendPrompt(promptWithExpiry);
+                handles.set(provider.id, handle);
+            }
+            catch {
+                // Provider unavailable — continue with others
+            }
+        }
+        if (handles.size === 0) {
+            throw new Error('No permission providers available');
+        }
+        // Race: poll all providers, first response wins
+        return new Promise((resolve, reject) => {
+            const entry = {
+                prompt: promptWithExpiry,
+                handles,
+                resolve,
+                reject,
+            };
+            this.pending.set(prompt.id, entry);
+            // Start polling
+            const pollTimer = setInterval(async () => {
+                for (const [providerId, handle] of handles) {
+                    const provider = this.providers.find((p) => p.id === providerId);
+                    if (!provider)
+                        continue;
+                    try {
+                        const response = await provider.pollResponse(handle);
+                        if (response) {
+                            clearInterval(pollTimer);
+                            clearTimeout(timeoutTimer);
+                            this.pending.delete(prompt.id);
+                            // Cancel remaining providers
+                            await this.cancelOtherProviders(handles, providerId);
+                            await this.hooks.emit('permission.responded', {
+                                promptId: prompt.id,
+                                status: response.status,
+                                respondedBy: response.respondedBy,
+                            });
+                            resolve(response);
+                            return;
+                        }
+                    }
+                    catch {
+                        // Poll error — continue
+                    }
+                }
+            }, this.pollIntervalMs);
+            // Timeout
+            const timeoutTimer = setTimeout(async () => {
+                clearInterval(pollTimer);
+                this.pending.delete(prompt.id);
+                // Cancel all providers
+                for (const [providerId, handle] of handles) {
+                    const provider = this.providers.find((p) => p.id === providerId);
+                    if (provider) {
+                        try {
+                            await provider.cancelPrompt(handle);
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+                await this.hooks.emit('permission.expired', {
+                    promptId: prompt.id,
+                    agentId: prompt.agentId,
+                });
+                reject(new Error(`Permission request expired after ${this.timeoutMs}ms`));
+            }, this.timeoutMs);
+        });
+    }
+    /**
+     * Provide a local approval (from terminal).
+     * Resolves the pending request and cancels remote providers.
+     */
+    async approveLocally(promptId, approved) {
+        const entry = this.pending.get(promptId);
+        if (!entry)
+            return;
+        const response = {
+            promptId,
+            status: approved ? 'approved' : 'denied',
+            respondedBy: 'local',
+            respondedAt: new Date().toISOString(),
+        };
+        this.pending.delete(promptId);
+        // Cancel all remote providers
+        for (const [providerId, handle] of entry.handles) {
+            const provider = this.providers.find((p) => p.id === providerId);
+            if (provider) {
+                try {
+                    await provider.cancelPrompt(handle);
+                }
+                catch { /* ignore */ }
+            }
+        }
+        await this.hooks.emit('permission.responded', {
+            promptId,
+            status: response.status,
+            respondedBy: 'local',
+        });
+        entry.resolve(response);
+    }
+    /**
+     * Get all pending approval requests.
+     */
+    getPending() {
+        return Array.from(this.pending.values()).map((e) => e.prompt);
+    }
+    async cancelOtherProviders(handles, excludeProviderId) {
+        for (const [providerId, handle] of handles) {
+            if (providerId === excludeProviderId)
+                continue;
+            const provider = this.providers.find((p) => p.id === providerId);
+            if (provider) {
+                try {
+                    await provider.cancelPrompt(handle);
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+}