sse-events-contract

Workspace API

---

Workspace API / types/sse-events-contract

types/sse-events-contract

Classes

SSEEventStreamValidator

Defined in: types/sse-events-contract.ts:411

Validates an event stream follows the contract

Constructors

Constructor

new SSEEventStreamValidator(): SSEEventStreamValidator

Returns

SSEEventStreamValidator

Methods

validateNext()

validateNext(event): SSEValidationResult

Defined in: types/sse-events-contract.ts:419

Validate the next event in the stream

Parameters

event

SkillSSEEvent

Returns

SSEValidationResult

isComplete()

isComplete(): SSEValidationResult

Defined in: types/sse-events-contract.ts:455

Check if the stream is complete and valid

Returns

SSEValidationResult

reset()

reset(): void

Defined in: types/sse-events-contract.ts:472

Reset the validator for a new stream

Returns

void

Interfaces

SSEEvent

Defined in: types/sse-events-contract.ts:30

Base SSE event structure

Type Parameters

T

T extends SSEEventType = SSEEventType

D

D = unknown

Properties

type

type: T

Defined in: types/sse-events-contract.ts:31

data

data: D

Defined in: types/sse-events-contract.ts:32

---

MetadataEventData

Defined in: types/sse-events-contract.ts:42

Metadata event - REQUIRED, must be first event

Properties

traceId

traceId: string

Defined in: types/sse-events-contract.ts:44

OpenTelemetry trace ID

runId

runId: string

Defined in: types/sse-events-contract.ts:46

Workflow run ID (UUID) - canonical identifier for API calls, database queries

voltAgentRunId?

optional voltAgentRunId: string

Defined in: types/sse-events-contract.ts:48

VoltAgent's native TEXT ID (for VoltOps trace lookup) - optional, only present for VoltAgent executions

voltAgentRunUuid?

optional voltAgentRunUuid: string

Defined in: types/sse-events-contract.ts:50

VoltAgent run UUID - internal identifier for FK references - optional, only present for VoltAgent executions

conversationId?

optional conversationId: string

Defined in: types/sse-events-contract.ts:52

Conversation ID - optional

skillId

skillId: string

Defined in: types/sse-events-contract.ts:54

Skill ID

skillVersionId

skillVersionId: string

Defined in: types/sse-events-contract.ts:56

Skill version ID

manifestHash?

optional manifestHash: string

Defined in: types/sse-events-contract.ts:58

Workflow manifest hash (optional, for caching)

approvedAt

approvedAt: string

Defined in: types/sse-events-contract.ts:60

Timestamp when execution was approved

---

PlanEventData

Defined in: types/sse-events-contract.ts:66

Plan event - optional, shows execution plan

Properties

steps

steps: PlanStep[]

Defined in: types/sse-events-contract.ts:67

---

PlanStep

Defined in: types/sse-events-contract.ts:70

Properties

stepIndex

stepIndex: number

Defined in: types/sse-events-contract.ts:71

name

name: string

Defined in: types/sse-events-contract.ts:72

type

type: "tool" | "llm" | "conditional" | "loop"

Defined in: types/sse-events-contract.ts:73

---

StepEventData

Defined in: types/sse-events-contract.ts:79

Step event - execution step progress

Properties

stepIndex

stepIndex: number

Defined in: types/sse-events-contract.ts:80

status

status: "succeeded" | "failed" | "pending" | "running" | "skipped"

Defined in: types/sse-events-contract.ts:81

output?

optional output: unknown

Defined in: types/sse-events-contract.ts:82

startedAt?

optional startedAt: string

Defined in: types/sse-events-contract.ts:83

endedAt?

optional endedAt: string

Defined in: types/sse-events-contract.ts:84

---

ToolCallEventData

Defined in: types/sse-events-contract.ts:90

Tool call event - tool invocation start

Properties

stepIndex?

optional stepIndex: number

Defined in: types/sse-events-contract.ts:91

tool

tool: string

Defined in: types/sse-events-contract.ts:92

args

args: Record<string, unknown>

Defined in: types/sse-events-contract.ts:93

---

ToolResultEventData

Defined in: types/sse-events-contract.ts:99

Tool result event - tool invocation result

Properties

stepIndex?

optional stepIndex: number

Defined in: types/sse-events-contract.ts:100

tool

tool: string

Defined in: types/sse-events-contract.ts:101

result

result: unknown

Defined in: types/sse-events-contract.ts:102

durationMs?

optional durationMs: number

Defined in: types/sse-events-contract.ts:103

---

TextEventData

Defined in: types/sse-events-contract.ts:109

Text event - streaming text output

Properties

text

text: string

Defined in: types/sse-events-contract.ts:110

---

CompleteEventData

Defined in: types/sse-events-contract.ts:116

Complete event - REQUIRED terminal event on success

Properties

status

status: "succeeded"

Defined in: types/sse-events-contract.ts:117

output

output: unknown

Defined in: types/sse-events-contract.ts:118

totalDurationMs?

optional totalDurationMs: number

Defined in: types/sse-events-contract.ts:119

totalTokens?

optional totalTokens: number

Defined in: types/sse-events-contract.ts:120

---

ErrorEventData

Defined in: types/sse-events-contract.ts:130

Error event - REQUIRED terminal event on failure

Note: Both stepIndex (camelCase) and step_index (snake_case) are supported for backward compatibility. New code should use step_index to match the WorkflowError interface in skills.ts.

Properties

code

code: string

Defined in: types/sse-events-contract.ts:131

message

message: string

Defined in: types/sse-events-contract.ts:132

stepIndex?

optional stepIndex: number

Defined in: types/sse-events-contract.ts:134

Deprecated

Use step_index instead

step_index?

optional step_index: number

Defined in: types/sse-events-contract.ts:136

Step index where the error occurred (preferred)

details?

optional details: Record<string, unknown>

Defined in: types/sse-events-contract.ts:137

---

SSEValidationResult

Defined in: types/sse-events-contract.ts:229

Validation result for SSE events

Properties

valid

valid: boolean

Defined in: types/sse-events-contract.ts:230

errors

errors: string[]

Defined in: types/sse-events-contract.ts:231

Type Aliases

SSEEventType

SSEEventType = "metadata" | "plan" | "step" | "tool_call" | "tool_result" | "text" | "complete" | "error"

Defined in: types/sse-events-contract.ts:17

All possible SSE event types

---

MetadataEvent

MetadataEvent = SSEEvent<"metadata", MetadataEventData>

Defined in: types/sse-events-contract.ts:144

---

PlanEvent

PlanEvent = SSEEvent<"plan", PlanEventData>

Defined in: types/sse-events-contract.ts:145

---

StepEvent

StepEvent = SSEEvent<"step", StepEventData>

Defined in: types/sse-events-contract.ts:146

---

ToolCallEvent

ToolCallEvent = SSEEvent<"tool_call", ToolCallEventData>

Defined in: types/sse-events-contract.ts:147

---

ToolResultEvent

ToolResultEvent = SSEEvent<"tool_result", ToolResultEventData>

Defined in: types/sse-events-contract.ts:148

---

TextEvent

TextEvent = SSEEvent<"text", TextEventData>

Defined in: types/sse-events-contract.ts:149

---

CompleteEvent

CompleteEvent = SSEEvent<"complete", CompleteEventData>

Defined in: types/sse-events-contract.ts:150

---

ErrorEvent

ErrorEvent = SSEEvent<"error", ErrorEventData>

Defined in: types/sse-events-contract.ts:151

---

SkillSSEEvent

SkillSSEEvent = MetadataEvent | PlanEvent | StepEvent | ToolCallEvent | ToolResultEvent | TextEvent | CompleteEvent | ErrorEvent

Defined in: types/sse-events-contract.ts:156

Union of all SSE event types

---

SSEErrorCode

SSEErrorCode = typeof SSE_ERROR_CODES[keyof typeof SSE_ERROR_CODES]

Defined in: types/sse-events-contract.ts:224

Variables

SSE_ERROR_CODES

const SSE_ERROR_CODES: object

Defined in: types/sse-events-contract.ts:179

Standard error codes for skill execution

This is an exhaustive list of all WorkflowErrorCode values that can appear in SSE events. It should be kept in sync with WorkflowErrorCode in skills.ts.

All codes from WorkflowErrorCode are valid SSE error codes, and this constant serves as the authoritative reference for validation and documentation.

Type Declaration

INVALID_INPUT_SCHEMA

readonly INVALID_INPUT_SCHEMA: "INVALID_INPUT_SCHEMA" = 'INVALID_INPUT_SCHEMA'

INVALID_STEP_OUTPUT_SCHEMA

readonly INVALID_STEP_OUTPUT_SCHEMA: "INVALID_STEP_OUTPUT_SCHEMA" = 'INVALID_STEP_OUTPUT_SCHEMA'

TOOL_DISABLED

readonly TOOL_DISABLED: "TOOL_DISABLED" = 'TOOL_DISABLED'

TOOL_NOT_ALLOWED

readonly TOOL_NOT_ALLOWED: "TOOL_NOT_ALLOWED" = 'TOOL_NOT_ALLOWED'

TOOL_NOT_FOUND

readonly TOOL_NOT_FOUND: "TOOL_NOT_FOUND" = 'TOOL_NOT_FOUND'

TOOL_ARGUMENTS_INVALID

readonly TOOL_ARGUMENTS_INVALID: "TOOL_ARGUMENTS_INVALID" = 'TOOL_ARGUMENTS_INVALID'

TOOL_EXECUTION_NOT_SUPPORTED

readonly TOOL_EXECUTION_NOT_SUPPORTED: "TOOL_EXECUTION_NOT_SUPPORTED" = 'TOOL_EXECUTION_NOT_SUPPORTED'

POLICY_VIOLATION

readonly POLICY_VIOLATION: "POLICY_VIOLATION" = 'POLICY_VIOLATION'

TIMEOUT

readonly TIMEOUT: "TIMEOUT" = 'TIMEOUT'

RETRY_EXHAUSTED

readonly RETRY_EXHAUSTED: "RETRY_EXHAUSTED" = 'RETRY_EXHAUSTED'

LLM_ERROR

readonly LLM_ERROR: "LLM_ERROR" = 'LLM_ERROR'

LLM_OUTPUT_PARSE_FAILED

readonly LLM_OUTPUT_PARSE_FAILED: "LLM_OUTPUT_PARSE_FAILED" = 'LLM_OUTPUT_PARSE_FAILED'

EXECUTION_FAILED

readonly EXECUTION_FAILED: "EXECUTION_FAILED" = 'EXECUTION_FAILED'

EXECUTION_CANCELLED

readonly EXECUTION_CANCELLED: "EXECUTION_CANCELLED" = 'EXECUTION_CANCELLED'

Execution was cancelled by user or system

PERMISSION_DENIED

readonly PERMISSION_DENIED: "PERMISSION_DENIED" = 'PERMISSION_DENIED'

RATE_LIMIT_EXCEEDED

readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED" = 'RATE_LIMIT_EXCEEDED'

INTERNAL_ERROR

readonly INTERNAL_ERROR: "INTERNAL_ERROR" = 'INTERNAL_ERROR'

IDEMPOTENCY_HIT

readonly IDEMPOTENCY_HIT: "IDEMPOTENCY_HIT" = 'IDEMPOTENCY_HIT'

Previous execution exists for this idempotency key (may have succeeded or failed)

EXECUTION_IN_PROGRESS

readonly EXECUTION_IN_PROGRESS: "EXECUTION_IN_PROGRESS" = 'EXECUTION_IN_PROGRESS'

Execution already in progress for this idempotency key

EXECUTION_SUSPENDED

readonly EXECUTION_SUSPENDED: "EXECUTION_SUSPENDED" = 'EXECUTION_SUSPENDED'

Execution is suspended awaiting human review

SKILL_NOT_FOUND

readonly SKILL_NOT_FOUND: "SKILL_NOT_FOUND" = 'SKILL_NOT_FOUND'

SKILL_VERSION_NOT_FOUND

readonly SKILL_VERSION_NOT_FOUND: "SKILL_VERSION_NOT_FOUND" = 'SKILL_VERSION_NOT_FOUND'

DOMAIN_NOT_FOUND

readonly DOMAIN_NOT_FOUND: "DOMAIN_NOT_FOUND" = 'DOMAIN_NOT_FOUND'

Functions

validateMetadataEvent()

validateMetadataEvent(data): SSEValidationResult

Defined in: types/sse-events-contract.ts:237

Validate a metadata event

Parameters

data

unknown

Returns

SSEValidationResult

---

validateCompleteEvent()

validateCompleteEvent(data): SSEValidationResult

Defined in: types/sse-events-contract.ts:289

Validate a complete event

Parameters

data

unknown

Returns

SSEValidationResult

---

validateErrorEvent()

validateErrorEvent(data): SSEValidationResult

Defined in: types/sse-events-contract.ts:321

Validate an error event

Parameters

data

unknown

Returns

SSEValidationResult

---

validateSSEEvent()

validateSSEEvent(event): SSEValidationResult

Defined in: types/sse-events-contract.ts:357

Validate any SSE event

Parameters

event

unknown

Returns

SSEValidationResult

---

createMetadataEvent()

createMetadataEvent(data): MetadataEvent

Defined in: types/sse-events-contract.ts:486

Create a metadata event

Parameters

data

MetadataEventData

Returns

MetadataEvent

---

createTextEvent()

createTextEvent(text): TextEvent

Defined in: types/sse-events-contract.ts:494

Create a text event

Parameters

text

string

Returns

TextEvent

---

createCompleteEvent()

createCompleteEvent(output, options?): CompleteEvent

Defined in: types/sse-events-contract.ts:502

Create a complete event

Parameters

output

unknown

options?

totalDurationMs?

number

totalTokens?

number

Returns

CompleteEvent

---

createErrorEvent()

createErrorEvent(code, message, options?): ErrorEvent

Defined in: types/sse-events-contract.ts:517

Create an error event

Parameters

code

SSEErrorCode

message

string

options?

stepIndex?

number

details?

Record<string, unknown>

Returns

ErrorEvent

---

serializeSSEEvent()

serializeSSEEvent(event): string

Defined in: types/sse-events-contract.ts:533

Serialize an SSE event for transmission

Parameters

event

SkillSSEEvent

Returns

string

---

parseSSEEvent()

parseSSEEvent(dataLine): SkillSSEEvent | null

Defined in: types/sse-events-contract.ts:540

Parse an SSE event from a data line

Parameters

dataLine

string

Returns

SkillSSEEvent | null