Stevora

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)
}
FieldTypeDescription
apiKeystringYour Stevora API key (required)
baseUrlstringBase URL of the Stevora API server
timeoutnumberRequest 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 };
}
FieldTypeDescription
idstringUnique run identifier
workspaceIdstringWorkspace this run belongs to
definitionIdstringID of the workflow definition being executed
statusWorkflowRunStatusCurrent run status
currentStepNamestring | nullName of the step currently executing, or null if not started / completed
inputRecord<string, unknown>Input data provided when the run was created
stateRecord<string, unknown>Accumulated workflow state built up across steps
outputRecord<string, unknown> | nullFinal output after successful completion
errorRecord<string, unknown> | nullError details if the run failed
totalCostCentsnumberTotal LLM cost for this run in cents
startedAtstring | nullISO 8601 timestamp when execution began
completedAtstring | nullISO 8601 timestamp when the run completed successfully
failedAtstring | nullISO 8601 timestamp when the run failed
cancelledAtstring | nullISO 8601 timestamp when the run was cancelled
nextRunAtstring | nullISO 8601 timestamp for a scheduled retry or delayed execution
idempotencyKeystring | nullClient-provided key for deduplication
versionnumberOptimistic concurrency version counter
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last-updated timestamp
stepRunsStepRun[]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';
ValueDescription
PENDINGRun created but not yet picked up by the execution engine
RUNNINGActively executing a step
WAITINGPaused, waiting for an external signal or event
PAUSEDManually paused
COMPLETEDAll steps finished successfully
FAILEDA step failed after exhausting retries
CANCELLEDCancelled 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;
}
FieldTypeDescription
idstringUnique step run identifier
workflowRunIdstringID of the parent workflow run
stepNamestringName of the step as defined in the workflow definition
stepTypeStepTypeThe type of step being executed
statusStepRunStatusCurrent step status
attemptCountnumberNumber of execution attempts so far
maxAttemptsnumberMaximum retry attempts allowed for this step
lastErrorRecord<string, unknown> | nullError from the most recent failed attempt
inputunknownInput data passed to this step
outputunknownOutput data produced by this step
startedAtstring | nullISO 8601 timestamp when execution started
completedAtstring | nullISO 8601 timestamp when the step completed
nextRetryAtstring | nullISO 8601 timestamp for the next scheduled retry
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 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';
ValueDescription
TASKGeneral-purpose computation step
WAITPauses execution for a duration or until a condition is met
CONDITIONBranching logic based on workflow state
EXTERNAL_EVENTWaits for an external signal to resume
LLMMakes an LLM API call (OpenAI, Anthropic)
APPROVALPauses 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;
}
FieldTypeDescription
idstringUnique definition identifier
workspaceIdstring | nullWorkspace this definition belongs to
namestringHuman-readable name
versionstringVersion string (e.g., "1.0.0")
descriptionstring | nullOptional description
stepsJsonunknown[]Array of step configuration objects
isActivebooleanWhether this definition can be used to create new runs
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 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;
}
FieldTypeDescription
idstringUnique approval request identifier
stepRunIdstringID of the step run that created this request
workflowRunIdstringID of the parent workflow run
workspaceIdstringWorkspace this request belongs to
contentunknownThe content to be reviewed (e.g., a draft email, a proposed action)
metadataRecord<string, unknown> | nullAdditional context for the reviewer
decisionstring | nullThe decision: 'approved', 'rejected', or 'edited'. null if pending
decidedBystring | nullIdentifier of who made the decision
editedContentunknownModified content submitted with an 'edited' decision
decidedAtstring | nullISO 8601 timestamp when the decision was made
expiresAtstring | nullISO 8601 timestamp when the approval request expires
createdAtstringISO 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[];
}
FieldTypeDescription
totalCostCentsnumberTotal cost in cents
totalCostDollarsstringTotal cost formatted as a dollar string (e.g., "0.42")
callsLlmCall[]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;
  }[];
}
FieldTypeDescription
totalCostCentsnumberAggregated cost in cents
totalCostDollarsstringAggregated cost formatted as a dollar string
totalCallsnumberTotal number of LLM calls
totalInputTokensnumberTotal input tokens across all calls
totalOutputTokensnumberTotal output tokens across all calls
byModelarrayCost 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[];
}
FieldTypeDescription
idstringUnique call identifier
modelstringModel name (e.g., "gpt-4o", "claude-sonnet-4-20250514")
providerstringProvider name (e.g., "openai", "anthropic")
inputTokensnumber | nullNumber of input tokens consumed
outputTokensnumber | nullNumber of output tokens generated
costCentsnumber | nullCost of this call in cents
durationMsnumber | nullLatency in milliseconds
statusstringCall status (e.g., "success", "error")
attemptnumberWhich retry attempt this was (1-based)
createdAtstringISO 8601 timestamp
toolTracesToolTrace[]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;
}
FieldTypeDescription
idstringUnique trace identifier
toolNamestringName of the tool that was called
inputJsonunknownInput passed to the tool
outputJsonunknownOutput returned by the tool
durationMsnumber | nullExecution time in milliseconds
statusstringExecution status (e.g., "success", "error")
sequencenumberOrder 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;
}
FieldTypeDescription
idstringUnique event identifier
workflowRunIdstringID of the workflow run this event belongs to
stepRunIdstring | nullID of the related step run, if applicable
eventTypestringEvent type (e.g., "workflow.started", "step.completed")
payloadRecord<string, unknown>Event-specific data
createdAtstringISO 8601 timestamp