Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.illa.io/llms.txt

Use this file to discover all available pages before exploring further.

This page documents high-value types used across the ILLA SDK, Chat, and polling APIs.

​
Core request/response types

​
ChatOptions

type ChatOptions = {
  id?: string
  coreApiProvider: ICoreApiProvider
  contextManager: IContextManager
  defaultRole?: PromptRole
  modelContext?: ModelContext
  userContext: UserContext
  asyncToolChecker?: AsyncToolChecker
  personalityContext?: PersonalityContext
}

​
SendMessageOptions

type SendMessageOptions = {
  signal?: AbortSignal
  onRequestId?: (requestId: string) => void
}

​
SendMessageStreamingOptions

type SendMessageStreamingOptions = {
  signal?: AbortSignal
  onEvent?: (event: TelemetryEvent) => void
  onTextDelta?: (delta: string) => void
  onComplete?: (result: ValidatedResultEventData) => void
  onError?: (error: Error) => void
}

​
SendMessageResult

type SendMessageResult = {
  chatId: string
  requestId?: string
  prompt: CoreApiChatBodyRequest['prompt']
  promptSnapshot: PromptSnapshot | PromptSnapshot[]
  messages: MessageHistoryType
  toolsConfig: ToolAutorouterRequest
  response:
    | { isError: false; data: CoreApiChatSuccessResponse }
    | { isError: true; error: CoreApiChatErrorResponse }
}

​
Context and persistence

​
IContextManager

Key methods:
  • getContext(chatId)
  • setMessages(chatId, messages)
  • appendMessages(chatId, messages)
  • setToolsConfig(chatId, toolsConfig)
  • clearContext(chatId)
  • deleteContext(chatId)

​
ChatContextSnapshot

type ChatContextSnapshot = {
  messages: MessageHistoryType
  toolsConfig: ToolAutorouterRequest
}

​
Polling and async action types

​
AsyncToolCheckerCheckParams

type AsyncToolCheckerCheckParams = {
  toolName: string
  protocol: string
  descriptor: BaseLongPollingArgs
}

​
AwaitableActionDescriptor

Alias used by awaitAction: 
type AwaitableActionDescriptor = {
  toolName: string
  protocol: string
  args: BaseLongPollingArgs
}

​
PollingConfig

type PollingConfig = {
  interval: number
  maxDuration: number
  retryThreshold: number
  maxRetries: number
}
All polling values are seconds.

​
EventSubscription

type EventSubscription = { unsubscribe(): void }

​
Pending tool payload

PendingToolCallType includes optional simulation metadata and multiple executable input shapes: 
type PendingToolCallType = {
  type: 'tool-call'
  toolCallId: string
  toolName: string
  input:
    | { type: 'SingleTransaction'; value: TransactionWithMetadata }
    | { type: 'BatchTransactions'; value: TransactionWithMetadata[] }
    | { type: 'SignatureRequests'; value: { signatureRequests: SignatureRequest[] } }
    | { type: 'ActionSequence'; value: ActionStep[] }
  simulated?: boolean
  simulation?: SimulationResult
}

​
ActionSequence

An ordered array of steps that must be executed sequentially. Each step can be a SingleTransaction, BatchTransactions, or SignatureRequests. 
{
  type: 'ActionSequence',
  value: [
    { type: 'BatchTransactions', value: [{ transaction: usdcTransfer }] },
    { type: 'SignatureRequests', value: { signatureRequests: [orderSignature] } },
  ],
}

​
SignatureRequest

Discriminated union based on signMethod: 
type SignatureRequest =
  | {
      signMethod: 'typedData'
      id: string
      signerAddress: string
      description?: string
      metadata?: Record<string, unknown>
      typedData: EIP712TypedData
    }
  | {
      signMethod: 'message'
      id: string
      signerAddress: string
      description?: string
      metadata?: Record<string, unknown>
      rawHash: string
    }

​
Simulation types

When simulation is enabled server-side, pending tools may include a SimulationResult describing the expected transaction outcome.

​
SimulationResult

type SimulationResult = {
  willSucceed: boolean
  assetChanges: AssetChange[]
  gasEstimate: GasEstimate
  errorMessage?: string
  errorExplanation?: string
  simulationId?: string
  simulatedAt: number
  actionType?: SimulationActionType
  sourceChainId?: number
  destChainId?: number
  actionMetadata?: ActionMetadata
  contractInteractions?: ContractInteraction[]
  nativeTokenSymbol?: string
}

​
AssetChange

type AssetChange = {
  tokenAddress: string
  tokenSymbol: string
  tokenName: string
  decimals: number
  rawAmount: string
  formattedAmount: string
  usdValue: string
  direction: 'in' | 'out'
  logoUrl?: string
}

​
GasEstimate

type GasEstimate = {
  gasLimit: string
  gasPrice: string
  gasCostNative: string
  gasCostUsd: string
}

​
SimulationActionType

type SimulationActionType =
  | 'transfer'
  | 'swap'
  | 'bridge'
  | 'supply'
  | 'withdraw'
  | 'contract'

​
ActionMetadata

type ActionMetadata = {
  inputToken?: string
  inputAmount?: string
  inputUsdValue?: string
  outputToken?: string
  outputAmount?: string
  outputUsdValue?: string
  chainName?: string
  destChainName?: string
  protocol?: string
  recipient?: string
}

​
ContractInteraction

type ContractInteraction = {
  address: string
  name?: string | null
  method?: string | null
  chainId: number
}

​
Narrowing result safely

const result = await sdk.sendMessage('Hello', { userContext: { address: '0x1234...' } })

if (result.response.isError) {
  console.error(result.response.error.name, result.response.error.message)
} else {
  console.log(result.response.data.text)
  console.log(result.response.data.pendingTools)
}

​
See also