@classic-homes/agent-contracts 0.0.0-stage → 0.1.0

package/dist/events.d.ts

@@ -0,0 +1,515 @@
+import { z } from 'zod';
+import { RequestId } from './ids.js';
+/** Which backend produced a stream. `mock` must always be visible to the user. */
+export declare const BackendMode: z.ZodEnum<{
+    mock: "mock";
+    live: "live";
+}>;
+export type BackendMode = z.infer<typeof BackendMode>;
+export declare const ErrorCode: z.ZodEnum<{
+    bad_request: "bad_request";
+    unauthenticated: "unauthenticated";
+    forbidden: "forbidden";
+    not_found: "not_found";
+    message_too_large: "message_too_large";
+    rate_limited: "rate_limited";
+    upstream_unavailable: "upstream_unavailable";
+    upstream_error: "upstream_error";
+    timeout: "timeout";
+    cancelled: "cancelled";
+    internal: "internal";
+}>;
+export type ErrorCode = z.infer<typeof ErrorCode>;
+/**
+ * Which agent run an event belongs to. The router's run has no parent; a delegated child's run
+ * names the router's run as its parent. Absent on the turn-level events (`start`, `done`).
+ */
+export declare const AgentScope: z.ZodObject<{
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentScope = z.infer<typeof AgentScope>;
+export declare const StartEvent: z.ZodObject<{
+    conversationId: z.ZodString;
+    mode: z.ZodEnum<{
+        mock: "mock";
+        live: "live";
+    }>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"start">;
+}, z.core.$strip>;
+export declare const DeltaEvent: z.ZodObject<{
+    text: z.ZodString;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"delta">;
+}, z.core.$strip>;
+export declare const ProposalEvent: z.ZodObject<{
+    operation: z.ZodUnion<readonly [z.ZodObject<{
+        target: z.ZodObject<{
+            sheet: z.ZodString;
+            address: z.ZodString;
+        }, z.core.$strip>;
+        write: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"values">;
+            values: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"formulas">;
+            formulas: z.ZodArray<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>], "type">;
+        precondition: z.ZodObject<{
+            formulas: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+            values: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>>;
+        }, z.core.$strip>;
+        operationId: z.ZodUUID;
+        documentId: z.ZodString;
+        summary: z.ZodString;
+        kind: z.ZodLiteral<"excel.writeRange">;
+    }, z.core.$strip>, z.ZodObject<{
+        target: z.ZodObject<{
+            targetId: z.ZodString;
+            expectedText: z.ZodString;
+        }, z.core.$strip>;
+        location: z.ZodEnum<{
+            before: "before";
+            after: "after";
+        }>;
+        text: z.ZodString;
+        operationId: z.ZodUUID;
+        documentId: z.ZodString;
+        summary: z.ZodString;
+        kind: z.ZodLiteral<"word.insertText">;
+    }, z.core.$strip>, z.ZodObject<{
+        target: z.ZodObject<{
+            targetId: z.ZodString;
+            expectedText: z.ZodString;
+        }, z.core.$strip>;
+        text: z.ZodString;
+        operationId: z.ZodUUID;
+        documentId: z.ZodString;
+        summary: z.ZodString;
+        kind: z.ZodLiteral<"word.replaceSelection">;
+    }, z.core.$strip>]>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"proposal">;
+}, z.core.$strip>;
+export declare const ErrorEvent: z.ZodObject<{
+    code: z.ZodEnum<{
+        bad_request: "bad_request";
+        unauthenticated: "unauthenticated";
+        forbidden: "forbidden";
+        not_found: "not_found";
+        message_too_large: "message_too_large";
+        rate_limited: "rate_limited";
+        upstream_unavailable: "upstream_unavailable";
+        upstream_error: "upstream_error";
+        timeout: "timeout";
+        cancelled: "cancelled";
+        internal: "internal";
+    }>;
+    message: z.ZodString;
+    retryable: z.ZodBoolean;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"error">;
+}, z.core.$strip>;
+export declare const DoneEvent: z.ZodObject<{
+    finishReason: z.ZodEnum<{
+        length: "length";
+        error: "error";
+        cancelled: "cancelled";
+        stop: "stop";
+    }>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"done">;
+}, z.core.$strip>;
+/** The agent asked a tool to run. Arguments are previewed, never echoed in full. */
+export declare const ToolCallEvent: z.ZodObject<{
+    callId: z.ZodString;
+    name: z.ZodString;
+    server: z.ZodOptional<z.ZodString>;
+    argsPreview: z.ZodString;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"tool_call">;
+}, z.core.$strip>;
+export declare const ToolResultStatus: z.ZodEnum<{
+    error: "error";
+    unauthenticated: "unauthenticated";
+    ok: "ok";
+    refused: "refused";
+}>;
+export type ToolResultStatus = z.infer<typeof ToolResultStatus>;
+export declare const ToolResultEvent: z.ZodObject<{
+    callId: z.ZodString;
+    status: z.ZodEnum<{
+        error: "error";
+        unauthenticated: "unauthenticated";
+        ok: "ok";
+        refused: "refused";
+    }>;
+    durationMs: z.ZodNumber;
+    summary: z.ZodString;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"tool_result">;
+}, z.core.$strip>;
+/** The router handed a task to a specialist child and later got it back. */
+export declare const DelegationEvent: z.ZodObject<{
+    child: z.ZodString;
+    childRunId: z.ZodString;
+    status: z.ZodEnum<{
+        start: "start";
+        end: "end";
+    }>;
+    summary: z.ZodOptional<z.ZodString>;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"delegation">;
+}, z.core.$strip>;
+export declare const ArtifactMediaType: z.ZodEnum<{
+    "text/markdown": "text/markdown";
+    "text/html": "text/html";
+    "application/vnd.ant.code": "application/vnd.ant.code";
+    "application/vnd.ant.mermaid": "application/vnd.ant.mermaid";
+    "application/vnd.ant.react": "application/vnd.ant.react";
+    "image/svg+xml": "image/svg+xml";
+}>;
+export type ArtifactMediaType = z.infer<typeof ArtifactMediaType>;
+/**
+ * A rendered artifact streamed alongside the answer. `open` carries the metadata, `delta`
+ * appends text, `close` ends it. Artifacts render only inside the client sandbox.
+ */
+export declare const ArtifactEvent: z.ZodObject<{
+    artifactId: z.ZodString;
+    op: z.ZodEnum<{
+        delta: "delta";
+        open: "open";
+        close: "close";
+    }>;
+    mediaType: z.ZodOptional<z.ZodEnum<{
+        "text/markdown": "text/markdown";
+        "text/html": "text/html";
+        "application/vnd.ant.code": "application/vnd.ant.code";
+        "application/vnd.ant.mermaid": "application/vnd.ant.mermaid";
+        "application/vnd.ant.react": "application/vnd.ant.react";
+        "image/svg+xml": "image/svg+xml";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"artifact">;
+}, z.core.$strip>;
+/** An MCP-UI resource returned by a tool. The client renders it in an isolated sandbox only. */
+export declare const UiEvent: z.ZodObject<{
+    callId: z.ZodString;
+    uri: z.ZodString;
+    mimeType: z.ZodLiteral<"text/html">;
+    html: z.ZodString;
+    preferredFrameSize: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"ui">;
+}, z.core.$strip>;
+/** A file the agent produced or mirrored, downloadable from the backend. */
+export declare const FileEvent: z.ZodObject<{
+    fileId: z.ZodString;
+    name: z.ZodString;
+    mimeType: z.ZodString;
+    bytes: z.ZodNumber;
+    path: z.ZodString;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"file">;
+}, z.core.$strip>;
+/** Token usage of one model call. Display and budgeting only. */
+export declare const UsageEvent: z.ZodObject<{
+    model: z.ZodString;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"usage">;
+}, z.core.$strip>;
+/**
+ * Streamed chat events. A well-formed stream is `start`, then any number of `delta`,
+ * `proposal`, `tool_call`, `tool_result`, `delegation`, `artifact`, `ui`, `file` and `usage`,
+ * then optionally one `error`, then exactly one `done`.
+ */
+export declare const ChatEvent: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    conversationId: z.ZodString;
+    mode: z.ZodEnum<{
+        mock: "mock";
+        live: "live";
+    }>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"start">;
+}, z.core.$strip>, z.ZodObject<{
+    text: z.ZodString;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"delta">;
+}, z.core.$strip>, z.ZodObject<{
+    operation: z.ZodUnion<readonly [z.ZodObject<{
+        target: z.ZodObject<{
+            sheet: z.ZodString;
+            address: z.ZodString;
+        }, z.core.$strip>;
+        write: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"values">;
+            values: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"formulas">;
+            formulas: z.ZodArray<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>], "type">;
+        precondition: z.ZodObject<{
+            formulas: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+            values: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>>;
+        }, z.core.$strip>;
+        operationId: z.ZodUUID;
+        documentId: z.ZodString;
+        summary: z.ZodString;
+        kind: z.ZodLiteral<"excel.writeRange">;
+    }, z.core.$strip>, z.ZodObject<{
+        target: z.ZodObject<{
+            targetId: z.ZodString;
+            expectedText: z.ZodString;
+        }, z.core.$strip>;
+        location: z.ZodEnum<{
+            before: "before";
+            after: "after";
+        }>;
+        text: z.ZodString;
+        operationId: z.ZodUUID;
+        documentId: z.ZodString;
+        summary: z.ZodString;
+        kind: z.ZodLiteral<"word.insertText">;
+    }, z.core.$strip>, z.ZodObject<{
+        target: z.ZodObject<{
+            targetId: z.ZodString;
+            expectedText: z.ZodString;
+        }, z.core.$strip>;
+        text: z.ZodString;
+        operationId: z.ZodUUID;
+        documentId: z.ZodString;
+        summary: z.ZodString;
+        kind: z.ZodLiteral<"word.replaceSelection">;
+    }, z.core.$strip>]>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"proposal">;
+}, z.core.$strip>, z.ZodObject<{
+    code: z.ZodEnum<{
+        bad_request: "bad_request";
+        unauthenticated: "unauthenticated";
+        forbidden: "forbidden";
+        not_found: "not_found";
+        message_too_large: "message_too_large";
+        rate_limited: "rate_limited";
+        upstream_unavailable: "upstream_unavailable";
+        upstream_error: "upstream_error";
+        timeout: "timeout";
+        cancelled: "cancelled";
+        internal: "internal";
+    }>;
+    message: z.ZodString;
+    retryable: z.ZodBoolean;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"error">;
+}, z.core.$strip>, z.ZodObject<{
+    finishReason: z.ZodEnum<{
+        length: "length";
+        error: "error";
+        cancelled: "cancelled";
+        stop: "stop";
+    }>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"done">;
+}, z.core.$strip>, z.ZodObject<{
+    callId: z.ZodString;
+    name: z.ZodString;
+    server: z.ZodOptional<z.ZodString>;
+    argsPreview: z.ZodString;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"tool_call">;
+}, z.core.$strip>, z.ZodObject<{
+    callId: z.ZodString;
+    status: z.ZodEnum<{
+        error: "error";
+        unauthenticated: "unauthenticated";
+        ok: "ok";
+        refused: "refused";
+    }>;
+    durationMs: z.ZodNumber;
+    summary: z.ZodString;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"tool_result">;
+}, z.core.$strip>, z.ZodObject<{
+    child: z.ZodString;
+    childRunId: z.ZodString;
+    status: z.ZodEnum<{
+        start: "start";
+        end: "end";
+    }>;
+    summary: z.ZodOptional<z.ZodString>;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"delegation">;
+}, z.core.$strip>, z.ZodObject<{
+    artifactId: z.ZodString;
+    op: z.ZodEnum<{
+        delta: "delta";
+        open: "open";
+        close: "close";
+    }>;
+    mediaType: z.ZodOptional<z.ZodEnum<{
+        "text/markdown": "text/markdown";
+        "text/html": "text/html";
+        "application/vnd.ant.code": "application/vnd.ant.code";
+        "application/vnd.ant.mermaid": "application/vnd.ant.mermaid";
+        "application/vnd.ant.react": "application/vnd.ant.react";
+        "image/svg+xml": "image/svg+xml";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"artifact">;
+}, z.core.$strip>, z.ZodObject<{
+    callId: z.ZodString;
+    uri: z.ZodString;
+    mimeType: z.ZodLiteral<"text/html">;
+    html: z.ZodString;
+    preferredFrameSize: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"ui">;
+}, z.core.$strip>, z.ZodObject<{
+    fileId: z.ZodString;
+    name: z.ZodString;
+    mimeType: z.ZodString;
+    bytes: z.ZodNumber;
+    path: z.ZodString;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"file">;
+}, z.core.$strip>, z.ZodObject<{
+    model: z.ZodString;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+    agent: z.ZodString;
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodLiteral<"usage">;
+}, z.core.$strip>], "type">;
+export type ChatEvent = z.infer<typeof ChatEvent>;
+export type ChatEventType = ChatEvent['type'];
+export type StartEvent = z.infer<typeof StartEvent>;
+export type DeltaEvent = z.infer<typeof DeltaEvent>;
+export type ProposalEvent = z.infer<typeof ProposalEvent>;
+export type ErrorEvent = z.infer<typeof ErrorEvent>;
+export type DoneEvent = z.infer<typeof DoneEvent>;
+export type ToolCallEvent = z.infer<typeof ToolCallEvent>;
+export type ToolResultEvent = z.infer<typeof ToolResultEvent>;
+export type DelegationEvent = z.infer<typeof DelegationEvent>;
+export type ArtifactEvent = z.infer<typeof ArtifactEvent>;
+export type UiEvent = z.infer<typeof UiEvent>;
+export type FileEvent = z.infer<typeof FileEvent>;
+export type UsageEvent = z.infer<typeof UsageEvent>;
+/** Event types every client must handle; the rest may be ignored by a client that cannot render them. */
+export declare const CORE_EVENT_TYPES: readonly ["start", "delta", "proposal", "error", "done"];
+/**
+ * Minimal shape of any stream event. A decoder validates this first so a client can keep its
+ * ordering guarantees for event types it does not know yet.
+ */
+export declare const EventEnvelope: z.ZodObject<{
+    requestId: z.ZodUUID;
+    seq: z.ZodNumber;
+    type: z.ZodString;
+}, z.core.$strip>;
+export type EventEnvelope = z.infer<typeof EventEnvelope>;
+/** An event of a type this client build does not know. Carries only the envelope. */
+export type UnknownEvent = {
+    type: 'unknown';
+    requestId: RequestId;
+    seq: number;
+    rawType: string;
+};
+export type DecodedChatEvent = ChatEvent | UnknownEvent;
+/** Non-stream JSON error body used for 4xx/5xx responses. */
+export declare const ApiError: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodEnum<{
+            bad_request: "bad_request";
+            unauthenticated: "unauthenticated";
+            forbidden: "forbidden";
+            not_found: "not_found";
+            message_too_large: "message_too_large";
+            rate_limited: "rate_limited";
+            upstream_unavailable: "upstream_unavailable";
+            upstream_error: "upstream_error";
+            timeout: "timeout";
+            cancelled: "cancelled";
+            internal: "internal";
+        }>;
+        message: z.ZodString;
+        correlationId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ApiError = z.infer<typeof ApiError>;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/events.js

@@ -0,0 +1,178 @@
+import { z } from 'zod';
+import { AgentKey, ArtifactId, ConversationId, FileId, RequestId, RunId, ToolCallId, } from './ids.js';
+import { LIMITS } from './limits.js';
+import { ProposedOperation } from './operations.js';
+/** Which backend produced a stream. `mock` must always be visible to the user. */
+export const BackendMode = z.enum(['mock', 'live']);
+export const ErrorCode = z.enum([
+    'bad_request',
+    'unauthenticated',
+    'forbidden',
+    'not_found',
+    'message_too_large',
+    'rate_limited',
+    'upstream_unavailable',
+    'upstream_error',
+    'timeout',
+    'cancelled',
+    'internal',
+]);
+const eventBase = {
+    requestId: RequestId,
+    /** Monotonic per-request sequence number starting at 0. */
+    seq: z.number().int().nonnegative(),
+};
+/**
+ * Which agent run an event belongs to. The router's run has no parent; a delegated child's run
+ * names the router's run as its parent. Absent on the turn-level events (`start`, `done`).
+ */
+export const AgentScope = z.object({
+    agent: AgentKey,
+    runId: RunId,
+    parentRunId: RunId.optional(),
+});
+const scoped = { ...eventBase, ...AgentScope.shape };
+export const StartEvent = z.object({
+    type: z.literal('start'),
+    ...eventBase,
+    conversationId: ConversationId,
+    mode: BackendMode,
+});
+export const DeltaEvent = z.object({ type: z.literal('delta'), ...eventBase, text: z.string() });
+export const ProposalEvent = z.object({
+    type: z.literal('proposal'),
+    ...eventBase,
+    operation: ProposedOperation,
+});
+export const ErrorEvent = z.object({
+    type: z.literal('error'),
+    ...eventBase,
+    code: ErrorCode,
+    message: z.string().max(1_000),
+    /** Whether repeating the same chat request is safe. Never true for document writes. */
+    retryable: z.boolean(),
+});
+export const DoneEvent = z.object({
+    type: z.literal('done'),
+    ...eventBase,
+    finishReason: z.enum(['stop', 'length', 'cancelled', 'error']),
+});
+/** The agent asked a tool to run. Arguments are previewed, never echoed in full. */
+export const ToolCallEvent = z.object({
+    type: z.literal('tool_call'),
+    ...scoped,
+    callId: ToolCallId,
+    name: z.string().min(1).max(128),
+    /** MCP server key for MCP tools; absent for builtins. */
+    server: z.string().min(1).max(64).optional(),
+    argsPreview: z.string().max(LIMITS.toolPreviewChars),
+});
+export const ToolResultStatus = z.enum(['ok', 'error', 'refused', 'unauthenticated']);
+export const ToolResultEvent = z.object({
+    type: z.literal('tool_result'),
+    ...scoped,
+    callId: ToolCallId,
+    status: ToolResultStatus,
+    durationMs: z.number().int().nonnegative(),
+    summary: z.string().max(LIMITS.toolPreviewChars),
+});
+/** The router handed a task to a specialist child and later got it back. */
+export const DelegationEvent = z.object({
+    type: z.literal('delegation'),
+    ...scoped,
+    child: AgentKey,
+    /** The child's run id, so its scoped events can be grouped under this delegation. */
+    childRunId: RunId,
+    status: z.enum(['start', 'end']),
+    summary: z.string().max(LIMITS.toolPreviewChars).optional(),
+});
+export const ArtifactMediaType = z.enum([
+    'text/markdown',
+    'text/html',
+    'application/vnd.ant.code',
+    'application/vnd.ant.mermaid',
+    'application/vnd.ant.react',
+    'image/svg+xml',
+]);
+/**
+ * A rendered artifact streamed alongside the answer. `open` carries the metadata, `delta`
+ * appends text, `close` ends it. Artifacts render only inside the client sandbox.
+ */
+export const ArtifactEvent = z.object({
+    type: z.literal('artifact'),
+    ...scoped,
+    artifactId: ArtifactId,
+    op: z.enum(['open', 'delta', 'close']),
+    mediaType: ArtifactMediaType.optional(),
+    title: z.string().max(200).optional(),
+    language: z.string().max(40).optional(),
+    text: z.string().max(LIMITS.artifactDeltaChars).optional(),
+});
+/** An MCP-UI resource returned by a tool. The client renders it in an isolated sandbox only. */
+export const UiEvent = z.object({
+    type: z.literal('ui'),
+    ...scoped,
+    callId: ToolCallId,
+    uri: z.string().regex(/^ui:\/\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]+$/),
+    mimeType: z.literal('text/html'),
+    html: z.string().max(LIMITS.uiHtmlChars),
+    /** `[width, height]` CSS sizes suggested by the tool. */
+    preferredFrameSize: z.tuple([z.string().max(20), z.string().max(20)]).optional(),
+});
+/** A file the agent produced or mirrored, downloadable from the backend. */
+export const FileEvent = z.object({
+    type: z.literal('file'),
+    ...scoped,
+    fileId: FileId,
+    name: z.string().min(1).max(255),
+    mimeType: z.string().min(1).max(127),
+    bytes: z.number().int().nonnegative(),
+    /** Same-origin download path on the backend; never an upstream or signed third-party URL. */
+    path: z.string().startsWith('/').max(512),
+});
+/** Token usage of one model call. Display and budgeting only. */
+export const UsageEvent = z.object({
+    type: z.literal('usage'),
+    ...scoped,
+    model: z.string().min(1).max(100),
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    cacheReadTokens: z.number().int().nonnegative().optional(),
+});
+/**
+ * Streamed chat events. A well-formed stream is `start`, then any number of `delta`,
+ * `proposal`, `tool_call`, `tool_result`, `delegation`, `artifact`, `ui`, `file` and `usage`,
+ * then optionally one `error`, then exactly one `done`.
+ */
+export const ChatEvent = z.discriminatedUnion('type', [
+    StartEvent,
+    DeltaEvent,
+    ProposalEvent,
+    ErrorEvent,
+    DoneEvent,
+    ToolCallEvent,
+    ToolResultEvent,
+    DelegationEvent,
+    ArtifactEvent,
+    UiEvent,
+    FileEvent,
+    UsageEvent,
+]);
+/** Event types every client must handle; the rest may be ignored by a client that cannot render them. */
+export const CORE_EVENT_TYPES = [
+    'start',
+    'delta',
+    'proposal',
+    'error',
+    'done',
+];
+/**
+ * Minimal shape of any stream event. A decoder validates this first so a client can keep its
+ * ordering guarantees for event types it does not know yet.
+ */
+export const EventEnvelope = z.object({ type: z.string().min(1).max(64), ...eventBase });
+/** Non-stream JSON error body used for 4xx/5xx responses. */
+export const ApiError = z.object({
+    error: z.object({ code: ErrorCode, message: z.string(), correlationId: z.string().optional() }),
+});
+//# sourceMappingURL=events.js.map