TypeScript types

@poolot/lily-web is written in TypeScript and ships .d.ts definitions, so every export is typed. This page lists the types you'll use most; import them directly from the package.

import {
  createLilyAgent,
  setInputHandler,
  loadLily,
  type CreateAgentOptions,
  type LilyAgentHandle,
  type LilyMessage,
  type LilyContentPart,
  type LilyEvent,
  type LilyRunOptions,
  type LilyRunResult,
  type LilyUsage,
} from '@poolot/lily-web'

Core types

  • CreateAgentOptions — the options bag for createLilyAgent. Extends the engine LoadOptions.
  • LilyAgentHandle — the object createLilyAgent resolves to; see the method list.
  • LilyMessage / LilyContentPart — the conversation types; see Events and messages.
  • LilyEvent — the streaming event union; see the event table.
  • LilyRunOptions — per-run limits and callbacks.
  • LilyRunResult — what runDetailed and continue return.
  • LilyUsage — { inputTokens; outputTokens; cachedInputTokens; calls }.

Typed events

Because LilyEvent is a discriminated union, a switch on event.type narrows the payload:

function handle(event: LilyEvent) {
  if (event.type === 'tool_call') {
    // event.name and event.arguments are available here
  } else if (event.type === 'usage') {
    // event.usage and event.cumulative are LilyUsage
  }
}

Top-level functions

function createLilyAgent(opts?: CreateAgentOptions): Promise<LilyAgentHandle>
function loadLily(opts?: LoadOptions): Promise<unknown>       // preload the engine (optional)
function setInputHandler(
  fn: ((question: string, placeholder: string, id: string) => string | null | Promise<string | null>) | null,
): unknown                                                    // returns the previous handler
  • loadLily warms the engine ahead of time; createLilyAgent calls it internally, so you only need it to preload.
  • setInputHandler registers how the agent's ask_user questions are answered — see Answering the agent's questions.

Beyond the basics

The package also exports helpers for structured output (@poolot/lily-web/structured), custom tools, approval rules, hooks, sessions, and environment detection (detectEnvironment, listModels, and more). Reach for these once the basics are in place; the shipped .d.ts files are the source of truth for their exact signatures.

See also