botinabox 2.9.0 → 2.9.2

package/dist/core/llm/provider-registry.d.ts

@@ -0,0 +1,9 @@
+import type { LLMProvider, ModelInfo } from "./types.js";
+export declare class ProviderRegistry {
+    private providers;
+    register(provider: LLMProvider): void;
+    unregister(id: string): void;
+    get(id: string): LLMProvider | undefined;
+    list(): LLMProvider[];
+    listModels(): ModelInfo[];
+}

package/dist/core/llm/types.d.ts

@@ -0,0 +1,2 @@
+/** LLM module types — re-exports from @botinabox/shared */
+export type { LLMProvider, ModelInfo, ResolvedModel, ChatParams, ChatResult, ChatMessage, ContentBlock, TokenUsage, ToolDefinition, ToolUse, } from "../../shared/index.js";

package/dist/core/orchestrator/adapters/api-adapter.d.ts

@@ -0,0 +1,34 @@
+import type { ModelRouter } from '../../llm/model-router.js';
+import type { ChatMessage, TokenUsage } from "../../../shared/index.js";
+export declare class ApiExecutionAdapter {
+    private modelRouter;
+    readonly type = "api";
+    constructor(modelRouter: ModelRouter);
+    execute(ctx: {
+        agent: {
+            id: string;
+            model?: string;
+            adapter_config?: string;
+        };
+        task: {
+            description?: string;
+            context?: string;
+        };
+        sessionParams?: {
+            history?: ChatMessage[];
+        };
+        contextFiles?: string[];
+        abortSignal?: AbortSignal;
+        onLog?: (stream: 'stdout' | 'stderr', chunk: string) => void;
+    }): Promise<{
+        output: string;
+        exitCode: number;
+        usage: TokenUsage & {
+            provider: string;
+            model: string;
+        };
+        sessionParams: {
+            history: ChatMessage[];
+        };
+    }>;
+}

package/dist/core/orchestrator/adapters/cli-adapter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Inputs to the CLI argument builder. Kept as a separate type so the
+ * pure arg-construction function is unit-testable without spawning a process.
+ */
+export 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.
+ */
+export declare function buildCliArgs(input: CliArgBuildInput): string[];
+export declare class CliExecutionAdapter {
+    readonly type = "cli";
+    execute(ctx: {
+        agent: {
+            id: string;
+            cwd?: string;
+            adapter_config?: string;
+            skip_permissions?: boolean;
+        };
+        task: {
+            title: string;
+            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;
+    }): Promise<{
+        output: string;
+        exitCode: number;
+    }>;
+}

package/dist/core/orchestrator/adapters/deterministic-adapter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * DeterministicAdapter — executes scripts without LLM calls.
+ * Story 6.1
+ *
+ * For tasks that don't require reasoning: routing, validation,
+ * data fetching, file transforms. Runs a user-specified command
+ * (Python, Node, bash) as a subprocess with task context on stdin.
+ */
+export interface DeterministicConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    inputMode?: 'stdin' | 'arg';
+}
+export declare class DeterministicAdapter {
+    readonly type = "deterministic";
+    execute(ctx: {
+        agent: {
+            id: string;
+            cwd?: string;
+            adapter_config?: string;
+        };
+        task: {
+            title: string;
+            description?: string;
+            context?: string;
+        };
+        abortSignal?: AbortSignal;
+        onLog?: (stream: string, chunk: string) => void;
+    }): Promise<{
+        output: string;
+        exitCode: number;
+    }>;
+}

package/dist/core/orchestrator/adapters/env-whitelist.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Filter the process environment to only allowed keys, then merge in extras.
+ */
+export declare function filterEnv(allowed?: string[], extra?: Record<string, string>): Record<string, string>;

package/dist/core/orchestrator/adapters/output-extractor.d.ts

@@ -0,0 +1,11 @@
+export declare const MAX_OUTPUT_BYTES: number;
+/**
+ * Extract final output from NDJSON log content.
+ * Finds last line with {type:'result'} or {role:'assistant'}.
+ * Caps at 4MB.
+ */
+export declare function extractOutput(ndjsonContent: string): string;
+/**
+ * Read file and extract output.
+ */
+export declare function extractOutputFromFile(logPath: string): string;

package/dist/core/orchestrator/adapters/process-manager.d.ts

@@ -0,0 +1,15 @@
+import type { ChildProcess } from 'node:child_process';
+export interface SpawnOpts {
+    cwd: string;
+    allowedEnvVars?: string[];
+    extraEnv?: Record<string, string>;
+    timeoutMs?: number;
+}
+/**
+ * Spawn a process with its own PGID (detached=true) and piped stdio.
+ */
+export declare function spawnProcess(command: string, args: string[], opts: SpawnOpts): ChildProcess;
+/**
+ * Kill an entire process group by negative PID.
+ */
+export declare function killProcessGroup(pid: number, signal?: NodeJS.Signals): void;

package/dist/core/orchestrator/adapters/tool-loop.d.ts

@@ -0,0 +1,22 @@
+import type { ChatMessage, ChatParams, ChatResult, ToolDefinition } from "../../../shared/index.js";
+export interface ToolExecutor {
+    (toolName: string, toolInput: unknown): Promise<string>;
+}
+export declare function toolLoop(params: {
+    model: string;
+    messages: ChatMessage[];
+    systemPrompt?: string;
+    tools?: ToolDefinition[];
+    maxIterations?: number;
+    signal?: AbortSignal;
+}, callLLM: (params: ChatParams) => Promise<ChatResult>, executeTool?: ToolExecutor): AsyncGenerator<{
+    type: 'text';
+    content: string;
+} | {
+    type: 'tool_use';
+    name: string;
+    input: unknown;
+} | {
+    type: 'done';
+    result: ChatResult;
+}>;

package/dist/core/orchestrator/agent-registry.d.ts

@@ -0,0 +1,31 @@
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+export declare class AgentRegistry {
+    private db;
+    private hooks;
+    constructor(db: DataStore, hooks: HookBus);
+    register(agent: {
+        slug: string;
+        name: string;
+        adapter: string;
+        role?: string;
+        [key: string]: unknown;
+    }, opts?: {
+        actorAgentId?: string;
+    }): Promise<string>;
+    getById(id: string): Promise<Record<string, unknown> | undefined>;
+    getBySlug(slug: string): Promise<Record<string, unknown> | undefined>;
+    list(filter?: {
+        status?: string;
+        role?: string;
+    }): Promise<Record<string, unknown>[]>;
+    update(id: string, changes: Record<string, unknown>): Promise<void>;
+    setStatus(id: string, newStatus: string): Promise<void>;
+    terminate(id: string): Promise<void>;
+    seedFromConfig(agentConfigs: Array<{
+        slug: string;
+        name: string;
+        adapter: string;
+        [key: string]: unknown;
+    }>): Promise<void>;
+}

package/dist/core/orchestrator/budget-controller.d.ts

@@ -0,0 +1,19 @@
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+export declare class BudgetController {
+    private db;
+    private hooks;
+    constructor(db: DataStore, hooks: HookBus);
+    checkBudget(agentId: string): Promise<{
+        allowed: boolean;
+        reason?: string;
+        currentSpendCents: number;
+        limitCents: number;
+    }>;
+    resetMonthlySpend(agentId: string): Promise<void>;
+    globalCheck(): Promise<{
+        allowed: boolean;
+        totalSpentCents: number;
+        limitCents: number;
+    }>;
+}

package/dist/core/orchestrator/chain-guard.d.ts

@@ -0,0 +1,14 @@
+export declare const MAX_CHAIN_DEPTH = 5;
+/**
+ * Throws if depth exceeds the maximum allowed chain depth.
+ */
+export declare function checkChainDepth(depth: number, max?: number): void;
+/**
+ * Build chain origin metadata for a new child task.
+ * If parentTaskId is provided, sets chain_origin_id and increments depth.
+ * Otherwise returns depth=0 with no origin.
+ */
+export declare function buildChainOrigin(parentTaskId?: string, parentOriginId?: string, parentDepth?: number): {
+    chain_origin_id?: string;
+    chain_depth: number;
+};

package/dist/core/orchestrator/circuit-breaker.d.ts

@@ -0,0 +1,65 @@
+/**
+ * CircuitBreaker — prevents runaway agent failures with automatic escalation.
+ * Story 6.2
+ *
+ * States:
+ *   CLOSED  → normal operation, failures counted
+ *   OPEN    → tripped, all executions blocked, escalated to human
+ *   HALF_OPEN → probe mode, one execution allowed to test recovery
+ *
+ * Integrates with LoopDetector and RunManager via HookBus events.
+ */
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+export declare enum BreakerState {
+    CLOSED = "closed",
+    OPEN = "open",
+    HALF_OPEN = "half_open"
+}
+export interface CircuitBreakerConfig {
+    /** Failures before tripping. Default: 3 */
+    failureThreshold?: number;
+    /** Milliseconds to wait before half-open probe. Default: 300_000 (5 min) */
+    resetTimeoutMs?: number;
+    /** Log events to the database. Default: true */
+    persist?: boolean;
+}
+export declare class CircuitBreaker {
+    private db;
+    private hooks;
+    private readonly breakers;
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private readonly persist;
+    constructor(db: DataStore, hooks: HookBus, config?: CircuitBreakerConfig);
+    /**
+     * Check if an agent is allowed to execute.
+     * Returns true if execution is allowed, false if circuit is open.
+     */
+    canExecute(agentId: string): boolean;
+    /**
+     * Record a successful execution. Resets the breaker to CLOSED.
+     */
+    recordSuccess(agentId: string): Promise<void>;
+    /**
+     * Record a failed execution. Increments failure count and may trip breaker.
+     */
+    recordFailure(agentId: string, reason?: string): Promise<void>;
+    /**
+     * Trip the breaker to OPEN state and escalate to human.
+     */
+    trip(agentId: string, reason: string): Promise<void>;
+    /**
+     * Manually reset a breaker (e.g. after human review).
+     */
+    reset(agentId: string): Promise<void>;
+    /**
+     * Get the current state of a breaker.
+     */
+    getState(agentId: string): BreakerState;
+    /**
+     * Get failure count for an agent.
+     */
+    getFailureCount(agentId: string): number;
+    private logEvent;
+}

package/dist/core/orchestrator/claude-stream-parser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Parse Claude CLI NDJSON (stream-json) output into structured results.
+ * Used by the CLI execution adapter to extract session info, costs,
+ * token usage, and text output from Claude CLI subprocess output.
+ */
+export interface ParsedStream {
+    sessionId: string | null;
+    model: string | null;
+    costUsd: number | null;
+    usage: UsageSummary | null;
+    summary: string;
+    isError: boolean;
+    errorMessage: string | null;
+    stopReason: string | null;
+}
+export interface UsageSummary {
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+}
+/**
+ * Parse Claude CLI NDJSON output into a structured result.
+ * Handles init, assistant, and result event types.
+ */
+export declare function parseClaudeStream(stdout: string): ParsedStream;
+/** Check if the run stopped due to max turns. */
+export declare function isMaxTurns(parsed: ParsedStream): boolean;
+/** Check if Claude CLI requires login. */
+export declare function isLoginRequired(stdout: string): boolean;
+/** Rewrite local image paths to prevent CLI auto-embedding as vision content. */
+export declare function deactivateLocalImagePaths(prompt: string): string;

package/dist/core/orchestrator/config-revisions.d.ts

@@ -0,0 +1,6 @@
+import type { DataStore } from '../data/data-store.js';
+/**
+ * Creates a config revision record with before/after snapshots.
+ * Note: uses config_revisions table with config_yaml storing JSON of {agentId, before, after}.
+ */
+export declare function createConfigRevision(db: DataStore, agentId: string, before: Record<string, unknown>, after: Record<string, unknown>): Promise<void>;

package/dist/core/orchestrator/dependency-resolver.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Dependency resolution utilities for workflow steps and task deps.
+ */
+export interface StepRef {
+    id: string;
+    dependsOn?: string[];
+}
+/**
+ * DFS cycle detection — returns true if cycle exists.
+ */
+export declare function detectCycle(steps: StepRef[]): boolean;
+/**
+ * Returns step IDs in topological (execution) order.
+ * Throws if a cycle is detected.
+ */
+export declare function topologicalSort(steps: StepRef[]): string[];
+/**
+ * Returns true if all dependencies are satisfied (present in completedTaskIds).
+ */
+export declare function areDependenciesMet(taskDepsJson: string | undefined, completedTaskIds: Set<string>): boolean;

package/dist/core/orchestrator/execution-engine.d.ts

@@ -0,0 +1,99 @@
+/**
+ * ExecutionEngine — generic task executor with pluggable tools and tool loop.
+ *
+ * Listens for task.created events, picks up tasks, runs them through an LLM
+ * with tools, and finishes the run with the result.
+ *
+ * Apps configure: model, tools, system prompt, max iterations.
+ * Framework handles: task pickup, locking, tool loop, cost tracking, result storage.
+ */
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+import type { RunManager } from './run-manager.js';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+export type ToolHandler = (input: Record<string, unknown>, context: ToolContext) => Promise<string>;
+export interface ToolContext {
+    taskId: string;
+    agentId: string;
+    hooks: HookBus;
+    db: DataStore;
+    /** Resolve a relative file path to an absolute path (environment-aware). */
+    resolveFilePath?: (path: string) => string;
+}
+export 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;
+}
+export interface ExecutionEngineConfig {
+    /** Anthropic client instance */
+    client: {
+        messages: {
+            create: (params: Record<string, unknown>) => Promise<{
+                content: Array<{
+                    type: string;
+                    text?: string;
+                    id?: string;
+                    name?: string;
+                    input?: unknown;
+                }>;
+                stop_reason: string;
+                usage: {
+                    input_tokens: number;
+                    output_tokens: number;
+                };
+            }>;
+        };
+    };
+    /** Model to use. Default: claude-sonnet-4-20250514 */
+    model?: string;
+    /** Max tool loop iterations. Default: 5 */
+    maxIterations?: number;
+    /** Tools available to the agent */
+    tools?: Array<{
+        definition: ToolDefinition;
+        handler: ToolHandler;
+    }>;
+    /** Additional system prompt text (appended after system context) */
+    systemPromptSuffix?: string;
+    /** Include system context (users, files, etc). Default: true */
+    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[];
+}
+/**
+ * Wrap a set of context files in `<file path="...">...</file>` XML tags,
+ * joined by blank lines. Returns an empty string if the input is empty so
+ * callers can safely concatenate the result into a larger prompt without
+ * needing a conditional. Pure function — no I/O — so it can be unit-tested
+ * without touching the filesystem or a model.
+ */
+export declare function formatContextFilesBlock(files: ContextFile[]): string;
+export declare function registerExecutionEngine(opts: {
+    db: DataStore;
+    hooks: HookBus;
+    runs: RunManager;
+    config: ExecutionEngineConfig;
+}): Promise<void>;

package/dist/core/orchestrator/governance-gate.d.ts

@@ -0,0 +1,110 @@
+/**
+ * GovernanceGate — independent validation gates for agent output.
+ * Story 6.7
+ *
+ * Key principle: gates report to the HUMAN, not to each other
+ * or to a project manager agent. Structural independence prevents capture.
+ *
+ * Gate dimensions:
+ *   QA       — data correctness (schema, row counts, format)
+ *   Quality  — code quality (lint, coverage, patterns)
+ *   Drift    — architectural drift (unintended dependencies, scope creep)
+ */
+import type { HookBus } from '../hooks/hook-bus.js';
+export type GateVerdict = 'pass' | 'fail' | 'warn';
+export interface GateResult {
+    gateId: string;
+    verdict: GateVerdict;
+    findings: GateFinding[];
+    checkedAt: string;
+    durationMs: number;
+}
+export interface GateFinding {
+    severity: 'info' | 'warning' | 'error' | 'critical';
+    message: string;
+    location?: string;
+    suggestion?: string;
+}
+export interface GateInput {
+    agentId: string;
+    taskId: string;
+    output: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Base class for governance gates. Each gate checks a different dimension.
+ * Gates are structurally independent — they report to the human operator,
+ * not to each other or to any agent.
+ */
+export declare abstract class GovernanceGate {
+    abstract readonly id: string;
+    abstract readonly name: string;
+    abstract readonly dimension: string;
+    /**
+     * Run the gate check on agent output.
+     * Must return a verdict and any findings.
+     */
+    abstract check(input: GateInput): Promise<GateResult>;
+}
+/**
+ * QA Gate — validates data correctness.
+ * Checks: schema conformance, row counts, format validation.
+ */
+export declare class QAGate extends GovernanceGate {
+    private validators;
+    readonly id = "qa";
+    readonly name = "Quality Assurance";
+    readonly dimension = "data_correctness";
+    constructor(validators?: Array<{
+        name: string;
+        validate: (output: string, metadata?: Record<string, unknown>) => GateFinding[];
+    }>);
+    check(input: GateInput): Promise<GateResult>;
+}
+/**
+ * Quality Gate — validates code quality.
+ * Checks: lint results, test coverage, review patterns.
+ */
+export declare class QualityGate extends GovernanceGate {
+    private checks;
+    readonly id = "quality";
+    readonly name = "Code Quality";
+    readonly dimension = "code_quality";
+    constructor(checks?: Array<{
+        name: string;
+        check: (output: string, metadata?: Record<string, unknown>) => Promise<GateFinding[]>;
+    }>);
+    check(input: GateInput): Promise<GateResult>;
+}
+/**
+ * Drift Gate — detects architectural drift.
+ * Checks: unintended dependencies, scope creep, pattern violations.
+ */
+export declare class DriftGate extends GovernanceGate {
+    private rules;
+    readonly id = "drift";
+    readonly name = "Architectural Drift";
+    readonly dimension = "architecture";
+    constructor(rules?: Array<{
+        name: string;
+        detect: (output: string, metadata?: Record<string, unknown>) => GateFinding[];
+    }>);
+    check(input: GateInput): Promise<GateResult>;
+}
+/**
+ * GateRunner — orchestrates multiple independent gates on agent output.
+ * Each gate runs independently. Results are reported to the human, not to agents.
+ */
+export declare class GateRunner {
+    private gates;
+    private hooks;
+    constructor(gates: GovernanceGate[], hooks: HookBus);
+    /**
+     * Run all gates on the given input.
+     * Gates run independently — one failure doesn't block others.
+     */
+    runAll(input: GateInput): Promise<{
+        passed: boolean;
+        results: GateResult[];
+    }>;
+}