@octavus/core 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -48,514 +48,34 @@ declare function isOtherThread(part: {
 }): boolean;
 
 /**
- * Stream event types for Octavus agent communication.
+ * Zod schemas for stream events.
  *
- * Events are organized into two categories:
+ * Schemas are organized into two categories:
  * - Standard Events (====): Aligned with Vercel AI SDK for interoperability
  * - Octavus Events (----): Octavus-specific protocol events
  */
+
+declare const toolResultSchema: z.ZodObject<{
+    toolCallId: z.ZodString;
+    toolName: z.ZodOptional<z.ZodString>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodString>;
+    outputVariable: z.ZodOptional<z.ZodString>;
+    blockIndex: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 /**
- * Display mode - controls execution indicator visibility (NOT final message visibility).
- * - hidden: Block runs silently
- * - name: Shows block/tool name
- * - description: Shows description
- * - stream: Shows live streaming content
- */
-type DisplayMode = 'hidden' | 'name' | 'description' | 'stream';
-type ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
-type ToolHandlers = Record<string, ToolHandler>;
-type ResourceUpdateHandler = (name: string, value: unknown) => Promise<void> | void;
-type MessageRole = 'user' | 'assistant' | 'system';
-type ToolCallStatus = 'pending' | 'streaming' | 'available' | 'error';
-interface ToolCallInfo {
-    id: string;
-    name: string;
-    description?: string;
-    arguments: Record<string, unknown>;
-    status: ToolCallStatus;
-    result?: unknown;
-    error?: string;
-}
-/** Signals the start of a response message */
-interface StartEvent {
-    type: 'start';
-    messageId?: string;
-}
-/** Signals completion of streaming */
-interface FinishEvent {
-    type: 'finish';
-    finishReason: FinishReason;
-}
-/** Error during streaming */
-interface ErrorEvent {
-    type: 'error';
-    errorText: string;
-}
-type FinishReason = 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'error' | 'other';
-/**
- * Start of text generation for a specific text part.
- *
- * If `responseType` is set, the text content is JSON matching a custom type.
- * The client SDK should parse the text as a structured object instead of
- * displaying it as plain text.
- */
-interface TextStartEvent {
-    type: 'text-start';
-    id: string;
-    /**
-     * If specified, the text content is JSON matching this type name.
-     * Client SDK should parse as object, not display as text.
-     */
-    responseType?: string;
-}
-/** Incremental text content */
-interface TextDeltaEvent {
-    type: 'text-delta';
-    id: string;
-    delta: string;
-}
-/** End of text generation for a specific text part */
-interface TextEndEvent {
-    type: 'text-end';
-    id: string;
-}
-/** Start of reasoning/thinking generation */
-interface ReasoningStartEvent {
-    type: 'reasoning-start';
-    id: string;
-}
-/** Incremental reasoning content */
-interface ReasoningDeltaEvent {
-    type: 'reasoning-delta';
-    id: string;
-    delta: string;
-}
-/** End of reasoning generation */
-interface ReasoningEndEvent {
-    type: 'reasoning-end';
-    id: string;
-}
-/** Tool call initiated - input streaming will follow */
-interface ToolInputStartEvent {
-    type: 'tool-input-start';
-    toolCallId: string;
-    toolName: string;
-    /** Human-readable title/description for the tool call */
-    title?: string;
-}
-/** Incremental tool input/arguments */
-interface ToolInputDeltaEvent {
-    type: 'tool-input-delta';
-    toolCallId: string;
-    inputTextDelta: string;
-}
-/** Tool input streaming has ended */
-interface ToolInputEndEvent {
-    type: 'tool-input-end';
-    toolCallId: string;
-}
-/** Tool input is complete and available */
-interface ToolInputAvailableEvent {
-    type: 'tool-input-available';
-    toolCallId: string;
-    toolName: string;
-    input: unknown;
-}
-/** Tool output/result is available */
-interface ToolOutputAvailableEvent {
-    type: 'tool-output-available';
-    toolCallId: string;
-    output: unknown;
-}
-/** Tool execution resulted in error */
-interface ToolOutputErrorEvent {
-    type: 'tool-output-error';
-    toolCallId: string;
-    errorText: string;
-}
-/** Base source event fields */
-interface BaseSourceEvent {
-    type: 'source';
-    /** The ID of the source */
-    id: string;
-}
-/** URL source from web search or similar tools */
-interface SourceUrlEvent extends BaseSourceEvent {
-    sourceType: 'url';
-    /** The URL of the source */
-    url: string;
-    /** The title of the source */
-    title?: string;
-}
-/** Document source from file processing */
-interface SourceDocumentEvent extends BaseSourceEvent {
-    sourceType: 'document';
-    /** IANA media type of the document (e.g., 'application/pdf') */
-    mediaType: string;
-    /** The title of the document */
-    title: string;
-    /** Optional filename of the document */
-    filename?: string;
-}
-/** Source event - union of all source types */
-type SourceEvent = SourceUrlEvent | SourceDocumentEvent;
-/** Protocol block execution started */
-interface BlockStartEvent {
-    type: 'block-start';
-    blockId: string;
-    blockName: string;
-    blockType: string;
-    display: DisplayMode;
-    description?: string;
-    /** Whether output goes to main chat (false for independent blocks) */
-    outputToChat?: boolean;
-    /** Thread name (undefined or 'main' for main thread) */
-    thread?: string;
-}
-/** Protocol block execution completed */
-interface BlockEndEvent {
-    type: 'block-end';
-    blockId: string;
-    summary?: string;
-}
-/** Resource value updated */
-interface ResourceUpdateEvent {
-    type: 'resource-update';
-    name: string;
-    value: unknown;
-}
-/** Pending tool call that needs external execution (continuation pattern) */
-interface PendingToolCall {
-    toolCallId: string;
-    toolName: string;
-    args: Record<string, unknown>;
-    /** 'llm' for LLM-initiated, 'block' for protocol block */
-    source?: 'llm' | 'block';
-    /** For block-based tools: variable name to store result in */
-    outputVariable?: string;
-    /** For block-based tools: block index to resume from after execution */
-    blockIndex?: number;
-}
-/**
- * When this event is received, the stream will close.
- * Consumer should execute the tools and POST a new trigger request with toolResults.
- */
-interface ToolRequestEvent {
-    type: 'tool-request';
-    toolCalls: PendingToolCall[];
-}
-/** Result from tool execution (consumer's response to tool-request) */
-interface ToolResult {
-    toolCallId: string;
-    toolName?: string;
-    result?: unknown;
-    error?: string;
-    outputVariable?: string;
-    blockIndex?: number;
-}
-/**
- * A file generated during execution (aligned with Vercel AI SDK FilePart).
- * Used for skill outputs, image generation, code execution artifacts, etc.
- */
-interface GeneratedFile {
-    /** Unique file ID */
-    id: string;
-    /** MIME type (e.g., 'image/png', 'application/pdf') - aligned with Vercel AI SDK */
-    mediaType: string;
-    /** URL for download/display (presigned S3 URL or data URL) */
-    url: string;
-    /** Original filename (optional, for display/download) */
-    filename?: string;
-    /** Size in bytes (optional, for display) */
-    size?: number;
-}
-/**
- * File generated and available for download/display.
- * Emitted when a tool or skill produces a file output.
- */
-interface FileAvailableEvent {
-    type: 'file-available';
-    /** Unique file ID */
-    id: string;
-    /** MIME type (aligned with Vercel AI SDK) */
-    mediaType: string;
-    /** URL for download/display */
-    url: string;
-    /** Original filename */
-    filename?: string;
-    /** Size in bytes */
-    size?: number;
-    /** Tool call that generated this file */
-    toolCallId?: string;
-}
-type StreamEvent = StartEvent | FinishEvent | ErrorEvent | TextStartEvent | TextDeltaEvent | TextEndEvent | ReasoningStartEvent | ReasoningDeltaEvent | ReasoningEndEvent | ToolInputStartEvent | ToolInputDeltaEvent | ToolInputEndEvent | ToolInputAvailableEvent | ToolOutputAvailableEvent | ToolOutputErrorEvent | SourceEvent | BlockStartEvent | BlockEndEvent | ResourceUpdateEvent | ToolRequestEvent | FileAvailableEvent;
-/**
- * Type of content in a message part (internal)
- */
-type MessagePartType = 'text' | 'reasoning' | 'tool-call' | 'source' | 'file' | 'object';
-/**
- * Source info for URL sources (from web search, etc.)
+ * Schema for file references used in trigger input and user messages.
  */
-interface SourceUrlInfo {
-    sourceType: 'url';
-    id: string;
-    url: string;
-    title?: string;
-}
-/**
- * Source info for document sources (from file processing)
- */
-interface SourceDocumentInfo {
-    sourceType: 'document';
-    id: string;
-    mediaType: string;
-    title: string;
-    filename?: string;
-}
-/**
- * Source info - union of all source types (internal)
- */
-type SourceInfo = SourceUrlInfo | SourceDocumentInfo;
-/**
- * File info for generated files (from skill execution, code execution, etc.)
- */
-interface FileInfo {
-    id: string;
-    mediaType: string;
-    url: string;
-    filename?: string;
-    size?: number;
-    toolCallId?: string;
-}
-/**
- * Object info for structured output (internal storage)
- */
-interface ObjectInfo {
-    id: string;
-    /** Type name from the protocol */
-    typeName: string;
-    /** The structured object value */
-    value: unknown;
-}
-/**
- * A single part of a message, stored in order for proper display (internal)
- */
-interface MessagePart {
-    type: MessagePartType;
-    /** Whether shown in chat UI (false = LLM sees it, user doesn't) */
-    visible: boolean;
-    /** Content for text/reasoning parts */
-    content?: string;
-    /** Tool call info for tool-call parts */
-    toolCall?: ToolCallInfo;
-    /** Source info for source parts (from web search, etc.) */
-    source?: SourceInfo;
-    /** File info for file parts (from skill execution, etc.) */
-    file?: FileInfo;
-    /** Object info for object parts (structured output) */
-    object?: ObjectInfo;
-    /** Thread name for non-main-thread content (e.g., "summary") */
-    thread?: string;
-}
-/**
- * Internal chat message - stored in session state, used by LLM
- */
-interface ChatMessage {
-    id: string;
-    role: MessageRole;
-    /** Ordered parts for display - preserves reasoning/tool/text order */
-    parts: MessagePart[];
-    createdAt: string;
-    /**
-     * Whether shown in chat UI (false = LLM sees it, user doesn't).
-     * Use for internal directives. Different from `display` which controls execution indicator.
-     * @default true
-     */
-    visible?: boolean;
-    content: string;
-    toolCalls?: ToolCallInfo[];
-    reasoning?: string;
-    /** Required by Anthropic to verify reasoning blocks */
-    reasoningSignature?: string;
-}
-/**
- * Status of a UI message
- */
-type UIMessageStatus = 'streaming' | 'done';
-/**
- * Status of a UI message part
- */
-type UIPartStatus = 'streaming' | 'done';
-/**
- * Text content in a UI message
- */
-interface UITextPart {
-    type: 'text';
-    text: string;
-    status: UIPartStatus;
-    /** Thread name (undefined or 'main' for main thread) */
-    thread?: string;
-}
-/**
- * Reasoning/thinking content in a UI message
- */
-interface UIReasoningPart {
-    type: 'reasoning';
-    text: string;
-    status: UIPartStatus;
-    /** Thread name (undefined or 'main' for main thread) */
-    thread?: string;
-}
-/**
- * Tool call status for UI
- */
-type UIToolCallStatus = 'pending' | 'running' | 'done' | 'error';
-/**
- * Tool call in a UI message
- */
-interface UIToolCallPart {
-    type: 'tool-call';
-    toolCallId: string;
-    toolName: string;
-    /** Human-readable display name (from protocol description) */
-    displayName?: string;
-    args: Record<string, unknown>;
-    result?: unknown;
-    error?: string;
-    status: UIToolCallStatus;
-    /** Thread name (undefined or 'main' for main thread) */
-    thread?: string;
-}
-/**
- * Operation status for UI
- */
-type UIOperationStatus = 'running' | 'done';
-/**
- * Internal operation in a UI message (e.g., set-resource, serialize-thread)
- * These are Octavus-specific operations, not LLM tool calls
- */
-interface UIOperationPart {
-    type: 'operation';
-    operationId: string;
-    /** Human-readable name (from block name/description) */
-    name: string;
-    /** Type of operation (e.g., 'set-resource', 'serialize-thread') */
-    operationType: string;
-    status: UIOperationStatus;
-    /** Thread name (undefined or 'main' for main thread) */
-    thread?: string;
-}
-/** Base UI source part fields */
-interface BaseUISourcePart {
-    type: 'source';
-    /** The ID of the source */
-    id: string;
-    /** Thread name (undefined or 'main' for main thread) */
-    thread?: string;
-}
-/**
- * URL source part (from web search results)
- */
-interface UISourceUrlPart extends BaseUISourcePart {
-    sourceType: 'url';
-    url: string;
-    title?: string;
-}
-/**
- * Document source part (from file processing)
- */
-interface UISourceDocumentPart extends BaseUISourcePart {
-    sourceType: 'document';
-    mediaType: string;
-    title: string;
-    filename?: string;
-}
-/**
- * Source part - union of all source types
- */
-type UISourcePart = UISourceUrlPart | UISourceDocumentPart;
-/**
- * File attachment part (aligned with Vercel AI SDK FilePart).
- * Generated by skill execution, image generation, code execution, etc.
- */
-interface UIFilePart {
-    type: 'file';
-    /** Unique file ID */
-    id: string;
-    /** MIME type for rendering (aligned with Vercel AI SDK) */
-    mediaType: string;
-    /** URL for download/display (presigned URL or data URL) */
-    url: string;
-    /** Original filename (for display/download) */
-    filename?: string;
-    /** Size in bytes */
-    size?: number;
-    /** Tool call that generated this file */
-    toolCallId?: string;
-    /** Thread name (undefined or 'main' for main thread) */
-    thread?: string;
-}
-/**
- * Status of a UI object part
- */
-type UIObjectStatus = 'streaming' | 'done' | 'error';
-/**
- * Structured object part in a UI message.
- * Used when the agent response is a typed object (structured output).
- * Client applications can render custom UI based on the typeName.
- */
-interface UIObjectPart {
-    type: 'object';
-    /** Unique part ID */
-    id: string;
-    /** The type name from the protocol (e.g., "ChatResponse") */
-    typeName: string;
-    /** Partial object while streaming (may have missing/incomplete fields) */
-    partial?: unknown;
-    /** Final validated object when done */
-    object?: unknown;
-    /** Current status */
-    status: UIObjectStatus;
-    /** Error message if status is 'error' */
-    error?: string;
-    /** Thread name (undefined or 'main' for main thread) */
-    thread?: string;
-}
-/**
- * Union of all UI message part types
- */
-type UIMessagePart = UITextPart | UIReasoningPart | UIToolCallPart | UIOperationPart | UISourcePart | UIFilePart | UIObjectPart;
-/**
- * UI Message - the client-facing message format
- * All complexity is handled by the SDK, this is what consumers render
- */
-interface UIMessage {
-    id: string;
-    role: 'user' | 'assistant';
-    parts: UIMessagePart[];
-    status: UIMessageStatus;
-    createdAt: Date;
-}
-
-/**
- * Zod schemas for stream events.
- *
- * Schemas are organized into two categories:
- * - Standard Events (====): Aligned with Vercel AI SDK for interoperability
- * - Octavus Events (----): Octavus-specific protocol events
- */
-
-declare const toolResultSchema: z.ZodObject<{
-    toolCallId: z.ZodString;
-    toolName: z.ZodOptional<z.ZodString>;
-    result: z.ZodOptional<z.ZodUnknown>;
-    error: z.ZodOptional<z.ZodString>;
-    outputVariable: z.ZodOptional<z.ZodString>;
-    blockIndex: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-declare const chatMessageSchema: z.ZodObject<{
+declare const fileReferenceSchema: z.ZodObject<{
     id: z.ZodString;
-    role: z.ZodEnum<{
+    mediaType: z.ZodString;
+    url: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+    size: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const chatMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<{
         user: "user";
         assistant: "assistant";
         system: "system";
@@ -563,11 +83,11 @@ declare const chatMessageSchema: z.ZodObject<{
     parts: z.ZodArray<z.ZodObject<{
         type: z.ZodEnum<{
             object: "object";
+            file: "file";
             source: "source";
             text: "text";
             reasoning: "reasoning";
             "tool-call": "tool-call";
-            file: "file";
         }>;
         visible: z.ZodBoolean;
         content: z.ZodOptional<z.ZodString>;
@@ -807,239 +327,754 @@ declare function safeParseStreamEvent(data: unknown): z.ZodSafeParseResult<{
     sourceType: "url";
     id: string;
     url: string;
-    title?: string | undefined;
-} | {
-    type: "source";
-    sourceType: "document";
+    title?: string | undefined;
+} | {
+    type: "source";
+    sourceType: "document";
+    id: string;
+    mediaType: string;
+    title: string;
+    filename?: string | undefined;
+} | {
+    type: "start";
+    messageId?: string | undefined;
+} | {
+    type: "finish";
+    finishReason: "error" | "stop" | "tool-calls" | "length" | "content-filter" | "other";
+} | {
+    type: "error";
+    errorText: string;
+} | {
+    type: "text-start";
+    id: string;
+    responseType?: string | undefined;
+} | {
+    type: "text-delta";
+    id: string;
+    delta: string;
+} | {
+    type: "text-end";
+    id: string;
+} | {
+    type: "reasoning-start";
+    id: string;
+} | {
+    type: "reasoning-delta";
+    id: string;
+    delta: string;
+} | {
+    type: "reasoning-end";
+    id: string;
+} | {
+    type: "tool-input-start";
+    toolCallId: string;
+    toolName: string;
+    title?: string | undefined;
+} | {
+    type: "tool-input-delta";
+    toolCallId: string;
+    inputTextDelta: string;
+} | {
+    type: "tool-input-end";
+    toolCallId: string;
+} | {
+    type: "tool-input-available";
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+} | {
+    type: "tool-output-available";
+    toolCallId: string;
+    output: unknown;
+} | {
+    type: "tool-output-error";
+    toolCallId: string;
+    errorText: string;
+} | {
+    type: "block-start";
+    blockId: string;
+    blockName: string;
+    blockType: string;
+    display: "hidden" | "name" | "description" | "stream";
+    description?: string | undefined;
+    outputToChat?: boolean | undefined;
+    thread?: string | undefined;
+} | {
+    type: "block-end";
+    blockId: string;
+    summary?: string | undefined;
+} | {
+    type: "resource-update";
+    name: string;
+    value: unknown;
+} | {
+    type: "tool-request";
+    toolCalls: {
+        toolCallId: string;
+        toolName: string;
+        args: Record<string, unknown>;
+        source?: "llm" | "block" | undefined;
+        outputVariable?: string | undefined;
+        blockIndex?: number | undefined;
+    }[];
+} | {
+    type: "file-available";
+    id: string;
+    mediaType: string;
+    url: string;
+    filename?: string | undefined;
+    size?: number | undefined;
+    toolCallId?: string | undefined;
+}>;
+declare function safeParseUIMessage(data: unknown): z.ZodSafeParseResult<{
+    id: string;
+    role: "user" | "assistant";
+    parts: ({
+        type: "source";
+        sourceType: "url";
+        id: string;
+        url: string;
+        title?: string | undefined;
+        thread?: string | undefined;
+    } | {
+        type: "source";
+        sourceType: "document";
+        id: string;
+        mediaType: string;
+        title: string;
+        filename?: string | undefined;
+        thread?: string | undefined;
+    } | {
+        type: "text";
+        text: string;
+        status: "streaming" | "done";
+        thread?: string | undefined;
+    } | {
+        type: "reasoning";
+        text: string;
+        status: "streaming" | "done";
+        thread?: string | undefined;
+    } | {
+        type: "tool-call";
+        toolCallId: string;
+        toolName: string;
+        args: Record<string, unknown>;
+        status: "pending" | "error" | "done" | "running";
+        displayName?: string | undefined;
+        result?: unknown;
+        error?: string | undefined;
+        thread?: string | undefined;
+    } | {
+        type: "operation";
+        operationId: string;
+        name: string;
+        operationType: string;
+        status: "done" | "running";
+        thread?: string | undefined;
+    } | {
+        type: "file";
+        id: string;
+        mediaType: string;
+        url: string;
+        filename?: string | undefined;
+        size?: number | undefined;
+        toolCallId?: string | undefined;
+        thread?: string | undefined;
+    } | {
+        type: "object";
+        id: string;
+        typeName: string;
+        status: "streaming" | "error" | "done";
+        partial?: unknown;
+        object?: unknown;
+        error?: string | undefined;
+        thread?: string | undefined;
+    })[];
+    status: "streaming" | "done";
+    createdAt: Date;
+}>;
+declare function safeParseUIMessages(data: unknown): z.ZodSafeParseResult<{
+    id: string;
+    role: "user" | "assistant";
+    parts: ({
+        type: "source";
+        sourceType: "url";
+        id: string;
+        url: string;
+        title?: string | undefined;
+        thread?: string | undefined;
+    } | {
+        type: "source";
+        sourceType: "document";
+        id: string;
+        mediaType: string;
+        title: string;
+        filename?: string | undefined;
+        thread?: string | undefined;
+    } | {
+        type: "text";
+        text: string;
+        status: "streaming" | "done";
+        thread?: string | undefined;
+    } | {
+        type: "reasoning";
+        text: string;
+        status: "streaming" | "done";
+        thread?: string | undefined;
+    } | {
+        type: "tool-call";
+        toolCallId: string;
+        toolName: string;
+        args: Record<string, unknown>;
+        status: "pending" | "error" | "done" | "running";
+        displayName?: string | undefined;
+        result?: unknown;
+        error?: string | undefined;
+        thread?: string | undefined;
+    } | {
+        type: "operation";
+        operationId: string;
+        name: string;
+        operationType: string;
+        status: "done" | "running";
+        thread?: string | undefined;
+    } | {
+        type: "file";
+        id: string;
+        mediaType: string;
+        url: string;
+        filename?: string | undefined;
+        size?: number | undefined;
+        toolCallId?: string | undefined;
+        thread?: string | undefined;
+    } | {
+        type: "object";
+        id: string;
+        typeName: string;
+        status: "streaming" | "error" | "done";
+        partial?: unknown;
+        object?: unknown;
+        error?: string | undefined;
+        thread?: string | undefined;
+    })[];
+    status: "streaming" | "done";
+    createdAt: Date;
+}[]>;
+/**
+ * Type guard to check if a value is a FileReference object.
+ */
+declare function isFileReference(value: unknown): value is z.infer<typeof fileReferenceSchema>;
+/**
+ * Type guard to check if a value is an array of FileReference objects.
+ */
+declare function isFileReferenceArray(value: unknown): value is z.infer<typeof fileReferenceSchema>[];
+
+/**
+ * Stream event types for Octavus agent communication.
+ *
+ * Events are organized into two categories:
+ * - Standard Events (====): Aligned with Vercel AI SDK for interoperability
+ * - Octavus Events (----): Octavus-specific protocol events
+ */
+/**
+ * Display mode - controls execution indicator visibility (NOT final message visibility).
+ * - hidden: Block runs silently
+ * - name: Shows block/tool name
+ * - description: Shows description
+ * - stream: Shows live streaming content
+ */
+type DisplayMode = 'hidden' | 'name' | 'description' | 'stream';
+type ToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
+type ToolHandlers = Record<string, ToolHandler>;
+/**
+ * Reference to an uploaded file.
+ * Used in trigger input and user messages for file attachments.
+ * Compatible with UIFilePart structure for rendering.
+ */
+interface FileReference {
+    /** Unique file ID (platform-generated) */
+    id: string;
+    /** IANA media type (e.g., 'image/png', 'application/pdf') */
+    mediaType: string;
+    /** Presigned download URL (S3) */
+    url: string;
+    /** Original filename */
+    filename?: string;
+    /** File size in bytes */
+    size?: number;
+}
+type ResourceUpdateHandler = (name: string, value: unknown) => Promise<void> | void;
+type MessageRole = 'user' | 'assistant' | 'system';
+type ToolCallStatus = 'pending' | 'streaming' | 'available' | 'error';
+interface ToolCallInfo {
+    id: string;
+    name: string;
+    description?: string;
+    arguments: Record<string, unknown>;
+    status: ToolCallStatus;
+    result?: unknown;
+    error?: string;
+}
+/** Signals the start of a response message */
+interface StartEvent {
+    type: 'start';
+    messageId?: string;
+}
+/** Signals completion of streaming */
+interface FinishEvent {
+    type: 'finish';
+    finishReason: FinishReason;
+}
+/** Error during streaming */
+interface ErrorEvent {
+    type: 'error';
+    errorText: string;
+}
+type FinishReason = 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'error' | 'other';
+/**
+ * Start of text generation for a specific text part.
+ *
+ * If `responseType` is set, the text content is JSON matching a custom type.
+ * The client SDK should parse the text as a structured object instead of
+ * displaying it as plain text.
+ */
+interface TextStartEvent {
+    type: 'text-start';
+    id: string;
+    /**
+     * If specified, the text content is JSON matching this type name.
+     * Client SDK should parse as object, not display as text.
+     */
+    responseType?: string;
+}
+/** Incremental text content */
+interface TextDeltaEvent {
+    type: 'text-delta';
+    id: string;
+    delta: string;
+}
+/** End of text generation for a specific text part */
+interface TextEndEvent {
+    type: 'text-end';
+    id: string;
+}
+/** Start of reasoning/thinking generation */
+interface ReasoningStartEvent {
+    type: 'reasoning-start';
+    id: string;
+}
+/** Incremental reasoning content */
+interface ReasoningDeltaEvent {
+    type: 'reasoning-delta';
+    id: string;
+    delta: string;
+}
+/** End of reasoning generation */
+interface ReasoningEndEvent {
+    type: 'reasoning-end';
+    id: string;
+}
+/** Tool call initiated - input streaming will follow */
+interface ToolInputStartEvent {
+    type: 'tool-input-start';
+    toolCallId: string;
+    toolName: string;
+    /** Human-readable title/description for the tool call */
+    title?: string;
+}
+/** Incremental tool input/arguments */
+interface ToolInputDeltaEvent {
+    type: 'tool-input-delta';
+    toolCallId: string;
+    inputTextDelta: string;
+}
+/** Tool input streaming has ended */
+interface ToolInputEndEvent {
+    type: 'tool-input-end';
+    toolCallId: string;
+}
+/** Tool input is complete and available */
+interface ToolInputAvailableEvent {
+    type: 'tool-input-available';
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+/** Tool output/result is available */
+interface ToolOutputAvailableEvent {
+    type: 'tool-output-available';
+    toolCallId: string;
+    output: unknown;
+}
+/** Tool execution resulted in error */
+interface ToolOutputErrorEvent {
+    type: 'tool-output-error';
+    toolCallId: string;
+    errorText: string;
+}
+/** Base source event fields */
+interface BaseSourceEvent {
+    type: 'source';
+    /** The ID of the source */
+    id: string;
+}
+/** URL source from web search or similar tools */
+interface SourceUrlEvent extends BaseSourceEvent {
+    sourceType: 'url';
+    /** The URL of the source */
+    url: string;
+    /** The title of the source */
+    title?: string;
+}
+/** Document source from file processing */
+interface SourceDocumentEvent extends BaseSourceEvent {
+    sourceType: 'document';
+    /** IANA media type of the document (e.g., 'application/pdf') */
+    mediaType: string;
+    /** The title of the document */
+    title: string;
+    /** Optional filename of the document */
+    filename?: string;
+}
+/** Source event - union of all source types */
+type SourceEvent = SourceUrlEvent | SourceDocumentEvent;
+/** Protocol block execution started */
+interface BlockStartEvent {
+    type: 'block-start';
+    blockId: string;
+    blockName: string;
+    blockType: string;
+    display: DisplayMode;
+    description?: string;
+    /** Whether output goes to main chat (false for independent blocks) */
+    outputToChat?: boolean;
+    /** Thread name (undefined or 'main' for main thread) */
+    thread?: string;
+}
+/** Protocol block execution completed */
+interface BlockEndEvent {
+    type: 'block-end';
+    blockId: string;
+    summary?: string;
+}
+/** Resource value updated */
+interface ResourceUpdateEvent {
+    type: 'resource-update';
+    name: string;
+    value: unknown;
+}
+/** Pending tool call that needs external execution (continuation pattern) */
+interface PendingToolCall {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    /** 'llm' for LLM-initiated, 'block' for protocol block */
+    source?: 'llm' | 'block';
+    /** For block-based tools: variable name to store result in */
+    outputVariable?: string;
+    /** For block-based tools: block index to resume from after execution */
+    blockIndex?: number;
+}
+/**
+ * When this event is received, the stream will close.
+ * Consumer should execute the tools and POST a new trigger request with toolResults.
+ */
+interface ToolRequestEvent {
+    type: 'tool-request';
+    toolCalls: PendingToolCall[];
+}
+/** Result from tool execution (consumer's response to tool-request) */
+interface ToolResult {
+    toolCallId: string;
+    toolName?: string;
+    result?: unknown;
+    error?: string;
+    outputVariable?: string;
+    blockIndex?: number;
+}
+/**
+ * A file generated during execution (aligned with Vercel AI SDK FilePart).
+ * Used for skill outputs, image generation, code execution artifacts, etc.
+ */
+interface GeneratedFile {
+    /** Unique file ID */
+    id: string;
+    /** MIME type (e.g., 'image/png', 'application/pdf') - aligned with Vercel AI SDK */
+    mediaType: string;
+    /** URL for download/display (presigned S3 URL or data URL) */
+    url: string;
+    /** Original filename (optional, for display/download) */
+    filename?: string;
+    /** Size in bytes (optional, for display) */
+    size?: number;
+}
+/**
+ * File generated and available for download/display.
+ * Emitted when a tool or skill produces a file output.
+ */
+interface FileAvailableEvent {
+    type: 'file-available';
+    /** Unique file ID */
     id: string;
+    /** MIME type (aligned with Vercel AI SDK) */
     mediaType: string;
-    title: string;
-    filename?: string | undefined;
-} | {
-    type: "start";
-    messageId?: string | undefined;
-} | {
-    type: "finish";
-    finishReason: "error" | "stop" | "tool-calls" | "length" | "content-filter" | "other";
-} | {
-    type: "error";
-    errorText: string;
-} | {
-    type: "text-start";
-    id: string;
-    responseType?: string | undefined;
-} | {
-    type: "text-delta";
+    /** URL for download/display */
+    url: string;
+    /** Original filename */
+    filename?: string;
+    /** Size in bytes */
+    size?: number;
+    /** Tool call that generated this file */
+    toolCallId?: string;
+}
+type StreamEvent = StartEvent | FinishEvent | ErrorEvent | TextStartEvent | TextDeltaEvent | TextEndEvent | ReasoningStartEvent | ReasoningDeltaEvent | ReasoningEndEvent | ToolInputStartEvent | ToolInputDeltaEvent | ToolInputEndEvent | ToolInputAvailableEvent | ToolOutputAvailableEvent | ToolOutputErrorEvent | SourceEvent | BlockStartEvent | BlockEndEvent | ResourceUpdateEvent | ToolRequestEvent | FileAvailableEvent;
+/**
+ * Type of content in a message part (internal)
+ */
+type MessagePartType = 'text' | 'reasoning' | 'tool-call' | 'source' | 'file' | 'object';
+/**
+ * Source info for URL sources (from web search, etc.)
+ */
+interface SourceUrlInfo {
+    sourceType: 'url';
     id: string;
-    delta: string;
-} | {
-    type: "text-end";
+    url: string;
+    title?: string;
+}
+/**
+ * Source info for document sources (from file processing)
+ */
+interface SourceDocumentInfo {
+    sourceType: 'document';
     id: string;
-} | {
-    type: "reasoning-start";
+    mediaType: string;
+    title: string;
+    filename?: string;
+}
+/**
+ * Source info - union of all source types (internal)
+ */
+type SourceInfo = SourceUrlInfo | SourceDocumentInfo;
+/**
+ * File info for generated files (from skill execution, code execution, etc.)
+ */
+interface FileInfo {
     id: string;
-} | {
-    type: "reasoning-delta";
+    mediaType: string;
+    url: string;
+    filename?: string;
+    size?: number;
+    toolCallId?: string;
+}
+/**
+ * Object info for structured output (internal storage)
+ */
+interface ObjectInfo {
     id: string;
-    delta: string;
-} | {
-    type: "reasoning-end";
+    /** Type name from the protocol */
+    typeName: string;
+    /** The structured object value */
+    value: unknown;
+}
+/**
+ * A single part of a message, stored in order for proper display (internal)
+ */
+interface MessagePart {
+    type: MessagePartType;
+    /** Whether shown in chat UI (false = LLM sees it, user doesn't) */
+    visible: boolean;
+    /** Content for text/reasoning parts */
+    content?: string;
+    /** Tool call info for tool-call parts */
+    toolCall?: ToolCallInfo;
+    /** Source info for source parts (from web search, etc.) */
+    source?: SourceInfo;
+    /** File info for file parts (from skill execution, etc.) */
+    file?: FileInfo;
+    /** Object info for object parts (structured output) */
+    object?: ObjectInfo;
+    /** Thread name for non-main-thread content (e.g., "summary") */
+    thread?: string;
+}
+/**
+ * Internal chat message - stored in session state, used by LLM
+ */
+interface ChatMessage {
     id: string;
-} | {
-    type: "tool-input-start";
-    toolCallId: string;
-    toolName: string;
-    title?: string | undefined;
-} | {
-    type: "tool-input-delta";
-    toolCallId: string;
-    inputTextDelta: string;
-} | {
-    type: "tool-input-end";
-    toolCallId: string;
-} | {
-    type: "tool-input-available";
+    role: MessageRole;
+    /** Ordered parts for display - preserves reasoning/tool/text order */
+    parts: MessagePart[];
+    createdAt: string;
+    /**
+     * Whether shown in chat UI (false = LLM sees it, user doesn't).
+     * Use for internal directives. Different from `display` which controls execution indicator.
+     * @default true
+     */
+    visible?: boolean;
+    content: string;
+    toolCalls?: ToolCallInfo[];
+    reasoning?: string;
+    /** Required by Anthropic to verify reasoning blocks */
+    reasoningSignature?: string;
+}
+/**
+ * Status of a UI message
+ */
+type UIMessageStatus = 'streaming' | 'done';
+/**
+ * Status of a UI message part
+ */
+type UIPartStatus = 'streaming' | 'done';
+/**
+ * Text content in a UI message
+ */
+interface UITextPart {
+    type: 'text';
+    text: string;
+    status: UIPartStatus;
+    /** Thread name (undefined or 'main' for main thread) */
+    thread?: string;
+}
+/**
+ * Reasoning/thinking content in a UI message
+ */
+interface UIReasoningPart {
+    type: 'reasoning';
+    text: string;
+    status: UIPartStatus;
+    /** Thread name (undefined or 'main' for main thread) */
+    thread?: string;
+}
+/**
+ * Tool call status for UI
+ */
+type UIToolCallStatus = 'pending' | 'running' | 'done' | 'error';
+/**
+ * Tool call in a UI message
+ */
+interface UIToolCallPart {
+    type: 'tool-call';
     toolCallId: string;
     toolName: string;
-    input: unknown;
-} | {
-    type: "tool-output-available";
-    toolCallId: string;
-    output: unknown;
-} | {
-    type: "tool-output-error";
-    toolCallId: string;
-    errorText: string;
-} | {
-    type: "block-start";
-    blockId: string;
-    blockName: string;
-    blockType: string;
-    display: "hidden" | "name" | "description" | "stream";
-    description?: string | undefined;
-    outputToChat?: boolean | undefined;
-    thread?: string | undefined;
-} | {
-    type: "block-end";
-    blockId: string;
-    summary?: string | undefined;
-} | {
-    type: "resource-update";
+    /** Human-readable display name (from protocol description) */
+    displayName?: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+    error?: string;
+    status: UIToolCallStatus;
+    /** Thread name (undefined or 'main' for main thread) */
+    thread?: string;
+}
+/**
+ * Operation status for UI
+ */
+type UIOperationStatus = 'running' | 'done';
+/**
+ * Internal operation in a UI message (e.g., set-resource, serialize-thread)
+ * These are Octavus-specific operations, not LLM tool calls
+ */
+interface UIOperationPart {
+    type: 'operation';
+    operationId: string;
+    /** Human-readable name (from block name/description) */
     name: string;
-    value: unknown;
-} | {
-    type: "tool-request";
-    toolCalls: {
-        toolCallId: string;
-        toolName: string;
-        args: Record<string, unknown>;
-        source?: "llm" | "block" | undefined;
-        outputVariable?: string | undefined;
-        blockIndex?: number | undefined;
-    }[];
-} | {
-    type: "file-available";
+    /** Type of operation (e.g., 'set-resource', 'serialize-thread') */
+    operationType: string;
+    status: UIOperationStatus;
+    /** Thread name (undefined or 'main' for main thread) */
+    thread?: string;
+}
+/** Base UI source part fields */
+interface BaseUISourcePart {
+    type: 'source';
+    /** The ID of the source */
+    id: string;
+    /** Thread name (undefined or 'main' for main thread) */
+    thread?: string;
+}
+/**
+ * URL source part (from web search results)
+ */
+interface UISourceUrlPart extends BaseUISourcePart {
+    sourceType: 'url';
+    url: string;
+    title?: string;
+}
+/**
+ * Document source part (from file processing)
+ */
+interface UISourceDocumentPart extends BaseUISourcePart {
+    sourceType: 'document';
+    mediaType: string;
+    title: string;
+    filename?: string;
+}
+/**
+ * Source part - union of all source types
+ */
+type UISourcePart = UISourceUrlPart | UISourceDocumentPart;
+/**
+ * File attachment part (aligned with Vercel AI SDK FilePart).
+ * Generated by skill execution, image generation, code execution, etc.
+ */
+interface UIFilePart {
+    type: 'file';
+    /** Unique file ID */
     id: string;
+    /** MIME type for rendering (aligned with Vercel AI SDK) */
     mediaType: string;
+    /** URL for download/display (presigned URL or data URL) */
     url: string;
-    filename?: string | undefined;
-    size?: number | undefined;
-    toolCallId?: string | undefined;
-}>;
-declare function safeParseUIMessage(data: unknown): z.ZodSafeParseResult<{
+    /** Original filename (for display/download) */
+    filename?: string;
+    /** Size in bytes */
+    size?: number;
+    /** Tool call that generated this file */
+    toolCallId?: string;
+    /** Thread name (undefined or 'main' for main thread) */
+    thread?: string;
+}
+/**
+ * Status of a UI object part
+ */
+type UIObjectStatus = 'streaming' | 'done' | 'error';
+/**
+ * Structured object part in a UI message.
+ * Used when the agent response is a typed object (structured output).
+ * Client applications can render custom UI based on the typeName.
+ */
+interface UIObjectPart {
+    type: 'object';
+    /** Unique part ID */
     id: string;
-    role: "user" | "assistant";
-    parts: ({
-        type: "source";
-        sourceType: "url";
-        id: string;
-        url: string;
-        title?: string | undefined;
-        thread?: string | undefined;
-    } | {
-        type: "source";
-        sourceType: "document";
-        id: string;
-        mediaType: string;
-        title: string;
-        filename?: string | undefined;
-        thread?: string | undefined;
-    } | {
-        type: "text";
-        text: string;
-        status: "streaming" | "done";
-        thread?: string | undefined;
-    } | {
-        type: "reasoning";
-        text: string;
-        status: "streaming" | "done";
-        thread?: string | undefined;
-    } | {
-        type: "tool-call";
-        toolCallId: string;
-        toolName: string;
-        args: Record<string, unknown>;
-        status: "pending" | "error" | "done" | "running";
-        displayName?: string | undefined;
-        result?: unknown;
-        error?: string | undefined;
-        thread?: string | undefined;
-    } | {
-        type: "operation";
-        operationId: string;
-        name: string;
-        operationType: string;
-        status: "done" | "running";
-        thread?: string | undefined;
-    } | {
-        type: "file";
-        id: string;
-        mediaType: string;
-        url: string;
-        filename?: string | undefined;
-        size?: number | undefined;
-        toolCallId?: string | undefined;
-        thread?: string | undefined;
-    } | {
-        type: "object";
-        id: string;
-        typeName: string;
-        status: "streaming" | "error" | "done";
-        partial?: unknown;
-        object?: unknown;
-        error?: string | undefined;
-        thread?: string | undefined;
-    })[];
-    status: "streaming" | "done";
-    createdAt: Date;
-}>;
-declare function safeParseUIMessages(data: unknown): z.ZodSafeParseResult<{
+    /** The type name from the protocol (e.g., "ChatResponse") */
+    typeName: string;
+    /** Partial object while streaming (may have missing/incomplete fields) */
+    partial?: unknown;
+    /** Final validated object when done */
+    object?: unknown;
+    /** Current status */
+    status: UIObjectStatus;
+    /** Error message if status is 'error' */
+    error?: string;
+    /** Thread name (undefined or 'main' for main thread) */
+    thread?: string;
+}
+/**
+ * Union of all UI message part types
+ */
+type UIMessagePart = UITextPart | UIReasoningPart | UIToolCallPart | UIOperationPart | UISourcePart | UIFilePart | UIObjectPart;
+/**
+ * UI Message - the client-facing message format
+ * All complexity is handled by the SDK, this is what consumers render
+ */
+interface UIMessage {
     id: string;
-    role: "user" | "assistant";
-    parts: ({
-        type: "source";
-        sourceType: "url";
-        id: string;
-        url: string;
-        title?: string | undefined;
-        thread?: string | undefined;
-    } | {
-        type: "source";
-        sourceType: "document";
-        id: string;
-        mediaType: string;
-        title: string;
-        filename?: string | undefined;
-        thread?: string | undefined;
-    } | {
-        type: "text";
-        text: string;
-        status: "streaming" | "done";
-        thread?: string | undefined;
-    } | {
-        type: "reasoning";
-        text: string;
-        status: "streaming" | "done";
-        thread?: string | undefined;
-    } | {
-        type: "tool-call";
-        toolCallId: string;
-        toolName: string;
-        args: Record<string, unknown>;
-        status: "pending" | "error" | "done" | "running";
-        displayName?: string | undefined;
-        result?: unknown;
-        error?: string | undefined;
-        thread?: string | undefined;
-    } | {
-        type: "operation";
-        operationId: string;
-        name: string;
-        operationType: string;
-        status: "done" | "running";
-        thread?: string | undefined;
-    } | {
-        type: "file";
-        id: string;
-        mediaType: string;
-        url: string;
-        filename?: string | undefined;
-        size?: number | undefined;
-        toolCallId?: string | undefined;
-        thread?: string | undefined;
-    } | {
-        type: "object";
-        id: string;
-        typeName: string;
-        status: "streaming" | "error" | "done";
-        partial?: unknown;
-        object?: unknown;
-        error?: string | undefined;
-        thread?: string | undefined;
-    })[];
-    status: "streaming" | "done";
+    role: 'user' | 'assistant';
+    parts: UIMessagePart[];
+    status: UIMessageStatus;
     createdAt: Date;
-}[]>;
+}
 
 /**
  * Octavus skill tool names
@@ -1086,4 +1121,4 @@ declare function isOctavusSkillTool(toolName: string): toolName is OctavusSkillT
  */
 declare function getSkillSlugFromToolCall(toolName: string, args: Record<string, unknown> | undefined): string | undefined;
 
-export { AppError, type BlockEndEvent, type BlockStartEvent, type ChatMessage, ConflictError, type DisplayMode, type ErrorEvent, type FileAvailableEvent, type FileInfo, type FinishEvent, type FinishReason, type GeneratedFile, MAIN_THREAD, type MessagePart, type MessagePartType, type MessageRole, NotFoundError, OCTAVUS_SKILL_TOOLS, type ObjectInfo, type OctavusSkillToolName, type PendingToolCall, type ReasoningDeltaEvent, type ReasoningEndEvent, type ReasoningStartEvent, type ResourceUpdateEvent, type ResourceUpdateHandler, type SourceDocumentEvent, type SourceDocumentInfo, type SourceEvent, type SourceInfo, type SourceUrlEvent, type SourceUrlInfo, type StartEvent, type StreamEvent, type TextDeltaEvent, type TextEndEvent, type TextStartEvent, type ToolCallInfo, type ToolCallStatus, type ToolHandler, type ToolHandlers, type ToolInputAvailableEvent, type ToolInputDeltaEvent, type ToolInputEndEvent, type ToolInputStartEvent, type ToolOutputAvailableEvent, type ToolOutputErrorEvent, type ToolRequestEvent, type ToolResult, type UIFilePart, type UIMessage, type UIMessagePart, type UIMessageStatus, type UIObjectPart, type UIObjectStatus, type UIOperationPart, type UIOperationStatus, type UIPartStatus, type UIReasoningPart, type UISourceDocumentPart, type UISourcePart, type UISourceUrlPart, type UITextPart, type UIToolCallPart, type UIToolCallStatus, ValidationError, chatMessageSchema, generateId, getSkillSlugFromToolCall, isMainThread, isOctavusSkillTool, isOtherThread, resolveThread, safeParseStreamEvent, safeParseUIMessage, safeParseUIMessages, threadForPart, toolResultSchema, uiMessagePartSchema, uiMessageSchema };
+export { AppError, type BlockEndEvent, type BlockStartEvent, type ChatMessage, ConflictError, type DisplayMode, type ErrorEvent, type FileAvailableEvent, type FileInfo, type FileReference, type FinishEvent, type FinishReason, type GeneratedFile, MAIN_THREAD, type MessagePart, type MessagePartType, type MessageRole, NotFoundError, OCTAVUS_SKILL_TOOLS, type ObjectInfo, type OctavusSkillToolName, type PendingToolCall, type ReasoningDeltaEvent, type ReasoningEndEvent, type ReasoningStartEvent, type ResourceUpdateEvent, type ResourceUpdateHandler, type SourceDocumentEvent, type SourceDocumentInfo, type SourceEvent, type SourceInfo, type SourceUrlEvent, type SourceUrlInfo, type StartEvent, type StreamEvent, type TextDeltaEvent, type TextEndEvent, type TextStartEvent, type ToolCallInfo, type ToolCallStatus, type ToolHandler, type ToolHandlers, type ToolInputAvailableEvent, type ToolInputDeltaEvent, type ToolInputEndEvent, type ToolInputStartEvent, type ToolOutputAvailableEvent, type ToolOutputErrorEvent, type ToolRequestEvent, type ToolResult, type UIFilePart, type UIMessage, type UIMessagePart, type UIMessageStatus, type UIObjectPart, type UIObjectStatus, type UIOperationPart, type UIOperationStatus, type UIPartStatus, type UIReasoningPart, type UISourceDocumentPart, type UISourcePart, type UISourceUrlPart, type UITextPart, type UIToolCallPart, type UIToolCallStatus, ValidationError, chatMessageSchema, fileReferenceSchema, generateId, getSkillSlugFromToolCall, isFileReference, isFileReferenceArray, isMainThread, isOctavusSkillTool, isOtherThread, resolveThread, safeParseStreamEvent, safeParseUIMessage, safeParseUIMessages, threadForPart, toolResultSchema, uiMessagePartSchema, uiMessageSchema };