@pipedog/openai 0.0.0-stage → 0.3.0

package/dist/live/events.d.ts

@@ -0,0 +1,768 @@
+type Dict = Record<string, any>;
+/** Maximum number of startup `input` messages a session accepts. */
+export declare const MAX_INPUT_ITEMS = 128;
+/** One validation problem: where it is (wire keys) and what is wrong. */
+export interface LiveModelValidationErrorDetail {
+    loc: (string | number)[];
+    msg: string;
+}
+/** Raised when data does not match a model, like pydantic's `ValidationError`. */
+export declare class LiveModelValidationError extends Error {
+    name: string;
+    readonly title: string;
+    readonly details: LiveModelValidationErrorDetail[];
+    constructor(title: string, details: LiveModelValidationErrorDetail[]);
+    /** The list of problems (pydantic `ValidationError.errors()`). */
+    errors(): LiveModelValidationErrorDetail[];
+}
+/**
+ * Validates one value. `wire` is true when the value comes from wire data
+ * (`modelValidate`), where nested models use snake_case keys.
+ */
+type Parser<T> = (value: unknown, wire: boolean) => T;
+interface FieldSpec<T = unknown> {
+    parse: Parser<T>;
+    /** Factory for the default value; absent when the field is required. */
+    default?: () => T;
+}
+type FieldSpecs = Record<string, FieldSpec>;
+/** Options for `modelDump()`. */
+export interface ModelDumpOptions {
+    /** Leave out model fields whose value is `null`. */
+    excludeNone?: boolean;
+}
+/**
+ * Base class of the Live API models (pydantic `BaseModel`).
+ *
+ * Subclasses declare their fields with `declare` and describe them in the
+ * static `fields` table (parser and default). The constructor validates
+ * camelCase options; `modelValidate()` validates wire (snake_case) data;
+ * `modelDump()` produces wire data.
+ */
+export declare abstract class LiveModel {
+    /** Field table: name, parser and default. */
+    static readonly fields: FieldSpecs;
+    /** What to do with unknown wire keys: drop them, or keep them in `modelExtra`. */
+    static readonly extra: "ignore" | "allow";
+    /** Unknown keys kept by models created with `extra = "allow"` (pydantic `model_extra`). */
+    modelExtra: Dict | null;
+    constructor(options?: object);
+    /**
+     * Validate wire data (snake_case keys) into a model (pydantic `model_validate`).
+     *
+     * @throws LiveModelValidationError If the data does not match the model.
+     */
+    static modelValidate<C extends abstract new (...args: any[]) => LiveModel>(this: C, data: unknown): InstanceType<C>;
+    /**
+     * The wire form of the model, with upstream's snake_case keys (pydantic
+     * `model_dump`). Nested models are dumped too.
+     */
+    modelDump(options?: ModelDumpOptions): Dict;
+    /** Serialize with the wire keys, as pydantic does. */
+    toJSON(): Dict;
+}
+export interface InputTextContentOptions {
+    type?: "input_text";
+    /** The text. */
+    text: string;
+}
+/**
+ * A text content part supplied by the client.
+ *
+ * - `type`: content type, always "input_text".
+ * - `text`: the text.
+ */
+export declare class InputTextContent extends LiveModel {
+    static readonly fields: FieldSpecs;
+    type: "input_text";
+    text: string;
+    constructor(options: InputTextContentOptions);
+}
+export interface OutputTextContentOptions {
+    type?: "output_text";
+    /** The text. */
+    text: string;
+}
+/**
+ * A text content part attributed to the assistant.
+ *
+ * - `type`: content type, always "output_text".
+ * - `text`: the text.
+ */
+export declare class OutputTextContent extends LiveModel {
+    static readonly fields: FieldSpecs;
+    type: "output_text";
+    text: string;
+    constructor(options: OutputTextContentOptions);
+}
+export interface InputItemOptions {
+    type?: "message";
+    /** Message role. */
+    role: "developer" | "user" | "assistant";
+    /** Exactly one text content part. */
+    content: (InputTextContent | OutputTextContent | InputTextContentOptions | OutputTextContentOptions)[];
+}
+/**
+ * A prior text-only conversation message seeded at session start.
+ *
+ * - `type`: item type, always "message".
+ * - `role`: message role. Developer and user messages carry `input_text`
+ *   content; assistant messages carry `output_text`. A `system` role is not
+ *   accepted here: application instructions belong in
+ *   `SessionConfig.instructions` or a developer message.
+ * - `content`: exactly one text content part.
+ */
+export declare class InputItem extends LiveModel {
+    static readonly fields: FieldSpecs;
+    type: "message";
+    role: "developer" | "user" | "assistant";
+    content: (InputTextContent | OutputTextContent)[];
+    constructor(options: InputItemOptions);
+}
+export interface AudioOutputConfigOptions {
+    /** Output voice name (defaults to `marin` server-side). */
+    voice?: string | null;
+}
+/**
+ * Output audio configuration.
+ *
+ * - `voice`: output voice name (defaults to `marin` server-side).
+ */
+export declare class AudioOutputConfig extends LiveModel {
+    static readonly fields: FieldSpecs;
+    voice: string | null;
+    constructor(options?: AudioOutputConfigOptions);
+}
+export type AudioFormatType = "audio/pcm" | "audio/pcmu" | "audio/pcma";
+export interface AudioFormatOptions {
+    /** `audio/pcm` (16 or 24 kHz PCM16), `audio/pcmu` or `audio/pcma` (8 kHz G.711). */
+    type?: AudioFormatType;
+    /** Sample rate in Hz. */
+    rate?: number;
+}
+/**
+ * WebSocket audio format, selected once at session start for input and output.
+ *
+ * - `type`: `audio/pcm` (16 or 24 kHz PCM16), `audio/pcmu` or `audio/pcma`
+ *   (8 kHz G.711).
+ * - `rate`: sample rate in Hz.
+ */
+export declare class AudioFormat extends LiveModel {
+    static readonly fields: FieldSpecs;
+    type: AudioFormatType;
+    rate: number;
+    constructor(options?: AudioFormatOptions);
+}
+export interface AudioConfigOptions {
+    /** Output audio configuration. */
+    output?: AudioOutputConfig | AudioOutputConfigOptions | null;
+    /** WebSocket audio format, shared by input and output. */
+    format?: AudioFormat | AudioFormatOptions | null;
+}
+/**
+ * Session audio configuration.
+ *
+ * - `output`: output audio configuration.
+ * - `format`: WebSocket audio format, shared by input and output.
+ */
+export declare class AudioConfig extends LiveModel {
+    static readonly fields: FieldSpecs;
+    output: AudioOutputConfig | null;
+    format: AudioFormat | null;
+    constructor(options?: AudioConfigOptions);
+}
+export interface ClientDelegationConfigOptions {
+    type?: "client";
+}
+/**
+ * Delegation configuration selecting client delegation.
+ *
+ * - `type`: delegation type, always "client".
+ */
+export declare class ClientDelegationConfig extends LiveModel {
+    static readonly fields: FieldSpecs;
+    type: "client";
+    constructor(options?: ClientDelegationConfigOptions);
+}
+export interface ResponsesDelegationConfigOptions {
+    type?: "responses";
+    /** Configuration of the backend Responses model. */
+    responses: Dict;
+}
+/**
+ * Delegation configuration selecting Responses delegation.
+ *
+ * - `type`: delegation type, always "responses".
+ * - `responses`: configuration of the backend Responses model: `model`,
+ *   `instructions`, `tools`, `tool_choice`, `reasoning`,
+ *   `max_output_tokens`, `service_tier`, and other Responses request fields
+ *   the Live API accepts.
+ */
+export declare class ResponsesDelegationConfig extends LiveModel {
+    static readonly fields: FieldSpecs;
+    type: "responses";
+    responses: Dict;
+    constructor(options: ResponsesDelegationConfigOptions);
+}
+export type DelegationConfig = ClientDelegationConfig | ResponsesDelegationConfig;
+export interface SessionConfigOptions {
+    /** The live model. Required, and immutable after start. */
+    model: string;
+    /** Instructions for the live model. Immutable after start. */
+    instructions?: string | null;
+    /** Audio configuration. */
+    audio?: AudioConfig | AudioConfigOptions | null;
+    /** Delegation mode. Omitted selects client delegation. */
+    delegation?: DelegationConfig | ClientDelegationConfigOptions | ResponsesDelegationConfigOptions | null;
+    /** Prior text-only conversation messages. Startup-only. */
+    input?: (InputItem | InputItemOptions)[] | null;
+    /** Whether the server keeps the session for 30 days. Startup-only. */
+    store?: boolean | null;
+}
+/**
+ * Live session configuration, sent once with `session.start`.
+ *
+ * - `model`: the live model. Required, and immutable after start.
+ * - `instructions`: instructions for the live model. Immutable after start;
+ *   `SessionInstructionsAppendEvent` adds more later.
+ * - `audio`: audio configuration. The output voice and format are immutable
+ *   after start.
+ * - `delegation`: delegation mode. Omitted selects client delegation. The
+ *   mode is immutable: switching needs a new session.
+ * - `input`: prior text-only conversation messages. Startup-only.
+ * - `store`: whether the server keeps the session for 30 days, as a
+ *   downloadable recording and as a source for a fork. Startup-only; the
+ *   server default is false.
+ */
+export declare class SessionConfig extends LiveModel {
+    static readonly fields: FieldSpecs;
+    model: string;
+    instructions: string | null;
+    audio: AudioConfig | null;
+    delegation: DelegationConfig | null;
+    input: InputItem[] | null;
+    store: boolean | null;
+    constructor(options: SessionConfigOptions);
+}
+export interface SessionUpdateConfigOptions {
+    /** Replacement delegation settings, of the session's mode. */
+    delegation?: DelegationConfig | ClientDelegationConfigOptions | ResponsesDelegationConfigOptions | null;
+}
+/**
+ * The sparse session update a running session accepts.
+ *
+ * Only delegation settings can change, and only within the mode chosen at
+ * startup. Startup fields (`model`, `instructions`, `audio`, `input`) are not
+ * update fields.
+ *
+ * - `delegation`: replacement delegation settings, of the session's mode.
+ */
+export declare class SessionUpdateConfig extends LiveModel {
+    static readonly fields: FieldSpecs;
+    delegation: DelegationConfig | null;
+    constructor(options?: SessionUpdateConfigOptions);
+}
+export interface ClientEventOptions {
+    /**
+     * Client-chosen identifier, echoed back as `client_event_id` on
+     * acknowledgments and errors.
+     */
+    eventId?: string;
+}
+/**
+ * Base class for events sent to the Live API.
+ *
+ * - `eventId`: client-chosen identifier, echoed back as `client_event_id` on
+ *   acknowledgments and errors.
+ */
+export declare class ClientEvent extends LiveModel {
+    static readonly fields: FieldSpecs;
+    eventId: string;
+    constructor(options?: ClientEventOptions);
+    /**
+     * Render the event as the JSON payload to send.
+     *
+     * Unset optional fields are omitted: the session schema is strict about
+     * unknown fields, and a `null` is not the same as an absent field.
+     *
+     * @returns The payload.
+     */
+    toPayload(): Dict;
+}
+export interface SessionStartEventOptions extends ClientEventOptions {
+    type?: "session.start";
+    /** The session configuration, including the model. */
+    session: SessionConfig | SessionConfigOptions;
+}
+/**
+ * Start the session. The first message on a WebSocket, sent exactly once.
+ *
+ * - `type`: event type, always "session.start".
+ * - `session`: the session configuration, including the model.
+ */
+export declare class SessionStartEvent extends ClientEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.start";
+    session: SessionConfig;
+    constructor(options: SessionStartEventOptions);
+}
+export interface SessionUpdateEventOptions extends ClientEventOptions {
+    type?: "session.update";
+    /** The sparse update. */
+    session: SessionUpdateConfig | SessionUpdateConfigOptions;
+}
+/**
+ * Apply a sparse update to a running session.
+ *
+ * - `type`: event type, always "session.update".
+ * - `session`: the sparse update.
+ */
+export declare class SessionUpdateEvent extends ClientEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.update";
+    session: SessionUpdateConfig;
+    constructor(options: SessionUpdateEventOptions);
+}
+export interface InputAudioAppendEventOptions extends ClientEventOptions {
+    type?: "session.input_audio.append";
+    /** Base64-encoded audio bytes. */
+    audio: string;
+}
+/**
+ * Append audio in the session's audio format. Not acknowledged.
+ *
+ * - `type`: event type, always "session.input_audio.append".
+ * - `audio`: base64-encoded audio bytes.
+ */
+export declare class InputAudioAppendEvent extends ClientEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.input_audio.append";
+    audio: string;
+    constructor(options: InputAudioAppendEventOptions);
+}
+export interface ContextAppendEventOptions extends ClientEventOptions {
+    /**
+     * The client delegation this content belongs to, or `null` for general
+     * session context. Always sent, including when it is `null`.
+     */
+    delegationId: string | null;
+    /** The text, at most 500 tokens. */
+    content: string;
+}
+/**
+ * Base class for the three context-append events.
+ *
+ * - `delegationId`: the client delegation this content belongs to, or `null`
+ *   for general session context. Always sent, including when it is `null`.
+ * - `content`: the text, at most 500 tokens.
+ */
+export declare class ContextAppendEvent extends ClientEvent {
+    static readonly fields: FieldSpecs;
+    delegationId: string | null;
+    content: string;
+    constructor(options: ContextAppendEventOptions);
+    /**
+     * Render the event, keeping `delegation_id` even when it is `null`.
+     *
+     * The field is required on these events, and `null` is meaningful: it marks
+     * the content as general session context rather than belonging to a
+     * delegation.
+     *
+     * @returns The payload.
+     */
+    toPayload(): Dict;
+}
+/**
+ * Append instructions the live model will follow, without replacing the
+ * startup ones.
+ *
+ * - `type`: event type, always "session.instructions.append".
+ */
+export declare class SessionInstructionsAppendEvent extends ContextAppendEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.instructions.append";
+}
+/**
+ * Append information to the live model's internal reasoning.
+ *
+ * The content is not spoken when appended, though the model can draw on it
+ * when a later user request makes it relevant. It is not a secrecy boundary.
+ *
+ * - `type`: event type, always "session.thinking.append".
+ */
+export declare class SessionThinkingAppendEvent extends ContextAppendEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.thinking.append";
+}
+/**
+ * Append information for the live model to speak aloud, in its own words.
+ *
+ * - `type`: event type, always "session.commentary.append".
+ */
+export declare class SessionCommentaryAppendEvent extends ContextAppendEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.commentary.append";
+}
+export interface FunctionCallOutputItemOptions {
+    type?: "function_call_output";
+    /** The `call_id` of the completed `function_call` item. */
+    callId: string;
+    /** The function output, as a string. */
+    output: string;
+}
+/**
+ * The result of a client-actionable function call from a Responses delegation.
+ *
+ * - `type`: item type, always "function_call_output".
+ * - `callId`: the `call_id` of the completed `function_call` item.
+ * - `output`: the function output, as a string.
+ */
+export declare class FunctionCallOutputItem extends LiveModel {
+    static readonly fields: FieldSpecs;
+    type: "function_call_output";
+    callId: string;
+    output: string;
+    constructor(options: FunctionCallOutputItemOptions);
+}
+export interface ResponseItemCreateEventOptions extends ClientEventOptions {
+    type?: "response.item.create";
+    /** The input item, such as a function call output. */
+    item: FunctionCallOutputItem | Dict;
+}
+/**
+ * Queue an input item for the backend Responses model. Not acknowledged.
+ *
+ * Queueing an item does not start inference: `ResponseCreateEvent` does.
+ * Responses delegation only.
+ *
+ * - `type`: event type, always "response.item.create".
+ * - `item`: the input item, such as a function call output.
+ */
+export declare class ResponseItemCreateEvent extends ClientEvent {
+    static readonly fields: FieldSpecs;
+    type: "response.item.create";
+    item: FunctionCallOutputItem | Dict;
+    constructor(options: ResponseItemCreateEventOptions);
+}
+export interface ResponseCreateEventOptions extends ClientEventOptions {
+    type?: "response.create";
+}
+/**
+ * Start or continue delegated Responses work. Responses delegation only.
+ *
+ * Every output required by the pending response must be queued first, or the
+ * command is rejected with `function_call_outputs_required`.
+ *
+ * - `type`: event type, always "response.create".
+ */
+export declare class ResponseCreateEvent extends ClientEvent {
+    static readonly fields: FieldSpecs;
+    type: "response.create";
+    constructor(options?: ResponseCreateEventOptions);
+}
+export interface SessionCloseEventOptions extends ClientEventOptions {
+    type?: "session.close";
+}
+/**
+ * Request a graceful shutdown; the server answers with `session.closed`.
+ *
+ * - `type`: event type, always "session.close".
+ */
+export declare class SessionCloseEvent extends ClientEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.close";
+    constructor(options?: SessionCloseEventOptions);
+}
+/** Server event fields are read from wire data with `modelValidate()`. */
+export type ServerEventOptions = Dict;
+/**
+ * Base class for events received from the Live API.
+ *
+ * Unknown fields are retained (in `modelExtra`) so events keep parsing as the
+ * API grows.
+ *
+ * - `type`: the event type.
+ * - `eventId`: identifier of this server event.
+ * - `clientEventId`: the client event this one answers, when correlatable.
+ */
+export declare class ServerEvent extends LiveModel {
+    static readonly extra: "allow";
+    static readonly fields: FieldSpecs;
+    type: string;
+    eventId: string | null;
+    clientEventId: string | null;
+    constructor(options: ServerEventOptions);
+}
+/**
+ * The resolved session, echoed by `session.started`, `session.updated` and
+ * `session.closed`.
+ *
+ * - `id`: session identifier. Opaque: forward it unchanged.
+ * - `expiresAt`: session expiry as a Unix timestamp in seconds.
+ * - `status`: session status.
+ * - `model`: the live model.
+ * - `instructions`: the startup instructions.
+ * - `audio`: audio configuration.
+ * - `delegation`: delegation configuration.
+ * - `input`: the startup conversation history.
+ * - `contextManagement`: long-session context handling.
+ */
+export declare class SessionResource extends LiveModel {
+    static readonly extra: "allow";
+    static readonly fields: FieldSpecs;
+    id: string | null;
+    expiresAt: number | null;
+    status: string | null;
+    model: string | null;
+    instructions: string | null;
+    audio: Dict | null;
+    delegation: Dict | null;
+    input: Dict[] | null;
+    contextManagement: Dict | null;
+    constructor(options?: Dict);
+}
+/**
+ * The session is configured and ready for audio.
+ *
+ * - `type`: event type, always "session.started".
+ * - `session`: the resolved session.
+ */
+export declare class SessionStartedEvent extends ServerEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.started";
+    session: SessionResource;
+}
+/**
+ * A sparse `session.update` was applied.
+ *
+ * - `type`: event type, always "session.updated".
+ * - `session`: the complete resolved session, not just the changed fields.
+ */
+export declare class SessionUpdatedEvent extends ServerEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.updated";
+    session: SessionResource;
+}
+/**
+ * A chunk of output audio in the session's audio format.
+ *
+ * - `type`: event type, always "session.output_audio.delta".
+ * - `delta`: base64-encoded audio bytes.
+ */
+export declare class OutputAudioDeltaEvent extends ServerEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.output_audio.delta";
+    delta: string;
+}
+/**
+ * A timed transcript fragment of user or assistant speech.
+ *
+ * Fragments are frame-aligned, not word- or turn-aligned: accumulate them in
+ * order, and group them into turns in the application if it needs turns.
+ *
+ * - `type`: "session.input_transcript.delta" (the user) or
+ *   "session.output_transcript.delta" (the assistant).
+ * - `delta`: the fragment text.
+ * - `startMs`: start of the fragment on the session timeline.
+ * - `endMs`: end of the fragment on the session timeline.
+ */
+export declare class TranscriptDeltaEvent extends ServerEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.input_transcript.delta" | "session.output_transcript.delta";
+    delta: string;
+    startMs: number | null;
+    endMs: number | null;
+    /** The speaker. */
+    get role(): "user" | "assistant";
+}
+/**
+ * A unit of work the live model delegated.
+ *
+ * The metadata carries no task text: a client delegator works out what to do
+ * from the conversation and application state it keeps itself.
+ *
+ * - `id`: delegation identifier, used to correlate returned context. Opaque:
+ *   return it unchanged.
+ * - `type`: item type, always "delegation".
+ * - `target`: "client" or "responses".
+ * - `responseId`: for Responses delegations, the id of the Responses run.
+ */
+export declare class DelegationMetadata extends LiveModel {
+    static readonly extra: "allow";
+    static readonly fields: FieldSpecs;
+    id: string;
+    type: string;
+    target: string;
+    responseId: string | null;
+    constructor(options: Dict);
+}
+/**
+ * The live model created a delegation.
+ *
+ * - `type`: event type, always "session.delegation.created".
+ * - `offsetMs`: position on the session timeline.
+ * - `delegation`: the delegation metadata.
+ */
+export declare class SessionDelegationCreatedEvent extends ServerEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.delegation.created";
+    offsetMs: number | null;
+    delegation: DelegationMetadata;
+}
+/**
+ * An output item of a Responses delegation.
+ *
+ * - `id`: item identifier.
+ * - `type`: item type, e.g. "function_call" or "message".
+ * - `status`: item status, e.g. "completed".
+ * - `callId`: for function calls, the call identifier to answer with.
+ * - `name`: for function calls, the function name.
+ * - `arguments`: for function calls, the JSON-encoded arguments.
+ */
+export declare class ResponseOutputItem extends LiveModel {
+    static readonly extra: "allow";
+    static readonly fields: FieldSpecs;
+    id: string | null;
+    type: string | null;
+    status: string | null;
+    callId: string | null;
+    name: string | null;
+    arguments: string | null;
+    constructor(options?: Dict);
+}
+/**
+ * A Responses lifecycle event, wrapped with the delegation it belongs to.
+ *
+ * The nested event keeps its Responses meaning and is dispatched by its own
+ * complete `type`. Lifecycle snapshots inside are reduced — `output` is an
+ * empty array even at `response.completed` — so collect output items from
+ * their individual events rather than from a snapshot.
+ *
+ * - `type`: event type, always "response.event".
+ * - `delegationId`: the delegation this response belongs to, when known.
+ * - `event`: the nested Responses event.
+ */
+export declare class ResponseEventEnvelope extends ServerEvent {
+    static readonly fields: FieldSpecs;
+    type: "response.event";
+    delegationId: string | null;
+    event: Dict;
+    /** The nested Responses event's type, or `""` if it has none. */
+    get innerType(): string;
+}
+/**
+ * Appended context was accepted and placed on the session timeline.
+ *
+ * Acceptance is not proof the model has spoken the content.
+ *
+ * - `type`: "session.instructions.appended", "session.thinking.appended" or
+ *   "session.commentary.appended".
+ * - `startMs`: start of the accepted range.
+ * - `endMs`: end of the accepted range.
+ */
+export declare class ContextAppendedEvent extends ServerEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.instructions.appended" | "session.thinking.appended" | "session.commentary.appended";
+    startMs: number | null;
+    endMs: number | null;
+}
+/**
+ * Context utilization, when reported.
+ *
+ * - `usageRatio`: fraction of the context window in use.
+ */
+export declare class ContextWindowUsage extends LiveModel {
+    static readonly extra: "allow";
+    static readonly fields: FieldSpecs;
+    usageRatio: number | null;
+    constructor(options?: Dict);
+}
+/**
+ * Cumulative live session usage.
+ *
+ * Backend token usage is not here: it belongs to the wrapped Responses
+ * lifecycle, on the nested `response.completed` event.
+ *
+ * - `seconds`: cumulative live audio duration in seconds.
+ */
+export declare class Usage extends LiveModel {
+    static readonly extra: "allow";
+    static readonly fields: FieldSpecs;
+    seconds: number | null;
+    constructor(options?: Dict);
+}
+/**
+ * Periodic cumulative usage report.
+ *
+ * - `type`: event type, always "session.usage.updated".
+ * - `usage`: cumulative usage, not an increment to sum.
+ * - `contextWindow`: context utilization, when reported.
+ */
+export declare class SessionUsageUpdatedEvent extends ServerEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.usage.updated";
+    usage: Usage;
+    contextWindow: ContextWindowUsage | null;
+}
+/**
+ * Graceful shutdown completed. Transport closure alone is not finalization.
+ *
+ * - `type`: event type, always "session.closed".
+ * - `reason`: why the session closed.
+ * - `session`: the session snapshot, as configuration rather than a live
+ *   session.
+ * - `usage`: final cumulative usage.
+ */
+export declare class SessionClosedEvent extends ServerEvent {
+    static readonly fields: FieldSpecs;
+    type: "session.closed";
+    reason: string | null;
+    session: SessionResource | null;
+    usage: Usage | null;
+}
+/**
+ * The error envelope shared by Live API and normalized Responses errors.
+ *
+ * - `type`: error type, e.g. "invalid_request_error".
+ * - `code`: error code.
+ * - `message`: human-readable message.
+ * - `param`: the offending field, when one caused the failure.
+ * - `clientEventId`: the client event the error correlates to, when known.
+ */
+export declare class ErrorDetails extends LiveModel {
+    static readonly extra: "allow";
+    static readonly fields: FieldSpecs;
+    type: string | null;
+    code: string | null;
+    message: string | null;
+    param: string | null;
+    clientEventId: string | null;
+    constructor(options?: Dict);
+}
+/**
+ * A startup, validation, command or delegated-Responses error.
+ *
+ * - `type`: event type, always "error".
+ * - `error`: the error details.
+ */
+export declare class ErrorEvent extends ServerEvent {
+    static readonly fields: FieldSpecs;
+    type: "error";
+    error: ErrorDetails;
+}
+/** A server event this module doesn't model; its fields are retained as extras. */
+export declare class UnknownServerEvent extends ServerEvent {
+}
+/**
+ * Parse a server event from its JSON text.
+ *
+ * Event types this module doesn't model become `UnknownServerEvent`.
+ *
+ * @param message The JSON text of one server event, as a string or UTF-8 bytes.
+ * @returns The parsed event.
+ * @throws Error If the text isn't a JSON object with a string `type`, or a
+ *   modeled event fails validation (upstream: ValueError).
+ */
+export declare function parseServerEvent(message: string | Uint8Array): ServerEvent;
+export {};
+//# sourceMappingURL=events.d.ts.map