@kici-dev/orchestrator 0.1.21 → 0.1.23

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/bringup-api.d.ts

@@ -0,0 +1,76 @@
+import { type HostRosterStore } from '../agent/host-roster.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { AgentTokenStore } from '../agent/token-store.js';
+import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+/** Bootstrap token TTL: short by design — a leaked token is inert after it. */
+export declare const BOOTSTRAP_TOKEN_TTL_MS: number;
+/** Default pre-boot dropbear/initramfs SSH port for `preBootSend`. */
+export declare const PRE_BOOT_DEFAULT_PORT = 2222;
+/** Default forced command at a dropbear unlock endpoint (ignored by `-c` forces). */
+export declare const PRE_BOOT_DEFAULT_COMMAND = "cryptroot-unlock";
+/** Shared deps for the bring-up handlers. */
+export interface BringupApiDeps {
+    registry: AgentRegistry;
+    rosterStore: HostRosterStore;
+    tokenStore: AgentTokenStore;
+    secretResolver: SecretResolver;
+    accessLog: AccessLogWriter;
+    graceMs: number;
+    /** Resolve the orchestrator's tenant org id (single-tenant ⇒ `__default__`). */
+    resolveOrgId: () => string;
+    /** Resolve the orchestrator WS URL the init-runner should dial. */
+    resolveOrchestratorUrl: () => string;
+}
+/**
+ * Reach the calling agent connects to + the resolved private key. Returned to
+ * the agent so it can run the SSH transport. The key value transits to the ops
+ * agent by design (it custodies the bring-up key), exactly as resolved secrets
+ * reach an agent at job dispatch.
+ */
+export interface BringupReach {
+    agentId: string;
+    address: string | null;
+    sshUser: string | null;
+    sshPort: number | null;
+}
+/** Result the agent receives for an `ensureInitRunner` call. */
+export interface EnsureInitRunnerResult {
+    broughtUp: boolean;
+    reach?: BringupReach;
+    privateKey?: string;
+    bootstrapToken?: string;
+    targetAgentId?: string;
+    orchestratorUrl?: string;
+    /** The init-runner label set the bootstrap token is bound to. */
+    labels?: string[];
+}
+/** Result the agent receives for a `preBootSend` call. */
+export interface PreBootSendResult {
+    reach: BringupReach;
+    /** The host's bring-up SSH private key — needed to authenticate to dropbear. */
+    privateKey: string;
+    /** The resolved pre-boot input (e.g. LUKS passphrase) to pipe to the prompt. */
+    input: string;
+    port: number;
+    command: string;
+}
+/** Thrown when the caller lacks `kici:capability:ssh-transport`. */
+export declare class CapabilityDeniedError extends Error {
+    constructor(callingAgentId: string);
+}
+/**
+ * Build the `kici.ensureInitRunner` handler. No-ops when the target already has
+ * a live agent; otherwise gates on the caller's capability, resolves the SSH
+ * key, mints a single-use bootstrap token, audits, and returns the material the
+ * agent needs to drop + start the init-runner over SSH.
+ */
+export declare function createEnsureInitRunnerHandler(deps: BringupApiDeps): (callingAgentId: string, params: Record<string, unknown>) => Promise<EnsureInitRunnerResult>;
+/**
+ * Build the `kici.preBootSend` handler. Gates on the caller's capability,
+ * resolves the pre-boot input secret (e.g. a LUKS passphrase), audits, and
+ * returns the input + reach so the agent can pipe it to the target's pre-boot
+ * SSH endpoint.
+ */
+export declare function createPreBootSendHandler(deps: BringupApiDeps): (callingAgentId: string, params: Record<string, unknown>) => Promise<PreBootSendResult>;
+//# sourceMappingURL=bringup-api.d.ts.map

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

@@ -0,0 +1,43 @@
+/**
+ * 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 { RegistrationStore } from '../registration/registration-store.js';
+import type { DashboardFleetHostsResponse, DashboardFleetHostResponse, DashboardFleetPreviewResponse, DashboardFleetWorkflowsForHostResponse, 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>;
+    /** All registered workflows (for the host-centric workflows-for-host read). */
+    registrationStore: RegistrationStore;
+}
+/** 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>;
+/**
+ * workflows-for-host: the host-centric inverse of the preview. Resolves this
+ * host's label set once, then tests every registered (non-disabled) workflow's
+ * runsOnAll predicate against it, returning each match with the fan-out's
+ * `onUnreachable` policy and the host's per-workflow disposition.
+ */
+export declare function handleFleetWorkflowsForHostRequest(deps: FleetHandlerDeps, requestId: string, agentId: string): Promise<DashboardFleetWorkflowsForHostResponse>;
+//# 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,19 @@
+/**
+ * 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 LockWorkflow } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+import type { ResolvedRunsOnAll } from './dashboard-fleet-handler.js';
+/** Pull the first static job's runsOnAll predicate from a parsed lock entry, or null. */
+export declare function extractRunsOnAll(workflow: LockWorkflow): ResolvedRunsOnAll | null;
+/** 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/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 DashboardFleetWorkflowsForHostRequest, 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,14 @@ 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 fleet workflows-for-host requests from Platform. */
+    onFleetWorkflowsForHost?: (msg: DashboardFleetWorkflowsForHostRequest) => 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 +202,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 +227,10 @@ export declare class PlatformClient {
     private readonly onDashboardDiagnostics?;
     private readonly onDashboardScalerCapacity?;
     private readonly onDashboardScalerAgents?;
+    private readonly onFleetHosts?;
+    private readonly onFleetHost?;
+    private readonly onFleetPreview?;
+    private readonly onFleetWorkflowsForHost?;
     private readonly onTrustPolicyUpdate?;
     private readonly onStaleCheckrunCleanup?;
     private readonly onJoinRequest?;

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

@@ -16,12 +16,23 @@ 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;
+    /**
+     * Log writer that owns the in-flight append tracking. The logs cursor
+     * handler drains its pending appends for a terminal run before computing the
+     * `done` flag, so the final (fire-and-forget) log chunk can't be lost to a
+     * race with the run-status transition.
+     */
+    logWriter?: {
+        drain(runId: string): Promise<void>;
+    };
     accessLog?: AccessLogWriter;
     /** Canonical org id this orchestrator is bound to (for access_log attribution). */
     orgId?: string | null;

package/installer-image-digests.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.1.21",
+  "version": "0.1.23",
   "images": {
-    "kici-agent": "sha256:28896aa6665887f959765c821d0535f44e6bcaa73b3f45d21c39b6f2f9604c49",
-    "kici-orchestrator": "sha256:d8b1b6306be8beaa973b0828e6d5ffbcb6f10b3c81b2875e37435b4bf140ecbe"
+    "kici-agent": "sha256:f3b4628262e2ec10d9f0a5b8eed54a1361e4a917728b38a0165a144d1f885653",
+    "kici-orchestrator": "sha256:240790924ee73e4b1230deb989d3db6c05141ca4db6376baeb88f5e0aeed19ee"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "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/engine": "0.1.21",
-    "@kici-dev/shared": "0.1.21"
+    "@kici-dev/engine": "0.1.23",
+    "@kici-dev/shared": "0.1.23"
   },
   "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.21"
+    "@kici-dev/agent": "0.1.23"
   },
   "scripts": {
     "build": "node ../../scripts/build-service.mjs && tsc --emitDeclarationOnly",