the-citadel 0.12.7

package/dist/config/index.d.ts

@@ -0,0 +1,6 @@
+import { type CitadelConfig, type CitadelConfigInput } from "./schema";
+export declare const CONFIG_KEY = "config_cache";
+export declare function loadConfig(): Promise<CitadelConfig>;
+export declare function setConfig(config: CitadelConfigInput): void;
+export declare function resetConfig(): void;
+export declare function getConfig(): CitadelConfig;

package/dist/config/schema.d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+export declare const ConfigSchema: z.ZodObject<{
+    env: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        production: "production";
+    }>>;
+    providers: z.ZodObject<{
+        openai: z.ZodOptional<z.ZodObject<{
+            apiKey: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        anthropic: z.ZodOptional<z.ZodObject<{
+            apiKey: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        ollama: z.ZodOptional<z.ZodObject<{
+            baseURL: z.ZodDefault<z.ZodString>;
+            apiKey: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    agents: z.ZodRecord<z.ZodString, z.ZodObject<{
+        provider: z.ZodEnum<{
+            openai: "openai";
+            anthropic: "anthropic";
+            ollama: "ollama";
+        }>;
+        model: z.ZodString;
+        mcpTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mcpResources: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>>;
+    mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        url: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>>;
+    worker: z.ZodObject<{
+        timeout: z.ZodDefault<z.ZodNumber>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+        costLimit: z.ZodDefault<z.ZodNumber>;
+        min_workers: z.ZodDefault<z.ZodNumber>;
+        max_workers: z.ZodDefault<z.ZodNumber>;
+        load_factor: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    gatekeeper: z.ZodDefault<z.ZodObject<{
+        min_workers: z.ZodDefault<z.ZodNumber>;
+        max_workers: z.ZodDefault<z.ZodNumber>;
+        load_factor: z.ZodDefault<z.ZodNumber>;
+        auto_close_epics: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    pearls: z.ZodObject<{
+        path: z.ZodDefault<z.ZodString>;
+        binary: z.ZodDefault<z.ZodString>;
+        autoSync: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+    bridge: z.ZodDefault<z.ZodObject<{
+        maxLogs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    context: z.ZodDefault<z.ZodObject<{
+        maxHistoryMessages: z.ZodDefault<z.ZodNumber>;
+        maxToolResponseSize: z.ZodDefault<z.ZodNumber>;
+        maxInspectContextSize: z.ZodDefault<z.ZodNumber>;
+        offloadThresholds: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        maxMessageSize: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    hooks: z.ZodOptional<z.ZodObject<{
+        onPearlStart: z.ZodOptional<z.ZodAny>;
+        onPearlDone: z.ZodOptional<z.ZodAny>;
+        onMoleculeStart: z.ZodOptional<z.ZodAny>;
+        onMoleculeDone: z.ZodOptional<z.ZodAny>;
+    }, z.core.$strip>>;
+    logging: z.ZodOptional<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        level: z.ZodDefault<z.ZodEnum<{
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+            error: "error";
+        }>>;
+        fileEnabled: z.ZodDefault<z.ZodBoolean>;
+        rotation: z.ZodDefault<z.ZodEnum<{
+            daily: "daily";
+            none: "none";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CitadelConfig = z.infer<typeof ConfigSchema>;
+export type CitadelConfigInput = z.input<typeof ConfigSchema>;
+export type AgentRole = string;
+export declare function defineConfig(config: CitadelConfigInput): CitadelConfigInput;

package/dist/core/agent.d.ts

@@ -0,0 +1,59 @@
+import { generateText, type LanguageModel, type ModelMessage, type Tool } from "ai";
+import { z } from "zod";
+import type { AgentRole } from "../config/schema";
+import { type PearlsClient } from "./pearls";
+export interface AgentContext {
+    pearlId?: string;
+    [key: string]: unknown;
+}
+export declare class AgentStepLimitReachedError extends Error {
+    constructor(message: string);
+}
+export interface ToolContext extends AgentContext {
+    toolCallId: string;
+    messages: ModelMessage[];
+    pearlsClient?: PearlsClient;
+}
+export declare abstract class CoreAgent {
+    protected role: AgentRole;
+    protected model: LanguageModel;
+    protected tools: Record<string, Tool>;
+    protected dynamicTools: Record<string, Tool>;
+    protected schemas: Record<string, z.ZodTypeAny>;
+    protected requiresExplicitCompletion: boolean;
+    protected pearlsClient?: PearlsClient;
+    constructor(role: AgentRole, model?: LanguageModel, pearlsClient?: PearlsClient);
+    /**
+     * Override this to provide tools dynamically based on context.
+     * These will be merged with registered static tools (like MCP tools).
+     */
+    protected getDynamicTools(_context?: AgentContext): Promise<Record<string, Tool>>;
+    private mcpLoaded;
+    protected executeGenerateText(messages: ModelMessage[]): Promise<Awaited<ReturnType<typeof generateText>>>;
+    protected registerBuiltinTools(): Promise<void>;
+    protected registerTool<T extends z.ZodTypeAny, R>(name: string, description: string, schema: T, execute: (args: z.infer<T>, toolContext?: ToolContext) => Promise<R>): void;
+    /**
+     * Registers an AI SDK Tool directly, ensuring its schema is discoverable.
+     */
+    protected registerSdkTool(name: string, sdkTool: Tool): void;
+    /**
+     * Override this to provide the system prompt.
+     */
+    protected getSystemPrompt(defaultPrompt: string): string;
+    /**
+     * Check permissions based on AGENTS.md frontmatter.
+     * NOTE: It could be useful to return the actual path that was blocked, this
+     *       would give agent more context to fix the issue.
+     */
+    protected checkPermissions(toolName: string, args: Record<string, unknown>): Promise<{
+        allowed: boolean;
+        error?: string;
+    }>;
+    /**
+     * The Unified Loop:
+     * - Loads Project Context (AGENTS.md)
+     * - Runs a manual loop interacting with the LLM
+     * - Handles tool execution manually for better control/logging
+     */
+    run(prompt: string, context?: AgentContext): Promise<string>;
+}

package/dist/core/formula.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+export declare const FormulaVariableSchema: z.ZodObject<{
+    description: z.ZodString;
+    required: z.ZodDefault<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const FormulaStepSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    needs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    if: z.ZodOptional<z.ZodString>;
+    for: z.ZodOptional<z.ZodObject<{
+        items: z.ZodString;
+        as: z.ZodString;
+    }, z.core.$strip>>;
+    on_failure: z.ZodOptional<z.ZodString>;
+    output_schema: z.ZodOptional<z.ZodAny>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    agent: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const FormulaSchema: z.ZodObject<{
+    formula: z.ZodString;
+    description: z.ZodString;
+    vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodString;
+        required: z.ZodDefault<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    prompts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    mcp_resources: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    context_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+        needs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        if: z.ZodOptional<z.ZodString>;
+        for: z.ZodOptional<z.ZodObject<{
+            items: z.ZodString;
+            as: z.ZodString;
+        }, z.core.$strip>>;
+        on_failure: z.ZodOptional<z.ZodString>;
+        output_schema: z.ZodOptional<z.ZodAny>;
+        context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        agent: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Formula = z.infer<typeof FormulaSchema>;
+export type FormulaStep = z.infer<typeof FormulaStepSchema>;
+export declare class FormulaRegistry {
+    private formulas;
+    private basePath;
+    constructor(basePath?: string);
+    loadAll(): Promise<void>;
+    private loadFormula;
+    get(name: string): Formula | undefined;
+    list(): Formula[];
+}
+export declare function getFormulaRegistry(basePath?: string): FormulaRegistry;
+export declare function setFormulaRegistry(registry: FormulaRegistry): void;

package/dist/core/gitignore.d.ts

@@ -0,0 +1 @@
+export declare function getIgnoredPatterns(baseDir?: string): string[];

package/dist/core/hooks.d.ts

@@ -0,0 +1,19 @@
+import { type Ticket, type WorkQueue } from "./queue";
+export type TicketHandler = (ticket: Ticket) => Promise<unknown>;
+export declare class Hook {
+    private agentId;
+    private queue;
+    private handler;
+    private pollingInterval;
+    private isRunning;
+    private heartbeatTimer;
+    private role;
+    private maxRetries;
+    constructor(agentId: string, role: string, handler: TicketHandler, queue?: WorkQueue, maxRetries?: number);
+    start(): void;
+    stop(): void;
+    private loop;
+    private cycle;
+    private startHeartbeat;
+    private stopHeartbeat;
+}

package/dist/core/instruction.d.ts

@@ -0,0 +1,103 @@
+import type { AgentRole } from "../config/schema";
+import { type PearlsClient } from "./pearls";
+import { type FormulaRegistry } from "./formula";
+import type { MCPService } from "../services/mcp";
+export interface InstructionContext {
+    role: AgentRole;
+    pearlId?: string;
+    labels?: string[];
+    context?: Record<string, unknown>;
+}
+export interface InstructionProvider {
+    name: string;
+    priority: number;
+    getInstructions(ctx: InstructionContext): Promise<string | null>;
+}
+/**
+ * Loads project-specific top-level protocol from .citadel/instructions/protocol.md
+ * This has the lowest priority value (5), meaning it appears at the very top.
+ */
+export declare class CustomProtocolProvider implements InstructionProvider {
+    name: string;
+    priority: number;
+    getInstructions(_ctx: InstructionContext): Promise<string | null>;
+}
+/**
+ * Loads AGENTS.md from project root.
+ */
+export declare class GlobalProvider implements InstructionProvider {
+    name: string;
+    priority: number;
+    getInstructions(ctx: InstructionContext): Promise<string | null>;
+}
+/**
+ * Hardcoded defaults for Citadel roles.
+ * Provides a universal System Integrity block for all roles,
+ * and a Worker base protocol for worker-type roles.
+ */
+export declare class BuiltinProvider implements InstructionProvider {
+    name: string;
+    priority: number;
+    private static readonly WORKER_TYPE_ROLES;
+    getInstructions(ctx: InstructionContext): Promise<string | null>;
+}
+/**
+ * Loads role-specific instructions from .citadel/instructions/role-${role}.md
+ */
+export declare class RoleProvider implements InstructionProvider {
+    name: string;
+    priority: number;
+    getInstructions(ctx: InstructionContext): Promise<string | null>;
+}
+/**
+ * Loads instructions from Formula if the pearl is part of a formula.
+ */
+export declare class FormulaProvider implements InstructionProvider {
+    name: string;
+    priority: number;
+    private pearls;
+    private formulaRegistry;
+    constructor(pearls?: PearlsClient, formulaRegistry?: FormulaRegistry);
+    getInstructions(ctx: InstructionContext): Promise<string | null>;
+}
+/**
+ * Loads instructions based on tags (labels) like .citadel/instructions/tag-git.md
+ */
+export declare class TagProvider implements InstructionProvider {
+    name: string;
+    priority: number;
+    getInstructions(ctx: InstructionContext): Promise<string | null>;
+}
+/**
+ * Loads status of blocking sub-tasks for the current pearl.
+ */
+export declare class SubTaskProvider implements InstructionProvider {
+    name: string;
+    priority: number;
+    private pearls;
+    constructor(pearls?: PearlsClient);
+    getInstructions(ctx: InstructionContext): Promise<string | null>;
+}
+/**
+ * Loads custom instructions from pearl context.
+ */
+export declare class ContextProvider implements InstructionProvider {
+    name: string;
+    priority: number;
+    getInstructions(ctx: InstructionContext): Promise<string | null>;
+}
+/**
+ * Enforcement of Completion Protocol.
+ * This is the HIGHEST priority (priority=100) and appears at the bottom.
+ */
+export declare class EnforcementProvider implements InstructionProvider {
+    name: string;
+    priority: number;
+    getInstructions(_ctx: InstructionContext): Promise<string | null>;
+}
+export declare class InstructionService {
+    private providers;
+    constructor(pearls?: PearlsClient, mcpService?: MCPService, formulaRegistry?: FormulaRegistry);
+    buildPrompt(ctx: InstructionContext, basePrompt: string): Promise<string>;
+}
+export declare function getInstructionService(pearls?: PearlsClient, mcpService?: MCPService, formulaRegistry?: FormulaRegistry): InstructionService;

package/dist/core/llm.d.ts

@@ -0,0 +1,3 @@
+import type { LanguageModel } from "ai";
+import type { AgentRole } from "../config/schema";
+export declare function getAgentModel(role: AgentRole): LanguageModel;

package/dist/core/logger.d.ts

@@ -0,0 +1,31 @@
+import { EventEmitter } from "node:events";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    meta?: Record<string, unknown>;
+}
+export interface LoggerOptions {
+    path?: string;
+    level?: LogLevel;
+    fileEnabled?: boolean;
+    consoleEnabled?: boolean;
+    rotation?: "daily" | "none";
+}
+export declare class CitadelLogger extends EventEmitter {
+    private consoleEnabled;
+    private fileEnabled;
+    private filePath?;
+    private rotation;
+    private lastRotationCheck;
+    setOptions(options: LoggerOptions): void;
+    setConsoleEnabled(enabled: boolean): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, error?: any, meta?: Record<string, unknown>): void;
+    private log;
+    private ensureRotation;
+}
+export declare const logger: CitadelLogger;

package/dist/core/mcp-resource-provider.d.ts

@@ -0,0 +1,14 @@
+import { type PearlsClient } from "./pearls";
+import { type FormulaRegistry } from "./formula";
+import type { InstructionContext, InstructionProvider } from "./instruction";
+import { type MCPService } from "../services/mcp";
+export declare class MCPResourceProvider implements InstructionProvider {
+    name: string;
+    priority: number;
+    private explicitMcpService?;
+    private pearls;
+    private formulaRegistry;
+    constructor(mcpService?: MCPService, pearls?: PearlsClient, formulaRegistry?: FormulaRegistry);
+    getInstructions(ctx: InstructionContext): Promise<string | null>;
+    private mergeResources;
+}

package/dist/core/memory.d.ts

@@ -0,0 +1,8 @@
+export declare class ToolResultMemory {
+    private baseDir;
+    constructor(baseDir?: string);
+    private ensureDir;
+    store(pearlId: string, content: string): Promise<string>;
+    get(pearlId: string, id: string): Promise<string | null>;
+}
+export declare function getToolResultMemory(): ToolResultMemory;

package/dist/core/pearls.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+export declare const PearlStatusSchema: z.ZodEnum<{
+    open: "open";
+    in_progress: "in_progress";
+    verify: "verify";
+    done: "done";
+}>;
+export type PearlStatus = z.infer<typeof PearlStatusSchema>;
+export declare const PearlPrioritySchema: z.ZodPipe<z.ZodAny, z.ZodTransform<0 | 2 | 4 | 3 | 1, any>>;
+export type PearlPriority = z.infer<typeof PearlPrioritySchema>;
+export declare const PearlSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        open: "open";
+        in_progress: "in_progress";
+        verify: "verify";
+        done: "done";
+    }>;
+    priority: z.ZodPipe<z.ZodAny, z.ZodTransform<0 | 2 | 4 | 3 | 1, any>>;
+    assignee: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    blockers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    acceptance_test: z.ZodOptional<z.ZodString>;
+    parent: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    output: z.ZodOptional<z.ZodUnknown>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+export type Pearl = z.infer<typeof PearlSchema>;
+export interface CreateOptions {
+    priority?: 0 | 1 | 2 | 3 | 4;
+    assignee?: string;
+    blockers?: string[];
+    acceptance_test?: string;
+    description?: string;
+    parent?: string;
+    type?: string;
+    context?: Record<string, unknown>;
+    labels?: string[];
+}
+export declare class PearlsClient {
+    private basePath;
+    private binary;
+    constructor(basePath?: string, binary?: string);
+    runCommand(args: string[]): Promise<string>;
+    init(): Promise<void>;
+    protected execute(command: string, args: string[], cwd: string): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    sync(): Promise<void>;
+    doctor(): Promise<boolean>;
+    private parseRaw;
+    private parseRawList;
+    private mapToDomain;
+    list(status?: PearlStatus): Promise<Pearl[]>;
+    ready(): Promise<Pearl[]>;
+    getAll(): Promise<Pearl[]>;
+    get(id: string): Promise<Pearl>;
+    create(title: string, options?: CreateOptions): Promise<Pearl>;
+    update(id: string, changes: Partial<Pearl>): Promise<Pearl>;
+    private validateTransition;
+    addDependency(childId: string, parentId: string): Promise<void>;
+    addComment(id: string, comment: string): Promise<string>;
+    listComments(id: string): Promise<Array<{
+        author: string;
+        content: string;
+        created_at: string;
+    }>>;
+}
+export declare function getPearls(basePath?: string): PearlsClient;
+export declare function setPearlsInstance(pearls: PearlsClient): void;

package/dist/core/pool.d.ts

@@ -0,0 +1,31 @@
+import { EventEmitter } from "node:events";
+interface PoolItem {
+    start?: () => Promise<void> | void;
+    stop?: () => void;
+}
+export declare class WorkerPool extends EventEmitter {
+    private workers;
+    private busyWorkers;
+    private role;
+    size: number;
+    private factory;
+    constructor(role: string, factory: (id: string) => PoolItem, size?: number);
+    private initialize;
+    /**
+     * Dynamic Resizing
+     */
+    resize(targetSize: number): Promise<void>;
+    private addWorker;
+    private removeWorker;
+    acquire(): Promise<PoolItem>;
+    release(worker: PoolItem): void;
+    start(): void;
+    stop(): void;
+    get status(): {
+        total: number;
+        busy: number;
+        idle: number;
+    };
+}
+export declare function getGlobalSingleton<T>(key: symbol, factory: () => T): T;
+export {};

package/dist/core/queue.d.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+export declare const TicketStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    queued: "queued";
+    processing: "processing";
+}>;
+export type TicketStatus = z.infer<typeof TicketStatusSchema>;
+export declare const TicketSchema: z.ZodObject<{
+    id: z.ZodString;
+    pearl_id: z.ZodString;
+    status: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        queued: "queued";
+        processing: "processing";
+    }>;
+    priority: z.ZodNumber;
+    target_role: z.ZodEnum<{
+        worker: "worker";
+        gatekeeper: "gatekeeper";
+    }>;
+    assignee_id: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodNumber;
+    started_at: z.ZodNullable<z.ZodNumber>;
+    completed_at: z.ZodNullable<z.ZodNumber>;
+    heartbeat_at: z.ZodNullable<z.ZodNumber>;
+    retry_count: z.ZodNumber;
+    next_attempt_at: z.ZodNullable<z.ZodNumber>;
+    output: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type Ticket = z.infer<typeof TicketSchema>;
+export declare class WorkQueue {
+    private db;
+    constructor(dbPath?: string);
+    private init;
+    enqueue(pearlId: string, priority?: number, targetRole?: string): void;
+    /**
+     * Claim a ticket for processing (The Hook)
+     */
+    claim(assigneeId: string, role: string): Ticket | null;
+    /**
+     * Signal that the worker is still alive
+     */
+    heartbeat(ticketId: string): void;
+    /**
+     * Mark ticket as complete with optional output
+     */
+    /**
+     * Mark ticket as complete with optional output
+     */
+    complete(ticketId: string, output?: unknown): void;
+    /**
+     * Get output of a completed ticket by Pearl ID
+     */
+    getOutput(pearlId: string): unknown;
+    /**
+     * Release a failed ticket back to queue (or fail permanently)
+     */
+    fail(ticketId: string, permanent?: boolean, maxRetries?: number): void;
+    /**
+     * Find stalled tickets and release them
+     */
+    releaseStalled(timeoutMs: number): number;
+    /**
+     * Check if a pearl has an active ticket (queued or processing)
+     */
+    getActiveTicket(pearlId: string): Ticket | null;
+    /**
+     * Get the latest ticket for a pearl (regardless of status)
+     */
+    getLatestTicket(pearlId: string): Ticket | null;
+    /**
+     * Reset tickets for a specific pearl
+     */
+    resetPearl(pearlId: string): void;
+    /**
+     * Get tickets currently being processed
+     */
+    listActive(timeoutMs?: number): Ticket[];
+    /**
+     * Get tickets by status
+     */
+    getTicketsByStatus(status: TicketStatus): Ticket[];
+    /**
+     * Get all tickets, optionally filtered by status
+     */
+    getAllTickets(status?: TicketStatus): Ticket[];
+    /**
+     * Get count of pending (queued) tickets for a specific role
+     */
+    getPendingCount(role: string): number;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+}
+export declare function getQueue(): WorkQueue;
+export declare function setQueueInstance(queue: WorkQueue): void;

package/dist/core/registry.d.ts

@@ -0,0 +1,3 @@
+export declare function getGlobalSingleton<T>(key: string, factory: () => T): T;
+export declare function setGlobalSingleton<T>(key: string, value: T): void;
+export declare function clearGlobalSingleton(key: string): void;

package/dist/core/schema-utils.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+interface JsonSchema {
+    type?: string;
+    description?: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    items?: unknown;
+    additionalProperties?: boolean | unknown;
+}
+export declare function jsonSchemaToZod(schema: JsonSchema | string): z.ZodTypeAny;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { loadConfig, setConfig, getConfig } from "./config";
+export { getQueue } from "./core/queue";
+export { Conductor } from "./services/conductor";
+export { getWorkflowEngine } from "./services/workflow-engine";
+export { getFormulaRegistry, type Formula } from "./core/formula";
+export { startBridge } from "./bridge/index";
+export { type Pearl, getPearls } from "./core/pearls";
+export { logger, type LogEntry, type LogLevel } from "./core/logger";
+export { getMCPService, type MCPService, type MCPTool } from "./services/mcp";