SDK References - TypeScript

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

function startup(params?: StartupParams): Promise<WarmQuery>;

import { qodercliAuth, startup } from '@qodercn-ai/qodercn-agent-sdk';

const warm = await startup({
  options: {
    auth: qodercliAuth(),
    cwd: process.cwd(),
  },
  initializeTimeoutMs: 30_000,
});

try {
  const q = warm.query('Summarize this repository.');
  for await (const message of q) {
    console.log(message);
  }
} finally {
  warm.close();
}

function resolveSettings(
  options?: ResolveSettingsOptions,
): Promise<ResolvedSettings>;

import { resolveSettings } from '@qodercn-ai/qodercn-agent-sdk';

const resolved = await resolveSettings({
  cwd: process.cwd(),
  settingSources: ['user', 'project'],
});

console.log(resolved.effective);
console.table(resolved.sources.map(({ source, path }) => ({ source, path })));

interrupt(): Promise<SDKControlInterruptResponse | undefined>;

type SDKControlInterruptResponse = {
  still_queued: string[];
  cancelled?: string[];
};

askSideQuestion(
  question: string,
  options?: AskSideQuestionOptions,
): Promise<SideQuestionResult | null>;

type SideQuestionHistoryEntry = {
  question: string;
  response: string;
  fallback_notice?: string;
};

type AskSideQuestionOptions = {
  signal?: AbortSignal;
  history?: readonly SideQuestionHistoryEntry[];
};

type SideQuestionResult = {
  response: string;
  synthetic: boolean;
  refusalFallback?: {
    originalModel: string;
    fallbackModel: string;
    content: string;
  };
};

const answer = await q.askSideQuestion(
  'Which configuration file is the current task using?',
  {
    history: [
      {
        question: 'What are we investigating?',
        response: 'A production login failure.',
      },
    ],
  },
);

console.log(answer?.response);

cancelAsyncMessage(messageUuid: string): Promise<boolean>;

backgroundTasks(toolUseId?: string): Promise<boolean>;

stopTask(taskId: string): Promise<void>;

initializationResult(): Promise<SDKControlInitializeResponse>;

accountInfo(): Promise<AccountInfo>;

function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;
function getSessionInfo(sessionId: string, options?: GetSessionInfoOptions): Promise<SDKSessionInfo | undefined>;
function getSessionMessages(sessionId: string, options?: GetSessionMessagesOptions): Promise<SessionMessage[]>;
function renameSession(sessionId: string, title: string, options?: SessionMutationOptions): Promise<void>;
function tagSession(sessionId: string, tag: string | null, options?: SessionMutationOptions): Promise<void>;
function forkSession(sessionId: string, options?: ForkSessionOptions): Promise<{ sessionId: string }>;
function listSubagents(sessionId: string, options?: ListSubagentsOptions): Promise<string[]>;
function getSubagentMessages(sessionId: string, agentId: string, options?: GetSubagentMessagesOptions): Promise<SessionMessage[]>;
function deleteSession(sessionId: string, options?: SessionMutationOptions): Promise<void>;

function importSessionToStore(
  sessionId: string,
  store: SessionStore,
  options?: {
    dir?: string;
    includeSubagents?: boolean;
    batchSize?: number;
  },
): Promise<void>;

import { qodercliAuth, query } from '@qodercn-ai/qodercn-agent-sdk';

const response = query({
  prompt: 'Analyze the current project',
  options: {
    auth: qodercliAuth(),
    vpcEndpoint: 'acme',
  },
});

for await (const message of response) {
  console.log(message);
}

type SessionKey = {
  projectKey: string;
  sessionId: string;
  subpath?: string;
};

type SessionStoreEntry = {
  type: string;
  uuid?: string;
  timestamp?: string;
  [key: string]: unknown;
};

interface SessionStore {
  append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
  load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
  listSessions?(projectKey: string): Promise<Array<{ sessionId: string; mtime: number }>>;
  delete?(key: SessionKey): Promise<void>;
  listSubkeys?(key: Omit<SessionKey, 'subpath'>): Promise<string[]>;
}

type SessionStoreFlush = 'batched' | 'eager';

type SDKSessionInfo = {
  sessionId: string;
  summary: string;
  lastModified: number;
  fileSize?: number;
  customTitle?: string;
  firstPrompt?: string;
  gitBranch?: string;
  cwd?: string;
  tag?: string;
  createdAt?: number;
};

type SessionMessage = {
  type: 'user' | 'assistant' | 'system';
  uuid: string;
  session_id: string;
  message: unknown;
  parent_tool_use_id: string | null;
  parent_agent_id: string | null;
  timestamp?: string;
  subtype?: string;
  compact_metadata?: object;
};

interface Settings {
  skillOverrides?: Record<
    string,
    'on' | 'name-only' | 'user-invocable-only' | 'off'
  >;
  skillListingMaxDescChars?: number;
  skillListingBudgetFraction?: number;
  // Other settings fields
}

interface StartupParams {
  options?: Options;
  initializeTimeoutMs?: number;
}

interface WarmQuery extends AsyncDisposable {
  query(prompt: string | AsyncIterable<SDKUserMessage>): Query;
  close(): void;
}

type ResolveSettingsOptions = {
  cwd?: string;
  settingSources?: Array<'user' | 'project' | 'local'>;
};

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

type ResolvedSettingsSource = {
  source: ResolvedSettingSource;
  settings: Settings;
  path?: string;
};

type ResolvedSettings = {
  effective: Settings;
  provenance: Record<
    string,
    { source: ResolvedSettingSource; path?: string }
  >;
  sources: ResolvedSettingsSource[];
};

type AccountInfo = {
  userId?: string;
  name?: string;
  email?: string;
  organization?: string;
  organizationName?: string;
  subscriptionType?: string;
  tokenSource?: string;
  apiKeySource?: string;
  apiProvider?: 'firstParty' | 'bedrock' | 'vertex' | 'foundry';
};

type SDKControlInitializeResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  skills?: Array<{
    name: string;
    description?: string;
    source?: string;
  }>;
  output_style: string;
  available_output_styles: string[];
  models: ModelInfo[];
  account: AccountInfo;
  fast_mode_state?: FastModeState;
};

type AuthOptions =
  | { type: 'accessToken'; accessToken: string | { envVar: string } }
  | { type: 'qodercli' }
  | {
      type: 'serviceAccount';
      serviceAccountKey: string;
    }
  | {
      type: 'serviceAccount';
      fetchServiceAccountToken: FetchServiceAccountToken;
    };

type ServiceAccountTokenResult = {
  token: string;
  expiresAt?: number;
};

type FetchServiceAccountToken = () => Promise<ServiceAccountTokenResult | null>;

const q = query({
  prompt: 'Use the reviewer agent to inspect recent changes.',
  options: {
    allowedTools: ['Agent'],
    agents: {
      reviewer: {
        description: 'Reviews code quality and reports actionable findings.',
        prompt: 'Review the requested code and report concrete issues.',
        tools: ['Read', 'Grep', 'Glob'],
      },
    },
  },
});

const q = query({
  prompt: 'Plan the implementation.',
  options: {
    agents: {
      planner: {
        description: 'Plans work before implementation.',
        prompt: 'Break work into steps, risks, and validation checks.',
        tools: ['Read', 'Grep', 'Glob'],
      },
    },
    agent: 'planner',
  },
});

type AgentDefinition = {
  description: string;
  prompt: string;
  tools?: string[];
  disallowedTools?: string[];
  model?: string;
  mcpServers?: AgentMcpServerSpec[];
  skills?: string[];
  initialPrompt?: string;
  maxTurns?: number;
  effort?: EffortLevel;
  permissionMode?: PermissionMode;
};

description: 'Runs project tests, analyzes failing output, and suggests fixes.'

prompt: `You are a security reviewer.
Check for authentication bypass, authorization bugs, injection risks, and secret leaks.
Return findings sorted by severity.`

tools: ['Read', 'Grep', 'Glob']

disallowedTools: ['Bash', 'Write']

type AgentMcpServerSpec =
  | string
  | Record<string, McpServerConfig>;

skills: ['review', 'sdk-test-plugin:sdk-echo']

initialPrompt: 'Start by scanning authentication and session management code.'

maxTurns: 6

type EffortLevel = 'low' | 'medium' | 'high' | 'max';

type PermissionMode =
  | 'default'
  | 'acceptEdits'
  | 'bypassPermissions'
  | 'yolo'
  | 'plan'
  | 'dontAsk'
  | 'auto';

type AgentInfo = {
  name: string;
  description: string;
  model?: string;
};

const q = query({
  prompt: 'List agents.',
  options: {
    agents: {
      reviewer: {
        description: 'Reviews code quality.',
        prompt: 'Review code and report findings.',
      },
    },
  },
});

const agents = await q.supportedAgents();

type ModelPolicyProvider = (
  context: ModelPolicyContext,
) => ModelPolicyResult | Promise<ModelPolicyResult>;

interface ModelPolicyContext {
  purpose: QoderModelPurpose;
  sessionId: string;
  availableModels: ModelInfo[];
}

type QoderModelPurpose =
  | 'main'
  | 'subagent'
  | 'web_fetch'
  | 'image_gen'
  | 'compact';

interface ModelPolicyResult {
  model: string | (CustomModel & { model: string });
  parameters?: Record<string, unknown>;
}

interface CustomModel {
  provider: string;
  model: string;
  api_key: string;
  style?: string;
}

interface SDKControlGetByokConfigResponse {
  providers: BYOKProviderInfo[];
}

interface BYOKProviderInfo {
  key: string;
  display_name: string;
  api_key_url: string;
  types: BYOKModelTypeInfo[];
}

interface BYOKModelTypeInfo {
  key?: string;
  display_name: string;
  models: BYOKModelInfo[];
}

interface BYOKModelInfo {
  key: string;
  display_name: string;
  is_vl: boolean;
  is_reasoning: boolean;
  format: string;
  max_input_tokens: number;
}

interface ModelInfo {
  value: string;
  displayName: string;
  description: string;
  isEnabled: boolean;
  isNew?: boolean;
  isFree?: boolean;
  priceFactor?: number;
  serverScene?: string;
  context_config?: ModelContextConfig;
  thinking_config?: ModelThinkingConfig;
  promotion?: ModelPromotion;
  serverModel?: ServerModelJson;
}

type ModelContextConfig = Record<string, ModelContextWindowEntry>;

interface ModelContextWindowEntry {
  token_count: number;
  is_default?: boolean;
}

interface ModelThinkingConfig {
  disabled?: ModelThinkingDisabled;
  enabled?: ModelThinkingEnabled;
}

interface ModelThinkingDisabled {
  description?: string;
}

interface ModelThinkingEnabled {
  description?: string;
  efforts?: Record<string, ModelEffortEntry>;
  is_default?: boolean;
}

interface ModelEffortEntry {
  description?: string;
  is_default?: boolean;
}

type LocalizedModelText = {
  en?: string;
  zh?: string;
} & Record<string, string | undefined>;

interface ModelPromotion {
  active: boolean;
  badge?: LocalizedModelText;
  description?: LocalizedModelText;
  discount_factor?: number;
  before_promotion_price_factor?: number;
  timezone?: string;
  rule_id?: string;
  window_start?: string;
  window_end?: string;
}

type ServerModelJson = Record<string, ServerModelJsonValue>;

type SDKControlGetContextUsageResponse = {
  model: string;
  contextWindow: {
    usedPercentage: number;
  };
  categories: Array<{
    type:
      | 'system_prompt'
      | 'system_tools'
      | 'skills'
      | 'messages'
      | 'other'
      | 'free_space'
      | 'auto_compact';
    percentage: number;
  }>;
  autoCompact: {
    enabled: boolean;
    thresholdPercentage: number;
  };
  skills: {
    count: number;
    percentageOfContext: number;
    items: Array<{
      name: string;
      source: 'project' | 'user' | 'built-in' | 'plugin';
      percentageOfContext: number;
    }>;
  };
  duplicateFileReads: Array<{
    path: string;
    count: number;
  }>;
  session: {
    messageCount: number;
    promptCount: number;
    toolCalls: { total: number; succeeded: number; failed: number };
    linesChanged: { added: number; removed: number };
  };
};

interface UsageInfo {
  userId?: string;
  userType?: string;
  totalUsagePercentage?: number;
  isHighestTier?: boolean;
  expiresAt?: number;
  upgradeUrl?: string;
  userQuota?: UsageQuotaBucket;
  addOnQuota?: UsageAddOnQuotaBucket;
  isQuotaExceeded?: boolean;
  isPlanQuotaProrated?: boolean;
  orgResourcePackage?: UsageOrgResourcePackage;
}

interface UsageQuotaBucket {
  total?: number;
  used?: number;
  remaining?: number;
  percentage?: number;
  unit?: string;
}

interface UsageAddOnQuotaBucket extends UsageQuotaBucket {
  detailUrl?: string;
}

interface UsageOrgResourcePackage {
  used?: number;
  cap?: number;
  remaining?: number;
  percentage?: number;
  available?: boolean;
  unit?: string;
}

class ModelPolicyTimeoutError extends Error {}

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

getAvailableModels(): Promise<ModelInfo[]>;

listByokProviders(): Promise<BYOKProviderInfo[] | null>;

getContextUsage(): Promise<SDKControlGetContextUsageResponse>;

const usage = await q.getContextUsage();

console.log(`Context used: ${usage.contextWindow.usedPercentage}%`);
for (const skill of usage.skills.items) {
  console.log(`${skill.name}: ${skill.percentageOfContext}% of context`);
}

getUsageInfo(): Promise<UsageInfo | null>;

import { query, qodercliAuth } from '@qodercn-ai/qodercn-agent-sdk';

const q = query({
  prompt: userMessages(),
  options: { auth: qodercliAuth() },
});

const usage = await q.getUsageInfo();
if (usage) {
  console.log(`Plan: ${usage.userType}, used ${usage.totalUsagePercentage}%`);
  console.log(`Plan quota: ${usage.userQuota?.remaining}/${usage.userQuota?.total} ${usage.userQuota?.unit} left`);
}

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

type CanUseToolOptions = {
  signal: AbortSignal;
  suggestions?: PermissionUpdate[];
  blockedPath?: string;
  decisionReason?: string;
  decisionReasonType?: PermissionDecisionReasonType;
  classifierApprovable?: boolean;
  title?: string;
  displayName?: string;
  description?: string;
  toolUseID: string;
  agentID?: string;
  exitPlanMode?: ExitPlanModeApprovalDetails;
};

type PermissionMode =
  | 'default'
  | 'acceptEdits'
  | 'bypassPermissions'
  | 'yolo'
  | 'plan'
  | 'dontAsk'
  | 'auto';

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

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;

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

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

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

type McpSdkServerConfigWithInstance = {
  type: 'sdk';
  name: string;
  instance: McpServer;
};

type SdkPluginConfig = {
  type: 'local';
  path: string;
};

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

type ToolConfig = {
  askUserQuestion?: {
    previewFormat?: 'markdown' | 'html';
  };
};

mcp__{serverName}__{toolName}

function tool<Schema extends AnyZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (
    args: InferShape<Schema>,
    extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
  ) => Promise<CallToolResult>,
  extras?: ToolExtras,
): SdkMcpToolDefinition<Schema>;

type AnyZodRawShape = ZodRawShapeCompat;

type InferShape<T extends AnyZodRawShape> = ShapeOutput<T>;

type SdkMcpToolDefinition<
  Schema extends AnyZodRawShape = AnyZodRawShape,
> = {
  name: string;
  description: string;
  inputSchema: Schema;
  annotations?: ToolAnnotations;
  handler: (
    args: InferShape<Schema>,
    extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
  ) => Promise<CallToolResult>;
};

type ToolExtras = {
  annotations?: ToolAnnotations;
};

type ToolAnnotations = {
  title?: string;
  readOnlyHint?: boolean;
  destructiveHint?: boolean;
  openWorldHint?: boolean;
};

function createSdkMcpServer(
  options: CreateSdkMcpServerOptions,
): McpSdkServerConfigWithInstance;

type CreateSdkMcpServerOptions = {
  name: string;
  version?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
};

type McpSdkServerConfigWithInstance = {
  type: 'sdk';
  name: string;
  instance: McpServer;
};

type CallToolResult = {
  content: McpToolResultContent[];
  isError?: boolean;
  _meta?: Record<string, unknown>;
};

type McpToolResultContent =
  | { type: 'text'; text: string }
  | { type: 'image'; data: string; mimeType: string }
  | { type: 'audio'; data: string; mimeType: string }
  | {
      type: 'resource_link';
      uri: string;
      name?: string;
      description?: string;
      mimeType?: string;
    }
  | {
      type: 'resource';
      resource: {
        uri: string;
        mimeType?: string;
        text?: string;
        blob?: string;
      };
    };

type AgentInput = {
  prompt: string;
  agent?: string;
  timeout_ms?: number;
};

type AgentOutput = {
  result: string;
  agent?: string;
  error?: string;
};

type BashInput = {
  command: string;
  timeout?: number;
  description?: string;
  run_in_background?: boolean;
};

type BashOutput = {
  stdout: string;
  stderr: string;
  exitCode: number;
  interrupted?: boolean;
};

type BashToolBackgroundLaunchResult = {
  kind: 'backgrounded';
  pid: number;
  taskId: string;
  outputFile?: string;
  command: string;
  stdout?: string;
  initialOutput: string;
  backgroundReason?: 'user' | 'model' | 'timeout' | 'auto';
  telemetryExecutionId?: string;
  totalLines?: number;
  totalBytes?: number;
};

function isBashToolBackgroundLaunchResult(
  value: unknown,
): value is BashToolBackgroundLaunchResult;