openvole 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,676 @@
+import { ZodSchema } from 'zod';
+import { Emitter } from 'mitt';
+
+/** Error codes for categorizing failures in the agent loop */
+type ActionErrorCode = 'TOOL_TIMEOUT' | 'TOOL_EXCEPTION' | 'TOOL_NOT_FOUND' | 'PERMISSION_DENIED' | 'PAW_CRASHED' | 'BRAIN_ERROR' | 'INVALID_PLAN';
+/** Structured error attached to a failed action */
+interface ActionError {
+    code: ActionErrorCode;
+    message: string;
+    toolName?: string;
+    pawName?: string;
+    details?: unknown;
+}
+/** Result of a single tool execution during the Act phase */
+interface ActionResult {
+    toolName: string;
+    pawName: string;
+    success: boolean;
+    output?: unknown;
+    error?: ActionError;
+    durationMs: number;
+}
+/** Create a structured ActionError */
+declare function createActionError(code: ActionErrorCode, message: string, opts?: {
+    toolName?: string;
+    pawName?: string;
+    details?: unknown;
+}): ActionError;
+/** Create a successful ActionResult */
+declare function successResult(toolName: string, pawName: string, output: unknown, durationMs: number): ActionResult;
+/** Create a failed ActionResult */
+declare function failureResult(toolName: string, pawName: string, error: ActionError, durationMs: number): ActionResult;
+
+/** Summary of a tool available to the Brain */
+interface ToolSummary {
+    name: string;
+    description: string;
+    pawName: string;
+}
+/** A Skill whose required tools are all satisfied (compact — Brain reads full instructions on demand) */
+interface ActiveSkill {
+    name: string;
+    description: string;
+    satisfiedBy: string[];
+}
+/** A single message in the agent's reasoning history */
+interface AgentMessage {
+    role: 'user' | 'brain' | 'tool_result' | 'error';
+    content: string;
+    toolCall?: {
+        name: string;
+        params: unknown;
+    };
+    timestamp: number;
+}
+/** The shared data structure that flows through the agent loop */
+interface AgentContext {
+    taskId: string;
+    messages: AgentMessage[];
+    availableTools: ToolSummary[];
+    activeSkills: ActiveSkill[];
+    metadata: Record<string, unknown>;
+    iteration: number;
+    maxIterations: number;
+}
+/** Create an empty AgentContext for a new task */
+declare function createAgentContext(taskId: string, maxIterations: number): AgentContext;
+
+/** A tool definition as provided by a Paw */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: ZodSchema;
+    execute: (params: unknown) => Promise<unknown>;
+}
+/** An entry in the tool registry — includes ownership metadata */
+interface ToolRegistryEntry {
+    name: string;
+    description: string;
+    parameters: ZodSchema;
+    pawName: string;
+    inProcess: boolean;
+    execute: (params: unknown) => Promise<unknown>;
+}
+
+/** Pluggable I/O interface for user-facing communication */
+interface VoleIO {
+    /** Ask the user for a yes/no confirmation */
+    confirm(message: string): Promise<boolean>;
+    /** Ask the user for free-form input */
+    prompt(message: string): Promise<string>;
+    /** Send a notification to the user (fire-and-forget) */
+    notify(message: string): void;
+}
+
+/** The plan returned by a Brain Paw during the Think phase */
+interface AgentPlan {
+    actions: PlannedAction[];
+    execution?: 'parallel' | 'sequential';
+    response?: string;
+    done?: boolean;
+}
+/** A single tool call the Brain wants to execute */
+interface PlannedAction {
+    tool: string;
+    params: unknown;
+}
+/** Hook called once when a task starts — initialize Paw state for this task */
+type BootstrapHook = (context: AgentContext) => Promise<AgentContext>;
+/** Hook called during the Perceive phase — enrich context before Think */
+type PerceiveHook = (context: AgentContext) => Promise<AgentContext>;
+/** Hook called during the Observe phase — fire-and-forget side effect */
+type ObserveHook = (result: ActionResult) => Promise<void>;
+/** Hook called when context exceeds size threshold — compress/summarize */
+type CompactHook = (context: AgentContext) => Promise<AgentContext>;
+/** A cron-triggered schedule hook */
+interface ScheduleHook {
+    cron: string;
+    handler: () => Promise<AgentTaskInput>;
+}
+/** Input for creating a new agent task */
+interface AgentTaskInput {
+    input: string;
+    source?: 'user' | 'schedule' | 'paw';
+}
+/** The full Paw definition — the contract every Paw must implement */
+interface PawDefinition {
+    name: string;
+    version: string;
+    description: string;
+    brain?: boolean;
+    inProcess?: boolean;
+    config?: ZodSchema;
+    hooks?: {
+        onBootstrap?: BootstrapHook;
+        onPerceive?: PerceiveHook;
+        onObserve?: ObserveHook;
+        onCompact?: CompactHook;
+        onSchedule?: ScheduleHook[];
+    };
+    tools?: ToolDefinition[];
+    think?: (context: AgentContext) => Promise<AgentPlan>;
+    io?: VoleIO;
+    onLoad?: (config: unknown) => Promise<void>;
+    onUnload?: () => Promise<void>;
+}
+/** Transport type for IPC communication */
+type TransportType = 'ipc' | 'stdio';
+/** Paw manifest as read from vole-paw.json */
+interface PawManifest {
+    name: string;
+    version: string;
+    description: string;
+    entry: string;
+    brain: boolean;
+    inProcess?: boolean;
+    transport?: TransportType;
+    tools: Array<{
+        name: string;
+        description: string;
+    }>;
+    permissions?: {
+        network?: string[];
+        listen?: number[];
+        filesystem?: string[];
+        env?: string[];
+    };
+}
+/** Paw configuration in vole.config.ts */
+interface PawConfig {
+    name: string;
+    hooks?: {
+        perceive?: {
+            order?: number;
+            pipeline?: boolean;
+        };
+    };
+    allow?: {
+        network?: string[];
+        listen?: number[];
+        filesystem?: string[];
+        env?: string[];
+    };
+}
+/** Runtime state of a loaded Paw */
+interface PawInstance {
+    name: string;
+    manifest: PawManifest;
+    config: PawConfig;
+    healthy: boolean;
+    transport: TransportType;
+    inProcess: boolean;
+    definition?: PawDefinition;
+    process?: {
+        kill: () => void;
+        pid?: number;
+    };
+    sendRequest?: (method: string, params?: unknown) => Promise<unknown>;
+    /** Bus events this Paw has subscribed to */
+    subscriptions?: string[];
+}
+/** Effective permissions = intersection of manifest requests and config grants */
+interface EffectivePermissions {
+    network: string[];
+    listen: number[];
+    filesystem: string[];
+    env: string[];
+}
+
+/** Rate limit configuration */
+interface RateLimits {
+    /** Max LLM (Brain) calls per minute */
+    llmCallsPerMinute?: number;
+    /** Max LLM (Brain) calls per hour */
+    llmCallsPerHour?: number;
+    /** Max tool executions per single task */
+    toolExecutionsPerTask?: number;
+    /** Max tasks per hour, keyed by source */
+    tasksPerHour?: Record<string, number>;
+}
+/** Loop configuration */
+interface LoopConfig {
+    maxIterations: number;
+    confirmBeforeAct: boolean;
+    taskConcurrency: number;
+    /** Max messages before triggering compact hooks (0 = disabled) */
+    compactThreshold: number;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    /** Rate limits (undefined = no limits) */
+    rateLimits?: RateLimits;
+}
+/** Tool profile — restricts which tools a task source can use */
+interface ToolProfile {
+    /** Tools allowed (if set, only these tools can be used) */
+    allow?: string[];
+    /** Tools denied (if set, these tools are blocked) */
+    deny?: string[];
+}
+/** Heartbeat configuration */
+interface HeartbeatConfig {
+    enabled: boolean;
+    intervalMinutes: number;
+}
+/** The full OpenVole configuration */
+interface VoleConfig {
+    brain?: string;
+    paws: Array<PawConfig | string>;
+    skills: string[];
+    loop: LoopConfig;
+    heartbeat: HeartbeatConfig;
+    /** Tool profiles per task source — restrict which tools can be used */
+    toolProfiles?: Record<string, ToolProfile>;
+}
+/** CLI-managed lock file — tracks installed paws and skills */
+interface VoleLock {
+    paws: Array<{
+        name: string;
+        version: string;
+        allow?: PawConfig['allow'];
+    }>;
+    skills: Array<{
+        name: string;
+        version: string;
+    }>;
+}
+/** Create a VoleConfig with defaults applied */
+declare function defineConfig(config: Partial<VoleConfig>): VoleConfig;
+/** Load configuration — merges vole.config.{ts,mjs,js} with vole.lock.json */
+declare function loadConfig(configPath: string): Promise<VoleConfig>;
+/** Read the lock file */
+declare function readLockFile(projectRoot: string): Promise<VoleLock>;
+/** Write the lock file */
+declare function writeLockFile(projectRoot: string, lock: VoleLock): Promise<void>;
+/** Add a Paw to the lock file */
+declare function addPawToLock(projectRoot: string, name: string, version: string, allow?: PawConfig['allow']): Promise<void>;
+/** Remove a Paw from the lock file */
+declare function removePawFromLock(projectRoot: string, name: string): Promise<void>;
+/** Add a Skill to the lock file */
+declare function addSkillToLock(projectRoot: string, name: string, version: string): Promise<void>;
+/** Remove a Skill from the lock file */
+declare function removeSkillFromLock(projectRoot: string, name: string): Promise<void>;
+
+/** Events emitted on the message bus */
+type BusEvents = {
+    'tool:registered': {
+        toolName: string;
+        pawName: string;
+    };
+    'tool:unregistered': {
+        toolName: string;
+        pawName: string;
+    };
+    'paw:registered': {
+        pawName: string;
+    };
+    'paw:unregistered': {
+        pawName: string;
+    };
+    'paw:crashed': {
+        pawName: string;
+        error?: unknown;
+    };
+    'task:queued': {
+        taskId: string;
+    };
+    'task:started': {
+        taskId: string;
+    };
+    'task:completed': {
+        taskId: string;
+        result?: string;
+    };
+    'task:failed': {
+        taskId: string;
+        error?: unknown;
+    };
+    'task:cancelled': {
+        taskId: string;
+    };
+    'rate:limited': {
+        bucket: string;
+        source?: string;
+    };
+};
+type MessageBus = Emitter<BusEvents>;
+/** Create a new message bus instance */
+declare function createMessageBus(): MessageBus;
+
+declare class ToolRegistry {
+    private bus;
+    private tools;
+    constructor(bus: MessageBus);
+    /** Register tools from a Paw. Skips tools with conflicting names. */
+    register(pawName: string, tools: ToolDefinition[], inProcess: boolean): void;
+    /** Remove all tools owned by a specific Paw */
+    unregister(pawName: string): void;
+    /** Get a tool entry by name */
+    get(toolName: string): ToolRegistryEntry | undefined;
+    /** List all registered tools */
+    list(): ToolRegistryEntry[];
+    /** Check if a tool exists */
+    has(toolName: string): boolean;
+    /** Get tool summaries for AgentContext */
+    summaries(): ToolSummary[];
+    /** Get all tool names owned by a specific Paw */
+    toolsForPaw(pawName: string): string[];
+    /** Clear all tools (for shutdown) */
+    clear(): void;
+}
+
+/** Interface for queryable registries (avoids circular imports) */
+interface QueryableSkillRegistry {
+    list(): Array<{
+        name: string;
+        active: boolean;
+        missingTools: string[];
+        definition: {
+            description: string;
+        };
+    }>;
+}
+interface QueryableTaskQueue {
+    list(): Array<{
+        id: string;
+        source: string;
+        input: string;
+        status: string;
+        createdAt: number;
+    }>;
+    enqueue(input: string, source?: 'user' | 'schedule' | 'paw', options?: {
+        sessionId?: string;
+        metadata?: Record<string, unknown>;
+    }): {
+        id: string;
+    };
+}
+interface QueryableScheduler {
+    list(): Array<{
+        id: string;
+        input: string;
+        intervalMinutes: number;
+        createdAt: number;
+    }>;
+}
+/** Manages loaded Paws and their lifecycle */
+declare class PawRegistry {
+    private bus;
+    private toolRegistry;
+    private projectRoot;
+    private paws;
+    private transports;
+    private perceiveHooks;
+    private observeHookPaws;
+    private bootstrapPaws;
+    private compactPaws;
+    private brainPawName;
+    /** Maps config path → manifest name (e.g. "./paws/paw-ollama" → "@openvole/paw-ollama") */
+    private configToManifest;
+    private skillRegistry?;
+    private taskQueue?;
+    private scheduler?;
+    constructor(bus: MessageBus, toolRegistry: ToolRegistry, projectRoot: string);
+    /** Inject queryable registries (called after construction to avoid circular deps) */
+    setQuerySources(skills: QueryableSkillRegistry, tasks: QueryableTaskQueue, scheduler?: QueryableScheduler): void;
+    /** Load and register a Paw */
+    load(config: PawConfig): Promise<boolean>;
+    /** Unload a Paw (accepts config path or manifest name) */
+    unload(name: string): Promise<boolean>;
+    /** Resolve a config name to its manifest name */
+    resolveManifestName(configName: string): string;
+    /** Set the Brain Paw name (accepts config path or manifest name) */
+    setBrain(name: string): void;
+    /** Get the Brain Paw name */
+    getBrainName(): string | undefined;
+    /** Get a Paw instance */
+    get(name: string): PawInstance | undefined;
+    /** List all loaded Paws */
+    list(): PawInstance[];
+    /** Check if a Paw is healthy */
+    isHealthy(name: string): boolean;
+    /**
+     * Run GLOBAL perceive hooks — only Paws without tools.
+     * Paws with tools use lazy perceive (called just before their tool executes).
+     */
+    runGlobalPerceiveHooks(context: AgentContext): Promise<AgentContext>;
+    /**
+     * Run LAZY perceive for a specific Paw — called just before its tool executes.
+     * Only runs if the Paw has an onPerceive hook registered.
+     */
+    runLazyPerceive(pawName: string, context: AgentContext): Promise<AgentContext>;
+    /** Run all Observe hooks concurrently (fire-and-forget) */
+    runObserveHooks(result: ActionResult): void;
+    /** Run bootstrap hooks — called once at the start of a task */
+    runBootstrapHooks(context: AgentContext): Promise<AgentContext>;
+    /**
+     * Run compact hooks — called when context exceeds size threshold.
+     * Paws can compress/summarize messages to free up context window space.
+     */
+    runCompactHooks(context: AgentContext): Promise<AgentContext>;
+    /** Call the Brain Paw's think function */
+    think(context: AgentContext): Promise<AgentPlan | null>;
+    /** Execute a tool on a subprocess Paw */
+    executeRemoteTool(pawName: string, toolName: string, params: unknown): Promise<unknown>;
+    private callPerceive;
+    private callObserve;
+    private registerInProcessTools;
+    private setupTransportHandlers;
+    /** Forward bus events to a Paw that subscribed */
+    private setupBusForwarding;
+    /** Handle state queries from Paws */
+    private handleQuery;
+    private waitForRegistration;
+}
+
+/** A Skill definition — parsed from SKILL.md */
+interface SkillDefinition {
+    name: string;
+    description: string;
+    version?: string;
+    requiredTools: string[];
+    optionalTools: string[];
+    instructions: string;
+    tags: string[];
+    /** OpenClaw compatibility — runtime requirements */
+    requires?: SkillRequirements;
+}
+/** Runtime requirements (OpenClaw-compatible) */
+interface SkillRequirements {
+    /** Environment variables the skill expects */
+    env: string[];
+    /** CLI binaries that must all be installed */
+    bins: string[];
+    /** CLI binaries where at least one must exist */
+    anyBins: string[];
+}
+/** Runtime state of a loaded Skill */
+interface SkillInstance {
+    name: string;
+    definition: SkillDefinition;
+    /** Path to the skill directory */
+    path: string;
+    active: boolean;
+    missingTools: string[];
+}
+
+/** Manages loaded Skills and their activation state */
+declare class SkillRegistry {
+    private bus;
+    private toolRegistry;
+    private projectRoot;
+    private skills;
+    constructor(bus: MessageBus, toolRegistry: ToolRegistry, projectRoot: string);
+    /** Load a Skill from a directory containing SKILL.md */
+    load(nameOrPath: string): Promise<boolean>;
+    /** Unload a Skill */
+    unload(name: string): boolean;
+    /** Re-run the resolver against the current tool registry */
+    resolve(): void;
+    /** Get all Skill instances */
+    list(): SkillInstance[];
+    /** Get active Skills only */
+    active(): SkillInstance[];
+    /** Get a Skill by name */
+    get(name: string): SkillInstance | undefined;
+}
+
+/**
+ * Sliding window counter rate limiter.
+ * Tracks timestamps per bucket and checks against limits.
+ */
+declare class RateLimiter {
+    private buckets;
+    /**
+     * Try to consume one token from the bucket.
+     * Returns true if the request is under the limit, false if rate-limited.
+     */
+    tryConsume(bucket: string, limit: number, windowMs: number): boolean;
+    /**
+     * Returns the number of remaining tokens in the bucket for the current window.
+     */
+    remaining(bucket: string, limit: number, windowMs: number): number;
+    /**
+     * Remove expired timestamps from a bucket.
+     */
+    private cleanup;
+}
+
+/** Task states */
+type TaskStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+/** A discrete unit of work for the agent loop */
+interface AgentTask {
+    id: string;
+    source: 'user' | 'schedule' | 'heartbeat' | 'paw';
+    input: string;
+    status: TaskStatus;
+    createdAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    result?: string;
+    error?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+}
+type TaskRunner = (task: AgentTask) => Promise<void>;
+/** FIFO task queue with configurable concurrency */
+declare class TaskQueue {
+    private bus;
+    private concurrency;
+    private rateLimiter?;
+    private rateLimits?;
+    private queue;
+    private running;
+    private completed;
+    private runner;
+    private draining;
+    constructor(bus: MessageBus, concurrency?: number, rateLimiter?: RateLimiter | undefined, rateLimits?: RateLimits | undefined);
+    /** Set the task runner function (called by the agent loop) */
+    setRunner(runner: TaskRunner): void;
+    /** Enqueue a new task */
+    enqueue(input: string, source?: 'user' | 'schedule' | 'heartbeat' | 'paw', options?: {
+        sessionId?: string;
+        metadata?: Record<string, unknown>;
+    }): AgentTask;
+    /** Cancel a task by ID */
+    cancel(taskId: string): boolean;
+    /** Get all tasks (queued + running + completed) */
+    list(): AgentTask[];
+    /** Get a task by ID */
+    get(taskId: string): AgentTask | undefined;
+    /** Check if a task has been cancelled */
+    isCancelled(taskId: string): boolean;
+    private drain;
+    private runTask;
+}
+
+interface LoopDependencies {
+    bus: MessageBus;
+    toolRegistry: ToolRegistry;
+    pawRegistry: PawRegistry;
+    skillRegistry: SkillRegistry;
+    io: VoleIO;
+    config: LoopConfig;
+    toolProfiles?: Record<string, ToolProfile>;
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Run the agent loop for a single task.
+ * Perceive → Think → Act → Observe → loop
+ */
+declare function runAgentLoop(task: AgentTask, deps: LoopDependencies): Promise<void>;
+
+/** In-memory store for brain-created recurring schedules */
+declare class SchedulerStore {
+    private schedules;
+    /** Create or replace a recurring schedule */
+    add(id: string, input: string, intervalMinutes: number, onTick: () => void): void;
+    /** Cancel a schedule by ID */
+    cancel(id: string): boolean;
+    /** List all active schedules */
+    list(): Array<{
+        id: string;
+        input: string;
+        intervalMinutes: number;
+        createdAt: number;
+    }>;
+    /** Clear all schedules (for shutdown) */
+    clearAll(): void;
+}
+
+/**
+ * Hook phase definitions.
+ *
+ * The actual hook execution logic lives in PawRegistry (perceive/observe hooks)
+ * and the agent loop (think/act orchestration). This module defines the hook
+ * lifecycle constants and types used across the system.
+ */
+/** The four phases of the agent loop */
+type LoopPhase = 'perceive' | 'think' | 'act' | 'observe';
+/** Phase ordering for logging and tracing */
+declare const PHASE_ORDER: readonly LoopPhase[];
+
+/** Resolve a Paw package path from its name */
+declare function resolvePawPath(name: string, projectRoot: string): string;
+/** Read and validate a vole-paw.json manifest */
+declare function readPawManifest(pawPath: string): Promise<PawManifest | null>;
+
+/**
+ * Compute effective permissions as the intersection of
+ * what the manifest requests and what the config grants.
+ */
+declare function computeEffectivePermissions(manifest: PawManifest, config: PawConfig): EffectivePermissions;
+/**
+ * Validate that a Paw's manifest permissions are reasonable.
+ * Returns warnings (non-blocking) for review.
+ */
+declare function validatePermissions(manifest: PawManifest, config: PawConfig): string[];
+
+/**
+ * Resolve Skill activation based on the current tool registry
+ * and runtime requirements (env vars, binaries).
+ *
+ * A Skill is active if:
+ * - All requiredTools are registered in the tool registry
+ * - All requires.env vars are set in the environment
+ * - All requires.bins are available on PATH
+ * - At least one of requires.anyBins is available (if specified)
+ */
+declare function resolveSkills(skills: SkillInstance[], toolRegistry: ToolRegistry): void;
+/** Build ActiveSkill entries for the AgentContext */
+declare function buildActiveSkills(skills: SkillInstance[], toolRegistry: ToolRegistry): ActiveSkill[];
+
+/** Default TTY I/O implementation using stdin/stdout */
+declare function createTtyIO(): VoleIO;
+
+interface VoleEngine {
+    bus: ReturnType<typeof createMessageBus>;
+    toolRegistry: ToolRegistry;
+    pawRegistry: PawRegistry;
+    skillRegistry: SkillRegistry;
+    taskQueue: TaskQueue;
+    io: VoleIO;
+    config: VoleConfig;
+    /** Start the engine — load Paws and Skills */
+    start(): Promise<void>;
+    /** Submit a task for execution */
+    run(input: string, source?: 'user' | 'schedule' | 'heartbeat' | 'paw', sessionId?: string): void;
+    /** Graceful shutdown */
+    shutdown(): Promise<void>;
+}
+/** Create and initialize the OpenVole engine */
+declare function createEngine(projectRoot: string, options?: {
+    io?: VoleIO;
+    configPath?: string;
+}): Promise<VoleEngine>;
+
+export { type ActionError, type ActionErrorCode, type ActionResult, type ActiveSkill, type AgentContext, type AgentMessage, type AgentPlan, type AgentTask, type BootstrapHook, type BusEvents, type CompactHook, type EffectivePermissions, type HeartbeatConfig, type LoopConfig, type LoopDependencies, type LoopPhase, type MessageBus, type ObserveHook, PHASE_ORDER, type PawConfig, type PawDefinition, type PawInstance, type PawManifest, PawRegistry, type PerceiveHook, type PlannedAction, RateLimiter, type RateLimits, type ScheduleHook, SchedulerStore, type SkillDefinition, type SkillInstance, SkillRegistry, TaskQueue, type TaskStatus, type ToolDefinition, ToolRegistry, type ToolRegistryEntry, type ToolSummary, type TransportType, type VoleConfig, type VoleEngine, type VoleIO, type VoleLock, addPawToLock, addSkillToLock, buildActiveSkills, computeEffectivePermissions, createActionError, createAgentContext, createEngine, createMessageBus, createTtyIO, defineConfig, failureResult, loadConfig, readLockFile, readPawManifest, removePawFromLock, removeSkillFromLock, resolvePawPath, resolveSkills, runAgentLoop, successResult, validatePermissions, writeLockFile };