botinabox 2.5.0 → 2.5.2

package/dist/shared/constants.js

@@ -0,0 +1,64 @@
+/** Shared constants — event names, default values, status enums */
+/** Hook/event name constants */
+export const EVENTS = {
+    // Cost
+    COST_RECORDED: "cost.recorded",
+    // Agent
+    AGENT_CREATED: "agent.created",
+    AGENT_STATUS_CHANGED: "agent.status_changed",
+    BUDGET_EXCEEDED: "budget.exceeded",
+    // Task
+    TASK_CREATED: "task.created",
+    TASK_COMPLETED: "task.completed",
+    TASK_FAILED: "task.failed",
+    TASK_CANCELLED: "task.cancelled",
+    // Run
+    RUN_STARTED: "run.started",
+    RUN_COMPLETED: "run.completed",
+    RUN_FAILED: "run.failed",
+    // Message pipeline
+    MESSAGE_INBOUND: "message.inbound",
+    MESSAGE_ROUTED: "message.routed",
+    MESSAGE_PROCESSED: "message.processed",
+    MESSAGE_OUTBOUND: "message.outbound",
+    MESSAGE_SENT: "message.sent",
+    // Updates
+    UPDATE_AVAILABLE: "update.available",
+    UPDATE_STARTED: "update.started",
+    UPDATE_COMPLETED: "update.completed",
+    UPDATE_FAILED: "update.failed",
+    // Workflow
+    WORKFLOW_STARTED: "workflow.started",
+    WORKFLOW_STEP_COMPLETED: "workflow.step_completed",
+    WORKFLOW_COMPLETED: "workflow.completed",
+    WORKFLOW_FAILED: "workflow.failed",
+};
+/** Default config values */
+export const DEFAULTS = {
+    TASK_POLL_INTERVAL_MS: 30_000,
+    NOTIFICATION_POLL_INTERVAL_MS: 5_000,
+    ORPHAN_REAP_INTERVAL_MS: 300_000, // 5 minutes
+    STALE_RUN_THRESHOLD_MS: 1_800_000, // 30 minutes
+    STALE_TASK_AGE_MS: 7_200_000, // 2 hours
+    MAX_CHAIN_DEPTH: 5,
+    MAX_NOTIFICATION_RETRIES: 3,
+    UPDATE_CHECK_INTERVAL_MS: 86_400_000, // 24 hours
+    RENDER_WATCH_INTERVAL_MS: 30_000,
+    DATA_PATH: "./data/bot.db",
+    RENDER_OUTPUT_DIR: "./context",
+    LOG_PATH_TEMPLATE: "./data/runs/{runId}.ndjson",
+    BUDGET_WARN_PERCENT: 80,
+};
+/** Task status values */
+export const TASK_STATUSES = [
+    "backlog", "todo", "in_progress", "in_review",
+    "done", "blocked", "cancelled",
+];
+/** Agent status values */
+export const AGENT_STATUSES = [
+    "idle", "running", "paused", "terminated", "error",
+];
+/** Run status values */
+export const RUN_STATUSES = [
+    "queued", "running", "succeeded", "failed", "cancelled",
+];

package/dist/shared/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @botinabox/shared — Shared types and interfaces for all Bot in a Box packages.
+ * Zero runtime dependencies.
+ */
+export * from "./types/channel.js";
+export * from "./types/provider.js";
+export * from "./types/execution.js";
+export * from "./types/agent.js";
+export * from "./types/task.js";
+export * from "./types/config.js";
+export * from "./types/connector.js";
+export * from "./types/workflow.js";
+export * from "./constants.js";
+export * from "./utils.js";

package/dist/shared/index.js

@@ -0,0 +1,14 @@
+/**
+ * @botinabox/shared — Shared types and interfaces for all Bot in a Box packages.
+ * Zero runtime dependencies.
+ */
+export * from "./types/channel.js";
+export * from "./types/provider.js";
+export * from "./types/execution.js";
+export * from "./types/agent.js";
+export * from "./types/task.js";
+export * from "./types/config.js";
+export * from "./types/connector.js";
+export * from "./types/workflow.js";
+export * from "./constants.js";
+export * from "./utils.js";

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

@@ -0,0 +1,36 @@
+/** Agent types — Story 1.5 / 3.1 */
+export type AgentStatus = "idle" | "running" | "paused" | "terminated" | "error";
+export interface AgentDefinition {
+    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 AgentRecord extends AgentDefinition {
+    id: string;
+    status: AgentStatus;
+    spentMonthlyCents: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string;
+}
+export interface AgentFilter {
+    status?: AgentStatus | AgentStatus[];
+    role?: string;
+    adapter?: string;
+}
+export interface BudgetCheck {
+    allowed: boolean;
+    status: "ok" | "warning" | "hard_stop";
+    spentCents: number;
+    limitCents?: number;
+    message?: string;
+}

package/dist/shared/types/agent.js

@@ -0,0 +1,2 @@
+/** Agent types — Story 1.5 / 3.1 */
+export {};

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

@@ -0,0 +1,70 @@
+/** Channel adapter types — Story 1.5 / 4.1 */
+export type ChatType = "direct" | "group" | "channel";
+export type FormattingMode = "markdown" | "mrkdwn" | "html" | "plain";
+export interface ChannelCapabilities {
+    chatTypes: ChatType[];
+    threads: boolean;
+    reactions: boolean;
+    editing: boolean;
+    media: boolean;
+    polls: boolean;
+    maxTextLength: number;
+    formattingMode: FormattingMode;
+}
+export interface ChannelMeta {
+    displayName: string;
+    icon?: string;
+    homepage?: string;
+}
+export interface InboundMessage {
+    id: string;
+    channel: string;
+    account?: string;
+    from: string;
+    userId?: string;
+    body: string;
+    threadId?: string;
+    replyToId?: string;
+    attachments?: Attachment[];
+    receivedAt: string;
+    raw?: unknown;
+}
+export interface Attachment {
+    type: "image" | "file" | "audio" | "video";
+    url?: string;
+    mimeType?: string;
+    filename?: string;
+    size?: number;
+}
+export interface OutboundPayload {
+    text: string;
+    threadId?: string;
+    replyToId?: string;
+    attachments?: Attachment[];
+}
+export interface SendResult {
+    success: boolean;
+    messageId?: string;
+    error?: string;
+}
+export interface HealthStatus {
+    ok: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+export type ChannelConfig = Record<string, unknown>;
+export 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>;
+}

package/dist/shared/types/channel.js

@@ -0,0 +1,2 @@
+/** Channel adapter types — Story 1.5 / 4.1 */
+export {};

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

@@ -0,0 +1,111 @@
+/** 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 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;
+    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/config.js

@@ -0,0 +1,2 @@
+/** Bot configuration types — Story 1.2 / 1.5 */
+export {};

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/connector.js

@@ -0,0 +1,2 @@
+/** Connector types — generic external service integrations. */
+export {};

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/shared/types/execution.js

@@ -0,0 +1,2 @@
+/** Execution adapter types — Story 1.5 / 3.4 / 3.5 */
+export {};

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

@@ -0,0 +1,73 @@
+/** LLM provider types — Story 1.5 / 2.1 */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export interface ChatMessage {
+    role: "user" | "assistant" | "system";
+    content: string | ContentBlock[];
+}
+export type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+};
+export interface ChatParams {
+    messages: ChatMessage[];
+    system?: string;
+    tools?: ToolDefinition[];
+    maxTokens?: number;
+    temperature?: number;
+    model: string;
+    abortSignal?: AbortSignal;
+}
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+export interface ChatResult {
+    content: string;
+    toolUses?: ToolUse[];
+    usage: TokenUsage;
+    model: string;
+    stopReason: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence";
+}
+export interface ToolUse {
+    id: string;
+    name: string;
+    input: unknown;
+}
+export interface ModelInfo {
+    id: string;
+    displayName: string;
+    contextWindow: number;
+    maxOutputTokens: number;
+    capabilities: Array<"chat" | "tools" | "vision" | "streaming">;
+    /** Cost in micro-cents per 1M tokens */
+    inputCostPerMToken?: number;
+    outputCostPerMToken?: number;
+}
+export interface ResolvedModel {
+    provider: string;
+    model: string;
+}
+export interface LLMProvider {
+    id: string;
+    displayName: string;
+    models: ModelInfo[];
+    chat(params: ChatParams): Promise<ChatResult>;
+    chatStream(params: ChatParams): AsyncGenerator<string, ChatResult, unknown>;
+    /** Convert ToolDefinition[] to provider-native format */
+    serializeTools(tools: ToolDefinition[]): unknown;
+}

package/dist/shared/types/provider.js

@@ -0,0 +1,2 @@
+/** LLM provider types — Story 1.5 / 2.1 */
+export {};

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/task.js

@@ -0,0 +1,2 @@
+/** Task types — Story 1.5 / 3.2 */
+export {};

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/types/workflow.js

@@ -0,0 +1,2 @@
+/** Workflow types — Story 1.5 / 5.1 */
+export {};

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/shared/utils.js

@@ -0,0 +1,13 @@
+/** Shared utility functions. */
+/**
+ * Truncate text at a word boundary, appending "..." if truncated.
+ * Returns the original text if it's shorter than maxLen.
+ */
+export function truncateAtWord(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    const truncated = text.slice(0, maxLen);
+    const lastSpace = truncated.lastIndexOf(" ");
+    const cutPoint = lastSpace > maxLen * 0.5 ? lastSpace : maxLen;
+    return truncated.slice(0, cutPoint) + "...";
+}

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>;