botinabox 2.9.1 → 2.9.3

package/dist/shared/types/config.d.ts

@@ -0,0 +1,160 @@
+/** Bot configuration types — Story 1.2 / 1.5 */
+export interface DataConfig {
+    path: string;
+    walMode: boolean;
+    backupDir?: string;
+}
+export interface ModelConfig {
+    aliases: Record<string, string>;
+    default: string;
+    routing: Record<string, string>;
+    fallbackChain: string[];
+    costLimit?: {
+        perRunCents?: number;
+    };
+}
+export interface SecurityConfig {
+    fieldLengthLimits?: Record<string, number>;
+    allowedFilePrefixes?: string[];
+}
+export interface RenderConfig {
+    outputDir: string;
+    watchIntervalMs: number;
+}
+export interface UpdateConfig {
+    policy: "auto-all" | "auto-compatible" | "auto-patch" | "notify" | "manual";
+    checkIntervalMs: number;
+    maintenanceWindow?: {
+        utcHourStart: number;
+        utcHourEnd: number;
+        days?: Array<"mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun">;
+    };
+}
+export interface BudgetConfig {
+    globalMonthlyCents?: number;
+    warnPercent: number;
+}
+export interface EntityColumnDef {
+    type: "uuid" | "text" | "integer" | "boolean" | "datetime" | "real";
+    required?: boolean;
+    default?: string | number | boolean;
+    references?: string;
+}
+export interface EntityConfig {
+    columns: Record<string, EntityColumnDef>;
+    relations?: Array<{
+        type: "hasMany" | "manyToMany" | "belongsTo";
+        table: string;
+        through?: string;
+        localKey?: string;
+        remoteKey?: string;
+    }>;
+}
+export interface AgentConfig {
+    slug: string;
+    name: string;
+    role?: string;
+    adapter: string;
+    model?: string;
+    workdir?: string;
+    instructionsFile?: string;
+    maxConcurrentRuns?: number;
+    budgetMonthlyCents?: number;
+    canCreateAgents?: boolean;
+    skipPermissions?: boolean;
+    config?: Record<string, unknown>;
+}
+export interface ExecutionConfig {
+    /** Model for task execution. Default: models.routing.task_execution */
+    model?: string;
+    /** Max tool loop iterations per task. Default: 5 */
+    maxIterations?: number;
+    /** Max tokens per LLM call. Default: 4096 */
+    maxTokens?: number;
+    /** Additional system prompt text appended to agent prompt */
+    systemPromptSuffix?: string;
+}
+export interface ChatConfig {
+    /** System prompt for the conversational responder */
+    systemPrompt?: string;
+    /** Max tokens for context window. Default: 4000 */
+    contextWindowTokens?: number;
+    /** Max recent outbound messages for redundancy check. Default: 10 */
+    redundancyWindow?: number;
+    /** Message dedup window in ms. Default: 300000 (5 min) */
+    dedupWindowMs?: number;
+    /** Max tokens for ack responses. Default: 500 */
+    responseMaxTokens?: number;
+}
+export interface RoutingConfig {
+    /** Routing rules for message triage */
+    rules: Array<{
+        agentSlug: string;
+        keywords?: string[];
+        patterns?: string[];
+        priority?: number;
+    }>;
+    /** Default agent when no rule matches */
+    fallbackAgent: string;
+    /** Use LLM for ambiguous messages. Default: false */
+    llmFallback?: boolean;
+}
+export interface SafetyConfig {
+    /** Circuit breaker failure threshold. Default: 3 */
+    circuitBreakerThreshold?: number;
+    /** Circuit breaker reset timeout ms. Default: 300000 (5 min) */
+    circuitBreakerResetMs?: number;
+    /** Max agent followup chain depth. Default: 5 */
+    maxChainDepth?: number;
+    /** Stale run detection threshold ms. Default: 1800000 (30 min) */
+    staleRunThresholdMs?: number;
+}
+export interface BotConfig {
+    data: DataConfig;
+    channels: Record<string, {
+        enabled: boolean;
+        accounts?: Record<string, unknown>;
+    } & Record<string, unknown>>;
+    connectors?: Record<string, {
+        enabled: boolean;
+        provider: string;
+        accounts?: Record<string, import("./connector.js").ConnectorConfig>;
+    } & Record<string, unknown>>;
+    agents: AgentConfig[];
+    providers: Record<string, {
+        enabled: boolean;
+    } & Record<string, unknown>>;
+    models: ModelConfig;
+    entities: Record<string, EntityConfig>;
+    security: SecurityConfig;
+    render: RenderConfig;
+    updates: UpdateConfig;
+    budget: BudgetConfig;
+    execution?: ExecutionConfig;
+    chat?: ChatConfig;
+    routing?: RoutingConfig;
+    safety?: SafetyConfig;
+    workflows?: Record<string, WorkflowConfigEntry>;
+}
+export interface WorkflowConfigEntry {
+    name: string;
+    description?: string;
+    steps: WorkflowStepConfig[];
+    trigger?: {
+        type: "task_completed" | "event" | "schedule" | "manual";
+        filter?: Record<string, unknown>;
+    };
+}
+export interface WorkflowStepConfig {
+    id: string;
+    name: string;
+    agentSlug?: string;
+    taskTemplate: {
+        title: string;
+        description: string;
+    };
+    dependsOn?: string[];
+    onComplete?: "next" | "parallel" | "end";
+    onFail?: "abort" | "skip" | "retry";
+    retryPolicy?: import("./task.js").RetryPolicy;
+}

package/dist/shared/types/connector.d.ts

@@ -0,0 +1,77 @@
+/** Connector types — generic external service integrations. */
+export interface ConnectorMeta {
+    displayName: string;
+    /** Provider identifier, e.g. "google", "trello", "jira", "salesforce" */
+    provider: string;
+    /** Data type this connector handles, e.g. "email", "calendar", "board", "crm" */
+    dataType: string;
+}
+export interface SyncOptions {
+    /** Only sync records after this ISO 8601 timestamp */
+    since?: string;
+    /** Provider-specific incremental sync token */
+    cursor?: string;
+    /** Maximum number of records to fetch */
+    limit?: number;
+    /** Provider-specific query filters */
+    filters?: Record<string, unknown>;
+}
+export interface SyncResult<T = Record<string, unknown>> {
+    /** Typed records produced by the connector — consumer decides where to store */
+    records: T[];
+    /** Next incremental sync token (persist for future calls) */
+    cursor?: string;
+    /** Whether more records are available (pagination) */
+    hasMore: boolean;
+    /** Errors encountered during sync (non-fatal per-record failures) */
+    errors: Array<{
+        id?: string;
+        error: string;
+    }>;
+}
+export interface PushResult {
+    success: boolean;
+    externalId?: string;
+    error?: string;
+}
+export interface AuthResult {
+    success: boolean;
+    account?: string;
+    /** URL the user must visit to authorize (for OAuth flows) */
+    authUrl?: string;
+    error?: string;
+}
+export type ConnectorConfig = Record<string, unknown>;
+/**
+ * Generic connector interface for external service integrations.
+ *
+ * Connectors pull and optionally push data to/from external services
+ * (Gmail, Calendar, Trello, Jira, Salesforce, etc.). They produce
+ * typed records — the consuming application decides where to store them.
+ *
+ * @typeParam T - The record type this connector produces/consumes.
+ */
+export interface Connector<T = Record<string, unknown>> {
+    readonly id: string;
+    readonly meta: ConnectorMeta;
+    connect(config: ConnectorConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        account?: string;
+        error?: string;
+    }>;
+    /** Pull records from external source */
+    sync(options?: SyncOptions): Promise<SyncResult<T>>;
+    /** Push a record to external source (optional) */
+    push?(payload: T): Promise<PushResult>;
+    /**
+     * Run the authentication/authorization flow for this connector.
+     * For OAuth connectors, this generates the auth URL and exchanges the code for tokens.
+     *
+     * @param codeProvider - called with the auth URL; must return the authorization code.
+     *   For CLI flows, this prints the URL and reads from stdin.
+     *   For programmatic flows, the caller handles the redirect.
+     */
+    authenticate?(codeProvider: (authUrl: string) => Promise<string>): Promise<AuthResult>;
+}

package/dist/shared/types/execution.d.ts

@@ -0,0 +1,29 @@
+/** Execution adapter types — Story 1.5 / 3.4 / 3.5 */
+export type RunStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";
+export interface RunContext {
+    runId: string;
+    agentId: string;
+    agentSlug: string;
+    taskId?: string;
+    taskTitle?: string;
+    taskDescription?: string;
+    model: string;
+    workdir: string;
+    sessionParams?: unknown;
+    abortSignal?: AbortSignal;
+    onLog?: (line: string) => void;
+}
+export interface RunResult {
+    status: "succeeded" | "failed";
+    output?: string;
+    error?: string;
+    usage?: import("./provider.js").TokenUsage;
+    costCents?: number;
+    sessionParams?: unknown;
+    clearSession?: boolean;
+    durationMs: number;
+}
+export interface ExecutionAdapter {
+    id: string;
+    execute(ctx: RunContext): Promise<RunResult>;
+}

package/dist/{provider-BHkqkSdq.d.ts → shared/types/provider.d.ts}

@@ -1,14 +1,14 @@
 /** LLM provider types — Story 1.5 / 2.1 */
-interface ToolDefinition {
+export interface ToolDefinition {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
 }
-interface ChatMessage {
+export interface ChatMessage {
     role: "user" | "assistant" | "system";
     content: string | ContentBlock[];
 }
-type ContentBlock = {
+export type ContentBlock = {
     type: "text";
     text: string;
 } | {
@@ -35,7 +35,7 @@ type ContentBlock = {
         data: string;
     };
 };
-interface ChatParams {
+export interface ChatParams {
     messages: ChatMessage[];
     system?: string;
     tools?: ToolDefinition[];
@@ -44,25 +44,25 @@ interface ChatParams {
     model: string;
     abortSignal?: AbortSignal;
 }
-interface TokenUsage {
+export interface TokenUsage {
     inputTokens: number;
     outputTokens: number;
     cacheReadTokens?: number;
     cacheWriteTokens?: number;
 }
-interface ChatResult {
+export interface ChatResult {
     content: string;
     toolUses?: ToolUse[];
     usage: TokenUsage;
     model: string;
     stopReason: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence";
 }
-interface ToolUse {
+export interface ToolUse {
     id: string;
     name: string;
     input: unknown;
 }
-interface ModelInfo {
+export interface ModelInfo {
     id: string;
     displayName: string;
     contextWindow: number;
@@ -72,11 +72,11 @@ interface ModelInfo {
     inputCostPerMToken?: number;
     outputCostPerMToken?: number;
 }
-interface ResolvedModel {
+export interface ResolvedModel {
     provider: string;
     model: string;
 }
-interface LLMProvider {
+export interface LLMProvider {
     id: string;
     displayName: string;
     models: ModelInfo[];
@@ -85,5 +85,3 @@ interface LLMProvider {
     /** Convert ToolDefinition[] to provider-native format */
     serializeTools(tools: ToolDefinition[]): unknown;
 }
-
-export type { ChatMessage as C, LLMProvider as L, ModelInfo as M, ResolvedModel as R, TokenUsage as T, ChatParams as a, ChatResult as b, ContentBlock as c, ToolUse as d, ToolDefinition as e };

package/dist/shared/types/task.d.ts

@@ -0,0 +1,47 @@
+/** Task types — Story 1.5 / 3.2 */
+export type TaskStatus = "backlog" | "todo" | "in_progress" | "in_review" | "done" | "blocked" | "cancelled";
+export interface RetryPolicy {
+    maxRetries: number;
+    backoffMs: number;
+    backoffMultiplier: number;
+    maxBackoffMs: number;
+}
+export interface TaskDefinition {
+    title: string;
+    description?: string;
+    assigneeId?: string;
+    priority?: number;
+    parentId?: string;
+    dependsOn?: string[];
+    followupAgentId?: string;
+    followupTemplate?: string;
+    chainOriginId?: string;
+    chainDepth?: number;
+    retryPolicy?: RetryPolicy;
+    metadata?: Record<string, unknown>;
+}
+export interface TaskRecord extends Required<Pick<TaskDefinition, "title" | "priority">> {
+    id: string;
+    description: string;
+    assigneeId?: string;
+    status: TaskStatus;
+    priority: number;
+    parentId?: string;
+    dependsOn: string[];
+    followupAgentId?: string;
+    followupTemplate?: string;
+    chainOriginId?: string;
+    chainDepth: number;
+    retryPolicy?: RetryPolicy;
+    retryCount: number;
+    maxRetries: number;
+    nextRetryAt?: string;
+    executionRunId?: string;
+    result?: string;
+    completedOutput?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    deletedAt?: string;
+}

package/dist/shared/types/workflow.d.ts

@@ -0,0 +1,39 @@
+/** Workflow types — Story 1.5 / 5.1 */
+export type WorkflowRunStatus = "running" | "completed" | "failed" | "cancelled";
+export interface WorkflowStep {
+    id: string;
+    name: string;
+    agentSlug?: string;
+    agentResolver?: string;
+    taskTemplate: {
+        title: string;
+        description: string;
+    };
+    dependsOn?: string[];
+    onComplete?: "next" | "parallel" | "end";
+    onFail?: "abort" | "skip" | "retry";
+    retryPolicy?: import("./task.js").RetryPolicy;
+    condition?: string;
+}
+export interface WorkflowDefinition {
+    slug: string;
+    name: string;
+    description?: string;
+    steps: WorkflowStep[];
+    trigger?: WorkflowTrigger;
+}
+export interface WorkflowTrigger {
+    type: "task_completed" | "event" | "schedule" | "manual";
+    filter?: Record<string, unknown>;
+}
+export interface WorkflowRunRecord {
+    id: string;
+    workflowId: string;
+    status: WorkflowRunStatus;
+    currentStep: number;
+    context: Record<string, unknown>;
+    originTaskId?: string;
+    startedAt: string;
+    finishedAt?: string;
+    error?: string;
+}

package/dist/shared/utils.d.ts

@@ -0,0 +1,6 @@
+/** Shared utility functions. */
+/**
+ * Truncate text at a word boundary, appending "..." if truncated.
+ * Returns the original text if it's shorter than maxLen.
+ */
+export declare function truncateAtWord(text: string, maxLen: number): string;

package/dist/update-check.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Check the npm registry for a newer version. Caches results for 24 hours.
+ * Returns the latest version string if an update is available, null otherwise.
+ */
+export declare function checkForUpdate(pkgName: string, currentVersion: string): Promise<string | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botinabox",
-  "version": "2.9.1",
+  "version": "2.9.3",
   "description": "Bot in a Box — framework for building multi-agent bots",
   "type": "module",
   "main": "./dist/index.js",
@@ -50,7 +50,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc --emitDeclarationOnly",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "check-docs": "echo 'Documentation check passed'",
@@ -60,7 +60,7 @@
     "@types/uuid": "^10.0.0",
     "ajv": "^8.17.1",
     "cron-parser": "^4.9.0",
-    "latticesql": "^1.6.6",
+    "latticesql": "^1.6.10",
     "uuid": "^13.0.0",
     "yaml": "^2.7.0"
   },

package/dist/channel-DziSPayj.d.ts

@@ -1,73 +0,0 @@
-/** Channel adapter types — Story 1.5 / 4.1 */
-type ChatType = "direct" | "group" | "channel";
-type FormattingMode = "markdown" | "mrkdwn" | "html" | "plain";
-interface ChannelCapabilities {
-    chatTypes: ChatType[];
-    threads: boolean;
-    reactions: boolean;
-    editing: boolean;
-    media: boolean;
-    polls: boolean;
-    maxTextLength: number;
-    formattingMode: FormattingMode;
-}
-interface ChannelMeta {
-    displayName: string;
-    icon?: string;
-    homepage?: string;
-}
-interface InboundMessage {
-    id: string;
-    channel: string;
-    account?: string;
-    from: string;
-    userId?: string;
-    body: string;
-    threadId?: string;
-    replyToId?: string;
-    attachments?: Attachment[];
-    receivedAt: string;
-    raw?: unknown;
-}
-type AttachmentMediaType = "image" | "video" | "audio" | "pdf" | "doc" | "excel" | "presentation" | "html" | "link" | "misc";
-interface Attachment {
-    type: AttachmentMediaType;
-    url?: string;
-    mimeType?: string;
-    filename?: string;
-    size?: number;
-}
-interface OutboundPayload {
-    text: string;
-    threadId?: string;
-    replyToId?: string;
-    attachments?: Attachment[];
-}
-interface SendResult {
-    success: boolean;
-    messageId?: string;
-    error?: string;
-}
-interface HealthStatus {
-    ok: boolean;
-    latencyMs?: number;
-    error?: string;
-}
-type ChannelConfig = Record<string, unknown>;
-interface ChannelAdapter {
-    /** Unique identifier for this adapter instance */
-    id: string;
-    meta: ChannelMeta;
-    capabilities: ChannelCapabilities;
-    connect(config: ChannelConfig): Promise<void>;
-    disconnect(): Promise<void>;
-    healthCheck(): Promise<HealthStatus>;
-    send(target: {
-        peerId: string;
-        threadId?: string;
-    }, payload: OutboundPayload): Promise<SendResult>;
-    /** Called when a message arrives — set by the framework */
-    onMessage?: (message: InboundMessage) => Promise<void>;
-}
-
-export type { Attachment as A, ChannelAdapter as C, FormattingMode as F, HealthStatus as H, InboundMessage as I, OutboundPayload as O, SendResult as S, AttachmentMediaType as a, ChannelCapabilities as b, ChannelConfig as c, ChannelMeta as d, ChatType as e };