@karmaniverous/jeeves-runner 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { DatabaseSync } from 'node:sqlite';
 import { Logger } from 'pino';
+import { DatabaseSync } from 'node:sqlite';
 
 /**
  * Runner configuration schema and types.
@@ -16,6 +16,7 @@ declare const runnerConfigSchema: z.ZodObject<{
     runRetentionDays: z.ZodDefault<z.ZodNumber>;
     cursorCleanupIntervalMs: z.ZodDefault<z.ZodNumber>;
     shutdownGraceMs: z.ZodDefault<z.ZodNumber>;
+    reconcileIntervalMs: z.ZodDefault<z.ZodNumber>;
     notifications: z.ZodDefault<z.ZodObject<{
         slackTokenPath: z.ZodOptional<z.ZodString>;
         defaultOnFailure: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -32,6 +33,10 @@ declare const runnerConfigSchema: z.ZodObject<{
         }>>;
         file: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    gateway: z.ZodDefault<z.ZodObject<{
+        url: z.ZodDefault<z.ZodString>;
+        tokenPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Inferred runner configuration type. */
 type RunnerConfig = z.infer<typeof runnerConfigSchema>;
@@ -42,6 +47,7 @@ type RunnerConfig = z.infer<typeof runnerConfigSchema>;
  * @module
  */
 
+/** Job definition schema for scheduled tasks. */
 declare const jobSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -62,33 +68,60 @@ declare const jobSchema: z.ZodObject<{
     onFailure: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     onSuccess: z.ZodDefault<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
+/** Inferred Job type from schema. */
 type Job = z.infer<typeof jobSchema>;
 
+/**
+ * Queue definition schema and types.
+ *
+ * @module
+ */
+
+/** Queue definition schema for managing queue behavior and retention. */
+declare const queueSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    dedupExpr: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    dedupScope: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        all: "all";
+    }>>;
+    maxAttempts: z.ZodDefault<z.ZodNumber>;
+    retentionDays: z.ZodDefault<z.ZodNumber>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+/** Inferred Queue type from schema. */
+type Queue = z.infer<typeof queueSchema>;
+
 /**
  * Run record schema and types.
  *
  * @module
  */
 
+/** Run status enumeration schema (pending, running, ok, error, timeout, skipped). */
 declare const runStatusSchema: z.ZodEnum<{
-    error: "error";
     pending: "pending";
+    error: "error";
     running: "running";
     ok: "ok";
     timeout: "timeout";
     skipped: "skipped";
 }>;
+/** Run trigger type enumeration schema (schedule, manual, retry). */
 declare const runTriggerSchema: z.ZodEnum<{
     schedule: "schedule";
     manual: "manual";
     retry: "retry";
 }>;
+/** Run record schema representing a job execution instance. */
 declare const runSchema: z.ZodObject<{
     id: z.ZodNumber;
     jobId: z.ZodString;
     status: z.ZodEnum<{
-        error: "error";
         pending: "pending";
+        error: "error";
         running: "running";
         ok: "ok";
         timeout: "timeout";
@@ -109,44 +142,101 @@ declare const runSchema: z.ZodObject<{
         retry: "retry";
     }>>;
 }, z.core.$strip>;
+/** Inferred Run type representing a job execution record. */
 type Run = z.infer<typeof runSchema>;
+/** Inferred RunStatus type from schema. */
 type RunStatus = z.infer<typeof runStatusSchema>;
+/** Inferred RunTrigger type from schema. */
 type RunTrigger = z.infer<typeof runTriggerSchema>;
 
 /**
  * Main runner orchestrator. Wires up database, scheduler, API server, and handles graceful shutdown on SIGTERM/SIGINT.
  */
 
-/** Runner interface. */
+/** Runner interface for managing the runner lifecycle. */
 interface Runner {
+    /** Initialize and start all runner components (database, scheduler, API server). */
     start(): Promise<void>;
+    /** Gracefully stop all runner components and clean up resources. */
     stop(): Promise<void>;
 }
+/** Optional dependencies for test injection. */
+interface RunnerDeps {
+    /** Optional custom logger instance. */
+    logger?: Logger;
+}
 /**
  * Create the runner. Initializes database, scheduler, API server, and sets up graceful shutdown.
  */
-declare function createRunner(config: RunnerConfig): Runner;
+declare function createRunner(config: RunnerConfig, deps?: RunnerDeps): Runner;
+
+/**
+ * Queue operations module for runner client. Provides enqueue, dequeue, done, and fail operations.
+ */
+
+/** Queue item returned from dequeue operation. */
+interface QueueItem {
+    /** Queue item unique identifier. */
+    id: number;
+    /** Queue item payload (deserialized from JSON). */
+    payload: unknown;
+}
 
 /**
  * Job client library for runner jobs. Provides cursor (state) and queue operations. Opens its own DB connection via JR_DB_PATH env var.
  */
+
 /** Client interface for job scripts to interact with runner state and queues. */
 interface RunnerClient {
+    /** Retrieve a cursor value by namespace and key. Returns null if not found or expired. */
     getCursor(namespace: string, key: string): string | null;
+    /** Set or update a cursor value with optional TTL (e.g., '30d', '24h', '60m'). */
     setCursor(namespace: string, key: string, value: string, options?: {
         ttl?: string;
     }): void;
+    /** Delete a cursor by namespace and key. */
     deleteCursor(namespace: string, key: string): void;
+    /** Retrieve a state value by namespace and key (alias for getCursor). Returns null if not found or expired. */
+    getState(namespace: string, key: string): string | null;
+    /** Set or update a state value with optional TTL (alias for setCursor). */
+    setState(namespace: string, key: string, value: string, options?: {
+        ttl?: string;
+    }): void;
+    /** Delete a state value by namespace and key (alias for deleteCursor). */
+    deleteState(namespace: string, key: string): void;
+    /** Check if a state item exists in a collection. */
+    hasItem(namespace: string, key: string, itemKey: string): boolean;
+    /** Retrieve a state item value from a collection. Returns null if not found. */
+    getItem(namespace: string, key: string, itemKey: string): string | null;
+    /** Set or update a state item in a collection. Value is optional (for existence-only tracking). Auto-creates parent state row if needed. */
+    setItem(namespace: string, key: string, itemKey: string, value?: string): void;
+    /** Delete a state item from a collection. */
+    deleteItem(namespace: string, key: string, itemKey: string): void;
+    /** Count state items in a collection. */
+    countItems(namespace: string, key: string): number;
+    /** Delete oldest items keeping only keepCount newest (by updated_at). Returns number deleted. */
+    pruneItems(namespace: string, key: string, keepCount: number): number;
+    /** List item_key values ordered by updated_at. Default order is desc. */
+    listItemKeys(namespace: string, key: string, options?: {
+        limit?: number;
+        order?: 'asc' | 'desc';
+    }): string[];
+    /** Add an item to a queue with optional priority and max attempts. Returns the queue item ID, or -1 if skipped due to deduplication. */
     enqueue(queue: string, payload: unknown, options?: {
         priority?: number;
         maxAttempts?: number;
     }): number;
-    dequeue(queue: string, count?: number): Array<{
-        id: number;
-        payload: unknown;
-    }>;
+    /**
+     * Claim and retrieve items from a queue for processing. Returns array of queue items with id and payload.
+     * @param queue - Queue name
+     * @param count - Number of items to dequeue (default 1)
+     */
+    dequeue(queue: string, count?: number): QueueItem[];
+    /** Mark a queue item as successfully completed. */
     done(queueItemId: number): void;
+    /** Mark a queue item as failed with optional error message. Retries if under max_attempts, else dead-letters. */
     fail(queueItemId: number, error?: string): void;
+    /** Close the database connection. */
     close(): void;
 }
 /**
@@ -159,38 +249,121 @@ declare function createClient(dbPath?: string): RunnerClient;
  */
 /** Result of a job execution. */
 interface ExecutionResult {
+    /** Execution outcome: 'ok', 'error', or 'timeout'. */
     status: 'ok' | 'error' | 'timeout';
+    /** Process exit code (null if timeout or spawn error). */
     exitCode: number | null;
+    /** Total execution duration in milliseconds. */
     durationMs: number;
+    /** Token count parsed from JR_RESULT output (for LLM jobs). */
     tokens: number | null;
+    /** Additional result metadata parsed from JR_RESULT output. */
     resultMeta: string | null;
+    /** Last N lines of stdout. */
     stdoutTail: string;
+    /** Last N lines of stderr. */
     stderrTail: string;
+    /** Error message if execution failed. */
     error: string | null;
 }
+/** Command resolution result. */
+interface ResolvedCommand {
+    /** Command to execute. */
+    command: string;
+    /** Arguments to pass to the command. */
+    args: string[];
+}
 /** Options for executing a job script. */
 interface ExecutionOptions {
+    /** Path to the script file to execute. */
     script: string;
+    /** Path to the SQLite database for job state access. */
     dbPath: string;
+    /** Job identifier (passed as JR_JOB_ID env var). */
     jobId: string;
+    /** Run identifier (passed as JR_RUN_ID env var). */
     runId: number;
+    /** Optional execution timeout in milliseconds. */
     timeoutMs?: number;
+    /** Optional custom command resolver (for extensibility). */
+    commandResolver?: (script: string) => ResolvedCommand;
 }
 /**
  * Execute a job script as a child process. Captures output, parses metadata, enforces timeout.
  */
 declare function executeJob(options: ExecutionOptions): Promise<ExecutionResult>;
 
+/**
+ * OpenClaw Gateway HTTP client for spawning and monitoring sessions.
+ */
+/** Options for creating a Gateway client. */
+interface GatewayClientOptions {
+    /** Gateway base URL (e.g., http://127.0.0.1:18789). */
+    url: string;
+    /** Bearer token for authentication. */
+    token: string;
+    /** Request timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/** Options for spawning a session. */
+interface SpawnSessionOptions {
+    /** Optional session label. */
+    label?: string;
+    /** Thinking level: low, medium, or high. */
+    thinking?: 'low' | 'medium' | 'high';
+    /** Run timeout in seconds. */
+    runTimeoutSeconds?: number;
+}
+/** Result of spawning a session. */
+interface SpawnSessionResult {
+    /** Session key for tracking. */
+    sessionKey: string;
+    /** Run identifier. */
+    runId: string;
+}
+/** Session history message. */
+interface SessionMessage {
+    /** Message role (user, assistant, etc.). */
+    role: string;
+    /** Stop reason (if present, indicates completion). */
+    stopReason?: string;
+}
+/** Session information from sessions_list. */
+interface SessionInfo {
+    /** Total tokens used. */
+    totalTokens: number;
+    /** Model name. */
+    model: string;
+    /** Transcript file path (if available). */
+    transcriptPath?: string;
+}
+/** Gateway client for invoking tools via /tools/invoke. */
+interface GatewayClient {
+    /** Spawn a new session with the given task. */
+    spawnSession(task: string, options?: SpawnSessionOptions): Promise<SpawnSessionResult>;
+    /** Get session history messages. */
+    getSessionHistory(sessionKey: string, limit?: number): Promise<SessionMessage[]>;
+    /** Get session info (tokens, model, etc.). Returns null if not found. */
+    getSessionInfo(sessionKey: string): Promise<SessionInfo | null>;
+    /** Check if session is complete. */
+    isSessionComplete(sessionKey: string): Promise<boolean>;
+}
+/** Create a Gateway client. */
+declare function createGatewayClient(options: GatewayClientOptions): GatewayClient;
+
 /**
  * Slack notification module. Sends job completion/failure messages via Slack Web API (chat.postMessage). Falls back gracefully if no token.
  */
 /** Notification configuration. */
 interface NotifyConfig {
+    /** Slack bot token for posting messages (null if not configured). */
     slackToken: string | null;
 }
 /** Notifier interface for job completion events. */
 interface Notifier {
+    /** Send a success notification to a Slack channel. */
     notifySuccess(jobName: string, durationMs: number, channel: string): Promise<void>;
+    /** Send a failure notification to a Slack channel. */
     notifyFailure(jobName: string, durationMs: number, error: string | null, channel: string): Promise<void>;
 }
 /**
@@ -204,24 +377,61 @@ declare function createNotifier(config: NotifyConfig): Notifier;
 
 /** Scheduler dependencies. */
 interface SchedulerDeps {
+    /** SQLite database connection. */
     db: DatabaseSync;
+    /** Job executor function. */
     executor: typeof executeJob;
+    /** Notification service for job completion events. */
     notifier: Notifier;
+    /** Runner configuration. */
     config: RunnerConfig;
+    /** Logger instance. */
     logger: Logger;
+    /** Optional Gateway client for session-type jobs. */
+    gatewayClient?: GatewayClient;
 }
-/** Scheduler interface. */
+/** Scheduler interface for managing job schedules and execution. */
 interface Scheduler {
+    /** Initialize and start the scheduler, loading all enabled jobs. */
     start(): void;
-    stop(): void;
+    /** Stop the scheduler and gracefully wait for running jobs to complete. */
+    stop(): Promise<void>;
+    /** Manually trigger a job by ID, bypassing the schedule. */
     triggerJob(jobId: string): Promise<ExecutionResult>;
+    /** Force an immediate reconciliation of job schedules with the database. */
+    reconcileNow(): void;
+    /** Get list of currently running job IDs. */
     getRunningJobs(): string[];
+    /** Get list of job IDs that failed to register cron schedules. */
+    getFailedRegistrations(): string[];
 }
 /**
  * Create the job scheduler. Manages cron schedules, job execution, overlap policies, and notifications.
  */
 declare function createScheduler(deps: SchedulerDeps): Scheduler;
 
+/**
+ * Session executor for job type='session'. Spawns OpenClaw Gateway sessions and polls for completion.
+ */
+
+/** Options for executing a session job. */
+interface SessionExecutionOptions {
+    /** Script field from job: can be raw prompt, path to .md/.txt, or legacy .js dispatcher. */
+    script: string;
+    /** Job identifier (used as session label). */
+    jobId: string;
+    /** Optional execution timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Gateway client instance. */
+    gatewayClient: GatewayClient;
+    /** Initial poll interval in milliseconds (default 5000). Exposed for testing. */
+    pollIntervalMs?: number;
+}
+/**
+ * Execute a session job: spawn a Gateway session, poll for completion, fetch token usage.
+ */
+declare function executeSession(options: SessionExecutionOptions): Promise<ExecutionResult>;
+
 /**
  * SQLite connection manager. Creates DB file with parent directories, enables WAL mode for concurrency.
  */
@@ -242,12 +452,16 @@ declare function closeConnection(db: DatabaseSync): void;
 
 /** Configuration for maintenance tasks. */
 interface MaintenanceConfig {
+    /** Number of days to retain completed run records before pruning. */
     runRetentionDays: number;
+    /** Interval in milliseconds between maintenance task runs. */
     cursorCleanupIntervalMs: number;
 }
 /** Maintenance controller with start/stop lifecycle. */
 interface Maintenance {
+    /** Start maintenance tasks (runs immediately, then on interval). */
     start(): void;
+    /** Stop maintenance task interval. */
     stop(): void;
     /** Run all maintenance tasks immediately (useful for testing and startup). */
     runNow(): void;
@@ -266,5 +480,5 @@ declare function createMaintenance(db: DatabaseSync, config: MaintenanceConfig,
  */
 declare function runMigrations(db: DatabaseSync): void;
 
-export { closeConnection, createClient, createConnection, createMaintenance, createNotifier, createRunner, createScheduler, executeJob, jobSchema, runMigrations, runSchema, runStatusSchema, runTriggerSchema, runnerConfigSchema };
-export type { ExecutionOptions, ExecutionResult, Job, Maintenance, MaintenanceConfig, Notifier, NotifyConfig, Run, RunStatus, RunTrigger, Runner, RunnerClient, RunnerConfig, Scheduler, SchedulerDeps };
+export { closeConnection, createClient, createConnection, createGatewayClient, createMaintenance, createNotifier, createRunner, createScheduler, executeJob, executeSession, jobSchema, queueSchema, runMigrations, runSchema, runStatusSchema, runTriggerSchema, runnerConfigSchema };
+export type { ExecutionOptions, ExecutionResult, GatewayClient, GatewayClientOptions, Job, Maintenance, MaintenanceConfig, Notifier, NotifyConfig, Queue, QueueItem, Run, RunStatus, RunTrigger, Runner, RunnerClient, RunnerConfig, Scheduler, SchedulerDeps, SessionExecutionOptions, SessionInfo, SessionMessage, SpawnSessionOptions, SpawnSessionResult };