@kici-dev/orchestrator 0.0.0 → 0.1.1

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

@@ -0,0 +1,88 @@
+/**
+ * Registry tracking active WebSocket observers per execution run.
+ *
+ * Multiple CLI clients can subscribe to observe the same run.
+ * The registry handles:
+ * - Per-run observer sets with subscribe/unsubscribe
+ * - Broadcast of messages (log, step, status, complete) to all observers
+ * - Message buffering with monotonic sequence numbers for reconnection backfill
+ * - Automatic cleanup of closed/errored connections during broadcast
+ * - TTL-based buffer cleanup after run completion
+ */
+import type { WsLike } from '@kici-dev/engine';
+export type ObserverWsLike = WsLike;
+export declare class ObserverRegistry {
+    /** Per-run observer sets. */
+    private readonly observers;
+    /** Per-run message buffers for reconnection backfill. */
+    private readonly buffers;
+    /** Monotonic sequence counter per run. */
+    private readonly sequenceCounters;
+    /** Scheduled buffer cleanup timers (for cancellation on new subscribe). */
+    private readonly cleanupTimers;
+    /**
+     * Subscribe an observer to a run.
+     *
+     * If `lastSeenSequence` is provided, buffered messages with sequence > lastSeenSequence
+     * are replayed to the observer immediately.
+     */
+    subscribe(runId: string, ws: ObserverWsLike, lastSeenSequence?: number): void;
+    /**
+     * Unsubscribe an observer from a run.
+     *
+     * If the observer set becomes empty, the buffer is kept alive
+     * for potential reconnection (TTL-based cleanup happens later).
+     */
+    unsubscribe(runId: string, ws: ObserverWsLike): void;
+    /**
+     * Broadcast a message object to all observers of a run.
+     *
+     * The message is serialized once, sent to all observers, and added to the
+     * run's buffer with a monotonic sequence number. Closed/errored connections
+     * are removed during broadcast.
+     */
+    broadcast(runId: string, message: object): void;
+    /**
+     * Convenience: broadcast a log chunk message.
+     */
+    broadcastLog(runId: string, jobId: string, jobName: string, stepIndex: number, stepName: string, lines: string[]): void;
+    /**
+     * Convenience: broadcast a step lifecycle event.
+     */
+    broadcastStep(runId: string, jobId: string, jobName: string, stepName: string, state: string, durationMs?: number): void;
+    /**
+     * Convenience: broadcast a run status change.
+     */
+    broadcastStatus(runId: string, status: string, jobName?: string): void;
+    /**
+     * Convenience: broadcast run completion with summary.
+     *
+     * After broadcasting, schedules buffer cleanup after COMPLETION_BUFFER_TTL_MS
+     * to allow brief reconnection windows.
+     */
+    broadcastComplete(runId: string, status: string, summary: object): void;
+    /**
+     * Get the number of active observers for a run.
+     */
+    getObserverCount(runId: string): number;
+    /**
+     * Check if a run has any active observers.
+     */
+    hasObservers(runId: string): boolean;
+    /**
+     * Remove all buffers for completed runs.
+     * Call periodically or on shutdown to reclaim memory.
+     */
+    cleanup(): void;
+    /**
+     * Get the current sequence number for a run (for testing).
+     */
+    getCurrentSequence(runId: string): number;
+    /**
+     * Get the buffer size for a run (for testing).
+     */
+    getBufferSize(runId: string): number;
+    private nextSequence;
+    private addToBuffer;
+}
+//# sourceMappingURL=observer-registry.d.ts.map

package/dist/ws/platform-client.d.ts

@@ -0,0 +1,270 @@
+import { type OrchestratorToPlatformMessage, type WebhookRelay, type WebhookRelayResult, type TrustPolicyUpdate, type StaleCheckrunCleanup, type DashboardRunDetailRequest, type DashboardStepLogsRequest, type DashboardOrchLogsRequest, type RunRerunRequest, type ManualScheduleRequest, type RunCancelRequest, type DashboardPayloadRequest, type DashboardPlatformToOrchMessage, type DashboardDiagnosticsRequest, type DashboardScalerCapacityRequest, type DashboardScalerAgentsRequest, type JoinRequest, type JoinResponse, type OrchCapabilities, type OrchRole } from '@kici-dev/engine';
+import { RelayBufferRegistry, type RelayStartMeta } from '../webhook/relay-buffer.js';
+/**
+ * Verification + processing outcome returned by the chunked relay path's
+ * `onVerifyInbound` callback. Mirrors the shape exported by
+ * `webhook/verify-inbound.ts` so wiring is a single hand-off without an
+ * adapter layer.
+ */
+export interface InboundVerifyOutcome {
+    result: WebhookRelayResult;
+    reason?: string;
+}
+export type ConnectionState = 'disconnected' | 'connecting' | 'authenticating' | 'authenticated';
+/**
+ * A webhook source that this orchestrator manages.
+ * Sent to Platform after auth.success so the Platform knows which
+ * routing keys this orchestrator handles.
+ *
+ * Note: webhookSecret is no longer included. Secrets are pushed separately
+ * via source.secrets after loading from PgSecretStore.
+ *
+ * Single source of truth lives in `../entry-helpers.ts`. Re-exported here
+ * so existing imports of `ProviderSource` from `./platform-client.js` keep
+ * working without churn.
+ */
+export type { ProviderSource } from '../entry-helpers.js';
+import type { ProviderSource } from '../entry-helpers.js';
+export interface PlatformClientOptions {
+    /** WebSocket URL of the Platform relay. */
+    url: string;
+    /** API key for authentication. */
+    token: string;
+    /** Callback invoked when a webhook relay is received from Platform. */
+    onWebhookRelay: (relay: WebhookRelay) => Promise<void>;
+    /** Provider sources to register after authentication. */
+    providerSources?: ProviderSource[];
+    /** Orchestrator cluster instance ID (sent in source.register for peer correlation). */
+    instanceId?: string;
+    /** Reachable address for peer-to-peer connections (from KICI_CLUSTER_ADDRESS env var). Null if not configured. */
+    address?: string | null;
+    /** Orchestrator version string (e.g. "0.0.1"). Sent in source.register for diagnostics. */
+    version?: string;
+    /** Orchestrator config mode. Sent in source.register for diagnostics. */
+    mode?: string;
+    /** Scaler backends configured (e.g. ["container", "firecracker"]). Sent in source.register for diagnostics. */
+    scalerBackends?: string[];
+    /** Whether this orchestrator has S3 log storage configured. Sent in source.register for pool validation. */
+    s3LogAccess?: boolean;
+    /** Queue timeout in ms. Sent in source.register for Platform safety-net GC. */
+    queueTimeoutMs?: number;
+    /** Heartbeat interval in ms. Default: 30000 (30s). */
+    heartbeatIntervalMs?: number;
+    /** Maximum reconnect delay in ms. Default: 60000 (60s). */
+    maxReconnectDelayMs?: number;
+    /** Maximum event buffer size. Default: 10000. */
+    maxBufferSize?: number;
+    /** Optional callback for log pull requests from Platform. */
+    onLogPullRequest?: (msg: {
+        messageId: string;
+        executionId: string;
+        jobName?: string;
+        stepIndex?: number;
+        cursor?: number;
+        limit?: number;
+    }) => void;
+    /** Optional callback for peer discovery (from Platform matchmaker). */
+    onPeerDiscover?: (peer: {
+        connectionId: string;
+        instanceId?: string;
+        address: string | null;
+        routingKeys: string[];
+        orchRole?: OrchRole;
+    }) => void;
+    /** Optional callback invoked after successful authentication and source registration. */
+    onAuthenticated?: () => void;
+    /** Optional callback for dashboard run detail requests from Platform. */
+    onDashboardRunDetail?: (msg: DashboardRunDetailRequest) => void;
+    /** Optional callback for dashboard step logs requests from Platform. */
+    onDashboardStepLogs?: (msg: DashboardStepLogsRequest) => void;
+    /** Optional callback for run re-run requests from Platform (dashboard action). */
+    onRunRerun?: (msg: RunRerunRequest) => void;
+    /** Optional callback for manual schedule trigger requests from Platform (dashboard action). */
+    onManualSchedule?: (msg: ManualScheduleRequest) => void;
+    /** Optional callback for run cancel requests from Platform (dashboard action). */
+    onRunCancel?: (msg: RunCancelRequest) => void;
+    /** Optional callback for dashboard payload requests from Platform. */
+    onDashboardPayload?: (msg: DashboardPayloadRequest) => void;
+    /** Optional callback for dashboard orchestration logs requests from Platform. */
+    onDashboardOrchLogs?: (msg: DashboardOrchLogsRequest) => void;
+    /** Optional callback for dashboard environment/held-run messages from Platform. */
+    onDashboardEnvMessage?: (msg: DashboardPlatformToOrchMessage) => void;
+    /** Optional callback for dashboard diagnostics requests from Platform. */
+    onDashboardDiagnostics?: (msg: DashboardDiagnosticsRequest) => void;
+    /** Optional callback for dashboard scaler capacity requests from Platform. */
+    onDashboardScalerCapacity?: (msg: DashboardScalerCapacityRequest) => void;
+    /** Optional callback for dashboard scaler agents requests from Platform. */
+    onDashboardScalerAgents?: (msg: DashboardScalerAgentsRequest) => void;
+    /** Optional callback for trust policy updates pushed from Platform. */
+    onTrustPolicyUpdate?: (msg: TrustPolicyUpdate) => void;
+    /** Optional callback for stale check run cleanup requests from Platform. */
+    onStaleCheckrunCleanup?: (msg: StaleCheckrunCleanup) => void;
+    /** Optional callback for join requests relayed via Platform. */
+    onJoinRequest?: (msg: JoinRequest) => Promise<JoinResponse>;
+    /** Custom orchestrator capabilities to merge with ORCH_CAPABILITIES in auth.request. */
+    orchCapabilities?: Partial<OrchCapabilities>;
+    /**
+     * Verify a reassembled inbound webhook from the chunked relay path.
+     *
+     * Wired to `verifyInboundWebhook(deps, ...)` in production. Required when
+     * Platform sends `webhook.relay.start`/`webhook.relay.chunk` (chunked path);
+     * if absent, the orchestrator ACKs `rejected_misconfigured` because it
+     * cannot perform the trust check the new design requires.
+     */
+    onVerifyInbound?: (meta: RelayStartMeta, body: Buffer) => Promise<InboundVerifyOutcome> | InboundVerifyOutcome;
+    /**
+     * Optional injected reassembly registry. Tests pass a registry with a short
+     * TTL; production constructs a default one per PlatformClient.
+     */
+    relayBuffer?: RelayBufferRegistry;
+}
+/**
+ * WebSocket client that connects the orchestrator to the Platform relay.
+ *
+ * Handles:
+ * - Authentication handshake (auth.request -> auth.success/failure)
+ * - Periodic heartbeat messages to keep the connection alive
+ * - Auto-reconnect with exponential backoff (1s initial, 1.5x, jitter, 60s max)
+ * - Webhook relay reception and ACK responses
+ * - Event buffering during disconnection with flush on reconnect
+ */
+export declare class PlatformClient {
+    private ws;
+    private _state;
+    private readonly eventBuffer;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private intentionalDisconnect;
+    private readonly url;
+    private readonly token;
+    private readonly onWebhookRelay;
+    private providerSources;
+    private readonly instanceId?;
+    private readonly address?;
+    private readonly version?;
+    private readonly mode?;
+    private readonly scalerBackends?;
+    private readonly s3LogAccess?;
+    private readonly queueTimeoutMs?;
+    private readonly heartbeatIntervalMs;
+    private readonly maxReconnectDelayMs;
+    private readonly onLogPullRequest?;
+    private readonly onPeerDiscover?;
+    private readonly onAuthenticated?;
+    private readonly onDashboardRunDetail?;
+    private readonly onDashboardStepLogs?;
+    private readonly onRunRerun?;
+    private readonly onManualSchedule?;
+    private readonly onRunCancel?;
+    private readonly onDashboardPayload?;
+    private readonly onDashboardOrchLogs?;
+    private readonly onDashboardEnvMessage?;
+    private readonly onDashboardDiagnostics?;
+    private readonly onDashboardScalerCapacity?;
+    private readonly onDashboardScalerAgents?;
+    private readonly onTrustPolicyUpdate?;
+    private readonly onStaleCheckrunCleanup?;
+    private readonly onJoinRequest?;
+    private readonly orchCapabilities;
+    private readonly onVerifyInbound?;
+    private readonly relayBuffer;
+    /**
+     * Public alias of the orchestrator's owning org as supplied by
+     * Platform on `auth.success`. Used by the check-run emitter to build
+     * outbound `details_url`s that hide the canonical `org_<12-char>` id.
+     * `undefined` when the orchestrator runs against a Platform that
+     * predates the alias plumbing, or before the first successful auth.
+     */
+    private _orgPublicAlias?;
+    /**
+     * Returns the cached public alias of the orchestrator's owning org,
+     * or `undefined` if Platform has not supplied one yet. Read by
+     * `commit-status.ts` when building `details_url`.
+     */
+    getOrgPublicAlias(): string | undefined;
+    constructor(options: PlatformClientOptions);
+    /** Current connection state. */
+    get state(): ConnectionState;
+    /** Number of messages currently buffered. */
+    getBufferedCount(): number;
+    /**
+     * Complete a chunked webhook relay: verify, process if accepted, ACK.
+     *
+     * Called from the `webhook.relay.chunk` handler once `relayBuffer.chunk(...)`
+     * returns `{ status: 'completed' }`. This sequence is intentionally single-pass
+     * and inside `requestContext.run` so trace propagation works end-to-end.
+     */
+    private completeChunkedRelay;
+    /**
+     * Initiate connection to the Platform relay.
+     * Starts the connect -> authenticate -> ready lifecycle.
+     */
+    connect(): void;
+    /**
+     * Gracefully disconnect from Platform. Does not trigger reconnection.
+     */
+    disconnect(): void;
+    /**
+     * Send a message to Platform. If authenticated, sends immediately.
+     * If not authenticated, buffers the message for later delivery.
+     */
+    send(message: OrchestratorToPlatformMessage): void;
+    /**
+     * Send a raw message directly on the WebSocket, bypassing typed validation.
+     * Used for log pull response messages (log.response) which are
+     * NOT in the OrchestratorToPlatformMessage union (they are in the separate log pull schema).
+     */
+    sendRaw(data: unknown): void;
+    /**
+     * Register a new source at runtime (e.g., after config reload adds a new GitHub app).
+     * Separate from the post-auth registration which sends all sources at once.
+     */
+    sendSourceRegister(source: ProviderSource): void;
+    /**
+     * Deregister sources at runtime (e.g., after config reload removes a GitHub app).
+     * Tells Platform to stop routing webhooks for these routing keys to this orchestrator.
+     */
+    sendSourceDeregister(source: {
+        routingKey: string;
+    }): void;
+    /**
+     * Diff current provider sources with new ones and send register/deregister as needed.
+     * Convenience method for config reload that atomically updates routing.
+     */
+    updateSources(newSources: ProviderSource[]): void;
+    getReconnectDelay(): number;
+    private doConnect;
+    private handleMessage;
+    /**
+     * Try the two non-mainline schemas (log-pull, cluster join.request) when
+     * the primary `platformToOrchestratorMessageSchema` failed to parse. Falls
+     * back to a structured warning if neither schema matches.
+     */
+    private handleNonStandardMessage;
+    /**
+     * Dispatch a parsed platform message to the appropriate per-area
+     * handler. Each `case` either inlines a tiny dispatch (for one-line
+     * forwards to a callback) or delegates to a private method when the
+     * branch carries non-trivial logic.
+     */
+    private dispatchPlatformMessage;
+    private handleAuthSuccess;
+    private handleAuthFailure;
+    private handleWebhookRelayStart;
+    private handleWebhookRelayChunk;
+    private handleSourceRegisterAck;
+    private handlePeerDiscover;
+    private handlePeerUpdate;
+    /**
+     * Send a message directly on the WebSocket without buffering.
+     * Used for ACK responses that must go immediately.
+     */
+    private sendDirect;
+    private flushBuffer;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private cancelReconnect;
+}
+//# sourceMappingURL=platform-client.d.ts.map

package/dist/ws/server-options.d.ts

@@ -0,0 +1,15 @@
+import type { WebSocketServer } from 'ws';
+/**
+ * Applies the security-relevant options to a `ws` `WebSocketServer` instance.
+ *
+ * Single source of truth for the orchestrator's agent-WS server config. Lives
+ * here so it is unit-testable independently of the heavy `createApp` dependency
+ * graph.
+ *
+ * The (`permessage-deflate` compression bombs) invariant lives here: any
+ * field added to defend against compression-bomb DoS — `maxPayload`,
+ * `serverNoContextTakeover`, etc. — MUST be set inside this helper so the
+ * neighbouring test file can assert it.
+ */
+export declare function configureSecureWsServer(wss: WebSocketServer): void;
+//# sourceMappingURL=server-options.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "description": "Customer-deployable orchestrator for the KiCI CI/CD stack. Receives webhook events (direct or via Platform relay), matches triggers against the lock file, and dispatches jobs to connected agents.",
   "keywords": [
     "kici",
@@ -9,17 +9,98 @@
     "ci-cd",
     "typescript",
     "workflows",
-    "devops"
+    "devops",
+    "orchestrator",
+    "webhook",
+    "self-hosted"
   ],
   "homepage": "https://kici.dev",
   "author": {
     "name": "KiCI",
     "email": "hello@kici.dev"
   },
-  "license": "Apache-2.0",
-  "main": "index.js",
+  "license": "AGPL-3.0-only",
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "sbom.spdx.json"
+  ],
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "kici-admin": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./cli": "./dist/cli.js"
+  },
+  "build": {
+    "entries": {
+      "server.js": "src/server.ts",
+      "standalone.js": "src/standalone.ts",
+      "cli.js": "src/cli/kici-admin.ts",
+      "index.js": "src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-service.mjs && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "db:migrate": "kysely migrate:latest",
+    "prepublishOnly": "npx tsx ../../hack/generate-sbom.ts --package packages/orchestrator --name @kici-dev/orchestrator"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1038.0",
+    "@aws-sdk/lib-storage": "^3.1038.0",
+    "@aws-sdk/s3-request-presigner": "^3.1038.0",
+    "@hono/node-server": "^2.0.0",
+    "@hono/node-ws": "^1.3.0",
+    "@inquirer/prompts": "^8.4.2",
+    "@kici-dev/engine": "workspace:*",
+    "@kici-dev/shared": "workspace:*",
+    "@octokit/auth-app": "^8.2.0",
+    "@octokit/rest": "^22.0.1",
+    "archiver": "^7.0.1",
+    "commander": "^14.0.3",
+    "croner": "^10.0.1",
+    "dockerode": "^5.0.0",
+    "hashi-vault-js": "^0.5.1",
+    "hono": "^4.12.18",
+    "jsonpath-plus": "^10.4.0",
+    "jszip": "^3.10.1",
+    "kysely": "^0.29.0",
+    "lru-cache": "^11.3.5",
+    "nanoid": "^5.1.9",
+    "pg": "^8.20.0",
+    "picomatch": "^4.0.4",
+    "strip-ansi": "^7.2.0",
+    "tar": "^7.5.13",
+    "ws": "^8.20.0",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  },
+  "kici": {
+    "metrics": {
+      "mode": "scrape",
+      "port": 10143,
+      "path": "/metrics",
+      "jobName": "kici-orchestrator"
+    }
+  },
+  "devDependencies": {
+    "@types/archiver": "^7.0.0",
+    "@types/dockerode": "^4.0.1",
+    "kysely-ctl": "^0.21.0"
   }
 }