@kici-dev/orchestrator 0.1.22 → 0.1.24

package/dist/storage/loopback-guard.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Startup guard: an orchestrator that runs non-co-located agents (any scaler
+ * backend) must not hand them a loopback storage URL. Loopback is only
+ * reachable by a co-located process, so a scaled agent would fail with an
+ * opaque ECONNREFUSED. This module detects the misconfiguration so the
+ * orchestrator can refuse to start with a clear, actionable error.
+ */
+import { ScalerBackendType } from '@kici-dev/engine';
+import type { AppConfig } from '../config.js';
+import type { ScalerConfig } from '../scaler/types.js';
+/**
+ * Every current scaler backend places the agent outside the orchestrator's
+ * loopback (separate netns, microVM, or host). Only a future co-located/"local"
+ * backend would be absent from this set. `kubernetes` is included defensively
+ * even though `ScalerEntry.type` excludes it today.
+ */
+export declare const NON_COLOCATED_BACKENDS: ReadonlySet<ScalerBackendType>;
+/** True for any host an agent in another netns/VM/host cannot reach. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/**
+ * Decide whether an agent-facing storage URL is a loopback address that a
+ * non-co-located agent could not reach. Returns a remediation message, or null
+ * when the configuration is safe.
+ */
+export declare function checkLoopbackAgentEndpoint(input: {
+    agentFacingUrl: string | null;
+    endpointSource: string;
+    fixEnvVar: string;
+    scalerBackends: ScalerBackendType[];
+}): {
+    message: string;
+} | null;
+/**
+ * Resolve the URL an AGENT would use to reach storage, plus the env var an
+ * operator would set to fix a loopback misconfiguration. Returns null when the
+ * storage backend has no agent-facing URL to validate.
+ */
+export declare function resolveAgentFacingStorage(config: AppConfig): {
+    url: string | null;
+    source: string;
+    fixEnvVar: string;
+} | null;
+/**
+ * Refuse to start when this orchestrator runs non-co-located agents (any scaler
+ * configured) and the agent-facing storage URL is a loopback address. Logs the
+ * remediation (so it reaches `kici-admin orchestrator logs`) then throws.
+ */
+export declare function assertAgentReachableStorage(config: AppConfig, scalerConfig: ScalerConfig | null): void;
+//# sourceMappingURL=loopback-guard.d.ts.map

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

@@ -16,7 +16,8 @@
  * When agentAuthMode === 'none', the auth phase is skipped (legacy behavior).
  */
 import type { WSEvents } from 'hono/ws';
-import type { RateLimiterConfig } from '@kici-dev/engine';
+import type { RateLimiterConfig, AttestationVerifyStatus } from '@kici-dev/engine';
+import type { ProvenanceTrustRoot } from '../provenance/trust-root.js';
 import type { AgentRegistry } from '../agent/registry.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
 import type { AgentTokenStore } from '../agent/token-store.js';
@@ -98,6 +99,10 @@ export interface AgentWsHandlerDeps {
         timestamp: number;
         data?: Record<string, unknown>;
         secretsAccessed?: string[];
+        /** Parallel step-group concurrency role (`sequential` | `parallel-child` | `parallel-group`). */
+        concurrencyKind?: string;
+        /** Parallel-group correlation id shared by a group's children. */
+        groupId?: string;
         /** Raw log bytes accumulated by this step's LogStreamer at terminal time. */
         logBytesStreamed?: number;
     }) => void;
@@ -187,9 +192,15 @@ export interface AgentWsHandlerDeps {
      * dep so a deployment can decide whether attestations share the cache bucket.
      */
     provenanceStorage?: CacheStorage;
+    /**
+     * Provenance trust root used to verify each bundle at ingest. When absent (or
+     * its issuer is null) the verdict is recorded as `unverifiable`.
+     */
+    provenanceTrustRoot?: ProvenanceTrustRoot;
     /**
      * Record a completed provenance-bundle upload (writes an attestations row).
      * `runId` is resolved server-side from the job's dispatch ref, never the wire.
+     * The verdict fields are computed at ingest (verify-at-ingest).
      */
     onProvenanceUpload?: (record: {
         runId: string;
@@ -198,6 +209,9 @@ export interface AgentWsHandlerDeps {
         subjectDigest: string;
         storageKey: string;
         mediaType: string;
+        verifyStatus: AttestationVerifyStatus;
+        verifyReason: string | null;
+        verifiedAt: Date | null;
     }) => Promise<void>;
     /** Optional rate limiter configuration. */
     rateLimiterConfig?: RateLimiterConfig;

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

@@ -10,7 +10,8 @@
 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';
+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[])[];
@@ -23,6 +24,8 @@ export interface FleetHandlerDeps {
     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>;
@@ -30,4 +33,11 @@ export declare function handleFleetHostsRequest(deps: FleetHandlerDeps, requestI
 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/fleet-runs-on-all.d.ts

@@ -9,8 +9,11 @@
  * 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 DashboardFleetHostsRequest, type DashboardFleetHostRequest, type DashboardFleetPreviewRequest, type JoinRequest, type JoinResponse, type DeploymentIdentity, type OrchCapabilities, type OrchRole } from '@kici-dev/engine';
+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 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
@@ -100,8 +100,16 @@ export interface PlatformClientOptions {
         orgId: string;
         clusterId: string | null;
     }) => void;
+    /**
+     * Optional callback fired with the provenance trust root (OIDC issuer) the
+     * Platform supplies on `auth.success`. The orchestrator uses it to verify
+     * provenance bundles at ingest. `null` means provenance is not configured.
+     */
+    onProvenanceIssuer?: (issuer: string | null) => void;
     /** Optional callback for dashboard run detail requests from Platform. */
     onDashboardRunDetail?: (msg: DashboardRunDetailRequest) => void;
+    /** Optional callback for dashboard structured run-result requests from Platform. */
+    onDashboardRunStructured?: (msg: DashboardRunStructuredRequest) => 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. */
@@ -112,6 +120,10 @@ export interface PlatformClientOptions {
     onDashboardStepLogs?: (msg: DashboardStepLogsRequest) => void;
     /** Optional callback for dashboard attestations-list requests from Platform. */
     onDashboardAttestationsList?: (msg: DashboardAttestationsListRequest) => void;
+    /** Optional callback for org-wide attestations list (browser) requests from Platform. */
+    onDashboardAttestationsListAll?: (msg: DashboardAttestationsListAllRequest) => void;
+    /** Optional callback for single-attestation detail requests from Platform. */
+    onDashboardAttestationGet?: (msg: DashboardAttestationGetRequest) => 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). */
@@ -142,6 +154,8 @@ export interface PlatformClientOptions {
     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. */
@@ -165,6 +179,25 @@ export interface PlatformClientOptions {
      */
     relayBuffer?: RelayBufferRegistry;
 }
+/** Error `*.response` frame shape for a dashboard request that failed validation. */
+export interface DashboardRequestErrorFrame {
+    type: string;
+    requestId: string;
+    error: string;
+    code: string;
+    orchVersion?: string;
+    requestType: string;
+}
+/**
+ * Build the error `*.response` frame for a dashboard request that failed schema
+ * validation, distinguishing a request type this build has never heard of
+ * (version mismatch → upgrade the orchestrator) from a known type with a
+ * malformed body (genuine client error).
+ */
+export declare function classifyDashboardRequestError(raw: {
+    type: string;
+    requestId: string;
+}, knownTypes: ReadonlySet<string>, orchVersion: string | undefined): DashboardRequestErrorFrame;
 /**
  * WebSocket client that connects the orchestrator to the Platform relay.
  *
@@ -209,12 +242,16 @@ export declare class PlatformClient {
     private readonly onPeerDiscover?;
     private readonly onAuthenticated?;
     private readonly onOrgIdentified?;
+    private readonly onProvenanceIssuer?;
     private readonly onDashboardRunDetail?;
+    private readonly onDashboardRunStructured?;
     private readonly onDashboardRunsList?;
     private readonly onDashboardRunsFilters?;
     private readonly onDashboardSourcesList?;
     private readonly onDashboardStepLogs?;
     private readonly onDashboardAttestationsList?;
+    private readonly onDashboardAttestationsListAll?;
+    private readonly onDashboardAttestationGet?;
     private readonly onRunRerun?;
     private readonly onManualSchedule?;
     private readonly onRunCancel?;
@@ -228,6 +265,7 @@ export declare class PlatformClient {
     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

@@ -24,6 +24,15 @@ export interface TestRelayHandlerDeps extends ProcessingDeps {
     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.22",
+  "version": "0.1.24",
   "images": {
-    "kici-agent": "sha256:7d3b048a45f46f51b843944ce106514094f2aac428ffe3aa35d8a97b174b553f",
-    "kici-orchestrator": "sha256:98e3b1ef13a3d28844b48ecbfbf26b982fc6fe12292cf138959721c08b48eabe"
+    "kici-agent": "sha256:1e02f0cda7f398d72b2e95dd74f9c67fb5a8b041307886ef85a6eae3024c7a4e",
+    "kici-orchestrator": "sha256:9aa83c19f39b3f80d62f328af57a38a681670766ed2ec7f46dabecd11e82538b"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "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",
@@ -39,9 +39,6 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "bin": {
-    "kici-admin": "./dist/cli.js"
-  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -63,7 +60,7 @@
     "@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": "^2.0.4",
+    "@hono/node-server": "^1.19.14",
     "@hono/node-ws": "^1.3.1",
     "@inquirer/prompts": "^8.5.2",
     "@octokit/auth-app": "^8.2.0",
@@ -86,8 +83,8 @@
     "ws": "^8.21.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@kici-dev/engine": "0.1.22",
-    "@kici-dev/shared": "0.1.22"
+    "@kici-dev/engine": "0.1.24",
+    "@kici-dev/shared": "0.1.24"
   },
   "kici": {
     "metrics": {
@@ -100,8 +97,9 @@
   "devDependencies": {
     "@types/archiver": "^8.0.0",
     "@types/dockerode": "^4.0.1",
+    "jose": "^6.1.0",
     "kysely-ctl": "^0.21.0",
-    "@kici-dev/agent": "0.1.22"
+    "@kici-dev/agent": "0.1.24"
   },
   "scripts": {
     "build": "node ../../scripts/build-service.mjs && tsc --emitDeclarationOnly",