@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/sources/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Source management module for the orchestrator.
+ *
+ * Provides CRUD operations (SourceStore), LISTEN/NOTIFY hot reload (SourceManager),
+ * and credential validation (validateGitHubSource) for webhook sources.
+ */
+export { SourceStore, type AddSourceParams, type SourceWithSecrets } from './source-store.js';
+export { SourceManager, type SourceManagerOptions } from './source-manager.js';
+export { validateGitHubSource, type ValidationResult } from './source-validator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/sources/source-manager.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Source manager with LISTEN/NOTIFY hot reload.
+ *
+ * Subscribes to PostgreSQL LISTEN/NOTIFY on the `sources_change` channel
+ * to detect source configuration changes. When a change is detected,
+ * reloads sources from the database, rebuilds the ProviderRegistry,
+ * and notifies the caller of added/removed sources via a callback.
+ *
+ * Debounces rapid changes to avoid excessive reloads.
+ */
+import type pg from 'pg';
+import { ProviderRegistry } from '../provider-registry.js';
+import type { ProviderSource } from '../entry-helpers.js';
+import type { SourceStore } from './source-store.js';
+/**
+ * Options for creating a SourceManager.
+ */
+export interface SourceManagerOptions {
+    /** Raw pg pool for LISTEN/NOTIFY subscriber. */
+    pool: pg.Pool;
+    /** SourceStore for reading sources and secrets. */
+    sourceStore: SourceStore;
+    /** Callback invoked when source diff is detected (for Platform registration). */
+    onSourcesChanged: (diff: {
+        added: ProviderSource[];
+        removed: ProviderSource[];
+    }) => void;
+    /** Debounce interval in ms for coalescing rapid changes. Default: 200. */
+    debounceMs?: number;
+}
+/**
+ * Manages webhook sources from the database with hot reload support.
+ *
+ * On start, loads all sources, builds a ProviderRegistry, and subscribes
+ * to LISTEN sources_change. On each NOTIFY, debounces and reloads,
+ * rebuilding the registry and computing the diff for Platform registration.
+ */
+export declare class SourceManager {
+    private readonly opts;
+    private client;
+    private registry;
+    private currentSources;
+    private debounceTimer;
+    private readonly debounceMs;
+    constructor(opts: SourceManagerOptions);
+    /** Get current ProviderRegistry (rebuilt on each reload). */
+    getRegistry(): ProviderRegistry;
+    /** Get current sources for Platform registration. */
+    getSources(): ProviderSource[];
+    /** Initial load + subscribe to changes. */
+    start(): Promise<ProviderRegistry>;
+    /** Stop listening and release the dedicated pg client. */
+    stop(): Promise<void>;
+    private scheduleReload;
+    /** Reload sources from DB and rebuild the ProviderRegistry. */
+    reload(): Promise<void>;
+    /**
+     * Build a ProviderBundle for a source with decrypted secrets.
+     * Currently only supports GitHub; throws for unknown providers.
+     */
+    private buildBundle;
+}
+//# sourceMappingURL=source-manager.d.ts.map

package/dist/sources/source-store.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Source store for orchestrator webhook source management.
+ *
+ * Provides CRUD operations for the sources table with secret storage
+ * via PgSecretStore. Secrets (private keys, webhook secrets) are stored
+ * separately from the source config to leverage the existing encryption
+ * infrastructure.
+ */
+import { type Kysely } from 'kysely';
+import type { Database, Source } from '../db/types.js';
+import type { PgSecretStore } from '../secrets/pg-secret-store.js';
+/**
+ * Parameters for adding a new source.
+ */
+export interface AddSourceParams {
+    /** Provider type (e.g. 'github') */
+    provider: string;
+    /** Human-readable source name */
+    name: string;
+    /** App ID for the provider (used to build routing key) */
+    appId: string;
+    /** Private key (PEM format for GitHub Apps) */
+    privateKey: string;
+    /** Webhook secret for signature verification */
+    webhookSecret?: string;
+    /** Extra non-sensitive config */
+    config?: Record<string, unknown>;
+    /** Customer/org identifier for secret and environment scoping */
+    customerId?: string;
+}
+/**
+ * A source with its decrypted secrets.
+ */
+export interface SourceWithSecrets extends Source {
+    privateKey: string;
+    webhookSecret?: string;
+}
+/**
+ * CRUD store for webhook sources backed by PostgreSQL.
+ * Sensitive credentials are stored in PgSecretStore under `__source__/<id>`.
+ */
+export declare class SourceStore {
+    private readonly db;
+    private readonly secretStore;
+    constructor(db: Kysely<Database>, secretStore: PgSecretStore);
+    /**
+     * Add a new source. Stores config in sources table, secrets in PgSecretStore.
+     * Routing key is computed as `<provider>:<appId>`.
+     */
+    addSource(params: AddSourceParams): Promise<Source>;
+    /**
+     * List all sources (no secrets exposed).
+     */
+    listSources(): Promise<Source[]>;
+    /**
+     * Get a single source by routing key, or null if not found.
+     */
+    getSource(routingKey: string): Promise<Source | null>;
+    /**
+     * Get a source with its decrypted secrets.
+     */
+    getSourceWithSecrets(routingKey: string): Promise<SourceWithSecrets | null>;
+    /**
+     * Update a source's name/config and optionally rotate secrets.
+     */
+    updateSource(routingKey: string, updates: {
+        name?: string;
+        privateKey?: string;
+        webhookSecret?: string;
+        config?: Record<string, unknown>;
+        /** New customer/org identifier (used for secret + environment scoping). */
+        customerId?: string;
+    }): Promise<Source>;
+    /**
+     * Remove a source and its associated secrets.
+     */
+    removeSource(routingKey: string): Promise<void>;
+}
+//# sourceMappingURL=source-store.d.ts.map

package/dist/sources/source-validator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Result of a source credential validation.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    appName?: string;
+    error?: string;
+}
+/**
+ * Validate GitHub App credentials by calling the GitHub API.
+ *
+ * Creates a JWT from the appId + privateKey and calls GET /app
+ * to verify the credentials are valid and retrieve the app name.
+ */
+export declare function validateGitHubSource(appId: string, privateKey: string): Promise<ValidationResult>;
+//# sourceMappingURL=source-validator.d.ts.map

package/dist/stale-detector/stale-run-detector.d.ts

@@ -0,0 +1,109 @@
+/**
+ * StaleRunDetector: periodic DB scanner for stale execution jobs.
+ *
+ * Detects jobs that have stopped sending heartbeats (agent died, network partition,
+ * container killed, etc.) and marks them as timed_out_stale. Also detects stale
+ * dispatch_queue entries that were dispatched but never acknowledged.
+ *
+ * Key behaviors:
+ * - Immediate startup scan for crash recovery (finds stale jobs from before restart)
+ * - Periodic scans at configurable interval (default 60s)
+ * - Uses timed_out_stale as distinct DB status (not just 'failed')
+ * - Optimistic concurrency: WHERE status='running' prevents race with agent completion
+ * - Does NOT call executionTracker.onJobStatus() to avoid redundant DB writes
+ * - Updates in-memory state and calls completeRunIfAllJobsTerminal for run completion
+ * - Force-terminates stale agents via scaler manager
+ * - Updates GitHub check runs with timed_out conclusion
+ */
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+import type { CommitStatusReporter } from '../reporting/commit-status.js';
+import type { ScalerManager } from '../scaler/manager.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { HeldRunStore } from '../environments/held-runs.js';
+export interface StaleRunDetectorDeps {
+    db: Kysely<Database>;
+    executionTracker: ExecutionTracker;
+    commitStatusReporter?: CommitStatusReporter;
+    scalerManager?: ScalerManager;
+    dispatcher: Dispatcher;
+    registry: AgentRegistry;
+    /** Threshold in ms after which a job is considered stale. Default: heartbeatIntervalMs * multiplier */
+    staleThresholdMs: number;
+    /** How often to scan for stale jobs in ms. Default: 60_000 */
+    scanIntervalMs: number;
+    /** Held run store for expiring overdue held runs. Optional -- if not set, held run cleanup is skipped. */
+    heldRunStore?: HeldRunStore;
+}
+export declare class StaleRunDetector {
+    private readonly db;
+    private readonly executionTracker;
+    private readonly commitStatusReporter?;
+    private readonly scalerManager?;
+    private readonly dispatcher;
+    private readonly registry;
+    private readonly staleThresholdMs;
+    private readonly scanIntervalMs;
+    private readonly heldRunStore?;
+    private interval;
+    constructor(deps: StaleRunDetectorDeps);
+    /**
+     * Clean up orphaned jobs left in 'recovering' state from a previous orchestrator instance.
+     *
+     * Recovery timers are in-memory (Dispatcher) and lost on restart. Any jobs still
+     * in 'recovering' state after a restart have no timer and no path to completion,
+     * so they must be failed immediately.
+     *
+     * Call this during startup, before the first periodic scan.
+     */
+    cleanupOrphanedRecoveryJobs(): Promise<void>;
+    /**
+     * Start the stale run detector.
+     * Runs an immediate scan for crash recovery, then starts periodic scans.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the stale run detector.
+     */
+    stop(): void;
+    /**
+     * Run a single stale detection scan.
+     *
+     * Three sub-scans:
+     * A. Running jobs with old heartbeat (last_heartbeat_at < threshold)
+     * B. Running jobs with NULL heartbeat (created_at < threshold, pre-heartbeat jobs)
+     * C. Dispatched queue entries that were never acknowledged
+     *
+     * After all sub-scans, checks run completion for affected runs.
+     *
+     * Note: jobs in 'recovering' state are NOT scanned -- they have their own
+     * per-job recovery timers managed by the Dispatcher (see Phase 15).
+     * All sub-scans filter on status='running' or status='dispatched',
+     * so recovering jobs are naturally excluded.
+     */
+    scan(): Promise<void>;
+    /**
+     * Sub-scan A: Find running jobs with stale heartbeats.
+     */
+    private scanStaleRunningJobs;
+    /**
+     * Sub-scan B: Find running jobs with NULL heartbeat and old created_at.
+     * These are jobs that started before the heartbeat system existed or where
+     * the initial heartbeat was never set.
+     */
+    private scanStaleRunningJobsNullHeartbeat;
+    /**
+     * Sub-scan C: Find dispatched entries that were never acknowledged.
+     * Only checks 'dispatched' status (job sent to agent but agent never started it).
+     * 'queued' jobs are legitimately waiting for agents and handled by queue timeout instead.
+     */
+    private scanStaleDispatchedJobs;
+    /**
+     * Mark a single running job as timed_out_stale.
+     * Shared by sub-scans A and B.
+     */
+    private markJobStale;
+}
+//# sourceMappingURL=stale-run-detector.d.ts.map

package/dist/standalone.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Independent mode entry point for the customer orchestrator.
+ *
+ * Operates in 'independent' mode:
+ * - Receives webhooks ONLY via direct HTTP endpoints
+ * - No Platform WS relay connection
+ * - No event buffer (nothing to buffer for)
+ *
+ * Same as server.ts but WITHOUT PlatformClient.
+ * Webhooks arrive only via the per-source generic webhook endpoints at
+ * /webhook/:orgId/generic/:sourceId, registered with `kici-admin source add`.
+ *
+ * Startup sequence:
+ * config -> DB -> provider registry -> dispatcher -> app -> HTTP -> heartbeat
+ *
+ * Graceful shutdown:
+ * agent WS -> heartbeat -> HTTP -> DB
+ */
+export {};
+//# sourceMappingURL=standalone.d.ts.map