@machinemetrics/agent-event-protocol 0.1.0

package/dist/types-CttB5bnC.d.cts

@@ -0,0 +1,323 @@
+/**
+ * Content block for user input messages.
+ * Currently supports text only; extensible for multimodal content (images, files, audio).
+ */
+type UserContentBlock = {
+    type: 'text';
+    /** The text content from the user. */
+    text: string;
+};
+/**
+ * Content block variants in assistant responses.
+ * Discriminated union on `type` field.
+ */
+type AssistantContentBlock = {
+    type: 'text';
+    /** The text output from the agent. */
+    text: string;
+} | {
+    type: 'thinking';
+    /** The reasoning/thinking content from the model. */
+    text: string;
+} | {
+    type: 'tool_use';
+    /** Unique identifier for this tool call, used to correlate with tool_result. */
+    toolCallId: string;
+    /** Name of the tool being invoked. */
+    tool: string;
+    /** Arguments passed to the tool. */
+    args: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    /** Identifier of the tool call this result corresponds to. */
+    toolCallId: string;
+    /** Name of the tool that was executed. */
+    tool: string;
+    /** Whether the tool execution succeeded or failed. */
+    status: 'success' | 'error';
+    /** Optional human-readable summary of the result. Full payloads are not included. */
+    summary?: string;
+};
+/**
+ * A single message containing user input.
+ * Messages contain an array of content blocks for future multimodal support.
+ */
+type InputMessage = {
+    /** Array of content blocks in this message. */
+    content: UserContentBlock[];
+};
+/**
+ * Result from a client-side action triggered by a continuation event.
+ * Sent back to the server in the next request's context.
+ */
+type ActionResult = {
+    /** Identifier matching the actionId from the continuation event. */
+    actionId: string;
+    /** Action type, matching the kind from the continuation event. */
+    kind: string;
+    /** Whether the action completed successfully. */
+    status: 'success' | 'error';
+    /** Result data on success. Schema depends on the action kind. */
+    data?: unknown;
+    /** Error message on failure. */
+    error?: string;
+};
+/**
+ * Request payload for agent streaming endpoints.
+ * Only `messages` is required; threadId enables conversation continuity.
+ */
+type AgentRequest = {
+    /** New user input messages. Server loads prior history via threadId. */
+    messages: InputMessage[];
+    /** Optional thread identifier to resume an existing conversation. */
+    threadId?: string;
+    /** Optional context including action results and passthrough data. */
+    context?: {
+        /** Results from continuation events in the previous response. */
+        actionResults?: ActionResult[];
+        /** Additional passthrough data for the agent. */
+        [key: string]: unknown;
+    };
+};
+/**
+ * Lifecycle stage for streaming content blocks.
+ * Content events progress through start → delta(s) → stop.
+ */
+type EventStage = 'start' | 'delta' | 'stop';
+/**
+ * Error codes for protocol error events.
+ * Maps to specific HTTP status codes and retry guidance.
+ */
+type ErrorCode = 
+/** Authentication failed (401). */
+'auth_failed'
+/** Thread does not exist (404). */
+ | 'thread_not_found'
+/** Thread ownership violation (403). */
+ | 'thread_access_denied'
+/** Invalid request format or missing required fields (400). */
+ | 'invalid_message_format'
+/** Message exceeds size limit (413). */
+ | 'message_too_large'
+/** Rate limit exceeded (429). */
+ | 'rate_limit_exceeded'
+/** Stream timed out (504). */
+ | 'stream_timeout'
+/** Agent execution error (500). */
+ | 'agent_error'
+/** Tool execution error (500). */
+ | 'tool_error'
+/** Internal server error (500). */
+ | 'internal_error'
+/** Action ID not found or already resolved (400). */
+ | 'invalid_action_id';
+/**
+ * Reason why the stream finished.
+ * Determines whether additional action is needed from the client.
+ */
+type FinishReason = 
+/** Generation completed normally. */
+'stop'
+/** Generation stopped due to max tokens. */
+ | 'length'
+/** Generation stopped due to an error. */
+ | 'error'
+/** Generation paused waiting for client action (see continuation event). */
+ | 'action_required';
+/**
+ * First event in a stream, providing request and thread identifiers.
+ * Always emitted before any content events.
+ */
+type MetadataEvent = {
+    event: 'metadata';
+    /** Unique identifier for this request, present on all events. */
+    requestId: string;
+    /** Thread identifier for conversation continuity. */
+    threadId: string;
+    /** Identifier of the agent handling this request. */
+    agentId: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Streaming text content from the agent.
+ * Uses the stage lifecycle: start → delta(s) → stop.
+ */
+type TextEvent = {
+    event: 'text';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier within this request. */
+    messageId: string;
+    /** Unique identifier for this content block. */
+    blockId: string;
+    /** Index of this block within the message (on start only). */
+    blockIndex?: number;
+    /** Lifecycle stage: start, delta, or stop. */
+    stage: EventStage;
+    /** Text content chunk (on delta only). */
+    delta?: string;
+    /** Index of this delta within the block for ordering (on delta only). */
+    deltaIndex?: number;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Streaming thinking/reasoning content from the model.
+ * Structure mirrors TextEvent; represents internal reasoning.
+ */
+type ThinkingEvent = {
+    event: 'thinking';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier within this request. */
+    messageId: string;
+    /** Unique identifier for this content block. */
+    blockId: string;
+    /** Index of this block within the message (on start only). */
+    blockIndex?: number;
+    /** Lifecycle stage: start, delta, or stop. */
+    stage: EventStage;
+    /** Thinking content chunk (on delta only). */
+    delta?: string;
+    /** Index of this delta within the block for ordering (on delta only). */
+    deltaIndex?: number;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Tool invocation event with streaming argument construction.
+ * Arguments may stream as JSON fragments in delta events.
+ */
+type ToolCallEvent = {
+    event: 'tool_call';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier within this request. */
+    messageId: string;
+    /** Unique identifier for this content block. */
+    blockId: string;
+    /** Index of this block within the message (on start only). */
+    blockIndex?: number;
+    /** Lifecycle stage: start, delta, or stop. */
+    stage: EventStage;
+    /** Unique identifier for this tool call (on start and stop). */
+    toolCallId?: string;
+    /** Name of the tool being invoked (on start and stop). */
+    tool?: string;
+    /** JSON fragment of arguments (on delta only). */
+    delta?: string;
+    /** Index of this delta within the block for ordering (on delta only). */
+    deltaIndex?: number;
+    /** Complete parsed arguments (on stop only). */
+    args?: Record<string, unknown>;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Tool execution result event.
+ * Contains status and optional summary; full payloads are not included.
+ */
+type ToolResultEvent = {
+    event: 'tool_result';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier within this request. */
+    messageId: string;
+    /** Unique identifier for this content block. */
+    blockId: string;
+    /** Index of this block within the message (on start only). */
+    blockIndex?: number;
+    /** Lifecycle stage: start, delta, or stop. */
+    stage: EventStage;
+    /** Identifier of the tool call this result corresponds to. */
+    toolCallId?: string;
+    /** Name of the tool that was executed. */
+    tool?: string;
+    /** Whether the tool execution succeeded or failed (on stop only). */
+    status?: 'success' | 'error';
+    /** Optional human-readable summary of the result (on stop only). */
+    summary?: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Terminal event indicating stream completion.
+ * Contains the complete content array and usage statistics.
+ */
+type DoneEvent = {
+    event: 'done';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier within this request. */
+    messageId: string;
+    /** Thread identifier for conversation continuity. */
+    threadId: string;
+    /** All completed content blocks for this response. */
+    content: AssistantContentBlock[];
+    /** Token usage statistics. */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    /** Reason why generation finished. */
+    finishReason: FinishReason;
+    /** Optional trace identifier for debugging. */
+    traceId?: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Terminal event indicating an error condition.
+ * Includes error code and retry guidance.
+ */
+type ErrorEvent = {
+    event: 'error';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Human-readable error message. */
+    message: string;
+    /** Structured error code for programmatic handling. */
+    code?: ErrorCode;
+    /** Whether the client should retry this request. */
+    retryable?: boolean;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Terminal event acknowledging client cancellation.
+ * Sent when the client aborts the stream.
+ */
+type AbortedEvent = {
+    event: 'aborted';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier if abort occurred mid-message. */
+    messageId?: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Event requesting client-side action before continuing.
+ * Stream pauses with finishReason 'action_required' until client responds.
+ */
+type ContinuationEvent = {
+    event: 'continuation';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Unique identifier for this action, used in ActionResult. */
+    actionId: string;
+    /** Action type identifier (e.g., 'tool', 'approval', 'input', 'oauth'). */
+    kind: string;
+    /** Action-specific payload. Schema depends on the kind. */
+    payload: Record<string, unknown>;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Union of all protocol event types.
+ * Discriminated on the `event` field.
+ */
+type AgentEvent = MetadataEvent | TextEvent | ThinkingEvent | ToolCallEvent | ToolResultEvent | DoneEvent | ErrorEvent | AbortedEvent | ContinuationEvent;
+
+export type { AssistantContentBlock as A, ContinuationEvent as C, DoneEvent as D, EventStage as E, FinishReason as F, InputMessage as I, MetadataEvent as M, TextEvent as T, UserContentBlock as U, ActionResult as a, AgentRequest as b, ErrorCode as c, ThinkingEvent as d, ToolCallEvent as e, ToolResultEvent as f, ErrorEvent as g, AbortedEvent as h, AgentEvent as i };

package/dist/types-CttB5bnC.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Content block for user input messages.
+ * Currently supports text only; extensible for multimodal content (images, files, audio).
+ */
+type UserContentBlock = {
+    type: 'text';
+    /** The text content from the user. */
+    text: string;
+};
+/**
+ * Content block variants in assistant responses.
+ * Discriminated union on `type` field.
+ */
+type AssistantContentBlock = {
+    type: 'text';
+    /** The text output from the agent. */
+    text: string;
+} | {
+    type: 'thinking';
+    /** The reasoning/thinking content from the model. */
+    text: string;
+} | {
+    type: 'tool_use';
+    /** Unique identifier for this tool call, used to correlate with tool_result. */
+    toolCallId: string;
+    /** Name of the tool being invoked. */
+    tool: string;
+    /** Arguments passed to the tool. */
+    args: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    /** Identifier of the tool call this result corresponds to. */
+    toolCallId: string;
+    /** Name of the tool that was executed. */
+    tool: string;
+    /** Whether the tool execution succeeded or failed. */
+    status: 'success' | 'error';
+    /** Optional human-readable summary of the result. Full payloads are not included. */
+    summary?: string;
+};
+/**
+ * A single message containing user input.
+ * Messages contain an array of content blocks for future multimodal support.
+ */
+type InputMessage = {
+    /** Array of content blocks in this message. */
+    content: UserContentBlock[];
+};
+/**
+ * Result from a client-side action triggered by a continuation event.
+ * Sent back to the server in the next request's context.
+ */
+type ActionResult = {
+    /** Identifier matching the actionId from the continuation event. */
+    actionId: string;
+    /** Action type, matching the kind from the continuation event. */
+    kind: string;
+    /** Whether the action completed successfully. */
+    status: 'success' | 'error';
+    /** Result data on success. Schema depends on the action kind. */
+    data?: unknown;
+    /** Error message on failure. */
+    error?: string;
+};
+/**
+ * Request payload for agent streaming endpoints.
+ * Only `messages` is required; threadId enables conversation continuity.
+ */
+type AgentRequest = {
+    /** New user input messages. Server loads prior history via threadId. */
+    messages: InputMessage[];
+    /** Optional thread identifier to resume an existing conversation. */
+    threadId?: string;
+    /** Optional context including action results and passthrough data. */
+    context?: {
+        /** Results from continuation events in the previous response. */
+        actionResults?: ActionResult[];
+        /** Additional passthrough data for the agent. */
+        [key: string]: unknown;
+    };
+};
+/**
+ * Lifecycle stage for streaming content blocks.
+ * Content events progress through start → delta(s) → stop.
+ */
+type EventStage = 'start' | 'delta' | 'stop';
+/**
+ * Error codes for protocol error events.
+ * Maps to specific HTTP status codes and retry guidance.
+ */
+type ErrorCode = 
+/** Authentication failed (401). */
+'auth_failed'
+/** Thread does not exist (404). */
+ | 'thread_not_found'
+/** Thread ownership violation (403). */
+ | 'thread_access_denied'
+/** Invalid request format or missing required fields (400). */
+ | 'invalid_message_format'
+/** Message exceeds size limit (413). */
+ | 'message_too_large'
+/** Rate limit exceeded (429). */
+ | 'rate_limit_exceeded'
+/** Stream timed out (504). */
+ | 'stream_timeout'
+/** Agent execution error (500). */
+ | 'agent_error'
+/** Tool execution error (500). */
+ | 'tool_error'
+/** Internal server error (500). */
+ | 'internal_error'
+/** Action ID not found or already resolved (400). */
+ | 'invalid_action_id';
+/**
+ * Reason why the stream finished.
+ * Determines whether additional action is needed from the client.
+ */
+type FinishReason = 
+/** Generation completed normally. */
+'stop'
+/** Generation stopped due to max tokens. */
+ | 'length'
+/** Generation stopped due to an error. */
+ | 'error'
+/** Generation paused waiting for client action (see continuation event). */
+ | 'action_required';
+/**
+ * First event in a stream, providing request and thread identifiers.
+ * Always emitted before any content events.
+ */
+type MetadataEvent = {
+    event: 'metadata';
+    /** Unique identifier for this request, present on all events. */
+    requestId: string;
+    /** Thread identifier for conversation continuity. */
+    threadId: string;
+    /** Identifier of the agent handling this request. */
+    agentId: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Streaming text content from the agent.
+ * Uses the stage lifecycle: start → delta(s) → stop.
+ */
+type TextEvent = {
+    event: 'text';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier within this request. */
+    messageId: string;
+    /** Unique identifier for this content block. */
+    blockId: string;
+    /** Index of this block within the message (on start only). */
+    blockIndex?: number;
+    /** Lifecycle stage: start, delta, or stop. */
+    stage: EventStage;
+    /** Text content chunk (on delta only). */
+    delta?: string;
+    /** Index of this delta within the block for ordering (on delta only). */
+    deltaIndex?: number;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Streaming thinking/reasoning content from the model.
+ * Structure mirrors TextEvent; represents internal reasoning.
+ */
+type ThinkingEvent = {
+    event: 'thinking';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier within this request. */
+    messageId: string;
+    /** Unique identifier for this content block. */
+    blockId: string;
+    /** Index of this block within the message (on start only). */
+    blockIndex?: number;
+    /** Lifecycle stage: start, delta, or stop. */
+    stage: EventStage;
+    /** Thinking content chunk (on delta only). */
+    delta?: string;
+    /** Index of this delta within the block for ordering (on delta only). */
+    deltaIndex?: number;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Tool invocation event with streaming argument construction.
+ * Arguments may stream as JSON fragments in delta events.
+ */
+type ToolCallEvent = {
+    event: 'tool_call';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier within this request. */
+    messageId: string;
+    /** Unique identifier for this content block. */
+    blockId: string;
+    /** Index of this block within the message (on start only). */
+    blockIndex?: number;
+    /** Lifecycle stage: start, delta, or stop. */
+    stage: EventStage;
+    /** Unique identifier for this tool call (on start and stop). */
+    toolCallId?: string;
+    /** Name of the tool being invoked (on start and stop). */
+    tool?: string;
+    /** JSON fragment of arguments (on delta only). */
+    delta?: string;
+    /** Index of this delta within the block for ordering (on delta only). */
+    deltaIndex?: number;
+    /** Complete parsed arguments (on stop only). */
+    args?: Record<string, unknown>;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Tool execution result event.
+ * Contains status and optional summary; full payloads are not included.
+ */
+type ToolResultEvent = {
+    event: 'tool_result';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier within this request. */
+    messageId: string;
+    /** Unique identifier for this content block. */
+    blockId: string;
+    /** Index of this block within the message (on start only). */
+    blockIndex?: number;
+    /** Lifecycle stage: start, delta, or stop. */
+    stage: EventStage;
+    /** Identifier of the tool call this result corresponds to. */
+    toolCallId?: string;
+    /** Name of the tool that was executed. */
+    tool?: string;
+    /** Whether the tool execution succeeded or failed (on stop only). */
+    status?: 'success' | 'error';
+    /** Optional human-readable summary of the result (on stop only). */
+    summary?: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Terminal event indicating stream completion.
+ * Contains the complete content array and usage statistics.
+ */
+type DoneEvent = {
+    event: 'done';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier within this request. */
+    messageId: string;
+    /** Thread identifier for conversation continuity. */
+    threadId: string;
+    /** All completed content blocks for this response. */
+    content: AssistantContentBlock[];
+    /** Token usage statistics. */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    /** Reason why generation finished. */
+    finishReason: FinishReason;
+    /** Optional trace identifier for debugging. */
+    traceId?: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Terminal event indicating an error condition.
+ * Includes error code and retry guidance.
+ */
+type ErrorEvent = {
+    event: 'error';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Human-readable error message. */
+    message: string;
+    /** Structured error code for programmatic handling. */
+    code?: ErrorCode;
+    /** Whether the client should retry this request. */
+    retryable?: boolean;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Terminal event acknowledging client cancellation.
+ * Sent when the client aborts the stream.
+ */
+type AbortedEvent = {
+    event: 'aborted';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Message identifier if abort occurred mid-message. */
+    messageId?: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Event requesting client-side action before continuing.
+ * Stream pauses with finishReason 'action_required' until client responds.
+ */
+type ContinuationEvent = {
+    event: 'continuation';
+    /** Request identifier for correlation. */
+    requestId: string;
+    /** Unique identifier for this action, used in ActionResult. */
+    actionId: string;
+    /** Action type identifier (e.g., 'tool', 'approval', 'input', 'oauth'). */
+    kind: string;
+    /** Action-specific payload. Schema depends on the kind. */
+    payload: Record<string, unknown>;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+};
+/**
+ * Union of all protocol event types.
+ * Discriminated on the `event` field.
+ */
+type AgentEvent = MetadataEvent | TextEvent | ThinkingEvent | ToolCallEvent | ToolResultEvent | DoneEvent | ErrorEvent | AbortedEvent | ContinuationEvent;
+
+export type { AssistantContentBlock as A, ContinuationEvent as C, DoneEvent as D, EventStage as E, FinishReason as F, InputMessage as I, MetadataEvent as M, TextEvent as T, UserContentBlock as U, ActionResult as a, AgentRequest as b, ErrorCode as c, ThinkingEvent as d, ToolCallEvent as e, ToolResultEvent as f, ErrorEvent as g, AbortedEvent as h, AgentEvent as i };