@kici-dev/agent 0.1.27 → 0.2.0

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

@@ -1,5 +1,14 @@
 import { type AgentToOrchestratorMessage, type JobDispatch, type JobCancel, type FleetLogsRequest } from '@kici-dev/engine';
-import type { CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from '../execution/sandbox/index.js';
+import type { CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ArtifactRequestIpc, ArtifactResponseIpc, ProvenanceResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from '../execution/sandbox/index.js';
+/**
+ * How many times an in-flight `artifacts.upload.complete` is re-sent across
+ * reconnects before the step is failed.
+ *
+ * Bounded so a flapping connection cannot loop forever. The overall wait is
+ * bounded independently by ARTIFACT_COMPLETE_ACK_TIMEOUT_MS, whose timer is
+ * never restarted across a hold or a resend.
+ */
+export declare const MAX_COMPLETE_RESEND_ATTEMPTS = 2;
 export type ConnectionState = 'disconnected' | 'connecting' | 'authenticating' | 'registering' | 'registered';
 export interface OrchestratorClientOptions {
     /** WebSocket URL of the orchestrator. */
@@ -76,6 +85,13 @@ export declare class OrchestratorClient {
     private reconnectTimer;
     private reconnectAttempts;
     private intentionalDisconnect;
+    /**
+     * Agent-facing capabilities advertised by the orchestrator on `register.ack`.
+     * Undefined until the first ack arrives, and on a pre-capability orchestrator
+     * that never advertises — both cases mean "assume unsupported" for every
+     * optional feature gated on it.
+     */
+    private orchCapabilities;
     private pendingLogBatch;
     private logFlushTimer;
     private static readonly LOG_BATCH_SIZE;
@@ -88,6 +104,26 @@ export declare class OrchestratorClient {
     private readonly pendingApiRequests;
     /** Pending user-cache restore/save requests awaiting orchestrator response. */
     private readonly pendingUserCacheRequests;
+    /** Pending user-artifact upload/download requests awaiting orchestrator response. */
+    private readonly pendingUserArtifactRequests;
+    /**
+     * In-flight `artifacts.upload.complete` frames that are safe to re-send after a
+     * reconnect, keyed by their current `messageId`.
+     *
+     * The commit is idempotent server-side (the storage key is derived server-side,
+     * `initMeta` is a re-writable sidecar, and the DB insert is
+     * `onConflict.doNothing()`), so a dropped ack means "we did not hear the
+     * answer", not "it did not happen". `beginUpload` / `download` are deliberately
+     * absent: `beginUpload` mints a presigned PUT and is not idempotent the same
+     * way, and `download` is read-only and cheap to fail.
+     */
+    private readonly resendableCompletes;
+    /**
+     * Completes taken off `pendingUserArtifactRequests` by the disconnect sweep and
+     * parked until the next `register.ack` re-sends them. Their ack timers keep
+     * running — parking does not extend the deadline.
+     */
+    private readonly heldCompletes;
     /**
      * Pending step-approval requests awaiting the orchestrator's resolution.
      * No client-side timeout: the orchestrator owns the (org-/SDK-configured)
@@ -243,6 +279,25 @@ export declare class OrchestratorClient {
      * Times out after 30 seconds for the round-trip ops.
      */
     requestUserCache(jobId: string, request: CacheRequestIpc): Promise<CacheResponseIpc>;
+    /**
+     * Relay a user-facing artifact request from the sandbox to the orchestrator.
+     *
+     * Translates the sandbox `artifacts.request` IPC into the matching
+     * `artifacts.*` WS message and resolves with the orchestrator's response
+     * mapped onto the IPC response shape:
+     *
+     * - `beginUpload` -> `artifacts.upload.request`, awaits `artifacts.upload.response`.
+     * - `completeUpload` -> `artifacts.upload.complete`, awaits
+     *   `artifacts.upload.complete.ack` when the orchestrator advertises the
+     *   `artifactCompleteAck` capability, and rejects when the commit failed so
+     *   the workflow step fails instead of losing the artifact behind a green run.
+     *   Against an orchestrator that never advertises it, the message stays
+     *   fire-and-forget and resolves immediately.
+     * - `download` -> `artifacts.download.request`, awaits `artifacts.download.response`.
+     *
+     * Times out after 30 seconds for the round-trip ops.
+     */
+    requestUserArtifact(jobId: string, request: ArtifactRequestIpc): Promise<ArtifactResponseIpc>;
     /**
      * Relay a provenance bundle upload operation to the orchestrator. Maps the
      * IPC `provenance.request` onto `requestProvenanceUploadUrl` (returns the
@@ -314,6 +369,55 @@ export declare class OrchestratorClient {
     }>;
     getReconnectDelay(): number;
     private doConnect;
+    /**
+     * Resolve a pending user-artifact request from an `artifacts.upload.response`
+     * / `artifacts.download.response` WS message, mapping the wire fields onto the
+     * IPC response shape. No-op when no request is pending for the requestId.
+     */
+    private resolveArtifactResponse;
+    /**
+     * Resolve or reject a pending completeUpload from an
+     * `artifacts.upload.complete.ack`. `committed` resolves the relayed IPC
+     * request; `failed` rejects it (carrying the orchestrator's reason), which
+     * propagates through the relay's `response.error` and fails the workflow step
+     * rather than losing the artifact silently. No-op when nothing is pending for
+     * the requestId (an ack for an already-timed-out complete).
+     */
+    private resolveArtifactCompleteAck;
+    /**
+     * Drop every trace of an in-flight upload-complete, whichever key it currently
+     * lives under and whether or not it is parked awaiting a resend.
+     *
+     * Called from the ack timer, which fires on the original schedule regardless of
+     * how many times the complete has been re-keyed since.
+     */
+    private forgetComplete;
+    /**
+     * Fail every parked upload-complete closed, for the paths where the reconnect
+     * the park was betting on will never arrive (a deliberate shutdown, a
+     * permanently rejected token). Naming the ambiguity keeps the operator from
+     * hunting for an artifact that in fact landed.
+     */
+    private rejectHeldCompletes;
+    /**
+     * Re-send every upload-complete parked by the disconnect sweep.
+     *
+     * Called from `register.ack`, once the new connection's capabilities are known.
+     * Each frame is re-keyed with a fresh `messageId` before it goes out: the id is
+     * the correlation key, so reusing it would let a late ack for the pre-disconnect
+     * send resolve the new pending.
+     *
+     * The ack timer created when the complete was first sent is deliberately left
+     * alone, so the hold plus every resend stays inside the original
+     * ARTIFACT_COMPLETE_ACK_TIMEOUT_MS budget.
+     */
+    private resendHeldCompletes;
+    /**
+     * Route the orchestrator's replies to a relayed user-artifact request, which
+     * are dispatched off the raw frame rather than the parsed protocol union.
+     * Returns true when the message was consumed.
+     */
+    private handleArtifactReply;
     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.1.27",
+  "version": "0.2.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",
@@ -49,25 +49,27 @@
     "entries": {
       "server.js": "src/server.ts",
       "workflow-runner.js": "src/execution/sandbox/workflow-runner.ts",
+      "workflow-runner-bundle.js": "src/execution/sandbox/workflow-runner.ts",
+      "container-ts-loader-hook.js": "src/execution/sandbox/container-ts-loader-hook.ts",
       "index.js": "src/index.ts"
     }
   },
   "dependencies": {
-    "@hono/node-server": "^1.19.14",
+    "@hono/node-server": "^2.0.10",
     "archiver": "^8.0.0",
-    "dockerode": "^5.0.0",
-    "hono": "^4.12.25",
+    "dockerode": "^5.0.1",
+    "hono": "^4.12.32",
     "jose": "^6.1.0",
-    "tar": "^7.5.16",
+    "tar": "^7.5.20",
     "winston": "^3.19.0",
-    "ws": "^8.21.0",
+    "ws": "^8.21.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.27",
-    "@kici-dev/engine": "0.1.27",
-    "@kici-dev/sdk": "0.1.27",
-    "@kici-dev/shared": "0.1.27"
+    "@kici-dev/core": "0.2.0",
+    "@kici-dev/engine": "0.2.0",
+    "@kici-dev/shared": "0.2.0",
+    "@kici-dev/sdk": "0.2.0"
   },
   "kici": {
     "metrics": {
@@ -80,8 +82,8 @@
     "@types/dockerode": "^4.0.1"
   },
   "scripts": {
-    "build": "node ../../scripts/build-service.mjs && tsc --emitDeclarationOnly",
-    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/build-service.mjs && tsgo --emitDeclarationOnly",
+    "typecheck": "tsgo --noEmit",
     "test": "vitest run"
   }
 }