TypeScript Types

Overview

The OpenCode SDK includes comprehensive TypeScript definitions generated from the OpenAPI specification. All types are exported from the main package.

import type {
  Session,
  Message,
  Part,
  Config,
  Agent,
  Model,
  Provider,
  // ... and many more
} from '@opencode-ai/sdk'

View the complete types file in the OpenCode repository.

Core Types

Session

Represents an AI coding session.

type Session = {
  id: string
  projectID: string
  directory: string
  parentID?: string
  title: string
  version: string
  time: {
    created: number
    updated: number
    compacting?: number
  }
  summary?: {
    additions: number
    deletions: number
    files: number
    diffs?: FileDiff[]
  }
  share?: {
    url: string
  }
  revert?: {
    messageID: string
    partID?: string
    snapshot?: string
    diff?: string
  }
}

Message

Union type for user and assistant messages.

type Message = UserMessage | AssistantMessage

type UserMessage = {
  id: string
  sessionID: string
  role: 'user'
  time: { created: number }
  agent: string
  model: {
    providerID: string
    modelID: string
  }
  system?: string
  tools?: Record<string, boolean>
  summary?: {
    title?: string
    body?: string
    diffs: FileDiff[]
  }
}

type AssistantMessage = {
  id: string
  sessionID: string
  role: 'assistant'
  time: {
    created: number
    completed?: number
  }
  parentID: string
  modelID: string
  providerID: string
  mode: string
  path: {
    cwd: string
    root: string
  }
  cost: number
  tokens: {
    input: number
    output: number
    reasoning: number
    cache: { read: number; write: number }
  }
  finish?: string
  error?: MessageError
  summary?: boolean
}

Part

Message parts (text, file, tool use, etc.).

type Part =
  | TextPart
  | ReasoningPart
  | FilePart
  | ToolPart
  | SubtaskPart
  | StepStartPart
  | StepFinishPart
  | SnapshotPart
  | PatchPart
  | AgentPart
  | RetryPart
  | CompactionPart

type TextPart = {
  id: string
  sessionID: string
  messageID: string
  type: 'text'
  text: string
  synthetic?: boolean
  ignored?: boolean
  time?: { start: number; end?: number }
  metadata?: Record<string, unknown>
}

type ToolPart = {
  id: string
  sessionID: string
  messageID: string
  type: 'tool'
  callID: string
  tool: string
  state: ToolState
  metadata?: Record<string, unknown>
}

type FilePart = {
  id: string
  sessionID: string
  messageID: string
  type: 'file'
  mime: string
  filename?: string
  url: string
  source?: FilePartSource
}

ToolState

Tool execution state.

type ToolState =
  | ToolStatePending
  | ToolStateRunning
  | ToolStateCompleted
  | ToolStateError

type ToolStatePending = {
  status: 'pending'
  input: Record<string, unknown>
  raw: string
}

type ToolStateRunning = {
  status: 'running'
  input: Record<string, unknown>
  title?: string
  metadata?: Record<string, unknown>
  time: { start: number }
}

type ToolStateCompleted = {
  status: 'completed'
  input: Record<string, unknown>
  output: string
  title: string
  metadata: Record<string, unknown>
  time: { start: number; end: number; compacted?: number }
  attachments?: FilePart[]
}

type ToolStateError = {
  status: 'error'
  input: Record<string, unknown>
  error: string
  metadata?: Record<string, unknown>
  time: { start: number; end: number }
}

Configuration Types

Config

Main configuration object.

type Config = {
  $schema?: string
  theme?: string
  logLevel?: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR'
  model?: string
  small_model?: string
  username?: string
  agent?: Record<string, AgentConfig>
  provider?: Record<string, ProviderConfig>
  mcp?: Record<string, McpLocalConfig | McpRemoteConfig>
  command?: Record<string, CommandConfig>
  plugin?: string[]
  snapshot?: boolean
  share?: 'manual' | 'auto' | 'disabled'
  autoupdate?: boolean | 'notify'
  instructions?: string[]
  tools?: Record<string, boolean>
  permission?: PermissionConfig
  keybinds?: KeybindsConfig
  tui?: TuiConfig
  // ... more options
}

AgentConfig

Configuration for individual agents.

type AgentConfig = {
  model?: string
  temperature?: number
  top_p?: number
  prompt?: string
  tools?: Record<string, boolean>
  disable?: boolean
  description?: string
  mode?: 'subagent' | 'primary' | 'all'
  color?: string
  maxSteps?: number
  permission?: PermissionConfig
}

type PermissionConfig = {
  edit?: 'ask' | 'allow' | 'deny'
  bash?: 'ask' | 'allow' | 'deny' | Record<string, 'ask' | 'allow' | 'deny'>
  webfetch?: 'ask' | 'allow' | 'deny'
  doom_loop?: 'ask' | 'allow' | 'deny'
  external_directory?: 'ask' | 'allow' | 'deny'
}

ProviderConfig

Provider configuration.

type ProviderConfig = {
  api?: string
  name?: string
  env?: string[]
  id?: string
  npm?: string
  models?: Record<string, ModelConfig>
  whitelist?: string[]
  blacklist?: string[]
  options?: {
    apiKey?: string
    baseURL?: string
    enterpriseUrl?: string
    setCacheKey?: boolean
    timeout?: number | false
  }
}

type ModelConfig = {
  id?: string
  name?: string
  release_date?: string
  attachment?: boolean
  reasoning?: boolean
  temperature?: boolean
  tool_call?: boolean
  cost?: {
    input: number
    output: number
    cache_read?: number
    cache_write?: number
  }
  limit?: {
    context: number
    output: number
  }
  modalities?: {
    input: ('text' | 'audio' | 'image' | 'video' | 'pdf')[]
    output: ('text' | 'audio' | 'image' | 'video' | 'pdf')[]
  }
  experimental?: boolean
  status?: 'alpha' | 'beta' | 'deprecated'
}

Provider and Model Types

Provider

Provider information.

type Provider = {
  id: string
  name: string
  source: 'env' | 'config' | 'custom' | 'api'
  env: string[]
  key?: string
  options: Record<string, unknown>
  models: Record<string, Model>
}

Model

Model information.

type Model = {
  id: string
  providerID: string
  api: {
    id: string
    url: string
    npm: string
  }
  name: string
  capabilities: {
    temperature: boolean
    reasoning: boolean
    attachment: boolean
    toolcall: boolean
    input: {
      text: boolean
      audio: boolean
      image: boolean
      video: boolean
      pdf: boolean
    }
    output: {
      text: boolean
      audio: boolean
      image: boolean
      video: boolean
      pdf: boolean
    }
  }
  cost: {
    input: number
    output: number
    cache: { read: number; write: number }
    experimentalOver200K?: {
      input: number
      output: number
      cache: { read: number; write: number }
    }
  }
  limit: {
    context: number
    output: number
  }
  status: 'alpha' | 'beta' | 'deprecated' | 'active'
  options: Record<string, unknown>
  headers: Record<string, string>
}

Agent

Agent information.

type Agent = {
  name: string
  description?: string
  mode: 'subagent' | 'primary' | 'all'
  builtIn: boolean
  topP?: number
  temperature?: number
  color?: string
  permission: {
    edit: 'ask' | 'allow' | 'deny'
    bash: Record<string, 'ask' | 'allow' | 'deny'>
    webfetch?: 'ask' | 'allow' | 'deny'
    doom_loop?: 'ask' | 'allow' | 'deny'
    external_directory?: 'ask' | 'allow' | 'deny'
  }
  model?: { modelID: string; providerID: string }
  prompt?: string
  tools: Record<string, boolean>
  options: Record<string, unknown>
  maxSteps?: number
}

Event Types

Event

Union type for all server events.

type Event =
  | EventSessionCreated
  | EventSessionUpdated
  | EventSessionDeleted
  | EventSessionStatus
  | EventSessionIdle
  | EventMessageUpdated
  | EventMessagePartUpdated
  | EventMessageRemoved
  | EventPermissionUpdated
  | EventTodoUpdated
  | EventFileEdited
  // ... and many more

type EventSessionCreated = {
  type: 'session.created'
  properties: { info: Session }
}

type EventMessageUpdated = {
  type: 'message.updated'
  properties: { info: Message }
}

type EventMessagePartUpdated = {
  type: 'message.part.updated'
  properties: { part: Part; delta?: string }
}

GlobalEvent

Event with directory context.

type GlobalEvent = {
  directory: string
  payload: Event
}

File Types

File

File status information.

type File = {
  path: string
  added: number
  removed: number
  status: 'added' | 'deleted' | 'modified'
}

FileDiff

File diff information.

type FileDiff = {
  file: string
  before: string
  after: string
  additions: number
  deletions: number
}

FileContent

File content response.

type FileContent = {
  type: 'text' | 'binary'
  content: string
  diff?: string
  patch?: PatchInfo
  encoding?: 'base64'
  mimeType?: string
}

Symbol

Workspace symbol.

type Symbol = {
  name: string
  kind: number
  location: {
    uri: string
    range: Range
  }
}

type Range = {
  start: { line: number; character: number }
  end: { line: number; character: number }
}

Project Types

Project

Project information.

type Project = {
  id: string
  worktree: string
  vcsDir?: string
  vcs?: 'git'
  time: {
    created: number
    initialized?: number
  }
}

Path

Path information.

type Path = {
  state: string
  config: string
  worktree: string
  directory: string
}

Error Types

Message Errors

type MessageError =
  | ProviderAuthError
  | UnknownError
  | MessageOutputLengthError
  | MessageAbortedError
  | ApiError

type ProviderAuthError = {
  name: 'ProviderAuthError'
  data: { providerID: string; message: string }
}

type ApiError = {
  name: 'APIError'
  data: {
    message: string
    statusCode?: number
    isRetryable: boolean
    responseHeaders?: Record<string, string>
    responseBody?: string
  }
}

API Errors

type BadRequestError = {
  data: unknown
  errors: Array<Record<string, unknown>>
  success: false
}

type NotFoundError = {
  name: 'NotFoundError'
  data: { message: string }
}

Permission Types

Permission

Permission request.

type Permission = {
  id: string
  type: string
  pattern?: string | string[]
  sessionID: string
  messageID: string
  callID?: string
  title: string
  metadata: Record<string, unknown>
  time: { created: number }
}

Todo Types

Todo

Todo item.

type Todo = {
  id: string
  content: string
  status: string
  priority: string
}

Command Types

Command

Command definition.

type Command = {
  name: string
  description?: string
  agent?: string
  model?: string
  template: string
  subtask?: boolean
}

Input Types

These types are used for creating messages:

type TextPartInput = {
  id?: string
  type: 'text'
  text: string
  synthetic?: boolean
  ignored?: boolean
  time?: { start: number; end?: number }
  metadata?: Record<string, unknown>
}

type FilePartInput = {
  id?: string
  type: 'file'
  mime: string
  filename?: string
  url: string
  source?: FilePartSource
}

type SubtaskPartInput = {
  id?: string
  type: 'subtask'
  prompt: string
  description: string
  agent: string
}

Usage Example

import type {
  Session,
  Message,
  Part,
  Config,
  AgentConfig,
  Event,
} from '@opencode-ai/sdk'
import { createOpencodeClient } from '@opencode-ai/sdk'

const client = createOpencodeClient()

// Types are inferred automatically
const sessions = await client.session.list()
const session: Session = sessions.data[0]

const messages = await client.session.messages({
  path: { id: session.id },
})

for (const msg of messages.data) {
  const info: Message = msg.info
  const parts: Part[] = msg.parts
  
  console.log(`${info.role}: ${parts.length} parts`)
}

// Subscribe to events
const events = await client.event.subscribe()
for await (const event of events.stream) {
  const evt: Event = event.payload
  
  if (evt.type === 'message.updated') {
    console.log('Message updated:', evt.properties.info.id)
  }
}

JavaScript SDK

Plugin API

Overview

Core Types

Session

Message

Part

ToolState

Configuration Types

Config

AgentConfig

ProviderConfig

Provider and Model Types

Provider

Model

Agent

Event Types

Event

GlobalEvent

File Types

File

FileDiff

FileContent

Symbol

Project Types

Project

Path

Error Types

Message Errors

API Errors

Permission Types

Permission

Todo Types

Todo

Command Types

Command

Input Types

Usage Example

JavaScript SDK

Plugin API

​Overview

​Core Types

​Session

​Message

​Part

​ToolState

​Configuration Types

​Config

​AgentConfig

​ProviderConfig

​Provider and Model Types

​Provider

​Model

​Agent

​Event Types

​Event

​GlobalEvent

​File Types

​File

​FileDiff

​FileContent

​Symbol

​Project Types

​Project

​Path

​Error Types

​Message Errors

​API Errors

​Permission Types

​Permission

​Todo Types

​Todo

​Command Types

​Command

​Input Types

​Usage Example

Overview

Core Types

Session

Message

Part

ToolState

Configuration Types

Config

AgentConfig

ProviderConfig

Provider and Model Types

Provider

Model

Agent

Event Types

Event

GlobalEvent

File Types

File

FileDiff

FileContent

Symbol

Project Types

Project

Path

Error Types

Message Errors

API Errors

Permission Types

Permission

Todo Types

Todo

Command Types

Command

Input Types

Usage Example