@kici-dev/engine 0.0.0 → 0.1.1

package/dist/protocol/messages/event-log.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/**
+ * Outcome of webhook processing on the orchestrator.
+ *
+ * - `received` — row written before processing started (e.g. oversized payload
+ *   path that records the row but defers further work to the standard pipeline).
+ * - `processed` — webhook was processed and at least one workflow was
+ *   evaluated. `matched_count` carries how many actually matched.
+ * - `duplicate` — dedup cache rejected the delivery.
+ * - `lockfile_missing` — repo lookup succeeded but no lock file was found
+ *   (and no global workflows matched either).
+ * - `failed` — pipeline threw an unhandled error. `error_message` carries
+ *   the message.
+ */
+export declare const EventLogStatus: z.ZodEnum<{
+    failed: "failed";
+    received: "received";
+    processed: "processed";
+    duplicate: "duplicate";
+    lockfile_missing: "lockfile_missing";
+}>;
+export type EventLogStatus = z.infer<typeof EventLogStatus>;
+/**
+ * Reason the payload was NOT stored to object storage.
+ *
+ * - `size_exceeded` — body exceeded the configured `eventLog.maxPayloadBytes`
+ *   soft cap. The DB row is still written (with the hash + actual size) so the
+ *   delivery is visible in the dashboard; the body itself can be retrieved
+ *   from `KICI_WEBHOOK_PAYLOAD_DIR` or raw logs by hash if needed.
+ * - `storage_failed` — upload to LogStorage threw. The DB row is still
+ *   written so the operator can investigate; the failure is logged at error
+ *   level by the writer.
+ */
+export declare const PayloadOmittedReason: z.ZodEnum<{
+    size_exceeded: "size_exceeded";
+    storage_failed: "storage_failed";
+}>;
+export type PayloadOmittedReason = z.infer<typeof PayloadOmittedReason>;
+/**
+ * Where the webhook arrived.
+ * - `relay` — Platform-Orchestrator WS relay path.
+ * - `direct` — Direct HTTP ingress (independent / hybrid mode).
+ */
+export declare const EventLogSource: z.ZodEnum<{
+    relay: "relay";
+    direct: "direct";
+}>;
+export type EventLogSource = z.infer<typeof EventLogSource>;
+//# sourceMappingURL=event-log.d.ts.map

package/dist/protocol/messages/event-log.js

@@ -0,0 +1,45 @@
+import "../../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/protocol/messages/event-log.ts
+/**
+* Outcome of webhook processing on the orchestrator.
+*
+* - `received` — row written before processing started (e.g. oversized payload
+*   path that records the row but defers further work to the standard pipeline).
+* - `processed` — webhook was processed and at least one workflow was
+*   evaluated. `matched_count` carries how many actually matched.
+* - `duplicate` — dedup cache rejected the delivery.
+* - `lockfile_missing` — repo lookup succeeded but no lock file was found
+*   (and no global workflows matched either).
+* - `failed` — pipeline threw an unhandled error. `error_message` carries
+*   the message.
+*/
+const EventLogStatus = z.enum([
+	"received",
+	"processed",
+	"duplicate",
+	"lockfile_missing",
+	"failed"
+]);
+/**
+* Reason the payload was NOT stored to object storage.
+*
+* - `size_exceeded` — body exceeded the configured `eventLog.maxPayloadBytes`
+*   soft cap. The DB row is still written (with the hash + actual size) so the
+*   delivery is visible in the dashboard; the body itself can be retrieved
+*   from `KICI_WEBHOOK_PAYLOAD_DIR` or raw logs by hash if needed.
+* - `storage_failed` — upload to LogStorage threw. The DB row is still
+*   written so the operator can investigate; the failure is logged at error
+*   level by the writer.
+*/
+const PayloadOmittedReason = z.enum(["size_exceeded", "storage_failed"]);
+/**
+* Where the webhook arrived.
+* - `relay` — Platform-Orchestrator WS relay path.
+* - `direct` — Direct HTTP ingress (independent / hybrid mode).
+*/
+const EventLogSource = z.enum(["relay", "direct"]);
+//#endregion
+export { EventLogSource, EventLogStatus, PayloadOmittedReason };
+
+//# sourceMappingURL=event-log.js.map

package/dist/protocol/messages/execution-status.d.ts

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+/** Status values for execution runs (execution_runs table). */
+export declare const ExecutionRunStatus: z.ZodEnum<{
+    success: "success";
+    pending: "pending";
+    running: "running";
+    failed: "failed";
+    cancelled: "cancelled";
+    cancelling: "cancelling";
+}>;
+export type ExecutionRunStatus = z.infer<typeof ExecutionRunStatus>;
+/** Status values for execution jobs (execution_jobs table + job.status protocol messages). */
+export declare const ExecutionJobStatus: z.ZodEnum<{
+    success: "success";
+    pending: "pending";
+    running: "running";
+    failed: "failed";
+    cancelled: "cancelled";
+    cancelling: "cancelling";
+    queued: "queued";
+    recovering: "recovering";
+    skipped: "skipped";
+    timed_out_stale: "timed_out_stale";
+    drift_dropped: "drift_dropped";
+}>;
+export type ExecutionJobStatus = z.infer<typeof ExecutionJobStatus>;
+/** Status values for execution steps (execution_steps table + step.status protocol messages). */
+export declare const ExecutionStepStatus: z.ZodEnum<{
+    success: "success";
+    running: "running";
+    failed: "failed";
+    skipped: "skipped";
+}>;
+export type ExecutionStepStatus = z.infer<typeof ExecutionStepStatus>;
+/** Terminal run states that indicate the run has completed. */
+export declare const TERMINAL_RUN_STATES: ReadonlySet<string>;
+/** Terminal job states that indicate the job is no longer running. */
+export declare const TERMINAL_JOB_STATES: ReadonlySet<string>;
+/** Structured execution status update for Platform metadata tracking. */
+export declare const executionStatusSchema: z.ZodObject<{
+    type: z.ZodLiteral<"execution.status">;
+    messageId: z.ZodString;
+    runId: z.ZodString;
+    workflowName: z.ZodString;
+    status: z.ZodEnum<{
+        success: "success";
+        pending: "pending";
+        running: "running";
+        failed: "failed";
+        cancelled: "cancelled";
+        cancelling: "cancelling";
+    }>;
+    repoIdentifier: z.ZodOptional<z.ZodString>;
+    sha: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    triggerEvent: z.ZodOptional<z.ZodString>;
+    commitMessage: z.ZodOptional<z.ZodString>;
+    jobCount: z.ZodOptional<z.ZodNumber>;
+    startedAt: z.ZodNumber;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodNumber;
+    parentRunId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    originalRunId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    triggeredBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    failureReason: z.ZodOptional<z.ZodString>;
+    logBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Per-step status forwarded from agent to Platform (real-time). */
+export declare const stepStatusForwardSchema: z.ZodObject<{
+    type: z.ZodLiteral<"step.status.forward">;
+    messageId: z.ZodString;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    jobName: z.ZodString;
+    stepIndex: z.ZodNumber;
+    stepName: z.ZodString;
+    state: z.ZodEnum<{
+        success: "success";
+        running: "running";
+        failed: "failed";
+        skipped: "skipped";
+    }>;
+    timestamp: z.ZodNumber;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    secretsAccessed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Per-job status forwarded from orchestrator to Platform (real-time). */
+export declare const jobStatusForwardSchema: z.ZodObject<{
+    type: z.ZodLiteral<"job.status.forward">;
+    messageId: z.ZodString;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    jobName: z.ZodString;
+    status: z.ZodEnum<{
+        success: "success";
+        pending: "pending";
+        running: "running";
+        failed: "failed";
+        cancelled: "cancelled";
+        cancelling: "cancelling";
+        queued: "queued";
+        recovering: "recovering";
+        skipped: "skipped";
+        timed_out_stale: "timed_out_stale";
+        drift_dropped: "drift_dropped";
+    }>;
+    matrixValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    errorMessage: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    orchestratorId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runsOnLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    logBytes: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+/** State replay sent on orchestrator reconnection -- full snapshot of active runs and jobs. */
+export declare const stateReplaySchema: z.ZodObject<{
+    type: z.ZodLiteral<"state.replay">;
+    messageId: z.ZodString;
+    runs: z.ZodArray<z.ZodObject<{
+        runId: z.ZodString;
+        workflowName: z.ZodString;
+        status: z.ZodEnum<{
+            success: "success";
+            pending: "pending";
+            running: "running";
+            failed: "failed";
+            cancelled: "cancelled";
+            cancelling: "cancelling";
+        }>;
+        routingKey: z.ZodOptional<z.ZodString>;
+        repoIdentifier: z.ZodOptional<z.ZodString>;
+        sha: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        triggerEvent: z.ZodOptional<z.ZodString>;
+        commitMessage: z.ZodOptional<z.ZodString>;
+        jobCount: z.ZodNumber;
+        startedAt: z.ZodNumber;
+        completedAt: z.ZodOptional<z.ZodNumber>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        parentRunId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        originalRunId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        triggeredBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        failureReason: z.ZodOptional<z.ZodString>;
+        jobs: z.ZodArray<z.ZodObject<{
+            jobId: z.ZodString;
+            jobName: z.ZodString;
+            status: z.ZodString;
+            startedAt: z.ZodOptional<z.ZodNumber>;
+            completedAt: z.ZodOptional<z.ZodNumber>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+            errorMessage: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            agentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            runsOnLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+export type ExecutionStatus = z.infer<typeof executionStatusSchema>;
+export type StepStatusForward = z.infer<typeof stepStatusForwardSchema>;
+//# sourceMappingURL=execution-status.d.ts.map

package/dist/protocol/messages/execution-status.js

@@ -0,0 +1,166 @@
+import "../../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/protocol/messages/execution-status.ts
+/** Status values for execution runs (execution_runs table). */
+const ExecutionRunStatus = z.enum([
+	"pending",
+	"running",
+	"success",
+	"failed",
+	"cancelled",
+	"cancelling"
+]);
+/** Status values for execution jobs (execution_jobs table + job.status protocol messages). */
+const ExecutionJobStatus = z.enum([
+	"pending",
+	"queued",
+	"running",
+	"recovering",
+	"cancelling",
+	"success",
+	"failed",
+	"cancelled",
+	"skipped",
+	"timed_out_stale",
+	"drift_dropped"
+]);
+/** Status values for execution steps (execution_steps table + step.status protocol messages). */
+const ExecutionStepStatus = z.enum([
+	"running",
+	"success",
+	"failed",
+	"skipped"
+]);
+/** Terminal run states that indicate the run has completed. */
+const TERMINAL_RUN_STATES = new Set([
+	ExecutionRunStatus.enum.success,
+	ExecutionRunStatus.enum.failed,
+	ExecutionRunStatus.enum.cancelled
+]);
+/** Terminal job states that indicate the job is no longer running. */
+const TERMINAL_JOB_STATES = new Set([
+	ExecutionJobStatus.enum.success,
+	ExecutionJobStatus.enum.failed,
+	ExecutionJobStatus.enum.cancelled,
+	ExecutionJobStatus.enum.skipped,
+	ExecutionJobStatus.enum.timed_out_stale,
+	ExecutionJobStatus.enum.drift_dropped
+]);
+/** Structured execution status update for Platform metadata tracking. */
+const executionStatusSchema = z.object({
+	type: z.literal("execution.status"),
+	messageId: z.string(),
+	runId: z.string(),
+	workflowName: z.string(),
+	status: ExecutionRunStatus,
+	repoIdentifier: z.string().optional(),
+	sha: z.string().optional(),
+	/** Git branch or tag (e.g. "main", "refs/tags/v1.0"). */
+	ref: z.string().optional(),
+	/** Trigger event type (e.g. "push", "pr:open"). */
+	triggerEvent: z.string().optional(),
+	/** First line of the commit message. */
+	commitMessage: z.string().optional(),
+	jobCount: z.number().optional(),
+	startedAt: z.number(),
+	completedAt: z.number().optional(),
+	durationMs: z.number().optional(),
+	timestamp: z.number(),
+	/** Parent run ID for re-run lineage (null/undefined for original runs). */
+	parentRunId: z.string().nullable().optional(),
+	/** Root ancestor run ID for re-run lineage (null/undefined for original runs). Always points to the first run in the chain. */
+	originalRunId: z.string().nullable().optional(),
+	/** User identity that triggered this re-run (null/undefined for webhook-triggered). */
+	triggeredBy: z.string().nullable().optional(),
+	/** Human-readable reason why the run failed (only present for failed runs). */
+	failureReason: z.string().optional(),
+	/**
+	* Total raw log bytes accumulated across all jobs of this run, summed by the
+	* orchestrator from per-step `logBytesStreamed` values reported by the agent.
+	* Only set on terminal run states. Powers the operator-side
+	* `kici_org_log_bytes` capacity-planning gauge on the Platform.
+	*/
+	logBytes: z.number().int().nonnegative().optional()
+});
+/** Per-step status forwarded from agent to Platform (real-time). */
+const stepStatusForwardSchema = z.object({
+	type: z.literal("step.status.forward"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	jobName: z.string(),
+	stepIndex: z.number(),
+	stepName: z.string(),
+	state: ExecutionStepStatus,
+	timestamp: z.number(),
+	data: z.record(z.string(), z.unknown()).optional(),
+	/** Secret key names accessed by this step. Forwarded from agent for dashboard display. */
+	secretsAccessed: z.array(z.string()).optional()
+});
+/** Per-job status forwarded from orchestrator to Platform (real-time). */
+const jobStatusForwardSchema = z.object({
+	type: z.literal("job.status.forward"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	jobName: z.string(),
+	status: ExecutionJobStatus,
+	matrixValues: z.record(z.string(), z.unknown()).optional(),
+	startedAt: z.number().optional(),
+	completedAt: z.number().optional(),
+	durationMs: z.number().optional(),
+	errorMessage: z.string().nullable().optional(),
+	agentId: z.string().nullable().optional(),
+	orchestratorId: z.string().nullable().optional(),
+	/** Labels used for agent routing. */
+	runsOnLabels: z.array(z.string()).optional(),
+	/**
+	* Total raw log bytes accumulated across all steps of this job, summed by
+	* the orchestrator from per-step `logBytesStreamed` values reported by the
+	* agent. Only set on terminal job states. Powers the operator-side
+	* `kici_org_log_bytes` capacity-planning gauge on the Platform.
+	*/
+	logBytes: z.number().int().nonnegative().optional(),
+	timestamp: z.number()
+});
+/** State replay sent on orchestrator reconnection -- full snapshot of active runs and jobs. */
+const stateReplaySchema = z.object({
+	type: z.literal("state.replay"),
+	messageId: z.string(),
+	runs: z.array(z.object({
+		runId: z.string(),
+		workflowName: z.string(),
+		status: ExecutionRunStatus,
+		routingKey: z.string().optional(),
+		repoIdentifier: z.string().optional(),
+		sha: z.string().optional(),
+		ref: z.string().optional(),
+		triggerEvent: z.string().optional(),
+		commitMessage: z.string().optional(),
+		jobCount: z.number(),
+		startedAt: z.number(),
+		completedAt: z.number().optional(),
+		durationMs: z.number().optional(),
+		parentRunId: z.string().nullable().optional(),
+		originalRunId: z.string().nullable().optional(),
+		triggeredBy: z.string().nullable().optional(),
+		/** Human-readable reason why the run failed (only present for failed runs). */
+		failureReason: z.string().optional(),
+		jobs: z.array(z.object({
+			jobId: z.string(),
+			jobName: z.string(),
+			status: z.string(),
+			startedAt: z.number().optional(),
+			completedAt: z.number().optional(),
+			durationMs: z.number().optional(),
+			errorMessage: z.string().nullable().optional(),
+			agentId: z.string().nullable().optional(),
+			runsOnLabels: z.array(z.string()).optional()
+		}))
+	})),
+	timestamp: z.number()
+});
+//#endregion
+export { ExecutionJobStatus, ExecutionRunStatus, ExecutionStepStatus, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES, executionStatusSchema, jobStatusForwardSchema, stateReplaySchema, stepStatusForwardSchema };
+
+//# sourceMappingURL=execution-status.js.map

package/dist/protocol/messages/join.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+/** Join request sent by a new orchestrator (via Platform relay or direct peer). */
+export declare const joinRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"join.request">;
+    messageId: z.ZodOptional<z.ZodString>;
+    token: z.ZodString;
+}, z.core.$strip>;
+/** Join response from an existing orchestrator back to the joiner. */
+export declare const joinResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"join.response">;
+    messageId: z.ZodOptional<z.ZodString>;
+    success: z.ZodBoolean;
+    encryptedBundle: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type JoinRequest = z.infer<typeof joinRequestSchema>;
+export type JoinResponse = z.infer<typeof joinResponseSchema>;
+//# sourceMappingURL=join.d.ts.map

package/dist/protocol/messages/join.js

@@ -0,0 +1,28 @@
+import "../../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/protocol/messages/join.ts
+/** Join request sent by a new orchestrator (via Platform relay or direct peer). */
+const joinRequestSchema = z.object({
+	type: z.literal("join.request"),
+	/** Correlation ID for Platform relay routing. Platform injects this on relay to match
+	*  join.response back to the correct joining orchestrator when multiple joiners
+	*  are active concurrently. */
+	messageId: z.string().optional(),
+	/** The full join token: kici_join_v1.<base64url_routing>.<secret_hex> */
+	token: z.string()
+});
+/** Join response from an existing orchestrator back to the joiner. */
+const joinResponseSchema = z.object({
+	type: z.literal("join.response"),
+	/** Correlation ID echoed from join.request for Platform relay routing. */
+	messageId: z.string().optional(),
+	success: z.boolean(),
+	/** Base64-encoded AES-256-GCM encrypted config bundle (present on success). */
+	encryptedBundle: z.string().optional(),
+	/** Error message (present on failure). */
+	error: z.string().optional()
+});
+//#endregion
+export { joinRequestSchema, joinResponseSchema };
+
+//# sourceMappingURL=join.js.map

package/dist/protocol/messages/log-pull.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+/** Log pull messages flowing from Platform to Orchestrator. */
+export declare const logPullPlatformToOrchSchema: z.ZodObject<{
+    type: z.ZodLiteral<"log.request">;
+    messageId: z.ZodString;
+    executionId: z.ZodString;
+    jobName: z.ZodOptional<z.ZodString>;
+    stepIndex: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Log pull messages flowing from Orchestrator to Platform. */
+export declare const logPullOrchToPlatformSchema: z.ZodObject<{
+    type: z.ZodLiteral<"log.response">;
+    messageId: z.ZodString;
+    executionId: z.ZodString;
+    chunks: z.ZodArray<z.ZodObject<{
+        jobName: z.ZodString;
+        stepIndex: z.ZodNumber;
+        lines: z.ZodArray<z.ZodString>;
+        timestamp: z.ZodNumber;
+    }, z.core.$strip>>;
+    cursor: z.ZodOptional<z.ZodNumber>;
+    complete: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=log-pull.d.ts.map

package/dist/protocol/messages/log-pull.js

@@ -0,0 +1,36 @@
+import "../../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/protocol/messages/log-pull.ts
+/** Request historical logs for a completed or running execution. */
+const logRequestSchema = z.object({
+	type: z.literal("log.request"),
+	messageId: z.string(),
+	executionId: z.string(),
+	jobName: z.string().optional(),
+	stepIndex: z.number().optional(),
+	cursor: z.number().optional(),
+	limit: z.number().optional()
+});
+/** Response with log data (correlates to log.request). */
+const logResponseSchema = z.object({
+	type: z.literal("log.response"),
+	messageId: z.string(),
+	executionId: z.string(),
+	chunks: z.array(z.object({
+		jobName: z.string(),
+		stepIndex: z.number(),
+		lines: z.array(z.string()),
+		timestamp: z.number()
+	})),
+	cursor: z.number().optional(),
+	complete: z.boolean(),
+	error: z.string().optional()
+});
+/** Log pull messages flowing from Platform to Orchestrator. */
+const logPullPlatformToOrchSchema = logRequestSchema;
+/** Log pull messages flowing from Orchestrator to Platform. */
+const logPullOrchToPlatformSchema = logResponseSchema;
+//#endregion
+export { logPullOrchToPlatformSchema, logPullPlatformToOrchSchema };
+
+//# sourceMappingURL=log-pull.js.map

package/dist/protocol/messages/observe.d.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+/** Subscribe to observe a running test execution. */
+export declare const observeSubscribeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"observe.subscribe">;
+    runId: z.ZodString;
+    token: z.ZodString;
+    lastSeenSequence: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Run status update sent to observer. */
+export declare const observeStatusSchema: z.ZodObject<{
+    type: z.ZodLiteral<"observe.status">;
+    runId: z.ZodString;
+    status: z.ZodEnum<{
+        success: "success";
+        pending: "pending";
+        running: "running";
+        failed: "failed";
+        cancelled: "cancelled";
+        cancelling: "cancelling";
+    }>;
+    jobName: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+/** Log chunk sent to observer. */
+export declare const observeLogSchema: z.ZodObject<{
+    type: z.ZodLiteral<"observe.log">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    jobName: z.ZodString;
+    stepIndex: z.ZodNumber;
+    stepName: z.ZodString;
+    lines: z.ZodArray<z.ZodString>;
+    sequence: z.ZodNumber;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+/** Step lifecycle event sent to observer. */
+export declare const observeStepSchema: z.ZodObject<{
+    type: z.ZodLiteral<"observe.step">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    jobName: z.ZodString;
+    stepName: z.ZodString;
+    state: z.ZodEnum<{
+        success: "success";
+        pending: "pending";
+        running: "running";
+        failed: "failed";
+        skipped: "skipped";
+    }>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodNumber;
+}, z.core.$strip>;
+/** Run completion summary sent to observer. */
+export declare const observeCompleteSchema: z.ZodObject<{
+    type: z.ZodLiteral<"observe.complete">;
+    runId: z.ZodString;
+    status: z.ZodEnum<{
+        success: "success";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>;
+    summary: z.ZodObject<{
+        totalDurationMs: z.ZodNumber;
+        jobs: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            status: z.ZodString;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ObserveStatus = z.infer<typeof observeStatusSchema>;
+export type ObserveLog = z.infer<typeof observeLogSchema>;
+export type ObserveStep = z.infer<typeof observeStepSchema>;
+export type ObserveComplete = z.infer<typeof observeCompleteSchema>;
+//# sourceMappingURL=observe.d.ts.map

package/dist/protocol/messages/observe.js

@@ -0,0 +1,70 @@
+import "../../chunk-gOLHoazu.js";
+import { ExecutionRunStatus } from "./execution-status.js";
+import { z } from "zod";
+//#region src/protocol/messages/observe.ts
+/** Subscribe to observe a running test execution. */
+const observeSubscribeSchema = z.object({
+	type: z.literal("observe.subscribe"),
+	runId: z.string(),
+	token: z.string(),
+	lastSeenSequence: z.number().optional()
+});
+/** Run status update sent to observer. */
+const observeStatusSchema = z.object({
+	type: z.literal("observe.status"),
+	runId: z.string(),
+	status: ExecutionRunStatus,
+	jobName: z.string().optional(),
+	timestamp: z.number()
+});
+/** Log chunk sent to observer. */
+const observeLogSchema = z.object({
+	type: z.literal("observe.log"),
+	runId: z.string(),
+	jobId: z.string(),
+	jobName: z.string(),
+	stepIndex: z.number(),
+	stepName: z.string(),
+	lines: z.array(z.string()),
+	sequence: z.number(),
+	timestamp: z.number()
+});
+/** Step lifecycle event sent to observer. */
+const observeStepSchema = z.object({
+	type: z.literal("observe.step"),
+	runId: z.string(),
+	jobId: z.string(),
+	jobName: z.string(),
+	stepName: z.string(),
+	state: z.enum([
+		"pending",
+		"running",
+		"success",
+		"failed",
+		"skipped"
+	]),
+	durationMs: z.number().optional(),
+	timestamp: z.number()
+});
+/** Run completion summary sent to observer. */
+const observeCompleteSchema = z.object({
+	type: z.literal("observe.complete"),
+	runId: z.string(),
+	status: z.enum([
+		"success",
+		"failed",
+		"cancelled"
+	]),
+	summary: z.object({
+		totalDurationMs: z.number(),
+		jobs: z.array(z.object({
+			name: z.string(),
+			status: z.string(),
+			durationMs: z.number().optional()
+		}))
+	})
+});
+//#endregion
+export { observeCompleteSchema, observeLogSchema, observeStatusSchema, observeStepSchema, observeSubscribeSchema };
+
+//# sourceMappingURL=observe.js.map