@kici-dev/orchestrator 0.1.27 → 0.2.0

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

@@ -1,5 +1,6 @@
-import { type OrchestratorToPlatformMessage, type WebhookRelay, type WebhookRelayResult, type TrustPolicyUpdate, type StaleCheckrunCleanup, type DashboardRunDetailRequest, type DashboardRunStructuredRequest, type DashboardRunsListRequest, type DashboardRunsFiltersRequest, type DashboardSourcesListRequest, type DashboardStepLogsRequest, type DashboardAttestationsListRequest, type DashboardAttestationsListAllRequest, type DashboardAttestationGetRequest, type DashboardAttestationRetryRequest, type DashboardOrchLogsRequest, type RunRerunRequest, type ManualScheduleRequest, type RunCancelRequest, type DashboardPayloadRequest, type DashboardPlatformToOrchMessage, type TestRelayRequest, type DashboardDiagnosticsRequest, type DashboardScalerCapacityRequest, type DashboardScalerAgentsRequest, type DashboardFleetHostsRequest, type DashboardFleetHostRequest, type DashboardFleetPreviewRequest, type DashboardFleetWorkflowsForHostRequest, type JoinRequest, type JoinResponse, type DeploymentIdentity, type OrchCapabilities, type OrchRole } from '@kici-dev/engine';
+import { type StateReplayRun, type OrchestratorToPlatformMessage, type WebhookRelay, type WebhookRelayResult, type TrustPolicyUpdate, type StaleCheckrunCleanup, type DashboardRunDetailRequest, type DashboardRunStructuredRequest, type DashboardRunStateRequest, type DashboardRunsListRequest, type DashboardRunsFiltersRequest, type DashboardSourcesListRequest, type DashboardStepLogsRequest, type DashboardAttestationsListRequest, type DashboardAttestationsListAllRequest, type DashboardAttestationGetRequest, type DashboardAttestationRetryRequest, type DashboardArtifactsListRequest, type DashboardOrchLogsRequest, type RunRerunRequest, type ManualScheduleRequest, type RunCancelRequest, type DashboardPayloadRequest, type DashboardPlatformToOrchMessage, type TestRelayRequest, type DashboardDiagnosticsRequest, type DashboardScalerCapacityRequest, type DashboardScalerAgentsRequest, type DashboardFleetHostsRequest, type DashboardFleetHostRequest, type DashboardFleetPreviewRequest, type DashboardFleetWorkflowsForHostRequest, type JoinRequest, type JoinResponse, type DeploymentIdentity, type OrchCapabilities, type OrchRole } from '@kici-dev/engine';
 import { RelayBufferRegistry, type RelayStartMeta } from '../webhook/relay-buffer.js';
+import type { AdmitResult } from '../webhook/ingest-admission.js';
 /**
  * Verification + processing outcome returned by the chunked relay path's
  * `onVerifyInbound` callback. Mirrors the shape exported by
@@ -11,6 +12,16 @@ export interface InboundVerifyOutcome {
     reason?: string;
 }
 export type ConnectionState = 'disconnected' | 'connecting' | 'authenticating' | 'authenticated';
+/**
+ * Outcome of a chunked `state.replay` send. `skipped` names why the replay did
+ * not complete: an empty payload, a frame that failed wire validation locally,
+ * a socket that closed mid-send, or the circuit breaker being open.
+ */
+export type ReplaySendResult = {
+    sent: number;
+    chunks: number;
+    skipped?: 'empty' | 'invalid' | 'disconnected' | 'breaker';
+};
 /**
  * A webhook source that this orchestrator manages.
  * Sent to Platform after auth.success so the Platform knows which
@@ -110,6 +121,8 @@ export interface PlatformClientOptions {
     onDashboardRunDetail?: (msg: DashboardRunDetailRequest) => void;
     /** Optional callback for dashboard structured run-result requests from Platform. */
     onDashboardRunStructured?: (msg: DashboardRunStructuredRequest) => void;
+    /** Optional callback for the run-state system reconciliation read from Platform. */
+    onDashboardRunState?: (msg: DashboardRunStateRequest) => void;
     /** Optional callback for dashboard runs.list (operator console) requests from Platform. */
     onDashboardRunsList?: (msg: DashboardRunsListRequest) => void;
     /** Optional callback for dashboard runs.filters (operator console) requests from Platform. */
@@ -125,6 +138,8 @@ export interface PlatformClientOptions {
     /** Optional callback for single-attestation detail requests from Platform. */
     onDashboardAttestationGet?: (msg: DashboardAttestationGetRequest) => void;
     onDashboardAttestationRetry?: (msg: DashboardAttestationRetryRequest) => void;
+    /** Optional callback for dashboard artifacts-list requests from Platform. */
+    onDashboardArtifactsList?: (msg: DashboardArtifactsListRequest) => 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). */
@@ -165,6 +180,17 @@ export interface PlatformClientOptions {
     onJoinRequest?: (msg: JoinRequest) => Promise<JoinResponse>;
     /** Custom orchestrator capabilities to merge with ORCH_CAPABILITIES in auth.request. */
     orchCapabilities?: Partial<OrchCapabilities>;
+    /**
+     * Test-only. Whether the orchestrator runs in test mode (config
+     * `KICI_TEST_MODE=1`). Gates `testOmitDashboardRequestTypes`.
+     */
+    testMode?: boolean;
+    /**
+     * Test-only. Comma-separated `dashboard.*` request types to drop from the
+     * advertised capability manifest (config `KICI_TEST_OMIT_DASHBOARD_REQUEST_TYPES`).
+     * Only honored when `testMode` is true; production leaves both unset.
+     */
+    testOmitDashboardRequestTypes?: string;
     /**
      * Verify a reassembled inbound webhook from the chunked relay path.
      *
@@ -179,6 +205,21 @@ export interface PlatformClientOptions {
      * TTL; production constructs a default one per PlatformClient.
      */
     relayBuffer?: RelayBufferRegistry;
+    /**
+     * Webhook-ingest admission hook. Called with the relay's routing key BEFORE
+     * signature verification (so an unverified flood is throttled too — a verify
+     * does a DB read). When it sheds, the relay acks `shed_retry_later` (429) and
+     * no pipeline work runs. When it admits, the returned slot is held for the
+     * fire-and-forget pipeline's lifetime and released on completion / error /
+     * timeout. Absent → no admission gate (tests, minimal wirings).
+     */
+    onAdmit?: (routingKey: string) => Promise<AdmitResult>;
+    /**
+     * Optional durable-overflow capture seam. Invoked with the pre-verify relay
+     * meta + assembled body on a shed, before the shed_retry_later ack. Best-effort
+     * — the client wraps it so a capture failure never blocks the ack.
+     */
+    onShedCapture?: (meta: RelayStartMeta, body: Buffer) => Promise<void>;
 }
 /** Error `*.response` frame shape for a dashboard request that failed validation. */
 export interface DashboardRequestErrorFrame {
@@ -216,6 +257,14 @@ export declare class PlatformClient {
     private heartbeatTimer;
     private reconnectTimer;
     private reconnectAttempts;
+    /** Armed on auth; resets the backoff only if the connection survives it. */
+    private stabilityTimer;
+    /** True once the current connection has survived CONNECTION_STABLE_MS. */
+    private connectionProvenStable;
+    /** True once a state replay has been sent on the current connection. */
+    private replaySentOnConnection;
+    private replayConsecutiveFailures;
+    private replayBreakerOpen;
     private intentionalDisconnect;
     private readonly url;
     private readonly token;
@@ -233,6 +282,16 @@ export declare class PlatformClient {
      * awaits the Platform's matching `.response`; rejected on timeout or close.
      */
     private readonly orchRpc;
+    /**
+     * Platform capabilities advertised on this connection (Platform → orchestrator
+     * `platform.capabilities` frame). `undefined` means nothing advertised yet —
+     * either a pre-capability Platform (which never advertises) or the frame has
+     * not arrived. Feature-gated sends treat "undefined" as optimistic (send
+     * anyway, backward-safe); only an advertised-but-absent flag suppresses a send.
+     * Reset to `undefined` on every (re)connect so a stale advertisement can't
+     * leak across connections.
+     */
+    private platformCapabilities;
     private readonly instanceId?;
     private readonly clusterName?;
     private readonly clusterId?;
@@ -252,6 +311,7 @@ export declare class PlatformClient {
     private readonly onProvenanceIssuer?;
     private readonly onDashboardRunDetail?;
     private readonly onDashboardRunStructured?;
+    private readonly onDashboardRunState?;
     private readonly onDashboardRunsList?;
     private readonly onDashboardRunsFilters?;
     private readonly onDashboardSourcesList?;
@@ -260,6 +320,7 @@ export declare class PlatformClient {
     private readonly onDashboardAttestationsListAll?;
     private readonly onDashboardAttestationGet?;
     private readonly onDashboardAttestationRetry?;
+    private readonly onDashboardArtifactsList?;
     private readonly onRunRerun?;
     private readonly onManualSchedule?;
     private readonly onRunCancel?;
@@ -279,6 +340,8 @@ export declare class PlatformClient {
     private readonly onJoinRequest?;
     private orchCapabilities;
     private readonly onVerifyInbound?;
+    private readonly onAdmit?;
+    private readonly onShedCapture?;
     private readonly relayBuffer;
     /**
      * Public alias of the orchestrator's owning org as supplied by
@@ -334,6 +397,37 @@ export declare class PlatformClient {
      * If not authenticated, buffers the message for later delivery.
      */
     send(message: OrchestratorToPlatformMessage): void;
+    /**
+     * Send the reconnect state replay as N paced frames.
+     *
+     * The payload is bounded by BOTH the wire schema's run cap and the Platform
+     * limiter's byte budget, and paced under its refill rate, because a frame
+     * breaching either one is rejected with a 4003 close — and since reconnecting
+     * does not reduce the run count, an oversized frame is resent forever rather
+     * than failing once.
+     *
+     * Uses `this.ws.send` directly rather than `this.send()` on purpose: `send()`
+     * falls back to `this.eventBuffer` when the socket is not open, which for a
+     * multi-frame replay would queue the remaining frames for the NEXT connection
+     * instead of abandoning a replay whose connection has already gone. The
+     * Platform's replay handler upserts per run, so abandoning is safe — the next
+     * reconnect replays from scratch.
+     */
+    sendStateReplay(runs: StateReplayRun[]): Promise<ReplaySendResult>;
+    /**
+     * Send a feature-gated message only if the Platform is known to support the
+     * named capability — the orchestrator-side pre-flight for a self-hosted
+     * orchestrator running ahead of the hosted Platform.
+     *
+     * Backward-safe: a Platform that never advertised capabilities (a
+     * pre-capability build, or the advertisement hasn't arrived yet) is treated as
+     * "unknown → send optimistically", exactly like the Platform's dashboard
+     * pre-flight treats an absent `supportedDashboardRequests` as "unknown", never
+     * "supports nothing". Only an *advertised* capability set that explicitly lacks
+     * the flag suppresses the send — surfacing a diagnosable capability gap instead
+     * of firing a frame the Platform would silently drop.
+     */
+    sendIfPlatformSupports(capability: string, message: OrchestratorToPlatformMessage): void;
     /**
      * Send a raw message directly on the WebSocket, bypassing typed validation.
      * Used for log pull response messages (log.response) which are
@@ -425,6 +519,7 @@ export declare class PlatformClient {
     private startHeartbeat;
     private stopHeartbeat;
     private scheduleReconnect;
+    private clearStabilityTimer;
     private cancelReconnect;
 }
 //# sourceMappingURL=platform-client.d.ts.map

package/dist/ws/replay-chunker.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Chunking for the reconnect `state.replay` payload.
+ *
+ * The wire schema caps `runs` at `STATE_REPLAY_MAX_RUNS` (500) and the
+ * Platform's WS limiter caps a single message at 4 MB with a 2 MB burst
+ * refilling at 500 KB/s, so a replay must be split on BOTH axes: a frame that
+ * breaches either one is dropped by the Platform, which closes the connection
+ * with 4003. Since nothing about reconnecting reduces the run count, an
+ * oversized frame is not a transient failure — the orchestrator rebuilds and
+ * resends it forever.
+ *
+ * Pure and I/O-free so the bounds can be shrunk in tests without building 500
+ * real runs.
+ */
+/**
+ * Runs per frame. Deliberately below the schema's hard cap of 500 so growth in
+ * a run's `jobs` array cannot silently re-break the link.
+ */
+export declare const REPLAY_CHUNK_MAX_RUNS = 200;
+/** Serialized bytes per frame. A quarter of the limiter's 2 MB burst. */
+export declare const REPLAY_CHUNK_MAX_BYTES: number;
+/** Mirrors the Platform limiter's byte refill rate; the pacing divisor. */
+export declare const REPLAY_BYTE_REFILL_BYTES_PER_SEC: number;
+export interface ChunkBounds {
+    maxRuns: number;
+    maxBytes: number;
+}
+/**
+ * Split `runs` into frames obeying both bounds, preserving order.
+ *
+ * A single run larger than `maxBytes` cannot be split — it is emitted alone.
+ * That is why the byte test is guarded on a non-empty current chunk: without
+ * the guard an oversized run would either loop forever or emit an empty chunk,
+ * and an empty `runs` array is not a frame worth sending.
+ */
+export declare function chunkReplayRuns<T>(runs: readonly T[], bounds?: ChunkBounds): T[][];
+//# sourceMappingURL=replay-chunker.d.ts.map

package/installer-image-digests.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.1.27",
+  "version": "0.2.0",
   "images": {
-    "kici-agent": "sha256:301120d679c7f199df1836bedde1ef896c9742f5212cd70753b84e89df195995",
-    "kici-orchestrator": "sha256:03af091cc946da7b037ce048867684d8fcc3528fd1320fa7a408627ad2a55f76"
+    "kici-agent": "sha256:720a94642479888c0b1c5fbcfca6760f800b32977cea9cda0c9bfff1fc70875d",
+    "kici-orchestrator": "sha256:674cc72d66556eefbd4eeac6b45550b1a12bdda5d517542d24483f28348ecd04"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.1.27",
+  "version": "0.2.0",
   "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": [
     "ci",
@@ -57,35 +57,35 @@
     }
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1064.0",
-    "@aws-sdk/lib-storage": "^3.1064.0",
-    "@aws-sdk/s3-request-presigner": "^3.1064.0",
-    "@hono/node-server": "^1.19.14",
-    "@hono/node-ws": "^1.3.1",
+    "@aws-sdk/client-kms": "^3.1089.0",
+    "@aws-sdk/client-s3": "^3.1089.0",
+    "@aws-sdk/lib-storage": "^3.1089.0",
+    "@aws-sdk/s3-request-presigner": "^3.1089.0",
+    "@hono/node-server": "^2.0.10",
     "@inquirer/prompts": "^8.5.2",
     "@octokit/auth-app": "^8.2.0",
     "@octokit/rest": "^22.0.1",
     "archiver": "^8.0.0",
     "commander": "^15.0.0",
     "croner": "^10.0.1",
-    "dockerode": "^5.0.0",
-    "hashi-vault-js": "^0.5.1",
-    "hono": "^4.12.25",
+    "dockerode": "^5.0.1",
+    "hashi-vault-js": "^0.5.2",
+    "hono": "^4.12.32",
     "jose": "^6.1.0",
     "jsonpath-plus": "^10.4.0",
     "jszip": "^3.10.1",
-    "kysely": "^0.29.2",
-    "lru-cache": "^11.5.1",
-    "nanoid": "^5.1.11",
-    "pg": "^8.21.0",
-    "picomatch": "^4.0.4",
+    "kysely": "^0.29.4",
+    "lru-cache": "^11.5.2",
+    "nanoid": "^6.0.0",
+    "pg": "^8.22.0",
+    "picomatch": "^4.0.5",
     "strip-ansi": "^7.2.0",
-    "tar": "^7.5.16",
-    "ws": "^8.21.0",
+    "tar": "^7.5.20",
+    "ws": "^8.21.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@kici-dev/shared": "0.1.27",
-    "@kici-dev/engine": "0.1.27"
+    "@kici-dev/engine": "0.2.0",
+    "@kici-dev/shared": "0.2.0"
   },
   "kici": {
     "metrics": {
@@ -98,12 +98,13 @@
   "devDependencies": {
     "@types/archiver": "^8.0.0",
     "@types/dockerode": "^4.0.1",
+    "@types/ws": "^8.18.1",
     "kysely-ctl": "^0.21.0",
-    "@kici-dev/agent": "0.1.27"
+    "@kici-dev/agent": "0.2.0"
   },
   "scripts": {
-    "build": "node ../../scripts/build-service.mjs && tsc --emitDeclarationOnly",
-    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/build-service.mjs && tsgo --emitDeclarationOnly",
+    "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "db:migrate": "kysely migrate:latest"
   }