TypeScript SDK Reference

Version Requirements: This documentation is for CodeBuddy Agent SDK v0.1.0 and above.

This document provides a complete API reference for the TypeScript SDK. For quick start and usage examples, please refer to SDK Overview.

Requirements

Dependency	Version Requirement
Node.js	>= 18.0.0
TypeScript	>= 5.0.0 (Recommended)

Runtime Support:

Node.js (Recommended)
Bun
Deno

Installation

bash

npm install @tencent-ai/agent-sdk

Or use other package managers:

bash

yarn add @tencent-ai/agent-sdk
pnpm add @tencent-ai/agent-sdk

Environment Variables

Variable Name	Description	Required
`CODEBUDDY_CODE_PATH`	CodeBuddy CLI executable path	Optional

Authentication Configuration

The SDK supports authentication using existing login credentials, API Key, or OAuth Client Credentials. See SDK Overview - Authentication Configuration for details.

Functions

query()

Main API entry point that creates a query and returns a message stream.

typescript

function query(params: {
  prompt: string | AsyncIterable<UserMessage>;
  options?: Options;
}): Query;

Parameters:

Parameter	Type	Description
`prompt`	`string \| AsyncIterable<UserMessage>`	Query prompt or user message stream
`options`	`Options`	Configuration options (optional)

Return Value: Query - Interface that extends AsyncGenerator<Message, void>

Query Interface

typescript

interface Query extends AsyncGenerator<Message, void> {
  // Interrupt current execution
  interrupt(): Promise<void>;

  // Dynamically modify permission mode
  setPermissionMode(mode: PermissionMode): Promise<void>;

  // Dynamically modify model
  setModel(model?: string): Promise<void>;

  // Set maximum thinking tokens
  setMaxThinkingTokens(tokens: number | null): Promise<void>;

  // Get available permission modes list
  getAvailableModes(): Promise<ModeInfo[]>;

  // Get available models list
  getAvailableModels(): Promise<ModelInfo[]>;

  // Get supported slash commands
  supportedCommands(): Promise<SlashCommand[]>;

  // Get supported models list
  supportedModels(): Promise<ModelInfo[]>;

  // Get MCP server status
  mcpServerStatus(): Promise<McpServerStatus[]>;

  // Get account information
  accountInfo(): Promise<AccountInfo>;

  // Stream input user messages
  streamInput(stream: AsyncIterable<UserMessage>): Promise<void>;
}

Constants

typescript

// All supported Hook events
const HOOK_EVENTS: readonly [
  'PreToolUse',
  'PostToolUse',
  'PostToolUseFailure',
  'Notification',
  'UserPromptSubmit',
  'SessionStart',
  'SessionEnd',
  'Stop',
  'SubagentStart',
  'SubagentStop',
  'PreCompact',
  'PermissionRequest',
  'WorktreeCreate',
  'WorktreeRemove'
];

// All exit reasons
const EXIT_REASONS: readonly [
  'user_cancelled',
  'tool_error',
  'max_turns',
  'max_budget_usd',
  'completed',
  'interrupted',
  'hook_blocked'
];

Errors

typescript

class AbortError extends Error {
  // Thrown when operation is aborted
}

Unstable V2 API

Warning: The following APIs are experimental and may change in future versions.

unstable_v2_createSession()

Create a new interactive session.

typescript

function unstable_v2_createSession(options: SessionOptions): Session;

unstable_v2_resumeSession()

Resume an existing session.

typescript

function unstable_v2_resumeSession(
  sessionId: string,
  options: SessionOptions
): Session;

unstable_v2_prompt()

Convenience function for single query.

typescript

function unstable_v2_prompt(
  message: string,
  options: SessionOptions
): Promise<Message[]>;

unstable_v2_authenticate()

Initiate an interactive login flow with support for multi-environment authentication (international, China, etc.).

typescript

function unstable_v2_authenticate(options: AuthenticateOptions): Promise<AuthenticateResponse>;

Parameters:

Field	Type	Description
`onAuthUrl`	`(authState: AuthState) => Promise<void>`	Authentication URL callback, used to open a browser or display the link
`environment`	`'external' \| 'internal' \| 'ioa' \| 'cloudhosted'`	Predefined environment (mutually exclusive with endpoint)
`endpoint`	`string`	Custom endpoint URL (for selfhosted, mutually exclusive with environment)
`methodId`	`string`	Authentication method ID, default `'external'`
`timeout`	`number`	Timeout in milliseconds, default 300000
`pathToCodebuddyCode`	`string`	CLI executable path (optional)
`env`	`Record<string, string>`	Environment variables (optional)

Returns: Promise<AuthenticateResponse>

userinfo - User info object containing userId, userName, userNickname, token, and other fields

Example:

typescript

import { unstable_v2_authenticate } from '@tencent-ai/agent-sdk';
import open from 'open';

// International login
const result = await unstable_v2_authenticate({
  environment: 'external',
  onAuthUrl: async (authState) => {
    console.log('Please login:', authState.authUrl);
    await open(authState.authUrl);
  }
});

console.log('Login successful:', result.userinfo.userName);

// Self-hosted login
const result2 = await unstable_v2_authenticate({
  endpoint: 'https://your-company.com',
  onAuthUrl: async (authState) => {
    console.log('Please login:', authState.authUrl);
    await open(authState.authUrl);
  }
});

Behavior:

If a valid token already exists, returns user info directly without triggering the login flow
Otherwise, notifies the user to open the login link via the onAuthUrl callback
After successful login, the token is cached and automatically reused on the next call

unstable_v2_logout()

Log out and clear the cached authentication token. The next call to authenticate() will trigger a fresh login.

typescript

function unstable_v2_logout(options?: LogoutOptions): Promise<void>;

Parameters:

Field	Type	Description
`environment`	`'external' \| 'internal' \| 'ioa' \| 'cloudhosted'`	Predefined environment (mutually exclusive with endpoint)
`endpoint`	`string`	Custom endpoint URL (mutually exclusive with environment)
`pathToCodebuddyCode`	`string`	CLI executable path (optional)
`env`	`Record<string, string>`	Environment variables (optional)

Example:

typescript

import { unstable_v2_authenticate, unstable_v2_logout } from '@tencent-ai/agent-sdk';

// Login
const result = await unstable_v2_authenticate({
  environment: 'external',
  onAuthUrl: (authState) => console.log('Login:', authState.authUrl),
});

// Logout
await unstable_v2_logout({ environment: 'external' });

// Re-login with a different user
const newUser = await unstable_v2_authenticate({
  environment: 'external',
  onAuthUrl: (authState) => console.log('Login:', authState.authUrl),
});

Session Interface

typescript

interface Session {
  // Session ID (available after initialization)
  readonly sessionId: string;

  // Send message
  send(message: string | UserMessage): Promise<void>;

  // Get response stream
  stream(): AsyncGenerator<Message, void>;

  // Close session
  close(): void;

  // Async disposal
  [Symbol.asyncDispose](): Promise<void>;
}

SessionOptions

typescript

type SessionOptions = {
  model: string;
  pathToCodebuddyCode?: string;
  executable?: 'node' | 'bun';
  executableArgs?: string[];
  env?: Record<string, string | undefined>;
  canUseTool?: CanUseTool;
};

Types

Options

Complete configuration options:

Field	Type	Description
`abortController`	`AbortController`	Used to cancel requests
`executable`	`'bun' \| 'deno' \| 'node'`	Runtime
`executableArgs`	`string[]`	Runtime arguments
`pathToCodebuddyCode`	`string`	CLI path
`cwd`	`string`	Working directory
`additionalDirectories`	`string[]`	Additional directories
`env`	`Record<string, string \| undefined>`	Environment variables
`model`	`string`	Specify model
`fallbackModel`	`string`	Fallback model
`maxThinkingTokens`	`number`	Maximum thinking tokens (deprecated, use `thinking` instead)
`thinking`	`ThinkingConfig`	Thinking mode configuration: `{ type: 'adaptive' }`, `{ type: 'enabled', budgetTokens: N }`, or `{ type: 'disabled' }`
`effort`	`'low' \| 'medium' \| 'high' \| 'xhigh'`	Model reasoning effort level
`allowedTools`	`string[]`	Allowed tools whitelist
`disallowedTools`	`string[]`	Disallowed tools blacklist
`canUseTool`	`CanUseTool`	Permission callback function
`permissionMode`	`PermissionMode`	Permission mode
`allowDangerouslySkipPermissions`	`boolean`	Allow skipping permissions
`permissionPromptToolName`	`string`	Permission prompt tool name
`continue`	`boolean`	Continue recent session
`resume`	`string`	Session ID to resume
`resumeSessionAt`	`string`	Resume at specific message position
`persistSession`	`boolean`	Persist session
`forkSession`	`boolean`	Fork session
`agents`	`Record<string, AgentDefinition>`	Custom agents
`hooks`	`Partial<Record<HookEvent, HookCallbackMatcher[]>>`	Hook configuration
`outputFormat`	`OutputFormat`	Output format
`systemPrompt`	`string \| { append: string }`	System prompt
`includePartialMessages`	`boolean`	Include partial messages
`maxTurns`	`number`	Maximum conversation turns
`mcpServers`	`Record<string, McpServerConfig>`	MCP server configuration
`strictMcpConfig`	`boolean`	Strict MCP configuration
`sandbox`	`SandboxSettings`	Sandbox settings
`settingSources`	`SettingSource[]`	Setting sources, controls which filesystem configurations are loaded. Default: no configurations are loaded

SettingSource

Controls which filesystem locations the SDK loads configurations from.

typescript

type SettingSource = 'user' | 'project' | 'local';

Value	Description	Location
`'user'`	Global user settings	`~/.codebuddy/settings.json`
`'project'`	Project shared settings	`.codebuddy/settings.json`
`'local'`	Project local settings	`.codebuddy/settings.local.json`

Default Behavior: When settingSources is not specified, the SDK does not load any filesystem configurations. This provides a completely clean runtime environment.

typescript

// Default: no configurations loaded (clean environment)
const q = query({ prompt: '...' });

// Load project configuration
const q = query({
  prompt: '...',
  options: { settingSources: ['project'] }
});

// Load all configurations (similar to CLI behavior)
const q = query({
  prompt: '...',
  options: { settingSources: ['user', 'project', 'local'] }
});

PermissionMode

typescript

type PermissionMode =
  | 'default'           // Default mode, all operations require confirmation
  | 'acceptEdits'       // Automatically approve file edits
  | 'bypassPermissions' // Skip all permission checks
  | 'plan'              // Plan mode, read-only operations allowed

PermissionResult

typescript

type PermissionResult =
  | {
      behavior: 'allow';
      updatedInput: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
      toolUseID?: string;
    }
  | {
      behavior: 'deny';
      message: string;
      interrupt?: boolean;
      toolUseID?: string;
    };

CanUseTool

typescript

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: CanUseToolOptions
) => Promise<PermissionResult>;

type CanUseToolOptions = {
  signal: AbortSignal;
  suggestions?: PermissionUpdate[];
  blockedPath?: string;
  decisionReason?: string;
  toolUseID: string;
  agentID?: string;
};

AgentDefinition

typescript

type AgentDefinition = {
  description: string;          // Agent description
  prompt: string;               // System prompt
  tools?: string[];             // Allowed tools
  disallowedTools?: string[];   // Disallowed tools
  model?: string;               // Model to use
};

ModeInfo

typescript

interface ModeInfo {
  id: string;           // Mode ID
  name: string;         // Display name
  description: string;  // Mode description
}

ModelInfo

typescript

interface ModelInfo {
  modelId: string;       // Model ID
  name: string;          // Display name
  description?: string;  // Model description
}

McpServerConfig

typescript

// Stdio type
type McpStdioServerConfig = {
  type?: 'stdio';
  command: string;
  args?: string[];
  env?: Record<string, string>;
};

// SSE type
type McpSSEServerConfig = {
  type: 'sse';
  url: string;
  headers?: Record<string, string>;
};

// HTTP type
type McpHttpServerConfig = {
  type: 'http';
  url: string;
  headers?: Record<string, string>;
};

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig;

HookEvent

typescript

type HookEvent =
  | 'PreToolUse'
  | 'PostToolUse'
  | 'PostToolUseFailure'
  | 'Notification'
  | 'UserPromptSubmit'
  | 'SessionStart'
  | 'SessionEnd'
  | 'Stop'
  | 'SubagentStart'
  | 'SubagentStop'
  | 'PreCompact'
  | 'PermissionRequest'
  | 'WorktreeCreate'
  | 'WorktreeRemove';

HookCallback

typescript

type HookCallback = (
  input: HookInput,
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

interface HookCallbackMatcher {
  matcher?: string;        // Match pattern (supports regex)
  hooks: HookCallback[];   // Callback function list
  timeout?: number;        // Timeout (milliseconds)
}

HookJSONOutput

typescript

// Sync output
type SyncHookJSONOutput = {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: 'approve' | 'block';
  systemMessage?: string;
  reason?: string;
  hookSpecificOutput?: Record<string, unknown>;
};

// Async output
type AsyncHookJSONOutput = {
  async: true;
  asyncTimeout?: number;
};

type HookJSONOutput = SyncHookJSONOutput | AsyncHookJSONOutput;

Message Types

Message

Union of all message types:

typescript

type Message =
  | SystemMessage
  | UserMessage
  | AssistantMessage
  | PartialAssistantMessage
  | ResultMessage
  | CompactBoundaryMessage
  | StatusMessage
  | ToolProgressMessage;

SystemMessage

typescript

type SystemMessage = {
  type: 'system';
  subtype: 'init';
  uuid: string;
  session_id: string;
  apiKeySource?: string;
  cwd?: string;
  tools: string[];
  mcp_servers?: Array<{ name: string; status: string }>;
  model: string;
  permissionMode: PermissionMode;
  slash_commands?: string[];
  codebuddy_code_version?: string;
  skills?: string[];
  plugins?: Array<{ name: string; path: string }>;
};

UserMessage

typescript

type UserMessage = {
  type: 'user';
  uuid?: string;
  session_id: string;
  message: {
    role: 'user';
    content: string | ContentBlock[];
  };
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  tool_use_result?: unknown;
};

AssistantMessage

typescript

type AssistantMessage = {
  type: 'assistant';
  uuid: string;
  session_id: string;
  message: {
    id: string;
    type: 'message';
    role: 'assistant';
    model: string;
    content: ContentBlock[];
    stop_reason: StopReason | null;
    stop_sequence: string | null;
    usage: Usage;
  };
  parent_tool_use_id: string | null;
  error?: string;
};

ResultMessage

typescript

type ResultMessage =
  | {
      type: 'result';
      subtype: 'success';
      uuid: string;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      result: string;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: PermissionDenial[];
      structured_output?: unknown;
    }
  | {
      type: 'result';
      subtype: 'error_during_execution' | 'error_max_turns' | 'error_max_budget_usd';
      uuid: string;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: PermissionDenial[];
      errors?: string[];
    };

ContentBlock

typescript

// Text content block
interface TextContentBlock {
  type: 'text';
  text: string;
}

// Tool use block
interface ToolUseContentBlock {
  type: 'tool_use';
  id: string;
  name: string;
  input: Record<string, unknown>;
}

// Tool result block
interface ToolResultContentBlock {
  type: 'tool_result';
  tool_use_id: string;
  content?: string | ContentBlock[];
  is_error?: boolean;
}

type ContentBlock =
  | TextContentBlock
  | ToolUseContentBlock
  | ToolResultContentBlock;

Usage

typescript

interface Usage {
  input_tokens: number;
  output_tokens: number;
  cache_read_input_tokens?: number | null;
  cache_creation_input_tokens?: number | null;
}

Input Types

AskUserQuestionInput

typescript

interface AskUserQuestionInput {
  // List of questions to ask (1-4 questions)
  questions: AskUserQuestionQuestion[];
  // User answers (collected by permission component)
  answers?: Record<string, string>;
}

AskUserQuestionQuestion

typescript

interface AskUserQuestionQuestion {
  // Complete question text (should end with ?)
  question: string;
  // Short label (max 12 characters)
  header: string;
  // Available options (2-4 options)
  options: AskUserQuestionOption[];
  // Allow multiple selections
  multiSelect: boolean;
}

AskUserQuestionOption

typescript

interface AskUserQuestionOption {
  // Display text (1-5 words)
  label: string;
  // Option description
  description: string;
}

ToolInputMap

typescript

interface ToolInputMap {
  AskUserQuestion: AskUserQuestionInput;
}

type KnownToolName = keyof ToolInputMap;

SDK Overview - Quick start and usage examples
Hook Reference Guide - Detailed Hook configuration instructions
MCP Integration - MCP server configuration guide

TypeScript SDK Reference ​

Requirements ​

Installation ​

Environment Variables ​

Authentication Configuration ​

Functions ​

query() ​

Query Interface ​

Constants ​

Errors ​

Unstable V2 API ​

unstable_v2_createSession() ​

unstable_v2_resumeSession() ​

unstable_v2_prompt() ​

unstable_v2_authenticate() ​

unstable_v2_logout() ​

Session Interface ​

SessionOptions ​

Types ​

Options ​

SettingSource ​

PermissionMode ​

PermissionResult ​

CanUseTool ​

AgentDefinition ​

ModeInfo ​

ModelInfo ​

McpServerConfig ​

HookEvent ​

HookCallback ​

HookJSONOutput ​

Message Types ​

Message ​

SystemMessage ​

UserMessage ​

AssistantMessage ​

ResultMessage ​

ContentBlock ​

Usage ​

Input Types ​

AskUserQuestionInput ​

AskUserQuestionQuestion ​

AskUserQuestionOption ​

ToolInputMap ​

Related Documentation ​

TypeScript SDK Reference

Requirements

Installation

Environment Variables

Authentication Configuration

Functions

query()

Query Interface

Constants

Errors

Unstable V2 API

unstable_v2_createSession()

unstable_v2_resumeSession()

unstable_v2_prompt()

unstable_v2_authenticate()

unstable_v2_logout()

Session Interface

SessionOptions

Types

Options

SettingSource

PermissionMode

PermissionResult

CanUseTool

AgentDefinition

ModeInfo

ModelInfo

McpServerConfig

HookEvent

HookCallback

HookJSONOutput

Message Types

Message

SystemMessage

UserMessage

AssistantMessage

ResultMessage

ContentBlock

Usage

Input Types

AskUserQuestionInput

AskUserQuestionQuestion

AskUserQuestionOption

ToolInputMap

Related Documentation