@kici-dev/engine 0.0.0 → 0.1.1

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

@@ -0,0 +1,379 @@
+import "../../chunk-gOLHoazu.js";
+import { heartbeatSchema } from "./common.js";
+import { authFailureSchema, authRequestSchema, authSuccessSchema } from "./auth.js";
+import { executionStatusSchema, jobStatusForwardSchema, stateReplaySchema, stepStatusForwardSchema } from "./execution-status.js";
+import { sourceDeregisterAckSchema, sourceDeregisterSchema, sourceRegistrationAckSchema, sourceRegistrationSchema } from "./source-registration.js";
+import { dashboardAccessLogListRequestSchema } from "./access-log.js";
+import { dashboardOrchLogsRequestSchema, jobContextMessageSchema, runEventMessageSchema } from "./run-events.js";
+import { globalWorkflowsGetRequestSchema, globalWorkflowsUpdateRequestSchema } from "./dashboard-global-workflows.js";
+import { backendGetRequestSchema, backendSyncRequestSchema, backendTestRequestSchema, backendsListRequestSchema, backendsSyncAllRequestSchema, dashboardDiagnosticsRequestSchema, dashboardEventLogDetailRequestSchema, dashboardEventLogListRequestSchema, dashboardEventLogPayloadStreamRequestSchema, dashboardPayloadRequestSchema, dashboardRunDetailRequestSchema, dashboardScalerAgentsRequestSchema, dashboardScalerCapacityRequestSchema, dashboardStepLogsRequestSchema, envBindingsListRequestSchema, envBindingsSetRequestSchema, envCreateRequestSchema, envDeleteRequestSchema, envGetRequestSchema, envHistoryRequestSchema, envListRequestSchema, envSecretDeleteRequestSchema, envSecretScopeCreateRequestSchema, envSecretScopeDeleteRequestSchema, envSecretScopeRenameRequestSchema, envSecretSetRequestSchema, envSecretsListRequestSchema, envSourceOverrideDeleteRequestSchema, envSourceOverrideSetRequestSchema, envSourceOverridesListRequestSchema, envUpdateRequestSchema, envVarDeleteRequestSchema, envVarSetRequestSchema, envVarsListRequestSchema, heldRunApproveRequestSchema, heldRunRejectRequestSchema, heldRunsListRequestSchema, manualScheduleRequestSchema, registrationDeleteRequestSchema, registrationDisableRequestSchema, registrationsListRequestSchema, runCancelRequestSchema, runRerunRequestSchema } from "./dashboard.js";
+import { z } from "zod";
+//#region src/protocol/messages/platform-orchestrator.ts
+/** Trust policy update pushed from Platform to orchestrator when policy or identity links change. */
+const trustPolicyUpdateSchema = z.object({
+	type: z.literal("trust_policy.update"),
+	orgId: z.string(),
+	policy: z.object({
+		forkPolicy: z.enum([
+			"hold",
+			"reject",
+			"allow"
+		]),
+		unknownContributorPolicy: z.enum(["hold", "reject"]),
+		workflowChangePolicy: z.enum([
+			"hold",
+			"reject",
+			"allow"
+		]),
+		approvalExpiryHours: z.number()
+	}),
+	identityLinks: z.array(z.object({
+		userId: z.string(),
+		provider: z.string(),
+		providerUsername: z.string(),
+		/**
+		* Immutable IDP-side numeric id (e.g. GitHub's `id`).
+		* Nullable during the backfill window for legacy rows that
+		* predate the column. Trust resolver prefers this over
+		* `providerUsername` and (in the strict end-state) refuses
+		* trust when both sides have it null.
+		*/
+		providerUserId: z.string().nullish()
+	})),
+	memberCiTrustLevels: z.record(z.string(), z.enum([
+		"none",
+		"read",
+		"write",
+		"admin"
+	]))
+});
+/**
+* Internal shape of a fully-reassembled, HMAC-verified webhook relay handed
+* to the orchestrator's `onWebhookRelay` callback.
+*
+* NOT a wire-parseable schema: this shape is intentionally absent from the
+* `platformToOrchestratorMessageSchema` discriminated union so that a rogue
+* or compromised Platform process (A10) cannot fabricate one and bypass the
+* on-orchestrator HMAC verification gate. The only legitimate construction
+* site is `completeChunkedRelay` in `packages/orchestrator/src/ws/platform-client.ts`,
+* which synthesizes this shape AFTER `onVerifyInbound` returns `'accepted'`.
+*
+* Migration `packages/platform/src/db/migrations/012_drop_webhook_secret_columns.ts`
+* makes the orch-side `verifyInboundWebhook` (called from `onVerifyInbound` on
+* the chunked relay path `webhook.relay.start` / `webhook.relay.chunk`) the
+* sole trust boundary against a malicious Platform; keeping this schema OUT
+* of the wire union enforces that invariant statically.
+*/
+const webhookRelaySchema = z.object({
+	type: z.literal("webhook.relay"),
+	messageId: z.string(),
+	routingKey: z.string(),
+	deliveryId: z.string(),
+	event: z.string(),
+	action: z.string().nullish(),
+	payload: z.unknown(),
+	/** Trace ID propagated across tiers for distributed tracing. */
+	requestId: z.string().optional()
+});
+/**
+* HMAC verification + processing result returned by orchestrator in webhook.ack.
+*
+* Used in the chunked relay protocol where the orchestrator (not Platform)
+* verifies the inbound HMAC signature against its locally-stored secret.
+*
+* - `accepted`: signature verified (or method is `none`/IP allowlist OK), webhook
+*   handed to the existing webhook processing pipeline.
+* - `rejected_signature`: signature did not match any rotation secret. Maps to HTTP 401.
+* - `rejected_unknown_source`: the routing key is not registered on this orchestrator
+*   (or the provider is not yet implemented). Maps to HTTP 404 + Platform negative cache.
+* - `rejected_misconfigured`: the orchestrator has the source but its verification config
+*   is malformed (e.g. invalid JSON in generic_webhook_sources.verification_config) or
+*   the chunked stream itself was malformed (out-of-order, oversize, base64 decode fail,
+*   missing chunks at finalization, TTL expiry). Maps to HTTP 500.
+*/
+const WebhookRelayResult = z.enum([
+	"accepted",
+	"rejected_signature",
+	"rejected_unknown_source",
+	"rejected_misconfigured"
+]);
+/**
+* Maximum total body size accepted by the chunked webhook relay protocol.
+* 25 MiB matches GitHub's own webhook payload cap. Senders that need higher must
+* connect their orchestrator directly (bypassing Platform).
+*/
+const WEBHOOK_RELAY_MAX_BODY_BYTES = 25 * 1024 * 1024;
+/**
+* Recommended raw chunk size for the chunked relay protocol. 64 KiB raw becomes
+* ~85 KiB base64 in JSON; permessage-deflate compresses it well. Sender (Platform)
+* picks the actual size; receiver (orchestrator) just enforces totalSize and chunkCount.
+*/
+const WEBHOOK_RELAY_CHUNK_SIZE = 64 * 1024;
+/**
+* Start frame of the chunked webhook relay protocol (Platform -> orchestrator).
+* Carries metadata + signature inputs only; body bytes follow in subsequent
+* webhook.relay.chunk frames correlated by messageId.
+*
+* The orchestrator allocates a per-messageId reassembly buffer on receipt.
+* No webhook.ack is sent until the final chunk completes the stream.
+*/
+const webhookRelayStartSchema = z.object({
+	type: z.literal("webhook.relay.start"),
+	messageId: z.string(),
+	routingKey: z.string(),
+	deliveryId: z.string(),
+	event: z.string(),
+	action: z.string().nullish(),
+	/** Inbound HTTP signature header NAME (lowercased, e.g. `x-hub-signature-256`). */
+	signatureHeaderName: z.string().nullish(),
+	/** Inbound HTTP signature header VALUE (the claimed HMAC, e.g. `sha256=abc...`). */
+	signatureHeader: z.string().nullish(),
+	/** Inbound HTTP request client IP for IP-allowlist verification (generic webhooks). */
+	clientIp: z.string().nullish(),
+	/**
+	* Selected inbound headers the orchestrator may need (lowercased keys). Senders
+	* SHOULD include only headers the verification path uses (signature alt-name,
+	* x-hub-signature, etc.) and route metadata; bulk header forwarding is an
+	* anti-pattern.
+	*/
+	headers: z.record(z.string(), z.string()),
+	/**
+	* Total body size in bytes. Sum of decoded chunk sizes MUST equal this value;
+	* mismatch yields rejected_misconfigured. Capped at WEBHOOK_RELAY_MAX_BODY_BYTES.
+	*/
+	totalSize: z.number().int().min(0).max(WEBHOOK_RELAY_MAX_BODY_BYTES),
+	/** Number of chunk frames the orchestrator should expect (>= 1). */
+	chunkCount: z.number().int().min(1),
+	/** Trace ID propagated across tiers for distributed tracing. */
+	requestId: z.string().optional()
+});
+/**
+* One chunk of the body. Sequence is 0-indexed and MUST arrive strictly in order;
+* the final=true chunk completes the stream and triggers verify+process on the
+* orchestrator. Decoded chunk bytes (sum across the stream) MUST equal totalSize
+* declared in webhook.relay.start.
+*/
+const webhookRelayChunkSchema = z.object({
+	type: z.literal("webhook.relay.chunk"),
+	messageId: z.string(),
+	/** 0-indexed chunk number; must match the orchestrator's expected next sequence. */
+	sequence: z.number().int().min(0),
+	/** Base64-encoded chunk bytes. */
+	data: z.string(),
+	/** True on the last chunk in the stream. Triggers verify+process on the orchestrator. */
+	final: z.boolean()
+});
+/** Peer discovery notification sent by Platform when another orchestrator shares routing keys. */
+const peerDiscoverSchema = z.object({
+	type: z.literal("peer.discover"),
+	peer: z.object({
+		connectionId: z.string(),
+		/** The peer's self-reported cluster instance ID (from source.register). */
+		instanceId: z.string().optional(),
+		address: z.string().nullable(),
+		routingKeys: z.array(z.string())
+	})
+});
+/** Full peer list update pushed by Platform to all pool members when membership changes. Replaces peer.discover. */
+const peerUpdateSchema = z.object({
+	type: z.literal("peer.update"),
+	peers: z.array(z.object({
+		connectionId: z.string(),
+		instanceId: z.string().optional(),
+		address: z.string().nullable(),
+		routingKeys: z.array(z.string()),
+		orchRole: z.enum(["coordinator", "worker"]).optional()
+	}))
+});
+/**
+* Stale check run cleanup request sent by Platform when a replacement orchestrator
+* reconnects after the previous one died. Contains metadata for runs that were
+* marked timed_out_stale by Platform, so the orchestrator can update stuck GitHub
+* check runs that the dead orchestrator left as "in_progress".
+*/
+const staleCheckrunCleanupSchema = z.object({
+	type: z.literal("stale.checkrun.cleanup"),
+	runs: z.array(z.object({
+		runId: z.string(),
+		provider: z.string(),
+		routingKey: z.string(),
+		repoIdentifier: z.string(),
+		sha: z.string(),
+		workflowName: z.string(),
+		jobNames: z.array(z.string())
+	}))
+});
+/** Periodic OTel metrics push from orchestrator to Platform for centralized observability. */
+const orchMetricsSchema = z.object({
+	type: z.literal("orch.metrics"),
+	messageId: z.string(),
+	metrics: z.array(z.object({
+		name: z.string(),
+		type: z.enum([
+			"counter",
+			"histogram",
+			"gauge",
+			"upDownCounter"
+		]),
+		value: z.number().optional(),
+		labels: z.record(z.string(), z.string()).optional(),
+		buckets: z.array(z.object({
+			le: z.number(),
+			count: z.number()
+		})).optional(),
+		count: z.number().optional(),
+		sum: z.number().optional()
+	})),
+	timestamp: z.number()
+});
+/**
+* Acknowledgment that a webhook was received and processing started.
+*
+* Under the chunked relay protocol the orchestrator also reports the HMAC
+* verification outcome here via `result`, and may include a non-secret-bearing
+* diagnostic in `reason` when result is a rejection. Both fields are optional
+* for backward compatibility during the rollout: pre-cutover senders omit them.
+*/
+const webhookAckSchema = z.object({
+	type: z.literal("webhook.ack"),
+	messageId: z.string(),
+	deliveryId: z.string(),
+	/**
+	* Verification + processing outcome. Required from the chunked relay path
+	* (commit 3 onwards on the orch side); pre-chunked acks omit this.
+	*/
+	result: WebhookRelayResult.optional(),
+	/**
+	* Optional non-secret-bearing diagnostic for rejection cases. MUST NOT
+	* include any secret material (HMAC keys, bearer tokens, computed signatures).
+	*/
+	reason: z.string().nullish()
+});
+/** Execution lifecycle event reported back to Platform. */
+const executionEventSchema = z.object({
+	type: z.literal("execution.event"),
+	messageId: z.string(),
+	runId: z.string(),
+	event: z.enum([
+		"started",
+		"job_dispatched",
+		"job_completed",
+		"finished"
+	]),
+	data: z.record(z.string(), z.unknown()),
+	timestamp: z.number()
+});
+/** Streaming log chunk from job execution. */
+const logChunkSchema = z.object({
+	type: z.literal("log.chunk"),
+	messageId: z.string(),
+	runId: z.string(),
+	jobId: z.string(),
+	stepIndex: z.number(),
+	lines: z.array(z.string()),
+	timestamp: z.number()
+});
+/** Cache lookup statistics forwarded from orchestrator to Platform for centralized metrics. */
+const cacheStatsSchema = z.object({
+	type: z.literal("cache.stats"),
+	cacheType: z.enum(["source", "dep"]),
+	hit: z.boolean()
+});
+/** All messages that flow from Platform to Orchestrator.
+*
+* The single-frame `webhookRelaySchema` is intentionally NOT a member of this
+* union: that shape carries an attacker-controlled `payload` and pre-existed
+* the chunked relay's on-orch HMAC verification, so accepting it on the wire
+* would let a compromised Platform (A10) fabricate webhook deliveries that
+* bypass the only trust boundary against a malicious Platform (see the
+* docblock on `webhookRelaySchema` above and migration
+* `packages/platform/src/db/migrations/012_drop_webhook_secret_columns.ts`).
+* The chunked path `webhook.relay.start` + `webhook.relay.chunk` is the sole
+* legitimate route from Platform to `onWebhookRelay`. */
+const platformToOrchestratorMessageSchema = z.discriminatedUnion("type", [
+	webhookRelayStartSchema,
+	webhookRelayChunkSchema,
+	trustPolicyUpdateSchema,
+	sourceRegistrationAckSchema,
+	sourceDeregisterAckSchema,
+	authSuccessSchema,
+	authFailureSchema,
+	peerDiscoverSchema,
+	peerUpdateSchema,
+	staleCheckrunCleanupSchema,
+	dashboardRunDetailRequestSchema,
+	dashboardStepLogsRequestSchema,
+	runRerunRequestSchema,
+	manualScheduleRequestSchema,
+	runCancelRequestSchema,
+	dashboardPayloadRequestSchema,
+	dashboardOrchLogsRequestSchema,
+	envListRequestSchema,
+	envGetRequestSchema,
+	envCreateRequestSchema,
+	envUpdateRequestSchema,
+	envDeleteRequestSchema,
+	envVarsListRequestSchema,
+	envVarSetRequestSchema,
+	envVarDeleteRequestSchema,
+	envSourceOverridesListRequestSchema,
+	envSourceOverrideSetRequestSchema,
+	envSourceOverrideDeleteRequestSchema,
+	envBindingsListRequestSchema,
+	envBindingsSetRequestSchema,
+	envSecretsListRequestSchema,
+	envSecretSetRequestSchema,
+	envSecretDeleteRequestSchema,
+	envSecretScopeCreateRequestSchema,
+	envSecretScopeRenameRequestSchema,
+	envSecretScopeDeleteRequestSchema,
+	envHistoryRequestSchema,
+	heldRunsListRequestSchema,
+	heldRunApproveRequestSchema,
+	heldRunRejectRequestSchema,
+	registrationsListRequestSchema,
+	registrationDisableRequestSchema,
+	registrationDeleteRequestSchema,
+	dashboardDiagnosticsRequestSchema,
+	dashboardScalerCapacityRequestSchema,
+	dashboardScalerAgentsRequestSchema,
+	backendsListRequestSchema,
+	backendGetRequestSchema,
+	backendsSyncAllRequestSchema,
+	backendSyncRequestSchema,
+	backendTestRequestSchema,
+	dashboardEventLogListRequestSchema,
+	dashboardEventLogDetailRequestSchema,
+	dashboardEventLogPayloadStreamRequestSchema,
+	globalWorkflowsGetRequestSchema,
+	globalWorkflowsUpdateRequestSchema,
+	dashboardAccessLogListRequestSchema
+]);
+/** All messages that flow from Orchestrator to Platform.
+*
+* Note: Dashboard response messages (dashboard.run.detail.response,
+* dashboard.step.logs.response, dashboard.orch.logs.response) are intentionally
+* excluded here. They are parsed separately via dashboardOrchToPlatformSchema so
+* the Platform WS handler can route them to the DashboardProxy for request
+* correlation. */
+const orchestratorToPlatformMessageSchema = z.discriminatedUnion("type", [
+	webhookAckSchema,
+	executionEventSchema,
+	logChunkSchema,
+	executionStatusSchema,
+	stepStatusForwardSchema,
+	jobStatusForwardSchema,
+	stateReplaySchema,
+	sourceRegistrationSchema,
+	sourceDeregisterSchema,
+	cacheStatsSchema,
+	authRequestSchema,
+	heartbeatSchema,
+	runEventMessageSchema,
+	jobContextMessageSchema,
+	orchMetricsSchema
+]);
+//#endregion
+export { WEBHOOK_RELAY_CHUNK_SIZE, WEBHOOK_RELAY_MAX_BODY_BYTES, WebhookRelayResult, cacheStatsSchema, executionEventSchema, logChunkSchema, orchMetricsSchema, orchestratorToPlatformMessageSchema, peerDiscoverSchema, peerUpdateSchema, platformToOrchestratorMessageSchema, staleCheckrunCleanupSchema, trustPolicyUpdateSchema, webhookAckSchema, webhookRelayChunkSchema, webhookRelaySchema, webhookRelayStartSchema };
+
+//# sourceMappingURL=platform-orchestrator.js.map

package/dist/protocol/messages/run-events.d.ts

@@ -0,0 +1,155 @@
+import { z } from 'zod';
+/** Infrastructure event emitted by orchestrator or agent during run lifecycle.
+ *
+ * SECURITY INVARIANT: This schema MUST NOT carry an `orgId` (or any tenant
+ * identifier). Orchestrator WS connections are single-tenant — `authState.orgId`
+ * is fixed for the connection's lifetime, derived from a DB-backed API-key hash.
+ * The Platform always uses `authState.orgId` for tenant attribution; trusting a
+ * wire-supplied field would be a cross-tenant injection primitive (see
+ * `docs/architecture/security/ws-tenant-isolation.md`).
+ */
+export declare const runEventMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"run.event">;
+    runId: z.ZodString;
+    eventType: z.ZodString;
+    timestampMs: z.ZodNumber;
+    sourceService: z.ZodEnum<{
+        platform: "platform";
+        orchestrator: "orchestrator";
+        agent: "agent";
+    }>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    traceId: z.ZodOptional<z.ZodString>;
+    spanId: z.ZodOptional<z.ZodString>;
+    parentSpanId: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    jobId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    stepIndex: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+/** Execution context sent by agent at job start for the Summary tab.
+ *
+ * SECURITY INVARIANT: see `runEventMessageSchema` above — no tenant identifier
+ * may appear on this wire schema. All tenant attribution comes from
+ * `authState.orgId` on the receiving Platform side.
+ */
+export declare const jobContextMessageSchema: 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>;
+/** Run event forwarded to browser for live timeline updates.
+ *
+ * NOTE: `runId` is already present in this schema (and always populated by the
+ * Platform WS fan-out in `browser-fan-out.ts::onRunEvent`). The dashboard uses it
+ * to group events by their originating run in the rerun chain. Do not remove.
+ */
+export declare const browserRunEventSchema: 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>;
+/** Job context forwarded to browser for Summary tab. */
+export declare const browserJobContextSchema: 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>;
+/** Request orchestration logs for a job via Platform-orchestrator proxy. */
+export declare const dashboardOrchLogsRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"dashboard.orch.logs">;
+    requestId: z.ZodString;
+    actor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        sub: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"api_key">;
+        keyId: z.ZodString;
+        ownerSub: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"service_account">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"platform_operator">;
+        sub: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"system">;
+        component: z.ZodString;
+    }, z.core.$strip>], "type">;
+    runId: z.ZodString;
+    jobId: z.ZodString;
+}, z.core.$strip>;
+/** Response with orchestration logs for a job. */
+export declare const dashboardOrchLogsResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"dashboard.orch.logs.response">;
+    requestId: z.ZodString;
+    lines: z.ZodArray<z.ZodString>;
+    totalLines: z.ZodNumber;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DashboardOrchLogsRequest = z.infer<typeof dashboardOrchLogsRequestSchema>;
+//# sourceMappingURL=run-events.d.ts.map

package/dist/protocol/messages/run-events.js

@@ -0,0 +1,115 @@
+import "../../chunk-gOLHoazu.js";
+import { actorPrincipalSchema } from "./actor.js";
+import { z } from "zod";
+//#region src/protocol/messages/run-events.ts
+/** Infrastructure event emitted by orchestrator or agent during run lifecycle.
+*
+* SECURITY INVARIANT: This schema MUST NOT carry an `orgId` (or any tenant
+* identifier). Orchestrator WS connections are single-tenant — `authState.orgId`
+* is fixed for the connection's lifetime, derived from a DB-backed API-key hash.
+* The Platform always uses `authState.orgId` for tenant attribution; trusting a
+* wire-supplied field would be a cross-tenant injection primitive (see
+* `docs/architecture/security/ws-tenant-isolation.md`).
+*/
+const runEventMessageSchema = z.object({
+	type: z.literal("run.event"),
+	runId: z.string(),
+	eventType: z.string(),
+	timestampMs: z.number(),
+	sourceService: z.enum([
+		"platform",
+		"orchestrator",
+		"agent"
+	]),
+	metadata: z.record(z.string(), z.unknown()).optional(),
+	traceId: z.string().optional(),
+	spanId: z.string().optional(),
+	parentSpanId: z.string().optional(),
+	durationMs: z.number().nullable().optional(),
+	jobId: z.string().nullable().optional(),
+	stepIndex: z.number().nullable().optional()
+});
+/** Execution context sent by agent at job start for the Summary tab.
+*
+* SECURITY INVARIANT: see `runEventMessageSchema` above — no tenant identifier
+* may appear on this wire schema. All tenant attribution comes from
+* `authState.orgId` on the receiving Platform side.
+*/
+const jobContextMessageSchema = z.object({
+	type: z.literal("job.context"),
+	runId: z.string(),
+	jobId: z.string(),
+	context: z.object({
+		envVars: z.array(z.object({
+			name: z.string(),
+			value: z.string(),
+			category: z.enum([
+				"system",
+				"user",
+				"inherited",
+				"secret"
+			])
+		})).optional(),
+		runtime: z.object({
+			nodeVersion: z.string().optional(),
+			os: z.string().optional(),
+			arch: z.string().optional()
+		}).optional(),
+		sandboxType: z.string().optional(),
+		labels: z.array(z.string()).optional(),
+		workingDirectory: z.string().optional(),
+		gitRef: z.string().optional(),
+		lockFileVersion: z.string().optional(),
+		sdkVersion: z.string().optional(),
+		depCacheStatus: z.string().optional(),
+		networkIsolation: z.string().optional(),
+		scalerContext: z.object({
+			backendType: z.string(),
+			scalerName: z.string()
+		}).passthrough().optional()
+	})
+});
+/** Run event forwarded to browser for live timeline updates.
+*
+* NOTE: `runId` is already present in this schema (and always populated by the
+* Platform WS fan-out in `browser-fan-out.ts::onRunEvent`). The dashboard uses it
+* to group events by their originating run in the rerun chain. Do not remove.
+*/
+const browserRunEventSchema = z.object({
+	type: z.literal("run.event"),
+	runId: z.string(),
+	eventType: z.string(),
+	timestampMs: z.number(),
+	sourceService: z.string(),
+	metadata: z.record(z.string(), z.unknown()).optional(),
+	durationMs: z.number().nullable().optional(),
+	jobId: z.string().nullable().optional(),
+	stepIndex: z.number().nullable().optional()
+});
+/** Job context forwarded to browser for Summary tab. */
+const browserJobContextSchema = z.object({
+	type: z.literal("job.context"),
+	runId: z.string(),
+	jobId: z.string(),
+	context: jobContextMessageSchema.shape.context
+});
+/** Request orchestration logs for a job via Platform-orchestrator proxy. */
+const dashboardOrchLogsRequestSchema = z.object({
+	type: z.literal("dashboard.orch.logs"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema,
+	runId: z.string(),
+	jobId: z.string()
+});
+/** Response with orchestration logs for a job. */
+const dashboardOrchLogsResponseSchema = z.object({
+	type: z.literal("dashboard.orch.logs.response"),
+	requestId: z.string(),
+	lines: z.array(z.string()),
+	totalLines: z.number(),
+	error: z.string().optional()
+});
+//#endregion
+export { browserJobContextSchema, browserRunEventSchema, dashboardOrchLogsRequestSchema, dashboardOrchLogsResponseSchema, jobContextMessageSchema, runEventMessageSchema };
+
+//# sourceMappingURL=run-events.js.map