@jokerized/getresearchdone 0.4.1

package/dist/lib/scheduler.d.ts

@@ -0,0 +1,254 @@
+/**
+ * GRD Scheduler -- Backend subprocess spawning, account rotation, budget pressure tracking,
+ * and idle watchdog. Dispatches agents to claude/codex/gemini/opencode CLI backends with
+ * per-account token budget monitoring and adaptive model-tier downgrade under pressure.
+ *
+ * @module scheduler
+ */
+import type { BackendId, AdapterBackendId, BackendAdapter, BackendUsageState, UsageSample, SpawnOpts, AccountResolution, SuperpowersConfig, SchedulerConfig, SchedulerSpawnResult, BudgetPressureLevel, BudgetPressureThresholds } from './types';
+import type * as childProcess from 'child_process';
+export declare const ADAPTERS: Record<AdapterBackendId, BackendAdapter>;
+/**
+ * Maps each adapter backend to its config-directory environment variable.
+ * Used by account rotation to override which account a CLI binary uses.
+ */
+export declare const ENV_VAR_MAP: Record<AdapterBackendId, string>;
+/** Token-per-minute budget for the free-fallback backend (effectively unlimited). */
+export declare const FREE_FALLBACK_BUDGET = 1000000;
+/**
+ * Creates a fresh BackendUsageState with the given token budget.
+ *
+ * @param tokenBudget - tokens-per-minute budget for this backend
+ * @returns initialized state with zeroed counters
+ */
+export declare function createBackendState(tokenBudget: number): BackendUsageState;
+/**
+ * Updates the EWMA estimate in-place with a new token observation.
+ * On first observation (ewma === 0), sets directly to the observed value.
+ *
+ * @param state - backend usage state to update
+ * @param tokens - observed token count for the latest task
+ * @param alpha - EWMA smoothing factor (0 < alpha < 1)
+ */
+export declare function updateEWMA(state: BackendUsageState, tokens: number, alpha: number): void;
+/**
+ * Removes samples older than windowMinutes from state and recalculates
+ * tokens_consumed_in_window from the remaining samples.
+ *
+ * @param state - backend usage state to mutate
+ * @param windowMinutes - rolling window duration in minutes
+ */
+export declare function evictExpiredSamples(state: BackendUsageState, windowMinutes: number): void;
+/**
+ * Records a completed usage sample, evicts stale samples from the window,
+ * updates EWMA, and recalculates budget_confidence.
+ *
+ * @param state - backend usage state to update
+ * @param sample - new usage sample to record
+ * @param windowMinutes - rolling window duration in minutes
+ * @param alpha - EWMA smoothing factor
+ */
+export declare function recordSample(state: BackendUsageState, sample: UsageSample, windowMinutes: number, alpha: number): void;
+/**
+ * Selects the highest-priority backend that has sufficient token headroom.
+ * Skips backends in cooldown or without enough remaining capacity (accounting
+ * for in-flight reservations). Falls back to freeFallback if none qualify.
+ *
+ * @param priority - ordered list of backend IDs to try
+ * @param states - map of backend ID to usage state
+ * @param safetyMargin - minimum remaining tasks before a backend is considered full
+ * @param freeFallback - fallback backend used when all priority backends are exhausted
+ * @returns selected BackendId
+ */
+export declare function pickBackend(priority: BackendId[], states: Map<string, BackendUsageState>, safetyMargin: number, freeFallback: {
+    backend: BackendId;
+}): BackendId;
+/**
+ * Sends `signal` to the process group of `child` on POSIX platforms, or to
+ * the direct child on Windows. Using a negative PID with process.kill ensures
+ * grandchildren (e.g., tool-invocation forks spawned by the backend CLI) are
+ * also terminated.
+ *
+ * Requires the child to have been spawned with `detached: true` so that it
+ * gets its own process group (pgid === pid).
+ *
+ * @param child - the spawned ChildProcess whose process group to signal
+ * @param signal - signal to send (e.g. 'SIGTERM', 'SIGKILL')
+ */
+export declare function _killProcessTree(child: Pick<childProcess.ChildProcess, 'pid' | 'kill'>, signal: NodeJS.Signals): void;
+/**
+ * Resolves the idle timeout in seconds for the given backend, applying the
+ * lookup order: per-backend override → global idle_timeout_seconds → default 900.
+ *
+ * @param backend - backend ID (e.g. 'claude', 'gemini')
+ * @param config - subset of SchedulerConfig with timeout fields
+ * @returns resolved idle timeout in seconds
+ */
+export declare function _resolveIdleTimeoutSeconds(backend: string, config: {
+    idle_timeout_seconds_by_backend?: Record<string, number>;
+    idle_timeout_seconds?: number;
+}): number;
+/**
+ * Starts an idle watchdog that invokes `onIdle` when no markActivity
+ * has been called for longer than `idleTimeoutMs`. Returns markActivity
+ * and stop functions.
+ *
+ * Polls every 1000ms. Fires at most once — subsequent ticks are no-ops.
+ */
+export declare function _startIdleWatchdog(idleTimeoutMs: number, onIdle: () => void): {
+    markActivity: () => void;
+    stop: () => void;
+};
+/**
+ * Returns true iff at least one account in the priority list has headroom.
+ * Small helper used by the _spawnWithRetry wait-branch decision.
+ */
+export declare function _anyPriorityHasHeadroom(priority: BackendId[], accounts: SuperpowersConfig['accounts'], states: Map<string, BackendUsageState>, safetyMargin: number): boolean;
+/**
+ * Computes the earliest timestamp (ms since epoch) at which ANY priority
+ * account will regain headroom based on sample aging out of the rolling
+ * window. Used by the wait-loop in _spawnWithRetry when all priority
+ * accounts are currently exhausted.
+ *
+ * For each priority account, walks its samples oldest-first, hypothetically
+ * dropping each one and recomputing projected headroom. The latest-dropped
+ * sample's timestamp + windowMinutes is the moment that account will have
+ * enough headroom for one more EWMA-sized task.
+ *
+ * Returns null if:
+ *   - No priority account has samples (nothing to wait for)
+ *   - Soonest recovery across all accounts is beyond Date.now() + maxWaitMs
+ *   - All considered accounts have zero ewma_tokens_per_task (no prediction data)
+ *
+ * Pattern adopted from gsd-2 v2.67 auto-timeout-recovery.ts — but
+ * sample-based rather than attempt-based.
+ *
+ * Note: tokens_reserved (in-flight EWMA cost) is held constant during the
+ * simulation because in-flight tasks are expected to complete independently
+ * of sample aging. This makes the estimate slightly pessimistic — actual
+ * headroom may return sooner.
+ */
+export declare function computeSoonestRecovery(states: Map<string, BackendUsageState>, priority: BackendId[], accounts: SuperpowersConfig['accounts'], windowMinutes: number, maxWaitMs: number): number | null;
+/**
+ * Returns true if any priority account has consumed more than the warning
+ * threshold (default 60%) of its rolling-window budget. Pure function.
+ */
+export declare function isBudgetPressured(states: Map<string, BackendUsageState>, priority: BackendId[], accounts: SuperpowersConfig['accounts'], thresholds?: BudgetPressureThresholds): boolean;
+/**
+ * Logs a single stderr line when the pressure level has changed since
+ * the last call with the same sessionKey. Safe to call per spawn —
+ * only emits on transitions. Noop when current == previous.
+ *
+ * The sessionKey lets multiple sessions in the same process have
+ * independent transition state. Autopilot/evolve/autoresearch
+ * typically pass process.pid.toString().
+ */
+export declare function logPressureTransition(sessionKey: string, current: BudgetPressureLevel, agentType: string, baseTier: string, effectiveTier: string): void;
+/**
+ * Classifies the worst pressure level across all priority accounts.
+ * Returns 'none' | 'warning' | 'high' | 'critical'. Pure function.
+ *
+ * For each priority account, computes (consumed + reserved) / budget
+ * and picks the worst ratio across all accounts (i.e., the one closest
+ * to exhaustion determines the level for the whole session).
+ */
+export declare function computeBudgetPressureLevel(states: Map<string, BackendUsageState>, priority: BackendId[], accounts: SuperpowersConfig['accounts'], thresholds?: BudgetPressureThresholds): BudgetPressureLevel;
+/**
+ * Resolves which backend and account to use for the next scheduled task.
+ * Walks the backend_priority list, and within each backend tries every
+ * configured account in order. Falls back to the free_fallback backend
+ * when all priority accounts are exhausted.
+ *
+ * Edge cases:
+ * - Empty accounts ({}) — returns default_backend with no config dir override
+ * - Empty account array ([]) — skips that backend
+ * - Backend in priority but missing from accounts — skipped
+ *
+ * @param superpowersConfig - superpowers configuration with accounts
+ * @param schedulerConfig - scheduler configuration with priority and fallback
+ * @param states - map of compound state keys to usage state
+ * @param safetyMargin - minimum remaining tasks before an account is considered full
+ * @returns resolved backend, account, and state key
+ */
+export declare function resolveAccount(superpowersConfig: SuperpowersConfig, schedulerConfig: SchedulerConfig, states: Map<string, BackendUsageState>, safetyMargin: number): AccountResolution;
+/**
+ * Marks one task as in-flight, incrementing the in-flight counter and
+ * reserving the EWMA-predicted token cost.
+ *
+ * @param state - backend usage state to mutate
+ */
+export declare function markInFlight(state: BackendUsageState): void;
+/**
+ * Marks one in-flight task as complete, decrementing the counter and
+ * recalculating tokens_reserved from the updated in-flight count.
+ *
+ * @param state - backend usage state to mutate
+ */
+export declare function markComplete(state: BackendUsageState): void;
+/**
+ * Checks whether a CLI binary is available on the system PATH.
+ * Uses 'where' on Windows and 'which' on POSIX (I8 fix).
+ */
+export declare function checkBinary(binary: string): boolean;
+/**
+ * High-level scheduler that selects backends, spawns CLI processes,
+ * records usage samples, and persists learned state across sessions.
+ */
+export interface Scheduler {
+    /**
+     * Unique per-createScheduler session key used to namespace pressure
+     * transition logging. Format: 'pid-<pid>-session-<counter>'. Read-only.
+     * (O3 fix — multiple createScheduler calls in the same process no
+     * longer share _lastLoggedPressure state.)
+     */
+    readonly sessionKey: string;
+    spawn(prompt: string, opts: SpawnOpts): Promise<SchedulerSpawnResult>;
+    getState(stateKey: string): BackendUsageState | undefined;
+    /**
+     * Returns a snapshot of the current per-account states map. Used by
+     * the Spec 4 budget pressure detection and complexity estimation
+     * wire-ups. Do NOT mutate the returned map — it is shared with the
+     * scheduler's internal state.
+     */
+    getStates(): Map<string, BackendUsageState>;
+    recordExternalSample(stateKey: string, sample: UsageSample): void;
+    persistState(planningDir: string): void;
+    loadPersistedState(planningDir: string): void;
+}
+/**
+ * Creates a Scheduler instance from the given config, or returns null
+ * when no config is provided (pass-through / disabled mode).
+ *
+ * When superpowersConfig is provided with account_rotation enabled, the
+ * scheduler tracks per-account state and uses resolveAccount() for backend
+ * selection. Otherwise, it uses the simple pickBackend() flow.
+ *
+ * @param config - scheduler configuration, or undefined to disable
+ * @param superpowersConfig - optional superpowers configuration for account rotation
+ * @returns Scheduler instance, or null if config is absent
+ */
+export declare function createScheduler(config: SchedulerConfig | undefined, superpowersConfig?: SuperpowersConfig): Scheduler | null;
+/** Result from detectSpin analysis. */
+export interface SpinDetectedEvent {
+    detected: boolean;
+    /** The repeated pattern excerpt (first 200 chars of the repeated chunk). */
+    repeated_pattern: string;
+    /** Number of consecutive similar chunks detected. */
+    consecutive_count: number;
+    /** Similarity score of the most repeated pair (0-1). */
+    max_similarity: number;
+}
+/**
+ * Analyze the last N stdout chunks from an agent run to detect spin (looping on
+ * the same error without progress). Uses bigram overlap (Jaccard similarity) to
+ * compare consecutive chunks.
+ *
+ * Returns SpinDetectedEvent with detected=true if 3+ consecutive pairs have
+ * similarity >= threshold (default 0.80).
+ *
+ * @param chunks - Array of stdout text chunks (ordered chronologically)
+ * @param threshold - Similarity threshold for spin detection (default 0.80)
+ * @param windowSize - Number of recent chunks to analyze (default 5)
+ */
+export declare function detectSpin(chunks: string[], threshold?: number, windowSize?: number): SpinDetectedEvent;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/lib/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../lib/scheduler.ts"],"names":[],"mappings":"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"}