@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/ws/agent-handler.d.ts

@@ -0,0 +1,176 @@
+/**
+ * WebSocket handler for agent connections.
+ *
+ * Agents connect to the orchestrator via WebSocket to:
+ * - Authenticate with a kat_ token (when agentAuthMode === 'token')
+ * - Register their capabilities (labels, concurrency)
+ * - Receive job dispatches
+ * - Report job execution status
+ * - Send periodic heartbeats
+ *
+ * Two-phase auth flow (when agentAuthMode === 'token'):
+ * 1. pendingAuth (5s): Agent must send auth.request with a valid kat_ token.
+ * 2. pendingRegistration (10s): After auth.success, agent must send agent.register.
+ * 3. registered: Agent is fully connected and can exchange messages.
+ *
+ * When agentAuthMode === 'none', the auth phase is skipped (legacy behavior).
+ */
+import type { WSEvents } from 'hono/ws';
+import type { RateLimiterConfig } from '@kici-dev/engine';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { AgentTokenStore } from '../agent/token-store.js';
+import type { OwnershipTracker } from '../agent/ownership-tracker.js';
+import type { SourceCache } from '../cache/source-cache.js';
+import type { DepCache } from '../cache/dep-cache.js';
+import type { PendingBuildTracker } from '../cache/pending-builds.js';
+import type { PendingInitTracker } from '../cache/pending-inits.js';
+import type { PendingDynamicTracker } from '../cache/pending-dynamics.js';
+import type { CacheStorage } from '../storage/types.js';
+import type { AgentMetricsAggregator } from '../metrics/agent-metrics-aggregator.js';
+import type { AgentApiRegistry } from './agent-api-registry.js';
+export interface AgentWsHandlerDeps {
+    registry: AgentRegistry;
+    dispatcher: Dispatcher;
+    /** Token store for validating agent auth tokens. Undefined when auth disabled. */
+    tokenStore?: AgentTokenStore;
+    /** Agent authentication mode. 'token' requires auth.request before register. */
+    agentAuthMode: 'token' | 'none';
+    /** Optional callback to forward job status to the Platform client. */
+    onJobStatus?: (agentId: string, msg: {
+        runId: string;
+        jobId: string;
+        state: string;
+        timestamp: number;
+        data?: Record<string, unknown>;
+    }) => void;
+    /** Optional callback when agent sends log chunks. */
+    onLogChunk?: (agentId: string, msg: {
+        runId: string;
+        jobId: string;
+        stepIndex: number;
+        lines: string[];
+        timestamp: number;
+    }) => void;
+    /** Optional callback when agent sends step status updates. */
+    onStepStatus?: (agentId: string, msg: {
+        runId: string;
+        jobId: string;
+        stepIndex: number;
+        stepName: string;
+        state: string;
+        timestamp: number;
+        data?: Record<string, unknown>;
+        secretsAccessed?: string[];
+        /** Raw log bytes accumulated by this step's LogStreamer at terminal time. */
+        logBytesStreamed?: number;
+    }) => void;
+    /**
+     * Optional callback when a scaler-managed agent registers.
+     *
+     * Returns:
+     * - `boundJobId` (optional): set when the scaler bound a specific queued
+     *   job to this agent at spawn time. The orchestrator eagerly dispatches
+     *   that job before the agent's idle timer fires.
+     * - `mandatoryLabels` (always populated for scaler-managed agents): the
+     *   spawning scaler's Kubernetes-taint-style gate. Threaded into the
+     *   AgentRegistry so subsequent label matches (queue drain + eager
+     *   dispatch) apply the same gate the scaler-side selector applied.
+     *
+     * Returns `null` for static agents not managed by any scaler.
+     */
+    onScalerAgentRegistered?: (agentId: string, labels: string[]) => {
+        boundJobId?: string;
+        mandatoryLabels: string[];
+    } | null;
+    /** Optional callback when an agent disconnects (for scaler lifecycle). */
+    onScalerAgentDisconnected?: (agentId: string) => void;
+    /** Optional callback when an agent completes a job (for scaler lifecycle). */
+    onScalerJobComplete?: (agentId: string) => void;
+    /** Optional callback when agent sends per-job heartbeats. */
+    onJobHeartbeat?: (agentId: string, msg: {
+        runId: string;
+        jobId: string;
+        timestamp: number;
+    }) => void;
+    /** Optional callback when agent sends operational log lines (stateful/external agents via WS). */
+    onAgentLog?: (agentId: string, msg: {
+        lines: string[];
+        timestamp: number;
+    }) => void;
+    /** Optional callback when agent acknowledges config (for MMDS clearing in Firecracker). */
+    onConfigAck?: (agentId: string) => void;
+    /** Optional callback when agent emits a custom event via ctx.emit(). */
+    onEventEmit?: (agentId: string, msg: {
+        jobId: string;
+        requestId: string;
+        eventName: string;
+        payload: Record<string, unknown>;
+        target?: {
+            repos?: string[];
+        };
+    }) => Promise<{
+        deliveryId?: string;
+        error?: string;
+    }>;
+    /** Optional callback when agent sends a run.event for infrastructure lifecycle tracking. */
+    onRunEvent?: (agentId: string, msg: {
+        runId: string;
+        eventType: string;
+        timestampMs: number;
+        sourceService: string;
+        jobId?: string | null;
+        metadata?: Record<string, unknown>;
+        durationMs?: number | null;
+    }) => void;
+    /** Optional callback when agent sends a job.context with execution environment details. */
+    onJobContext?: (agentId: string, msg: {
+        runId: string;
+        jobId: string;
+        context: Record<string, unknown>;
+    }) => void;
+    /** Bundle cache for generating pre-signed upload URLs. */
+    sourceCache?: SourceCache;
+    /** Dep cache for generating pre-signed upload URLs. */
+    depCache?: DepCache;
+    /** Cache storage for setting metadata after upload completion. */
+    cacheStorage?: CacheStorage;
+    /** Optional rate limiter configuration. */
+    rateLimiterConfig?: RateLimiterConfig;
+    /** Optional ownership tracker for validating job-related messages. */
+    ownershipTracker?: OwnershipTracker;
+    /** Optional pending build tracker for cleanup on agent disconnect. */
+    pendingBuilds?: PendingBuildTracker;
+    /** Optional pending init tracker for cleanup on agent disconnect. */
+    pendingInits?: PendingInitTracker;
+    /** Optional pending dynamic tracker for cleanup on agent disconnect. */
+    pendingDynamics?: PendingDynamicTracker;
+    /** Optional callback when agent sends encrypted secret outputs on job success. */
+    onSecretOutputs?: (runId: string, jobId: string, secretOutputs: Record<string, {
+        agentPublicKey: string;
+        encrypted: string;
+    }>) => Promise<void>;
+    /** Agent metrics aggregator for receiving pushed metrics. */
+    agentMetricsAggregator?: AgentMetricsAggregator;
+    /** Optional callback when agent reports a job belongs to a concurrency group. */
+    onConcurrencyReport?: (agentId: string, msg: {
+        runId: string;
+        jobId: string;
+        group: string;
+        messageId: string;
+    }) => Promise<{
+        action: 'proceed' | 'wait' | 'cancel';
+        reason?: string;
+    }>;
+    /**
+     * Optional callback fired when an agent's WS connection closes, after the
+     * dispatcher's own cleanup has run. Used by the long-poll concurrency
+     * pipeline to drop the agent's queued waiters and `cancelQueued` the
+     * matching DB rows so the run is marked failed instead of dangling.
+     */
+    onConcurrencyAgentDisconnect?: (agentId: string) => void | Promise<void>;
+    /** Agent private API registry for handling agent.api.request messages. */
+    agentApiRegistry?: AgentApiRegistry;
+}
+export declare function createAgentWsHandler(deps: AgentWsHandlerDeps): WSEvents;
+//# sourceMappingURL=agent-handler.d.ts.map

package/dist/ws/agent-heartbeat.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Heartbeat monitor for agent WebSocket connections.
+ *
+ * Periodically inspects all registered agents and:
+ * - Logs warnings for agents past the unhealthy threshold (90s).
+ * - Forcibly disconnects agents past the disconnect threshold (180s).
+ *
+ * Follows the same pattern as the Platform HeartbeatMonitor
+ * (packages/platform/src/ws/heartbeat.ts) for consistency across
+ * the three-tier architecture.
+ */
+import type { AgentRegistry } from '../agent/registry.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+interface AgentHeartbeatMonitorDeps {
+    registry: AgentRegistry;
+    dispatcher: Dispatcher;
+    /** Silence duration after which an agent is considered unhealthy (default 90s). */
+    unhealthyThresholdMs?: number;
+    /** Silence duration after which an agent is forcibly disconnected (default 180s). */
+    disconnectThresholdMs?: number;
+    /** How often to run the heartbeat check (default 30s). */
+    checkIntervalMs?: number;
+}
+/**
+ * Periodically inspects all registered agent connections and:
+ * - Marks agents as unhealthy after 90s of silence (log only).
+ * - Closes and unregisters agents after 180s of silence.
+ * - Triggers dispatcher.onAgentDisconnect for stale agents.
+ */
+export declare class AgentHeartbeatMonitor {
+    private readonly registry;
+    private readonly dispatcher;
+    private readonly unhealthyThresholdMs;
+    private readonly disconnectThresholdMs;
+    private readonly checkIntervalMs;
+    private interval;
+    constructor(deps: AgentHeartbeatMonitorDeps);
+    /** Start the periodic heartbeat check. */
+    start(): void;
+    /** Stop the periodic heartbeat check. */
+    stop(): void;
+    private check;
+}
+export {};
+//# sourceMappingURL=agent-heartbeat.d.ts.map

package/dist/ws/dashboard-backends-handler.d.ts

@@ -0,0 +1,51 @@
+import type { BackendSyncManager, DashboardPlatformToOrchMessage } from '@kici-dev/engine';
+import type { BackendRegistry } from '../secrets/backend-registry.js';
+import type { BackendHealthChecker } from '../secrets/backend-health.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+interface DashboardBackendsHandlerDeps {
+    /** Send a response message back to Platform over the WS connection. */
+    send: (msg: unknown) => void;
+    registry: BackendRegistry;
+    healthChecker: BackendHealthChecker;
+    syncManager?: BackendSyncManager;
+    /** Access log writer — records one row per read / mutation with actor attribution. */
+    accessLog?: AccessLogWriter;
+    /** Org ID for access_log rows (null when the orchestrator isn't org-scoped). */
+    orgId?: string | null;
+    /** Routing key for access_log rows (null when not run-scoped). */
+    routingKey?: string | null;
+}
+/**
+ * Handler for all dashboard backend WS messages.
+ *
+ * Dispatches incoming messages by type and calls the appropriate backend services.
+ */
+export declare class DashboardBackendsHandler {
+    private readonly deps;
+    private orgId;
+    private routingKey;
+    private readonly accessLog;
+    constructor(deps: DashboardBackendsHandlerDeps);
+    /**
+     * Update the bound orgId + routingKey. Called from server.ts after resolving
+     * the single tenant org from the `sources` / `generic_webhook_sources` table.
+     */
+    setOrgContext(orgId: string | null, routingKey: string | null): void;
+    /**
+     * Write an access_log row for a handler invocation. Best-effort; the writer
+     * swallows failures.
+     */
+    private recordAccess;
+    /**
+     * Route a dashboard backends message to the appropriate handler.
+     * Returns true if the message was handled, false otherwise.
+     */
+    handleMessage(msg: DashboardPlatformToOrchMessage): Promise<boolean>;
+    private handleList;
+    private handleGet;
+    private handleSyncAll;
+    private handleSyncOne;
+    private handleTest;
+}
+export {};
+//# sourceMappingURL=dashboard-backends-handler.d.ts.map

package/dist/ws/dashboard-diagnostics-handler.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Handles dashboard.diagnostics requests from Platform.
+ *
+ * Reads the AgentRegistry for connected agent info, extracts orchestrator
+ * metadata from config, and computes label gap information from the job queue.
+ *
+ * Returns a response matching dashboardDiagnosticsResponseSchema.
+ */
+import type { AgentRegistry } from '../agent/registry.js';
+import type { AppConfig } from '../config.js';
+import type { ScalerManager } from '../scaler/manager.js';
+import type { ScalerConfig, ScalerEntry } from '../scaler/types.js';
+import type { DashboardDiagnosticsResponse, DashboardScalerCapacityResponse, DashboardScalerAgentsResponse } from '@kici-dev/engine';
+import type { PeerRegistry } from '../cluster/peer-registry.js';
+import type { RaftNode } from '../cluster/raft.js';
+export interface DiagnosticsHandlerDeps {
+    agentRegistry: AgentRegistry;
+    config: AppConfig;
+    /** Orchestrator version string (e.g. "0.0.1"). */
+    version: string;
+    /** Unique scaler backend types (e.g. ["container", "firecracker"]). */
+    scalerBackends: string[];
+    /** Optional job queue for queued job count. */
+    jobQueue?: {
+        getDepth(): Promise<number>;
+    };
+    /** Optional scaler manager for agent-to-scaler mapping. */
+    scalerManager?: ScalerManager | null;
+    /** Optional scaler config for scaler details. */
+    scalerConfig?: ScalerConfig | null;
+    /** Optional peer registry for cluster coordinator mode. */
+    peerRegistry?: PeerRegistry | null;
+    /** Optional Raft node for cluster election state. */
+    raftNode?: RaftNode | null;
+}
+/**
+ * Build a safe config subset for a scaler entry (no secrets like socketPath, uid, gid, etc).
+ * Uses an explicit allowlist to prevent accidental secret leaks.
+ */
+export declare function buildSafeScalerConfig(entry: ScalerEntry): Record<string, unknown>;
+/**
+ * Build a diagnostics response for the given request.
+ * When includeAgents is false (default), agents[] is empty and aggregate fields are populated.
+ */
+export declare function handleDiagnosticsRequest(deps: DiagnosticsHandlerDeps, requestId: string, includeAgents?: boolean): Promise<DashboardDiagnosticsResponse>;
+/**
+ * Build a per-scaler capacity response for the given request.
+ * Reads ScalerManager status to get active/max counts per backend.
+ */
+export declare function handleScalerCapacityRequest(scalerManager: ScalerManager | null, requestId: string): DashboardScalerCapacityResponse;
+/**
+ * Build a per-scaler agents response for the given request.
+ * When scalerName is null, returns agents not bound to any scaler (stateful agents).
+ */
+export declare function handleScalerAgentsRequest(deps: DiagnosticsHandlerDeps, requestId: string, scalerName: string | null): DashboardScalerAgentsResponse;
+//# sourceMappingURL=dashboard-diagnostics-handler.d.ts.map

package/dist/ws/dashboard-env-handler.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Dashboard environment handler for the orchestrator.
+ *
+ * Responds to dashboard.environments.* and dashboard.held-runs.* WS messages
+ * from Platform by calling the appropriate stores (EnvironmentStore, VariableStore,
+ * BindingStore, PgSecretStore) and sending typed responses.
+ *
+ * Each handler:
+ * 1. Extracts orgId from the dependency context
+ * 2. Calls the appropriate store method
+ * 3. Returns a response message with requestId and data (or error)
+ */
+import { type Kysely } from 'kysely';
+import type { DashboardPlatformToOrchMessage } from '@kici-dev/engine';
+import type { EnvironmentStore } from '../environments/environment-store.js';
+import type { VariableStore } from '../environments/variable-store.js';
+import type { BindingStore } from '../environments/binding-store.js';
+import type { Database } from '../db/types.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+/** Secret store interface (subset of PgSecretStore methods used here). */
+interface SecretStoreForDashboard {
+    listScopes(orgId: string): Promise<string[]>;
+    listKeys(orgId: string, scope: string): Promise<string[]>;
+    setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
+    deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
+    createScope?(orgId: string, scope: string): Promise<void>;
+    renameScope?(orgId: string, oldScope: string, newScope: string): Promise<void>;
+    deleteScope?(orgId: string, scope: string): Promise<void>;
+}
+export interface DashboardEnvHandlerDeps {
+    /** Organization ID for all operations. */
+    orgId: string;
+    /** Send a response message back to Platform over the WS connection. */
+    send: (msg: unknown) => void;
+    environmentStore: EnvironmentStore;
+    variableStore: VariableStore;
+    bindingStore: BindingStore;
+    secretStore: SecretStoreForDashboard;
+    /** Load fresh backend stores from registry (creates new store instances with current credentials). */
+    loadBackendStores?: () => Promise<Map<string, SecretStoreForDashboard>>;
+    /** Database for held_runs queries. */
+    db: Kysely<Database>;
+    /** Access log writer — records one row per read / mutation with actor attribution. */
+    accessLog?: AccessLogWriter;
+    /** Routing key for access_log rows (null when not run-scoped). */
+    routingKey?: string | null;
+}
+/**
+ * Handler for all dashboard environment and held run WS messages.
+ *
+ * Dispatches incoming messages by type and calls the appropriate store.
+ */
+export declare class DashboardEnvHandler {
+    private readonly deps;
+    private routingKey;
+    private readonly accessLog;
+    constructor(deps: DashboardEnvHandlerDeps);
+    /** Update the orgId used for all operations (called when resolved from DB). */
+    setOrgId(orgId: string): void;
+    /** Update the routing key bound to access_log rows. */
+    setRoutingKey(routingKey: string | null): void;
+    /**
+     * Write an access_log row for a handler invocation. Uses the handler's
+     * bound orgId + routingKey, the msg.actor principal, and the handler-
+     * specified action + target. Best-effort; the writer swallows failures.
+     */
+    private recordAccess;
+    /**
+     * Route a dashboard message to the appropriate handler.
+     * Returns true if the message was handled, false otherwise.
+     */
+    handleMessage(msg: DashboardPlatformToOrchMessage): Promise<boolean>;
+    private handleEnvList;
+    private handleEnvGet;
+    private handleEnvCreate;
+    private handleEnvUpdate;
+    private handleEnvDelete;
+    private handleVarsList;
+    private handleVarSet;
+    private handleVarDelete;
+    private handleSourceOverridesList;
+    private handleSourceOverrideSet;
+    private handleSourceOverrideDelete;
+    private handleBindingsList;
+    private handleBindingsSet;
+    /** Load fresh backend stores, falling back to single secretStore wrapped in a Map. */
+    private getBackendStores;
+    /**
+     * Resolve the correct backend store for a prefixed scope (e.g., 'vault:aws/prod').
+     * Returns the store and the scope to pass to it.
+     * All stores expect unprefixed scopes — the backend prefix is stripped.
+     */
+    private resolveStoreForScope;
+    private handleSecretsList;
+    private handleSecretSet;
+    private handleSecretDelete;
+    private handleScopeCreate;
+    private handleScopeRename;
+    private handleScopeDelete;
+    private handleEnvHistory;
+    private handleHeldRunsList;
+    private handleHeldRunApprove;
+    private handleHeldRunReject;
+    private sendError;
+}
+export {};
+//# sourceMappingURL=dashboard-env-handler.d.ts.map

package/dist/ws/dashboard-global-workflows-handler.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Dashboard global-workflows handler for the orchestrator.
+ *
+ * Responds to `dashboard.global-workflows.*` WS messages from Platform by
+ * reading or upserting the `org_settings` row keyed by `customer_id`. The
+ * row holds the org-level global-workflow policy: master enable, plus the
+ * three repo-pattern lists (allow / deny / elevate). Each list entry is a
+ * `{routingKey?, pattern}` object that may optionally pin to one source.
+ *
+ * The handler binds a single `customerId` at construction time (via the
+ * sources / generic_webhook_sources lookup at server startup) and updates
+ * via setOrgId() when a real customer source registers.
+ */
+import { type Kysely } from 'kysely';
+import type { GlobalWorkflowsGetRequest, GlobalWorkflowsUpdateRequest, GlobalWorkflowSettings, RepoPatternEntry } from '@kici-dev/engine/protocol/dashboard-global-workflows';
+import type { Database, OrgSettings } from '../db/types.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+interface DashboardGlobalWorkflowsHandlerDeps {
+    /** Customer / org identifier — primary key on org_settings. */
+    customerId: string;
+    /** Send a response message back to Platform over the WS connection. */
+    send: (msg: unknown) => void;
+    db: Kysely<Database>;
+    /** Access log writer — records one row per read / mutation with actor attribution. */
+    accessLog?: AccessLogWriter;
+}
+type GlobalWorkflowsMessage = GlobalWorkflowsGetRequest | GlobalWorkflowsUpdateRequest;
+/**
+ * Returns true when the message is one this handler can dispatch. Used by the
+ * server to route incoming WS messages.
+ */
+export declare function isDashboardGlobalWorkflowsMessage(msg: {
+    type: string;
+} | null | undefined): msg is GlobalWorkflowsMessage;
+export declare class DashboardGlobalWorkflowsHandler {
+    private readonly deps;
+    private readonly accessLog;
+    constructor(deps: DashboardGlobalWorkflowsHandlerDeps);
+    /** Update the customer / org id this handler operates on. */
+    setOrgId(customerId: string | null): void;
+    /**
+     * Write an access_log row for a handler invocation. Best-effort; the writer
+     * swallows failures.
+     */
+    private recordAccess;
+    handleMessage(msg: GlobalWorkflowsMessage): Promise<boolean>;
+    private handleGet;
+    private handleUpdate;
+    private readRow;
+    private upsertRow;
+    private sendError;
+}
+interface NormalizedPatch {
+    enabled: boolean;
+    allowedRepos: RepoPatternEntry[] | null;
+    deniedRepos: RepoPatternEntry[] | null;
+    elevatedRepos: RepoPatternEntry[] | null;
+}
+/**
+ * Derive the effective storage state from an existing row (may be undefined)
+ * plus a partial update message. Unset fields fall back to the existing value;
+ * an explicit `null` clears the corresponding column.
+ */
+export declare function buildPatch(existing: OrgSettings | undefined, msg: GlobalWorkflowsUpdateRequest): NormalizedPatch;
+/**
+ * Project a row into the public settings shape. Returns a defaulted "disabled"
+ * settings object when the row does not yet exist, so callers always get a
+ * renderable state.
+ */
+export declare function rowToSettings(customerId: string, row: OrgSettings | undefined): GlobalWorkflowSettings;
+export {};
+//# sourceMappingURL=dashboard-global-workflows-handler.d.ts.map

package/dist/ws/dashboard-registrations-handler.d.ts

@@ -0,0 +1,84 @@
+import type { Kysely } from 'kysely';
+import { type ActorPrincipal } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+import type { RegistrationStore } from '../registration/registration-store.js';
+import type { RegistrationIndex } from '../registration/registration-index.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+interface DashboardRegistrationsHandlerDeps {
+    /** Organization ID for all operations. */
+    orgId: string;
+    /** Send a response message back to Platform over the WS connection. */
+    send: (msg: unknown) => void;
+    /** Registration store for DB queries. */
+    registrationStore: RegistrationStore;
+    /** Registration index for version info. */
+    registrationIndex: RegistrationIndex;
+    /** Database for execution_runs and cron_last_fired queries. */
+    db: Kysely<Database>;
+    /** Access log writer — records one row per read / mutation with actor attribution. */
+    accessLog?: AccessLogWriter;
+    /** Routing key for access_log rows (null when not run-scoped). */
+    routingKey?: string | null;
+}
+interface RegistrationsListMessage {
+    type: 'dashboard.registrations.list';
+    requestId: string;
+    actor: ActorPrincipal;
+    triggerType?: string;
+    repoIdentifier?: string;
+}
+interface RegistrationDisableMessage {
+    type: 'dashboard.registration.disable';
+    requestId: string;
+    actor: ActorPrincipal;
+    registrationId: string;
+    disabled: boolean;
+}
+interface RegistrationDeleteMessage {
+    type: 'dashboard.registration.delete';
+    requestId: string;
+    actor: ActorPrincipal;
+    registrationId: string;
+    cancelActiveRuns?: boolean;
+}
+type RegistrationMessage = RegistrationsListMessage | RegistrationDisableMessage | RegistrationDeleteMessage;
+/**
+ * Handler for dashboard registration WS messages (list, disable, delete).
+ *
+ * Queries registration store, enriches with last-triggered and next-fire data,
+ * and sends typed response via deps.send().
+ */
+export declare class DashboardRegistrationsHandler {
+    private readonly deps;
+    private routingKey;
+    private readonly accessLog;
+    constructor(deps: DashboardRegistrationsHandlerDeps);
+    /** Update the orgId used for all operations (called when resolved from DB). */
+    setOrgId(orgId: string): void;
+    /** Update the routing key bound to access_log rows. */
+    setRoutingKey(routingKey: string | null): void;
+    /**
+     * Write an access_log row for a handler invocation. Uses the handler's
+     * bound orgId + routingKey, the msg.actor principal, and the handler-
+     * specified action + target. Best-effort; the writer swallows failures.
+     */
+    private recordAccess;
+    handle(msg: RegistrationMessage): Promise<void>;
+    private handleDisable;
+    private handleDelete;
+    /**
+     * Batch-fetch source metadata for the routing keys in the registrations,
+     * keyed on `routing_key`. The map combines rows from `sources` (native,
+     * currently always GitHub Apps) and `generic_webhook_sources` (generic /
+     * universal-git / internal). When a routing key is present in both, the
+     * native row wins.
+     *
+     * Each query is wrapped in its own try/catch so a transient failure on
+     * one table still allows enrichment from the other; rows missing in both
+     * fall through to the synthetic fallback in `buildRegistrationSource`.
+     */
+    private loadSourceMetadata;
+    private handleList;
+}
+export {};
+//# sourceMappingURL=dashboard-registrations-handler.d.ts.map

package/dist/ws/event-buffer.d.ts

@@ -0,0 +1,16 @@
+import type { OrchestratorToPlatformMessage } from '@kici-dev/engine';
+import { RingBuffer } from '@kici-dev/shared';
+/**
+ * In-memory buffer for orchestrator-to-Platform messages during disconnection.
+ *
+ * Wraps the generic RingBuffer from @kici-dev/shared with the orchestrator's
+ * message type. Default maxSize is 10,000 (inherited from RingBuffer). When
+ * the orchestrator loses its WebSocket connection to Platform, outgoing messages
+ * are buffered here and flushed in order on reconnection.
+ */
+export declare class EventBuffer extends RingBuffer<OrchestratorToPlatformMessage> {
+    constructor(options?: {
+        maxSize?: number;
+    });
+}
+//# sourceMappingURL=event-buffer.d.ts.map

package/dist/ws/observer-handler.d.ts

@@ -0,0 +1,42 @@
+/**
+ * WebSocket handler for observer connections.
+ *
+ * CLI clients connect to observe a running execution in real-time.
+ * The observer channel is read-only: clients subscribe with a run ID
+ * and token, then receive log chunks, step status changes, and
+ * completion events broadcast by the ObserverRegistry.
+ *
+ * Auth flow:
+ * 1. Connection opens, 5-second auth timeout starts
+ * 2. First message must be `observe.subscribe` with valid token and runId
+ * 3. Token validated against admin_tokens (same as admin API auth)
+ * 4. Run ID validated against execution_runs table
+ * 5. If valid: registered in ObserverRegistry, initial status sent
+ * 6. Subsequent messages ignored (read-only channel)
+ * 7. On close: unregistered from ObserverRegistry
+ */
+import type { WSEvents } from 'hono/ws';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { ObserverRegistry } from './observer-registry.js';
+import type { TokenManager } from '../secrets/token-manager.js';
+export declare const WS_CLOSE_OBSERVER_AUTH_FAILED = 4001;
+export declare const WS_CLOSE_OBSERVER_AUTH_TIMEOUT = 4002;
+export declare const WS_CLOSE_OBSERVER_INVALID_MESSAGE = 4003;
+export declare const WS_CLOSE_OBSERVER_RUN_NOT_FOUND = 4030;
+export interface ObserverHandlerDeps {
+    observerRegistry: ObserverRegistry;
+    db: Kysely<Database>;
+    tokenManager: TokenManager;
+}
+/**
+ * Create a Hono WS event handler for observer connections.
+ *
+ * Flow:
+ * 1. onOpen: start 5-second auth timeout
+ * 2. First onMessage: must be observe.subscribe with valid token + runId
+ * 3. Subsequent messages: ignored (read-only channel)
+ * 4. onClose: cleanup from registry
+ */
+export declare function createObserverWsHandler(deps: ObserverHandlerDeps): WSEvents;
+//# sourceMappingURL=observer-handler.d.ts.map