botinabox 1.8.2 → 1.8.3

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

package/dist/update-check.js

@@ -0,0 +1,56 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const ONE_DAY_MS = 86_400_000;
+function isNewer(latest, current) {
+    const a = latest.split('.').map(Number);
+    const b = current.split('.').map(Number);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        if (av > bv)
+            return true;
+        if (av < bv)
+            return false;
+    }
+    return false;
+}
+/**
+ * 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 async function checkForUpdate(pkgName, currentVersion) {
+    const cacheDir = join(homedir(), `.${pkgName}`);
+    const cachePath = join(cacheDir, 'update-check.json');
+    // Check cache first
+    try {
+        if (existsSync(cachePath)) {
+            const cached = JSON.parse(readFileSync(cachePath, 'utf-8'));
+            if (Date.now() - cached.checked < ONE_DAY_MS) {
+                return isNewer(cached.latest, currentVersion) ? cached.latest : null;
+            }
+        }
+    }
+    catch {
+        // Cache corrupt or unreadable — proceed to fetch
+    }
+    // Fetch latest version from npm
+    const res = await fetch(`https://registry.npmjs.org/${pkgName}/latest`, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    const latest = data.version;
+    // Write cache
+    try {
+        if (!existsSync(cacheDir))
+            mkdirSync(cacheDir, { recursive: true });
+        writeFileSync(cachePath, JSON.stringify({ latest, checked: Date.now() }));
+    }
+    catch {
+        // Non-critical — skip caching
+    }
+    return isNewer(latest, currentVersion) ? latest : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botinabox",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "Bot in a Box — framework for building multi-agent bots",
   "type": "module",
   "main": "./dist/index.js",