@chaoslabs/ai-sdk 0.0.10 → 1.0.0

package/dist/stream.d.ts

@@ -3,7 +3,12 @@
  *
  * Utilities for parsing and working with WebSocket stream messages
  * from the Chaos AI backend.
+ *
+ * StreamMessage is a discriminated union - the `type` field determines
+ * the shape of `content`. TypeScript will narrow the content type
+ * automatically when you check the type field.
  */
+import type { Block } from "./types.js";
 export type MessageType = "agent_status_change" | "agent_message" | "report" | "follow_up_suggestions" | "user_input";
 export type AgentStatus = "processing" | "done" | "error" | "cancelled";
 export interface StreamMessageContext {
@@ -11,22 +16,212 @@ export interface StreamMessageContext {
     artifactId: string;
     query?: string;
 }
-export interface StreamMessage {
+/**
+ * Content for agent_status_change messages.
+ * Indicates the current status of the agent workflow.
+ */
+export interface AgentStatusContent {
+    status: AgentStatus;
+}
+/**
+ * Content for agent_message messages (thinking/progress messages).
+ * Contains the agent's current thinking or progress update.
+ */
+export interface AgentMessageContent {
+    messageId: string;
+    artifactId: string;
+    type: string;
+    data: AgentTextData;
+    order: number;
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The data payload within an agent message.
+ */
+export interface AgentTextData {
+    message: string;
+}
+/**
+ * A caption for a report block.
+ */
+export interface Caption {
+    label: string;
+    value: unknown;
+    group?: string;
+    collapsable?: boolean;
+}
+/**
+ * A reference used to generate the response.
+ */
+export interface Reference {
+    title: string;
+    url: string;
+    content: string;
+    hiddenUrl?: string;
+    textSpans?: number[][];
+    engineId?: string;
+}
+/**
+ * Content for report messages.
+ * Contains a block of content (markdown, table, chart, etc.)
+ */
+export interface ReportContent {
+    id: string;
+    artifactId: string;
+    type: string;
+    data: Block;
+    order: number;
+    createdAt: number;
+    updatedAt: number;
+    createdBy?: string;
+    metadata?: Record<string, unknown>;
+    captions?: Caption[];
+    references?: Reference[];
+    version?: number;
+}
+/**
+ * Content for follow_up_suggestions messages.
+ * Contains suggested follow-up queries.
+ */
+export interface FollowUpSuggestionsContent {
+    messageId: string;
+    artifactId: string;
+    type: string;
+    data: FollowUpData;
+    order: number;
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The data payload for follow-up suggestions.
+ */
+export interface FollowUpData {
+    followUpQueries: string[];
+}
+/**
+ * Content for user_input messages.
+ * Indicates the agent needs clarification from the user.
+ */
+export interface UserInputContent {
+    type: string;
+    candidates: Record<string, UserInputCandidate[]>;
+}
+/**
+ * A candidate option for user disambiguation.
+ */
+export interface UserInputCandidate {
+    symbol: string;
+    name: string;
+    market_cap: number;
+    token_id: string;
+    score: number;
+}
+interface StreamMessageBase {
     id: string;
-    type: MessageType;
     timestamp: number;
-    content: unknown;
     context: StreamMessageContext;
 }
-export declare function isAgentStatusMessage(msg: StreamMessage): boolean;
-export declare function isAgentMessage(msg: StreamMessage): boolean;
-export declare function isReportMessage(msg: StreamMessage): boolean;
-export declare function isFollowUpSuggestions(msg: StreamMessage): boolean;
-export declare function isUserInputMessage(msg: StreamMessage): boolean;
+/**
+ * Agent status change message.
+ * @example
+ * if (msg.type === 'agent_status_change') {
+ *   console.log(msg.content.status); // TypeScript knows this is AgentStatus
+ * }
+ */
+export interface AgentStatusMessage extends StreamMessageBase {
+    type: "agent_status_change";
+    content: AgentStatusContent;
+}
+/**
+ * Agent thinking/progress message.
+ * @example
+ * if (msg.type === 'agent_message') {
+ *   console.log(msg.content.data.message); // TypeScript knows the shape
+ * }
+ */
+export interface AgentTextMessage extends StreamMessageBase {
+    type: "agent_message";
+    content: AgentMessageContent;
+}
+/**
+ * Report block message (markdown, table, chart, etc.)
+ * @example
+ * if (msg.type === 'report') {
+ *   const blockData = msg.content.data; // The actual block
+ * }
+ */
+export interface ReportMessage extends StreamMessageBase {
+    type: "report";
+    content: ReportContent;
+}
+/**
+ * Follow-up suggestions message.
+ * @example
+ * if (msg.type === 'follow_up_suggestions') {
+ *   const queries = msg.content.data.followUpQueries;
+ * }
+ */
+export interface FollowUpSuggestionsMessage extends StreamMessageBase {
+    type: "follow_up_suggestions";
+    content: FollowUpSuggestionsContent;
+}
+/**
+ * User input request message.
+ * @example
+ * if (msg.type === 'user_input') {
+ *   const candidates = msg.content.candidates;
+ * }
+ */
+export interface UserInputMessage extends StreamMessageBase {
+    type: "user_input";
+    content: UserInputContent;
+}
+/**
+ * Union of all stream message types.
+ *
+ * This is a discriminated union - check the `type` field to narrow
+ * the content type automatically:
+ *
+ * @example
+ * function handleMessage(msg: StreamMessage) {
+ *   switch (msg.type) {
+ *     case 'agent_status_change':
+ *       // TypeScript knows: msg.content is AgentStatusContent
+ *       console.log(msg.content.status);
+ *       break;
+ *     case 'agent_message':
+ *       // TypeScript knows: msg.content is AgentMessageContent
+ *       console.log(msg.content.data.message);
+ *       break;
+ *     case 'report':
+ *       // TypeScript knows: msg.content is ReportContent
+ *       console.log(msg.content.data);
+ *       break;
+ *     case 'follow_up_suggestions':
+ *       // TypeScript knows: msg.content is FollowUpSuggestionsContent
+ *       console.log(msg.content.data.followUpQueries);
+ *       break;
+ *     case 'user_input':
+ *       // TypeScript knows: msg.content is UserInputContent
+ *       console.log(msg.content.candidates);
+ *       break;
+ *   }
+ * }
+ */
+export type StreamMessage = AgentStatusMessage | AgentTextMessage | ReportMessage | FollowUpSuggestionsMessage | UserInputMessage;
+export declare function isAgentStatusMessage(msg: StreamMessage): msg is AgentStatusMessage;
+export declare function isAgentMessage(msg: StreamMessage): msg is AgentTextMessage;
+export declare function isReportMessage(msg: StreamMessage): msg is ReportMessage;
+export declare function isFollowUpSuggestions(msg: StreamMessage): msg is FollowUpSuggestionsMessage;
+export declare function isUserInputMessage(msg: StreamMessage): msg is UserInputMessage;
 export declare function parseAgentStatus(msg: StreamMessage): AgentStatus | null;
 export declare function isTerminalStatus(status: AgentStatus): boolean;
 export declare function extractAgentMessageText(msg: StreamMessage): string | null;
 export declare function extractSuggestions(msg: StreamMessage): string[];
-export declare function extractReportBlock(msg: StreamMessage): unknown | null;
+export declare function extractReportBlock(msg: StreamMessage): Block | null;
 export declare function parseStreamLine(line: string): StreamMessage | null;
 export declare function parseStreamLines(text: string): StreamMessage[];
+export {};

package/dist/stream.js

@@ -3,6 +3,10 @@
  *
  * Utilities for parsing and working with WebSocket stream messages
  * from the Chaos AI backend.
+ *
+ * StreamMessage is a discriminated union - the `type` field determines
+ * the shape of `content`. TypeScript will narrow the content type
+ * automatically when you check the type field.
  */
 // ============================================================================
 // Type Guards
@@ -30,49 +34,36 @@ export function parseAgentStatus(msg) {
     if (msg.type !== "agent_status_change") {
         return null;
     }
-    const content = msg.content;
-    if (typeof content?.status === "string" &&
-        VALID_STATUSES.includes(content.status)) {
-        return content.status;
+    const status = msg.content?.status;
+    if (!status || !VALID_STATUSES.includes(status)) {
+        return null;
     }
-    return null;
+    return status;
 }
 const TERMINAL_STATUSES = ["done", "error", "cancelled"];
 export function isTerminalStatus(status) {
     return TERMINAL_STATUSES.includes(status);
 }
 // ============================================================================
-// Content Extraction
+// Content Extraction (for convenience, type guards provide same functionality)
 // ============================================================================
 export function extractAgentMessageText(msg) {
     if (msg.type !== "agent_message") {
         return null;
     }
-    const content = msg.content;
-    if (typeof content?.data?.message === "string") {
-        return content.data.message;
-    }
-    return null;
+    return msg.content?.data?.message ?? null;
 }
 export function extractSuggestions(msg) {
     if (msg.type !== "follow_up_suggestions") {
         return [];
     }
-    const content = msg.content;
-    if (Array.isArray(content?.suggestions)) {
-        return content.suggestions.filter((s) => typeof s === "string");
-    }
-    return [];
+    return msg.content?.data?.followUpQueries ?? [];
 }
 export function extractReportBlock(msg) {
     if (msg.type !== "report") {
         return null;
     }
-    const content = msg.content;
-    if (content?.data !== undefined) {
-        return content.data;
-    }
-    return null;
+    return msg.content?.data ?? null;
 }
 // ============================================================================
 // Stream Parser

package/dist/type-guards.d.ts

@@ -0,0 +1,316 @@
+import type { Block, ChartBlock, InfoBlock, CodeBlock } from './types.js';
+import type { Primitive, SwapPrimitive, BridgePrimitive, SupplyPrimitive, WithdrawPrimitive, BorrowPrimitive, RepayPrimitive, StakePrimitive, UnstakePrimitive, ClaimPrimitive, AddLiquidityPrimitive, RemoveLiquidityPrimitive, OpenPositionPrimitive, ClosePositionPrimitive, DepositPrimitive, MintPrimitive, BurnPrimitive, RestakePrimitive, ApprovePrimitive, TransferPrimitive, WrapPrimitive, UnwrapPrimitive } from './primitives.js';
+/**
+ * Type guard to check if a primitive is a swap operation.
+ *
+ * @example
+ * ```typescript
+ * if (isSwapPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is SwapParams
+ *   console.log(primitive.params.token_in);
+ *   console.log(primitive.params.token_out);
+ * }
+ * ```
+ */
+export declare function isSwapPrimitive(p: Primitive): p is SwapPrimitive;
+/**
+ * Type guard to check if a primitive is a bridge operation.
+ *
+ * @example
+ * ```typescript
+ * if (isBridgePrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is BridgeParams
+ *   console.log(primitive.params.from_chain);
+ *   console.log(primitive.params.to_chain);
+ * }
+ * ```
+ */
+export declare function isBridgePrimitive(p: Primitive): p is BridgePrimitive;
+/**
+ * Type guard to check if a primitive is a supply operation.
+ *
+ * @example
+ * ```typescript
+ * if (isSupplyPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is LendingParams
+ *   console.log(primitive.params.asset);
+ *   console.log(primitive.params.amount);
+ * }
+ * ```
+ */
+export declare function isSupplyPrimitive(p: Primitive): p is SupplyPrimitive;
+/**
+ * Type guard to check if a primitive is a withdraw operation.
+ *
+ * @example
+ * ```typescript
+ * if (isWithdrawPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is LendingParams
+ *   console.log(primitive.params.asset);
+ * }
+ * ```
+ */
+export declare function isWithdrawPrimitive(p: Primitive): p is WithdrawPrimitive;
+/**
+ * Type guard to check if a primitive is a borrow operation.
+ *
+ * @example
+ * ```typescript
+ * if (isBorrowPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is LendingParams
+ *   console.log(primitive.params.asset);
+ * }
+ * ```
+ */
+export declare function isBorrowPrimitive(p: Primitive): p is BorrowPrimitive;
+/**
+ * Type guard to check if a primitive is a repay operation.
+ *
+ * @example
+ * ```typescript
+ * if (isRepayPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is LendingParams
+ *   console.log(primitive.params.asset);
+ * }
+ * ```
+ */
+export declare function isRepayPrimitive(p: Primitive): p is RepayPrimitive;
+/**
+ * Type guard to check if a primitive is a stake operation.
+ *
+ * @example
+ * ```typescript
+ * if (isStakePrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is StakingParams
+ *   console.log(primitive.params.amount);
+ *   console.log(primitive.params.protocol);
+ * }
+ * ```
+ */
+export declare function isStakePrimitive(p: Primitive): p is StakePrimitive;
+/**
+ * Type guard to check if a primitive is an unstake operation.
+ *
+ * @example
+ * ```typescript
+ * if (isUnstakePrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is StakingParams
+ *   console.log(primitive.params.amount);
+ * }
+ * ```
+ */
+export declare function isUnstakePrimitive(p: Primitive): p is UnstakePrimitive;
+/**
+ * Type guard to check if a primitive is a claim operation.
+ *
+ * @example
+ * ```typescript
+ * if (isClaimPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is ClaimParams
+ *   console.log(primitive.params.protocol);
+ * }
+ * ```
+ */
+export declare function isClaimPrimitive(p: Primitive): p is ClaimPrimitive;
+/**
+ * Type guard to check if a primitive is an add liquidity operation.
+ *
+ * @example
+ * ```typescript
+ * if (isAddLiquidityPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is LiquidityParams
+ *   console.log(primitive.params.token_a);
+ *   console.log(primitive.params.token_b);
+ * }
+ * ```
+ */
+export declare function isAddLiquidityPrimitive(p: Primitive): p is AddLiquidityPrimitive;
+/**
+ * Type guard to check if a primitive is a remove liquidity operation.
+ *
+ * @example
+ * ```typescript
+ * if (isRemoveLiquidityPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is LiquidityParams
+ *   console.log(primitive.params.token_a);
+ * }
+ * ```
+ */
+export declare function isRemoveLiquidityPrimitive(p: Primitive): p is RemoveLiquidityPrimitive;
+/**
+ * Type guard to check if a primitive is an open position operation.
+ *
+ * @example
+ * ```typescript
+ * if (isOpenPositionPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is PositionParams
+ *   console.log(primitive.params.market);
+ *   console.log(primitive.params.side);
+ * }
+ * ```
+ */
+export declare function isOpenPositionPrimitive(p: Primitive): p is OpenPositionPrimitive;
+/**
+ * Type guard to check if a primitive is a close position operation.
+ *
+ * @example
+ * ```typescript
+ * if (isClosePositionPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is PositionParams
+ *   console.log(primitive.params.market);
+ * }
+ * ```
+ */
+export declare function isClosePositionPrimitive(p: Primitive): p is ClosePositionPrimitive;
+/**
+ * Type guard to check if a primitive is a deposit operation.
+ *
+ * @example
+ * ```typescript
+ * if (isDepositPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is DepositParams
+ *   console.log(primitive.params.vault);
+ * }
+ * ```
+ */
+export declare function isDepositPrimitive(p: Primitive): p is DepositPrimitive;
+/**
+ * Type guard to check if a primitive is a mint operation.
+ *
+ * @example
+ * ```typescript
+ * if (isMintPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is MintParams
+ *   console.log(primitive.params.asset);
+ *   console.log(primitive.params.collateral);
+ * }
+ * ```
+ */
+export declare function isMintPrimitive(p: Primitive): p is MintPrimitive;
+/**
+ * Type guard to check if a primitive is a burn operation.
+ *
+ * @example
+ * ```typescript
+ * if (isBurnPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is MintParams
+ *   console.log(primitive.params.asset);
+ * }
+ * ```
+ */
+export declare function isBurnPrimitive(p: Primitive): p is BurnPrimitive;
+/**
+ * Type guard to check if a primitive is a restake operation.
+ *
+ * @example
+ * ```typescript
+ * if (isRestakePrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is StakingParams
+ *   console.log(primitive.params.amount);
+ *   console.log(primitive.params.operator);
+ * }
+ * ```
+ */
+export declare function isRestakePrimitive(p: Primitive): p is RestakePrimitive;
+/**
+ * Type guard to check if a primitive is an approve operation.
+ *
+ * @example
+ * ```typescript
+ * if (isApprovePrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is ApproveParams
+ *   console.log(primitive.params.token);
+ *   console.log(primitive.params.spender);
+ * }
+ * ```
+ */
+export declare function isApprovePrimitive(p: Primitive): p is ApprovePrimitive;
+/**
+ * Type guard to check if a primitive is a transfer operation.
+ *
+ * @example
+ * ```typescript
+ * if (isTransferPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is TransferParams
+ *   console.log(primitive.params.token);
+ *   console.log(primitive.params.to);
+ * }
+ * ```
+ */
+export declare function isTransferPrimitive(p: Primitive): p is TransferPrimitive;
+/**
+ * Type guard to check if a primitive is a wrap operation.
+ *
+ * @example
+ * ```typescript
+ * if (isWrapPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is WrapParams
+ *   console.log(primitive.params.amount);
+ * }
+ * ```
+ */
+export declare function isWrapPrimitive(p: Primitive): p is WrapPrimitive;
+/**
+ * Type guard to check if a primitive is an unwrap operation.
+ *
+ * @example
+ * ```typescript
+ * if (isUnwrapPrimitive(primitive)) {
+ *   // TypeScript knows primitive.params is WrapParams
+ *   console.log(primitive.params.amount);
+ * }
+ * ```
+ */
+export declare function isUnwrapPrimitive(p: Primitive): p is UnwrapPrimitive;
+import type { PieChartBlock, TimeseriesChartBlock } from './types.js';
+export type { PieChartBlock, TimeseriesChartBlock };
+/**
+ * Type guard to check if a chart block is a pie chart.
+ *
+ * @example
+ * ```typescript
+ * if (isPieChartBlock(block)) {
+ *   // TypeScript knows block.chartType is 'pie'
+ *   const data = block.data; // [[label, value], ...]
+ * }
+ * ```
+ */
+export declare function isPieChartBlock(block: ChartBlock): block is PieChartBlock;
+/**
+ * Type guard to check if a chart block is a timeseries chart.
+ *
+ * @example
+ * ```typescript
+ * if (isTimeseriesChartBlock(block)) {
+ *   // TypeScript knows block.chartType is 'timeseries'
+ *   const series = block.series;
+ * }
+ * ```
+ */
+export declare function isTimeseriesChartBlock(block: ChartBlock): block is TimeseriesChartBlock;
+/**
+ * Type guard to check if a block is an info block.
+ *
+ * @example
+ * ```typescript
+ * if (isInfoBlock(block)) {
+ *   // TypeScript knows block is InfoBlock
+ *   console.log(block.message);
+ *   console.log(block.severity);
+ * }
+ * ```
+ */
+export declare function isInfoBlock(block: Block): block is InfoBlock;
+/**
+ * Type guard to check if a block is a code block.
+ *
+ * @example
+ * ```typescript
+ * if (isCodeBlock(block)) {
+ *   // TypeScript knows block is CodeBlock
+ *   console.log(block.code);
+ *   console.log(block.language);
+ * }
+ * ```
+ */
+export declare function isCodeBlock(block: Block): block is CodeBlock;