@kici-dev/orchestrator 0.1.23 → 0.1.25

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/webhook/dedup.d.ts

@@ -24,6 +24,20 @@ export declare class DedupCache {
      * Idempotent -- duplicate marks are silently ignored.
      */
     mark(deliveryId: string): Promise<void>;
+    /**
+     * Atomically claim a delivery ID. Returns `true` when this call inserted the
+     * row (the caller owns this delivery — proceed), `false` when a row already
+     * existed (duplicate — drop it).
+     *
+     * This replaces the historic `exists()`-then-`mark()` check-then-act, which
+     * raced across cluster instances: behind an external load balancer, GitHub's
+     * own retries and LB retries can fan the same `X-GitHub-Delivery` to two
+     * instances concurrently — both passed `exists()` and both dispatched. The
+     * single `INSERT … ON CONFLICT (delivery_id) DO NOTHING` is the atomic
+     * arbiter backed by the `dedup_cache` primary key, so exactly one caller
+     * wins regardless of how many instances receive the same delivery.
+     */
+    claim(deliveryId: string): Promise<boolean>;
     /**
      * Remove expired entries from the database.
      * Also trims the in-memory cache to MAX_MEMORY_CACHE_SIZE.

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,7 +209,33 @@ export interface AgentWsHandlerDeps {
         subjectDigest: string;
         storageKey: string;
         mediaType: string;
+        verifyStatus: AttestationVerifyStatus;
+        verifyReason: string | null;
+        verifiedAt: Date | null;
+    }) => Promise<void>;
+    /**
+     * Optional callback when an agent reports a deferred attestation (transient
+     * mint failure). Persists the frozen envelope into the deferred-attestation
+     * outbox; the job stays green and the token is minted later.
+     */
+    onProvenanceDefer?: (record: {
+        runId: string;
+        jobId: string;
+        subjectName: string;
+        subjectDigest: string;
+        audience: string;
+        mediaType: string;
+        statementHash: string;
+        dsseEnvelope: unknown;
+        publicKey: unknown;
+        originKind: 'deferred' | 'offline-backfill';
     }) => Promise<void>;
+    /**
+     * Classify a deferred attestation's origin from the local run row: a run
+     * ingested while the Platform was down is `offline-backfill`, otherwise a
+     * transient blip is `deferred`. Defaults to always-`deferred` when unset.
+     */
+    classifyDeferOrigin?: (runId: string) => Promise<'deferred' | 'offline-backfill'>;
     /** Optional rate limiter configuration. */
     rateLimiterConfig?: RateLimiterConfig;
     /** Optional ownership tracker for validating job-related messages. */

package/dist/ws/oidc-token-relay.d.ts

@@ -4,39 +4,43 @@
  * Backs the `oidc.token.request` agent.api method: an agent asks for a
  * short-lived OIDC ID token for a job it is running; the orchestrator verifies
  * the agent owns that job, resolves its runId from its own dispatch state, and
- * relays a mint request to the Platform's token-mint endpoint over HTTPS using
- * the orchestrator's own `KICI_PLATFORM_TOKEN`. The agent never holds Platform
- * credentials and never asserts its own identity claims — the Platform derives
- * every identity claim from its own run/job rows.
+ * relays a mint request to the Platform over the authenticated orchestrator↔
+ * Platform WebSocket (orchestrator-initiated RPC). The agent never holds
+ * Platform credentials and never asserts its own identity claims — the Platform
+ * derives every identity claim from its own run/job rows.
  */
-import { type OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
-/** 404 / 409: the run/job is missing on the Platform or the job is terminal. */
+import { type OidcTokenResult, type DeferredMintParams } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+/** rejected: the run/job is missing on the Platform or the job is terminal. */
 export declare class MintRejectedError extends Error {
 }
-/** 503: provenance signing is not configured / the Platform is unavailable. */
+/** unavailable: provenance signing is not configured / the Platform is unavailable. */
 export declare class MintUnavailableError extends Error {
 }
-/** Any other non-2xx from the mint endpoint. */
+/** Any other failure (transport or Platform-side). */
 export declare class MintRelayError extends Error {
 }
-/**
- * Turn the Platform WS URL (`wss://host[/base]/ws`) into its HTTP base
- * (`https://host[/base]`). Maps the scheme and strips a trailing `/ws` while
- * preserving the host and any basePath in front of it.
- */
-export declare function deriveHttpBaseFromWsUrl(wsUrl: string): string;
+/** Minimal surface the relay needs from the Platform WS client. */
+export interface MintPlatformClient {
+    sendRequestAndAwait<Res>(type: 'oidc.mint.request', payload: Record<string, unknown>, timeoutMs?: number): Promise<Res>;
+}
 export interface RequestMintArgs {
-    httpBase: string;
-    token: string;
+    platformClient: MintPlatformClient;
     orchestratorId: string;
     runId: string;
     jobId: string;
     audience: string;
+    /**
+     * Deferred *fulfilment* mint: when set, the request knowingly targets a
+     * completed (terminal) job and binds the frozen statement hash + origin so
+     * the Platform relaxes its live-job check and stamps the mint-timing marker.
+     * The live agent path never sets this.
+     */
+    deferred?: DeferredMintParams;
 }
 /**
- * Call the Platform token-mint endpoint over HTTPS using the orchestrator's
- * Platform token. Maps non-2xx responses to typed errors so the agent always
- * sees a clear message instead of a raw 5xx body.
+ * Send a mint request over the WS and map the typed response to either a result
+ * or one of the three error classes. The user-facing strings are produced here
+ * (client-side) so they stay stable regardless of Platform wording.
  */
 export declare function requestMint(args: RequestMintArgs): Promise<OidcTokenResult>;
 export interface OidcTokenHandlerDeps {
@@ -45,9 +49,15 @@ export interface OidcTokenHandlerDeps {
             runId: string;
         } | undefined;
     };
-    platformToken: string;
-    platformHttpBase: string;
+    platformClient: MintPlatformClient;
     orchestratorId: string;
+    /** Test-only fault-injection master switch (config.testMode). */
+    testMode: boolean;
+    /**
+     * Test-only: force-defer the *initial* agent mint for any job requesting this
+     * OIDC audience (config.testMintDeferAudience). Ignored unless `testMode`.
+     */
+    testMintDeferAudience?: string;
 }
 /**
  * Build the agent.api handler for `OIDC_TOKEN_REQUEST_METHOD`. Validates the

package/dist/ws/orch-rpc.d.ts

@@ -0,0 +1,9 @@
+/** Platform->orch message types that resolve a pending orch-initiated request. */
+export declare const ORCH_RPC_RESPONSE_TYPES: ReadonlySet<string>;
+export declare class OrchRpcRegistry {
+    private readonly pending;
+    register(requestId: string, timeoutMs: number): Promise<unknown>;
+    resolve(requestId: string, msg: unknown): void;
+    rejectAll(err: Error): void;
+}
+//# sourceMappingURL=orch-rpc.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 DashboardFleetWorkflowsForHostRequest, 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 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 { 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,11 @@ 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;
+    onDashboardAttestationRetry?: (msg: DashboardAttestationRetryRequest) => 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). */
@@ -167,6 +180,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.
  *
@@ -195,6 +227,12 @@ export declare class PlatformClient {
      * `source.register.ack` arrives, or rejected on timeout / disconnect.
      */
     private readonly pendingSourceRegistrations;
+    /**
+     * Generic orchestrator-initiated RPC correlation (e.g. the provenance OIDC
+     * mint). The orchestrator sends a `requestId`-keyed request over the WS and
+     * awaits the Platform's matching `.response`; rejected on timeout or close.
+     */
+    private readonly orchRpc;
     private readonly instanceId?;
     private readonly clusterName?;
     private readonly clusterId?;
@@ -211,12 +249,17 @@ 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 onDashboardAttestationRetry?;
     private readonly onRunRerun?;
     private readonly onManualSchedule?;
     private readonly onRunCancel?;
@@ -297,6 +340,15 @@ export declare class PlatformClient {
      * NOT in the OrchestratorToPlatformMessage union (they are in the separate log pull schema).
      */
     sendRaw(data: unknown): void;
+    /**
+     * Send an orchestrator-initiated request over the Platform WS and await its
+     * typed `.response`. The reverse of the Platform's dashboard-RPC pattern: we
+     * hold the pending map and resolve on the echoed requestId. Rejects on timeout
+     * or connection close; protocol-level errors arrive inside the response body.
+     * The request type is a member of the typed orch->Platform union, so it rides
+     * the validated `send()` path.
+     */
+    sendRequestAndAwait<Res>(type: OrchestratorToPlatformMessage['type'], payload: Record<string, unknown>, timeoutMs?: number): Promise<Res>;
     /**
      * Register a new source at runtime (e.g., after config reload adds a new GitHub app).
      * Separate from the post-auth registration which sends all sources at once.

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

@@ -58,6 +58,8 @@ export interface TestTriggerPayload {
     status: 'accepted' | 'rejected';
     reason?: string;
     jobIds: string[];
+    /** User-visible warnings on acceptance (e.g. skipped non-test bound environments). */
+    warnings?: string[];
 }
 /**
  * Resolve the overlay tarball URL + decryption keys from the upload record, then

package/installer-image-digests.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.1.23",
+  "version": "0.1.24",
   "images": {
-    "kici-agent": "sha256:f3b4628262e2ec10d9f0a5b8eed54a1361e4a917728b38a0165a144d1f885653",
-    "kici-orchestrator": "sha256:240790924ee73e4b1230deb989d3db6c05141ca4db6376baeb88f5e0aeed19ee"
+    "kici-agent": "sha256:1e02f0cda7f398d72b2e95dd74f9c67fb5a8b041307886ef85a6eae3024c7a4e",
+    "kici-orchestrator": "sha256:9aa83c19f39b3f80d62f328af57a38a681670766ed2ec7f46dabecd11e82538b"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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",
@@ -74,6 +71,7 @@
     "dockerode": "^5.0.0",
     "hashi-vault-js": "^0.5.1",
     "hono": "^4.12.25",
+    "jose": "^6.1.0",
     "jsonpath-plus": "^10.4.0",
     "jszip": "^3.10.1",
     "kysely": "^0.29.2",
@@ -86,8 +84,8 @@
     "ws": "^8.21.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@kici-dev/engine": "0.1.23",
-    "@kici-dev/shared": "0.1.23"
+    "@kici-dev/engine": "0.1.25",
+    "@kici-dev/shared": "0.1.25"
   },
   "kici": {
     "metrics": {
@@ -101,7 +99,7 @@
     "@types/archiver": "^8.0.0",
     "@types/dockerode": "^4.0.1",
     "kysely-ctl": "^0.21.0",
-    "@kici-dev/agent": "0.1.23"
+    "@kici-dev/agent": "0.1.25"
   },
   "scripts": {
     "build": "node ../../scripts/build-service.mjs && tsc --emitDeclarationOnly",