opencode-hive 0.9.1 → 1.0.1

package/dist/background/concurrency.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Concurrency Manager for background task execution.
+ *
+ * Provides:
+ * - Per-agent or per-model concurrency limiting
+ * - Queueing with FIFO ordering
+ * - Proper slot release and handoff
+ * - Rate limiting with exponential backoff
+ * - Timeout handling to prevent indefinite starvation
+ */
+/**
+ * Configuration for concurrency limits.
+ */
+export interface ConcurrencyConfig {
+    /** Default concurrent tasks per key (default: 3) */
+    defaultLimit?: number;
+    /** Per-agent limits: { "forager": 2, "explorer": 1 } */
+    agentLimits?: Record<string, number>;
+    /** Per-model limits: { "anthropic/claude-sonnet": 2 } */
+    modelLimits?: Record<string, number>;
+    /** Maximum wait time in queue before rejection (default: 300000 = 5 min) */
+    queueTimeoutMs?: number;
+    /** Minimum delay between task starts for same key (default: 1000 = 1 sec) */
+    minDelayBetweenStartsMs?: number;
+}
+/**
+ * Concurrency Manager for background tasks.
+ *
+ * Uses a key-based system where keys can be:
+ * - Agent names: "forager", "explorer"
+ * - Model identifiers: "anthropic/claude-sonnet"
+ * - Custom keys: "hive-task"
+ */
+export declare class ConcurrencyManager {
+    private config;
+    private counts;
+    private queues;
+    private lastStartTimes;
+    constructor(config?: ConcurrencyConfig);
+    /**
+     * Get the concurrency limit for a key.
+     * Checks model limits, then agent limits, then default.
+     */
+    getLimit(key: string): number;
+    /**
+     * Acquire a concurrency slot for the given key.
+     * Returns immediately if slot is available, otherwise queues.
+     *
+     * @throws Error if queue timeout is exceeded
+     */
+    acquire(key: string): Promise<void>;
+    /**
+     * Release a concurrency slot.
+     * If there are waiters, hands off to the next one.
+     */
+    release(key: string): void;
+    /**
+     * Try to acquire without waiting.
+     * Returns true if slot was acquired, false otherwise.
+     */
+    tryAcquire(key: string): boolean;
+    /**
+     * Cancel all waiting entries for a key.
+     */
+    cancelWaiters(key: string): number;
+    /**
+     * Clear all state. Used during shutdown.
+     */
+    clear(): void;
+    /**
+     * Get current slot count for a key.
+     */
+    getCount(key: string): number;
+    /**
+     * Get queue length for a key.
+     */
+    getQueueLength(key: string): number;
+    /**
+     * Get available slots for a key.
+     */
+    getAvailable(key: string): number;
+    /**
+     * Check if a key is at capacity.
+     */
+    isAtCapacity(key: string): boolean;
+    /**
+     * Get status summary for all keys.
+     */
+    getStatus(): Record<string, {
+        count: number;
+        limit: number;
+        queued: number;
+    }>;
+    /**
+     * Enforce rate limiting (minimum delay between starts).
+     */
+    private enforceRateLimit;
+}
+/**
+ * Create a new ConcurrencyManager instance.
+ */
+export declare function createConcurrencyManager(config?: ConcurrencyConfig): ConcurrencyManager;

package/dist/background/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Background tasking module for Hive worker execution.
+ *
+ * Provides the internal background task management capabilities used by:
+ * - background_task / background_output / background_cancel tools (Task 04)
+ * - hive_exec_start integration (Task 05)
+ *
+ * Core capabilities:
+ * 1. In-memory store with state machine enforcement
+ * 2. Idempotency support for safe retries
+ * 3. Dynamic agent discovery and gating
+ * 4. Hive task persistence via TaskService
+ * 5. Concurrency limiting with queueing (Task 06)
+ * 6. Polling/stability detection - READ-ONLY (Task 06)
+ * 7. Sequential ordering enforcement for Hive tasks (Task 06)
+ */
+export type { BackgroundTaskStatus, BackgroundTaskRecord, BackgroundTaskProgress, SpawnOptions, SpawnResult, OpencodeClient, AgentInfo, AgentValidationResult, } from './types.js';
+export { VALID_TRANSITIONS, isTerminalStatus, isValidTransition, } from './types.js';
+export { BackgroundTaskStore, getStore, resetStore, } from './store.js';
+export type { AgentValidationOptions, } from './agent-gate.js';
+export { AgentGate, createAgentGate, } from './agent-gate.js';
+export type { ConcurrencyConfig, } from './concurrency.js';
+export { ConcurrencyManager, createConcurrencyManager, } from './concurrency.js';
+export type { PollerConfig, TaskObservation, } from './poller.js';
+export { BackgroundPoller, createPoller, } from './poller.js';
+export type { BackgroundManagerOptions, } from './manager.js';
+export { BackgroundManager, createBackgroundManager, } from './manager.js';

package/dist/background/manager.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Background task manager for Hive worker execution.
+ *
+ * Provides the main API for:
+ * - Spawning background tasks with idempotency
+ * - Managing task lifecycle (start, complete, cancel)
+ * - Persisting Hive-linked task metadata via TaskService
+ * - Querying task status
+ * - Concurrency limiting with queueing
+ * - Polling/stability detection (read-only)
+ * - Sequential ordering enforcement for Hive tasks
+ */
+import { BackgroundTaskStore } from './store.js';
+import { AgentGate } from './agent-gate.js';
+import { ConcurrencyManager, ConcurrencyConfig } from './concurrency.js';
+import { BackgroundPoller, PollerConfig, TaskObservation } from './poller.js';
+import { BackgroundTaskRecord, BackgroundTaskStatus, OpencodeClient, SpawnOptions, SpawnResult } from './types.js';
+/**
+ * Options for creating a BackgroundManager.
+ */
+export interface BackgroundManagerOptions {
+    /** OpenCode client for session management */
+    client: OpencodeClient;
+    /** Project root directory for TaskService */
+    projectRoot: string;
+    /** Optional custom store (defaults to global singleton) */
+    store?: BackgroundTaskStore;
+    /** Concurrency configuration */
+    concurrency?: ConcurrencyConfig;
+    /** Poller configuration */
+    poller?: PollerConfig;
+    /** Enforce sequential execution for Hive tasks (default: true) */
+    enforceHiveSequential?: boolean;
+}
+/**
+ * Background task manager.
+ * Coordinates between in-memory store, agent validation, Hive persistence,
+ * concurrency limiting, and polling/stability detection.
+ */
+export declare class BackgroundManager {
+    private store;
+    private agentGate;
+    private client;
+    private taskService;
+    private concurrencyManager;
+    private poller;
+    private enforceHiveSequential;
+    constructor(options: BackgroundManagerOptions);
+    /**
+     * Spawn a new background task.
+     *
+     * Handles idempotency:
+     * - If idempotencyKey is provided and exists, returns existing task
+     * - Otherwise creates new task
+     *
+     * For Hive-linked tasks (hiveFeature + hiveTaskFolder provided):
+     * - Enforces sequential ordering (blocks if earlier tasks pending)
+     * - Persists idempotencyKey and workerSession to .hive task status.json
+     *
+     * @param options - Spawn options
+     * @returns Spawn result with task record
+     */
+    spawn(options: SpawnOptions): Promise<SpawnResult>;
+    /**
+     * Check if a Hive task can be started based on sequential ordering.
+     * Returns error if earlier tasks are still pending/in_progress.
+     */
+    private checkHiveTaskOrdering;
+    /**
+     * Get a task by ID.
+     */
+    getTask(taskId: string): BackgroundTaskRecord | undefined;
+    /**
+     * Get a task by idempotency key.
+     */
+    getTaskByIdempotencyKey(key: string): BackgroundTaskRecord | undefined;
+    /**
+     * Get a task by Hive feature and task folder.
+     */
+    getTaskByHiveTask(feature: string, taskFolder: string): BackgroundTaskRecord | undefined;
+    /**
+     * Update task status.
+     */
+    updateStatus(taskId: string, status: BackgroundTaskStatus, options?: {
+        errorMessage?: string;
+    }): BackgroundTaskRecord;
+    /**
+     * Notify the parent session that a background task completed.
+     *
+     * This intentionally uses session.prompt() so the parent agent "wakes up"
+     * and can continue the workflow (e.g., call background_output).
+     */
+    private notifyParentSession;
+    /**
+     * Cancel a task.
+     */
+    cancel(taskId: string): Promise<BackgroundTaskRecord>;
+    /**
+     * Cancel all active tasks for a parent session.
+     */
+    cancelAll(parentSessionId: string): Promise<BackgroundTaskRecord[]>;
+    /**
+     * List all tasks, optionally filtered.
+     */
+    list(filter?: {
+        status?: BackgroundTaskStatus | BackgroundTaskStatus[];
+        parentSessionId?: string;
+        hiveFeature?: string;
+    }): BackgroundTaskRecord[];
+    /**
+     * Get all active tasks.
+     */
+    getActive(): BackgroundTaskRecord[];
+    /**
+     * Handle session idle event (task completion).
+     */
+    handleSessionIdle(sessionId: string): void;
+    /**
+     * Handle message event (progress update).
+     */
+    handleMessageEvent(sessionId: string, messageText?: string): void;
+    /**
+     * Get the agent gate for direct access.
+     */
+    getAgentGate(): AgentGate;
+    /**
+     * Get the concurrency manager for direct access.
+     */
+    getConcurrencyManager(): ConcurrencyManager;
+    /**
+     * Get the poller for direct access.
+     */
+    getPoller(): BackgroundPoller;
+    /**
+     * Get observations for all active tasks from the poller.
+     */
+    getObservations(): TaskObservation[];
+    /**
+     * Get observation for a specific task.
+     */
+    getTaskObservation(taskId: string): TaskObservation | null;
+    /**
+     * Get task counts by status.
+     */
+    getCounts(): Record<BackgroundTaskStatus, number>;
+    /**
+     * Shutdown the manager and clean up resources.
+     */
+    shutdown(): void;
+}
+/**
+ * Create a new BackgroundManager.
+ */
+export declare function createBackgroundManager(options: BackgroundManagerOptions): BackgroundManager;

package/dist/background/poller.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Background Poller for session status and stability detection.
+ *
+ * This module provides READ-ONLY observation of background task sessions.
+ * It does NOT write to .hive - only updates in-memory task progress.
+ *
+ * Capabilities:
+ * - Track session status (running/idle)
+ * - Track message growth and last activity timestamps
+ * - Compute "maybe stuck" heuristics
+ * - Exponential backoff to avoid polling storms
+ */
+import { BackgroundTaskStore } from './store.js';
+import { OpencodeClient } from './types.js';
+/**
+ * Configuration for the background poller.
+ */
+export interface PollerConfig {
+    /** Base polling interval in ms (default: 5000) */
+    pollIntervalMs?: number;
+    /** Max polling interval with backoff (default: 30000) */
+    maxPollIntervalMs?: number;
+    /** Time before task is considered "maybe stuck" (default: 600000 = 10 min) */
+    stuckThresholdMs?: number;
+    /** Minimum runtime before stuck detection kicks in (default: 30000 = 30 sec) */
+    minRuntimeBeforeStuckMs?: number;
+    /** Consecutive stable polls before marking as stable (default: 3) */
+    stableCountThreshold?: number;
+}
+/**
+ * Optional callbacks for reacting to observed session state.
+ *
+ * NOTE: Poller remains "read-only" with respect to `.hive`.
+ * These callbacks are intended for in-memory lifecycle transitions (e.g. marking
+ * a background task completed) handled by the owning manager.
+ */
+export interface PollerHandlers {
+    /**
+     * Invoked when the poller observes that a background session is idle/complete.
+     *
+     * The owning manager should:
+     * - transition the task to a terminal state
+     * - release any concurrency slot
+     * - cleanup poller state
+     */
+    onSessionIdle?: (sessionId: string, reason: 'status' | 'stable') => void;
+}
+/**
+ * Observation result for a single task.
+ */
+export interface TaskObservation {
+    taskId: string;
+    sessionId: string;
+    status: string;
+    messageCount: number;
+    lastActivityAt: string | null;
+    maybeStuck: boolean;
+    stablePolls: number;
+    isStable: boolean;
+}
+/**
+ * Background Poller - read-only observer for task sessions.
+ *
+ * IMPORTANT: This poller does NOT write to .hive.
+ * It only updates in-memory task progress for status reporting.
+ */
+export declare class BackgroundPoller {
+    private store;
+    private client;
+    private config;
+    private handlers;
+    private pollingState;
+    private pollInterval;
+    private isPolling;
+    private currentIntervalMs;
+    constructor(store: BackgroundTaskStore, client: OpencodeClient, config?: PollerConfig, handlers?: PollerHandlers);
+    /**
+     * Start the background poller.
+     * Automatically stops when no active tasks remain.
+     */
+    start(): void;
+    /**
+     * Stop the background poller.
+     */
+    stop(): void;
+    /**
+     * Check if poller is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get observations for all active tasks.
+     * This is a read-only snapshot of current state.
+     */
+    getObservations(): TaskObservation[];
+    /**
+     * Get observation for a specific task.
+     */
+    getTaskObservation(taskId: string): TaskObservation | null;
+    /**
+     * Perform a single poll cycle.
+     * Updates in-memory progress only - NO .hive writes.
+     */
+    poll(): Promise<void>;
+    /**
+     * Poll a single task and update its progress.
+     * READ-ONLY: Only updates in-memory store, never writes .hive.
+     */
+    private pollTask;
+    /**
+     * Build an observation from task and polling state.
+     */
+    private buildObservation;
+    /**
+     * Adjust polling interval based on activity patterns.
+     * Uses exponential backoff when tasks are stable.
+     */
+    private adjustPollingInterval;
+    /**
+     * Clean up polling state for a task.
+     * Call when task reaches terminal state.
+     */
+    cleanupTask(taskId: string): void;
+    /**
+     * Clear all state (for testing or shutdown).
+     */
+    clear(): void;
+}
+/**
+ * Create a new BackgroundPoller instance.
+ */
+export declare function createPoller(store: BackgroundTaskStore, client: OpencodeClient, config?: PollerConfig, handlers?: PollerHandlers): BackgroundPoller;

package/dist/background/store.d.ts

@@ -0,0 +1,100 @@
+/**
+ * In-memory store for background task records.
+ *
+ * Provides:
+ * - CRUD operations for task records
+ * - Idempotency key lookups
+ * - State machine enforcement
+ * - Query methods for task filtering
+ */
+import { BackgroundTaskRecord, BackgroundTaskStatus, BackgroundTaskProgress } from './types.js';
+/**
+ * In-memory store for background tasks.
+ * Thread-safe for single-process Node.js (no concurrent access issues).
+ */
+export declare class BackgroundTaskStore {
+    private tasks;
+    private idempotencyIndex;
+    /**
+     * Create a new task record.
+     *
+     * @param options - Task creation options
+     * @returns The created task record
+     * @throws If idempotencyKey already exists (use getByIdempotencyKey first)
+     */
+    create(options: {
+        agent: string;
+        description: string;
+        sessionId: string;
+        idempotencyKey?: string;
+        parentSessionId?: string;
+        parentMessageId?: string;
+        parentAgent?: string;
+        notifyParent?: boolean;
+        hiveFeature?: string;
+        hiveTaskFolder?: string;
+        workdir?: string;
+    }): BackgroundTaskRecord;
+    /**
+     * Get a task by ID.
+     */
+    get(taskId: string): BackgroundTaskRecord | undefined;
+    /**
+     * Get a task by idempotency key.
+     */
+    getByIdempotencyKey(key: string): BackgroundTaskRecord | undefined;
+    /**
+     * Get a task by Hive feature and task folder.
+     */
+    getByHiveTask(feature: string, taskFolder: string): BackgroundTaskRecord | undefined;
+    /**
+     * Update task status with state machine enforcement.
+     *
+     * @param taskId - Task ID to update
+     * @param newStatus - New status
+     * @param updates - Additional field updates
+     * @returns Updated task record
+     * @throws If transition is invalid
+     */
+    updateStatus(taskId: string, newStatus: BackgroundTaskStatus, updates?: Partial<Pick<BackgroundTaskRecord, 'errorMessage' | 'progress'>>): BackgroundTaskRecord;
+    /**
+     * Update task progress without changing status.
+     */
+    updateProgress(taskId: string, progress: Partial<BackgroundTaskProgress>): BackgroundTaskRecord;
+    /**
+     * Delete a task.
+     */
+    delete(taskId: string): boolean;
+    /**
+     * List all tasks, optionally filtered.
+     */
+    list(filter?: {
+        status?: BackgroundTaskStatus | BackgroundTaskStatus[];
+        parentSessionId?: string;
+        hiveFeature?: string;
+    }): BackgroundTaskRecord[];
+    /**
+     * Get all active (non-terminal) tasks.
+     */
+    getActive(): BackgroundTaskRecord[];
+    /**
+     * Get task count by status.
+     */
+    countByStatus(): Record<BackgroundTaskStatus, number>;
+    /**
+     * Clear all tasks (for testing).
+     */
+    clear(): void;
+    /**
+     * Get total task count.
+     */
+    get size(): number;
+}
+/**
+ * Get or create the global store instance.
+ */
+export declare function getStore(): BackgroundTaskStore;
+/**
+ * Reset the global store (for testing).
+ */
+export declare function resetStore(): void;