@kici-dev/agent 0.5.0 → 0.6.0

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

@@ -29,6 +29,14 @@ export interface OrchestratorClientOptions {
     onJobCancel: (cancel: JobCancel) => void;
     /** Agent authentication token (kat_ prefixed). When provided, sends auth.request before agent.register. */
     token?: string;
+    /**
+     * Self-bootstrap claim code. When set and no static `token` is present, the
+     * client exchanges it for its own ephemeral credentials via
+     * `scaler.claim-credentials` on WS open — before any auth / register — then
+     * adopts the minted token, agentId, and labels. A rejected or expired code
+     * fails permanently (no reconnect). Ignored when a static `token` is present.
+     */
+    scalerClaimCode?: string;
     /** Heartbeat interval in ms. Default: 30000 (30s). */
     heartbeatIntervalMs?: number;
     /** Maximum reconnect delay in ms. Default: 60000 (60s). */
@@ -102,6 +110,8 @@ export declare class OrchestratorClient {
     private readonly pendingEventEmitRequests;
     /** Pending agent.api.request calls awaiting orchestrator response. */
     private readonly pendingApiRequests;
+    /** Pending scaler.claim-credentials requests awaiting orchestrator response. */
+    private readonly pendingClaimCredentialsRequests;
     /** Pending user-cache restore/save requests awaiting orchestrator response. */
     private readonly pendingUserCacheRequests;
     /** Pending user-artifact upload/download requests awaiting orchestrator response. */
@@ -134,12 +144,13 @@ export declare class OrchestratorClient {
     /** Pending concurrency report requests awaiting orchestrator ack. */
     private readonly pendingConcurrencyRequests;
     private readonly url;
-    private readonly agentId;
-    private readonly labels;
+    private agentId;
+    private labels;
     private readonly properties;
     private readonly onJobDispatch;
     private readonly onJobCancel;
-    private readonly token?;
+    private token?;
+    private readonly scalerClaimCode?;
     private readonly heartbeatIntervalMs;
     private readonly maxReconnectDelayMs;
     private readonly getInFlightJobs?;
@@ -158,10 +169,26 @@ export declare class OrchestratorClient {
      * `pendingDispatch` is set by the orchestrator when a queued job has been
      * pre-bound to this agent and the dispatch.job message is in flight. The
      * agent must defer arming the short scaler-idle timer in this case.
+     *
+     * `warmPool` is set when this agent was pre-spawned to wait for work rather
+     * than for a specific queued job. The agent must arm no idle timer at all:
+     * the orchestrator's warm-pool reaper owns its lifetime.
      */
     onRegistered: ((info: {
         pendingDispatch: boolean;
+        warmPool: boolean;
     }) => void) | null;
+    /**
+     * Callback invoked when a self-bootstrap claim exchange fails permanently
+     * (invalid / expired / already-consumed claim code, or the exchange itself
+     * errored or timed out). Only ever fires in self-bootstrap mode
+     * (`scalerClaimCode` set, no static token) — a statically-tokened agent never
+     * runs the claim exchange. A one-shot self-bootstrap agent cannot make any
+     * further progress after this, so server.ts wires it to a non-zero graceful
+     * shutdown; without it the health HTTP server keeps the process alive and a
+     * GitHub Actions run hangs until the job timeout.
+     */
+    onClaimFailedPermanently: ((reason: string) => void) | null;
     constructor(options: OrchestratorClientOptions);
     /** Current connection state. */
     get state(): ConnectionState;
@@ -214,6 +241,7 @@ export declare class OrchestratorClient {
     requestUploadUrl(jobId: string, cacheType: 'source' | 'deps', key: {
         contentHash?: string;
         lockfileHash?: string;
+        depsHash?: string;
         platform: string;
         arch: string;
     }): Promise<string>;
@@ -251,6 +279,24 @@ export declare class OrchestratorClient {
         deliveryId?: string;
         error?: string;
     }>;
+    /**
+     * Send a scaler.claim-credentials WS message and await the response.
+     *
+     * Used by a provisioning workflow (via `ctx.kici.scaler.claimAgentCredentials`)
+     * to exchange a single-use claim code — delivered on a `kici.scaler.scale-up`
+     * event — for freshly minted ephemeral agent credentials. The token rides the
+     * response only; it is never logged. Times out after 15 seconds (matching the
+     * generic agent-API request timeout).
+     */
+    sendClaimCredentials(claimCode: string): Promise<{
+        credentials?: {
+            agentToken: string;
+            agentId: string;
+            orchestratorUrl: string;
+            labels: string[];
+        };
+        error?: string;
+    }>;
     /**
      * Build this agent's fleet mini-bundle and stream it back to the orchestrator
      * as ordered fleet.bundle.chunk frames (the WS frame cap forbids one frame).
@@ -369,6 +415,40 @@ export declare class OrchestratorClient {
     }>;
     getReconnectDelay(): number;
     private doConnect;
+    /**
+     * WS-open handshake driver.
+     *
+     * Self-bootstrap runs first: when a `scalerClaimCode` is set and no static
+     * token is present, the client exchanges the single-use code for its own
+     * ephemeral credentials over `scaler.claim-credentials` — before any auth or
+     * register — and adopts the minted token, agentId, and labels. A rejected or
+     * expired code fails permanently (no reconnect), so a one-shot provisioning
+     * run exits visibly rather than looping.
+     *
+     * Then the normal handshake: with a token (static or just-minted) send
+     * `auth.request` and register after `auth.success`; without one, register
+     * directly (unauthenticated mode).
+     */
+    private onWsOpen;
+    /**
+     * Exchange the single-use claim code for ephemeral credentials, adopting the
+     * minted token / agentId / labels on success. Returns true when credentials
+     * were adopted; false when the claim failed permanently (the connection has
+     * already been torn down with no reconnect).
+     */
+    private performClaimExchange;
+    /**
+     * Merge the claim-minted labels into the agent's own label set, deduped. The
+     * self-reported `kici:os:` / `kici:arch:` / `kici:host:` facts are derived at
+     * register time (`sendAgentRegister`), so they survive regardless.
+     */
+    private mergeClaimedLabels;
+    /**
+     * Fail a self-bootstrap claim permanently, using the same no-reconnect
+     * mechanism as `auth.failure`: mark the auth context dead, suppress reconnect,
+     * and close the socket. A one-shot provisioning run then exits visibly.
+     */
+    private failClaimPermanently;
     /**
      * Resolve a pending user-artifact request from an `artifacts.upload.response`
      * / `artifacts.download.response` WS message, mapping the wire fields onto the
@@ -418,6 +498,18 @@ export declare class OrchestratorClient {
      * Returns true when the message was consumed.
      */
     private handleArtifactReply;
+    /**
+     * Resolve a pending scaler credential-claim request from its response
+     * message. Returns true when it handled the message. Extracted from
+     * handleMessage so that dispatcher stays under the function-length limit.
+     */
+    private handleClaimCredentialsResponse;
+    /**
+     * Complete registration: adopt the orchestrator's negotiated capabilities,
+     * enter the `registered` state, flush everything parked while disconnected,
+     * and hand the ack's lifetime flags to `onRegistered`.
+     */
+    private handleRegisterAck;
     private handleMessage;
     private flushBuffer;
     /** Send the current pending log batch as an agent.log message. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/agent",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Customer-deployable agent for the KiCI CI/CD stack. Connects to an orchestrator, clones the workflow repo, executes steps, and streams logs back.",
   "keywords": [
     "ci",
@@ -55,21 +55,21 @@
     }
   },
   "dependencies": {
-    "@hono/node-server": "^2.0.10",
+    "@hono/node-server": "^2.1.1",
     "archiver": "^8.0.0",
     "dockerode": "^5.0.1",
-    "hono": "^4.12.32",
-    "jose": "^6.1.0",
-    "tar": "^7.5.20",
+    "hono": "^4.13.2",
+    "jose": "^6.2.10",
+    "tar": "^7.5.22",
     "winston": "^3.19.0",
-    "ws": "^8.21.1",
+    "ws": "^8.21.3",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.5.0",
-    "@kici-dev/engine": "0.5.0",
-    "@kici-dev/sdk": "0.5.0",
-    "@kici-dev/shared": "0.5.0"
+    "@kici-dev/engine": "0.6.0",
+    "@kici-dev/sdk": "0.6.0",
+    "@kici-dev/shared": "0.6.0",
+    "@kici-dev/core": "0.6.0"
   },
   "kici": {
     "metrics": {