@kici-dev/engine 0.1.14 → 0.1.16

package/dist/protocol/messages/orchestrator-agent.d.ts

@@ -1,4 +1,18 @@
 import { z } from 'zod';
+/**
+ * Cache write scope for a job's user-facing cache.
+ *
+ * - `shared` — trusted ref (default branch / write-permission contributor):
+ *   reads AND writes the org-shared default-branch scope.
+ * - `isolated` — untrusted ref (fork PR / unknown contributor): reads the
+ *   shared scope as a fallback but writes only into a per-run isolated scope,
+ *   so an untrusted ref can never poison the shared cache (GitHub Actions model).
+ */
+export declare const CacheRefScope: z.ZodEnum<{
+    shared: "shared";
+    isolated: "isolated";
+}>;
+export type CacheRefScope = z.infer<typeof CacheRefScope>;
 /**
  * Structured git-clone auth material. Carries everything the agent needs to
  * authenticate a single `git clone`:
@@ -83,6 +97,12 @@ export declare const jobDispatchSchema: z.ZodObject<{
         token: z.ZodString;
     }, z.core.$strip>>>;
     installEnvSecrets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    orgId: z.ZodOptional<z.ZodString>;
+    repoId: z.ZodOptional<z.ZodString>;
+    cacheRefScope: z.ZodOptional<z.ZodEnum<{
+        shared: "shared";
+        isolated: "isolated";
+    }>>;
 }, z.core.$strip>;
 /** Cancel a running or queued job. */
 export declare const jobCancelSchema: z.ZodObject<{
@@ -161,6 +181,51 @@ export declare const jobStatusSchema: z.ZodObject<{
         encrypted: z.ZodString;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
+/** Reasons an agent can refuse a job.dispatch. */
+export declare const JobRejectReason: z.ZodEnum<{
+    draining: "draining";
+    busy: "busy";
+}>;
+export type JobRejectReason = z.infer<typeof JobRejectReason>;
+/**
+ * Explicit dispatch rejection (agent -> orchestrator).
+ *
+ * Sent when the agent cannot accept a job.dispatch (already running a job,
+ * or draining). The orchestrator undoes its dispatch accounting and requeues
+ * the job for another agent. Protocol invariant: every job.dispatch is
+ * answered — accepted with `job.ack` (a `job.status` with state `running`
+ * also resolves the deadline), or refused with this message. An unanswered
+ * dispatch is treated as lost once the ack deadline expires (requeue +
+ * disconnect the agent) and is also covered by disconnect-time triage.
+ */
+export declare const jobRejectSchema: z.ZodObject<{
+    type: z.ZodLiteral<"job.reject">;
+    messageId: z.ZodString;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    reason: z.ZodEnum<{
+        draining: "draining";
+        busy: "busy";
+    }>;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Positive dispatch acknowledgment (agent -> orchestrator).
+ *
+ * Sent immediately when the agent receives a job.dispatch and accepts it
+ * (after the drain/busy checks, before execution begins). The orchestrator
+ * arms a deadline when it sends a dispatch; `job.ack`, `job.reject`, or a
+ * `job.status` with state `running` resolves it. A dispatch with no answer
+ * inside the deadline is treated as lost: the orchestrator requeues the job
+ * and disconnects the unresponsive agent.
+ */
+export declare const jobAckSchema: z.ZodObject<{
+    type: z.ZodLiteral<"job.ack">;
+    messageId: z.ZodString;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
 /**
  * Streaming log chunk from step execution (agent -> orchestrator).
  *
@@ -247,6 +312,46 @@ export declare const configAckSchema: z.ZodObject<{
     messageId: z.ZodString;
     agentId: z.ZodString;
 }, z.core.$strip>;
+/** Agent -> Orchestrator: request a user-cache restore (presigned download). */
+export declare const cacheUserRestoreRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"cache.user.restore.request">;
+    messageId: z.ZodString;
+    jobId: z.ZodString;
+    key: z.ZodString;
+    restoreKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Orchestrator -> Agent: presigned download URL + matched key + tar hash, or a miss. */
+export declare const cacheUserRestoreResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"cache.user.restore.response">;
+    requestId: z.ZodString;
+    hit: z.ZodBoolean;
+    matchedKey: z.ZodOptional<z.ZodString>;
+    downloadUrl: z.ZodOptional<z.ZodString>;
+    tarHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Agent -> Orchestrator: request a presigned PUT for a user-cache save (immutable; may decline if key exists). */
+export declare const cacheUserSaveRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"cache.user.save.request">;
+    messageId: z.ZodString;
+    jobId: z.ZodString;
+    key: z.ZodString;
+}, z.core.$strip>;
+/** Orchestrator -> Agent: presigned PUT URL, or `skip` when the immutable key already exists. */
+export declare const cacheUserSaveResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"cache.user.save.response">;
+    requestId: z.ZodString;
+    uploadUrl: z.ZodOptional<z.ZodString>;
+    skip: z.ZodBoolean;
+}, z.core.$strip>;
+/** Agent -> Orchestrator: confirm a user-cache upload finished; orchestrator commits temp -> final + sets metadata. */
+export declare const cacheUserSaveCompleteSchema: z.ZodObject<{
+    type: z.ZodLiteral<"cache.user.save.complete">;
+    messageId: z.ZodString;
+    jobId: z.ZodString;
+    key: z.ZodString;
+    tarHash: z.ZodString;
+    sizeBytes: z.ZodNumber;
+}, z.core.$strip>;
 /** Agent -> Orchestrator: emit a custom event from a running workflow step. */
 export declare const eventEmitSchema: z.ZodObject<{
     type: z.ZodLiteral<"event.emit">;
@@ -319,6 +424,81 @@ export declare const agentApiResponseSchema: z.ZodObject<{
     result: z.ZodOptional<z.ZodUnknown>;
     error: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** Orchestrator asks an agent for its log/diagnostic mini-bundle. */
+export declare const fleetLogsRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"fleet.logs.request">;
+    requestId: z.ZodString;
+    logWindowHours: z.ZodNumber;
+    maxBytes: z.ZodNumber;
+}, z.core.$strip>;
+/** One base64 frame of an agent's mini-bundle ZIP. */
+export declare const fleetBundleChunkSchema: z.ZodObject<{
+    type: z.ZodLiteral<"fleet.bundle.chunk">;
+    requestId: z.ZodString;
+    seq: z.ZodNumber;
+    isLast: z.ZodBoolean;
+    dataB64: z.ZodString;
+}, z.core.$strip>;
+/** Agent failed to build/stream its mini-bundle. */
+export declare const fleetBundleErrorSchema: z.ZodObject<{
+    type: z.ZodLiteral<"fleet.bundle.error">;
+    requestId: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+/** Outcome of a step-level approval hold, sent back to the waiting agent. */
+export declare const StepApprovalOutcome: z.ZodEnum<{
+    rejected: "rejected";
+    approved: "approved";
+    expired: "expired";
+}>;
+export type StepApprovalOutcome = z.infer<typeof StepApprovalOutcome>;
+/**
+ * Agent -> Orchestrator: a step carrying `requireApproval` is about to run and
+ * the agent is blocking its step loop until the orchestrator resolves the
+ * approval. The orchestrator creates a step-scoped `held_runs` row from the
+ * normalized requirement and replies with `step.approval-resolved` once the
+ * hold is approved, rejected, or expired. The agent keeps heartbeats flowing
+ * during the wait so it is not reaped as stale.
+ *
+ * NOT fast-pathed — the `log.chunk` / `heartbeat` manual-validator invariant is
+ * untouched by this message.
+ */
+export declare const stepApprovalRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"step.approval-request">;
+    messageId: z.ZodString;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    stepName: z.ZodString;
+    clauses: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        team: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        user: z.ZodString;
+    }, z.core.$strict>]>>;
+    reason: z.ZodString;
+    timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type StepApprovalRequest = z.infer<typeof stepApprovalRequestSchema>;
+/**
+ * Orchestrator -> Agent: resolution of a step-level approval hold. `requestId`
+ * correlates to the originating `step.approval-request.messageId`. On
+ * `approved` the agent runs the step with its live workspace intact; on
+ * `rejected`/`expired` it fails the job with a clear reason.
+ */
+export declare const stepApprovalResolvedSchema: z.ZodObject<{
+    type: z.ZodLiteral<"step.approval-resolved">;
+    requestId: z.ZodString;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    outcome: z.ZodEnum<{
+        rejected: "rejected";
+        approved: "approved";
+        expired: "expired";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StepApprovalResolved = z.infer<typeof stepApprovalResolvedSchema>;
 /** All messages that flow from Orchestrator to Agent. */
 export declare const orchestratorToAgentMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"job.dispatch">;
@@ -375,6 +555,12 @@ export declare const orchestratorToAgentMessageSchema: z.ZodDiscriminatedUnion<[
         token: z.ZodString;
     }, z.core.$strip>>>;
     installEnvSecrets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    orgId: z.ZodOptional<z.ZodString>;
+    repoId: z.ZodOptional<z.ZodString>;
+    cacheRefScope: z.ZodOptional<z.ZodEnum<{
+        shared: "shared";
+        isolated: "isolated";
+    }>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"job.cancel">;
     messageId: z.ZodString;
@@ -403,6 +589,18 @@ export declare const orchestratorToAgentMessageSchema: z.ZodDiscriminatedUnion<[
     type: z.ZodLiteral<"cache.upload.response">;
     requestId: z.ZodString;
     uploadUrl: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"cache.user.restore.response">;
+    requestId: z.ZodString;
+    hit: z.ZodBoolean;
+    matchedKey: z.ZodOptional<z.ZodString>;
+    downloadUrl: z.ZodOptional<z.ZodString>;
+    tarHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"cache.user.save.response">;
+    requestId: z.ZodString;
+    uploadUrl: z.ZodOptional<z.ZodString>;
+    skip: z.ZodBoolean;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"event.emit.response">;
     requestId: z.ZodString;
@@ -419,6 +617,23 @@ export declare const orchestratorToAgentMessageSchema: z.ZodDiscriminatedUnion<[
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"auth.failure">;
     reason: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"fleet.logs.request">;
+    requestId: z.ZodString;
+    logWindowHours: z.ZodNumber;
+    maxBytes: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"step.approval-resolved">;
+    requestId: z.ZodString;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    outcome: z.ZodEnum<{
+        rejected: "rejected";
+        approved: "approved";
+        expired: "expired";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "type">;
 /** All messages that flow from Agent to Orchestrator. */
 export declare const agentToOrchestratorMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -475,6 +690,22 @@ export declare const agentToOrchestratorMessageSchema: z.ZodDiscriminatedUnion<[
         agentPublicKey: z.ZodString;
         encrypted: z.ZodString;
     }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"job.reject">;
+    messageId: z.ZodString;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    reason: z.ZodEnum<{
+        draining: "draining";
+        busy: "busy";
+    }>;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"job.ack">;
+    messageId: z.ZodString;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    timestamp: z.ZodNumber;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"log.chunk">;
     messageId: z.ZodString;
@@ -555,6 +786,24 @@ export declare const agentToOrchestratorMessageSchema: z.ZodDiscriminatedUnion<[
     platform: z.ZodString;
     arch: z.ZodString;
     depsHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"cache.user.restore.request">;
+    messageId: z.ZodString;
+    jobId: z.ZodString;
+    key: z.ZodString;
+    restoreKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"cache.user.save.request">;
+    messageId: z.ZodString;
+    jobId: z.ZodString;
+    key: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"cache.user.save.complete">;
+    messageId: z.ZodString;
+    jobId: z.ZodString;
+    key: z.ZodString;
+    tarHash: z.ZodString;
+    sizeBytes: z.ZodNumber;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"event.emit">;
     jobId: z.ZodString;
@@ -595,12 +844,47 @@ export declare const agentToOrchestratorMessageSchema: z.ZodDiscriminatedUnion<[
     type: z.ZodLiteral<"auth.request">;
     token: z.ZodString;
     protocolVersion: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"fleet.bundle.chunk">;
+    requestId: z.ZodString;
+    seq: z.ZodNumber;
+    isLast: z.ZodBoolean;
+    dataB64: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"fleet.bundle.error">;
+    requestId: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"step.approval-request">;
+    messageId: z.ZodString;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    stepName: z.ZodString;
+    clauses: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        team: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        user: z.ZodString;
+    }, z.core.$strict>]>>;
+    reason: z.ZodString;
+    timeoutSeconds: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>], "type">;
 export type JobDispatch = z.infer<typeof jobDispatchSchema>;
 export type JobCancel = z.infer<typeof jobCancelSchema>;
 export type JobStatus = z.infer<typeof jobStatusSchema>;
+export type JobReject = z.infer<typeof jobRejectSchema>;
+export type JobAck = z.infer<typeof jobAckSchema>;
 export type AgentLogChunk = z.infer<typeof agentLogChunkSchema>;
 export type AgentStepStatus = z.infer<typeof agentStepStatusSchema>;
 export type AgentMetrics = z.infer<typeof agentMetricsSchema>;
+export type CacheUserRestoreRequest = z.infer<typeof cacheUserRestoreRequestSchema>;
+export type CacheUserRestoreResponse = z.infer<typeof cacheUserRestoreResponseSchema>;
+export type CacheUserSaveRequest = z.infer<typeof cacheUserSaveRequestSchema>;
+export type CacheUserSaveResponse = z.infer<typeof cacheUserSaveResponseSchema>;
+export type CacheUserSaveComplete = z.infer<typeof cacheUserSaveCompleteSchema>;
+export type FleetLogsRequest = z.infer<typeof fleetLogsRequestSchema>;
+export type FleetBundleChunk = z.infer<typeof fleetBundleChunkSchema>;
+export type FleetBundleError = z.infer<typeof fleetBundleErrorSchema>;
+export type OrchestratorToAgentMessage = z.infer<typeof orchestratorToAgentMessageSchema>;
 export type AgentToOrchestratorMessage = z.infer<typeof agentToOrchestratorMessageSchema>;
 //# sourceMappingURL=orchestrator-agent.d.ts.map

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

@@ -1,8 +1,19 @@
 import "../../chunk-gOLHoazu.js";
 import { ExecutionJobStatus, ExecutionStepStatus } from "./execution-status.js";
+import { approverClauseSchema } from "../../approval/types.js";
 import { z } from "zod";
 //#region src/protocol/messages/orchestrator-agent.ts
 /**
+* Cache write scope for a job's user-facing cache.
+*
+* - `shared` — trusted ref (default branch / write-permission contributor):
+*   reads AND writes the org-shared default-branch scope.
+* - `isolated` — untrusted ref (fork PR / unknown contributor): reads the
+*   shared scope as a fallback but writes only into a per-run isolated scope,
+*   so an untrusted ref can never poison the shared cache (GitHub Actions model).
+*/
+const CacheRefScope = z.enum(["shared", "isolated"]);
+/**
 * Structured git-clone auth material. Carries everything the agent needs to
 * authenticate a single `git clone`:
 *
@@ -109,7 +120,18 @@ const jobDispatchSchema = z.object({
 	* is stripped at resolution time). For use with a customer-committed
 	* `.kici/.npmrc` containing `${VAR}` placeholders.
 	*/
-	installEnvSecrets: z.record(z.string(), z.string()).optional()
+	installEnvSecrets: z.record(z.string(), z.string()).optional(),
+	/** Org id that owns this run — namespaces the user-facing cache (per-tenant isolation). */
+	orgId: z.string().optional(),
+	/** Repo identifier (e.g. "owner/repo") — second namespacing level for the user-facing cache. */
+	repoId: z.string().optional(),
+	/**
+	* Cache write scope for this job. `shared` lets the job write the
+	* org-shared default-branch cache; `isolated` confines writes to a
+	* per-run scope while still allowing shared-scope reads. Absent ⇒ treated
+	* 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({
@@ -222,6 +244,44 @@ const jobStatusSchema = z.object({
 		encrypted: z.string()
 	})).optional()
 });
+/** Reasons an agent can refuse a job.dispatch. */
+const JobRejectReason = z.enum(["busy", "draining"]);
+/**
+* Explicit dispatch rejection (agent -> orchestrator).
+*
+* Sent when the agent cannot accept a job.dispatch (already running a job,
+* or draining). The orchestrator undoes its dispatch accounting and requeues
+* the job for another agent. Protocol invariant: every job.dispatch is
+* answered — accepted with `job.ack` (a `job.status` with state `running`
+* also resolves the deadline), or refused with this message. An unanswered
+* dispatch is treated as lost once the ack deadline expires (requeue +
+* disconnect the agent) and is also covered by disconnect-time triage.
+*/
+const jobRejectSchema = z.object({
+	type: z.literal("job.reject"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	reason: JobRejectReason,
+	timestamp: z.number()
+});
+/**
+* Positive dispatch acknowledgment (agent -> orchestrator).
+*
+* Sent immediately when the agent receives a job.dispatch and accepts it
+* (after the drain/busy checks, before execution begins). The orchestrator
+* arms a deadline when it sends a dispatch; `job.ack`, `job.reject`, or a
+* `job.status` with state `running` resolves it. A dispatch with no answer
+* inside the deadline is treated as lost: the orchestrator requeues the job
+* and disconnects the unresponsive agent.
+*/
+const jobAckSchema = z.object({
+	type: z.literal("job.ack"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	timestamp: z.number()
+});
 /**
 * Streaming log chunk from step execution (agent -> orchestrator).
 *
@@ -361,6 +421,56 @@ const cacheUploadCompleteSchema = z.object({
 	/** SHA-256 hash of the dependency tarball for integrity verification. Only present for deps uploads. */
 	depsHash: z.string().optional()
 });
+/** Agent -> Orchestrator: request a user-cache restore (presigned download). */
+const cacheUserRestoreRequestSchema = z.object({
+	type: z.literal("cache.user.restore.request"),
+	messageId: z.string(),
+	jobId: z.string(),
+	/** Exact cache key. */
+	key: z.string(),
+	/** Ordered prefix fallbacks (newest matching entry wins). */
+	restoreKeys: z.array(z.string()).optional()
+});
+/** Orchestrator -> Agent: presigned download URL + matched key + tar hash, or a miss. */
+const cacheUserRestoreResponseSchema = z.object({
+	type: z.literal("cache.user.restore.response"),
+	requestId: z.string(),
+	/** True when an entry matched (exact or prefix). */
+	hit: z.boolean(),
+	/** Full key that matched (exact key or the matched prefix entry's full key). */
+	matchedKey: z.string().optional(),
+	/** Presigned GET URL for the matched tarball. Present only on hit. */
+	downloadUrl: z.string().optional(),
+	/** SHA-256 of the tarball bytes for integrity verification on download. */
+	tarHash: z.string().optional()
+});
+/** Agent -> Orchestrator: request a presigned PUT for a user-cache save (immutable; may decline if key exists). */
+const cacheUserSaveRequestSchema = z.object({
+	type: z.literal("cache.user.save.request"),
+	messageId: z.string(),
+	jobId: z.string(),
+	key: z.string()
+});
+/** Orchestrator -> Agent: presigned PUT URL, or `skip` when the immutable key already exists. */
+const cacheUserSaveResponseSchema = z.object({
+	type: z.literal("cache.user.save.response"),
+	requestId: z.string(),
+	/** Presigned PUT URL to the temp object. Absent when `skip` is true. */
+	uploadUrl: z.string().optional(),
+	/** True when the exact key already exists (immutable no-op). */
+	skip: z.boolean()
+});
+/** Agent -> Orchestrator: confirm a user-cache upload finished; orchestrator commits temp -> final + sets metadata. */
+const cacheUserSaveCompleteSchema = z.object({
+	type: z.literal("cache.user.save.complete"),
+	messageId: z.string(),
+	jobId: z.string(),
+	key: z.string(),
+	/** SHA-256 of the tarball bytes. */
+	tarHash: z.string(),
+	/** Tarball size in bytes (drives quota accounting). */
+	sizeBytes: z.number().int().nonnegative()
+});
 /** Agent -> Orchestrator: emit a custom event from a running workflow step. */
 const eventEmitSchema = z.object({
 	type: z.literal("event.emit"),
@@ -445,6 +555,82 @@ const agentApiResponseSchema = z.object({
 	/** Error description (present on failure). */
 	error: z.string().optional()
 });
+/** Orchestrator asks an agent for its log/diagnostic mini-bundle. */
+const fleetLogsRequestSchema = z.object({
+	type: z.literal("fleet.logs.request"),
+	/** UUID correlating the chunked response. */
+	requestId: z.string(),
+	/** Hours of log history to include. */
+	logWindowHours: z.number(),
+	/** Per-node cap on raw log bytes. */
+	maxBytes: z.number()
+});
+/** One base64 frame of an agent's mini-bundle ZIP. */
+const fleetBundleChunkSchema = z.object({
+	type: z.literal("fleet.bundle.chunk"),
+	requestId: z.string(),
+	seq: z.number().int().nonnegative(),
+	isLast: z.boolean(),
+	dataB64: z.string()
+});
+/** Agent failed to build/stream its mini-bundle. */
+const fleetBundleErrorSchema = z.object({
+	type: z.literal("fleet.bundle.error"),
+	requestId: z.string(),
+	message: z.string()
+});
+/** Outcome of a step-level approval hold, sent back to the waiting agent. */
+const StepApprovalOutcome = z.enum([
+	"approved",
+	"rejected",
+	"expired"
+]);
+/**
+* Agent -> Orchestrator: a step carrying `requireApproval` is about to run and
+* the agent is blocking its step loop until the orchestrator resolves the
+* approval. The orchestrator creates a step-scoped `held_runs` row from the
+* normalized requirement and replies with `step.approval-resolved` once the
+* hold is approved, rejected, or expired. The agent keeps heartbeats flowing
+* during the wait so it is not reaped as stale.
+*
+* NOT fast-pathed — the `log.chunk` / `heartbeat` manual-validator invariant is
+* untouched by this message.
+*/
+const stepApprovalRequestSchema = z.object({
+	type: z.literal("step.approval-request"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number().int().nonnegative(),
+	stepName: z.string(),
+	/** AND-list of approver clauses (empty = any approval-capable member). */
+	clauses: z.array(approverClauseSchema),
+	/** Human label for the gate (from the SDK `requireApproval` reason). */
+	reason: z.string(),
+	/**
+	* Per-gate timeout override (seconds) from the SDK `requireApproval.timeout`.
+	* Absent ⇒ the orchestrator uses the org-default `approval_expiry_seconds`.
+	* The orchestrator owns the authoritative `expiresAt` computation.
+	*/
+	timeoutSeconds: z.number().int().positive().optional()
+});
+/**
+* Orchestrator -> Agent: resolution of a step-level approval hold. `requestId`
+* correlates to the originating `step.approval-request.messageId`. On
+* `approved` the agent runs the step with its live workspace intact; on
+* `rejected`/`expired` it fails the job with a clear reason.
+*/
+const stepApprovalResolvedSchema = z.object({
+	type: z.literal("step.approval-resolved"),
+	/** Correlates to the originating step.approval-request messageId. */
+	requestId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number().int().nonnegative(),
+	outcome: StepApprovalOutcome,
+	/** Optional human reason (e.g. the reject reason). */
+	reason: z.string().optional()
+});
 /** All messages that flow from Orchestrator to Agent. */
 const orchestratorToAgentMessageSchema = z.discriminatedUnion("type", [
 	jobDispatchSchema,
@@ -452,16 +638,22 @@ const orchestratorToAgentMessageSchema = z.discriminatedUnion("type", [
 	registerAckSchema,
 	jobConcurrencyAckSchema,
 	cacheUploadResponseSchema,
+	cacheUserRestoreResponseSchema,
+	cacheUserSaveResponseSchema,
 	eventEmitResponseSchema,
 	agentApiResponseSchema,
 	agentAuthSuccessSchema,
-	agentAuthFailureSchema
+	agentAuthFailureSchema,
+	fleetLogsRequestSchema,
+	stepApprovalResolvedSchema
 ]);
 /** All messages that flow from Agent to Orchestrator. */
 const agentToOrchestratorMessageSchema = z.discriminatedUnion("type", [
 	agentRegisterSchema,
 	agentStatusSchema,
 	jobStatusSchema,
+	jobRejectSchema,
+	jobAckSchema,
 	agentLogChunkSchema,
 	agentStepStatusSchema,
 	jobHeartbeatSchema,
@@ -470,12 +662,18 @@ const agentToOrchestratorMessageSchema = z.discriminatedUnion("type", [
 	configAckSchema,
 	cacheUploadRequestSchema,
 	cacheUploadCompleteSchema,
+	cacheUserRestoreRequestSchema,
+	cacheUserSaveRequestSchema,
+	cacheUserSaveCompleteSchema,
 	eventEmitSchema,
 	agentApiRequestSchema,
 	agentMetricsSchema,
-	agentAuthRequestSchema
+	agentAuthRequestSchema,
+	fleetBundleChunkSchema,
+	fleetBundleErrorSchema,
+	stepApprovalRequestSchema
 ]);
 //#endregion
-export { agentApiRequestSchema, agentApiResponseSchema, agentAuthFailureSchema, agentAuthRequestSchema, agentAuthSuccessSchema, agentLogChunkSchema, agentMetricsSchema, agentRegisterSchema, agentStatusSchema, agentStepStatusSchema, agentToOrchestratorMessageSchema, configAckSchema, eventEmitResponseSchema, eventEmitSchema, gitAuthSchema, jobCancelSchema, jobConcurrencyAckSchema, jobConcurrencyReportSchema, jobDispatchSchema, jobStatusSchema, orchestratorToAgentMessageSchema, registerAckSchema };
+export { CacheRefScope, JobRejectReason, StepApprovalOutcome, agentApiRequestSchema, agentApiResponseSchema, agentAuthFailureSchema, agentAuthRequestSchema, agentAuthSuccessSchema, agentLogChunkSchema, agentMetricsSchema, agentRegisterSchema, agentStatusSchema, agentStepStatusSchema, agentToOrchestratorMessageSchema, cacheUserRestoreRequestSchema, cacheUserRestoreResponseSchema, cacheUserSaveCompleteSchema, cacheUserSaveRequestSchema, cacheUserSaveResponseSchema, configAckSchema, eventEmitResponseSchema, eventEmitSchema, fleetBundleChunkSchema, fleetBundleErrorSchema, fleetLogsRequestSchema, gitAuthSchema, jobAckSchema, jobCancelSchema, jobConcurrencyAckSchema, jobConcurrencyReportSchema, jobDispatchSchema, jobRejectSchema, jobStatusSchema, orchestratorToAgentMessageSchema, registerAckSchema, stepApprovalRequestSchema, stepApprovalResolvedSchema };
 
 //# sourceMappingURL=orchestrator-agent.js.map