API Reference

interface CallModelParams {
  /** Model slug in provider/model format. Required. */
  model: string;

  /** Initial messages (first turn only). Use inputItems for subsequent turns. */
  messages?: InputMessage[];

  /** Item list from the previous turn's result.items. */
  inputItems?: Item[];

  /** Tools available to the model this turn. */
  tools?: Tool[];

  /** Conditions that end the loop early. */
  stopConditions?: StopCondition[];

  /** Function returning updated params based on the current item list. */
  dynamicParams?: (items: Item[]) => Partial<CallModelParams>;

  /** Context to pass forward to the next turn without adding it to the item list. */
  nextTurnParams?: NextTurnParams;

  /** Stream token deltas. Default false. */
  stream?: boolean;

  /** Fires for each text delta when stream is true. */
  onToken?: (delta: string) => void;

  /** Fires for each stream event (tool calls, errors, turn end) when stream is true. */
  onEvent?: (event: StreamEvent) => void;

  /** Per-turn token limit. */
  maxTokens?: number;

  /** Sampling temperature (0–2). */
  temperature?: number;

  /** Top-p nucleus sampling (0–1). */
  topP?: number;
}

interface TurnResult {
  /** Final text output for this turn. */
  output: string;

  /** Updated item list. Pass as inputItems to the next callModel() call. */
  items: Item[];

  /** Token usage for this turn. */
  usage: TokenUsage;

  /** Remaining balance in micro-DA after this turn. */
  balance: bigint;

  /** Why the turn ended. */
  stopReason: StopReason;

  /** The stop condition that fired, when stopReason is "stop_condition_met". */
  stoppedBy?: StopCondition;
}

type StopReason =
  | "end_turn"           // Model signalled end of turn naturally
  | "stop_condition_met" // A declared stop condition was satisfied
  | "max_tokens"         // Token limit reached
  | "error";             // An error occurred

interface TokenUsage {
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
  costMicroDA: bigint;  // Exact DA cost in micro-DA
}

type Item =
  | MessageItem
  | ToolCallItem
  | ToolResultItem
  | ErrorItem;

interface MessageItem {
  type: "message";
  role: "user" | "assistant" | "system";
  content: string | ContentPart[];
  turnIndex: number;
}

interface ToolCallItem {
  type: "tool_call";
  id: string;
  name: string;
  arguments: Record<string, unknown>;
  turnIndex: number;
}

interface ToolResultItem {
  type: "tool_result";
  toolCallId: string;
  output: string;
  error?: string;
  turnIndex: number;
}

interface ErrorItem {
  type: "error";
  code: string;
  message: string;
  turnIndex: number;
}

interface Tool {
  name: string;
  description: string;
  parameters: JSONSchema;  // JSON Schema object describing the arguments
  execute: (args: Record<string, unknown>) => Promise<string>;
  approval?: "always" | "never" | ((call: ToolCallItem) => Promise<boolean>);
}

type StopCondition =
  | { type: "no_tool_calls" }
  | { type: "max_turns"; maxTurns: number }
  | { type: "balance_below"; threshold: bigint }
  | { type: "output_schema"; schema: JSONSchema }
  | { type: "custom"; check: (result: TurnResult) => boolean };

type StreamEvent =
  | { type: "token"; delta: string }
  | { type: "tool_call_start"; name: string }
  | { type: "tool_call_end"; name: string }
  | { type: "turn_end"; result: TurnResult }
  | { type: "error"; code: string; message: string };