@kici-dev/engine 0.0.0 → 0.1.0

package/dist/protocol/messages/peer.js

@@ -0,0 +1,372 @@
+import "../../chunk-gOLHoazu.js";
+import { ExecutionJobStatus } from "./execution-status.js";
+import { z } from "zod";
+//#region src/protocol/messages/peer.ts
+/** Agent summary included in peer heartbeat and auth response messages. */
+const peerAgentSummarySchema = z.object({
+	agentId: z.string(),
+	labels: z.array(z.string()),
+	activeJobs: z.number(),
+	maxConcurrency: z.number(),
+	platform: z.string(),
+	arch: z.string(),
+	/**
+	* Kubernetes-taint-style mandatory labels inherited from the spawning
+	* scaler (empty / omitted for static agents and warm-pool replenishment
+	* spawns). Cross-peer routing applies the same gate the local label
+	* matcher does: a connected-agent entry only matches when every
+	* mandatory label appears in the required label set.
+	*
+	* Optional + default `[]` for legacy peers — older orchestrators that
+	* predate the gate omit the field, and the coordinator falls back to
+	* "no gate" routing for those agents (matching pre-gate behavior).
+	*/
+	mandatoryLabels: z.array(z.string()).optional().default([])
+});
+/** Peer capabilities advertised during heartbeat and auth response. */
+const peerCapabilitiesSchema = z.object({
+	s3LogAccess: z.boolean(),
+	logRoutingOverride: z.enum(["direct", "coordinator"]).optional()
+});
+/** Scaler capacity summary included in peer heartbeat and auth response for routing decisions. */
+const scalerCapacitySummarySchema = z.object({
+	/** Scaler backend name (e.g. "stg-worker-bare-metal") */
+	name: z.string().optional(),
+	/** Scaler backend type (e.g. "bare-metal", "container") */
+	type: z.string().optional(),
+	/** Label sets this scaler backend can provision */
+	labelSets: z.array(z.array(z.string())),
+	/** Maximum agents for this backend */
+	maxAgents: z.number(),
+	/** Current active count for this backend */
+	activeCount: z.number(),
+	/**
+	* Labels a job MUST declare in `runsOn` to be allowed on this backend
+	* (Kubernetes-taint-style opt-in gate). When omitted (legacy peer) or
+	* empty the backend has no gate. Cross-peer routing applies the same
+	* rule as the local label matcher: a scaler-capacity entry only
+	* matches when every mandatory label appears in the required label set.
+	*/
+	mandatoryLabels: z.array(z.string()).optional().default([])
+});
+/** Peer hello: initiator sends ephemeral X25519 public key and nonce. */
+const peerHelloSchema = z.object({
+	type: z.literal("peer.hello"),
+	/** Base64-encoded X25519 DER SPKI ephemeral public key. */
+	ephemeralPublicKey: z.string(),
+	/** Base64-encoded 32-byte random nonce (HKDF salt). */
+	nonce: z.string()
+});
+/** Peer hello response: responder sends their ephemeral X25519 public key. */
+const peerHelloResponseSchema = z.object({
+	type: z.literal("peer.hello.response"),
+	/** Base64-encoded X25519 DER SPKI ephemeral public key. */
+	ephemeralPublicKey: z.string()
+});
+/** Peer auth request sent after ECDH handshake (encrypted channel established). */
+const peerAuthRequestSchema = z.object({
+	type: z.literal("peer.auth.request"),
+	instanceId: z.string(),
+	/** Join token (first connection via token-based auth). */
+	token: z.string().optional(),
+	/** HMAC proof of credential ownership (reconnection). */
+	proof: z.string().optional(),
+	protocolVersion: z.number(),
+	/** Software version of the connecting peer (for version compat check). */
+	softwareVersion: z.string().optional(),
+	/** Role of the connecting peer. */
+	role: z.enum(["coordinator", "worker"]).optional()
+});
+/** Peer auth response indicating whether the connection was accepted. */
+const peerAuthResponseSchema = z.object({
+	type: z.literal("peer.auth.response"),
+	accepted: z.boolean(),
+	instanceId: z.string().optional(),
+	reason: z.string().optional(),
+	/** Session credential issued on first join (worker stores for reconnection). */
+	sessionCredential: z.string().optional(),
+	/** Assigned role echoed back to the connecting peer. */
+	role: z.string().optional(),
+	/** Software version of the coordinator (for version compat check). */
+	softwareVersion: z.string().optional(),
+	agents: z.array(peerAgentSummarySchema).optional(),
+	scalerCapacity: z.array(scalerCapacitySummarySchema).optional(),
+	capabilities: peerCapabilitiesSchema.optional()
+});
+/** Periodic heartbeat from one orchestrator to its peers. */
+const peerHeartbeatSchema = z.object({
+	type: z.literal("peer.heartbeat"),
+	instanceId: z.string(),
+	term: z.number(),
+	leaderId: z.string().nullable(),
+	draining: z.boolean(),
+	agents: z.array(peerAgentSummarySchema),
+	capabilities: peerCapabilitiesSchema,
+	/** Optional scaler capacity data for on-demand backends (backward compatible). */
+	scalerCapacity: z.array(scalerCapacitySummarySchema).optional(),
+	/** Shared config version for cross-orchestrator config sync (backward compatible). */
+	configVersion: z.number().optional(),
+	/** Registry version for cross-orchestrator registration sync (backward compatible). */
+	registryVersion: z.number().optional(),
+	timestamp: z.number(),
+	hostname: z.string().optional(),
+	osRelease: z.string().optional(),
+	totalMemoryMb: z.number().optional(),
+	memoryUsedMb: z.number().optional(),
+	memoryAvailableMb: z.number().optional(),
+	cpuCount: z.number().optional(),
+	uptimeSeconds: z.number().optional(),
+	nodeVersion: z.string().optional(),
+	runningAsUser: z.string().nullable().optional(),
+	runningAsUid: z.number().nullable().optional(),
+	version: z.string().optional()
+});
+/** Request to reroute a job to another orchestrator (no local agent can handle it). */
+const jobRerouteSchema = z.object({
+	type: z.literal("job.reroute"),
+	messageId: z.string(),
+	/**
+	* Pre-allocated job identifier. The sending coordinator MUST allocate
+	* the jobId before sending so it can register the execution_runs +
+	* execution_jobs rows under that id in its own DB. Receiving peer
+	* (worker or coord) MUST use this exact id when dispatching to its
+	* agent — without that, the agent's later `job.status`/`step.status`
+	* messages reference a jobId the owning coord never wrote to the DB,
+	* and the run silently stalls at `running`.
+	*/
+	jobId: z.string(),
+	runId: z.string(),
+	deliveryId: z.string(),
+	routingKey: z.string(),
+	event: z.string(),
+	action: z.string().nullable(),
+	payload: z.record(z.string(), z.unknown()),
+	jobName: z.string(),
+	workflowName: z.string(),
+	runsOnLabels: z.array(z.array(z.string())),
+	/** Labels that the dispatched agent must NOT have (optional for backward compatibility). */
+	excludeLabels: z.array(z.string()).optional(),
+	triedConnections: z.array(z.string()),
+	maxHops: z.number(),
+	coordinatorId: z.string(),
+	requestId: z.string().optional(),
+	traceId: z.string().optional(),
+	/** Resolved job configuration (steps, rules, matrix, etc.) for the receiving orch to dispatch. */
+	jobConfig: z.record(z.string(), z.unknown()).optional(),
+	/** Clone URL for the repository. */
+	repoUrl: z.string().optional(),
+	/** Git ref (branch name). */
+	ref: z.string().optional(),
+	/** Commit SHA. */
+	sha: z.string().optional(),
+	/** Provider type (e.g. 'github'). */
+	provider: z.string().optional(),
+	/** Provider-specific context (e.g. { installationId }). */
+	providerContext: z.record(z.string(), z.unknown()).optional(),
+	/** Pre-signed source tarball download URL (cache hit). */
+	sourceTarUrl: z.string().optional(),
+	/** SHA-256 hash of the source tarball bytes for integrity verification. */
+	sourceTarHash: z.string().optional(),
+	/** Pre-signed dependency tarball download URL (cache hit). */
+	depsUrl: z.string().optional(),
+	/** Dependency tarball hash for cache keying. */
+	depsHash: z.string().optional(),
+	/** Pre-resolved clone token for workers without provider credentials. */
+	cloneToken: z.string().optional(),
+	/** Encrypted secrets envelope (AES-256-GCM with session key). */
+	encryptedSecrets: z.string().optional(),
+	/** Encrypted namespaced secrets envelope. */
+	encryptedNamespacedSecrets: z.string().optional()
+});
+/** Acknowledgment of a job reroute request. */
+const jobRerouteAckSchema = z.object({
+	type: z.literal("job.reroute.ack"),
+	messageId: z.string(),
+	accepted: z.boolean(),
+	reason: z.string().optional()
+});
+/**
+* Job or step progress update forwarded from a worker peer to its owning
+* coordinator (the coord that has the run rows in its DB).
+*
+* `kind` is the discriminator the coord uses to decide which downstream
+* call to make:
+*  - kind='job'  → ExecutionTracker.onJobStatus, which is what drives the
+*                  run-level state machine (running → success/failed/...).
+*                  `stepIndex`/`stepName` are unused for this kind.
+*  - kind='step' → ExecutionTracker.onStepStatus, which only persists step
+*                  rows. `stepIndex`/`stepName` MUST point at the step.
+*
+* Without the discriminator, the coord conflated the two and silently
+* dropped every job-level event into onStepStatus, so the run never
+* advanced past `running` for a peer-rerouted job.
+*
+* `state` is typed as the full ExecutionJobStatus enum because the worker
+* forwards the agent's job.status verbatim; ExecutionStepStatus is a
+* strict subset and the coord trusts `kind` to route correctly.
+*/
+const jobProgressSchema = z.object({
+	type: z.literal("job.progress"),
+	kind: z.enum(["job", "step"]),
+	runId: z.string(),
+	jobId: z.string(),
+	jobName: z.string(),
+	stepIndex: z.number(),
+	stepName: z.string(),
+	state: ExecutionJobStatus,
+	timestamp: z.number(),
+	data: z.record(z.string(), z.unknown()).optional()
+});
+/** Request to cancel a job on a peer orchestrator. */
+const peerJobCancelSchema = z.object({
+	type: z.literal("peer.job.cancel"),
+	runId: z.string(),
+	jobId: z.string().optional(),
+	reason: z.string(),
+	/** When true, force-cancel immediately without waiting for hooks. */
+	force: z.boolean().optional()
+});
+/** Raft vote request during leader election. */
+const raftVoteRequestSchema = z.object({
+	type: z.literal("raft.vote.request"),
+	term: z.number(),
+	candidateId: z.string(),
+	lastLogIndex: z.number(),
+	lastLogTerm: z.number()
+});
+/** Raft vote response from a peer. */
+const raftVoteResponseSchema = z.object({
+	type: z.literal("raft.vote.response"),
+	term: z.number(),
+	voteGranted: z.boolean(),
+	voterId: z.string()
+});
+/** Raft append entries (leader heartbeat only, no log entries). */
+const raftAppendEntriesSchema = z.object({
+	type: z.literal("raft.append.entries"),
+	term: z.number(),
+	leaderId: z.string()
+});
+/** Log chunk relay: worker -> coordinator. Batched log lines from agent execution. */
+const peerLogChunkSchema = z.object({
+	type: z.literal("peer.log.chunk"),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number(),
+	lines: z.array(z.object({
+		text: z.string(),
+		timestamp: z.number(),
+		stream: z.enum(["stdout", "stderr"]).optional()
+	}))
+});
+/** Cache upload request: worker -> coordinator. Worker agent needs upload URL. */
+const peerCacheUploadRequestSchema = z.object({
+	type: z.literal("peer.cache.upload.request"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	cacheType: z.enum(["source", "deps"]),
+	hash: z.string(),
+	sizeBytes: z.number()
+});
+/** Cache upload response: coordinator -> worker. Pre-signed upload URL. */
+const peerCacheUploadResponseSchema = z.object({
+	type: z.literal("peer.cache.upload.response"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	uploadUrl: z.string()
+});
+/**
+* Config reload request: forwarded from one orchestrator to a specific peer
+* when an operator calls POST /admin/config/reload with a `target` parameter.
+* The receiving peer executes a local reload and replies with
+* peer.config.reload.response.
+*/
+const peerConfigReloadSchema = z.object({
+	type: z.literal("peer.config.reload"),
+	messageId: z.string(),
+	/** Whether to drain in-flight work before reloading. */
+	drain: z.boolean().optional()
+});
+/**
+* Config reload response: sent back from the target peer carrying the
+* ReloadResult fields produced by ConfigReloader.executeReload().
+*/
+const peerConfigReloadResponseSchema = z.object({
+	type: z.literal("peer.config.reload.response"),
+	messageId: z.string(),
+	success: z.boolean(),
+	version: z.number().optional(),
+	errors: z.array(z.string()).optional(),
+	restartRequired: z.array(z.string()).optional(),
+	fieldsChanged: z.array(z.string()).optional()
+});
+/** Graceful shutdown announcement. Peers remove sender from registry immediately. */
+const peerLeavingSchema = z.object({
+	type: z.literal("peer.leaving"),
+	instanceId: z.string(),
+	/** Current Raft term for leader identification */
+	term: z.number()
+});
+/**
+* Notify every peer that an agent token has been revoked so each peer can
+* close its own in-flight WS connections authenticated by that token.
+* The originating peer kicks locally first (via the DELETE admin route),
+* then broadcasts this message over the encrypted peer mesh.
+*/
+const peerAgentTokenRevokeSchema = z.object({
+	type: z.literal("peer.agent-token.revoke"),
+	/** The `agent_tokens.id` whose in-flight WS must be kicked on every peer. */
+	tokenId: z.string().min(1),
+	/** Originating peer's instanceId — for log correlation across the cluster. */
+	senderInstanceId: z.string().min(1)
+});
+/** All peer-to-peer messages (outbound from this node). */
+const peerToPeerMessageSchema = z.discriminatedUnion("type", [
+	peerHelloSchema,
+	peerHelloResponseSchema,
+	peerAuthRequestSchema,
+	peerAuthResponseSchema,
+	peerHeartbeatSchema,
+	jobRerouteSchema,
+	jobRerouteAckSchema,
+	jobProgressSchema,
+	peerJobCancelSchema,
+	raftVoteRequestSchema,
+	raftVoteResponseSchema,
+	raftAppendEntriesSchema,
+	peerLogChunkSchema,
+	peerCacheUploadRequestSchema,
+	peerCacheUploadResponseSchema,
+	peerConfigReloadSchema,
+	peerConfigReloadResponseSchema,
+	peerLeavingSchema,
+	peerAgentTokenRevokeSchema
+]);
+/** All peer-to-peer messages (inbound to this node). */
+const peerFromPeerMessageSchema = z.discriminatedUnion("type", [
+	peerHelloSchema,
+	peerHelloResponseSchema,
+	peerAuthRequestSchema,
+	peerAuthResponseSchema,
+	peerHeartbeatSchema,
+	jobRerouteSchema,
+	jobRerouteAckSchema,
+	jobProgressSchema,
+	peerJobCancelSchema,
+	raftVoteRequestSchema,
+	raftVoteResponseSchema,
+	raftAppendEntriesSchema,
+	peerLogChunkSchema,
+	peerCacheUploadRequestSchema,
+	peerCacheUploadResponseSchema,
+	peerConfigReloadSchema,
+	peerConfigReloadResponseSchema,
+	peerLeavingSchema,
+	peerAgentTokenRevokeSchema
+]);
+//#endregion
+export { jobProgressSchema, jobRerouteAckSchema, jobRerouteSchema, peerAgentTokenRevokeSchema, peerAuthRequestSchema, peerAuthResponseSchema, peerCapabilitiesSchema, peerConfigReloadResponseSchema, peerConfigReloadSchema, peerFromPeerMessageSchema, peerHeartbeatSchema, peerHelloResponseSchema, peerHelloSchema, peerJobCancelSchema, peerLeavingSchema, peerToPeerMessageSchema, raftAppendEntriesSchema, raftVoteRequestSchema, raftVoteResponseSchema };
+
+//# sourceMappingURL=peer.js.map