botinabox 2.9.0 → 2.9.2

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/shared/types/provider.d.ts

@@ -0,0 +1,87 @@
+/** 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;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+} | {
+    type: "document";
+    source: {
+        type: "base64";
+        media_type: "application/pdf";
+        data: 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/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.0",
+  "version": "2.9.2",
   "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'",