This document provides a reference for all TypeScript types exported by KODE SDK.
type MessageRole = 'user' | 'assistant' | 'system';
interface Message {
role: MessageRole;
content: ContentBlock[];
metadata?: MessageMetadata;
}
interface MessageMetadata {
content_blocks?: ContentBlock[];
transport?: 'provider' | 'text' | 'omit';
}
Union type for all content block types.
type ContentBlock =
| { type: 'text'; text: string }
| { type: 'image_url'; image_url: { url: string } }
| { type: 'tool_use'; id: string; name: string; input: any; meta?: Record<string, any> }
| { type: 'tool_result'; tool_use_id: string; content: any; is_error?: boolean }
| ReasoningContentBlock
| ImageContentBlock
| AudioContentBlock
| FileContentBlock;
type ReasoningContentBlock = {
type: 'reasoning';
reasoning: string;
meta?: Record<string, any>;
};
type ImageContentBlock = {
type: 'image';
url?: string;
file_id?: string;
base64?: string;
mime_type?: string;
meta?: Record<string, any>;
};
type AudioContentBlock = {
type: 'audio';
url?: string;
file_id?: string;
base64?: string;
mime_type?: string;
meta?: Record<string, any>;
};
type FileContentBlock = {
type: 'file';
url?: string;
file_id?: string;
filename?: string;
base64?: string;
mime_type?: string;
meta?: Record<string, any>;
};
type AgentRuntimeState = 'READY' | 'WORKING' | 'PAUSED';
| State | Description |
|---|
READY | Agent is idle and ready to receive messages |
WORKING | Agent is processing a message |
PAUSED | Agent is paused waiting for permission decision |
type BreakpointState =
| 'READY'
| 'PRE_MODEL'
| 'STREAMING_MODEL'
| 'TOOL_PENDING'
| 'AWAITING_APPROVAL'
| 'PRE_TOOL'
| 'TOOL_EXECUTING'
| 'POST_TOOL';
interface AgentStatus {
agentId: string;
state: AgentRuntimeState;
stepCount: number;
lastSfpIndex: number;
lastBookmark?: Bookmark;
cursor: number;
breakpoint: BreakpointState;
}
interface AgentInfo {
agentId: string;
templateId: string;
createdAt: string;
lineage: string[];
configVersion: string;
messageCount: number;
lastSfpIndex: number;
lastBookmark?: Bookmark;
breakpoint?: BreakpointState;
metadata?: Record<string, any>;
}
type ToolCallState =
| 'PENDING'
| 'APPROVAL_REQUIRED'
| 'APPROVED'
| 'EXECUTING'
| 'COMPLETED'
| 'FAILED'
| 'DENIED'
| 'SEALED';
| State | Description |
|---|
PENDING | Tool call received, not yet processed |
APPROVAL_REQUIRED | Waiting for user approval |
APPROVED | Approved, ready to execute |
EXECUTING | Currently executing |
COMPLETED | Execution completed successfully |
FAILED | Execution failed |
DENIED | User denied the tool call |
SEALED | Auto-sealed during resume |
interface ToolCallRecord {
id: string;
name: string;
input: any;
state: ToolCallState;
approval: ToolCallApproval;
result?: any;
error?: string;
isError?: boolean;
startedAt?: number;
completedAt?: number;
durationMs?: number;
createdAt: number;
updatedAt: number;
auditTrail: ToolCallAuditEntry[];
}
type ToolCallSnapshot = Pick<
ToolCallRecord,
'id' | 'name' | 'state' | 'approval' | 'result' | 'error' | 'isError' | 'durationMs' | 'startedAt' | 'completedAt'
> & {
inputPreview?: any;
auditTrail?: ToolCallAuditEntry[];
};
interface ToolCallApproval {
required: boolean;
decision?: 'allow' | 'deny';
decidedBy?: string;
decidedAt?: number;
note?: string;
meta?: Record<string, any>;
}
interface ToolCallAuditEntry {
state: ToolCallState;
timestamp: number;
note?: string;
}
interface ToolOutcome {
id: string;
name: string;
ok: boolean;
content: any;
durationMs?: number;
}
interface ToolCall {
id: string;
name: string;
args: any;
agentId: string;
}
interface ToolContext {
agentId: string;
sandbox: Sandbox;
agent: any;
services?: Record<string, any>;
signal?: AbortSignal;
emit?: (eventType: string, data?: any) => void;
}
interface Bookmark {
seq: number;
timestamp: number;
}
type AgentChannel = 'progress' | 'control' | 'monitor';
type AgentEvent = ProgressEvent | ControlEvent | MonitorEvent;
interface AgentEventEnvelope<T extends AgentEvent = AgentEvent> {
cursor: number;
bookmark: Bookmark;
event: T;
}
interface Timeline {
cursor: number;
bookmark: Bookmark;
event: AgentEvent;
}
type SnapshotId = string;
interface Snapshot {
id: SnapshotId;
messages: Message[];
lastSfpIndex: number;
lastBookmark: Bookmark;
createdAt: string;
metadata?: Record<string, any>;
}
type HookDecision =
| { decision: 'ask'; meta?: any }
| { decision: 'deny'; reason?: string; toolResult?: any }
| { result: any }
| void;
type PostHookResult =
| void
| { update: Partial<ToolOutcome> }
| { replace: ToolOutcome };
interface PermissionConfig {
mode: PermissionDecisionMode;
requireApprovalTools?: string[];
allowTools?: string[];
denyTools?: string[];
metadata?: Record<string, any>;
}
type PermissionDecisionMode = 'auto' | 'approval' | 'readonly' | (string & {});
| Mode | Description |
|---|
auto | Automatically allow all tool calls |
approval | Require approval for all tool calls |
readonly | Allow read-only tools, require approval for others |
interface SubAgentConfig {
templates?: string[];
depth: number;
inheritConfig?: boolean;
overrides?: {
permission?: PermissionConfig;
todo?: TodoConfig;
};
}
interface TodoConfig {
enabled: boolean;
remindIntervalSteps?: number;
storagePath?: string;
reminderOnStart?: boolean;
}
interface SandboxConfig {
kind: SandboxKind;
workDir?: string;
enforceBoundary?: boolean;
allowPaths?: string[];
watchFiles?: boolean;
[key: string]: any;
}
type SandboxKind = 'local' | 'docker' | 'k8s' | 'remote' | 'vfs' | 'e2b' | 'opensandbox';
type ResumeStrategy = 'crash' | 'manual';
| Strategy | Description |
|---|
crash | Auto-seal incomplete tools and emit agent_resumed event |
manual | Leave incomplete tools as-is for manual handling |
interface ReminderOptions {
skipStandardEnding?: boolean;
priority?: 'low' | 'medium' | 'high';
category?: 'file' | 'todo' | 'security' | 'performance' | 'general';
}
interface E2BSandboxOptions {
apiKey?: string;
template?: string;
timeoutMs?: number;
workDir?: string;
envs?: Record<string, string>;
metadata?: Record<string, string>;
allowInternetAccess?: boolean;
execTimeoutMs?: number;
sandboxId?: string;
domain?: string;
}
interface E2BTemplateConfig {
alias: string;
base: 'python' | 'node' | 'debian' | 'ubuntu' | 'custom';
baseVersion?: string;
dockerfile?: string;
aptPackages?: string[];
pipPackages?: string[];
npmPackages?: string[];
buildCommands?: string[];
workDir?: string;
cpuCount?: number;
memoryMB?: number;
}
type OpenSandboxWatchMode = 'native' | 'polling' | 'off';
interface OpenSandboxOptions {
kind: 'opensandbox';
apiKey?: string;
endpoint?: string;
domain?: string;
protocol?: 'http' | 'https';
sandboxId?: string;
image?: string;
template?: string;
workDir?: string;
timeoutMs?: number;
execTimeoutMs?: number;
requestTimeoutSeconds?: number;
useServerProxy?: boolean;
env?: Record<string, string>;
metadata?: Record<string, string>;
resource?: Record<string, string>;
networkPolicy?: Record<string, any>;
skipHealthCheck?: boolean;
readyTimeoutSeconds?: number;
healthCheckPollingInterval?: number;
watch?: {
mode?: OpenSandboxWatchMode;
pollIntervalMs?: number;
};
lifecycle?: {
disposeAction?: 'close' | 'kill';
};
}