Types
TypeScript type definitions
Types
All types are exported from @stevora/sdk and can be imported directly:
import type {
AgentRuntimeConfig,
WorkflowRun,
StepRun,
WorkflowDefinition,
ApprovalRequest,
CostSummary,
} from '@stevora/sdk';Configuration
AgentRuntimeConfig
Configuration object passed to the AgentRuntime constructor.
interface AgentRuntimeConfig {
apiKey: string;
baseUrl?: string; // default: 'http://localhost:3000'
timeout?: number; // default: 30000 (ms)
}| Field | Type | Description |
|---|---|---|
apiKey | string | Your Stevora API key (required) |
baseUrl | string | Base URL of the Stevora API server |
timeout | number | Request timeout in milliseconds |
Workflow runs
WorkflowRun
Represents a single execution of a workflow definition.
interface WorkflowRun {
id: string;
workspaceId: string;
definitionId: string;
status: WorkflowRunStatus;
currentStepName: string | null;
input: Record<string, unknown>;
state: Record<string, unknown>;
output: Record<string, unknown> | null;
error: Record<string, unknown> | null;
totalCostCents: number;
startedAt: string | null;
completedAt: string | null;
failedAt: string | null;
cancelledAt: string | null;
nextRunAt: string | null;
idempotencyKey: string | null;
version: number;
createdAt: string;
updatedAt: string;
stepRuns?: StepRun[];
definition?: { name: string; version: string };
}| Field | Type | Description |
|---|---|---|
id | string | Unique run identifier |
workspaceId | string | Workspace this run belongs to |
definitionId | string | ID of the workflow definition being executed |
status | WorkflowRunStatus | Current run status |
currentStepName | string | null | Name of the step currently executing, or null if not started / completed |
input | Record<string, unknown> | Input data provided when the run was created |
state | Record<string, unknown> | Accumulated workflow state built up across steps |
output | Record<string, unknown> | null | Final output after successful completion |
error | Record<string, unknown> | null | Error details if the run failed |
totalCostCents | number | Total LLM cost for this run in cents |
startedAt | string | null | ISO 8601 timestamp when execution began |
completedAt | string | null | ISO 8601 timestamp when the run completed successfully |
failedAt | string | null | ISO 8601 timestamp when the run failed |
cancelledAt | string | null | ISO 8601 timestamp when the run was cancelled |
nextRunAt | string | null | ISO 8601 timestamp for a scheduled retry or delayed execution |
idempotencyKey | string | null | Client-provided key for deduplication |
version | number | Optimistic concurrency version counter |
createdAt | string | ISO 8601 creation timestamp |
updatedAt | string | ISO 8601 last-updated timestamp |
stepRuns | StepRun[] | Step runs (included when fetching a single run) |
definition | { name: string; version: string } | Embedded definition summary |
WorkflowRunStatus
Union type of all possible workflow run statuses.
type WorkflowRunStatus =
| 'PENDING'
| 'RUNNING'
| 'WAITING'
| 'PAUSED'
| 'COMPLETED'
| 'FAILED'
| 'CANCELLED';| Value | Description |
|---|---|
PENDING | Run created but not yet picked up by the execution engine |
RUNNING | Actively executing a step |
WAITING | Paused, waiting for an external signal or event |
PAUSED | Manually paused |
COMPLETED | All steps finished successfully |
FAILED | A step failed after exhausting retries |
CANCELLED | Cancelled by a user or API call |
Steps
StepRun
Represents the execution of a single step within a workflow run.
interface StepRun {
id: string;
workflowRunId: string;
stepName: string;
stepType: StepType;
status: StepRunStatus;
attemptCount: number;
maxAttempts: number;
lastError: Record<string, unknown> | null;
input: unknown;
output: unknown;
startedAt: string | null;
completedAt: string | null;
nextRetryAt: string | null;
createdAt: string;
updatedAt: string;
}| Field | Type | Description |
|---|---|---|
id | string | Unique step run identifier |
workflowRunId | string | ID of the parent workflow run |
stepName | string | Name of the step as defined in the workflow definition |
stepType | StepType | The type of step being executed |
status | StepRunStatus | Current step status |
attemptCount | number | Number of execution attempts so far |
maxAttempts | number | Maximum retry attempts allowed for this step |
lastError | Record<string, unknown> | null | Error from the most recent failed attempt |
input | unknown | Input data passed to this step |
output | unknown | Output data produced by this step |
startedAt | string | null | ISO 8601 timestamp when execution started |
completedAt | string | null | ISO 8601 timestamp when the step completed |
nextRetryAt | string | null | ISO 8601 timestamp for the next scheduled retry |
createdAt | string | ISO 8601 creation timestamp |
updatedAt | string | ISO 8601 last-updated timestamp |
StepRunStatus
Union type of all possible step statuses.
type StepRunStatus =
| 'PENDING'
| 'RUNNING'
| 'WAITING'
| 'COMPLETED'
| 'FAILED'
| 'SKIPPED'
| 'CANCELLED';StepType
The kind of step in a workflow definition.
type StepType = 'TASK' | 'WAIT' | 'CONDITION' | 'EXTERNAL_EVENT' | 'LLM' | 'APPROVAL';| Value | Description |
|---|---|
TASK | General-purpose computation step |
WAIT | Pauses execution for a duration or until a condition is met |
CONDITION | Branching logic based on workflow state |
EXTERNAL_EVENT | Waits for an external signal to resume |
LLM | Makes an LLM API call (OpenAI, Anthropic) |
APPROVAL | Pauses for human review and decision |
Definitions
WorkflowDefinition
A reusable workflow template that describes the steps to execute.
interface WorkflowDefinition {
id: string;
workspaceId: string | null;
name: string;
version: string;
description: string | null;
stepsJson: unknown[];
isActive: boolean;
createdAt: string;
updatedAt: string;
}| Field | Type | Description |
|---|---|---|
id | string | Unique definition identifier |
workspaceId | string | null | Workspace this definition belongs to |
name | string | Human-readable name |
version | string | Version string (e.g., "1.0.0") |
description | string | null | Optional description |
stepsJson | unknown[] | Array of step configuration objects |
isActive | boolean | Whether this definition can be used to create new runs |
createdAt | string | ISO 8601 creation timestamp |
updatedAt | string | ISO 8601 last-updated timestamp |
CreateDefinitionInput
Input for creating a new workflow definition.
interface CreateDefinitionInput {
name: string;
version: string;
description?: string;
steps: Record<string, unknown>[];
}Approvals
ApprovalRequest
A human-in-the-loop approval request generated by an APPROVAL step.
interface ApprovalRequest {
id: string;
stepRunId: string;
workflowRunId: string;
workspaceId: string;
content: unknown;
metadata: Record<string, unknown> | null;
decision: string | null;
decidedBy: string | null;
editedContent: unknown;
decidedAt: string | null;
expiresAt: string | null;
createdAt: string;
}| Field | Type | Description |
|---|---|---|
id | string | Unique approval request identifier |
stepRunId | string | ID of the step run that created this request |
workflowRunId | string | ID of the parent workflow run |
workspaceId | string | Workspace this request belongs to |
content | unknown | The content to be reviewed (e.g., a draft email, a proposed action) |
metadata | Record<string, unknown> | null | Additional context for the reviewer |
decision | string | null | The decision: 'approved', 'rejected', or 'edited'. null if pending |
decidedBy | string | null | Identifier of who made the decision |
editedContent | unknown | Modified content submitted with an 'edited' decision |
decidedAt | string | null | ISO 8601 timestamp when the decision was made |
expiresAt | string | null | ISO 8601 timestamp when the approval request expires |
createdAt | string | ISO 8601 creation timestamp |
DecideApprovalInput
Input for submitting a decision on an approval request.
interface DecideApprovalInput {
decision: 'approved' | 'rejected' | 'edited';
editedContent?: Record<string, unknown>;
decidedBy?: string;
}Costs and tracing
RunCost
Cost breakdown for a single workflow run.
interface RunCost {
totalCostCents: number;
totalCostDollars: string;
calls: LlmCall[];
}| Field | Type | Description |
|---|---|---|
totalCostCents | number | Total cost in cents |
totalCostDollars | string | Total cost formatted as a dollar string (e.g., "0.42") |
calls | LlmCall[] | Individual LLM calls that contributed to the cost |
CostSummary
Aggregated cost data across the workspace.
interface CostSummary {
totalCostCents: number;
totalCostDollars: string;
totalCalls: number;
totalInputTokens: number;
totalOutputTokens: number;
byModel: {
model: string;
calls: number;
costCents: number;
inputTokens: number;
outputTokens: number;
}[];
}| Field | Type | Description |
|---|---|---|
totalCostCents | number | Aggregated cost in cents |
totalCostDollars | string | Aggregated cost formatted as a dollar string |
totalCalls | number | Total number of LLM calls |
totalInputTokens | number | Total input tokens across all calls |
totalOutputTokens | number | Total output tokens across all calls |
byModel | array | Cost breakdown grouped by model |
LlmCall
A single LLM API call trace.
interface LlmCall {
id: string;
model: string;
provider: string;
inputTokens: number | null;
outputTokens: number | null;
costCents: number | null;
durationMs: number | null;
status: string;
attempt: number;
createdAt: string;
toolTraces?: ToolTrace[];
}| Field | Type | Description |
|---|---|---|
id | string | Unique call identifier |
model | string | Model name (e.g., "gpt-4o", "claude-sonnet-4-20250514") |
provider | string | Provider name (e.g., "openai", "anthropic") |
inputTokens | number | null | Number of input tokens consumed |
outputTokens | number | null | Number of output tokens generated |
costCents | number | null | Cost of this call in cents |
durationMs | number | null | Latency in milliseconds |
status | string | Call status (e.g., "success", "error") |
attempt | number | Which retry attempt this was (1-based) |
createdAt | string | ISO 8601 timestamp |
toolTraces | ToolTrace[] | Tool calls made during this LLM call |
ToolTrace
A tool call executed during an LLM call.
interface ToolTrace {
id: string;
toolName: string;
inputJson: unknown;
outputJson: unknown;
durationMs: number | null;
status: string;
sequence: number;
}| Field | Type | Description |
|---|---|---|
id | string | Unique trace identifier |
toolName | string | Name of the tool that was called |
inputJson | unknown | Input passed to the tool |
outputJson | unknown | Output returned by the tool |
durationMs | number | null | Execution time in milliseconds |
status | string | Execution status (e.g., "success", "error") |
sequence | number | Order of execution within the LLM call (0-based) |
Pagination and API responses
PaginationMeta
Pagination metadata returned by list endpoints.
interface PaginationMeta {
page: number;
pageSize: number;
total: number;
totalPages: number;
}ApiResponse<T>
Raw API response envelope. You typically do not need to use this directly as the SDK unwraps it for you.
interface ApiResponse<T> {
success: boolean;
data?: T;
error?: { code: string; message: string; details?: unknown };
meta?: PaginationMeta;
}Input types
CreateRunInput
interface CreateRunInput {
definitionId: string;
input?: Record<string, unknown>;
idempotencyKey?: string;
}ListRunsParams
interface ListRunsParams {
page?: number;
pageSize?: number;
status?: WorkflowRunStatus;
definitionId?: string;
}ResumeRunInput
interface ResumeRunInput {
signalType: string;
payload?: Record<string, unknown>;
}Events
WorkflowEvent
A lifecycle event recorded during workflow execution.
interface WorkflowEvent {
id: string;
workflowRunId: string;
stepRunId: string | null;
eventType: string;
payload: Record<string, unknown>;
createdAt: string;
}| Field | Type | Description |
|---|---|---|
id | string | Unique event identifier |
workflowRunId | string | ID of the workflow run this event belongs to |
stepRunId | string | null | ID of the related step run, if applicable |
eventType | string | Event type (e.g., "workflow.started", "step.completed") |
payload | Record<string, unknown> | Event-specific data |
createdAt | string | ISO 8601 timestamp |