@kici-dev/engine 0.14.2 → 0.16.0

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

@@ -1,10 +1,10 @@
 import "../../rolldown-runtime-ClRpJifh.js";
 import { provenanceContextSchema } from "../../provenance/id-token-event-claims.js";
+import { agentCapabilitiesSchema, orchAgentCapabilitiesSchema } from "./capabilities.js";
+import { LogStream } from "./log-stream.js";
 import { ExecutionJobStatus, ExecutionStepStatus, StepConcurrencyKind } from "./execution-status.js";
 import { dsseEnvelopeSchema } from "../../provenance/dsse.js";
 import { approvalTimeoutSecondsSchema, approverClauseSchema } from "../../approval/types.js";
-import { agentCapabilitiesSchema, orchAgentCapabilitiesSchema } from "./capabilities.js";
-import { LogStream } from "./log-stream.js";
 import { z } from "zod";
 //#region src/protocol/messages/orchestrator-agent.ts
 /**
@@ -88,8 +88,6 @@ const jobDispatchSchema = z.object({
 	/** 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' } } */
@@ -98,8 +96,8 @@ const jobDispatchSchema = z.object({
 	maxLogSizeBytes: z.coerce.number().optional(),
 	/**
 	* Orchestrator-resolved concurrency-slot wait timeout (ms), from the
-	* fleet-wide `cluster_settings.concurrency_wait_timeout_ms`. Agent falls
-	* back to its own env/config default (1h) when absent (older orchestrators).
+	* fleet-wide `cluster_settings.concurrency_wait_timeout_ms`. The agent falls
+	* back to its own env/config default (1h) when absent.
 	*/
 	concurrencyWaitTimeoutMs: 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. */
@@ -129,9 +127,10 @@ const jobDispatchSchema = z.object({
 	* HEAD branch where the claim is the BASE branch, and `workflowRef` here is
 	* the `<name>@<sha>` claim rather than a global workflow's clone ref.
 	*
-	* Additive and optional: an older orchestrator omits it and the agent falls
-	* back to its local guess. That fallback statement fails the capture
-	* cross-check, so the defer is dropped rather than stored unchecked.
+	* Absent when the orchestrator has no provenance issuer configured, or when
+	* a worker dispatches a rerouted job. The agent then falls back to its local
+	* guess. That fallback statement fails the capture cross-check, so the
+	* defer is dropped rather than stored unchecked.
 	*/
 	provenanceContext: provenanceContextSchema.optional(),
 	/** Plain outputs from upstream jobs (keyed by job name, then by step name). Populated for downstream jobs with `needs` dependencies. */
@@ -142,20 +141,14 @@ const jobDispatchSchema = z.object({
 	* Per-invoke-gate results for any upstream gate this job `needs`, keyed by
 	* gate job name. One {@link invokeResultSchema} entry per run the gate
 	* triggered, carrying the invoked run's non-secret declared outputs. Powers
-	* a standard downstream job's `ctx.needs['<gate>'].result`. Additive and
-	* optional — older orchestrators omit it and the agent resolves the gate
-	* need through the fan-out group shape instead.
+	* a standard downstream job's `ctx.needs['<gate>'].result`. Absent when the
+	* job needs no invoke gate, or when a worker dispatches a rerouted job; the
+	* agent then resolves the gate need through the fan-out group shape.
 	*/
 	upstreamInvokeResults: z.record(z.string(), z.array(invokeResultSchema)).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.
+	* Structured clone auth for the source repo. Absent when the job's provider
+	* mints no clone credential (a public or local repository).
 	*/
 	sourceAuth: gitAuthSchema.optional(),
 	/**
@@ -187,9 +180,8 @@ const jobDispatchSchema = z.object({
 	* resolved by the orchestrator (the lock carries secret NAMES; the agent
 	* never resolves them itself).
 	*
-	* Optional for backward compatibility with older orchestrators, which do
-	* not send it — an agent that receives no auth pulls anonymously, exactly
-	* as it did before.
+	* Absent when the job's image needs no registry credential — the agent
+	* then pulls anonymously.
 	*/
 	containerRegistryAuth: z.object({
 		username: z.string().min(1),
@@ -214,19 +206,6 @@ const jobDispatchSchema = z.object({
 	* as `isolated` by the agent (fail-closed).
 	*/
 	cacheRefScope: CacheRefScope.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({
@@ -268,17 +247,10 @@ const registerAckSchema = z.object({
 	* reaper's back, re-creating the spawn/reap churn that reaping only surplus
 	* agents exists to prevent.
 	*
-	* Absent on orchestrators that predate warm pools. An agent that does not
-	* understand this field arms the short KICI_SCALER_IDLE_TIMEOUT timer exactly
-	* as before — so warm pools do not work against it, which is today's
-	* behaviour rather than a regression.
+	* Absent for a job-bound spawn and for a static agent.
 	*/
 	warmPool: z.boolean().optional(),
-	/**
-	* Optional agent-facing capabilities this orchestrator supports (absent on
-	* pre-capability orchestrators). The agent reads it to decide whether to
-	* await optional acks like `artifacts.upload.complete.ack`.
-	*/
+	/** Agent-facing capabilities this orchestrator advertises; none are defined at protocol 4. */
 	capabilities: orchAgentCapabilitiesSchema.optional()
 });
 /** Agent registration with capabilities and capacity. */
@@ -291,7 +263,7 @@ const agentRegisterSchema = z.object({
 	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. */
+	/** Agent version (e.g. "0.0.1"). Absent when the agent cannot read its own package version. */
 	version: z.string().optional(),
 	/** Maximum concurrent jobs this agent can handle. Defaults to 1 if not specified. */
 	maxConcurrency: z.number().int().positive().optional(),
@@ -326,11 +298,7 @@ const agentRegisterSchema = z.object({
 		z.number(),
 		z.boolean()
 	])).optional(),
-	/**
-	* Optional agent behaviours this agent build implements (absent on
-	* pre-capability agents, which the orchestrator treats as supporting none).
-	* The orchestrator reads it to route work that depends on one of them.
-	*/
+	/** Optional agent behaviours this agent advertises; none are defined at protocol 4. */
 	capabilities: agentCapabilitiesSchema.optional()
 });
 /** Periodic agent status update. */
@@ -377,8 +345,8 @@ const jobStatusSchema = z.object({
 * `LockJob` interface in `trigger/types.ts`, and a hand-written Zod copy would
 * drift and start rejecting legitimate generated jobs.
 *
-* Every field beyond the verdict itself is `.optional()` so an older peer
-* tolerates the message unchanged.
+* Every field beyond the verdict itself is `.optional()`: an undecided or
+* job-less verdict omits them.
 */
 const globalEvalCandidateResultSchema = z.object({
 	/** The candidate workflow's name, as it appears in the lock file. */
@@ -451,11 +419,8 @@ const agentLogChunkSchema = z.object({
 	stepIndex: z.number(),
 	lines: z.array(z.string()),
 	timestamp: z.number(),
-	/**
-	* Which stream these lines came from. Optional for backward compatibility
-	* with agents that do not send it; absent is read as `stdout`.
-	*/
-	stream: LogStream.optional()
+	/** Which stream these lines came from. */
+	stream: LogStream
 });
 /** Step-level execution state report (agent -> orchestrator). */
 const agentStepStatusSchema = z.object({
@@ -553,37 +518,37 @@ const configAckSchema = z.object({
 	messageId: z.string(),
 	agentId: z.string()
 });
-/** Agent -> Orchestrator: request a pre-signed upload URL for cache storage. */
-const cacheUploadRequestSchema = z.object({
+/**
+* Agent -> Orchestrator: request a pre-signed upload URL for cache storage.
+*
+* Each tarball is stored under its own content hash, so the orchestrator needs
+* that hash to sign the upload URL: `sourceTarDigest` for a source upload,
+* `depsHash` for a deps upload. The agent has already packed and hashed the
+* tarball by the time it asks.
+*/
+const cacheUploadRequestSchema = z.discriminatedUnion("cacheType", [z.object({
 	type: z.literal("cache.upload.request"),
 	messageId: z.string(),
 	jobId: z.string(),
-	cacheType: z.enum(["source", "deps"]),
+	cacheType: z.literal("source"),
 	contentHash: z.string().optional(),
+	platform: z.string(),
+	arch: z.string(),
+	/** SHA-256 of the source tarball about to be uploaded. */
+	sourceTarDigest: z.string()
+}), z.object({
+	type: z.literal("cache.upload.request"),
+	messageId: z.string(),
+	jobId: z.string(),
+	cacheType: z.literal("deps"),
 	lockfileHash: z.string().optional(),
 	platform: z.string(),
 	arch: z.string(),
-	/**
-	* SHA-256 of the dependency tarball about to be uploaded. Deps uploads only.
-	*
-	* The dep tarball is stored under its own content hash, so the orchestrator
-	* needs it to sign the upload URL — the agent has already built the tarball
-	* and hashed it by the time it asks. Optional so an older agent that omits it
-	* still gets a usable (lockfile-keyed) URL during a mixed-version rollout.
-	*/
-	depsHash: z.string().optional(),
-	/**
-	* SHA-256 of the source tarball about to be uploaded. Source uploads only.
-	*
-	* The source tarball is stored under its own content hash, so the
-	* orchestrator needs it to sign the upload URL — the agent has already packed
-	* and hashed it by the time it asks. Optional so an older agent that omits it
-	* still gets a usable URL during a mixed-version rollout.
-	*/
-	sourceTarDigest: z.string().optional(),
+	/** SHA-256 of the dependency tarball about to be uploaded. */
+	depsHash: z.string(),
 	/** In-repo `workspace:` sibling closure digest; part of the dep pointer key. */
 	siblingsDigest: z.string().optional()
-});
+})]);
 /** Orchestrator -> Agent: return the pre-signed upload URL. */
 const cacheUploadResponseSchema = z.object({
 	type: z.literal("cache.upload.response"),
@@ -591,22 +556,29 @@ const cacheUploadResponseSchema = z.object({
 	uploadUrl: z.string()
 });
 /** Agent -> Orchestrator: confirm upload complete (for metadata update). */
-const cacheUploadCompleteSchema = z.object({
+const cacheUploadCompleteSchema = z.discriminatedUnion("cacheType", [z.object({
 	type: z.literal("cache.upload.complete"),
 	messageId: z.string(),
 	jobId: z.string(),
-	cacheType: z.enum(["source", "deps"]),
+	cacheType: z.literal("source"),
 	contentHash: z.string().optional(),
+	platform: z.string(),
+	arch: z.string(),
+	/** SHA-256 of the source tarball's own bytes. */
+	sourceTarDigest: z.string()
+}), z.object({
+	type: z.literal("cache.upload.complete"),
+	messageId: z.string(),
+	jobId: z.string(),
+	cacheType: z.literal("deps"),
 	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(),
-	/** SHA-256 of the source tarball's own bytes. Only present for source uploads. */
-	sourceTarDigest: z.string().optional(),
+	/** SHA-256 hash of the dependency tarball for integrity verification. */
+	depsHash: z.string(),
 	/** In-repo `workspace:` sibling closure digest; part of the dep pointer key. */
 	siblingsDigest: z.string().optional()
-});
+})]);
 /** Agent -> Orchestrator: request a user-cache restore (presigned download). */
 const cacheUserRestoreRequestSchema = z.object({
 	type: z.literal("cache.user.restore.request"),
@@ -765,8 +737,7 @@ const artifactsUploadResponseSchema = z.object({
 	* uploads are not configured on the orchestrator, the job's run could not be
 	* resolved, the job is not owned by this agent, or the orchestrator hit an
 	* internal error. A safe, fixed,
-	* human-readable string; never a raw exception. Older agents ignore the field
-	* and fall back to a generic rejection message.
+	* human-readable string; never a raw exception.
 	*/
 	error: z.string().optional()
 });
@@ -793,9 +764,7 @@ const artifactsUploadCompleteSchema = z.object({
 const ArtifactCompleteAckOutcome = z.enum(["committed", "failed"]);
 /**
 * Orchestrator -> Agent: the outcome of committing an
-* `artifacts.upload.complete`. Sent by orchestrators that advertise the
-* `artifactCompleteAck` capability on `register.ack`; the agent awaits it and
-* fails the workflow step on `failed`/timeout, so a lost commit surfaces as a
+* `artifacts.upload.complete`. The agent awaits it and fails the workflow step on `failed`/timeout, so a lost commit surfaces as a
 * failed step instead of a green run with a missing artifact. `requestId`
 * echoes the complete message's `messageId`.
 */
@@ -841,8 +810,7 @@ const artifactsDownloadResponseSchema = z.object({
 	* the job's run could not be resolved, the job is not owned by this agent, or
 	* the orchestrator hit an internal error — rather than a genuinely missing
 	* artifact. A safe, fixed,
-	* human-readable string; never a raw exception. Older agents ignore the field
-	* and render the plain not-found message.
+	* human-readable string; never a raw exception.
 	*/
 	error: z.string().optional()
 });
@@ -876,8 +844,7 @@ const eventEmitResponseSchema = z.object({
 * A provisioned agent normally sends this itself to self-bootstrap — the claim
 * code is the authorization, so it may send it before it authenticates or
 * registers. A provisioning workflow can also send it to obtain the token
-* directly. Additive/negotiated by presence — older peers that never emit it
-* are unaffected, so it needs no `PROTOCOL_VERSION` bump of its own.
+* directly.
 */
 const scalerClaimCredentialsSchema = z.object({
 	type: z.literal("scaler.claim-credentials"),