@kici-dev/engine 0.0.0 → 0.1.1

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

@@ -0,0 +1,369 @@
+/**
+ * Browser-Platform WebSocket protocol schemas.
+ *
+ * Defines all message types for the browser <-> Platform WS connection:
+ * - Browser -> Platform: auth, log subscribe/unsubscribe, status subscribe/unsubscribe
+ * - Platform -> Browser: auth response, log lines, gap, run/job/step status, error
+ *
+ * Follows the same Zod-based pattern as platform-orchestrator.ts and other protocol schemas.
+ */
+import { z } from 'zod';
+/** Browser sends JWT token for authentication (first message after WS open). */
+export declare const browserAuthRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"auth.request">;
+    token: z.ZodString;
+}, z.core.$strip>;
+/** Browser sends a refreshed JWT token to extend the session. */
+export declare const browserAuthRefreshSchema: z.ZodObject<{
+    type: z.ZodLiteral<"auth.refresh">;
+    token: z.ZodString;
+}, z.core.$strip>;
+/** Browser subscribes to log lines for a specific step. */
+export declare const browserLogSubscribeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"log.subscribe">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    afterLineCount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Browser unsubscribes from log lines for a specific step. */
+export declare const browserLogUnsubscribeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"log.unsubscribe">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+}, z.core.$strip>;
+/** Browser subscribes to org-level status updates (run/job/step status changes). */
+export declare const browserStatusSubscribeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"status.subscribe">;
+    scope: z.ZodLiteral<"org">;
+    orgId: z.ZodString;
+}, z.core.$strip>;
+/** Browser unsubscribes from status updates. */
+export declare const browserStatusUnsubscribeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"status.unsubscribe">;
+}, z.core.$strip>;
+/** Browser sends a keepalive ping to prevent LB idle timeout. */
+export declare const browserPingSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+}, z.core.$strip>;
+/**
+ * Browser asks Platform to begin streaming the body of an event-log delivery.
+ *
+ * The dashboard generates `requestId` (uuid) per fetch so it can correlate
+ * incoming chunks. `orgId` is NOT taken from the wire — Platform's
+ * browser-handler resolves the run's owning org from the user's membership
+ * and gates on `event_log:read_payload`. Same trust model as the existing
+ * `log.subscribe` message.
+ */
+export declare const browserEventLogPayloadFetchSchema: z.ZodObject<{
+    type: z.ZodLiteral<"event-log.payload.fetch">;
+    requestId: z.ZodString;
+    orgId: z.ZodString;
+    deliveryId: z.ZodString;
+}, z.core.$strip>;
+/** All messages that flow from Browser to Platform. */
+export declare const browserToPlatformMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"auth.request">;
+    token: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"auth.refresh">;
+    token: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"log.subscribe">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    afterLineCount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"log.unsubscribe">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"status.subscribe">;
+    scope: z.ZodLiteral<"org">;
+    orgId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"status.unsubscribe">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"event-log.payload.fetch">;
+    requestId: z.ZodString;
+    orgId: z.ZodString;
+    deliveryId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+}, z.core.$strip>], "type">;
+/** Platform confirms browser authentication. */
+export declare const browserAuthSuccessSchema: z.ZodObject<{
+    type: z.ZodLiteral<"auth.success">;
+    connectionId: z.ZodString;
+}, z.core.$strip>;
+/** Platform rejects browser authentication. */
+export declare const browserAuthFailureSchema: z.ZodObject<{
+    type: z.ZodLiteral<"auth.failure">;
+    reason: z.ZodString;
+}, z.core.$strip>;
+/** Platform sends log lines for a subscribed step. */
+export declare const browserLogLinesSchema: z.ZodObject<{
+    type: z.ZodLiteral<"log.lines">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    lines: z.ZodArray<z.ZodString>;
+    lineCount: z.ZodNumber;
+}, z.core.$strip>;
+/** Platform notifies browser that lines were dropped due to backpressure. */
+export declare const browserGapSchema: z.ZodObject<{
+    type: z.ZodLiteral<"log.gap">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    droppedLineCount: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Reason a live-log stream was terminated by the Platform.
+ *
+ * Currently only `plan_limit_live_log_minutes` (daily live-log minute cap
+ * exceeded). New reasons land here as the Platform grows more enforcement
+ * surfaces (e.g. retention, manual operator kick).
+ */
+export declare const browserLogStreamTerminatedReason: z.ZodEnum<{
+    plan_limit_live_log_minutes: "plan_limit_live_log_minutes";
+}>;
+export type BrowserLogStreamTerminatedReason = z.infer<typeof browserLogStreamTerminatedReason>;
+/**
+ * Platform notifies browser that a live-log stream has been terminated.
+ *
+ * Sent in two cases:
+ * 1. **At subscribe time:** the org is already over the daily live-log
+ *    minute cap when the browser sends `log.subscribe`. The Platform
+ *    sends `log.stream.terminated` and never registers the subscription.
+ * 2. **Mid-stream:** the periodic metering tick observed the org just
+ *    crossed the cap. The Platform sends `log.stream.terminated` to all
+ *    active log subscribers in that org and unregisters them.
+ *
+ * Browsers should display the upgrade prompt and NOT auto-resubscribe.
+ */
+export declare const browserLogStreamTerminatedSchema: z.ZodObject<{
+    type: z.ZodLiteral<"log.stream.terminated">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    reason: z.ZodEnum<{
+        plan_limit_live_log_minutes: "plan_limit_live_log_minutes";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Platform sends a run-level status update. */
+export declare const browserRunStatusSchema: z.ZodObject<{
+    type: z.ZodLiteral<"run.status">;
+    runId: z.ZodString;
+    status: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Platform sends a job-level status update. */
+export declare const browserJobStatusSchema: z.ZodObject<{
+    type: z.ZodLiteral<"job.status">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    jobName: z.ZodString;
+    status: z.ZodString;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Platform sends a step-level status update. */
+export declare const browserStepStatusSchema: z.ZodObject<{
+    type: z.ZodLiteral<"step.status">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    stepName: z.ZodString;
+    state: z.ZodString;
+    timestamp: z.ZodNumber;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    secretsAccessed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Platform notifies browser of a new run (first-time insert, full run summary). */
+export declare const browserRunNewSchema: z.ZodObject<{
+    type: z.ZodLiteral<"run.new">;
+    runId: z.ZodString;
+    status: z.ZodString;
+    workflowName: 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;
+    orgId: z.ZodString;
+}, z.core.$strip>;
+/** Platform notifies browser of a new job (first-time insert). */
+export declare const browserJobNewSchema: z.ZodObject<{
+    type: z.ZodLiteral<"job.new">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    jobName: z.ZodString;
+    status: z.ZodString;
+    matrixValues: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Platform responds to a browser keepalive ping. */
+export declare const browserPongSchema: z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+}, z.core.$strip>;
+/** Platform sends an error to the browser. */
+export declare const browserErrorSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+/** All messages that flow from Platform to Browser. */
+export declare const platformToBrowserMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"auth.success">;
+    connectionId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"auth.failure">;
+    reason: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"log.lines">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    lines: z.ZodArray<z.ZodString>;
+    lineCount: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"log.gap">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    droppedLineCount: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"log.stream.terminated">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    reason: z.ZodEnum<{
+        plan_limit_live_log_minutes: "plan_limit_live_log_minutes";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"run.status">;
+    runId: z.ZodString;
+    status: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"run.new">;
+    runId: z.ZodString;
+    status: z.ZodString;
+    workflowName: 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;
+    orgId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"job.status">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    jobName: z.ZodString;
+    status: z.ZodString;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"job.new">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    jobName: z.ZodString;
+    status: z.ZodString;
+    matrixValues: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"step.status">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    stepIndex: z.ZodNumber;
+    stepName: z.ZodString;
+    state: z.ZodString;
+    timestamp: z.ZodNumber;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    secretsAccessed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"run.event">;
+    runId: z.ZodString;
+    eventType: z.ZodString;
+    timestampMs: z.ZodNumber;
+    sourceService: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    durationMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    jobId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    stepIndex: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"job.context">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+    context: z.ZodObject<{
+        envVars: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+            category: z.ZodEnum<{
+                user: "user";
+                system: "system";
+                inherited: "inherited";
+                secret: "secret";
+            }>;
+        }, z.core.$strip>>>;
+        runtime: z.ZodOptional<z.ZodObject<{
+            nodeVersion: z.ZodOptional<z.ZodString>;
+            os: z.ZodOptional<z.ZodString>;
+            arch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        sandboxType: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        workingDirectory: z.ZodOptional<z.ZodString>;
+        gitRef: z.ZodOptional<z.ZodString>;
+        lockFileVersion: z.ZodOptional<z.ZodString>;
+        sdkVersion: z.ZodOptional<z.ZodString>;
+        depCacheStatus: z.ZodOptional<z.ZodString>;
+        networkIsolation: z.ZodOptional<z.ZodString>;
+        scalerContext: z.ZodOptional<z.ZodObject<{
+            backendType: z.ZodString;
+            scalerName: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"event-log.payload.chunk">;
+    requestId: z.ZodString;
+    seq: z.ZodNumber;
+    data: z.ZodString;
+    isLast: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodEnum<{
+        payload_unavailable: "payload_unavailable";
+        not_found: "not_found";
+        read_failed: "read_failed";
+        forbidden: "forbidden";
+        orch_stream_timeout: "orch_stream_timeout";
+        orchestrator_unavailable: "orchestrator_unavailable";
+    }>>;
+    totalBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "type">;
+export type BrowserEventLogPayloadFetch = z.infer<typeof browserEventLogPayloadFetchSchema>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/protocol/messages/browser.js

@@ -0,0 +1,225 @@
+import "../../chunk-gOLHoazu.js";
+import { browserJobContextSchema, browserRunEventSchema } from "./run-events.js";
+import { browserEventLogPayloadChunkSchema } from "./dashboard.js";
+import { z } from "zod";
+//#region src/protocol/messages/browser.ts
+/**
+* Browser-Platform WebSocket protocol schemas.
+*
+* Defines all message types for the browser <-> Platform WS connection:
+* - Browser -> Platform: auth, log subscribe/unsubscribe, status subscribe/unsubscribe
+* - Platform -> Browser: auth response, log lines, gap, run/job/step status, error
+*
+* Follows the same Zod-based pattern as platform-orchestrator.ts and other protocol schemas.
+*/
+/** Browser sends JWT token for authentication (first message after WS open). */
+const browserAuthRequestSchema = z.object({
+	type: z.literal("auth.request"),
+	token: z.string().min(1)
+});
+/** Browser sends a refreshed JWT token to extend the session. */
+const browserAuthRefreshSchema = z.object({
+	type: z.literal("auth.refresh"),
+	token: z.string().min(1)
+});
+/** Browser subscribes to log lines for a specific step. */
+const browserLogSubscribeSchema = z.object({
+	type: z.literal("log.subscribe"),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number(),
+	/** Resume from this line count (for mid-execution join after REST fetch). */
+	afterLineCount: z.number().optional()
+});
+/** Browser unsubscribes from log lines for a specific step. */
+const browserLogUnsubscribeSchema = z.object({
+	type: z.literal("log.unsubscribe"),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number()
+});
+/** Browser subscribes to org-level status updates (run/job/step status changes). */
+const browserStatusSubscribeSchema = z.object({
+	type: z.literal("status.subscribe"),
+	/** Scope of status subscription. Currently only 'org' is supported. */
+	scope: z.literal("org"),
+	/** The org to subscribe to. Required so the Platform can route updates for the correct org. */
+	orgId: z.string().min(1)
+});
+/** Browser unsubscribes from status updates. */
+const browserStatusUnsubscribeSchema = z.object({ type: z.literal("status.unsubscribe") });
+/** Browser sends a keepalive ping to prevent LB idle timeout. */
+const browserPingSchema = z.object({ type: z.literal("ping") });
+/**
+* Browser asks Platform to begin streaming the body of an event-log delivery.
+*
+* The dashboard generates `requestId` (uuid) per fetch so it can correlate
+* incoming chunks. `orgId` is NOT taken from the wire — Platform's
+* browser-handler resolves the run's owning org from the user's membership
+* and gates on `event_log:read_payload`. Same trust model as the existing
+* `log.subscribe` message.
+*/
+const browserEventLogPayloadFetchSchema = z.object({
+	type: z.literal("event-log.payload.fetch"),
+	requestId: z.string().min(1),
+	orgId: z.string().min(1),
+	deliveryId: z.string().min(1)
+});
+/** All messages that flow from Browser to Platform. */
+const browserToPlatformMessageSchema = z.discriminatedUnion("type", [
+	browserAuthRequestSchema,
+	browserAuthRefreshSchema,
+	browserLogSubscribeSchema,
+	browserLogUnsubscribeSchema,
+	browserStatusSubscribeSchema,
+	browserStatusUnsubscribeSchema,
+	browserEventLogPayloadFetchSchema,
+	browserPingSchema
+]);
+/** Platform confirms browser authentication. */
+const browserAuthSuccessSchema = z.object({
+	type: z.literal("auth.success"),
+	connectionId: z.string()
+});
+/** Platform rejects browser authentication. */
+const browserAuthFailureSchema = z.object({
+	type: z.literal("auth.failure"),
+	reason: z.string()
+});
+/** Platform sends log lines for a subscribed step. */
+const browserLogLinesSchema = z.object({
+	type: z.literal("log.lines"),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number(),
+	lines: z.array(z.string()),
+	/** Total line count (cumulative offset so browser knows position). */
+	lineCount: z.number()
+});
+/** Platform notifies browser that lines were dropped due to backpressure. */
+const browserGapSchema = z.object({
+	type: z.literal("log.gap"),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number(),
+	droppedLineCount: z.number()
+});
+/**
+* Reason a live-log stream was terminated by the Platform.
+*
+* Currently only `plan_limit_live_log_minutes` (daily live-log minute cap
+* exceeded). New reasons land here as the Platform grows more enforcement
+* surfaces (e.g. retention, manual operator kick).
+*/
+const browserLogStreamTerminatedReason = z.enum(["plan_limit_live_log_minutes"]);
+/**
+* Platform notifies browser that a live-log stream has been terminated.
+*
+* Sent in two cases:
+* 1. **At subscribe time:** the org is already over the daily live-log
+*    minute cap when the browser sends `log.subscribe`. The Platform
+*    sends `log.stream.terminated` and never registers the subscription.
+* 2. **Mid-stream:** the periodic metering tick observed the org just
+*    crossed the cap. The Platform sends `log.stream.terminated` to all
+*    active log subscribers in that org and unregisters them.
+*
+* Browsers should display the upgrade prompt and NOT auto-resubscribe.
+*/
+const browserLogStreamTerminatedSchema = z.object({
+	type: z.literal("log.stream.terminated"),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number(),
+	reason: browserLogStreamTerminatedReason,
+	/** Optional human-readable message for the dashboard to display. */
+	message: z.string().optional()
+});
+/** Platform sends a run-level status update. */
+const browserRunStatusSchema = z.object({
+	type: z.literal("run.status"),
+	runId: z.string(),
+	status: z.string(),
+	completedAt: z.number().optional(),
+	durationMs: z.number().optional()
+});
+/** Platform sends a job-level status update. */
+const browserJobStatusSchema = z.object({
+	type: z.literal("job.status"),
+	runId: z.string(),
+	jobId: z.string(),
+	jobName: z.string(),
+	status: z.string(),
+	startedAt: z.number().optional(),
+	completedAt: z.number().optional(),
+	durationMs: z.number().optional()
+});
+/** Platform sends a step-level status update. */
+const browserStepStatusSchema = z.object({
+	type: z.literal("step.status"),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number(),
+	stepName: z.string(),
+	state: z.string(),
+	timestamp: z.number(),
+	startedAt: z.number().optional(),
+	completedAt: z.number().optional(),
+	durationMs: z.number().optional(),
+	/** Secret key names accessed by this step. Present on completion states. */
+	secretsAccessed: z.array(z.string()).optional()
+});
+/** Platform notifies browser of a new run (first-time insert, full run summary). */
+const browserRunNewSchema = z.object({
+	type: z.literal("run.new"),
+	runId: z.string(),
+	status: z.string(),
+	workflowName: z.string(),
+	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(),
+	orgId: z.string()
+});
+/** Platform notifies browser of a new job (first-time insert). */
+const browserJobNewSchema = z.object({
+	type: z.literal("job.new"),
+	runId: z.string(),
+	jobId: z.string(),
+	jobName: z.string(),
+	status: z.string(),
+	matrixValues: z.record(z.string(), z.unknown()).nullable().optional(),
+	startedAt: z.number().optional()
+});
+/** Platform responds to a browser keepalive ping. */
+const browserPongSchema = z.object({ type: z.literal("pong") });
+/** Platform sends an error to the browser. */
+const browserErrorSchema = z.object({
+	type: z.literal("error"),
+	code: z.string(),
+	message: z.string()
+});
+/** All messages that flow from Platform to Browser. */
+const platformToBrowserMessageSchema = z.discriminatedUnion("type", [
+	browserAuthSuccessSchema,
+	browserAuthFailureSchema,
+	browserLogLinesSchema,
+	browserGapSchema,
+	browserLogStreamTerminatedSchema,
+	browserRunStatusSchema,
+	browserRunNewSchema,
+	browserJobStatusSchema,
+	browserJobNewSchema,
+	browserStepStatusSchema,
+	browserErrorSchema,
+	browserPongSchema,
+	browserRunEventSchema,
+	browserJobContextSchema,
+	browserEventLogPayloadChunkSchema
+]);
+//#endregion
+export { browserAuthFailureSchema, browserAuthRefreshSchema, browserAuthRequestSchema, browserAuthSuccessSchema, browserErrorSchema, browserEventLogPayloadFetchSchema, browserGapSchema, browserJobNewSchema, browserJobStatusSchema, browserLogLinesSchema, browserLogStreamTerminatedReason, browserLogStreamTerminatedSchema, browserLogSubscribeSchema, browserLogUnsubscribeSchema, browserPingSchema, browserPongSchema, browserRunNewSchema, browserRunStatusSchema, browserStatusSubscribeSchema, browserStatusUnsubscribeSchema, browserStepStatusSchema, browserToPlatformMessageSchema, platformToBrowserMessageSchema };
+
+//# sourceMappingURL=browser.js.map

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

@@ -0,0 +1,46 @@
+/**
+ * Orchestrator capability negotiation schemas.
+ *
+ * Modeled after peerCapabilitiesSchema in peer.ts.
+ * See CONTEXT.md through for design decisions.
+ *
+ * Direction: orchestrator → Platform only. The Platform is always at the latest version
+ * (centrally deployed), so Platform capabilities are unnecessary. The Platform checks
+ * orchestrator capabilities before sending feature-gated messages.
+ *
+ * Pattern: Each field indicates support for an optional protocol feature.
+ * Missing fields default to unsupported for backward compatibility.
+ * Schema uses .passthrough() so newer orchestrators sending unknown flags don't get stripped.
+ */
+import { z } from 'zod';
+/** Orchestrator role in a cluster topology. */
+export declare const OrchRole: z.ZodEnum<{
+    coordinator: "coordinator";
+    worker: "worker";
+}>;
+export type OrchRole = z.infer<typeof OrchRole>;
+/**
+ * Orchestrator-advertised capabilities sent in auth.request.
+ * Uses .passthrough() so newer orchestrators sending unknown flags are preserved.
+ */
+export declare const orchCapabilitiesSchema: z.ZodObject<{
+    orchRole: z.ZodOptional<z.ZodEnum<{
+        coordinator: "coordinator";
+        worker: "worker";
+    }>>;
+}, z.core.$loose>;
+/** Inferred type for orchestrator capabilities. */
+export type OrchCapabilities = z.infer<typeof orchCapabilitiesSchema>;
+/** Default orchestrator capabilities sent in auth.request. */
+export declare const ORCH_CAPABILITIES: Readonly<{
+    orchRole: "coordinator";
+}>;
+/**
+ * Check whether an orchestrator advertises a specific capability flag.
+ *
+ * Takes `string` (not `keyof`) because newer versions may have flags the current code
+ * doesn't know about. Returns false if capabilities is undefined (pre-capability
+ * orchestrator) or the flag is missing/false.
+ */
+export declare function hasOrchCapability(capabilities: OrchCapabilities | undefined, flag: string): boolean;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/protocol/messages/capabilities.js

@@ -0,0 +1,42 @@
+import "../../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/protocol/messages/capabilities.ts
+/**
+* Orchestrator capability negotiation schemas.
+*
+* Modeled after peerCapabilitiesSchema in peer.ts.
+* See CONTEXT.md through for design decisions.
+*
+* Direction: orchestrator → Platform only. The Platform is always at the latest version
+* (centrally deployed), so Platform capabilities are unnecessary. The Platform checks
+* orchestrator capabilities before sending feature-gated messages.
+*
+* Pattern: Each field indicates support for an optional protocol feature.
+* Missing fields default to unsupported for backward compatibility.
+* Schema uses .passthrough() so newer orchestrators sending unknown flags don't get stripped.
+*/
+/** Orchestrator role in a cluster topology. */
+const OrchRole = z.enum(["coordinator", "worker"]);
+/**
+* Orchestrator-advertised capabilities sent in auth.request.
+* Uses .passthrough() so newer orchestrators sending unknown flags are preserved.
+*/
+const orchCapabilitiesSchema = z.object({ 
+/** Orchestrator's role in the cluster (coordinator manages DB/vault, worker is stateless). */
+orchRole: OrchRole.optional() }).passthrough();
+/** Default orchestrator capabilities sent in auth.request. */
+const ORCH_CAPABILITIES = Object.freeze({ orchRole: OrchRole.enum.coordinator });
+/**
+* Check whether an orchestrator advertises a specific capability flag.
+*
+* Takes `string` (not `keyof`) because newer versions may have flags the current code
+* doesn't know about. Returns false if capabilities is undefined (pre-capability
+* orchestrator) or the flag is missing/false.
+*/
+function hasOrchCapability(capabilities, flag) {
+	return capabilities?.[flag] === true;
+}
+//#endregion
+export { ORCH_CAPABILITIES, OrchRole, hasOrchCapability, orchCapabilitiesSchema };
+
+//# sourceMappingURL=capabilities.js.map