@ai-setting/roy-agent-core 1.7.51 → 1.7.53

package/dist/env/workflow/service/workflow-service.d.ts

@@ -0,0 +1,422 @@
+/**
+ * WorkflowService - Session-based Workflow Execution
+ *
+ * After session-based refactoring, workflow runs are managed via SessionComponent.
+ * The workflows table is still used for storing workflow definitions.
+ *
+ * Key concepts:
+ * - Session IS a workflow run (no separate runId concept)
+ * - Session.metadata stores workflow run state (status, input, agentSessions)
+ * - Session.messages stores node execution history with workflow.node.* roles
+ * - Resume is based on session state and messages
+ */
+import type { Workflow, WorkflowDefinition, RunOptions, RunResult, WorkflowMetadata, WorkflowConfig } from '../types';
+export interface WorkflowRepository {
+    create(workflow: Omit<Workflow, 'id' | 'createdAt' | 'updatedAt'>): Workflow;
+    getById(id: string): Workflow | null;
+    getByName(name: string): Workflow | null;
+    list(options?: ListOptions): Workflow[];
+    update(id: string, updates: Partial<Workflow>): Workflow | null;
+    delete(id: string): boolean;
+    /** v2: 在事务中执行一个函数，回滚任何抛出 */
+    transaction<T>(fn: () => T): T;
+    /** v4: 拿过滤后的全局总数（不应用 limit/offset） */
+    countAll(options?: {
+        tag?: string;
+        tags?: string[];
+        taskId?: number;
+        search?: string;
+    }): number;
+}
+export interface ITagRepository {
+    upsertMany(names: string[]): void;
+    decrementMany(names: string[]): void;
+    list(options?: {
+        sortBy?: "usage_count" | "name" | "created_at";
+        order?: "asc" | "desc";
+        limit?: number;
+    }): {
+        name: string;
+        usage_count: number;
+        created_at: string;
+        updated_at: string;
+    }[];
+    get(name: string): {
+        name: string;
+        usage_count: number;
+        created_at: string;
+        updated_at: string;
+    } | undefined;
+}
+export interface ListWorkflowsWithTagsResult {
+    workflows: Workflow[];
+    available_tags: {
+        name: string;
+        count: number;
+    }[];
+    total: number;
+}
+export interface SearchWorkflowsWithTagsResult extends ListWorkflowsWithTagsResult {
+    keyword?: string;
+    tags?: string[];
+}
+import type { NodeDefinition } from '../types';
+/**
+ * Tag validation constants
+ *
+ * Tags are required for all workflows and are constrained to:
+ * - At least 1 tag
+ * - At most 3 tags
+ *
+ * This supports fine-grained workflow discovery (filtering) while preventing
+ * tag spam.
+ */
+export declare const TAG_MIN_COUNT = 1;
+export declare const TAG_MAX_COUNT = 3;
+export declare const DEFAULT_TAG = "default";
+export declare class TagValidationError extends Error {
+    constructor(message: string);
+}
+export interface CreateOptions {
+    tags?: string[];
+    metadata?: WorkflowMetadata;
+    taskId?: number;
+    force?: boolean;
+}
+export interface ListOptions {
+    tag?: string;
+    taskId?: number;
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface SearchOptions {
+    keyword?: string;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+}
+export interface WorkflowUpdates {
+    definition?: WorkflowDefinition;
+    config?: WorkflowConfig;
+    tags?: string[];
+    metadata?: WorkflowMetadata;
+}
+export interface WorkflowEngine {
+    createSession(workflowId: string, options?: {
+        input?: Record<string, any>;
+        workflowName?: string;
+        workflowVersion?: string;
+    }): Promise<string>;
+    run(sessionId: string, options?: RunOptions): Promise<RunResult>;
+    runWorkflow(workflow: Workflow | WorkflowDefinition, options?: RunOptions): Promise<RunResult>;
+    stop(sessionId: string, reason?: string): Promise<void>;
+    addNode(sessionId: string, nodeDefinition: NodeDefinition): Promise<void>;
+    removeNode(sessionId: string, nodeId: string): Promise<void>;
+}
+export type WorkflowEngineFactory = (workflow: Workflow, options?: RunOptions) => Pick<WorkflowEngine, 'run' | 'stop' | 'runWorkflow'>;
+export interface SessionInfo {
+    id: string;
+    title: string;
+    metadata: WorkflowSessionMetadata;
+    createdAt: Date;
+    updatedAt: Date;
+    /**
+     * Task #1739 — top-level parent session id (mirrors legacy `parentID`).
+     * Workflow sessions created by a sub-agent carry the sub-agent's session id
+     * here, so cascade-stop queries (`WorkflowService.stopAllForParent`) can
+     * find them. May be null for top-level sessions.
+     */
+    parentSessionId?: string | null;
+}
+export interface WorkflowSessionMetadata {
+    type: 'workflow';
+    runId?: string;
+    workflowId?: string;
+    workflowName: string;
+    workflowVersion?: string;
+    status: 'running' | 'paused' | 'completed' | 'failed' | 'stopped';
+    input?: any;
+    rootNodeId?: string;
+    agentSessions?: AgentSessionRef[];
+}
+export interface AgentSessionRef {
+    nodeId: string;
+    sessionId: string;
+    status: 'active' | 'paused' | 'completed';
+}
+export declare class WorkflowService {
+    private workflowRepository;
+    private engineFactory;
+    private sessionComponent?;
+    /**
+     * v2: 可选 tag 仓库，用于维护 workflow_tags 表
+     */
+    tagRepository?: ITagRepository;
+    constructor(workflowRepository: WorkflowRepository, engineFactory: WorkflowEngineFactory, sessionComponent?: {
+        create(options: {
+            id?: string;
+            title: string;
+            metadata: any;
+        }): Promise<{
+            id: string;
+        }>;
+        get(id: string): Promise<SessionInfo | null | undefined>;
+        list?(options?: {
+            limit?: number;
+            offset?: number;
+        }): Promise<SessionInfo[]>;
+        update(id: string, updates: {
+            metadata?: any;
+        }): Promise<boolean>;
+        addMessage(sessionId: string, message: any): Promise<string>;
+        getMessages(sessionId: string): Promise<any[]>;
+    } | undefined, tagRepository?: ITagRepository);
+    /**
+     * Task #2245 — Codex P1-2: paginated session fetch.
+     *
+     * Fetches ALL workflow sessions via `sessionComponent.list` with
+     * `limit: 1000` chunks, accumulated until a short batch signals EOF.
+     * This replaces the previous single-call `list({ limit: 1000 })`
+     * which silently dropped sessions beyond the first 1000.
+     *
+     * Safety cap of 50,000 total sessions to prevent runaway fetches
+     * against an unbounded `sessionComponent.list` implementation.
+     */
+    private listAllSessions;
+    /**
+     * Task #2245 — Engine instance cache (BL-1).
+     *
+     * Maps sessionId → WorkflowEngine instance that actually owns the run.
+     * The engineFactory returns a NEW WorkflowEngine on every call, but
+     * `WorkflowEngine.activeSessions` is a private per-instance Map. So a
+     * freshly-created engine has no record of the running session, and its
+     * `stop(sessionId)` only updates the database (no abort, no executor
+     * cancel). This cache lets `stopRun` locate the real engine.
+     *
+     * Lifecycle: `runWorkflow` registers the engine after `runWorkflow()`
+     * returns (which synchronously populates `engine.activeSessions` before the
+     * first await). `stopRun` consults the cache first; on miss it falls back
+     * to a fresh engine (DB-only stop).
+     */
+    /**
+     * Task #2245 — Codex P0-1: cache engine instance per workflowName so
+     * `stopRun` can find the engine during in-flight execution.
+     *
+     * Previous design cached by `sessionId` AFTER `engine.runWorkflow()`
+     * returned — useless for the in-flight case. New design caches by
+     * `workflowName` (one engine owns the named workflow), so the engine
+     * is registered BEFORE `runWorkflow` is awaited and is available
+     * for `stopRun` at any time during execution.
+     *
+     * `workflowName` → `WorkflowEngine` (one engine owns the workflow's
+     * `activeSessions` Map, including any in-flight or completed sessions).
+     */
+    private engineInstances;
+    /**
+     * Codex P0-1: reverse index `sessionId` → `engine` for O(1) stopRun lookup.
+     * Populated when the engine is registered (BEFORE runWorkflow) and
+     * cleaned up via pruneStaleEngines() / dispose().
+     */
+    private sessionToEngine;
+    /**
+     * P0-3 (Task #2269): reverse index `sessionId` → `parentSessionId` for
+     * precise `hasActiveWorkflowForParent` lookup. Populated when runWorkflow
+     * resolves (the engine factory call carries `parentSessionId` via
+     * `options`) and cleaned up when the session is force-stopped / stopped
+     * via stopRun. Without this, hasActiveWorkflowForParent would have to
+     * iterate ALL engines and return true on any active session — false
+     * positives in multi-REPL scenarios.
+     */
+    private sessionToParent;
+    /**
+     * Validate tag count is within allowed range (1-3 tags).
+     * Throws TagValidationError with a friendly message on failure.
+     */
+    private validateTags;
+    /**
+     * Create a new workflow from definition
+     *
+     * v2: create + tag upsert 在同一事务（由 WorkflowRepository.transaction 包装）
+     */
+    createWorkflow(definition: WorkflowDefinition, options?: CreateOptions): Promise<Workflow>;
+    /**
+     * v2: 在 update 时同步 tag 表
+     */
+    private syncTagsOnUpdate;
+    /**
+     * Get workflow by id or name
+     */
+    getWorkflow(idOrName: string): Workflow | null;
+    /**
+     * Get workflow by id
+     */
+    getWorkflowById(id: string): Workflow | null;
+    /**
+     * Get workflow by name
+     */
+    getWorkflowByName(name: string): Workflow | null;
+    /**
+     * List workflows with optional filters
+     */
+    listWorkflows(options?: ListOptions): Workflow[];
+    /**
+     * Search workflows with combined keyword + multi-tag AND filter.
+     *
+     * - `keyword`: matched (case-insensitive) against name and description
+     * - `tags`: ALL tags must be present on the workflow (AND filter)
+     * - `limit`/`offset`: pagination
+     */
+    searchWorkflows(options?: SearchOptions): Workflow[];
+    /**
+     * Update an existing workflow
+     */
+    updateWorkflow(idOrName: string, updates: WorkflowUpdates, options?: {
+        tags?: string[];
+    }): Promise<Workflow>;
+    /**
+     * Delete a workflow by name or id
+     *
+     * v2: delete + tag decrement 在同一事务
+     */
+    deleteWorkflow(idOrName: string): Promise<boolean>;
+    /**
+     * v2: list workflows + available_tags（按 usage_count DESC, name ASC）
+     * v4: total 字段修复 — 使用 repository.countAll() 拿过滤后全局总数
+     */
+    listWorkflowsWithTags(options?: ListOptions): Promise<ListWorkflowsWithTagsResult>;
+    /**
+     * v2: search workflows + available_tags
+     * v4: total 字段修复 — 使用 repository.countAll() 拿过滤后全局总数
+     */
+    searchWorkflowsWithTags(options?: SearchOptions): Promise<SearchWorkflowsWithTagsResult>;
+    /**
+     * v3: List all tags from the workflow_tags table with flexible sort/limit.
+     *
+     * Used by:
+     * - `workflow_tag_list` MCP tool (lets agents discover the tag pool)
+     * - `workflow tag list` CLI subcommand
+     *
+     * Default sort: usage_count DESC, name ASC (most-used tags first).
+     */
+    listTags(options?: {
+        sortBy?: 'usage_count' | 'name' | 'created_at';
+        order?: 'asc' | 'desc';
+        limit?: number;
+    }): Promise<{
+        tags: Array<{
+            name: string;
+            usage_count: number;
+            created_at: string;
+            updated_at: string;
+        }>;
+        total: number;
+    }>;
+    /**
+     * v3: Get a single tag by name (returns undefined when not found).
+     */
+    getTag(name: string): {
+        name: string;
+        usage_count: number;
+        created_at: string;
+        updated_at: string;
+    } | undefined;
+    /**
+     * Run a workflow by definition or name
+     *
+     * This creates a Session that represents the workflow run.
+     * The Session ID is used as the run identifier for pause/resume.
+     */
+    runWorkflow(idOrNameOrDefinition: string | WorkflowDefinition, input?: Record<string, any>, options?: RunOptions): Promise<RunResult>;
+    /**
+     * Run workflow by name (convenience method)
+     */
+    runWorkflowByName(name: string, input?: Record<string, any>, options?: RunOptions): Promise<RunResult>;
+    /**
+     * Stop a running workflow session
+     */
+    stopRun(sessionId: string, reason?: string): Promise<void>;
+    /**
+     * Codex P0-2: prune engineInstances entries whose `activeSessions` map
+     * no longer contains any session (engine is "stale" — no in-flight work).
+     * Called after stopRun / dispose to prevent the engine cache from
+     * accumulating engines across long-running REPL sessions.
+     */
+    private pruneStaleEngines;
+    /**
+     * Codex P0-2: dispose all engine caches. Called from
+     * BackgroundTaskManager.dispose() or directly on service shutdown.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Task #2245 — ESC cascade stop.
+     *
+     * Stop all workflow sessions whose `parentSessionId === parentSessionId` and
+     * whose metadata is type=workflow with status in {running, paused}. Calls
+     * the existing `stopRun(sessionId, reason)` per entry, which already invokes
+     * `engine.stop()` and cascades mark of nested agent sessions (Task #1837).
+     *
+     * Returns `{ stoppedSessionIds, errors }` for audit / caller logging.
+     * P1-#7: errors array includes per-session failure details so
+     * cascadeStopSessionTree can surface them in CascadeStopResult.errors.
+     *
+     * Idempotent: re-running on an already-stopped set is a no-op for those
+     * sessions; running/paused entries that succeeded are returned.
+     */
+    hasActiveWorkflowForParent(parentSessionId: string): boolean;
+    stopAllForParent(parentSessionId: string): Promise<{
+        stoppedSessionIds: string[];
+        errors: Array<{
+            sessionId: string;
+            error: string;
+            stack?: string;
+        }>;
+    }>;
+    /**
+     * Task #2245 — ESC force-stop (second-press within 2s window).
+     *
+     * Traverse ALL workflow sessions (regardless of parent), mark running/paused
+     * ones as `stopped` via sessionComponent.update. Used as the force path when
+     * `stopAllForParent` (graceful) leaves residual orphans.
+     *
+     * Idempotent: re-running on already-stopped sessions is a no-op.
+     * Does NOT invoke engine.stop() — direct DB mark is sufficient for force
+     * cleanup; engine session has either completed or is being torn down.
+     */
+    forceStopAll(): Promise<void>;
+    /**
+     * Resume an existing workflow session.
+     *
+     * Looks up the session, verifies it's a workflow session, resolves the
+     * workflow definition from session metadata, then re-enters execution
+     * via `engine.run(sessionId, options)`. The engine's unified `run()`
+     * detects the existing session and infers the resume point from
+     * persisted messages (Task #1829).
+     *
+     * Replaces the CLI's `(service as any).engineFactory` hack with a
+     * proper public API.
+     *
+     * @param sessionId - Existing workflow runId/sessionId (Task #1837:
+     *                    runId == sessionId, both start with `workflow_`)
+     * @param options - Optional RunOptions (input is forwarded as userResponse
+     *                  for ask_user interrupt resume paths)
+     * @returns Promise resolving to RunResult
+     * @throws Error when session not found / not a workflow session / workflow not registered
+     */
+    resumeSession(sessionId: string, options?: RunOptions): Promise<RunResult>;
+    /**
+     * Get workflow session by ID
+     */
+    getSession(sessionId: string): Promise<SessionInfo | null>;
+    /**
+     * List workflow sessions
+     */
+    listSessions(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<SessionInfo[]>;
+    /**
+     * Get messages from a workflow session
+     */
+    getSessionMessages(sessionId: string): Promise<any[]>;
+}

package/dist/env/workflow/storage/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Workflow Storage Module
+ *
+ * Re-exports all storage components for the workflow component.
+ *
+ * Note: After session-based refactoring, workflow runs are now managed via SessionComponent.
+ * The workflows table is still used for storing workflow definitions.
+ */
+export { getDatabase, closeDatabase, initializeTables, getDatabasePath, resetDatabase, initDatabase, type BunDatabase, } from './sqlite';
+export { WorkflowRepository, rowToWorkflow, migrateEmptyTagsToDefault, type WorkflowRow, type ListWorkflowsOptions, type UpdateWorkflowOptions, } from './workflow-repo';
+export { TagRepository, type TagInfo, } from './tag-repo';

package/dist/env/workflow/storage/mock-repositories.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Mock Repositories for Testing
+ *
+ * Note: After session-based refactoring, workflow runs are managed via SessionComponent.
+ * These mock repositories only handle workflow definitions.
+ */
+import type { Workflow, WorkflowRun, RunStatus } from '../types';
+export interface MockRunRepositoryOptions {
+    workflowId?: string;
+    workflowName?: string;
+}
+export declare class MockRunRepository {
+    private runs;
+    private options;
+    constructor(options?: MockRunRepositoryOptions);
+    setWorkflowInfo(workflowId: string, workflowName: string): void;
+    createWorkflowRun(run: Omit<WorkflowRun, 'id'>): WorkflowRun;
+    getWorkflowRun(id: string): WorkflowRun | null;
+    listWorkflowRuns(workflowId?: string, options?: {
+        status?: RunStatus;
+    }): WorkflowRun[];
+    updateWorkflowRun(id: string, updates: Partial<WorkflowRun>): WorkflowRun | null;
+    clear(): void;
+    count(): number;
+    setWorkflowName(name: string): void;
+}
+export declare class MockWorkflowRepository {
+    private workflows;
+    private nameIndex;
+    create(workflow: Omit<Workflow, 'id' | 'createdAt' | 'updatedAt'>): Workflow;
+    getById(id: string): Workflow | null;
+    getByName(name: string): Workflow | null;
+    list(options?: {
+        tag?: string;
+        limit?: number;
+        offset?: number;
+    }): Workflow[];
+    update(id: string, updates: Partial<Workflow>): Workflow | null;
+    delete(id: string): boolean;
+    exists(name: string): boolean;
+    clear(): void;
+    count(): number;
+    /**
+     * v4: 拿过滤后的全局总数（不应用 limit/offset）
+     *
+     * 与 list() 共享 tag 过滤逻辑，但忽略 limit/offset。
+     * 支持单 tag (SQL 风格) 和多 tag AND。
+     */
+    countAll(options?: {
+        tag?: string;
+        tags?: string[];
+        taskId?: number;
+        search?: string;
+    }): number;
+    /**
+     * v2: in-memory 事务支持
+     *
+     * 通过快照/回滚实现：拷贝当前 state，函数成功则 commit，失败则恢复快照。
+     */
+    transaction<T>(fn: () => T): T;
+}
+export interface MockEngineCall {
+    method: string;
+    args: any[];
+    result?: any;
+    timestamp: number;
+}
+export type MockEngineFactory = () => MockWorkflowEngine;
+export declare class MockWorkflowEngine {
+    calls: MockEngineCall[];
+    private sessionResults;
+    private workflowName;
+    constructor();
+    setWorkflowName(name: string): void;
+    getWorkflowName(): string;
+    createSession(workflowId: string, options?: {
+        input?: Record<string, any>;
+        workflowName?: string;
+        workflowVersion?: string;
+    }): Promise<string>;
+    createRun(workflowNameOrDefinition: string | any, options?: {
+        input?: Record<string, any>;
+        debug?: boolean;
+    }): Promise<string>;
+    run(runId: string, options?: any): Promise<any>;
+    runWorkflow(workflow: any, options?: any): Promise<any>;
+    pause(sessionId: string): Promise<void>;
+    resume(sessionId: string, options?: {
+        userResponse?: string;
+        pendingNodeId?: string;
+        agentSessionId?: string;
+    }): Promise<any>;
+    stop(sessionId: string, reason?: string): Promise<void>;
+    addNode(sessionId: string, nodeDefinition: any): Promise<void>;
+    removeNode(sessionId: string, nodeId: string): Promise<void>;
+    clearCalls(): void;
+    getLastCall(): MockEngineCall | undefined;
+    getCallsByMethod(method: string): MockEngineCall[];
+}
+export declare class MockNodeRegistry {
+    private nodes;
+    register(type: string, factory: any): void;
+    get(type: string): any;
+    has(type: string): boolean;
+    list(): string[];
+}

package/dist/env/workflow/storage/safe-json.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Safe JSON parsing helpers for storage layer
+ *
+ * 历史背景：Bug 修复 Task #4033 / Task #4037
+ * ----------------------------------------------------------------
+ * Bug #4033：task-store 的 rowToTask 对 tags 字段做裸 `JSON.parse`，
+ *   当 tags 被存成 CSV 字符串 `'html-styling, css-refactor, v34, ...'`
+ *   时抛 SyntaxError，整个 `tasks list` 命令挂掉。
+ *
+ * Bug #4037（sibling-risk）：workflow-repo 的 rowToWorkflow 同样有 4 处
+ *   裸 JSON.parse（metadata / definition / config / tags），本文件统一
+ *   收口成 4 个语义明确的 helper：
+ *
+ *   - parseJsonOrThrow(raw, fieldName, rowCtx)
+ *       业务关键字段（definition / metadata）损坏时直接抛错。
+ *       错误信息带 fieldName + row.name + row.id，便于排查。
+ *       原则：宁可让上层在 ReportError 路径上挂掉，也别返回 silent-corrupt 数据。
+ *
+ *   - parseJsonObjectOrEmpty(raw, fieldName)
+ *       辅助对象字段（config）损坏时 fallback 到 {}。
+ *
+ *   - parseTagsSafely(raw)
+ *       tags 字段专用，复用 task-store 的 5-tier fallback 策略：
+ *         1. null/undefined/空串 → []
+ *         2. 合法 JSON 数组 → 原样返回
+ *         3. 合法 JSON 但不是数组（如 "tag1" 单字符串）→ 包成单元素数组
+ *         4. 非法 JSON（CSV / 纯文本）→ 当作单个 tag，包成单元素数组
+ *         5. 其他类型 → []
+ *
+ *   - parseJsonArrayOrEmpty(raw, fieldName)
+ *       通用数组字段 fallback（如未来 workflow_tags 表新增数组字段）。
+ *       当前 task-store 的 parseTagsSafely 是 private static，未来重构时
+ *       可以考虑迁到这里以避免重复。
+ */
+export interface RowContext {
+    /** 数据库行 id（UUID），用于错误信息定位 */
+    id?: string;
+    /** workflow/task 名字，便于人在错误里直接 grep */
+    name?: string;
+}
+/**
+ * 业务关键字段：损坏时抛错，错误信息带 fieldName + row.name + row.id。
+ *
+ * @throws {Error} 包含 fieldName / row.name / row.id / 原始片段
+ */
+export declare function parseJsonOrThrow<T = unknown>(raw: unknown, fieldName: string, rowCtx?: RowContext): T;
+/**
+ * 辅助对象字段：损坏时 fallback 到 {}，不抛错。
+ */
+export declare function parseJsonObjectOrEmpty<T extends object = Record<string, unknown>>(raw: unknown, fieldName: string): T;
+/**
+ * 通用数组字段 fallback。
+ * 损坏时返回 []，不抛错。
+ */
+export declare function parseJsonArrayOrEmpty<T = unknown>(raw: unknown, fieldName: string): T[];
+/**
+ * tags 字段专用，语义与 task-store 的 parseTagsSafely 完全一致。
+ *
+ * 未来如果 task-store 的 private static parseTagsSafely 重构到这里，
+ * 可以从 sqlite-task-store.ts 删掉私有版本，统一从本函数导入。
+ */
+export declare function parseTagsSafely(raw: unknown): string[];

package/dist/env/workflow/storage/sqlite.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview SQLite Storage for Workflow Component
+ *
+ * 根据运行环境自动选择 SQLite 实现：
+ * - Bun 运行时：使用 bun:sqlite
+ * - Node.js/Electron：使用 better-sqlite3
+ *
+ * 存储路径：~/.local/share/roy-agent/workflows.db
+ *
+ * Note: After session-based refactoring, workflow runs are managed via SessionComponent.
+ * Only the workflows table is used here for storing workflow definitions.
+ */
+/**
+ * Get the database file path
+ * Default: ~/.local/share/roy-agent/workflows.db
+ */
+export declare function getDatabasePath(): string;
+/**
+ * Get the singleton database instance
+ * @param path - Optional custom database path. If not provided, uses default path.
+ *               Use ':memory:' for in-memory database (testing)
+ */
+export declare function getDatabase(path?: string): any;
+/**
+ * Close the database connection
+ */
+export declare function closeDatabase(): void;
+export type BunDatabase = {
+    exec(sql: string): void;
+    query<T>(sql: string): {
+        all(): T[];
+        get(...params: any[]): T | null;
+    };
+    run(sql: string, ...params: any[]): {
+        lastInsertRowid: number;
+        changes: number;
+    };
+    close(): void;
+    pragma?: (sql: string) => void;
+};
+/**
+ * Initialize all required tables
+ *
+ * Note: Only workflows table is created. Workflow runs are managed via SessionComponent
+ * using the session/message storage, following the session-based design.
+ */
+export declare function initializeTables(): void;
+/**
+ * Reset the database instance (for testing purposes)
+ * This is useful for tests that need a fresh database
+ */
+export declare function resetDatabase(): void;
+/**
+ * Initialize tables and return a ready database
+ * This is a convenience function that combines getDatabase and initializeTables
+ */
+export declare function initDatabase(path?: string): any;