@kici-dev/orchestrator 0.1.20 → 0.1.22

package/dist/worker/in-memory-job-queue.d.ts

@@ -42,6 +42,23 @@ export declare class InMemoryJobQueue {
      * labels no longer match, or the agent's gate is not satisfied.
      */
     dequeueById(jobId: string, agentLabels: string[], agentMandatoryLabels?: string[]): Promise<QueuedJob | null>;
+    /**
+     * Dequeue the oldest pending job pinned to a specific agent. Mirrors the
+     * DB-backed `JobQueue.dequeueByPinnedAgent` that `Dispatcher.onAgentAvailable`
+     * calls — host-fanout children pinned to THIS agent drain before the generic
+     * label drain. Like the DB version, a pinned job relaxes the label-subset
+     * gate (the agent is its designated runner) and only the JS regex
+     * post-filter is applied.
+     *
+     * The worker receives jobs via direct P2P dispatch and does not currently
+     * pin jobs to agents, so in practice no in-memory job carries a
+     * `pinnedAgentId` and this returns null — `onAgentAvailable` then falls back
+     * to `dequeueForLabels`. Implementing it (rather than leaving it undefined)
+     * is mandatory: `Dispatcher.onAgentAvailable` invokes it unconditionally, so
+     * its absence threw `TypeError: this.queue.dequeueByPinnedAgent is not a
+     * function` as an unhandled rejection that crashed the worker.
+     */
+    dequeueByPinnedAgent(agentId: string, agentLabels?: string[]): Promise<QueuedJob | null>;
     /** Return count of pending jobs. */
     getDepth(): Promise<number>;
     /** No-op — the job is already tracked in `dispatched` from dequeue. */

package/dist/worker/peer-outbox.d.ts

@@ -0,0 +1,36 @@
+import type { JobProgress } from '@kici-dev/engine';
+export interface OutboxRecord {
+    coordUrl: string;
+    message: JobProgress;
+    persistedAt: number;
+}
+/** Durable, at-least-once store of terminal job.progress awaiting coordinator ACK. */
+export declare class PeerOutbox {
+    private readonly dir;
+    private readonly now;
+    private readonly records;
+    constructor(dir: string, now?: () => number);
+    private static coordKey;
+    private static recordKey;
+    private fileFor;
+    loadFromDisk(): Promise<void>;
+    enqueue(coordUrl: string, message: JobProgress): Promise<void>;
+    /**
+     * Synchronous, durably-fsynced enqueue. The terminal job status is on disk
+     * before this method returns — there is no async window in which an
+     * un-flushed write can be lost if the worker process is killed moments
+     * later (e.g. a worker orchestrator that crashes during microVM teardown
+     * right after the job completes). The asynchronous {@link enqueue} is
+     * fire-and-forget at its call site, so its fsync can be dropped when the
+     * event loop never runs again; this variant blocks the (infrequent,
+     * once-per-job-terminal) call path until the bytes are durable instead.
+     */
+    enqueueSync(coordUrl: string, message: JobProgress): void;
+    ack(coordUrl: string, runId: string, jobId: string): Promise<void>;
+    pendingFor(coordUrl: string): OutboxRecord[];
+    prune(ttlMs: number, now?: number): Promise<number>;
+    private fsync;
+    private fsyncDir;
+    private fsyncDirSync;
+}
+//# sourceMappingURL=peer-outbox.d.ts.map

package/dist/worker/worker-outbox-relay.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Relay glue between the worker's in-memory execution tracker and the durable
+ * peer outbox. Extracted so the mapping/replay logic is unit-testable and so
+ * the worker bootstrap stays under the function-length cap.
+ */
+import { type JobProgress } from '@kici-dev/engine';
+import type { StatusUpdate } from './in-memory-execution-tracker.js';
+import type { PeerOutbox } from './peer-outbox.js';
+/** Map a terminal job-level StatusUpdate to the JobProgress to durably relay; null otherwise. */
+export declare function buildTerminalJobProgress(update: StatusUpdate): JobProgress | null;
+/** Re-send every outbox record destined for `url`. Send failures are retried on the next connect. */
+export declare function replayPending(outbox: PeerOutbox, send: (m: JobProgress) => boolean, url: string): void;
+//# sourceMappingURL=worker-outbox-relay.d.ts.map

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

@@ -227,12 +227,13 @@ export interface AgentWsHandlerDeps {
         reason?: string;
     }>;
     /**
-     * Optional callback when an agent blocks a `requireApproval` step. The server
-     * creates a step-scoped hold from the carried clauses and returns a promise
-     * that resolves when the hold is approved, rejected, or expired. The handler
-     * relays the resolution back to the originating agent as a
-     * `step.approval-resolved` message. The `agentId` lets the server drop the
-     * pending resolver when the agent disconnects.
+     * Optional callback when an agent blocks an `approval` step. The server
+     * creates a step-scoped hold from the carried clauses (and the drift
+     * `payload` for a `when: 'drift'` gate) and returns a promise that resolves
+     * when the hold is approved, rejected, or expired. The handler relays the
+     * resolution back to the originating agent as a `step.approval-resolved`
+     * message. The `agentId` lets the server drop the pending resolver when the
+     * agent disconnects.
      */
     onStepApproval?: (agentId: string, msg: {
         runId: string;
@@ -246,6 +247,10 @@ export interface AgentWsHandlerDeps {
         }>;
         reason: string;
         timeoutSeconds?: number;
+        payload?: {
+            summaryMarkdown: string;
+            drift: unknown;
+        };
     }) => Promise<{
         outcome: 'approved' | 'rejected' | 'expired';
         reason?: string;

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

@@ -0,0 +1,33 @@
+/**
+ * Orchestrator-side handlers for the fleet-management read path (P2).
+ *
+ * Each handler answers one Platform->orchestrator read-relay request from
+ * `HostRosterStore`, returning the canonical `HostInventoryEntry` shape on the
+ * wire. The handlers are pure (they take their dependencies as arguments) so
+ * the WS wiring in `server.ts` stays a thin adapter and the logic is unit
+ * testable without a live DB / Platform connection.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import { HostRosterStore } from '../agent/host-roster.js';
+import type { DashboardFleetHostsResponse, DashboardFleetHostResponse, DashboardFleetPreviewResponse, LabelMatcher, OnUnreachableMode } from '@kici-dev/engine';
+/** A workflow's resolved runsOnAll predicate, or null when it has none. */
+export interface ResolvedRunsOnAll {
+    include: readonly (readonly LabelMatcher[])[];
+    exclude: readonly LabelMatcher[];
+    onUnreachable: OnUnreachableMode;
+}
+export interface FleetHandlerDeps {
+    db: Kysely<Database>;
+    rosterStore: HostRosterStore;
+    rosterGraceMs: number;
+    /** Resolve a workflow's runsOnAll predicate + onUnreachable, or null. */
+    resolveRunsOnAll: (workflowName: string) => Promise<ResolvedRunsOnAll | null>;
+}
+/** Roster: every declared/live host as a `HostInventoryEntry`. */
+export declare function handleFleetHostsRequest(deps: FleetHandlerDeps, requestId: string): Promise<DashboardFleetHostsResponse>;
+/** Host detail: one host (or null) plus its most-recent pinned runs. */
+export declare function handleFleetHostRequest(deps: FleetHandlerDeps, requestId: string, agentId: string): Promise<DashboardFleetHostResponse>;
+/** runsOnAll preview: matched hosts + the fan-out policy + estimated child count. */
+export declare function handleFleetPreviewRequest(deps: FleetHandlerDeps, requestId: string, workflowName: string): Promise<DashboardFleetPreviewResponse>;
+//# sourceMappingURL=dashboard-fleet-handler.d.ts.map

package/dist/ws/dashboard-fleet-write-handler.d.ts

@@ -0,0 +1,60 @@
+import type { FleetHostDeclareRequest, FleetHostRemoveRequest } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { HostRosterStore } from '../agent/host-roster.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+interface DashboardFleetWriteHandlerDeps {
+    /** Send a response message back to Platform over the WS connection. */
+    send: (msg: unknown) => void;
+    /** The orchestrator host roster store (declare / remove). */
+    rosterStore: HostRosterStore;
+    /** Database — required for dashboard-write policy lookups. */
+    db: Kysely<Database>;
+    /** Access log writer — records one row per 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;
+}
+/** Messages this handler owns. */
+type FleetWriteMessage = FleetHostDeclareRequest | FleetHostRemoveRequest;
+/**
+ * Handler for the fleet host-write WS messages. Dispatches by type and calls
+ * the host roster store behind the dashboard-write policy gate.
+ */
+export declare class DashboardFleetWriteHandler {
+    private readonly deps;
+    private orgId;
+    private routingKey;
+    private readonly accessLog;
+    constructor(deps: DashboardFleetWriteHandlerDeps);
+    /**
+     * 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;
+    /**
+     * Defense-in-depth dashboard-write policy gate. Returns true when the
+     * operation is allowed and the caller should proceed. Returns false when the
+     * policy is disabled — also records a `denied` access_log row and emits a
+     * structured `operation_disabled` envelope on the WS.
+     *
+     * Fails open when no org is bound — the orch hasn't resolved a customer yet.
+     */
+    private enforcePolicy;
+    /**
+     * Write an access_log row for a handler invocation. Best-effort; the writer
+     * swallows failures.
+     */
+    private recordAccess;
+    /**
+     * Route a fleet host-write message to the appropriate handler. Returns true
+     * if the message was handled, false otherwise.
+     */
+    handleMessage(msg: FleetWriteMessage): Promise<boolean>;
+    private handleDeclare;
+    private handleRemove;
+}
+export {};
+//# sourceMappingURL=dashboard-fleet-write-handler.d.ts.map

package/dist/ws/fleet-runs-on-all.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resolve a workflow's `runsOnAll` host-fan-out predicate from the orchestrator's
+ * persisted registrations, for the fleet runsOnAll-preview read path.
+ *
+ * The orchestrator stores each registered workflow's full lock entry in
+ * `workflow_registrations.lock_entry` (JSON). This reader parses that entry,
+ * finds the first static job carrying a `runsOnAll` predicate, and returns its
+ * `{ include, exclude, onUnreachable }` — or null when no registered workflow of
+ * that name declares a host fan-out.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { ResolvedRunsOnAll } from './dashboard-fleet-handler.js';
+/** Find the resolved runsOnAll predicate for a workflow by name, or null. */
+export declare function resolveWorkflowRunsOnAll(db: Kysely<Database>, workflowName: string): Promise<ResolvedRunsOnAll | null>;
+//# sourceMappingURL=fleet-runs-on-all.d.ts.map

package/dist/ws/inventory-api.d.ts

@@ -0,0 +1,17 @@
+import { type HostInventoryEntry } from '@kici-dev/engine';
+import type { HostRosterStore } from '../agent/host-roster.js';
+/** Store surface the inventory handlers need (kept narrow for testability). */
+export interface InventoryApiDeps {
+    rosterStore: Pick<HostRosterStore, 'queryInventory' | 'getInventory'>;
+    /** Roster grace window (ms) — the same value runsOnAll's `findMatching` uses. */
+    graceMs: number;
+}
+/**
+ * Build the `inventory.query` handler. Validates the optional label selector
+ * (`include` OR-of-AND groups + `exclude`); an empty selector ⇒ all hosts.
+ * Property filtering is done client-side in the workflow.
+ */
+export declare function createInventoryQueryHandler(deps: InventoryApiDeps): (agentId: string, params: Record<string, unknown>) => Promise<HostInventoryEntry[]>;
+/** Build the `inventory.get` handler — single-host lookup, null when absent. */
+export declare function createInventoryGetHandler(deps: InventoryApiDeps): (agentId: string, params: Record<string, unknown>) => Promise<HostInventoryEntry | null>;
+//# sourceMappingURL=inventory-api.d.ts.map

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

@@ -1,4 +1,4 @@
-import { type OrchestratorToPlatformMessage, type WebhookRelay, type WebhookRelayResult, type TrustPolicyUpdate, type StaleCheckrunCleanup, type DashboardRunDetailRequest, type DashboardRunsListRequest, type DashboardRunsFiltersRequest, type DashboardSourcesListRequest, type DashboardStepLogsRequest, type DashboardAttestationsListRequest, type DashboardOrchLogsRequest, type RunRerunRequest, type ManualScheduleRequest, type RunCancelRequest, type DashboardPayloadRequest, type DashboardPlatformToOrchMessage, type TestRelayRequest, type DashboardDiagnosticsRequest, type DashboardScalerCapacityRequest, type DashboardScalerAgentsRequest, type JoinRequest, type JoinResponse, type OrchCapabilities, type OrchRole } from '@kici-dev/engine';
+import { type OrchestratorToPlatformMessage, type WebhookRelay, type WebhookRelayResult, type TrustPolicyUpdate, type StaleCheckrunCleanup, type DashboardRunDetailRequest, type DashboardRunsListRequest, type DashboardRunsFiltersRequest, type DashboardSourcesListRequest, type DashboardStepLogsRequest, type DashboardAttestationsListRequest, 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 JoinRequest, type JoinResponse, type DeploymentIdentity, 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
@@ -58,6 +58,8 @@ export interface PlatformClientOptions {
     mode?: string;
     /** Scaler backends configured (e.g. ["container", "firecracker"]). Sent in source.register for diagnostics. */
     scalerBackends?: string[];
+    /** How the orchestrator process was deployed. Sent in source.register so the dashboard can build the correct kici-admin invocation. */
+    deployment?: DeploymentIdentity;
     /** 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. */
@@ -134,6 +136,12 @@ export interface PlatformClientOptions {
     onDashboardScalerCapacity?: (msg: DashboardScalerCapacityRequest) => void;
     /** Optional callback for dashboard scaler agents requests from Platform. */
     onDashboardScalerAgents?: (msg: DashboardScalerAgentsRequest) => void;
+    /** Optional callback for fleet roster requests from Platform. */
+    onFleetHosts?: (msg: DashboardFleetHostsRequest) => void;
+    /** Optional callback for fleet host-detail requests from Platform. */
+    onFleetHost?: (msg: DashboardFleetHostRequest) => void;
+    /** Optional callback for fleet runsOnAll-preview requests from Platform. */
+    onFleetPreview?: (msg: DashboardFleetPreviewRequest) => void;
     /** Optional callback for trust policy updates pushed from Platform. */
     onTrustPolicyUpdate?: (msg: TrustPolicyUpdate) => void;
     /** Optional callback for stale check run cleanup requests from Platform. */
@@ -192,6 +200,7 @@ export declare class PlatformClient {
     private readonly version?;
     private readonly mode?;
     private readonly scalerBackends?;
+    private readonly deployment?;
     private readonly s3LogAccess?;
     private readonly queueTimeoutMs?;
     private readonly heartbeatIntervalMs;
@@ -216,6 +225,9 @@ export declare class PlatformClient {
     private readonly onDashboardDiagnostics?;
     private readonly onDashboardScalerCapacity?;
     private readonly onDashboardScalerAgents?;
+    private readonly onFleetHosts?;
+    private readonly onFleetHost?;
+    private readonly onFleetPreview?;
     private readonly onTrustPolicyUpdate?;
     private readonly onStaleCheckrunCleanup?;
     private readonly onJoinRequest?;

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

@@ -16,10 +16,12 @@ import type { Database } from '../db/types.js';
 import type { CacheStorage } from '../storage/types.js';
 import type { LogStorage } from '../reporting/log-storage.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
-import { type TestPipelineDeps } from '../pipeline/test-pipeline.js';
+import type { ProcessingDeps } from '../pipeline/processor.js';
 /** Dependencies shared by all five test-relay handlers. */
-export interface TestRelayHandlerDeps extends TestPipelineDeps {
+export interface TestRelayHandlerDeps extends ProcessingDeps {
     db: Kysely<Database>;
+    /** Agent registry — required here: the cancel handler resolves the job's agent. */
+    agentRegistry: NonNullable<ProcessingDeps['agentRegistry']>;
     cacheStorage?: CacheStorage;
     logStorage?: LogStorage;
     accessLog?: AccessLogWriter;

package/installer-image-digests.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.1.20",
+  "version": "0.1.22",
   "images": {
-    "kici-agent": "sha256:ff28cf8e8fd0405b63797dbd8a972ac328184f53f18fb20443220758769f5fec",
-    "kici-orchestrator": "sha256:f8e27842e455c0fbfa7df564c8adc6505054110610f20b35618c56841bbc905f"
+    "kici-agent": "sha256:7d3b048a45f46f51b843944ce106514094f2aac428ffe3aa35d8a97b174b553f",
+    "kici-orchestrator": "sha256:98e3b1ef13a3d28844b48ecbfbf26b982fc6fe12292cf138959721c08b48eabe"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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",
@@ -86,8 +86,8 @@
     "ws": "^8.21.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@kici-dev/shared": "0.1.20",
-    "@kici-dev/engine": "0.1.20"
+    "@kici-dev/engine": "0.1.22",
+    "@kici-dev/shared": "0.1.22"
   },
   "kici": {
     "metrics": {
@@ -101,7 +101,7 @@
     "@types/archiver": "^8.0.0",
     "@types/dockerode": "^4.0.1",
     "kysely-ctl": "^0.21.0",
-    "@kici-dev/agent": "0.1.20"
+    "@kici-dev/agent": "0.1.22"
   },
   "scripts": {
     "build": "node ../../scripts/build-service.mjs && tsc --emitDeclarationOnly",