@kici-dev/engine 0.1.22 → 0.1.24

package/dist/metrics/metric-catalog.generated.js

@@ -88,13 +88,17 @@ const MetricNames = {
 	KICI_PLATFORM_LOG_LINES_FORWARDED_TOTAL: "kici_platform_log_lines_forwarded_total",
 	KICI_PLATFORM_METRICS_QUERY_RATE_LIMITED_TOTAL: "kici_platform_metrics_query_rate_limited_total",
 	KICI_PLATFORM_MIMIR_RELAY_ERRORS_TOTAL: "kici_platform_mimir_relay_errors_total",
+	KICI_PLATFORM_NOTIFICATIONS_DELIVERED_TOTAL: "kici_platform_notifications_delivered_total",
+	KICI_PLATFORM_NOTIFICATIONS_SUPPRESSED_TOTAL: "kici_platform_notifications_suppressed_total",
 	KICI_PLATFORM_ORCH_METRICS_FILTERED_TOTAL: "kici_platform_orch_metrics_filtered_total",
 	KICI_PLATFORM_ORPHAN_CONNECTIONS_SWEPT_TOTAL: "kici_platform_orphan_connections_swept_total",
 	KICI_PLATFORM_PG_POOL_CLIENT_ERRORS_TOTAL: "kici_platform_pg_pool_client_errors_total",
+	KICI_PLATFORM_PLAN_CAP_CHECK_ERRORS_TOTAL: "kici_platform_plan_cap_check_errors_total",
 	KICI_PLATFORM_STALE_ORCHESTRATORS_TOTAL: "kici_platform_stale_orchestrators_total",
 	KICI_PLATFORM_STALE_PLATFORM_CONNECTIONS_EVICTED_TOTAL: "kici_platform_stale_platform_connections_evicted_total",
 	KICI_PLATFORM_STALE_RUNS_FAILED_TOTAL: "kici_platform_stale_runs_failed_total",
 	KICI_PLATFORM_STEP_STATUS_FORWARDS_TOTAL: "kici_platform_step_status_forwards_total",
+	KICI_PLATFORM_WS_ORG_RATE_LIMITED_TOTAL: "kici_platform_ws_org_rate_limited_total",
 	KICI_REGISTRATIONS_TOTAL: "kici_registrations_total",
 	KICI_UNIVERSAL_GIT_REGISTRATION_ERRORS_TOTAL: "kici_universal_git_registration_errors_total",
 	KICI_USER_REGISTRATION_NOTIFY_TOTAL: "kici_user_registration_notify_total",
@@ -188,8 +192,16 @@ const MetricLabels = {
 	KICI_ORCH_LOG_CHUNKS_RECEIVED_TOTAL: [],
 	KICI_ORCH_PG_POOL_CLIENT_ERRORS_TOTAL: ["source"],
 	KICI_ORCH_SCALER_CONFIG_RELOADS_TOTAL: ["result"],
-	KICI_ORCH_SCALER_CPUS_USED: ["scaler", "machinePool"],
-	KICI_ORCH_SCALER_MEMORY_BYTES_USED: ["scaler", "machinePool"],
+	KICI_ORCH_SCALER_CPUS_USED: [
+		"scaler",
+		"scalerType",
+		"machinePool"
+	],
+	KICI_ORCH_SCALER_MEMORY_BYTES_USED: [
+		"scaler",
+		"scalerType",
+		"machinePool"
+	],
 	KICI_ORCH_SCALER_SPAWN_FAILURES_TOTAL: ["backend", "bound"],
 	KICI_ORCH_SCALER_SPAWN_REFUSALS_TOTAL: [],
 	KICI_ORCH_SOURCE_CACHE_HITS_TOTAL: [],
@@ -227,13 +239,17 @@ const MetricLabels = {
 	KICI_PLATFORM_LOG_LINES_FORWARDED_TOTAL: [],
 	KICI_PLATFORM_METRICS_QUERY_RATE_LIMITED_TOTAL: ["org_id"],
 	KICI_PLATFORM_MIMIR_RELAY_ERRORS_TOTAL: ["reason"],
+	KICI_PLATFORM_NOTIFICATIONS_DELIVERED_TOTAL: ["channel_type", "result"],
+	KICI_PLATFORM_NOTIFICATIONS_SUPPRESSED_TOTAL: ["org_id"],
 	KICI_PLATFORM_ORCH_METRICS_FILTERED_TOTAL: ["reason", "metric"],
 	KICI_PLATFORM_ORPHAN_CONNECTIONS_SWEPT_TOTAL: [],
 	KICI_PLATFORM_PG_POOL_CLIENT_ERRORS_TOTAL: ["source"],
+	KICI_PLATFORM_PLAN_CAP_CHECK_ERRORS_TOTAL: ["org_id"],
 	KICI_PLATFORM_STALE_ORCHESTRATORS_TOTAL: [],
 	KICI_PLATFORM_STALE_PLATFORM_CONNECTIONS_EVICTED_TOTAL: ["org_id"],
 	KICI_PLATFORM_STALE_RUNS_FAILED_TOTAL: [],
 	KICI_PLATFORM_STEP_STATUS_FORWARDS_TOTAL: ["state"],
+	KICI_PLATFORM_WS_ORG_RATE_LIMITED_TOTAL: ["org_id"],
 	KICI_REGISTRATIONS_TOTAL: [],
 	KICI_UNIVERSAL_GIT_REGISTRATION_ERRORS_TOTAL: ["reason"],
 	KICI_USER_REGISTRATION_NOTIFY_TOTAL: ["result"],
@@ -366,13 +382,17 @@ const MetricKind = {
 	KICI_PLATFORM_LOG_LINES_FORWARDED_TOTAL: "counter",
 	KICI_PLATFORM_METRICS_QUERY_RATE_LIMITED_TOTAL: "counter",
 	KICI_PLATFORM_MIMIR_RELAY_ERRORS_TOTAL: "counter",
+	KICI_PLATFORM_NOTIFICATIONS_DELIVERED_TOTAL: "counter",
+	KICI_PLATFORM_NOTIFICATIONS_SUPPRESSED_TOTAL: "counter",
 	KICI_PLATFORM_ORCH_METRICS_FILTERED_TOTAL: "counter",
 	KICI_PLATFORM_ORPHAN_CONNECTIONS_SWEPT_TOTAL: "counter",
 	KICI_PLATFORM_PG_POOL_CLIENT_ERRORS_TOTAL: "counter",
+	KICI_PLATFORM_PLAN_CAP_CHECK_ERRORS_TOTAL: "counter",
 	KICI_PLATFORM_STALE_ORCHESTRATORS_TOTAL: "counter",
 	KICI_PLATFORM_STALE_PLATFORM_CONNECTIONS_EVICTED_TOTAL: "counter",
 	KICI_PLATFORM_STALE_RUNS_FAILED_TOTAL: "counter",
 	KICI_PLATFORM_STEP_STATUS_FORWARDS_TOTAL: "counter",
+	KICI_PLATFORM_WS_ORG_RATE_LIMITED_TOTAL: "counter",
 	KICI_REGISTRATIONS_TOTAL: "counter",
 	KICI_UNIVERSAL_GIT_REGISTRATION_ERRORS_TOTAL: "counter",
 	KICI_USER_REGISTRATION_NOTIFY_TOTAL: "counter",
@@ -501,13 +521,17 @@ const MetricDescription = {
 	KICI_PLATFORM_LOG_LINES_FORWARDED_TOTAL: "Total log lines forwarded from orchestrators",
 	KICI_PLATFORM_METRICS_QUERY_RATE_LIMITED_TOTAL: "Total dashboard metric-query requests rate-limited (429).",
 	KICI_PLATFORM_MIMIR_RELAY_ERRORS_TOTAL: "Total Mimir push-relay errors (Platform-embedded metrics). Labels: reason.",
+	KICI_PLATFORM_NOTIFICATIONS_DELIVERED_TOTAL: "Notification delivery attempts that reached a terminal outcome",
+	KICI_PLATFORM_NOTIFICATIONS_SUPPRESSED_TOTAL: "Run-terminal notifications suppressed by the per-org notification quota",
 	KICI_PLATFORM_ORCH_METRICS_FILTERED_TOTAL: "Orchestrator-pushed metric data points dropped or rewritten by the catalog allow-list. Labels: reason, metric.",
 	KICI_PLATFORM_ORPHAN_CONNECTIONS_SWEPT_TOTAL: "Total orphan connections swept from platform_connections",
 	KICI_PLATFORM_PG_POOL_CLIENT_ERRORS_TOTAL: "Total pg connection errors absorbed without a process restart",
+	KICI_PLATFORM_PLAN_CAP_CHECK_ERRORS_TOTAL: "WS connection rejected because the plan-limit check errored (fail-closed)",
 	KICI_PLATFORM_STALE_ORCHESTRATORS_TOTAL: "Total orchestrators detected as permanently disconnected",
 	KICI_PLATFORM_STALE_PLATFORM_CONNECTIONS_EVICTED_TOTAL: "platform_connections rows evicted by source.register DB dedup (same-instance reconnect path)",
 	KICI_PLATFORM_STALE_RUNS_FAILED_TOTAL: "Total execution runs failed due to orchestrator staleness",
 	KICI_PLATFORM_STEP_STATUS_FORWARDS_TOTAL: "Total step status forwards received",
+	KICI_PLATFORM_WS_ORG_RATE_LIMITED_TOTAL: "Inbound orchestrator messages dropped by the per-org aggregate WS rate limit",
 	KICI_REGISTRATIONS_TOTAL: "Total user registrations (new personal orgs created on first login)",
 	KICI_UNIVERSAL_GIT_REGISTRATION_ERRORS_TOTAL: "Errors encountered while registering universal-git provider bundles",
 	KICI_USER_REGISTRATION_NOTIFY_TOTAL: "New-user Telegram notifications by result (sent|failed)",
@@ -643,13 +667,17 @@ const MetricService = {
 	KICI_PLATFORM_LOG_LINES_FORWARDED_TOTAL: "platform",
 	KICI_PLATFORM_METRICS_QUERY_RATE_LIMITED_TOTAL: "platform",
 	KICI_PLATFORM_MIMIR_RELAY_ERRORS_TOTAL: "platform",
+	KICI_PLATFORM_NOTIFICATIONS_DELIVERED_TOTAL: "platform",
+	KICI_PLATFORM_NOTIFICATIONS_SUPPRESSED_TOTAL: "platform",
 	KICI_PLATFORM_ORCH_METRICS_FILTERED_TOTAL: "platform",
 	KICI_PLATFORM_ORPHAN_CONNECTIONS_SWEPT_TOTAL: "platform",
 	KICI_PLATFORM_PG_POOL_CLIENT_ERRORS_TOTAL: "platform",
+	KICI_PLATFORM_PLAN_CAP_CHECK_ERRORS_TOTAL: "platform",
 	KICI_PLATFORM_STALE_ORCHESTRATORS_TOTAL: "platform",
 	KICI_PLATFORM_STALE_PLATFORM_CONNECTIONS_EVICTED_TOTAL: "platform",
 	KICI_PLATFORM_STALE_RUNS_FAILED_TOTAL: "platform",
 	KICI_PLATFORM_STEP_STATUS_FORWARDS_TOTAL: "platform",
+	KICI_PLATFORM_WS_ORG_RATE_LIMITED_TOTAL: "platform",
 	KICI_REGISTRATIONS_TOTAL: "platform",
 	KICI_UNIVERSAL_GIT_REGISTRATION_ERRORS_TOTAL: "orchestrator",
 	KICI_USER_REGISTRATION_NOTIFY_TOTAL: "platform",
@@ -779,13 +807,17 @@ const ALL_METRIC_NAMES = [
 	"kici_platform_log_lines_forwarded_total",
 	"kici_platform_metrics_query_rate_limited_total",
 	"kici_platform_mimir_relay_errors_total",
+	"kici_platform_notifications_delivered_total",
+	"kici_platform_notifications_suppressed_total",
 	"kici_platform_orch_metrics_filtered_total",
 	"kici_platform_orphan_connections_swept_total",
 	"kici_platform_pg_pool_client_errors_total",
+	"kici_platform_plan_cap_check_errors_total",
 	"kici_platform_stale_orchestrators_total",
 	"kici_platform_stale_platform_connections_evicted_total",
 	"kici_platform_stale_runs_failed_total",
 	"kici_platform_step_status_forwards_total",
+	"kici_platform_ws_org_rate_limited_total",
 	"kici_registrations_total",
 	"kici_universal_git_registration_errors_total",
 	"kici_user_registration_notify_total",

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

@@ -13,6 +13,7 @@ import { z } from 'zod';
  */
 /** Where the access-log entry was originated from. */
 export declare const AccessLogSource: z.ZodEnum<{
+    agent: "agent";
     platform_proxy: "platform_proxy";
     admin_http: "admin_http";
     admin_cli: "admin_cli";
@@ -29,12 +30,12 @@ export type AccessLogOutcome = z.infer<typeof AccessLogOutcome>;
 export declare const AccessLogTargetType: z.ZodEnum<{
     run: "run";
     job: "job";
-    payload: "payload";
     step: "step";
+    environment: "environment";
+    payload: "payload";
     event_log: "event_log";
     event_log_payload: "event_log_payload";
     secret_scope: "secret_scope";
-    environment: "environment";
     registration: "registration";
     backend: "backend";
     diagnostics: "diagnostics";
@@ -45,6 +46,7 @@ export declare const AccessLogTargetType: z.ZodEnum<{
     event_dlq: "event_dlq";
     org_settings: "org_settings";
     cluster_meta: "cluster_meta";
+    attestation: "attestation";
 }>;
 export type AccessLogTargetType = z.infer<typeof AccessLogTargetType>;
 /**
@@ -60,6 +62,7 @@ export declare const AccessLogAction: z.ZodEnum<{
     "fleet.host.declare": "fleet.host.declare";
     "fleet.host.remove": "fleet.host.remove";
     "run.detail.read": "run.detail.read";
+    "run.structured.read": "run.structured.read";
     "runs.list.read": "runs.list.read";
     "runs.filters.read": "runs.filters.read";
     "sources.list.read": "sources.list.read";
@@ -107,6 +110,8 @@ export declare const AccessLogAction: z.ZodEnum<{
     "scaler.capacity.read": "scaler.capacity.read";
     "scaler.agents.read": "scaler.agents.read";
     "fleet.read": "fleet.read";
+    "fleet.init_runner.bringup": "fleet.init_runner.bringup";
+    "fleet.pre_boot.send": "fleet.pre_boot.send";
     "backend.list.read": "backend.list.read";
     "backend.get.read": "backend.get.read";
     "backend.sync": "backend.sync";
@@ -152,6 +157,7 @@ export declare const accessLogItemSchema: z.ZodObject<{
         "fleet.host.declare": "fleet.host.declare";
         "fleet.host.remove": "fleet.host.remove";
         "run.detail.read": "run.detail.read";
+        "run.structured.read": "run.structured.read";
         "runs.list.read": "runs.list.read";
         "runs.filters.read": "runs.filters.read";
         "sources.list.read": "sources.list.read";
@@ -199,6 +205,8 @@ export declare const accessLogItemSchema: z.ZodObject<{
         "scaler.capacity.read": "scaler.capacity.read";
         "scaler.agents.read": "scaler.agents.read";
         "fleet.read": "fleet.read";
+        "fleet.init_runner.bringup": "fleet.init_runner.bringup";
+        "fleet.pre_boot.send": "fleet.pre_boot.send";
         "backend.list.read": "backend.list.read";
         "backend.get.read": "backend.get.read";
         "backend.sync": "backend.sync";
@@ -215,12 +223,12 @@ export declare const accessLogItemSchema: z.ZodObject<{
     targetType: z.ZodNullable<z.ZodEnum<{
         run: "run";
         job: "job";
-        payload: "payload";
         step: "step";
+        environment: "environment";
+        payload: "payload";
         event_log: "event_log";
         event_log_payload: "event_log_payload";
         secret_scope: "secret_scope";
-        environment: "environment";
         registration: "registration";
         backend: "backend";
         diagnostics: "diagnostics";
@@ -231,10 +239,12 @@ export declare const accessLogItemSchema: z.ZodObject<{
         event_dlq: "event_dlq";
         org_settings: "org_settings";
         cluster_meta: "cluster_meta";
+        attestation: "attestation";
     }>>;
     targetId: z.ZodNullable<z.ZodString>;
     requestId: z.ZodNullable<z.ZodString>;
     source: z.ZodEnum<{
+        agent: "agent";
         platform_proxy: "platform_proxy";
         admin_http: "admin_http";
         admin_cli: "admin_cli";
@@ -267,6 +277,7 @@ export declare const accessLogFilterSchema: z.ZodObject<{
         "fleet.host.declare": "fleet.host.declare";
         "fleet.host.remove": "fleet.host.remove";
         "run.detail.read": "run.detail.read";
+        "run.structured.read": "run.structured.read";
         "runs.list.read": "runs.list.read";
         "runs.filters.read": "runs.filters.read";
         "sources.list.read": "sources.list.read";
@@ -314,6 +325,8 @@ export declare const accessLogFilterSchema: z.ZodObject<{
         "scaler.capacity.read": "scaler.capacity.read";
         "scaler.agents.read": "scaler.agents.read";
         "fleet.read": "fleet.read";
+        "fleet.init_runner.bringup": "fleet.init_runner.bringup";
+        "fleet.pre_boot.send": "fleet.pre_boot.send";
         "backend.list.read": "backend.list.read";
         "backend.get.read": "backend.get.read";
         "backend.sync": "backend.sync";
@@ -328,6 +341,7 @@ export declare const accessLogFilterSchema: z.ZodObject<{
         purge_chunk: "purge_chunk";
     }>>;
     source: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
         platform_proxy: "platform_proxy";
         admin_http: "admin_http";
         admin_cli: "admin_cli";
@@ -340,12 +354,12 @@ export declare const accessLogFilterSchema: z.ZodObject<{
     targetType: z.ZodOptional<z.ZodEnum<{
         run: "run";
         job: "job";
-        payload: "payload";
         step: "step";
+        environment: "environment";
+        payload: "payload";
         event_log: "event_log";
         event_log_payload: "event_log_payload";
         secret_scope: "secret_scope";
-        environment: "environment";
         registration: "registration";
         backend: "backend";
         diagnostics: "diagnostics";
@@ -356,6 +370,7 @@ export declare const accessLogFilterSchema: z.ZodObject<{
         event_dlq: "event_dlq";
         org_settings: "org_settings";
         cluster_meta: "cluster_meta";
+        attestation: "attestation";
     }>>;
     targetId: z.ZodOptional<z.ZodString>;
     fromTimestamp: z.ZodOptional<z.ZodString>;
@@ -370,6 +385,10 @@ export declare const dashboardAccessLogListRequestSchema: z.ZodObject<{
     actor: z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"user">;
         sub: z.ZodString;
+        agent: z.ZodOptional<z.ZodObject<{
+            patId: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"api_key">;
         keyId: z.ZodString;
@@ -404,6 +423,7 @@ export declare const dashboardAccessLogListRequestSchema: z.ZodObject<{
         "fleet.host.declare": "fleet.host.declare";
         "fleet.host.remove": "fleet.host.remove";
         "run.detail.read": "run.detail.read";
+        "run.structured.read": "run.structured.read";
         "runs.list.read": "runs.list.read";
         "runs.filters.read": "runs.filters.read";
         "sources.list.read": "sources.list.read";
@@ -451,6 +471,8 @@ export declare const dashboardAccessLogListRequestSchema: z.ZodObject<{
         "scaler.capacity.read": "scaler.capacity.read";
         "scaler.agents.read": "scaler.agents.read";
         "fleet.read": "fleet.read";
+        "fleet.init_runner.bringup": "fleet.init_runner.bringup";
+        "fleet.pre_boot.send": "fleet.pre_boot.send";
         "backend.list.read": "backend.list.read";
         "backend.get.read": "backend.get.read";
         "backend.sync": "backend.sync";
@@ -465,6 +487,7 @@ export declare const dashboardAccessLogListRequestSchema: z.ZodObject<{
         purge_chunk: "purge_chunk";
     }>>;
     source: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
         platform_proxy: "platform_proxy";
         admin_http: "admin_http";
         admin_cli: "admin_cli";
@@ -477,12 +500,12 @@ export declare const dashboardAccessLogListRequestSchema: z.ZodObject<{
     targetType: z.ZodOptional<z.ZodEnum<{
         run: "run";
         job: "job";
-        payload: "payload";
         step: "step";
+        environment: "environment";
+        payload: "payload";
         event_log: "event_log";
         event_log_payload: "event_log_payload";
         secret_scope: "secret_scope";
-        environment: "environment";
         registration: "registration";
         backend: "backend";
         diagnostics: "diagnostics";
@@ -493,6 +516,7 @@ export declare const dashboardAccessLogListRequestSchema: z.ZodObject<{
         event_dlq: "event_dlq";
         org_settings: "org_settings";
         cluster_meta: "cluster_meta";
+        attestation: "attestation";
     }>>;
     targetId: z.ZodOptional<z.ZodString>;
     fromTimestamp: z.ZodOptional<z.ZodString>;
@@ -529,6 +553,7 @@ export declare const dashboardAccessLogListResponseSchema: z.ZodObject<{
             "fleet.host.declare": "fleet.host.declare";
             "fleet.host.remove": "fleet.host.remove";
             "run.detail.read": "run.detail.read";
+            "run.structured.read": "run.structured.read";
             "runs.list.read": "runs.list.read";
             "runs.filters.read": "runs.filters.read";
             "sources.list.read": "sources.list.read";
@@ -576,6 +601,8 @@ export declare const dashboardAccessLogListResponseSchema: z.ZodObject<{
             "scaler.capacity.read": "scaler.capacity.read";
             "scaler.agents.read": "scaler.agents.read";
             "fleet.read": "fleet.read";
+            "fleet.init_runner.bringup": "fleet.init_runner.bringup";
+            "fleet.pre_boot.send": "fleet.pre_boot.send";
             "backend.list.read": "backend.list.read";
             "backend.get.read": "backend.get.read";
             "backend.sync": "backend.sync";
@@ -592,12 +619,12 @@ export declare const dashboardAccessLogListResponseSchema: z.ZodObject<{
         targetType: z.ZodNullable<z.ZodEnum<{
             run: "run";
             job: "job";
-            payload: "payload";
             step: "step";
+            environment: "environment";
+            payload: "payload";
             event_log: "event_log";
             event_log_payload: "event_log_payload";
             secret_scope: "secret_scope";
-            environment: "environment";
             registration: "registration";
             backend: "backend";
             diagnostics: "diagnostics";
@@ -608,10 +635,12 @@ export declare const dashboardAccessLogListResponseSchema: z.ZodObject<{
             event_dlq: "event_dlq";
             org_settings: "org_settings";
             cluster_meta: "cluster_meta";
+            attestation: "attestation";
         }>>;
         targetId: z.ZodNullable<z.ZodString>;
         requestId: z.ZodNullable<z.ZodString>;
         source: z.ZodEnum<{
+            agent: "agent";
             platform_proxy: "platform_proxy";
             admin_http: "admin_http";
             admin_cli: "admin_cli";

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

@@ -18,7 +18,8 @@ import { z } from "zod";
 const AccessLogSource = z.enum([
 	"platform_proxy",
 	"admin_http",
-	"admin_cli"
+	"admin_cli",
+	"agent"
 ]);
 /** Outcome of the attempted action. */
 const AccessLogOutcome = z.enum([
@@ -45,7 +46,8 @@ const AccessLogTargetType = z.enum([
 	"access_log",
 	"event_dlq",
 	"org_settings",
-	"cluster_meta"
+	"cluster_meta",
+	"attestation"
 ]);
 /**
 * Dotted-namespace action names. Every handler that writes an access_log
@@ -53,6 +55,7 @@ const AccessLogTargetType = z.enum([
 */
 const AccessLogAction = z.enum([
 	"run.detail.read",
+	"run.structured.read",
 	"runs.list.read",
 	"runs.filters.read",
 	"sources.list.read",
@@ -104,6 +107,8 @@ const AccessLogAction = z.enum([
 	"fleet.read",
 	"fleet.host.declare",
 	"fleet.host.remove",
+	"fleet.init_runner.bringup",
+	"fleet.pre_boot.send",
 	"backend.list.read",
 	"backend.get.read",
 	"backend.sync",

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

@@ -20,6 +20,10 @@ export type ActorType = z.infer<typeof ActorType>;
 export declare const userActorSchema: z.ZodObject<{
     type: z.ZodLiteral<"user">;
     sub: z.ZodString;
+    agent: z.ZodOptional<z.ZodObject<{
+        patId: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type UserActor = z.infer<typeof userActorSchema>;
 export declare const apiKeyActorSchema: z.ZodObject<{
@@ -48,6 +52,10 @@ export type SystemActor = z.infer<typeof systemActorSchema>;
 export declare const actorPrincipalSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"user">;
     sub: z.ZodString;
+    agent: z.ZodOptional<z.ZodObject<{
+        patId: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"api_key">;
     keyId: z.ZodString;

package/dist/protocol/messages/actor.js

@@ -21,7 +21,18 @@ const ActorType = z.enum([
 const userActorSchema = z.object({
 	type: z.literal(ActorType.enum.user),
 	/** Keycloak subject (idp_sub). */
-	sub: z.string().min(1)
+	sub: z.string().min(1),
+	/**
+	* Present when the user is acting through an agent-kind PAT (e.g. a coding
+	* agent driving KiCI via the developer MCP server). The PAT still inherits
+	* the user's permissions — this is provenance only, not an authority change.
+	* `patId` is the opaque PAT identifier; `label` is the human-set agent name
+	* recorded on every audit / access-log row.
+	*/
+	agent: z.object({
+		patId: z.string().min(1),
+		label: z.string().min(1)
+	}).optional()
 });
 const apiKeyActorSchema = z.object({
 	type: z.literal(ActorType.enum.api_key),
@@ -77,7 +88,7 @@ const actorPrincipalSchema = z.discriminatedUnion("type", [
 */
 function stringifyActor(actor) {
 	switch (actor.type) {
-		case "user": return `user:${actor.sub}`;
+		case "user": return actor.agent ? `user:${actor.sub} via agent:${actor.agent.label}` : `user:${actor.sub}`;
 		case "api_key": return `api_key:${actor.keyId}`;
 		case "service_account": return `service_account:${actor.id}`;
 		case "platform_operator": return `platform_operator:${actor.sub}`;
@@ -116,7 +127,10 @@ function flattenActor(actor) {
 		case "user": return {
 			actorType: "user",
 			actorId: actor.sub,
-			actorMeta: null
+			actorMeta: actor.agent ? {
+				agentPatId: actor.agent.patId,
+				agentLabel: actor.agent.label
+			} : null
 		};
 		case "api_key": return {
 			actorType: "api_key",