@kya-os/contracts 1.7.25 → 1.7.26

package/dist/compute.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * Compute Process Contracts
+ *
+ * Schemas for the @kya-os/compute <-> AgentShield API communication.
+ * These define the heartbeat protocol, config bundle format,
+ * and control server status frames.
+ *
+ * @package @kya-os/contracts/compute
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControlStatusSchema = exports.ConfigBundleSchema = exports.HeartbeatResponseSchema = exports.ComputeCommandSchema = exports.UpdateVersionCommandSchema = exports.UpdateConfigCommandSchema = exports.RestartCommandSchema = exports.StopCommandSchema = exports.HeartbeatRequestSchema = void 0;
+const zod_1 = require("zod");
+const agent_deployment_js_1 = require("./agent-deployment.js");
+// ============================================================================
+// Heartbeat Protocol
+// ============================================================================
+/**
+ * Heartbeat request body.
+ * Sent by compute process: POST /api/v1/molti/agents/{did}/heartbeat
+ * Auth: X-Heartbeat-Token header
+ */
+exports.HeartbeatRequestSchema = zod_1.z.object({
+    /** Agent DID this heartbeat is for */
+    agentDid: agent_deployment_js_1.DidStringSchema,
+    /** Current compute process status */
+    status: zod_1.z.enum(["starting", "running", "error", "stopping"]),
+    /** @kya-os/compute package version (from package.json) */
+    computeVersion: zod_1.z.string().min(1).max(50),
+    /** Installed OpenClaw version (from npm ls) */
+    openclawVersion: zod_1.z.string().max(50).optional(),
+    /** Fly machine ID (from FLY_MACHINE_ID env var) */
+    machineId: zod_1.z.string().max(255).optional(),
+    /** Seconds since compute process started */
+    uptimeSeconds: zod_1.z.number().nonnegative().optional(),
+    /** Current RSS memory in MB */
+    memoryMb: zod_1.z.number().nonnegative().optional(),
+});
+// ============================================================================
+// Compute Commands (Discriminated Union)
+// ============================================================================
+/**
+ * Stop command — graceful shutdown, no payload accepted.
+ */
+exports.StopCommandSchema = zod_1.z
+    .object({
+    type: zod_1.z.literal("stop"),
+})
+    .strict();
+/**
+ * Restart command — restart the compute process, no payload accepted.
+ */
+exports.RestartCommandSchema = zod_1.z
+    .object({
+    type: zod_1.z.literal("restart"),
+})
+    .strict();
+/**
+ * Update config command — triggers config re-fetch, no payload accepted.
+ */
+exports.UpdateConfigCommandSchema = zod_1.z
+    .object({
+    type: zod_1.z.literal("update_config"),
+})
+    .strict();
+/**
+ * Update version command — requires target version in payload.
+ */
+exports.UpdateVersionCommandSchema = zod_1.z
+    .object({
+    type: zod_1.z.literal("update_version"),
+    payload: zod_1.z.object({
+        /** Target OpenClaw version to install */
+        version: zod_1.z.string().min(1).max(50),
+    }),
+})
+    .strict();
+/**
+ * Command that Agent Shield can send to the compute process
+ * via the heartbeat response.
+ *
+ * Discriminated union by `type` field:
+ * - `stop` / `restart` / `update_config` — no payload
+ * - `update_version` — requires `{ version: string }` payload
+ */
+exports.ComputeCommandSchema = zod_1.z.discriminatedUnion("type", [
+    exports.StopCommandSchema,
+    exports.RestartCommandSchema,
+    exports.UpdateConfigCommandSchema,
+    exports.UpdateVersionCommandSchema,
+]);
+/**
+ * Heartbeat response from Agent Shield.
+ * Returned by: POST /api/v1/molti/agents/{did}/heartbeat
+ */
+exports.HeartbeatResponseSchema = zod_1.z.object({
+    /** Always true for successful heartbeats */
+    ack: zod_1.z.literal(true),
+    /** Pending commands for the compute process to execute */
+    commands: zod_1.z.array(exports.ComputeCommandSchema).default([]),
+    /** ISO timestamp of last config change (compute compares to detect updates) */
+    configUpdatedAt: zod_1.z.string().datetime().optional(),
+});
+// ============================================================================
+// Config Bundle
+// ============================================================================
+/**
+ * Config bundle returned by Agent Shield to the compute process.
+ * Fetched on boot: GET /api/v1/molti/deployments/{did}/config-bundle
+ * Auth: X-Heartbeat-Token header (for managed) or X-API-Key (for BYOK)
+ *
+ * IMPORTANT: This extends the existing config-bundle endpoint.
+ * BYOK deployments continue to use the existing shape (version 1).
+ * Managed deployments use this shape (version 2+).
+ *
+ * **Private Key Delivery**: The agent's private key is NOT included in the config bundle.
+ * It is delivered as the `AGENT_PRIVATE_KEY` environment variable at Fly machine creation
+ * time and persists in the machine's env. This avoids transmitting the key on every
+ * config fetch and keeps it out of the config-bundle response surface.
+ */
+exports.ConfigBundleSchema = zod_1.z.object({
+    /** Schema version — 2 for managed bundles */
+    version: zod_1.z.number().int().positive(),
+    /** Kill switch — if true, compute must exit immediately */
+    killed: zod_1.z.boolean(),
+    /** Target OpenClaw version to install */
+    openclawVersion: zod_1.z.string().min(1).max(50),
+    /** Agent personality/system prompt file contents (max 100KB) */
+    soulFile: zod_1.z.string().max(100000).nullable(),
+    /** Gateway auth token for OpenClaw */
+    gatewayToken: zod_1.z.string().min(1).max(500),
+    /** Channel configurations */
+    channels: zod_1.z.object({
+        telegram: zod_1.z
+            .object({
+            enabled: zod_1.z.boolean(),
+            token: zod_1.z.string().optional(),
+        })
+            .optional(),
+        discord: zod_1.z
+            .object({
+            enabled: zod_1.z.boolean(),
+            token: zod_1.z.string().optional(),
+        })
+            .optional(),
+        slack: zod_1.z
+            .object({
+            enabled: zod_1.z.boolean(),
+            token: zod_1.z.string().optional(),
+            appToken: zod_1.z.string().optional(),
+        })
+            .optional(),
+    }),
+    /** AI provider configuration — key is decrypted, sent over TLS */
+    aiProvider: zod_1.z.object({
+        type: zod_1.z.enum(["anthropic", "openai"]),
+        apiKey: zod_1.z.string().min(1).max(500),
+    }),
+    /** ISO timestamp of last config modification */
+    updatedAt: zod_1.z.string().datetime(),
+});
+// ============================================================================
+// Control Server (WebSocket :18790)
+// ============================================================================
+/**
+ * Status frame pushed from compute control server to dashboard.
+ * Sent on connect + every 5 seconds.
+ */
+exports.ControlStatusSchema = zod_1.z.object({
+    /** Whether the agent runtime is healthy */
+    healthy: zod_1.z.boolean(),
+    /** Seconds since compute process started */
+    uptimeSeconds: zod_1.z.number().nonnegative(),
+    /** Installed OpenClaw version */
+    openclawVersion: zod_1.z.string().min(1).max(50),
+    /** @kya-os/compute version */
+    computeVersion: zod_1.z.string().min(1).max(50),
+    /** Number of active WS connections to control server */
+    activeConnections: zod_1.z.number().int().nonnegative(),
+    /** Current RSS memory in MB */
+    memoryMb: zod_1.z.number().nonnegative(),
+    /** CPU usage percentage (0-100) */
+    cpuPercent: zod_1.z.number().nonnegative().max(100),
+});