@kici-dev/orchestrator 0.11.0 → 0.12.0

package/dist/storage/filesystem.d.ts

@@ -6,7 +6,7 @@
  * are replaced by HMAC-signed `http://<orchUrl>/api/v1/cache/blob/...` URLs
  * — see `sign-url.ts` for the token mechanics and `app.ts` for the route.
  *
- * Intended for single-host deployments and E2E sandboxes where standing up
+ * Intended for single-host deployments and test sandboxes where standing up
  * an S3-compatible service is overkill. Production should still use S3.
  *
  * Metadata is co-located as a sibling JSON file (`<key>.meta.json`) so the

package/dist/storage/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Pluggable storage backends:
  *   - S3CacheStorage         — production / multi-host
- *   - FilesystemCacheStorage — single-host / E2E sandbox
+ *   - FilesystemCacheStorage — single-host / test sandbox
  *
  * Use createCacheStorage() to instantiate from a discriminated config.
  */

package/dist/storage/sign-url.d.ts

@@ -10,7 +10,8 @@
  * Signature input: `${method}:${key}:${expiresUnixMs}` with HMAC-SHA256 keyed
  * by a per-orchestrator-process secret (random 32-byte hex at boot, persists
  * for the lifetime of the process). Tokens become invalid on orchestrator
- * restart — fine for the filesystem backend's E2E / single-host use case.
+ * restart — fine for the filesystem backend's single-host / test-sandbox use
+ * case.
  */
 /** Default URL lifetime: 1 hour (matches S3 backend's PUT-URL lifetime). */
 export declare const DEFAULT_SIGN_URL_TTL_MS: number;

package/dist/storage/types.d.ts

@@ -7,7 +7,7 @@
  *
  * Backends:
  *   - `S3CacheStorage` for production / multi-host deployments
- *   - `FilesystemCacheStorage` for single-host / E2E sandboxes
+ *   - `FilesystemCacheStorage` for single-host / test sandboxes
  */
 /**
  * Metadata tracked alongside each cached item.
@@ -119,7 +119,7 @@ export type S3CacheStorageConfig = SharedS3Config & {
  * mints HMAC-signed `http://baseUrl<routePrefix>...` URLs that the
  * orchestrator's `/api/v1/cache/blob/*` route verifies before serving.
  *
- * Intended for single-host / E2E sandboxes where standing up an
+ * Intended for single-host / test sandboxes where standing up an
  * S3-compatible service is overkill.
  */
 export interface FilesystemCacheStorageConfig {

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

@@ -19,7 +19,7 @@
  * frame is accepted there and answered with auth.success without reading the
  * token, and the agent then registers as normal.
  */
-import type { WSEvents } from 'hono/ws';
+import type { WSContext, WSEvents, WSMessageReceive } from 'hono/ws';
 import { LogStream } from '@kici-dev/engine';
 import type { RateLimiterConfig, AttestationVerifyStatus } from '@kici-dev/engine';
 import type { ProvenanceTrustRoot } from '../provenance/trust-root.js';
@@ -74,6 +74,26 @@ import type { FleetAgentCollector } from './fleet-agent-collector.js';
  * trailing partial multi-byte char.
  */
 export declare function truncateCloseReason(reason: string): string;
+/** What a failed frame is about, for the failure log. */
+export interface FrameIdentity {
+    messageType?: string;
+    agentId?: string;
+    runId?: string;
+    jobId?: string;
+}
+/**
+ * Read the type and ids from a raw agent frame, for logging a failure. Only
+ * string fields are copied, each capped at 128 characters; anything that is
+ * not a JSON object yields nothing. Runs on the failure path only.
+ */
+export declare function frameIdentity(data: unknown): FrameIdentity;
+/**
+ * The agent WebSocket handler. `onMessage` resolves once the frame is handled
+ * and never rejects: the WebSocket server does not await it.
+ */
+export interface AgentWsEvents extends Omit<WSEvents, 'onMessage'> {
+    onMessage(evt: MessageEvent<WSMessageReceive>, ws: WSContext): Promise<void>;
+}
 export interface AgentWsHandlerDeps {
     registry: AgentRegistry;
     dispatcher: Dispatcher;
@@ -383,7 +403,6 @@ export interface AgentWsHandlerDeps {
  * SYNC INVARIANT: This manual validator MUST match the Zod schema
  * `agentLogChunkSchema` in packages/engine/src/protocol/messages/orchestrator-agent.ts.
  * If you change the schema, update this validator in the same commit.
- * See CLAUDE.md rule: "Zod fast-path sync invariant".
  */
 export declare function isValidLogChunk(raw: unknown): raw is {
     type: 'log.chunk';
@@ -405,5 +424,17 @@ export interface AgentLogChunkInput {
     /** Absent when the agent does not report a stream; read as `stdout`. */
     stream?: LogStream;
 }
-export declare function createAgentWsHandler(deps: AgentWsHandlerDeps): WSEvents;
+/**
+ * Create a Hono WS event handler for agent connections.
+ *
+ * Flow:
+ * 1. onOpen: start 10-second register timer
+ * 2. First onMessage: must be agent.register with labels and capacity
+ * 3. Subsequent onMessage: validated against protocol schemas, routed by type
+ * 4. onClose: cleanup from pending registration or dispatcher
+ *
+ * A frame whose handling fails is logged with its type and ids; the
+ * connection stays open.
+ */
+export declare function createAgentWsHandler(deps: AgentWsHandlerDeps): AgentWsEvents;
 //# sourceMappingURL=agent-handler.d.ts.map

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

@@ -5,9 +5,8 @@
  * - 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.
+ * Follows the same pattern as the Platform's heartbeat monitor, for
+ * consistency across the three-tier architecture.
  */
 import type { AgentRegistry } from '../agent/registry.js';
 import type { Dispatcher } from '../agent/dispatcher.js';

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

@@ -67,7 +67,7 @@ export interface DashboardContextHandlerDeps {
 /** Dependencies enabling the resolver-backed approve/reject + resume path. */
 export interface ApprovalHandlerDeps {
     store: HeldRunStore;
-    /** Team name → member user ids (Plan-1 trust-policy cache). */
+    /** Team name → member user ids (trust-policy cache). */
     teamMembershipLookup: TeamMembershipLookup;
     /** Re-dispatch a released job hold (consumes its pending context). */
     resumeJob: (signal: ReleaseSignal) => Promise<void>;

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

@@ -51,6 +51,12 @@ import type { ProviderSource } from '../entry-helpers.js';
  * is exactly the pair that drifts.
  */
 export declare const ADMITTED_PIPELINE_LIFETIME_MS: number;
+/**
+ * A handler for one Platform frame. It may be async: the client runs it
+ * through {@link PlatformClient.runFrameHandler}, which logs a failure and
+ * keeps the connection.
+ */
+export type FrameHandler<M> = (msg: M) => void | Promise<void>;
 export interface PlatformClientOptions {
     /** WebSocket URL of the Platform relay. */
     url: string;
@@ -99,14 +105,14 @@ export interface PlatformClientOptions {
     /** Maximum event buffer size. Default: 10000. */
     maxBufferSize?: number;
     /** Optional callback for log pull requests from Platform. */
-    onLogPullRequest?: (msg: {
+    onLogPullRequest?: FrameHandler<{
         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;
@@ -116,7 +122,7 @@ export interface PlatformClientOptions {
         orchRole?: OrchRole;
     }) => void;
     /** Optional callback invoked after successful authentication and source registration. */
-    onAuthenticated?: () => void;
+    onAuthenticated?: () => void | Promise<void>;
     /**
      * Returns this coordinator's currently-connected worker peers for the
      * `cluster.membership` snapshot. Undefined on a non-coordinator (or when
@@ -156,66 +162,66 @@ export interface PlatformClientOptions {
      */
     onProvenanceIssuer?: (issuer: string | null) => void;
     /** Optional callback for dashboard run detail requests from Platform. */
-    onDashboardRunDetail?: (msg: DashboardRunDetailRequest) => void;
+    onDashboardRunDetail?: FrameHandler<DashboardRunDetailRequest>;
     /** Optional callback for dashboard structured run-result requests from Platform. */
-    onDashboardRunStructured?: (msg: DashboardRunStructuredRequest) => void;
+    onDashboardRunStructured?: FrameHandler<DashboardRunStructuredRequest>;
     /** Optional callback for the run-state system reconciliation read from Platform. */
-    onDashboardRunState?: (msg: DashboardRunStateRequest) => void;
+    onDashboardRunState?: FrameHandler<DashboardRunStateRequest>;
     /** Optional callback for dashboard runs.list (operator console) requests from Platform. */
-    onDashboardRunsList?: (msg: DashboardRunsListRequest) => void;
+    onDashboardRunsList?: FrameHandler<DashboardRunsListRequest>;
     /** Optional callback for dashboard runs.filters (operator console) requests from Platform. */
-    onDashboardRunsFilters?: (msg: DashboardRunsFiltersRequest) => void;
+    onDashboardRunsFilters?: FrameHandler<DashboardRunsFiltersRequest>;
     /** Optional callback for dashboard sources.list (operator console) requests from Platform. */
-    onDashboardSourcesList?: (msg: DashboardSourcesListRequest) => void;
+    onDashboardSourcesList?: FrameHandler<DashboardSourcesListRequest>;
     /** Optional callback for dashboard admin-tokens.list (RBAC drift report) requests from Platform. */
-    onDashboardAdminTokensList?: (msg: DashboardAdminTokensListRequest) => void;
+    onDashboardAdminTokensList?: FrameHandler<DashboardAdminTokensListRequest>;
     /** Optional callback for dashboard step logs requests from Platform. */
-    onDashboardStepLogs?: (msg: DashboardStepLogsRequest) => void;
+    onDashboardStepLogs?: FrameHandler<DashboardStepLogsRequest>;
     /** Optional callback for dashboard attestations-list requests from Platform. */
-    onDashboardAttestationsList?: (msg: DashboardAttestationsListRequest) => void;
+    onDashboardAttestationsList?: FrameHandler<DashboardAttestationsListRequest>;
     /** Optional callback for org-wide attestations list (browser) requests from Platform. */
-    onDashboardAttestationsListAll?: (msg: DashboardAttestationsListAllRequest) => void;
+    onDashboardAttestationsListAll?: FrameHandler<DashboardAttestationsListAllRequest>;
     /** Optional callback for single-attestation detail requests from Platform. */
-    onDashboardAttestationGet?: (msg: DashboardAttestationGetRequest) => void;
-    onDashboardAttestationRetry?: (msg: DashboardAttestationRetryRequest) => void;
+    onDashboardAttestationGet?: FrameHandler<DashboardAttestationGetRequest>;
+    onDashboardAttestationRetry?: FrameHandler<DashboardAttestationRetryRequest>;
     /** Optional callback for dashboard artifacts-list requests from Platform. */
-    onDashboardArtifactsList?: (msg: DashboardArtifactsListRequest) => void;
+    onDashboardArtifactsList?: FrameHandler<DashboardArtifactsListRequest>;
     /** Optional callback for run re-run requests from Platform (dashboard action). */
-    onRunRerun?: (msg: RunRerunRequest) => void;
+    onRunRerun?: FrameHandler<RunRerunRequest>;
     /** Optional callback for manual schedule trigger requests from Platform (dashboard action). */
-    onManualSchedule?: (msg: ManualScheduleRequest) => void;
+    onManualSchedule?: FrameHandler<ManualScheduleRequest>;
     /** Optional callback for run cancel requests from Platform (dashboard action). */
-    onRunCancel?: (msg: RunCancelRequest) => void;
+    onRunCancel?: FrameHandler<RunCancelRequest>;
     /** Optional callback for dashboard payload requests from Platform. */
-    onDashboardPayload?: (msg: DashboardPayloadRequest) => void;
+    onDashboardPayload?: FrameHandler<DashboardPayloadRequest>;
     /** Optional callback for dashboard orchestration logs requests from Platform. */
-    onDashboardOrchLogs?: (msg: DashboardOrchLogsRequest) => void;
+    onDashboardOrchLogs?: FrameHandler<DashboardOrchLogsRequest>;
     /** Optional callback for dashboard environment/held-run messages from Platform. */
-    onDashboardEnvMessage?: (msg: DashboardPlatformToOrchMessage) => void;
+    onDashboardEnvMessage?: FrameHandler<DashboardPlatformToOrchMessage>;
     /**
      * Optional callback for Platform-first `kici run remote` control-plane relay
      * requests (upload-init, trigger, status, logs, cancel). The handler performs
      * the action and replies over the WS keyed by `requestId`.
      */
-    onTestRelay?: (msg: TestRelayRequest) => void;
+    onTestRelay?: FrameHandler<TestRelayRequest>;
     /** Optional callback for dashboard diagnostics requests from Platform. */
-    onDashboardDiagnostics?: (msg: DashboardDiagnosticsRequest) => void;
+    onDashboardDiagnostics?: FrameHandler<DashboardDiagnosticsRequest>;
     /** Optional callback for dashboard scaler capacity requests from Platform. */
-    onDashboardScalerCapacity?: (msg: DashboardScalerCapacityRequest) => void;
+    onDashboardScalerCapacity?: FrameHandler<DashboardScalerCapacityRequest>;
     /** Optional callback for dashboard scaler agents requests from Platform. */
-    onDashboardScalerAgents?: (msg: DashboardScalerAgentsRequest) => void;
+    onDashboardScalerAgents?: FrameHandler<DashboardScalerAgentsRequest>;
     /** Optional callback for fleet roster requests from Platform. */
-    onFleetHosts?: (msg: DashboardFleetHostsRequest) => void;
+    onFleetHosts?: FrameHandler<DashboardFleetHostsRequest>;
     /** Optional callback for fleet host-detail requests from Platform. */
-    onFleetHost?: (msg: DashboardFleetHostRequest) => void;
+    onFleetHost?: FrameHandler<DashboardFleetHostRequest>;
     /** Optional callback for fleet runsOnAll-preview requests from Platform. */
-    onFleetPreview?: (msg: DashboardFleetPreviewRequest) => void;
+    onFleetPreview?: FrameHandler<DashboardFleetPreviewRequest>;
     /** Optional callback for fleet workflows-for-host requests from Platform. */
-    onFleetWorkflowsForHost?: (msg: DashboardFleetWorkflowsForHostRequest) => void;
+    onFleetWorkflowsForHost?: FrameHandler<DashboardFleetWorkflowsForHostRequest>;
     /** Optional callback for trust policy updates pushed from Platform. */
-    onTrustPolicyUpdate?: (msg: TrustPolicyUpdate) => void;
+    onTrustPolicyUpdate?: FrameHandler<TrustPolicyUpdate>;
     /** Optional callback for stale check run cleanup requests from Platform. */
-    onStaleCheckrunCleanup?: (msg: StaleCheckrunCleanup) => void;
+    onStaleCheckrunCleanup?: FrameHandler<StaleCheckrunCleanup>;
     /** Optional callback for join requests relayed via Platform. */
     onJoinRequest?: (msg: JoinRequest) => Promise<JoinResponse>;
     /** Custom orchestrator capabilities to merge with ORCH_CAPABILITIES in auth.request. */
@@ -540,6 +546,12 @@ export declare class PlatformClient {
      * not a recognisable dashboard request (let the caller log a warning).
      */
     private respondToInvalidDashboardRequest;
+    /**
+     * Run the handler for one Platform frame. Nothing awaits a frame, so a throw
+     * or a rejection is logged with the frame's type and request id and the
+     * connection carries on; left unhandled it would stop the orchestrator.
+     */
+    private runFrameHandler;
     /**
      * Dispatch a parsed platform message to the appropriate per-area
      * handler. Each `case` either inlines a tiny dispatch (for one-line

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

@@ -6,7 +6,7 @@ import type { WebSocketServer } from 'ws';
  * here so it is unit-testable independently of the heavy `createApp` dependency
  * graph.
  *
- * The (`permessage-deflate` compression bombs) invariant lives here: any
+ * The `permessage-deflate` compression-bomb 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.

package/dist/ws/test-relay-handlers.d.ts

@@ -118,7 +118,7 @@ export interface TestRunLogsPayload {
 }
 /**
  * Return the next chunk of a run's logs from a monotonic line-offset cursor
- * (spec §13a). The orchestrator concatenates every log line in a deterministic
+ * The orchestrator concatenates every log line in a deterministic
  * `(jobName ASC, stepIndex ASC, lineIndex ASC)` order; `cursor` is the count of
  * lines already delivered. `done` is true only when the run is terminal AND the
  * cursor has reached the end (the final tail-draining poll). A poll mid-step

package/installer-image-digests.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.11.0",
+  "version": "0.12.0",
   "images": {
-    "kici-agent": "sha256:3a7a387964836acf6f89bdd31a4ee285383349926db21ef90d43905a5bce1dd4",
-    "kici-orchestrator": "sha256:8ee2909b622f813348506589c25b8b7d4ef2333604e1bc919e15016304822a27"
+    "kici-agent": "sha256:eaa1d2270da370f150b149dbf51569b51759d7b62607fe6a1cee8b01babac2e9",
+    "kici-orchestrator": "sha256:a1a73e458b0cda327e534b74ba02406fb64170d61a3de34bfbfa8c42ab75d087"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.11.0",
+  "version": "0.12.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",
@@ -90,8 +90,8 @@
     "ws": "^8.21.3",
     "yaml": "^2.9.1",
     "zod": "^4.6.5",
-    "@kici-dev/engine": "0.11.0",
-    "@kici-dev/shared": "0.11.0"
+    "@kici-dev/engine": "0.12.0",
+    "@kici-dev/shared": "0.12.0"
   },
   "kici": {
     "metrics": {
@@ -106,7 +106,7 @@
     "@types/dockerode": "^4.0.1",
     "@types/ws": "^8.18.1",
     "kysely-ctl": "^0.21.0",
-    "@kici-dev/agent": "0.11.0"
+    "@kici-dev/agent": "0.12.0"
   },
   "scripts": {
     "build": "node ../../scripts/build-service.mjs && tsc --emitDeclarationOnly",