Core API Overview

The Core API section documents the workflow.* runtime API available directly to business workflows. Its boundary is src/runtime-api.ts in the Core repository: local hosts and CLI inject these methods into globalThis.workflow, so a business workflow does not import them from "steamharness".

Entry boundary

Entrance	Description
workflow.*	Global API used by business workflows, sourced from src/runtime-api.ts in the Core repository.
steamharness package entry	Utility entry used by CLI, Server, tests, and advanced hosts, sourced from src/index.ts in the Core repository.

Runtime API index

API	Description
defineProject	Defines a workflow and its main execution function.
defineEntrypoint	Defines an independently runnable Workflow entrypoint, including its parameters, tools, and registry.
defineExecutor	Defines a Workflow project's entrypoints or a Conversation project's single execution configuration.
parseConversationDefaultInputArgs	Parses the serialized --message, --images, and --files values from the default conversation input.
createInputNode	Creates an input-parsing node.
createFileInputNode	Creates a file-input node and resolves a file parameter reference to a file object.
createUserInputNode	Create a human input node that can be persisted, pausing workflow to waiting_for_input.
createToolApprovalGate	Create tool approval wrappers; combine executor tools registry entries and context.toolPermissions reuse user-input to wait for/resume protocol approval tool calls.
createLLMNode	Create a non-streaming LLM call node.
createLLMStreamNode	Create a streaming LLM call node.
createLLMProviderFromConfig	Create an LLM provider from the current project configuration snapshot.
createLLMProviderRef	Creates a provider reference that can be deferred resolved.
createOutputNode	Creating a synchronous or streaming output node;createOutputItem, createOutputPayload, addOutputItem, and createOutputItemChunk are also described on this page.
createDetailsOutputNode	A convenient output node for creating independent, foldable output items.
createTimerNode / endTimer	Create a business timing node and write a timing card at the explicit end or workflow end.
createQuestionClassifierNode	Create a problem classification node based on LLM.
runNode	Execute the normal node and trigger the node to execute the hook.
runStreamNode	Execute the streaming node, collect chunks, and produce finalize results.
runIf	Execute the if / else-if / else branch and write the branch selection to the run report and Diagram.
runFor	Execute a traceable for loop and let Diagram display the loop body with the loop container.
runWhile	Execute the traceable while loop and let Diagram display the loop body with the loop container.
runProject	Call another workflow in the current context, multiplexing KV, session, provider, token usage, and trace.
Knowledge Documents	Manage project Markdown Knowledge documents through an explicit local or server storage context.
getConfig	Read a native JSON configuration value from the current run snapshot.
getRuntimePlatform / isCli / isDesktop	Determine whether the execution host for the current workflow is CLI or a local desktop host.
getRuntimeLocale	Reads the Simplified Chinese or English language selected by the current host for localized visible output.
getLLMProvider	Resolves LLM provider by context, node name, and provider source.
HarnessError	Standard workflow error type.

Core Run Object

Most API runs around input, context, node, and payload.

Object	Type	Description
input	Input or node Output	The input data for the current workflow or node.
context	RunContext / NodeContext	Contains provider, storage, conversation, files, metadata, hooks, and abortSignal.
payload	RunPayload subtype	Node payload should inherit RunPayload, errCode: 0, errMessage: "" on success.
provider	LLMProviderSource / LLMProvider	The LLM node parses the actual provider by provider source.

NodeContext Core Fields

Field	Type	Description
config	ConfigurationValues	Immutable configuration values for this run.
providers	ProviderRegistry	LLM provider the registry and binding tables.
storage	StorageContext	Explicit local and server locations, each with three-scope kv and persistentValue. The project dataStorage.mode strictly limits accessible locations. Core 0.2 no longer provides top-level context.kv or context.persistentValue.
conversation	ConversationContext	Session state read/write entry. setTitle can safely suggest UI title; other reads and writes will throw errors when the session is not enabled.
tokenUsage	TokenUsageContext	Token-usage reporting context. When disabled, report() is a no-op; when enabled, it writes KV, run reports, and runtime events.
userInput	UserInputContext | undefined	Wait/resume entry for user input and tool approval. Local hosts will be injected according to the host capacity.
files	FileStore | undefined	File reference resolution entry;createFile generates a server-backed run file.
metadata	object | undefined	Current execution meta information, such as workflow, runId, conversationId;Workflow run also contains entrypointId and entrypointTitle.
nodeHooks	NodeExecutionHooks | undefined	Node start, chunk, complete, and other event callbacks.
timers	TimerContext | undefined	Business timing node context;createTimerNode start timing,endTimer end timing.
toolPermissions	ToolPermissionContext | undefined	The tool permission context for the current run. Parses by executor tools default and host override values for createToolApprovalGate() or custom tool call logic to determine enablement, automatic approval, and manual approval.
abortSignal	AbortSignal | undefined	Interrupt execution and provider calls.

Payload Constraint

Field	Description
errCode	Business error code. The success value is 0.
errMessage	The error description. Uniform empty string on success.