Core Exports
Enumerations
Section titled “Enumerations”ErrorCode
Section titled “ErrorCode”Defined in: types/errors.ts:4
Unified error codes for all SDK errors — single source of truth.
Enumeration Members
Section titled “Enumeration Members”ABORTED
Section titled “ABORTED”ABORTED:
"ABORTED"
Defined in: types/errors.ts:29
AUTH_EXPIRED
Section titled “AUTH_EXPIRED”AUTH_EXPIRED:
"AUTH_EXPIRED"
Defined in: types/errors.ts:6
AUTH_INVALID
Section titled “AUTH_INVALID”AUTH_INVALID:
"AUTH_INVALID"
Defined in: types/errors.ts:7
AUTH_REQUIRED
Section titled “AUTH_REQUIRED”AUTH_REQUIRED:
"AUTH_REQUIRED"
Defined in: types/errors.ts:44
BACKEND_NOT_INSTALLED
Section titled “BACKEND_NOT_INSTALLED”BACKEND_NOT_INSTALLED:
"BACKEND_NOT_INSTALLED"
Defined in: types/errors.ts:32
CONTEXT_OVERFLOW
Section titled “CONTEXT_OVERFLOW”CONTEXT_OVERFLOW:
"CONTEXT_OVERFLOW"
Defined in: types/errors.ts:20
DEPENDENCY_MISSING
Section titled “DEPENDENCY_MISSING”DEPENDENCY_MISSING:
"DEPENDENCY_MISSING"
Defined in: types/errors.ts:31
DISPOSED
Section titled “DISPOSED”DISPOSED:
"DISPOSED"
Defined in: types/errors.ts:28
INVALID_INPUT
Section titled “INVALID_INPUT”INVALID_INPUT:
"INVALID_INPUT"
Defined in: types/errors.ts:23
INVALID_RESPONSE
Section titled “INVALID_RESPONSE”INVALID_RESPONSE:
"INVALID_RESPONSE"
Defined in: types/errors.ts:24
INVALID_TRANSITION
Section titled “INVALID_TRANSITION”INVALID_TRANSITION:
"INVALID_TRANSITION"
Defined in: types/errors.ts:30
MODEL_NOT_FOUND
Section titled “MODEL_NOT_FOUND”MODEL_NOT_FOUND:
"MODEL_NOT_FOUND"
Defined in: types/errors.ts:18
MODEL_OVERLOADED
Section titled “MODEL_OVERLOADED”MODEL_OVERLOADED:
"MODEL_OVERLOADED"
Defined in: types/errors.ts:19
NETWORK
Section titled “NETWORK”NETWORK:
"NETWORK"
Defined in: types/errors.ts:13
PERMISSION_DENIED
Section titled “PERMISSION_DENIED”PERMISSION_DENIED:
"PERMISSION_DENIED"
Defined in: types/errors.ts:36
PROVIDER_ERROR
Section titled “PROVIDER_ERROR”PROVIDER_ERROR:
"PROVIDER_ERROR"
Defined in: types/errors.ts:17
PROVIDER_NOT_FOUND
Section titled “PROVIDER_NOT_FOUND”PROVIDER_NOT_FOUND:
"PROVIDER_NOT_FOUND"
Defined in: types/errors.ts:43
RATE_LIMIT
Section titled “RATE_LIMIT”RATE_LIMIT:
"RATE_LIMIT"
Defined in: types/errors.ts:10
REENTRANCY
Section titled “REENTRANCY”REENTRANCY:
"REENTRANCY"
Defined in: types/errors.ts:27
SESSION_EXPIRED
Section titled “SESSION_EXPIRED”SESSION_EXPIRED:
"SESSION_EXPIRED"
Defined in: types/errors.ts:40
SESSION_NOT_FOUND
Section titled “SESSION_NOT_FOUND”SESSION_NOT_FOUND:
"SESSION_NOT_FOUND"
Defined in: types/errors.ts:39
STORAGE_DUPLICATE_KEY
Section titled “STORAGE_DUPLICATE_KEY”STORAGE_DUPLICATE_KEY:
"STORAGE_DUPLICATE_KEY"
Defined in: types/errors.ts:50
STORAGE_ERROR
Section titled “STORAGE_ERROR”STORAGE_ERROR:
"STORAGE_ERROR"
Defined in: types/errors.ts:47
STORAGE_IO_ERROR
Section titled “STORAGE_IO_ERROR”STORAGE_IO_ERROR:
"STORAGE_IO_ERROR"
Defined in: types/errors.ts:51
STORAGE_NOT_FOUND
Section titled “STORAGE_NOT_FOUND”STORAGE_NOT_FOUND:
"STORAGE_NOT_FOUND"
Defined in: types/errors.ts:49
STORAGE_SERIALIZATION_ERROR
Section titled “STORAGE_SERIALIZATION_ERROR”STORAGE_SERIALIZATION_ERROR:
"STORAGE_SERIALIZATION_ERROR"
Defined in: types/errors.ts:52
TIMEOUT
Section titled “TIMEOUT”TIMEOUT:
"TIMEOUT"
Defined in: types/errors.ts:14
TOOL_EXECUTION
Section titled “TOOL_EXECUTION”TOOL_EXECUTION:
"TOOL_EXECUTION"
Defined in: types/errors.ts:35
Classes
Section titled “Classes”AbortError
Section titled “AbortError”Defined in: errors.ts:108
Thrown when an agent run is aborted
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new AbortError():
AbortError
Defined in: errors.ts:109
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
Inherited from
Section titled “Inherited from”httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
Inherited from
Section titled “Inherited from”retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
Inherited from
Section titled “Inherited from”ActivityTimeoutError
Section titled “ActivityTimeoutError”Defined in: errors.ts:127
Thrown when a stream has no activity within the configured timeout
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new ActivityTimeoutError(
timeoutMs):ActivityTimeoutError
Defined in: errors.ts:128
Parameters
Section titled “Parameters”timeoutMs
Section titled “timeoutMs”number
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
Inherited from
Section titled “Inherited from”httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
Inherited from
Section titled “Inherited from”retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
Inherited from
Section titled “Inherited from”AgentSDKError
Section titled “AgentSDKError”Defined in: errors.ts:17
Base error class for agent-sdk.
Use AgentSDKError.is(err) for reliable cross-module instanceof checks
(works across separately bundled entry points where instanceof may fail).
Extends
Section titled “Extends”Error
Extended by
Section titled “Extended by”StorageErrorChatErrorReentrancyErrorDisposedErrorBackendNotFoundErrorBackendAlreadyRegisteredErrorSubprocessErrorDependencyErrorAbortErrorToolExecutionErrorActivityTimeoutErrorStructuredOutputErrorAuthError
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new AgentSDKError(
message,options?):AgentSDKError
Defined in: errors.ts:27
Parameters
Section titled “Parameters”message
Section titled “message”string
options?
Section titled “options?”Returns
Section titled “Returns”Overrides
Section titled “Overrides”Error.constructor
Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
BackendAlreadyRegisteredError
Section titled “BackendAlreadyRegisteredError”Defined in: errors.ts:79
Thrown when a backend is already registered
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new BackendAlreadyRegisteredError(
backend):BackendAlreadyRegisteredError
Defined in: errors.ts:80
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
Inherited from
Section titled “Inherited from”httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
Inherited from
Section titled “Inherited from”retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
Inherited from
Section titled “Inherited from”BackendNotFoundError
Section titled “BackendNotFoundError”Defined in: errors.ts:66
Thrown when a backend is not found in the registry
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new BackendNotFoundError(
backend):BackendNotFoundError
Defined in: errors.ts:67
Parameters
Section titled “Parameters”backend
Section titled “backend”string
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
Inherited from
Section titled “Inherited from”httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
Inherited from
Section titled “Inherited from”retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
Inherited from
Section titled “Inherited from”abstract BaseAgent
Section titled “abstract BaseAgent”Defined in: base-agent.ts:23
Abstract base agent with shared lifecycle logic. Concrete backends extend this and implement the protected _run/_stream methods.
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new BaseAgent(
config):BaseAgent
Defined in: base-agent.ts:38
Parameters
Section titled “Parameters”config
Section titled “config”Returns
Section titled “Returns”Properties
Section titled “Properties”abortController
Section titled “abortController”
protectedabortController:AbortController|null=null
Defined in: base-agent.ts:25
backendName
Section titled “backendName”
abstractprotectedreadonlybackendName:string
Defined in: base-agent.ts:31
Backend identifier (e.g. “copilot”, “claude”, “vercel-ai”)
config
Section titled “config”
protectedreadonlyconfig:FullAgentConfig
Defined in: base-agent.ts:26
protectedstate:AgentState="idle"
Defined in: base-agent.ts:24
Accessors
Section titled “Accessors”sessionId
Section titled “sessionId”Get Signature
Section titled “Get Signature”get sessionId():
string|undefined
Defined in: base-agent.ts:34
CLI session ID for persistent mode. Override in backends that support it.
Returns
Section titled “Returns”string | undefined
The CLI session ID when using persistent session mode. Undefined in per-call mode or before the first call. Can be stored externally for session resume.
Implementation of
Section titled “Implementation of”Methods
Section titled “Methods”abort()
Section titled “abort()”abort():
void
Defined in: base-agent.ts:184
Abort the current operation. No-op if not running.
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”addStreamMiddleware()
Section titled “addStreamMiddleware()”addStreamMiddleware(
middleware):void
Defined in: base-agent.ts:152
Register a stream middleware. Applied in registration order after built-in transforms.
Parameters
Section titled “Parameters”middleware
Section titled “middleware”Returns
Section titled “Returns”void
checkAbort()
Section titled “checkAbort()”
protectedcheckAbort(signal):void
Defined in: base-agent.ts:500
Throw AbortError if signal is already aborted
Parameters
Section titled “Parameters”signal
Section titled “signal”AbortSignal
Returns
Section titled “Returns”void
dispose()
Section titled “dispose()”dispose():
void
Defined in: base-agent.ts:204
Mark agent as disposed. Override to add cleanup.
Returns
Section titled “Returns”void
Implementation of
Section titled “Implementation of”executeRun()
Section titled “executeRun()”
abstractprotectedexecuteRun(messages,options,signal):Promise<AgentResult<void>>
Defined in: base-agent.ts:214
Execute a blocking run. Backend implements the actual LLM call.
Parameters
Section titled “Parameters”messages
Section titled “messages”Message[]
options
Section titled “options”signal
Section titled “signal”AbortSignal
Returns
Section titled “Returns”Promise<AgentResult<void>>
executeRunStructured()
Section titled “executeRunStructured()”
abstractprotectedexecuteRunStructured<T>(messages,schema,options,signal):Promise<AgentResult<T>>
Defined in: base-agent.ts:221
Execute a structured output run. Backend implements parsing.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”messages
Section titled “messages”Message[]
schema
Section titled “schema”options
Section titled “options”signal
Section titled “signal”AbortSignal
Returns
Section titled “Returns”Promise<AgentResult<T>>
executeStream()
Section titled “executeStream()”
abstractprotectedexecuteStream(messages,options,signal):AsyncIterable<AgentEvent>
Defined in: base-agent.ts:229
Execute a streaming run. Backend yields events.
Parameters
Section titled “Parameters”messages
Section titled “messages”Message[]
options
Section titled “options”signal
Section titled “signal”AbortSignal
Returns
Section titled “Returns”AsyncIterable<AgentEvent>
getConfig()
Section titled “getConfig()”getConfig():
Readonly<FullAgentConfig>
Defined in: base-agent.ts:199
Get frozen agent configuration.
Returns
Section titled “Returns”Readonly<FullAgentConfig>
Implementation of
Section titled “Implementation of”getState()
Section titled “getState()”getState():
AgentState
Defined in: base-agent.ts:195
Get current agent lifecycle state.
Returns
Section titled “Returns”Implementation of
Section titled “Implementation of”guardDisposed()
Section titled “guardDisposed()”
protectedguardDisposed():void
Defined in: base-agent.ts:493
Returns
Section titled “Returns”void
guardReentrancy()
Section titled “guardReentrancy()”
protectedguardReentrancy():void
Defined in: base-agent.ts:487
Returns
Section titled “Returns”void
interrupt()
Section titled “interrupt()”interrupt():
Promise<void>
Defined in: base-agent.ts:191
Default interrupt — falls back to abort(). Backends may override with graceful shutdown.
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”resolveTools()
Section titled “resolveTools()”
protectedresolveTools(options?):ToolDefinition<unknown>[]
Defined in: base-agent.ts:337
Resolve tools to use for this call (per-call override > config default)
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”ToolDefinition<unknown>[]
run(
prompt,options):Promise<AgentResult<void>>
Defined in: base-agent.ts:44
Run a single prompt and return the result. Wraps prompt in a user message.
Parameters
Section titled “Parameters”prompt
Section titled “prompt”options
Section titled “options”Returns
Section titled “Returns”Promise<AgentResult<void>>
Implementation of
Section titled “Implementation of”runStructured()
Section titled “runStructured()”runStructured<
T>(prompt,schema,options):Promise<AgentResult<T>>
Defined in: base-agent.ts:87
Run with structured output validated against a Zod schema.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”prompt
Section titled “prompt”schema
Section titled “schema”options
Section titled “options”Returns
Section titled “Returns”Promise<AgentResult<T>>
Implementation of
Section titled “Implementation of”runWithContext()
Section titled “runWithContext()”runWithContext(
messages,options):Promise<AgentResult<void>>
Defined in: base-agent.ts:66
Run with full conversation history. Messages are passed directly to the backend.
Parameters
Section titled “Parameters”messages
Section titled “messages”Message[]
options
Section titled “options”Returns
Section titled “Returns”Promise<AgentResult<void>>
Implementation of
Section titled “Implementation of”stream()
Section titled “stream()”stream(
prompt,options):AsyncIterable<AgentEvent>
Defined in: base-agent.ts:110
Stream events for a single prompt. Wraps prompt in a user message.
Parameters
Section titled “Parameters”prompt
Section titled “prompt”options
Section titled “options”Returns
Section titled “Returns”AsyncIterable<AgentEvent>
Implementation of
Section titled “Implementation of”streamWithContext()
Section titled “streamWithContext()”streamWithContext(
messages,options):AsyncIterable<AgentEvent>
Defined in: base-agent.ts:131
Stream events with full conversation history. Messages are passed directly to the backend.
Parameters
Section titled “Parameters”messages
Section titled “messages”Message[]
options
Section titled “options”Returns
Section titled “Returns”AsyncIterable<AgentEvent>
Implementation of
Section titled “Implementation of”CompositePermissionStore
Section titled “CompositePermissionStore”Defined in: permission-store.ts:128
Composes multiple stores — checks in order, routes writes by scope.
- “session” → sessionStore (in-memory)
- “project” → projectStore (file-based in project directory)
- “always” → userStore (file-based in user home)
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new CompositePermissionStore(
sessionStore,projectStore,userStore?):CompositePermissionStore
Defined in: permission-store.ts:133
Parameters
Section titled “Parameters”sessionStore
Section titled “sessionStore”projectStore
Section titled “projectStore”userStore?
Section titled “userStore?”Returns
Section titled “Returns”Methods
Section titled “Methods”approve()
Section titled “approve()”approve(
toolName,scope):Promise<void>
Defined in: permission-store.ts:151
Store an approval decision
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”clear()
Section titled “clear()”clear():
Promise<void>
Defined in: permission-store.ts:169
Clear all approvals
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”dispose()
Section titled “dispose()”dispose():
Promise<void>
Defined in: permission-store.ts:175
Dispose resources
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”isApproved()
Section titled “isApproved()”isApproved(
toolName):Promise<boolean>
Defined in: permission-store.ts:143
Check if tool is already approved
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<boolean>
Implementation of
Section titled “Implementation of”revoke()
Section titled “revoke()”revoke(
toolName):Promise<void>
Defined in: permission-store.ts:163
Revoke approval for a tool
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”DependencyError
Section titled “DependencyError”Defined in: errors.ts:95
Thrown when a required peer dependency is not installed
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new DependencyError(
packageName):DependencyError
Defined in: errors.ts:98
Parameters
Section titled “Parameters”packageName
Section titled “packageName”string
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
Inherited from
Section titled “Inherited from”httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
Inherited from
Section titled “Inherited from”packageName
Section titled “packageName”
readonlypackageName:string
Defined in: errors.ts:96
retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
Inherited from
Section titled “Inherited from”DisposedError
Section titled “DisposedError”Defined in: errors.ts:56
Thrown when an operation is attempted on a disposed agent/service
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new DisposedError(
entity):DisposedError
Defined in: errors.ts:57
Parameters
Section titled “Parameters”entity
Section titled “entity”string
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
Inherited from
Section titled “Inherited from”httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
Inherited from
Section titled “Inherited from”retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
Inherited from
Section titled “Inherited from”FilePermissionStore
Section titled “FilePermissionStore”Defined in: permission-store.ts:66
File-backed store — reads/writes a JSON file for persistent approvals.
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new FilePermissionStore(
filePath):FilePermissionStore
Defined in: permission-store.ts:69
Parameters
Section titled “Parameters”filePath
Section titled “filePath”string
Returns
Section titled “Returns”Methods
Section titled “Methods”approve()
Section titled “approve()”approve(
toolName,scope):Promise<void>
Defined in: permission-store.ts:78
Store an approval decision
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”clear()
Section titled “clear()”clear():
Promise<void>
Defined in: permission-store.ts:91
Clear all approvals
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”dispose()
Section titled “dispose()”dispose():
Promise<void>
Defined in: permission-store.ts:95
Dispose resources
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”isApproved()
Section titled “isApproved()”isApproved(
toolName):Promise<boolean>
Defined in: permission-store.ts:73
Check if tool is already approved
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<boolean>
Implementation of
Section titled “Implementation of”revoke()
Section titled “revoke()”revoke(
toolName):Promise<void>
Defined in: permission-store.ts:85
Revoke approval for a tool
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”InMemoryPermissionStore
Section titled “InMemoryPermissionStore”Defined in: permission-store.ts:29
In-memory store — approvals live until process exits (or dispose).
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new InMemoryPermissionStore():
InMemoryPermissionStore
Returns
Section titled “Returns”Methods
Section titled “Methods”approve()
Section titled “approve()”approve(
toolName,scope):Promise<void>
Defined in: permission-store.ts:36
Store an approval decision
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”clear()
Section titled “clear()”clear():
Promise<void>
Defined in: permission-store.ts:45
Clear all approvals
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”dispose()
Section titled “dispose()”dispose():
Promise<void>
Defined in: permission-store.ts:49
Dispose resources
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”isApproved()
Section titled “isApproved()”isApproved(
toolName):Promise<boolean>
Defined in: permission-store.ts:32
Check if tool is already approved
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<boolean>
Implementation of
Section titled “Implementation of”revoke()
Section titled “revoke()”revoke(
toolName):Promise<void>
Defined in: permission-store.ts:41
Revoke approval for a tool
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”ReentrancyError
Section titled “ReentrancyError”Defined in: errors.ts:46
Thrown when agent.run() is called while already running (M8 re-entrancy guard)
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new ReentrancyError():
ReentrancyError
Defined in: errors.ts:47
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
Inherited from
Section titled “Inherited from”httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
Inherited from
Section titled “Inherited from”retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
Inherited from
Section titled “Inherited from”StructuredOutputError
Section titled “StructuredOutputError”Defined in: errors.ts:138
Thrown when structured output parsing fails
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new StructuredOutputError(
message,options?):StructuredOutputError
Defined in: errors.ts:139
Parameters
Section titled “Parameters”message
Section titled “message”string
options?
Section titled “options?”ErrorOptions
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
Inherited from
Section titled “Inherited from”httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
Inherited from
Section titled “Inherited from”retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
Inherited from
Section titled “Inherited from”SubprocessError
Section titled “SubprocessError”Defined in: errors.ts:87
Thrown when subprocess management fails
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new SubprocessError(
message,options?):SubprocessError
Defined in: errors.ts:88
Parameters
Section titled “Parameters”message
Section titled “message”string
options?
Section titled “options?”ErrorOptions
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
Inherited from
Section titled “Inherited from”httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
Inherited from
Section titled “Inherited from”retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
Inherited from
Section titled “Inherited from”ToolExecutionError
Section titled “ToolExecutionError”Defined in: errors.ts:116
Thrown when a tool execution fails
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new ToolExecutionError(
toolName,message,options?):ToolExecutionError
Defined in: errors.ts:119
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
message
Section titled “message”string
options?
Section titled “options?”ErrorOptions
Returns
Section titled “Returns”Overrides
Section titled “Overrides”Properties
Section titled “Properties”
readonlyoptionalcode:string
Defined in: errors.ts:21
Machine-readable error code. Prefer values from the ErrorCode enum.
Inherited from
Section titled “Inherited from”httpStatus?
Section titled “httpStatus?”
readonlyoptionalhttpStatus:number
Defined in: errors.ts:25
HTTP status code hint for error classification
Inherited from
Section titled “Inherited from”retryable
Section titled “retryable”
readonlyretryable:boolean
Defined in: errors.ts:23
Whether this error is safe to retry
Inherited from
Section titled “Inherited from”toolName
Section titled “toolName”
readonlytoolName:string
Defined in: errors.ts:117
Methods
Section titled “Methods”
staticis(error):error is AgentSDKError
Defined in: errors.ts:36
Check if an error is an AgentSDKError (works across bundled copies)
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”error is AgentSDKError
Inherited from
Section titled “Inherited from”Interfaces
Section titled “Interfaces”AgentConfig
Section titled “AgentConfig”Defined in: types/agent.ts:105
Identity-only agent configuration — defines the agent’s behavior, NOT per-call defaults. For creating an agent with model/tools defaults, use FullAgentConfig.
Properties
Section titled “Properties”availableTools?
Section titled “availableTools?”
optionalavailableTools:string[]
Defined in: types/agent.ts:124
Filter for backend built-in tools (e.g. ["web_search", "web_fetch"] for Copilot).
When set, only listed built-in tools are available. Backend-specific.
Security note: This is a trust boundary — it controls which backend-native tools the AI agent can invoke. By default, backends expose ALL their built-in tools. Set this to restrict access (e.g. prevent file system access in a web-facing agent).
errorHandling?
Section titled “errorHandling?”
optionalerrorHandling:ErrorHandlingConfig
Defined in: types/agent.ts:110
heartbeatInterval?
Section titled “heartbeatInterval?”
optionalheartbeatInterval:number
Defined in: types/agent.ts:131
Interval in milliseconds for emitting heartbeat events during streaming. When set, heartbeat events are emitted to keep the stream alive during long tool executions. Default: off (no heartbeats).
maxTurns?
Section titled “maxTurns?”
optionalmaxTurns:number
Defined in: types/agent.ts:108
onUsage()?
Section titled “onUsage()?”
optionalonUsage: (usage) =>void
Defined in: types/agent.ts:127
Callback invoked with usage data after run completion or during streaming. Fire-and-forget: errors are logged but not propagated.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
permissionStore?
Section titled “permissionStore?”
optionalpermissionStore:IPermissionStore
Defined in: types/agent.ts:112
Pluggable store for persisting permission scope decisions across runs
sessionMode?
Section titled “sessionMode?”
optionalsessionMode:"per-call"|"persistent"
Defined in: types/agent.ts:136
Session reuse mode for CLI backends (Copilot, Claude). “per-call” (default): creates a fresh CLI session for each run/stream call. “persistent”: reuses the same CLI session across calls, preserving conversation history natively in the CLI backend. Session is destroyed on agent dispose().
supervisor?
Section titled “supervisor?”
optionalsupervisor:SupervisorHooks
Defined in: types/agent.ts:107
systemMessageMode?
Section titled “systemMessageMode?”
optionalsystemMessageMode:"replace"|"append"
Defined in: types/agent.ts:115
How to apply systemPrompt: “append” adds to backend default, “replace” overrides it. Default: “append”. Currently used by the Copilot backend.
systemPrompt
Section titled “systemPrompt”systemPrompt:
string
Defined in: types/agent.ts:106
timeout?
Section titled “timeout?”
optionaltimeout:TimeoutConfig
Defined in: types/agent.ts:109
AgentResult
Section titled “AgentResult”Defined in: types/agent.ts:161
Result of an agent run, generic over structured output type T
Type Parameters
Section titled “Type Parameters”T = void
Properties
Section titled “Properties”messages
Section titled “messages”messages:
Message[]
Defined in: types/agent.ts:170
output
Section titled “output”output:
string|null
Defined in: types/agent.ts:162
structuredOutput
Section titled “structuredOutput”structuredOutput:
Textendsvoid?undefined:T
Defined in: types/agent.ts:163
toolCalls
Section titled “toolCalls”toolCalls:
object[]
Defined in: types/agent.ts:164
approved
Section titled “approved”approved:
boolean
args:
JSONValue
result
Section titled “result”result:
JSONValue
toolName
Section titled “toolName”toolName:
string
usage?
Section titled “usage?”
optionalusage:UsageData
Defined in: types/agent.ts:171
AgentSDKErrorOptions
Section titled “AgentSDKErrorOptions”Defined in: errors.ts:4
Options for constructing an AgentSDKError
Extends
Section titled “Extends”ErrorOptions
Properties
Section titled “Properties”
optionalcode:string
Defined in: errors.ts:6
Machine-readable error code
httpStatus?
Section titled “httpStatus?”
optionalhttpStatus:number
Defined in: errors.ts:10
HTTP status code hint (e.g. 401, 429, 500)
retryable?
Section titled “retryable?”
optionalretryable:boolean
Defined in: errors.ts:8
Whether this error is retryable (default: false)
BackendOptionsMap
Section titled “BackendOptionsMap”Defined in: registry.ts:20
Map of built-in backend names to their options types
Properties
Section titled “Properties”claude
Section titled “claude”claude:
ClaudeBackendOptions
Defined in: registry.ts:22
copilot
Section titled “copilot”copilot:
CopilotBackendOptions
Defined in: registry.ts:21
vercel-ai
Section titled “vercel-ai”vercel-ai:
VercelAIBackendOptions
Defined in: registry.ts:23
CallDefaults
Section titled “CallDefaults”Defined in: types/agent.ts:141
Per-call defaults that can be provided at agent creation time. Each field can also be overridden on individual calls via RunOptions.
Properties
Section titled “Properties”model?
Section titled “model?”
optionalmodel:string
Defined in: types/agent.ts:143
Default model (overridable per-call via RunOptions.model)
modelParams?
Section titled “modelParams?”
optionalmodelParams:ModelParams
Defined in: types/agent.ts:145
Default model parameters
providerOptions?
Section titled “providerOptions?”
optionalproviderOptions:Record<string,Record<string,unknown>>
Defined in: types/agent.ts:151
Provider-specific options passed through to the underlying SDK. For Vercel AI: passed as providerOptions to generateText/streamText. Example: { google: { thinkingConfig: { thinkingBudget: 1024 } } }
tools?
Section titled “tools?”
optionaltools:ToolDefinition<unknown>[]
Defined in: types/agent.ts:147
Default tools (overridable per-call via RunOptions.tools)
CallOptions
Section titled “CallOptions”Defined in: types/agent.ts:16
Per-call overrides passed to run(), stream(), runStructured(). Allows overriding the model, tools, signal, and other parameters on a per-request basis without modifying the agent configuration.
Extended by
Section titled “Extended by”Properties
Section titled “Properties”maxTokens?
Section titled “maxTokens?”
optionalmaxTokens:number
Defined in: types/agent.ts:30
Per-call token limit
model?
Section titled “model?”
optionalmodel:string
Defined in: types/agent.ts:18
Override the default model for this call
providerOptions?
Section titled “providerOptions?”
optionalproviderOptions:Record<string,unknown>
Defined in: types/agent.ts:26
Provider-specific options passed through to the underlying SDK
retry?
Section titled “retry?”
optionalretry:RetryConfig
Defined in: types/agent.ts:32
Retry configuration for this call
signal?
Section titled “signal?”
optionalsignal:AbortSignal
Defined in: types/agent.ts:22
Per-call abort signal
systemMessage?
Section titled “systemMessage?”
optionalsystemMessage:string
Defined in: types/agent.ts:24
Override system message for this call
timeout?
Section titled “timeout?”
optionaltimeout:number
Defined in: types/agent.ts:28
Per-call timeout in milliseconds
tools?
Section titled “tools?”
optionaltools:ToolDefinition<unknown>[]
Defined in: types/agent.ts:20
Override/extend tools for this call
ClaudeBackendOptions
Section titled “ClaudeBackendOptions”Defined in: types/backends.ts:21
Options for Claude CLI backend
Properties
Section titled “Properties”cliPath?
Section titled “cliPath?”
optionalcliPath:string
Defined in: types/backends.ts:22
optionalenv:Record<string,string|undefined>
Defined in: types/backends.ts:28
Custom environment variables merged into the subprocess env
maxTurns?
Section titled “maxTurns?”
optionalmaxTurns:number
Defined in: types/backends.ts:24
oauthToken?
Section titled “oauthToken?”
optionaloauthToken:string
Defined in: types/backends.ts:26
OAuth token for Claude authentication (set as CLAUDE_CODE_OAUTH_TOKEN env var)
resumeSessionId?
Section titled “resumeSessionId?”
optionalresumeSessionId:string
Defined in: types/backends.ts:31
Session ID to resume after server restart. On startup, the backend attempts to resume this session before creating a new one.
workingDirectory?
Section titled “workingDirectory?”
optionalworkingDirectory:string
Defined in: types/backends.ts:23
CopilotBackendOptions
Section titled “CopilotBackendOptions”Defined in: types/backends.ts:2
Options for Copilot CLI backend
Properties
Section titled “Properties”cliArgs?
Section titled “cliArgs?”
optionalcliArgs:string[]
Defined in: types/backends.ts:8
Extra CLI arguments passed to the Copilot subprocess (e.g. [“—allow-all”])
cliPath?
Section titled “cliPath?”
optionalcliPath:string
Defined in: types/backends.ts:3
optionalenv:Record<string,string|undefined>
Defined in: types/backends.ts:14
Custom environment variables merged into the subprocess env
githubToken?
Section titled “githubToken?”
optionalgithubToken:string
Defined in: types/backends.ts:5
resumeSessionId?
Section titled “resumeSessionId?”
optionalresumeSessionId:string
Defined in: types/backends.ts:17
Session ID to resume after server restart. On startup, the backend attempts to resume this session before creating a new one.
startupTimeoutMs?
Section titled “startupTimeoutMs?”
optionalstartupTimeoutMs:number
Defined in: types/backends.ts:12
Timeout in milliseconds for CLI startup and auth check (default: 30000).
timeout?
Section titled “timeout?”
optionaltimeout:number
Defined in: types/backends.ts:10
Timeout in milliseconds for sendAndWait() calls. When undefined, uses copilot-sdk default (60s).
useLoggedInUser?
Section titled “useLoggedInUser?”
optionaluseLoggedInUser:boolean
Defined in: types/backends.ts:6
workingDirectory?
Section titled “workingDirectory?”
optionalworkingDirectory:string
Defined in: types/backends.ts:4
ErrorHandlingConfig
Section titled “ErrorHandlingConfig”Defined in: types/agent.ts:89
Error handling strategy configuration
Properties
Section titled “Properties”onError()?
Section titled “onError()?”
optionalonError: (error,context) =>void
Defined in: types/agent.ts:95
Global error callback for monitoring
Parameters
Section titled “Parameters”Error
context
Section titled “context”"tool" | "llm" | "permission" | "ask-user"
Returns
Section titled “Returns”void
onToolError?
Section titled “onToolError?”
optionalonToolError:"fail"|"continue"|"ask-llm"
Defined in: types/agent.ts:91
What to do when a tool throws
retryLLM?
Section titled “retryLLM?”
optionalretryLLM:object
Defined in: types/agent.ts:93
Retry config for transient LLM failures
backoffMs
Section titled “backoffMs”backoffMs:
number
maxAttempts
Section titled “maxAttempts”maxAttempts:
number
IAgent
Section titled “IAgent”Defined in: types/agent.ts:182
Core agent interface — run prompts, stream events, manage lifecycle
Properties
Section titled “Properties”sessionId
Section titled “sessionId”
readonlysessionId:string|undefined
Defined in: types/agent.ts:185
The CLI session ID when using persistent session mode. Undefined in per-call mode or before the first call. Can be stored externally for session resume.
Methods
Section titled “Methods”abort()
Section titled “abort()”abort():
void
Defined in: types/agent.ts:210
Abort the current operation. No-op if not running.
Returns
Section titled “Returns”void
dispose()
Section titled “dispose()”dispose():
void
Defined in: types/agent.ts:218
Release resources. After dispose(), agent must not be used.
Returns
Section titled “Returns”void
getConfig()
Section titled “getConfig()”getConfig():
Readonly<FullAgentConfig>
Defined in: types/agent.ts:216
Get frozen agent configuration.
Returns
Section titled “Returns”Readonly<FullAgentConfig>
getState()
Section titled “getState()”getState():
AgentState
Defined in: types/agent.ts:214
Get current agent lifecycle state.
Returns
Section titled “Returns”interrupt()
Section titled “interrupt()”interrupt():
Promise<void>
Defined in: types/agent.ts:212
Gracefully interrupt the current operation. Resolves when the backend acknowledges.
Returns
Section titled “Returns”Promise<void>
run(
prompt,options):Promise<AgentResult<void>>
Defined in: types/agent.ts:187
Run a single prompt and return the result. Wraps prompt in a user message.
Parameters
Section titled “Parameters”prompt
Section titled “prompt”options
Section titled “options”Returns
Section titled “Returns”Promise<AgentResult<void>>
runStructured()
Section titled “runStructured()”runStructured<
T>(prompt,schema,options):Promise<AgentResult<T>>
Defined in: types/agent.ts:194
Run with structured output validated against a Zod schema.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”prompt
Section titled “prompt”schema
Section titled “schema”options
Section titled “options”Returns
Section titled “Returns”Promise<AgentResult<T>>
runWithContext()
Section titled “runWithContext()”runWithContext(
messages,options):Promise<AgentResult<void>>
Defined in: types/agent.ts:189
Run with full conversation history. Messages are passed directly to the backend.
Parameters
Section titled “Parameters”messages
Section titled “messages”Message[]
options
Section titled “options”Returns
Section titled “Returns”Promise<AgentResult<void>>
stream()
Section titled “stream()”stream(
prompt,options):AsyncIterable<AgentEvent>
Defined in: types/agent.ts:200
Stream events for a single prompt. Wraps prompt in a user message.
Parameters
Section titled “Parameters”prompt
Section titled “prompt”options
Section titled “options”Returns
Section titled “Returns”AsyncIterable<AgentEvent>
streamWithContext()
Section titled “streamWithContext()”streamWithContext(
messages,options):AsyncIterable<AgentEvent>
Defined in: types/agent.ts:205
Stream events with full conversation history. Messages are passed directly to the backend.
Parameters
Section titled “Parameters”messages
Section titled “messages”Message[]
options
Section titled “options”Returns
Section titled “Returns”AsyncIterable<AgentEvent>
IAgentService
Section titled “IAgentService”Defined in: types/agent.ts:224
Backend service interface — creates agents, lists models, validates config
Properties
Section titled “Properties”
readonlyname:string
Defined in: types/agent.ts:225
Methods
Section titled “Methods”createAgent()
Section titled “createAgent()”createAgent(
config):IAgent
Defined in: types/agent.ts:226
Parameters
Section titled “Parameters”config
Section titled “config”Returns
Section titled “Returns”dispose()
Section titled “dispose()”dispose():
Promise<void>
Defined in: types/agent.ts:229
Returns
Section titled “Returns”Promise<void>
listModels()
Section titled “listModels()”listModels():
Promise<ModelInfo[]>
Defined in: types/agent.ts:227
Returns
Section titled “Returns”Promise<ModelInfo[]>
validate()
Section titled “validate()”validate():
Promise<ValidationResult>
Defined in: types/agent.ts:228
Returns
Section titled “Returns”Promise<ValidationResult>
IPermissionStore
Section titled “IPermissionStore”Defined in: permission-store.ts:9
Pluggable store for persisting permission (scope) decisions across runs.
Methods
Section titled “Methods”approve()
Section titled “approve()”approve(
toolName,scope):Promise<void>
Defined in: permission-store.ts:14
Store an approval decision
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<void>
clear()
Section titled “clear()”clear():
Promise<void>
Defined in: permission-store.ts:20
Clear all approvals
Returns
Section titled “Returns”Promise<void>
dispose()
Section titled “dispose()”dispose():
Promise<void>
Defined in: permission-store.ts:23
Dispose resources
Returns
Section titled “Returns”Promise<void>
isApproved()
Section titled “isApproved()”isApproved(
toolName):Promise<boolean>
Defined in: permission-store.ts:11
Check if tool is already approved
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<boolean>
revoke()
Section titled “revoke()”revoke(
toolName):Promise<void>
Defined in: permission-store.ts:17
Revoke approval for a tool
Parameters
Section titled “Parameters”toolName
Section titled “toolName”string
Returns
Section titled “Returns”Promise<void>
ModelInfo
Section titled “ModelInfo”Defined in: types/models.ts:2
Model metadata returned by listModels()
Properties
Section titled “Properties”capabilities?
Section titled “capabilities?”
optionalcapabilities:string[]
Defined in: types/models.ts:11
Model capabilities (e.g. “vision”, “tools”, “structured”)
contextWindow?
Section titled “contextWindow?”
optionalcontextWindow:number
Defined in: types/models.ts:9
Context window size in tokens
id:
string
Defined in: types/models.ts:3
optionalname:string
Defined in: types/models.ts:4
provider?
Section titled “provider?”
optionalprovider:string
Defined in: types/models.ts:5
optionaltier:"fast"|"standard"|"premium"
Defined in: types/models.ts:7
Model tier for UI categorization and cost hints
ModelParams
Section titled “ModelParams”Defined in: types/models.ts:15
LLM model parameters
Properties
Section titled “Properties”maxTokens?
Section titled “maxTokens?”
optionalmaxTokens:number
Defined in: types/models.ts:17
stopSequences?
Section titled “stopSequences?”
optionalstopSequences:string[]
Defined in: types/models.ts:19
temperature?
Section titled “temperature?”
optionaltemperature:number
Defined in: types/models.ts:16
optionaltopP:number
Defined in: types/models.ts:18
PermissionDecision
Section titled “PermissionDecision”Defined in: types/permissions.ts:17
What the permission callback returns
Properties
Section titled “Properties”allowed
Section titled “allowed”allowed:
boolean
Defined in: types/permissions.ts:18
modifiedInput?
Section titled “modifiedInput?”
optionalmodifiedInput:Record<string,unknown>
Defined in: types/permissions.ts:22
Modified tool arguments (tool args may be altered by user)
reason?
Section titled “reason?”
optionalreason:string
Defined in: types/permissions.ts:24
Denial reason (if denied)
scope?
Section titled “scope?”
optionalscope:PermissionScope
Defined in: types/permissions.ts:20
How long to remember this decision
PermissionRequest
Section titled “PermissionRequest”Defined in: types/permissions.ts:5
What the permission callback receives
Properties
Section titled “Properties”rawSDKRequest?
Section titled “rawSDKRequest?”
optionalrawSDKRequest:unknown
Defined in: types/permissions.ts:13
Original SDK permission request (for pass-through)
suggestedScope?
Section titled “suggestedScope?”
optionalsuggestedScope:PermissionScope
Defined in: types/permissions.ts:11
SDK-suggested scope (from Claude CLI’s suggestions)
toolArgs
Section titled “toolArgs”toolArgs:
Record<string,unknown>
Defined in: types/permissions.ts:7
toolCallId?
Section titled “toolCallId?”
optionaltoolCallId:string
Defined in: types/permissions.ts:9
Unique identifier for this specific tool call
toolName
Section titled “toolName”toolName:
string
Defined in: types/permissions.ts:6
RetryConfig
Section titled “RetryConfig”Defined in: types/agent.ts:38
Configuration for automatic retries on transient errors
Properties
Section titled “Properties”backoffMultiplier?
Section titled “backoffMultiplier?”
optionalbackoffMultiplier:number
Defined in: types/agent.ts:44
Backoff multiplier (default: 2)
initialDelayMs?
Section titled “initialDelayMs?”
optionalinitialDelayMs:number
Defined in: types/agent.ts:42
Initial delay in ms before first retry (default: 1000)
maxRetries?
Section titled “maxRetries?”
optionalmaxRetries:number
Defined in: types/agent.ts:40
Maximum number of retries (default: 0 — no retry)
retryableErrors?
Section titled “retryableErrors?”
optionalretryableErrors:ErrorCode[]
Defined in: types/agent.ts:46
Which error codes to retry (default: all recoverable codes)
RunOptions
Section titled “RunOptions”Defined in: types/agent.ts:63
Options passed to agent.run() / agent.stream(). Extends CallOptions with run-specific fields (context, activityTimeoutMs). model is REQUIRED — every agent call must specify the model explicitly.
Extends
Section titled “Extends”Properties
Section titled “Properties”activityTimeoutMs?
Section titled “activityTimeoutMs?”
optionalactivityTimeoutMs:number
Defined in: types/agent.ts:71
Inactivity timeout for streaming (ms). When set, the stream aborts if no event (including heartbeats/progress) arrives within this period. Resets on every received event. Default: no timeout. Only affects stream()/streamWithContext().
context?
Section titled “context?”
optionalcontext:Record<string,unknown>
Defined in: types/agent.ts:67
Arbitrary context passed to the agent run
maxTokens?
Section titled “maxTokens?”
optionalmaxTokens:number
Defined in: types/agent.ts:30
Per-call token limit
Inherited from
Section titled “Inherited from”model:
string
Defined in: types/agent.ts:65
Model to use for this call (required — no implicit defaults)
Overrides
Section titled “Overrides”providerOptions?
Section titled “providerOptions?”
optionalproviderOptions:Record<string,unknown>
Defined in: types/agent.ts:26
Provider-specific options passed through to the underlying SDK
Inherited from
Section titled “Inherited from”retry?
Section titled “retry?”
optionalretry:RetryConfig
Defined in: types/agent.ts:32
Retry configuration for this call
Inherited from
Section titled “Inherited from”signal?
Section titled “signal?”
optionalsignal:AbortSignal
Defined in: types/agent.ts:22
Per-call abort signal
Inherited from
Section titled “Inherited from”systemMessage?
Section titled “systemMessage?”
optionalsystemMessage:string
Defined in: types/agent.ts:24
Override system message for this call
Inherited from
Section titled “Inherited from”timeout?
Section titled “timeout?”
optionaltimeout:number
Defined in: types/agent.ts:28
Per-call timeout in milliseconds
Inherited from
Section titled “Inherited from”tools?
Section titled “tools?”
optionaltools:ToolDefinition<unknown>[]
Defined in: types/agent.ts:20
Override/extend tools for this call
Inherited from
Section titled “Inherited from”StreamContext
Section titled “StreamContext”Defined in: types/events.ts:44
Context passed to stream middleware — immutable per stream invocation
Properties
Section titled “Properties”abortController
Section titled “abortController”abortController:
AbortController
Defined in: types/events.ts:47
backend
Section titled “backend”backend:
string
Defined in: types/events.ts:46
config
Section titled “config”config:
Readonly<Record<string,unknown>>
Defined in: types/events.ts:49
Agent config snapshot. Loosely typed to avoid leaking internal FullAgentConfig to external middleware consumers.
model:
string
Defined in: types/events.ts:45
StructuredOutputConfig
Section titled “StructuredOutputConfig”Defined in: types/agent.ts:52
Configuration for typed structured output from LLM
Type Parameters
Section titled “Type Parameters”T = unknown
Properties
Section titled “Properties”description?
Section titled “description?”
optionaldescription:string
Defined in: types/agent.ts:55
optionalname:string
Defined in: types/agent.ts:54
schema
Section titled “schema”schema:
ZodType<T>
Defined in: types/agent.ts:53
SupervisorHooks
Section titled “SupervisorHooks”Defined in: types/permissions.ts:51
Hooks for supervisor/UI to intercept agent actions
Properties
Section titled “Properties”onAskUser()?
Section titled “onAskUser()?”
optionalonAskUser: (request,signal) =>Promise<UserInputResponse>
Defined in: types/permissions.ts:53
Parameters
Section titled “Parameters”request
Section titled “request”signal
Section titled “signal”AbortSignal
Returns
Section titled “Returns”Promise<UserInputResponse>
onPermission?
Section titled “onPermission?”
optionalonPermission:PermissionCallback
Defined in: types/permissions.ts:52
TimeoutConfig
Section titled “TimeoutConfig”Defined in: types/agent.ts:77
Timeout configuration for agent operations
Properties
Section titled “Properties”perLLMRequest?
Section titled “perLLMRequest?”
optionalperLLMRequest:number
Defined in: types/agent.ts:83
Max time for a single LLM request (ms)
perTool?
Section titled “perTool?”
optionalperTool:number
Defined in: types/agent.ts:81
Max time for a single tool execution (ms)
total?
Section titled “total?”
optionaltotal:number
Defined in: types/agent.ts:79
Max time for entire agent run (ms)
ToolCall
Section titled “ToolCall”Defined in: types/tools.ts:36
A tool call made by the LLM during execution
Properties
Section titled “Properties”args:
JSONValue
Defined in: types/tools.ts:39
id:
string
Defined in: types/tools.ts:37
name:
string
Defined in: types/tools.ts:38
ToolContext
Section titled “ToolContext”Defined in: types/tools.ts:28
Request-scoped context passed to tool execute functions via ChatRuntime. Contains session identity and user-defined metadata from the current session.
Properties
Section titled “Properties”custom?
Section titled “custom?”
optionalcustom:Record<string,unknown>
Defined in: types/tools.ts:32
Custom metadata from the session (e.g. user ID, tenant, permissions)
sessionId
Section titled “sessionId”sessionId:
string
Defined in: types/tools.ts:30
Active chat session ID
ToolDeclaration
Section titled “ToolDeclaration”Defined in: types/tools.ts:5
What the LLM sees — name, description, schema. Passed to all backends.
Extended by
Section titled “Extended by”Type Parameters
Section titled “Type Parameters”TParams
Section titled “TParams”TParams = unknown
Properties
Section titled “Properties”description
Section titled “description”description:
string
Defined in: types/tools.ts:7
metadata?
Section titled “metadata?”
optionalmetadata:object
Defined in: types/tools.ts:10
category?
Section titled “category?”
optionalcategory:string
optionalicon:string
optionaltags:string[]
name:
string
Defined in: types/tools.ts:6
needsApproval?
Section titled “needsApproval?”
optionalneedsApproval:boolean
Defined in: types/tools.ts:9
parameters
Section titled “parameters”parameters:
ZodType<TParams>
Defined in: types/tools.ts:8
ToolDefinition
Section titled “ToolDefinition”Defined in: types/tools.ts:21
Full tool with execute function. Required for API-based backends. CLI backends extract declaration; execute map held internally. The optional second parameter receives request-scoped context when invoked through ChatRuntime (session ID, user data, custom metadata).
Extends
Section titled “Extends”ToolDeclaration<TParams>
Type Parameters
Section titled “Type Parameters”TParams
Section titled “TParams”TParams = unknown
Properties
Section titled “Properties”description
Section titled “description”description:
string
Defined in: types/tools.ts:7
Inherited from
Section titled “Inherited from”execute()
Section titled “execute()”execute: (
params,context?) =>unknown
Defined in: types/tools.ts:23
Parameters
Section titled “Parameters”params
Section titled “params”TParams
context?
Section titled “context?”Returns
Section titled “Returns”unknown
metadata?
Section titled “metadata?”
optionalmetadata:object
Defined in: types/tools.ts:10
category?
Section titled “category?”
optionalcategory:string
optionalicon:string
optionaltags:string[]
Inherited from
Section titled “Inherited from”name:
string
Defined in: types/tools.ts:6
Inherited from
Section titled “Inherited from”needsApproval?
Section titled “needsApproval?”
optionalneedsApproval:boolean
Defined in: types/tools.ts:9
Inherited from
Section titled “Inherited from”parameters
Section titled “parameters”parameters:
ZodType<TParams>
Defined in: types/tools.ts:8
Inherited from
Section titled “Inherited from”ToolResult
Section titled “ToolResult”Defined in: types/tools.ts:43
Result of executing a tool call
Properties
Section titled “Properties”isError?
Section titled “isError?”
optionalisError:boolean
Defined in: types/tools.ts:47
name:
string
Defined in: types/tools.ts:45
result
Section titled “result”result:
JSONValue
Defined in: types/tools.ts:46
toolCallId
Section titled “toolCallId”toolCallId:
string
Defined in: types/tools.ts:44
UsageData
Section titled “UsageData”Defined in: types/events.ts:6
Usage data from LLM execution — tokens consumed plus optional metadata
Properties
Section titled “Properties”backend?
Section titled “backend?”
optionalbackend:string
Defined in: types/events.ts:10
completionTokens
Section titled “completionTokens”completionTokens:
number
Defined in: types/events.ts:8
model?
Section titled “model?”
optionalmodel:string
Defined in: types/events.ts:9
promptTokens
Section titled “promptTokens”promptTokens:
number
Defined in: types/events.ts:7
UserInputRequest
Section titled “UserInputRequest”Defined in: types/permissions.ts:34
Request for user input — separate from permissions
Properties
Section titled “Properties”allowFreeform?
Section titled “allowFreeform?”
optionalallowFreeform:boolean
Defined in: types/permissions.ts:38
Whether to allow freeform text input (default: true)
choices?
Section titled “choices?”
optionalchoices:string[]
Defined in: types/permissions.ts:36
question
Section titled “question”question:
string
Defined in: types/permissions.ts:35
UserInputResponse
Section titled “UserInputResponse”Defined in: types/permissions.ts:42
Response from user to an input request
Properties
Section titled “Properties”answer
Section titled “answer”answer:
string
Defined in: types/permissions.ts:43
selectedChoiceIndex?
Section titled “selectedChoiceIndex?”
optionalselectedChoiceIndex:number
Defined in: types/permissions.ts:47
Index of selected choice (if choice was selected)
wasFreeform
Section titled “wasFreeform”wasFreeform:
boolean
Defined in: types/permissions.ts:45
true if user typed a custom answer instead of selecting a choice
ValidationResult
Section titled “ValidationResult”Defined in: types/models.ts:23
Result of backend validation check
Properties
Section titled “Properties”errors
Section titled “errors”errors:
string[]
Defined in: types/models.ts:25
valid:
boolean
Defined in: types/models.ts:24
VercelAIBackendOptions
Section titled “VercelAIBackendOptions”Defined in: types/backends.ts:97
Options for Vercel AI SDK backend
Properties
Section titled “Properties”apiKey
Section titled “apiKey”apiKey:
string
Defined in: types/backends.ts:98
baseUrl?
Section titled “baseUrl?”
optionalbaseUrl:string
Defined in: types/backends.ts:100
provider?
Section titled “provider?”
optionalprovider:string
Defined in: types/backends.ts:99
Type Aliases
Section titled “Type Aliases”AgentEvent
Section titled “AgentEvent”AgentEvent = {
text:string;type:"text_delta"; } | {text:string;type:"thinking_delta"; } | {args:JSONValue;toolCallId:string;toolName:string;type:"tool_call_start"; } | {result:JSONValue;toolCallId:string;toolName:string;type:"tool_call_end"; } | {request:PermissionRequest;type:"permission_request"; } | {decision:PermissionDecision;toolName:string;type:"permission_response"; } | {request:UserInputRequest;type:"ask_user"; } | {answer:string;type:"ask_user_response"; } | {type:"thinking_start"; } | {type:"thinking_end"; } | {backend?:string;completionTokens:number;model?:string;promptTokens:number;type:"usage_update"; } | {backend:string;sessionId:string;transcriptPath?:string;type:"session_info"; } | {type:"heartbeat"; } | {code?:ErrorCode;error:string;recoverable:boolean;type:"error"; } | {finalOutput:string|null;finishReason?:string;streamed?:boolean;structuredOutput?:unknown;type:"done"; }
Defined in: types/events.ts:14
Events emitted during streaming agent execution
AgentState
Section titled “AgentState”AgentState =
"idle"|"running"|"streaming"|"disposed"
Defined in: types/agent.ts:177
Agent lifecycle state
BackendFactory()
Section titled “BackendFactory()”BackendFactory<
TOptions> = (options) =>IAgentService|Promise<IAgentService>
Defined in: registry.ts:15
Factory function that creates a backend service from options
Type Parameters
Section titled “Type Parameters”TOptions
Section titled “TOptions”TOptions = unknown
Parameters
Section titled “Parameters”options
Section titled “options”TOptions
Returns
Section titled “Returns”IAgentService | Promise<IAgentService>
BuiltinBackendName
Section titled “BuiltinBackendName”BuiltinBackendName = keyof
BackendOptionsMap
Defined in: registry.ts:27
All known backend names (built-in + custom)
ContentPart
Section titled “ContentPart”ContentPart = {
text:string;type:"text"; } | {data:string;mimeType:string;type:"image"; }
Defined in: types/messages.ts:7
Individual content part within a multi-part message
FullAgentConfig
Section titled “FullAgentConfig”FullAgentConfig =
AgentConfig&CallDefaults
Defined in: types/agent.ts:156
Full agent configuration: identity + per-call defaults. This is what createAgent() accepts. Backward-compatible with the old AgentConfig shape.
JSONValue
Section titled “JSONValue”JSONValue =
string|number|boolean|null|JSONValue[] | {[key:string]:JSONValue; }
Defined in: types/json.ts:2
JSON-serializable value used for tool arguments and results
Message
Section titled “Message”Message = {
content:MessageContent;role:"user"; } | {content:MessageContent;role:"assistant";thinking?:string;toolCalls?:ToolCall[]; } | {content?:string;role:"tool";toolResults:ToolResult[]; } | {content:string;role:"system"; }
Defined in: types/messages.ts:12
Conversation message — discriminated union on role
MessageContent
Section titled “MessageContent”MessageContent =
string|ContentPart[]
Defined in: types/messages.ts:4
Message content — plain string or array of text/image parts
PermissionCallback()
Section titled “PermissionCallback()”PermissionCallback = (
request,signal) =>Promise<PermissionDecision>
Defined in: types/permissions.ts:28
Permission callback signature
Parameters
Section titled “Parameters”request
Section titled “request”signal
Section titled “signal”AbortSignal
Returns
Section titled “Returns”Promise<PermissionDecision>
PermissionScope
Section titled “PermissionScope”PermissionScope =
"once"|"session"|"project"|"always"
Defined in: types/permissions.ts:2
Scope for “remember this decision”
StreamMiddleware()
Section titled “StreamMiddleware()”StreamMiddleware = (
source,context) =>AsyncIterable<AgentEvent>
Defined in: types/events.ts:54
A composable transform over the agent event stream. Receives the upstream source and context, returns a transformed stream.
Parameters
Section titled “Parameters”source
Section titled “source”AsyncIterable<AgentEvent>
context
Section titled “context”Returns
Section titled “Returns”AsyncIterable<AgentEvent>
Functions
Section titled “Functions”buildSystemPrompt()
Section titled “buildSystemPrompt()”buildSystemPrompt(
base,schemaInstruction?):string
Defined in: utils/messages.ts:29
Build a system prompt with optional structured output instruction
Parameters
Section titled “Parameters”string
schemaInstruction?
Section titled “schemaInstruction?”string
Returns
Section titled “Returns”string
classifyAgentError()
Section titled “classifyAgentError()”classifyAgentError(
error):ErrorCode
Defined in: types/errors.ts:73
Classify an error message string into an ErrorCode
Parameters
Section titled “Parameters”string | Error
Returns
Section titled “Returns”contentToText()
Section titled “contentToText()”contentToText(
content):string
Defined in: utils/messages.ts:24
Convert MessageContent to plain text
Parameters
Section titled “Parameters”content
Section titled “content”Returns
Section titled “Returns”string
createAgentService()
Section titled “createAgentService()”Call Signature
Section titled “Call Signature”createAgentService<
K>(name,options,configId?):Promise<IAgentService>
Defined in: registry.ts:171
Create a backend service with type-safe options.
When configId is provided, the service instance is cached and reused
on subsequent calls with the same name+configId pair. Without configId,
a new instance is created every call.
Type Parameters
Section titled “Type Parameters”K extends keyof BackendOptionsMap
Parameters
Section titled “Parameters”K
options
Section titled “options”configId?
Section titled “configId?”string
Returns
Section titled “Returns”Promise<IAgentService>
Call Signature
Section titled “Call Signature”createAgentService(
name,options,configId?):Promise<IAgentService>
Defined in: registry.ts:176
Create a backend service with type-safe options.
When configId is provided, the service instance is cached and reused
on subsequent calls with the same name+configId pair. Without configId,
a new instance is created every call.
Parameters
Section titled “Parameters”string
options
Section titled “options”unknown
configId?
Section titled “configId?”string
Returns
Section titled “Returns”Promise<IAgentService>
createDefaultPermissionStore()
Section titled “createDefaultPermissionStore()”createDefaultPermissionStore(
projectDir?):CompositePermissionStore
Defined in: permission-store.ts:187
Create a default composite store with separate project and user-level persistence.
Parameters
Section titled “Parameters”projectDir?
Section titled “projectDir?”string
Returns
Section titled “Returns”disposeBackend()
Section titled “disposeBackend()”disposeBackend(
name,configId?):Promise<number>
Defined in: registry.ts:84
Dispose all cached service instances for a backend, or a single named config. Returns the number of instances disposed.
Parameters
Section titled “Parameters”string
configId?
Section titled “configId?”string
Returns
Section titled “Returns”Promise<number>
getTextContent()
Section titled “getTextContent()”getTextContent(
content):string
Defined in: types/guards.ts:24
Extract text from MessageContent regardless of format
Parameters
Section titled “Parameters”content
Section titled “content”Returns
Section titled “Returns”string
hasBackend()
Section titled “hasBackend()”hasBackend(
name):boolean
Defined in: registry.ts:63
Check if a backend is registered (eagerly or lazily)
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”boolean
isMultiPartContent()
Section titled “isMultiPartContent()”isMultiPartContent(
content):content is ContentPart[]
Defined in: types/guards.ts:17
Type guard: checks if MessageContent is multi-part array
Parameters
Section titled “Parameters”content
Section titled “content”Returns
Section titled “Returns”content is ContentPart[]
isRecoverableErrorCode()
Section titled “isRecoverableErrorCode()”isRecoverableErrorCode(
code):boolean
Defined in: types/errors.ts:68
Check if an error code is recoverable
Parameters
Section titled “Parameters”Returns
Section titled “Returns”boolean
isTextContent()
Section titled “isTextContent()”isTextContent(
content):content is string
Defined in: types/guards.ts:12
Type guard: checks if MessageContent is plain string
Parameters
Section titled “Parameters”content
Section titled “content”Returns
Section titled “Returns”content is string
isToolDefinition()
Section titled “isToolDefinition()”isToolDefinition(
tool):tool is ToolDefinition<unknown>
Defined in: types/guards.ts:5
Type guard: checks if a ToolDeclaration has an execute function (i.e., is a ToolDefinition)
Parameters
Section titled “Parameters”Returns
Section titled “Returns”tool is ToolDefinition<unknown>
listBackends()
Section titled “listBackends()”listBackends():
string[]
Defined in: registry.ts:68
List all registered backend names (eager + lazy)
Returns
Section titled “Returns”string[]
listConfigs()
Section titled “listConfigs()”listConfigs(
name):string[]
Defined in: registry.ts:109
List all active config IDs for a backend
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”string[]
messagesToPrompt()
Section titled “messagesToPrompt()”messagesToPrompt(
messages):string
Defined in: utils/messages.ts:5
Convert our Message[] to a flat prompt string (for CLIs that accept text)
Parameters
Section titled “Parameters”messages
Section titled “messages”Message[]
Returns
Section titled “Returns”string
registerBackend()
Section titled “registerBackend()”registerBackend<
TOptions>(name,factory):void
Defined in: registry.ts:47
Register a custom backend factory
Type Parameters
Section titled “Type Parameters”TOptions
Section titled “TOptions”TOptions = unknown
Parameters
Section titled “Parameters”string
factory
Section titled “factory”BackendFactory<TOptions>
Returns
Section titled “Returns”void
registerLazyBackend()
Section titled “registerLazyBackend()”registerLazyBackend(
name,loader):void
Defined in: registry.ts:158
Register a lazy-loaded backend. The loader is called once on first use, then the resulting factory is cached in the main registry. Use this for backends that have heavy dependencies (peer deps, native modules).
Parameters
Section titled “Parameters”string
loader
Section titled “loader”() => Promise<BackendFactory<unknown>>
Returns
Section titled “Returns”void
resetRegistry()
Section titled “resetRegistry()”resetRegistry():
void
Defined in: registry.ts:77
Reset registry to initial state (for testing)
Returns
Section titled “Returns”void
unregisterBackend()
Section titled “unregisterBackend()”unregisterBackend(
name):boolean
Defined in: registry.ts:58
Unregister a backend (primarily for testing)
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”boolean
zodToJsonSchema()
Section titled “zodToJsonSchema()”zodToJsonSchema(
schema):Record<string,unknown>
Defined in: utils/schema.ts:5
Convert a Zod schema to JSON Schema. Detection order: toJSONSchema() (Zod v4) → jsonSchema() (Zod v3.24+) → _def extraction (Zod v3 legacy).
Parameters
Section titled “Parameters”schema
Section titled “schema”ZodType
Returns
Section titled “Returns”Record<string, unknown>