@kici-dev/engine 0.0.0 → 0.1.1

package/dist/protocol/messages/orchestrator-agent.js

@@ -0,0 +1,481 @@
+import "../../chunk-gOLHoazu.js";
+import { ExecutionJobStatus, ExecutionStepStatus } from "./execution-status.js";
+import { z } from "zod";
+//#region src/protocol/messages/orchestrator-agent.ts
+/**
+* Structured git-clone auth material. Carries everything the agent needs to
+* authenticate a single `git clone`:
+*
+*   - `kind: 'basic'` — HTTPS Basic auth (PAT / password). `secret` is the
+*     token, `user` is the Basic-auth username (defaults filled in by the
+*     provider, e.g. `x-access-token` for GitHub-style PATs).
+*   - `kind: 'ssh'` — SSH key auth. `secret` is the PEM-encoded private key.
+*     `sshHostKeyPolicy` + `sshKnownHostsPem` drive StrictHostKeyChecking.
+*
+* Used by `sourceAuth` and `workflowAuth` on `jobDispatchSchema` so a single
+* global-workflow dispatch can carry two different credentials (one per
+* clone target — required for cross-provider global workflows).
+*/
+const gitAuthSchema = z.object({
+	kind: z.enum(["basic", "ssh"]),
+	/** Basic-auth username. Omit for SSH. */
+	user: z.string().optional(),
+	/** Basic-auth password/PAT, or PEM-encoded SSH private key. */
+	secret: z.string(),
+	/** SSH-only. `accept-new` trusts first seen host keys; `pinned` requires `sshKnownHostsPem`. */
+	sshHostKeyPolicy: z.enum(["accept-new", "pinned"]).optional(),
+	/** SSH-only, required when `sshHostKeyPolicy === 'pinned'`. OpenSSH known_hosts content. */
+	sshKnownHostsPem: z.string().optional()
+}).superRefine((val, ctx) => {
+	if (val.kind === "ssh" && val.sshHostKeyPolicy === "pinned" && !val.sshKnownHostsPem) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["sshKnownHostsPem"],
+		message: "sshKnownHostsPem is required when sshHostKeyPolicy is \"pinned\""
+	});
+});
+/** Dispatch a job to an agent for execution. */
+const jobDispatchSchema = z.object({
+	type: z.literal("job.dispatch"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	repoUrl: z.string(),
+	ref: z.string(),
+	sha: z.string(),
+	lockFileUrl: z.string(),
+	/** Pass-through job configuration. Shape is `LockJob | LockDynamicJobFn` from the lock file. */
+	jobConfig: z.record(z.string(), z.unknown()).describe("Job configuration from the lock file (LockJob | LockDynamicJobFn)"),
+	timestamp: z.number(),
+	/** Short-lived GitHub installation token for private repo clone auth. */
+	token: z.string().optional(),
+	/** Orchestrator-provided secrets to merge into step environment. */
+	secrets: z.record(z.string(), z.string()).optional(),
+	/** Namespaced secrets by context name: { 'context-name': { KEY: 'value' } } */
+	namespacedSecrets: z.record(z.string(), z.record(z.string(), z.string())).optional(),
+	/** Max log size per step in bytes. Agent falls back to its own config default (10MB). */
+	maxLogSizeBytes: z.coerce.number().optional(),
+	/** URL or file:// path to a pre-packed `.kici/` source tarball. If present, agent extracts it into workDir instead of cloning the repo. */
+	sourceTarUrl: z.string().optional(),
+	/** SHA-256 hash of the source tarball bytes for integrity verification on download. */
+	sourceTarHash: z.string().optional(),
+	/** URL or file:// path to pre-built dependency tarball. If present, agent extracts to .kici/node_modules/ instead of running install. */
+	depsUrl: z.string().optional(),
+	/** SHA-256 hash of the dependency tarball for integrity verification. */
+	depsHash: z.string().optional(),
+	/** Trace ID propagated across tiers for distributed tracing. */
+	requestId: z.string().optional(),
+	/** Base64-encoded X25519 public key for the workflow run (for encrypting secret outputs). */
+	runPublicKey: z.string().optional(),
+	/** Plain outputs from upstream jobs (keyed by job name, then by step name). Populated for downstream jobs with `needs` dependencies. */
+	upstreamJobOutputs: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+	/**
+	* Structured clone auth for the source repo. Preferred over `token` (which
+	* remains as a backward-compat field for same-provider GitHub App flows
+	* during the transition to universal-git / cross-provider global workflows).
+	*
+	* When both `token` and `sourceAuth` are set, a Zod refinement enforces
+	* that they agree (`sourceAuth.kind === 'basic'` and
+	* `sourceAuth.secret === token`) — otherwise the dispatch is rejected to
+	* prevent silent credential mismatches.
+	*/
+	sourceAuth: gitAuthSchema.optional(),
+	/**
+	* Structured clone auth for the **workflow** repo in a global-workflow
+	* dispatch (when the workflow is authored on a different source than the
+	* source repo). When `jobConfig.isGlobalWorkflow === true` and the two
+	* providers differ, the orchestrator populates `sourceAuth` from the
+	* inbound bundle and `workflowAuth` from the registration's bundle.
+	*
+	* For same-provider global workflows this is typically absent and the
+	* agent reuses `sourceAuth` for both clones.
+	*/
+	workflowAuth: gitAuthSchema.optional(),
+	/**
+	* Private npm registries the agent should authenticate against before
+	* `npm install`. Each entry's `token` is the resolved value (the
+	* orchestrator already looked it up via the per-environment
+	* secretResolver path; protection-rule gates have already passed at this
+	* point). Untrusted contributors get an empty list.
+	*/
+	npmRegistries: z.array(z.object({
+		url: z.string().url(),
+		scope: z.string().optional(),
+		alwaysAuth: z.boolean(),
+		token: z.string().min(1)
+	})).optional(),
+	/**
+	* Extra resolved secrets to project as env vars on the install
+	* subprocess. Keyed by the bare secret name (the qualified env: prefix
+	* is stripped at resolution time). For use with a customer-committed
+	* `.kici/.npmrc` containing `${VAR}` placeholders.
+	*/
+	installEnvSecrets: z.record(z.string(), z.string()).optional()
+}).superRefine((val, ctx) => {
+	if (val.token && val.sourceAuth) {
+		if (val.sourceAuth.kind !== "basic") ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ["sourceAuth", "kind"],
+			message: "token is set; sourceAuth.kind must be \"basic\" to agree"
+		});
+		else if (val.sourceAuth.secret !== val.token) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ["sourceAuth", "secret"],
+			message: "token and sourceAuth.secret must match when both are set"
+		});
+	}
+});
+/** Cancel a running or queued job. */
+const jobCancelSchema = z.object({
+	type: z.literal("job.cancel"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	reason: z.string(),
+	/** When true, force-cancel immediately without waiting for hooks. */
+	force: z.boolean().optional()
+});
+/** Acknowledge agent registration with orchestrator-assigned settings. */
+const registerAckSchema = z.object({
+	type: z.literal("register.ack"),
+	agentId: z.string(),
+	labels: z.array(z.string()),
+	scalerManaged: z.boolean().default(false),
+	/**
+	* Set when the orchestrator's scaler bound a specific queued job to this
+	* agent at spawn time and is preparing the dispatch.job message right now.
+	* Scaler-managed agents that see this flag MUST NOT arm the short
+	* KICI_SCALER_IDLE_TIMEOUT timer on register — the dispatch is in flight
+	* and may take a few seconds to arrive (provider lookup, secret merging,
+	* upstream output fetching all happen between register.ack and dispatch.job
+	* for jobs with `needs:` dependencies). Without this flag the agent races
+	* the orchestrator and self-shuts down before the dispatch arrives.
+	* If the dispatch never arrives (orchestrator crash, etc.) the agent's
+	* KICI_SCALER_PENDING_DISPATCH_TIMEOUT (default 60s) acts as a safety net.
+	*/
+	pendingDispatch: z.boolean().optional()
+});
+/** Agent registration with capabilities and capacity. */
+const agentRegisterSchema = z.object({
+	type: z.literal("agent.register"),
+	messageId: z.string(),
+	agentId: z.string(),
+	labels: z.array(z.string()),
+	/** Agent platform (os.platform(), e.g. 'linux', 'darwin', 'win32') */
+	platform: z.string().optional(),
+	/** Agent architecture (os.arch(), e.g. 'x64', 'arm64') */
+	arch: z.string().optional(),
+	/** Agent version (e.g. "0.0.1"). Optional for backward compatibility with older agents. */
+	version: z.string().optional(),
+	/** Maximum concurrent jobs this agent can handle. Defaults to 1 if not specified. */
+	maxConcurrency: z.number().int().positive().optional(),
+	/** Jobs still running on this agent (sent on reconnection to enable job recovery). */
+	inFlightJobs: z.array(z.object({
+		jobId: z.string(),
+		runId: z.string()
+	})).optional(),
+	/** Machine hostname (os.hostname()) */
+	hostname: z.string().optional(),
+	/** OS kernel release (os.release()) */
+	osRelease: z.string().optional(),
+	/** OS version string (os.version()) */
+	osVersion: z.string().optional(),
+	/** Total system memory in MiB */
+	totalMemoryMb: z.number().optional(),
+	/** Number of logical CPUs */
+	cpuCount: z.number().optional(),
+	/** Node.js version (process.versions.node) */
+	nodeVersion: z.string().optional(),
+	/** Username of the OS user running the agent process */
+	runningAsUser: z.string().optional(),
+	/** UID of the OS user running the agent process */
+	runningAsUid: z.number().optional()
+});
+/** Periodic agent status update. */
+const agentStatusSchema = z.object({
+	type: z.literal("agent.status"),
+	messageId: z.string(),
+	agentId: z.string(),
+	activeJobs: z.number(),
+	/** Used memory in MiB (os.totalmem() - os.freemem()) */
+	memoryUsedMb: z.number().optional(),
+	/** Available memory in MiB (os.freemem()) */
+	memoryAvailableMb: z.number().optional(),
+	/** System uptime in seconds (os.uptime()) */
+	uptimeSeconds: z.number().optional()
+});
+/** Job execution state transition report. */
+const jobStatusSchema = z.object({
+	type: z.literal("job.status"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	state: ExecutionJobStatus,
+	timestamp: z.number(),
+	data: z.record(z.string(), z.unknown()).optional(),
+	/** Job names dropped by determinism drift (agent re-eval produced fewer jobs than expected). */
+	droppedJobs: z.array(z.string()).optional(),
+	/** Encrypted secret outputs from agent (present on job success when secret outputs exist). */
+	secretOutputs: z.record(z.string(), z.object({
+		/** Base64-encoded agent ephemeral X25519 public key (DER SPKI). */
+		agentPublicKey: z.string(),
+		/** Base64-encoded encrypted value: IV (12B) || AuthTag (16B) || Ciphertext. */
+		encrypted: z.string()
+	})).optional()
+});
+/**
+* Streaming log chunk from step execution (agent -> orchestrator).
+*
+* FAST-PATHED: A manual validator exists in
+* packages/orchestrator/src/ws/agent-handler.ts (isValidLogChunk).
+* If you change this schema, update the manual validator in the same commit.
+* See CLAUDE.md rule: "Zod fast-path sync invariant".
+*/
+const agentLogChunkSchema = z.object({
+	type: z.literal("log.chunk"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number(),
+	lines: z.array(z.string()),
+	timestamp: z.number()
+});
+/** Step-level execution state report (agent -> orchestrator). */
+const agentStepStatusSchema = z.object({
+	type: z.literal("step.status"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number().int().nonnegative(),
+	stepName: z.string(),
+	state: ExecutionStepStatus,
+	timestamp: z.number(),
+	data: z.record(z.string(), z.unknown()).optional(),
+	/** Distinguishes regular steps from hook executions. */
+	step_type: z.enum([
+		"step",
+		"hook:onCancel",
+		"hook:cleanup",
+		"hook:onSuccess",
+		"hook:onFailure",
+		"hook:beforeStep",
+		"hook:afterStep"
+	]).optional(),
+	/** Secret key names accessed by this step via ctx.secrets.get()/expose(). Never contains values. */
+	secretsAccessed: z.array(z.string()).optional(),
+	/**
+	* Total raw bytes streamed by this step's LogStreamer at terminal time.
+	* Counts agent-side raw bytes (the same count fed to the transient
+	* `kici_agent_log_bytes_total` counter), so it reflects what the customer
+	* actually emitted — not gzip archive size or post-processing size.
+	* Set on terminal step states only. Reused by the orchestrator to
+	* accumulate per-job and per-run totals for the operator-side
+	* `kici_org_log_bytes` capacity-planning gauge.
+	*/
+	logBytesStreamed: z.number().int().nonnegative().optional()
+});
+/** Periodic job heartbeat from agent to orchestrator (stale run detection). */
+const jobHeartbeatSchema = z.object({
+	type: z.literal("job.heartbeat"),
+	runId: z.string(),
+	jobId: z.string(),
+	timestamp: z.number()
+});
+/** Operational log lines streamed from agent to orchestrator (stateful/external agents). */
+const agentLogSchema = z.object({
+	type: z.literal("agent.log"),
+	messageId: z.string(),
+	agentId: z.string(),
+	lines: z.array(z.string()),
+	timestamp: z.number()
+});
+/** Agent -> Orchestrator: report that a job belongs to a concurrency group. */
+const jobConcurrencyReportSchema = z.object({
+	type: z.literal("job.concurrency.report"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	group: z.string()
+});
+/**
+* Orchestrator -> Agent: acknowledge concurrency report with action to take.
+*
+* The orchestrator sends this in two situations:
+* 1. As a direct response to a `job.concurrency.report` message — `requestId`
+*    correlates to the report. Action is `proceed`, `wait`, or `cancel`.
+* 2. As an UNSOLICITED follow-up after the agent received `wait`. When a slot
+*    in the concurrency group is released (by completion, cancellation, or
+*    superseding), the orchestrator picks the FIFO-next queued waiter and
+*    sends `{ action: 'proceed' }` to the agent that's still parked on its
+*    second `waitForConcurrencyAck` call. `runId` / `jobId` are present in
+*    this case so the agent can sanity-check the wake-up matches its job.
+*    The agent's pending-ack slot resolves regardless of `requestId` (single
+*    in-flight ack per workflow-runner process).
+*/
+const jobConcurrencyAckSchema = z.object({
+	type: z.literal("job.concurrency.ack"),
+	requestId: z.string(),
+	action: z.enum([
+		"proceed",
+		"wait",
+		"cancel"
+	]),
+	reason: z.string().optional(),
+	/** Optional run identifier for unsolicited slot-release wake-ups. */
+	runId: z.string().optional(),
+	/** Optional job identifier for unsolicited slot-release wake-ups. */
+	jobId: z.string().optional()
+});
+/** Agent acknowledges receipt of configuration (e.g., MMDS handshake). */
+const configAckSchema = z.object({
+	type: z.literal("config.ack"),
+	messageId: z.string(),
+	agentId: z.string()
+});
+/** Agent -> Orchestrator: request a pre-signed upload URL for cache storage. */
+const cacheUploadRequestSchema = z.object({
+	type: z.literal("cache.upload.request"),
+	messageId: z.string(),
+	jobId: z.string(),
+	cacheType: z.enum(["source", "deps"]),
+	contentHash: z.string().optional(),
+	lockfileHash: z.string().optional(),
+	platform: z.string(),
+	arch: z.string()
+});
+/** Orchestrator -> Agent: return the pre-signed upload URL. */
+const cacheUploadResponseSchema = z.object({
+	type: z.literal("cache.upload.response"),
+	requestId: z.string(),
+	uploadUrl: z.string()
+});
+/** Agent -> Orchestrator: confirm upload complete (for metadata update). */
+const cacheUploadCompleteSchema = z.object({
+	type: z.literal("cache.upload.complete"),
+	messageId: z.string(),
+	jobId: z.string(),
+	cacheType: z.enum(["source", "deps"]),
+	contentHash: z.string().optional(),
+	lockfileHash: z.string().optional(),
+	platform: z.string(),
+	arch: z.string(),
+	/** SHA-256 hash of the dependency tarball for integrity verification. Only present for deps uploads. */
+	depsHash: z.string().optional()
+});
+/** Agent -> Orchestrator: emit a custom event from a running workflow step. */
+const eventEmitSchema = z.object({
+	type: z.literal("event.emit"),
+	/** Job that is emitting the event. */
+	jobId: z.string(),
+	/** Correlates to the runner's request for response routing. */
+	requestId: z.string(),
+	/** Custom event name (e.g. 'deploy-complete'). */
+	eventName: z.string(),
+	/** Event payload (arbitrary JSON-serializable data). */
+	payload: z.record(z.string(), z.unknown()),
+	/** Optional targeting for cross-repo delivery. */
+	target: z.object({ repos: z.array(z.string()).optional() }).optional()
+});
+/** Orchestrator -> Agent: response confirming event delivery. */
+const eventEmitResponseSchema = z.object({
+	type: z.literal("event.emit.response"),
+	/** Correlates to the original event.emit requestId. */
+	requestId: z.string(),
+	/** Delivery ID assigned by the orchestrator (present on success). */
+	deliveryId: z.string().optional(),
+	/** Error description (present on failure). */
+	error: z.string().optional()
+});
+/** Periodic metrics push from agent to orchestrator. */
+const agentMetricsSchema = z.object({
+	type: z.literal("agent.metrics"),
+	messageId: z.string(),
+	agentId: z.string(),
+	metrics: z.array(z.object({
+		name: z.string(),
+		type: z.enum([
+			"counter",
+			"histogram",
+			"gauge",
+			"upDownCounter"
+		]),
+		value: z.number().optional(),
+		labels: z.record(z.string(), z.string()).optional(),
+		buckets: z.array(z.object({
+			le: z.number(),
+			count: z.number()
+		})).optional(),
+		count: z.number().optional(),
+		sum: z.number().optional()
+	})),
+	timestamp: z.number()
+});
+/** Auth request sent by agent to orchestrator when connecting via WebSocket. */
+const agentAuthRequestSchema = z.object({
+	type: z.literal("auth.request"),
+	token: z.string().min(1),
+	protocolVersion: z.number().int().positive()
+});
+/** Auth success response sent by orchestrator to agent after successful authentication. */
+const agentAuthSuccessSchema = z.object({
+	type: z.literal("auth.success"),
+	connectionId: z.string()
+});
+/** Auth failure response sent by orchestrator to agent when authentication fails. */
+const agentAuthFailureSchema = z.object({
+	type: z.literal("auth.failure"),
+	reason: z.string()
+});
+/** API request sent by agent to orchestrator (e.g., infrastructure.list). */
+const agentApiRequestSchema = z.object({
+	type: z.literal("agent.api.request"),
+	/** UUID for correlating the response. */
+	requestId: z.string(),
+	/** Dot-namespaced method name (e.g., 'infrastructure.list'). */
+	method: z.string(),
+	/** Method-specific parameters. */
+	params: z.record(z.string(), z.unknown()).default({})
+});
+/** API response sent by orchestrator to agent. */
+const agentApiResponseSchema = z.object({
+	type: z.literal("agent.api.response"),
+	/** Matches the original request's requestId. */
+	requestId: z.string(),
+	/** Method result (present on success). */
+	result: z.unknown().optional(),
+	/** Error description (present on failure). */
+	error: z.string().optional()
+});
+/** All messages that flow from Orchestrator to Agent. */
+const orchestratorToAgentMessageSchema = z.discriminatedUnion("type", [
+	jobDispatchSchema,
+	jobCancelSchema,
+	registerAckSchema,
+	jobConcurrencyAckSchema,
+	cacheUploadResponseSchema,
+	eventEmitResponseSchema,
+	agentApiResponseSchema,
+	agentAuthSuccessSchema,
+	agentAuthFailureSchema
+]);
+/** All messages that flow from Agent to Orchestrator. */
+const agentToOrchestratorMessageSchema = z.discriminatedUnion("type", [
+	agentRegisterSchema,
+	agentStatusSchema,
+	jobStatusSchema,
+	agentLogChunkSchema,
+	agentStepStatusSchema,
+	jobHeartbeatSchema,
+	agentLogSchema,
+	jobConcurrencyReportSchema,
+	configAckSchema,
+	cacheUploadRequestSchema,
+	cacheUploadCompleteSchema,
+	eventEmitSchema,
+	agentApiRequestSchema,
+	agentMetricsSchema,
+	agentAuthRequestSchema
+]);
+//#endregion
+export { agentApiRequestSchema, agentApiResponseSchema, agentAuthFailureSchema, agentAuthRequestSchema, agentAuthSuccessSchema, agentLogChunkSchema, agentMetricsSchema, agentRegisterSchema, agentStatusSchema, agentStepStatusSchema, agentToOrchestratorMessageSchema, configAckSchema, eventEmitResponseSchema, eventEmitSchema, gitAuthSchema, jobCancelSchema, jobConcurrencyAckSchema, jobConcurrencyReportSchema, jobDispatchSchema, jobStatusSchema, orchestratorToAgentMessageSchema, registerAckSchema };
+
+//# sourceMappingURL=orchestrator-agent.js.map