@kici-dev/agent 0.0.0 → 0.1.2

package/dist/ws/event-buffer.d.ts

@@ -0,0 +1,16 @@
+import type { AgentToOrchestratorMessage } from '@kici-dev/engine';
+import { RingBuffer } from '@kici-dev/shared';
+/**
+ * In-memory buffer for agent-to-orchestrator messages during disconnection.
+ *
+ * Wraps the generic RingBuffer from @kici-dev/shared with the agent's
+ * message type and a default maxSize of 5,000. When the agent loses its
+ * WebSocket connection to the orchestrator, outgoing messages are buffered
+ * here and flushed in order on reconnection.
+ */
+export declare class EventBuffer extends RingBuffer<AgentToOrchestratorMessage> {
+    constructor(options?: {
+        maxSize?: number;
+    });
+}
+//# sourceMappingURL=event-buffer.d.ts.map

package/dist/ws/log-buffer.d.ts

@@ -0,0 +1,15 @@
+import { RingBuffer } from '@kici-dev/shared';
+/**
+ * Ring buffer for agent log lines during WS disconnection.
+ *
+ * Wraps the generic RingBuffer from @kici-dev/shared with string type
+ * and a default capacity of 10,000 lines. When the agent loses its
+ * WebSocket connection, operational log lines are buffered here and
+ * replayed on reconnection.
+ */
+export declare class LogBuffer extends RingBuffer<string> {
+    constructor(options?: {
+        maxLines?: number;
+    });
+}
+//# sourceMappingURL=log-buffer.d.ts.map

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

@@ -0,0 +1,269 @@
+import { type AgentToOrchestratorMessage, type JobDispatch, type JobCancel } from '@kici-dev/engine';
+export type ConnectionState = 'disconnected' | 'connecting' | 'authenticating' | 'registering' | 'registered';
+interface OrchestratorClientOptions {
+    /** WebSocket URL of the orchestrator. */
+    url: string;
+    /** Agent's unique identifier. */
+    agentId: string;
+    /** Agent's label set for job routing. */
+    labels: string[];
+    /** Callback invoked when a job.dispatch message is received. */
+    onJobDispatch: (dispatch: JobDispatch) => void;
+    /** Callback invoked when a job.cancel message is received. */
+    onJobCancel: (cancel: JobCancel) => void;
+    /** Agent authentication token (kat_ prefixed). When provided, sends auth.request before agent.register. */
+    token?: string;
+    /** Heartbeat interval in ms. Default: 30000 (30s). */
+    heartbeatIntervalMs?: number;
+    /** Maximum reconnect delay in ms. Default: 60000 (60s). */
+    maxReconnectDelayMs?: number;
+    /** Maximum event buffer size. Default: 5000. */
+    maxBufferSize?: number;
+    /** Maximum log buffer lines for agent.log during disconnection. Default: 10000. */
+    maxLogBufferLines?: number;
+    /** Callback to retrieve in-flight jobs for reconnection reporting. */
+    getInFlightJobs?: () => Array<{
+        jobId: string;
+        runId: string;
+    }>;
+    /** Agent roles. undefined = all, [] = execution only. Used to derive kici:role:* auto-labels. */
+    roles?: string[];
+    /**
+     * Whether the agent was spawned by the orchestrator's auto-scaler.
+     * Mirrors KICI_SCALER_MANAGED=1 from config; passed in so the client
+     * doesn't have to read process.env directly.
+     */
+    scalerManaged?: boolean;
+}
+/**
+ * WebSocket client that connects the agent to the customer orchestrator.
+ *
+ * Handles:
+ * - Registration handshake (sends agent.register on connect)
+ * - Periodic heartbeat messages to keep the connection alive
+ * - Auto-reconnect with exponential backoff (1s initial, 1.5x, jitter, 60s max)
+ * - Job dispatch and cancel message routing to callbacks
+ * - Event buffering during disconnection with flush on reconnect
+ *
+ * Mirrors the proven PlatformClient pattern from packages/orchestrator but adapted
+ * for the agent-to-orchestrator protocol direction.
+ */
+export declare class OrchestratorClient {
+    private ws;
+    private _state;
+    private readonly eventBuffer;
+    private readonly logBuffer;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private intentionalDisconnect;
+    private pendingLogBatch;
+    private logFlushTimer;
+    private static readonly LOG_BATCH_SIZE;
+    private static readonly LOG_FLUSH_INTERVAL_MS;
+    /** Pending upload URL requests awaiting orchestrator response. */
+    private readonly pendingUploadRequests;
+    /** Pending event.emit requests awaiting orchestrator response. */
+    private readonly pendingEventEmitRequests;
+    /** Pending agent.api.request calls awaiting orchestrator response. */
+    private readonly pendingApiRequests;
+    /** Pending concurrency report requests awaiting orchestrator ack. */
+    private readonly pendingConcurrencyRequests;
+    private readonly url;
+    private readonly agentId;
+    private readonly labels;
+    private readonly onJobDispatch;
+    private readonly onJobCancel;
+    private readonly token?;
+    private readonly heartbeatIntervalMs;
+    private readonly maxReconnectDelayMs;
+    private readonly getInFlightJobs?;
+    private readonly roles;
+    private readonly scalerManaged;
+    /** Timestamp when the connection was lost, used for gap marker outage duration. */
+    private disconnectedAt;
+    /** Set to true when auth.failure is received. Prevents retrying with a bad token. */
+    private authFailed;
+    /**
+     * Callback invoked when the client transitions to the 'registered' state.
+     * Fires on both initial registration and re-registration after reconnection.
+     * Used by server.ts to re-evaluate idle shutdown after reconnection.
+     *
+     * `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.
+     */
+    onRegistered: ((info: {
+        pendingDispatch: boolean;
+    }) => void) | null;
+    constructor(options: OrchestratorClientOptions);
+    /** Current connection state. */
+    get state(): ConnectionState;
+    /** Number of messages currently buffered. */
+    getBufferedCount(): number;
+    /**
+     * Get the underlying WebSocket's bufferedAmount (bytes pending in the send queue).
+     * Used by LogStreamer for backpressure detection.
+     */
+    getBufferedAmount(): number;
+    /**
+     * Register a one-time callback for the WebSocket 'drain' event.
+     * Fires when the send buffer has been flushed to the kernel.
+     * Used by LogStreamer to resume sending after backpressure.
+     */
+    onDrain(callback: () => void): void;
+    /**
+     * Initiate connection to the orchestrator.
+     * Starts the connect -> register -> registered lifecycle.
+     */
+    connect(): void;
+    /**
+     * Gracefully disconnect from the orchestrator. Does not trigger reconnection.
+     */
+    disconnect(): void;
+    /**
+     * Send a message to the orchestrator. If registered, sends immediately.
+     * If not registered, buffers the message for later delivery.
+     */
+    send(message: AgentToOrchestratorMessage): void;
+    /**
+     * Send a message directly on the WebSocket without buffering.
+     * Used for heartbeat and other protocol messages that must not be buffered.
+     */
+    sendDirect(message: AgentToOrchestratorMessage): void;
+    /**
+     * Stream a log line to the orchestrator via agent.log messages.
+     *
+     * If connected and registered, lines are batched (up to 50 lines or 100ms)
+     * and sent as agent.log messages. If disconnected, lines are buffered in the
+     * LogBuffer for replay on reconnection.
+     */
+    streamLog(line: string): void;
+    /**
+     * Request a pre-signed S3 upload URL from the orchestrator.
+     *
+     * Sends a cache.upload.request WS message and waits for a cache.upload.response.
+     * Times out after 30 seconds.
+     */
+    requestUploadUrl(jobId: string, cacheType: 'source' | 'deps', key: {
+        contentHash?: string;
+        lockfileHash?: string;
+        platform: string;
+        arch: string;
+    }): Promise<string>;
+    /**
+     * Notify orchestrator that an S3 upload completed successfully.
+     *
+     * The orchestrator uses this to initialize metadata on the S3 object.
+     */
+    sendUploadComplete(jobId: string, cacheType: 'source' | 'deps', key: {
+        contentHash?: string;
+        lockfileHash?: string;
+        platform: string;
+        arch: string;
+        depsHash?: string;
+    }): void;
+    /**
+     * Send an event.emit WS message to the orchestrator and await the response.
+     *
+     * Used by the job runner to relay custom event emissions from the sandbox
+     * (ctx.emit()) to the orchestrator for persistence and routing.
+     * Times out after 5 seconds (matching the sandbox-side timeout).
+     */
+    sendEventEmit(jobId: string, requestId: string, eventName: string, payload: Record<string, unknown>, target?: {
+        repos?: string[];
+    }): Promise<{
+        requestId: string;
+        deliveryId?: string;
+        error?: string;
+    }>;
+    /**
+     * Send a typed API request to the orchestrator and await the response.
+     *
+     * This is the transport layer for the agent private API. The SDK's typed
+     * KiciApi interface calls this with dot-namespaced method names.
+     */
+    sendApiRequest(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Send a job.context message to the orchestrator.
+     *
+     * Conveys execution environment details (runtime, sandbox type, env vars)
+     * for the Summary tab. The orchestrator enriches with orgId before forwarding to Platform.
+     */
+    sendJobContext(runId: string, jobId: string, context: {
+        envVars?: Array<{
+            name: string;
+            value: string;
+            category: 'system' | 'user' | 'inherited' | 'secret';
+        }>;
+        runtime?: {
+            nodeVersion?: string;
+            os?: string;
+            arch?: string;
+        };
+        sandboxType?: string;
+        labels?: string[];
+        workingDirectory?: string;
+        gitRef?: string;
+    }): void;
+    /**
+     * Send a run.event message to the orchestrator.
+     *
+     * Emits infrastructure lifecycle events (clone, execution, teardown).
+     * The orchestrator enriches with orgId before forwarding to Platform.
+     */
+    sendRunEvent(runId: string, eventType: string, opts?: {
+        jobId?: string;
+        metadata?: Record<string, unknown>;
+        durationMs?: number;
+    }): void;
+    /**
+     * Send a job.concurrency.report WS message and wait for job.concurrency.ack.
+     *
+     * The orchestrator evaluates the concurrency group and responds with an action:
+     * - proceed: continue with execution
+     * - wait: release the agent slot, orchestrator will re-dispatch later
+     * - cancel: cancel the job (superseded by newer run)
+     *
+     * Times out after 30 seconds.
+     */
+    sendConcurrencyReport(runId: string, jobId: string, group: string): Promise<{
+        action: 'proceed' | 'wait' | 'cancel';
+        reason?: string;
+    }>;
+    getReconnectDelay(): number;
+    private doConnect;
+    private handleMessage;
+    private flushBuffer;
+    /** Send the current pending log batch as an agent.log message. */
+    private sendLogBatch;
+    /** Send an agent.log message directly on the WebSocket. */
+    private sendAgentLogMessage;
+    /**
+     * Drain pending log batch into the LogBuffer.
+     * Called on disconnect to preserve pending lines for replay on reconnect.
+     */
+    private drainPendingLogBatch;
+    /**
+     * Block MMDS access via iptables.
+     * Called in Firecracker/scaler-managed mode after receiving config via register.ack.
+     * This prevents the agent (and any user code) from accessing MMDS metadata.
+     */
+    private blockMmdsAccess;
+    /**
+     * Send config.ack to orchestrator to confirm receipt of registration config.
+     * This signals the orchestrator to clear MMDS data for Firecracker agents.
+     */
+    private sendConfigAck;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /**
+     * Send agent.register message on the WebSocket.
+     * Extracted to avoid duplication between authenticated and unauthenticated flows.
+     */
+    private sendAgentRegister;
+    private scheduleReconnect;
+    private cancelReconnect;
+}
+export {};
+//# sourceMappingURL=orchestrator-client.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/agent",
-  "version": "0.0.0",
+  "version": "0.1.2",
   "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": [
     "kici",
@@ -9,17 +9,69 @@
     "ci-cd",
     "typescript",
     "workflows",
-    "devops"
+    "devops",
+    "agent",
+    "runner"
   ],
   "homepage": "https://kici.dev",
   "author": {
     "name": "KiCI",
     "email": "hello@kici.dev"
   },
-  "license": "Apache-2.0",
-  "main": "index.js",
+  "license": "AGPL-3.0-only",
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "sbom.spdx.json"
+  ],
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "build": {
+    "entries": {
+      "server.js": "src/server.ts",
+      "workflow-runner.js": "src/execution/sandbox/workflow-runner.ts",
+      "index.js": "src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.0.0",
+    "dockerode": "^5.0.0",
+    "hono": "^4.12.18",
+    "tar": "^7.5.13",
+    "winston": "^3.19.0",
+    "ws": "^8.20.0",
+    "zod": "^4.3.6",
+    "zx": "^8.8.5",
+    "@kici-dev/engine": "0.1.2",
+    "@kici-dev/sdk": "0.1.2",
+    "@kici-dev/shared": "0.1.2"
+  },
+  "kici": {
+    "metrics": {
+      "mode": "push",
+      "jobName": "kici-agent"
+    }
+  },
+  "devDependencies": {
+    "@types/dockerode": "^4.0.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-service.mjs && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}