PlanStream

executePlan(
  plan: ExecutionPlan,
  options?: { signal?: AbortSignal },
): Promise<PlanStream>

sendStepDecision(
  decision: StepDecision,
  options?: { signal?: AbortSignal },
): Promise<CoreApiChatResponse>

new PlanStream(stream: ReadableStream<Uint8Array>, options?: PlanStreamOptions)

on<T>(eventType: T, handler: (event) => void): void   // register a handler (multiple allowed per type)
off<T>(eventType: T, handler): void                   // remove a handler
close(): void                                         // abort the stream and release resources
isClosed(): boolean                                   // whether the stream has closed

import { IllaSDK } from '@illalabs/sdk'
import type { ExecutionPlan } from '@illalabs/sdk'

const sdk = new IllaSDK({ apiKey: process.env.ILLA_API_KEY! })

// 1. A planning-enabled chat turn returns a plan to approve.
const turn = await sdk.sendMessage(
  'Swap 1 ETH to USDC, then supply the USDC to Aave on Base',
  { userContext: { address: '0x1234...' } },
)

if (turn.response.isError) {
  throw new Error(turn.response.error.message)
}

const plan: ExecutionPlan | undefined = turn.response.data.plan

if (!plan) {
  // Planning was not enabled for this key/environment — treat as a normal chat turn.
  console.log(turn.response.data.text)
} else {
  // 2. After the user approves, stream the plan's execution.
  const stream = await sdk.executePlan(plan)

  stream.on('plan_generated', (event) => {
    console.log(`Plan ${event.data.planId}: ${event.data.stepCount} step(s)`)
  })

  stream.on('plan_step_started', (event) => {
    console.log(`Step ${event.data.stepNumber}: ${event.data.description}`)
  })

  stream.on('plan_step_completed', (event) => {
    console.log(`Step ${event.data.stepNumber} → ${event.data.status}`)

    // 3. If a step fails, decide how to proceed.
    if (event.data.status === 'failed') {
      void sdk.sendStepDecision({
        planId: event.data.planId,
        planVersion: plan.version,
        stepNumber: event.data.stepNumber,
        action: 'retry',
      })
    }
  })

  stream.on('plan_execution_complete', (event) => {
    console.log(
      `Execution ${event.data.status}: ${event.data.completedSteps}/${event.data.totalSteps}`,
    )
    stream.close()
  })

  stream.on('error', (event) => {
    console.error('Plan error:', event.data.message)
    stream.close()
  })
}