Types

Reference for the TypeScript types Nuabase exports.

Importing types

import type {
  // Options
  OutputDef,
  GetOptions,
  ListOptions,
  ListResultRow,
  ModelInput,

  // Results
  CastResult,
  CastResultSource,
  NormalizedUsage,
  DirectMeta,
  AnswerOrigin,
  SchemaEnforcementKind,

  // Configuration
  DirectConfig,
  ProviderApiKeys,
  LlmProviderId,
  LocalAgentId,
} from 'nuabase';

import type {
  // Local agents
  LocalAgent,
  LocalAgentConfig,
  LocalAgentOptions,
  LocalAgentCallOptions,
  LocalAgentAuthMode,
  LocalAgentStatus,
  AgentEffort,
  Logger,

  // Agent sessions
  AgentSessionConfig,
  AgentSessionStart,
  AgentSessionFiles,
  AgentSessionMode,
  AgentSessionRefusal,
  SessionApproval,
  SessionLauncherTarget,
} from 'nuabase/local-agent';

nuabase also re-exports z from Zod, so import { Nua, z } from 'nuabase' works.

Options

OutputDef

type OutputDef<TSchema extends z.ZodTypeAny, TName extends string = string> = {
  name: TName;     // a name for the generated value
  schema: TSchema; // its Zod schema
};

GetOptions

type GetOptions<TSchema extends z.ZodTypeAny> = {
  input?: unknown;
  output: OutputDef<TSchema>;
  model?: ModelInput;
};

ListOptions

type ListOptions<
  TSchema extends z.ZodTypeAny,
  TData extends Record<string, unknown>,
  PrimaryKey extends keyof TData & string,
  TName extends string = string,
> = {
  input: TData[];
  primaryKey: PrimaryKey;
  output: OutputDef<TSchema, TName>;
  model?: ModelInput;
};

ListResultRow

type ListResultRow<
  TSchema extends z.ZodTypeAny,
  PrimaryKey extends string,
  TName extends string = string,
> = {
  [K in PrimaryKey]: string | number;
} & {
  [K in TName]: z.infer<TSchema>;
};

With output: { name: 'account', schema: z.string() } and primaryKey: 'id', each row is { id: string | number; account: string }.

ModelInput

type LlmProviderId = 'groq' | 'cerebras' | 'gemini' | 'openrouter' | 'deepseek';

type ModelInput =
  | { provider: LlmProviderId; model: string }
  | { alias: 'fast' | 'gemini' | 'qwen' | 'sonnet' | 'opus' | 'haiku' | 'kimi' | 'deepseek' | 'gpt' };

See Models & Providers for what each alias resolves to.

Results

CastResult

type CastResult<T> = CastResultSuccess<T> | CastResultFailure;

type CastResultSuccess<T> = {
  success: true;
  data: T;
  usage: NormalizedUsage;
  model: string;        // "provider:model" or "agent:model"
  latencyMs: number;
  source: 'direct';
  meta: DirectMeta;
};

type CastResultFailure = {
  success: false;
  reason: string;   // why the last attempt failed, in the engine's own words where it gave any
  attempts: number; // attempts made; 0 when the call was refused before any
  error: string;    // a one-line summary for logs
  source: 'direct';
  latencyMs: number;
};

To get the data type of a result:

type Data<R> = R extends CastResult<infer T> ? T : never;

NormalizedUsage

type NormalizedUsage = {
  promptTokens: number;            // includes cached prompt tokens
  completionTokens: number;
  totalTokens: number;
  promptCacheReadTokens?: number;  // read from the provider's prompt cache
  promptCacheWriteTokens?: number; // written to the provider's prompt cache
};

The two cache fields are present only when the provider reports them, and are subsets of promptTokens.

DirectMeta

type DirectMeta = AnswerOrigin & {
  schemaEnforcement: 'native' | 'in-prompt';
};

type AnswerOrigin =
  | { engine: 'http'; provider: LlmProviderId; model: string }
  | {
      engine: 'local-agent';
      agent: 'claude-code' | 'codex' | 'pi';
      model: string | undefined;           // reported by the agent, else the one requested
      costUsdEstimate: number | undefined; // the CLI's own estimate at API prices
    };

schemaEnforcement says whether the engine enforced the schema itself ('native') or Nuabase described it in the prompt ('in-prompt'). The answer is parsed with your schema either way.

Configuration

DirectConfig

type DirectConfig =
  | { providers: ProviderApiKeys; model?: ModelInput; localAgent?: never }
  | { localAgent: LocalAgent; providers?: never; model?: never };

type ProviderApiKeys = {
  groq?: { apiKey: string };
  cerebras?: { apiKey: string };
  gemini?: { apiKey: string };
  openrouter?: { apiKey: string };
  deepseek?: { apiKey: string };
};

Local agent types

type LocalAgentId = 'claude-code' | 'codex' | 'pi';
type LocalAgentAuthMode = 'subscription' | 'inherit';

type AgentEffort = 'low' | 'medium' | 'high';

type LocalAgentOptions = {
  model?: string;
  effort?: AgentEffort;
  timeoutMs?: number;   // default 180000
  concurrency?: number; // default 2
  auth?: LocalAgentAuthMode;
  logger?: Logger;      // default: the console
};

interface Logger {
  debug(message: string, context?: object): void;
  info(message: string, context?: object): void;
  warn(message: string, context?: object): void;
  error(message: string, context?: object): void;
}

type LocalAgentConfig = LocalAgentOptions & {
  agent: LocalAgentId;
  binaryPath?: string;
};

type LocalAgentStatus =
  | { agent: LocalAgentId; installed: false; loggedIn: false; detail?: string }
  | { agent: LocalAgentId; installed: true; loggedIn: boolean; binaryPath: string; version?: string; detail?: string };

LocalAgent

class LocalAgent {
  readonly agent: LocalAgentId;
  readonly logger: Logger;
  with(options: LocalAgentCallOptions): LocalAgent;
}

type LocalAgentCallOptions = {
  model?: string;
  effort?: AgentEffort;
  timeoutMs?: number;
};

with() returns the same agent with other call options, sharing its process limit. See Several models on one agent.

Agent sessions

See Interactive Coding Agent Session.

type SessionApproval = 'ask' | 'auto';

type AgentSessionConfig = {
  agent: LocalAgentId;
  binaryPath?: string;         // default: looked up on PATH
  cwd: string;                 // the project the agent works in
  model?: string;
  approval?: SessionApproval;  // default 'ask'
  prompt: string;              // the session's first message
  dir: string;                 // where the prompt and launcher are written
  name?: string;               // default: <UTC time>-<agent>-<4 hex digits>
  platform?: NodeJS.Platform;  // default: process.platform
};

type AgentSessionStart =
  | { kind: 'opened'; files: AgentSessionFiles }
  | { kind: 'command'; files: AgentSessionFiles }
  | { kind: 'open_failed'; files: AgentSessionFiles; error: string }
  | { kind: 'refused'; reason: AgentSessionRefusal; message: string };

type AgentSessionFiles = {
  promptPath: string;
  launcherPath: string;
  command: string; // runs the launcher from any POSIX terminal
};

type AgentSessionRefusal = 'unsupported_platform' | 'prompt_too_long' | 'agent_not_found';

type AgentSessionMode = 'terminal' | 'command' | 'none';

type SessionLauncherTarget = {
  cwd: string;
  binaryPath: string;
  agentArgs: readonly string[]; // the agent's own options, before the prompt
  promptPath: string;
};