@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/protocol/gateway-protocol/events.d.ts

@@ -0,0 +1,567 @@
+import { z } from "zod";
+/**
+ * SSE / stream events emitted by the gateway while an agent turn runs.
+ *
+ * Transport: the client POSTs `agent.turn.submit`, then opens the turn's event
+ * stream (`GET /v1/turns/:turnId/events`, `text/event-stream`). Each SSE
+ * `data:` line is one JSON event below.
+ *
+ * Event names follow the same dotted convention as commands. New event types
+ * are added additively; existing fields are never removed or retyped within a
+ * wire version.
+ *
+ * Two families coexist: `agent.turn.*` (the original assistant-message
+ * oriented events) and `turn.*` (typed turn-lifecycle taxonomy with a
+ * per-turn `runId` for cross-event correlation).
+ */
+export declare const toolCallSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    startedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    arguments: Record<string, unknown>;
+    startedAt: string;
+}, {
+    name: string;
+    id: string;
+    arguments: Record<string, unknown>;
+    startedAt: string;
+}>;
+/** Every stream event type, mapped to its payload schema. */
+export declare const STREAM_EVENT_SCHEMAS: {
+    readonly "agent.turn.token": {
+        readonly type: "agent.turn.token";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** Incremental text delta for the assistant message. */
+            delta: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            turnId: string;
+            delta: string;
+        }, {
+            turnId: string;
+            delta: string;
+        }>;
+    };
+    readonly "agent.turn.tool_call": {
+        readonly type: "agent.turn.tool_call";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            toolCall: z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                startedAt: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                name: string;
+                id: string;
+                arguments: Record<string, unknown>;
+                startedAt: string;
+            }, {
+                name: string;
+                id: string;
+                arguments: Record<string, unknown>;
+                startedAt: string;
+            }>;
+        }, "strip", z.ZodTypeAny, {
+            turnId: string;
+            toolCall: {
+                name: string;
+                id: string;
+                arguments: Record<string, unknown>;
+                startedAt: string;
+            };
+        }, {
+            turnId: string;
+            toolCall: {
+                name: string;
+                id: string;
+                arguments: Record<string, unknown>;
+                startedAt: string;
+            };
+        }>;
+    };
+    readonly "agent.turn.done": {
+        readonly type: "agent.turn.done";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            status: z.ZodEnum<["queued", "running", "completed", "cancelled", "failed"]>;
+            /** Final assistant text when the turn completed. */
+            output: z.ZodOptional<z.ZodString>;
+            usage: z.ZodOptional<z.ZodObject<{
+                inputTokens: z.ZodNumber;
+                outputTokens: z.ZodNumber;
+                totalTokens: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                inputTokens: number;
+                outputTokens: number;
+                totalTokens: number;
+            }, {
+                inputTokens: number;
+                outputTokens: number;
+                totalTokens: number;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            status: "completed" | "cancelled" | "queued" | "running" | "failed";
+            turnId: string;
+            output?: string | undefined;
+            usage?: {
+                inputTokens: number;
+                outputTokens: number;
+                totalTokens: number;
+            } | undefined;
+        }, {
+            status: "completed" | "cancelled" | "queued" | "running" | "failed";
+            turnId: string;
+            output?: string | undefined;
+            usage?: {
+                inputTokens: number;
+                outputTokens: number;
+                totalTokens: number;
+            } | undefined;
+        }>;
+    };
+    readonly "agent.turn.error": {
+        readonly type: "agent.turn.error";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            error: z.ZodString;
+            /** True when the client may retry with the same requestId. */
+            retryable: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            error: string;
+            turnId: string;
+            retryable?: boolean | undefined;
+        }, {
+            error: string;
+            turnId: string;
+            retryable?: boolean | undefined;
+        }>;
+    };
+    readonly "turn.start": {
+        readonly type: "turn.start";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** UUID generated per turn; traces every event of the turn. */
+            runId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            runId: string;
+            turnId: string;
+        }, {
+            runId: string;
+            turnId: string;
+        }>;
+    };
+    readonly "turn.tool_start": {
+        readonly type: "turn.tool_start";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** UUID generated per turn; traces every event of the turn. */
+            runId: z.ZodString;
+            toolCallId: z.ZodString;
+            toolName: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            runId: string;
+            toolName: string;
+            turnId: string;
+            toolCallId: string;
+        }, {
+            runId: string;
+            toolName: string;
+            turnId: string;
+            toolCallId: string;
+        }>;
+    };
+    readonly "turn.tool_end": {
+        readonly type: "turn.tool_end";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** UUID generated per turn; traces every event of the turn. */
+            runId: z.ZodString;
+            toolCallId: z.ZodString;
+            toolName: z.ZodString;
+            durationMs: z.ZodNumber;
+            status: z.ZodEnum<["ok", "error"]>;
+        }, "strip", z.ZodTypeAny, {
+            status: "error" | "ok";
+            runId: string;
+            toolName: string;
+            durationMs: number;
+            turnId: string;
+            toolCallId: string;
+        }, {
+            status: "error" | "ok";
+            runId: string;
+            toolName: string;
+            durationMs: number;
+            turnId: string;
+            toolCallId: string;
+        }>;
+    };
+    readonly "turn.approval_required": {
+        readonly type: "turn.approval_required";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** UUID generated per turn; traces every event of the turn. */
+            runId: z.ZodString;
+            toolName: z.ZodString;
+            args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            reason: z.ZodString;
+            /**
+             * P1-2: set on boot re-announcements of approvals that survived a
+             * gateway restart. No live turn waits behind such an event — answering
+             * records the decision and `turn.approve` reports `resumed: false`.
+             */
+            resumed: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            reason: string;
+            runId: string;
+            toolName: string;
+            args: Record<string, unknown>;
+            turnId: string;
+            resumed?: boolean | undefined;
+        }, {
+            reason: string;
+            runId: string;
+            toolName: string;
+            args: Record<string, unknown>;
+            turnId: string;
+            resumed?: boolean | undefined;
+        }>;
+    };
+    readonly "turn.verification": {
+        readonly type: "turn.verification";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** UUID generated per turn; traces every event of the turn. */
+            runId: z.ZodString;
+            report: z.ZodObject<{
+                verdicts: z.ZodArray<z.ZodObject<{
+                    verdict: z.ZodString;
+                    claim: z.ZodOptional<z.ZodString>;
+                }, "strip", z.ZodTypeAny, {
+                    verdict: string;
+                    claim?: string | undefined;
+                }, {
+                    verdict: string;
+                    claim?: string | undefined;
+                }>, "many">;
+                ungroundedCount: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                verdicts: {
+                    verdict: string;
+                    claim?: string | undefined;
+                }[];
+                ungroundedCount: number;
+            }, {
+                verdicts: {
+                    verdict: string;
+                    claim?: string | undefined;
+                }[];
+                ungroundedCount: number;
+            }>;
+        }, "strip", z.ZodTypeAny, {
+            runId: string;
+            turnId: string;
+            report: {
+                verdicts: {
+                    verdict: string;
+                    claim?: string | undefined;
+                }[];
+                ungroundedCount: number;
+            };
+        }, {
+            runId: string;
+            turnId: string;
+            report: {
+                verdicts: {
+                    verdict: string;
+                    claim?: string | undefined;
+                }[];
+                ungroundedCount: number;
+            };
+        }>;
+    };
+    readonly "turn.routed": {
+        readonly type: "turn.routed";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** UUID generated per turn; traces every event of the turn. */
+            runId: z.ZodString;
+            /** Routing decision for the turn: `fast` (cheap) or `deep` (careful). */
+            route: z.ZodEnum<["fast", "deep"]>;
+            /** Why the router decided this route (e.g. `default:fast`, `risk:destructive`). */
+            reason: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            reason: string;
+            runId: string;
+            turnId: string;
+            route: "fast" | "deep";
+        }, {
+            reason: string;
+            runId: string;
+            turnId: string;
+            route: "fast" | "deep";
+        }>;
+    };
+    readonly "turn.escalated": {
+        readonly type: "turn.escalated";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** UUID generated per turn; traces every event of the turn. */
+            runId: z.ZodString;
+            /** Escalation always runs fast → deep: the only direction the router escalates. */
+            from: z.ZodEnum<["fast", "deep"]>;
+            to: z.ZodEnum<["fast", "deep"]>;
+            /** What triggered the escalation (e.g. `guard:unsupported-claims`). */
+            trigger: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            runId: string;
+            turnId: string;
+            from: "fast" | "deep";
+            to: "fast" | "deep";
+            trigger: string;
+        }, {
+            runId: string;
+            turnId: string;
+            from: "fast" | "deep";
+            to: "fast" | "deep";
+            trigger: string;
+        }>;
+    };
+    readonly "turn.reasoning_delta": {
+        readonly type: "turn.reasoning_delta";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** UUID generated per turn; traces every event of the turn. */
+            runId: z.ZodOptional<z.ZodString>;
+            /** One reasoning fragment; concatenate across events for the full trace. */
+            delta: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            turnId: string;
+            delta: string;
+            runId?: string | undefined;
+        }, {
+            turnId: string;
+            delta: string;
+            runId?: string | undefined;
+        }>;
+    };
+    readonly "turn.compacted": {
+        readonly type: "turn.compacted";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            prunedTurns: z.ZodNumber;
+            originalTokens: z.ZodNumber;
+            compactedTokens: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            originalTokens: number;
+            compactedTokens: number;
+            turnId: string;
+            prunedTurns: number;
+        }, {
+            originalTokens: number;
+            compactedTokens: number;
+            turnId: string;
+            prunedTurns: number;
+        }>;
+    };
+    readonly "guard.blocked": {
+        readonly type: "guard.blocked";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** UUID generated per turn; traces every event of the turn. */
+            runId: z.ZodString;
+            toolName: z.ZodString;
+            /** Which guard layer denied the call: boundary | gates | verifier | sanitizer. */
+            layer: z.ZodString;
+            reason: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            reason: string;
+            runId: string;
+            toolName: string;
+            turnId: string;
+            layer: string;
+        }, {
+            reason: string;
+            runId: string;
+            toolName: string;
+            turnId: string;
+            layer: string;
+        }>;
+    };
+    readonly "guard.tagged": {
+        readonly type: "guard.tagged";
+        readonly schema: z.ZodObject<{
+            turnId: z.ZodString;
+            /** UUID generated per turn; traces every event of the turn. */
+            runId: z.ZodString;
+            /** Tool that produced the output; empty string when the name is unknown. */
+            toolName: z.ZodString;
+            /** The boundary classification assigned to this tool output. */
+            trust: z.ZodEnum<["trusted", "untrusted"]>;
+            /** Tool-call id of the tagged output, when known. */
+            callId: z.ZodOptional<z.ZodString>;
+            /** `detectInstructions` pattern ids found in the output (untrusted only). */
+            patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            runId: string;
+            toolName: string;
+            turnId: string;
+            trust: "trusted" | "untrusted";
+            callId?: string | undefined;
+            patterns?: string[] | undefined;
+        }, {
+            runId: string;
+            toolName: string;
+            turnId: string;
+            trust: "trusted" | "untrusted";
+            callId?: string | undefined;
+            patterns?: string[] | undefined;
+        }>;
+    };
+    readonly "task.created": {
+        readonly type: "task.created";
+        readonly schema: z.ZodObject<{
+            taskId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            taskId: string;
+        }, {
+            taskId: string;
+        }>;
+    };
+    readonly "task.progress": {
+        readonly type: "task.progress";
+        readonly schema: z.ZodObject<{
+            taskId: z.ZodString;
+            stepIndex: z.ZodNumber;
+            totalSteps: z.ZodNumber;
+            detail: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            stepIndex: number;
+            totalSteps: number;
+            taskId: string;
+            detail?: string | undefined;
+        }, {
+            stepIndex: number;
+            totalSteps: number;
+            taskId: string;
+            detail?: string | undefined;
+        }>;
+    };
+    readonly "task.checkpoint": {
+        readonly type: "task.checkpoint";
+        readonly schema: z.ZodObject<{
+            taskId: z.ZodString;
+            stepIndex: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            stepIndex: number;
+            taskId: string;
+        }, {
+            stepIndex: number;
+            taskId: string;
+        }>;
+    };
+    readonly "task.paused": {
+        readonly type: "task.paused";
+        readonly schema: z.ZodObject<{
+            taskId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            taskId: string;
+        }, {
+            taskId: string;
+        }>;
+    };
+    readonly "task.resumed": {
+        readonly type: "task.resumed";
+        readonly schema: z.ZodObject<{
+            taskId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            taskId: string;
+        }, {
+            taskId: string;
+        }>;
+    };
+    readonly "task.awaiting_approval": {
+        readonly type: "task.awaiting_approval";
+        readonly schema: z.ZodObject<{
+            taskId: z.ZodString;
+            runId: z.ZodString;
+            toolName: z.ZodString;
+            reason: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            reason: string;
+            runId: string;
+            toolName: string;
+            taskId: string;
+        }, {
+            reason: string;
+            runId: string;
+            toolName: string;
+            taskId: string;
+        }>;
+    };
+    readonly "task.completed": {
+        readonly type: "task.completed";
+        readonly schema: z.ZodObject<{
+            taskId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            taskId: string;
+        }, {
+            taskId: string;
+        }>;
+    };
+    readonly "task.failed": {
+        readonly type: "task.failed";
+        readonly schema: z.ZodObject<{
+            taskId: z.ZodString;
+            error: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            error: string;
+            taskId: string;
+        }, {
+            error: string;
+            taskId: string;
+        }>;
+    };
+    readonly "task.cancelled": {
+        readonly type: "task.cancelled";
+        readonly schema: z.ZodObject<{
+            taskId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            taskId: string;
+        }, {
+            taskId: string;
+        }>;
+    };
+    readonly "task.interrupted": {
+        readonly type: "task.interrupted";
+        readonly schema: z.ZodObject<{
+            taskId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            taskId: string;
+        }, {
+            taskId: string;
+        }>;
+    };
+};
+/** Union of all known stream event type literals. */
+export type StreamEventType = keyof typeof STREAM_EVENT_SCHEMAS;
+/** Validated payload for a given stream event. */
+export type StreamEventPayload<T extends StreamEventType> = z.infer<(typeof STREAM_EVENT_SCHEMAS)[T]["schema"]>;
+/** A validated stream event: discriminated union over every known event type. */
+export type StreamEvent = {
+    [K in StreamEventType]: {
+        type: K;
+        payload: StreamEventPayload<K>;
+    };
+}[StreamEventType];
+/**
+ * Validate a raw SSE `data:` value (parsed JSON object or JSON string).
+ * Returns the event with its `type` and validated `payload`.
+ * Throws {@link ProtocolError} with code INVALID_EVENT on any mismatch.
+ */
+export declare function parseEvent(raw: unknown): StreamEvent;