Ripline API Reference v0.1.0

---

Ripline API Reference / types

types

Type Aliases

AgentDefinition

AgentDefinition = BuiltinAgentDefinition | ExternalAgentDefinition

Defined in: types.ts:140

---

AgentNode

AgentNode = NodeBase & object

Defined in: types.ts:197

Type Declaration

agentId?

optional agentId: string

channel?

optional channel: string

container?

optional container: NodeContainerConfig

Container execution mode for this node. "isolated" = fresh container per node using the configured build image. Object form = custom image/env/volumes. When unset, inherits from run-level container config (if any).

cwd?

optional cwd: string

Working directory for Claude Code (supports template interpolation).

dangerouslySkipPermissions?

optional dangerouslySkipPermissions: boolean

When runner is claude-code and global bypass is allowed: set true to use bypass for this node only. Omit or false = dontAsk for this node. Safer to enable per-node than globally.

deliver?

optional deliver: boolean

mcpServers?

optional mcpServers: Record<string, McpServerConfig>

Node-level explicit MCP server configs (merged on top of agent-definition mcpServers; node wins).

mode?

optional mode: "plan" | "execute"

For runner: claude-code — "plan" = read-only; "execute" = full access. Default when runner is claude-code: "execute".

model?

optional model: string

When runner is claude-code: model to use (e.g. claude-sonnet-4-6, claude-opus-4-6). Omit to use config or CLI default.

prompt

prompt: string

resetSession?

optional resetSession: boolean

When true or omitted, use a new session per run (context isolation). When false, use run-level sessionId for continuity.

runner?

optional runner: string

Runner type for this node (e.g. "claude-code"). When set, the matching runner must be provided in runner options.

sessionId?

optional sessionId: string

skills?

optional skills: string[]

Node-level skill names to attach from the registry (merged with agent-definition skills; node wins).

thinking?

optional thinking: "off" | "minimal" | "low" | "medium" | "high"

timeoutSeconds?

optional timeoutSeconds: number

type

type: "agent"

---

BackgroundQueueConfig

BackgroundQueueConfig = object

Defined in: types.ts:433

Configuration for the background queue.

Properties

enabled

enabled: boolean

Defined in: types.ts:434

maxRetries

maxRetries: number

Defined in: types.ts:435

---

BackgroundQueueItem

BackgroundQueueItem = object

Defined in: types.ts:417

An item queued for background processing.

Properties

createdAt

createdAt: number

Defined in: types.ts:424

id

id: string

Defined in: types.ts:418

inputs

inputs: Record<string, unknown>

Defined in: types.ts:420

manualBoost

manualBoost: number

Defined in: types.ts:423

maxRetries

maxRetries: number

Defined in: types.ts:428

needsReview

needsReview: boolean

Defined in: types.ts:429

pipeline

pipeline: string

Defined in: types.ts:419

priority

priority: number

Defined in: types.ts:421

retries

retries: number

Defined in: types.ts:427

runId?

optional runId: string

Defined in: types.ts:426

severityWeight

severityWeight: number

Defined in: types.ts:422

status

status: "pending" | "running" | "completed" | "errored" | "failed"

Defined in: types.ts:425

---

BuiltinAgentDefinition

BuiltinAgentDefinition = object

Defined in: types.ts:116

Properties

cwd?

optional cwd: string

Defined in: types.ts:124

dangerouslySkipPermissions?

optional dangerouslySkipPermissions: boolean

Defined in: types.ts:125

mcpServers?

optional mcpServers: Record<string, McpServerConfig>

Defined in: types.ts:129

Explicit MCP server configs. Merged with resolved skills; explicit entries win.

mode?

optional mode: "plan" | "execute"

Defined in: types.ts:121

model?

optional model: string

Defined in: types.ts:120

runner

runner: BuiltinAgentRunner

Defined in: types.ts:117

skills?

optional skills: string[]

Defined in: types.ts:127

Named skills to attach from the skills registry (resolved to mcpServers at run time).

skillsFile?

optional skillsFile: string

Defined in: types.ts:131

Path to a markdown file describing available skills; injected into agent context. Relative to effective cwd, or absolute.

systemPrompt?

optional systemPrompt: string

Defined in: types.ts:119

Prepended to the node's prompt at run time.

thinking?

optional thinking: "off" | "minimal" | "low" | "medium" | "high"

Defined in: types.ts:122

timeoutSeconds?

optional timeoutSeconds: number

Defined in: types.ts:123

---

BuiltinAgentRunner

BuiltinAgentRunner = "claude-code" | "codex"

Defined in: types.ts:114

---

CheckpointNode

CheckpointNode = NodeBase & object

Defined in: types.ts:268

Type Declaration

reason?

optional reason: string

resumeKey?

optional resumeKey: string

type

type: "checkpoint"

---

CollectChildrenNode

CollectChildrenNode = NodeBase & object

Defined in: types.ts:300

Type Declaration

type

type: "collect_children"

---

ContainerBuildUserConfig

ContainerBuildUserConfig = object

Defined in: types.ts:42

User-level container build configuration (from ~/.ripline/config.json).

Properties

buildImage?

optional buildImage: string

Defined in: types.ts:50

Docker image to use for builds. Default "ripline-builder:latest".

containerTimeoutMs?

optional containerTimeoutMs: number

Defined in: types.ts:56

Timeout in ms for the container. Default 600_000 (10 min).

enabled?

optional enabled: boolean

Defined in: types.ts:44

Enable container-based builds. Default false.

repoPath?

optional repoPath: string

Defined in: types.ts:46

Absolute path to the host git repository (auto-detected from cwd if omitted).

secretsMountPath?

optional secretsMountPath: string

Defined in: types.ts:54

Path on host to mount as secrets inside the container.

targetBranch?

optional targetBranch: string

Defined in: types.ts:48

Target branch to merge into (e.g. "main"). Default "main".

testCommand?

optional testCommand: string

Defined in: types.ts:52

Shell command to run the project test suite during promote. Default "npm test".

---

ContainerResourceLimits

ContainerResourceLimits = object

Defined in: types.ts:439

Resource limits applied to each build container.

Properties

cpus?

optional cpus: string

Defined in: types.ts:441

CPU limit (e.g. "1.5" for 1.5 cores, "0.5" for half a core). Maps to Docker --cpus.

memory?

optional memory: string

Defined in: types.ts:443

Memory limit (e.g. "512m", "2g"). Maps to Docker --memory.

---

EnqueueNode

EnqueueNode = NodeBase & object

Defined in: types.ts:290

Type Declaration

mode?

optional mode: "batch" | "per-item"

batch = one child run with inputs.tasks = full list; per-item = one run per task.

pipelineId

pipelineId: string

Child pipeline to run for each task (or once with full list in batch mode).

tasksSource?

optional tasksSource: string

Artifact key containing tasks array (default "tasks").

type

type: "enqueue"

---

ErrorCategory

ErrorCategory = "transient" | "permanent" | "unknown"

Defined in: types.ts:112

---

ExternalAgentDefinition

ExternalAgentDefinition = object

Defined in: types.ts:135

An agent with no special Ripline config (e.g. an external agent whose definition lives outside Ripline).

Properties

runner?

optional runner: string

Defined in: types.ts:137

Arbitrary runner type string for custom / third-party runners.

---

InputNode

InputNode = NodeBase & object

Defined in: types.ts:186

Type Declaration

path?

optional path: string

type

type: "input"

---

LiteralNode

LiteralNode = NodeBase & object

Defined in: types.ts:181

Type Declaration

type

type: "data"

value

value: unknown

---

LoopBody

LoopBody = object

Defined in: types.ts:254

Properties

edges?

optional edges: PipelineEdge[]

Defined in: types.ts:258

entry?

optional entry: string[]

Defined in: types.ts:256

nodes?

optional nodes: PipelineNode[]

Defined in: types.ts:257

pipelineId?

optional pipelineId: string

Defined in: types.ts:255

---

LoopNode

LoopNode = NodeBase & object

Defined in: types.ts:238

Type Declaration

body

body: LoopBody

collection

collection: string

dependsOnField?

optional dependsOnField: string

Field name on each item that holds an array of dependency item IDs. Default 'dependsOn'.

exitCondition?

optional exitCondition: string

indexVar?

optional indexVar: string

itemVar?

optional itemVar: string

maxConcurrency?

optional maxConcurrency: number

Maximum number of items to execute concurrently in parallel mode.

maxIterations?

optional maxIterations: number

mode?

optional mode: "sequential" | "parallel"

Execution mode: 'sequential' processes items one-by-one; 'parallel' uses dependency waves. Default 'sequential'.

type

type: "loop"

---

McpHttpServerConfig

McpHttpServerConfig = object

Defined in: types.ts:16

Properties

headers?

optional headers: Record<string, string>

Defined in: types.ts:19

type

type: "http"

Defined in: types.ts:17

url

url: string

Defined in: types.ts:18

---

McpServerConfig

McpServerConfig = McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig

Defined in: types.ts:23

Serializable MCP server config (no live SDK instances).

---

McpSSEServerConfig

McpSSEServerConfig = object

Defined in: types.ts:10

Properties

headers?

optional headers: Record<string, string>

Defined in: types.ts:13

type

type: "sse"

Defined in: types.ts:11

url

url: string

Defined in: types.ts:12

---

McpStdioServerConfig

McpStdioServerConfig = object

Defined in: types.ts:3

Properties

args?

optional args: string[]

Defined in: types.ts:6

command

command: string

Defined in: types.ts:5

env?

optional env: Record<string, string>

Defined in: types.ts:7

type?

optional type: "stdio"

Defined in: types.ts:4

---

NodeBase

NodeBase = object

Defined in: types.ts:171

Properties

contracts?

optional contracts: NodeContract

Defined in: types.ts:175

description?

optional description: string

Defined in: types.ts:174

id

id: string

Defined in: types.ts:172

metadata?

optional metadata: Record<string, unknown>

Defined in: types.ts:176

name?

optional name: string

Defined in: types.ts:173

retry?

optional retry: NodeRetryConfig

Defined in: types.ts:178

Retry transient failures: max attempts and optional delay between attempts.

---

NodeContainerConfig

NodeContainerConfig = "isolated" | { env?: Record<string, string>; image?: string; resourceLimits?: ContainerResourceLimits; timeoutMs?: number; volumes?: Record<string, string>; workdir?: string; }

Defined in: types.ts:154

Container configuration for node-level or run-level container execution.

"isolated" is shorthand for a fresh container per-node using the default build image. An object form allows full control over image, env, volumes, and resource limits.

Run-level: set container on PipelineDefinition — a single container is started at run begin and shared across all nodes that opt in, allowing file/artifact hand-off.

Node-level: set container: "isolated" on an individual node — that node gets its own fresh container, independent of any run-level container.

Type Declaration

"isolated"

{ env?: Record<string, string>; image?: string; resourceLimits?: ContainerResourceLimits; timeoutMs?: number; volumes?: Record<string, string>; workdir?: string; }

env?

optional env: Record<string, string>

Extra environment variables to inject (merged with run env).

image?

optional image: string

Docker image to use. Defaults to the build image configured in containerBuild.

resourceLimits?

optional resourceLimits: ContainerResourceLimits

Resource limits (CPU, memory).

timeoutMs?

optional timeoutMs: number

Timeout in milliseconds. Default 600_000 (10 min).

volumes?

optional volumes: Record<string, string>

Volume mounts as host:container pairs.

workdir?

optional workdir: string

Working directory inside the container. Default "/workspace".

---

NodeContract

NodeContract = object

Defined in: types.ts:94

Properties

input?

optional input: JSONSchema7

Defined in: types.ts:95

output?

optional output: JSONSchema7

Defined in: types.ts:96

---

NodeRetryConfig

NodeRetryConfig = object

Defined in: types.ts:99

Properties

delayMs?

optional delayMs: number

Defined in: types.ts:101

maxAttempts

maxAttempts: number

Defined in: types.ts:100

---

OutputNode

OutputNode = NodeBase & object

Defined in: types.ts:274

Type Declaration

merge?

optional merge: boolean

path?

optional path: string

source?

optional source: string

Artifact key to write (default: this node's id).

type

type: "output"

---

PipelineContracts

PipelineContracts = object

Defined in: types.ts:349

Properties

input?

optional input: JSONSchema7

Defined in: types.ts:350

output?

optional output: JSONSchema7

Defined in: types.ts:351

---

PipelineDefinition

PipelineDefinition = object

Defined in: types.ts:354

Properties

container?

optional container: NodeContainerConfig

Defined in: types.ts:382

Run-level container configuration.

When set, a single container is started at the beginning of the run and shared across all nodes that participate in container execution (agent and shell nodes). This allows steps to hand off files and artifacts through the shared container filesystem.

Individual nodes can still override with container: "isolated" to get a fresh container for that specific node.

Can also be supplied via run inputs as _container (object form only) to allow per-run container overrides without modifying the pipeline YAML.

contracts?

optional contracts: PipelineContracts

Defined in: types.ts:362

description?

optional description: string

Defined in: types.ts:358

edges

edges: PipelineEdge[]

Defined in: types.ts:361

entry

entry: string[]

Defined in: types.ts:359

id

id: string

Defined in: types.ts:355

metadata?

optional metadata: Record<string, unknown>

Defined in: types.ts:364

name?

optional name: string

Defined in: types.ts:357

nodes

nodes: PipelineNode[]

Defined in: types.ts:360

queue?

optional queue: string

Defined in: types.ts:366

Named queue this pipeline belongs to. Defaults to "default".

retry?

optional retry: RetryPolicy

Defined in: types.ts:368

Pipeline-level retry policy for automatic run resumption on failure.

tags?

optional tags: string[]

Defined in: types.ts:363

version?

optional version: string | number

Defined in: types.ts:356

---

PipelineEdge

PipelineEdge = object

Defined in: types.ts:340

Properties

default?

optional default: boolean

Defined in: types.ts:345

from

from: object

Defined in: types.ts:342

node

node: string

port?

optional port: string

id?

optional id: string

Defined in: types.ts:341

on_error?

optional on_error: boolean

Defined in: types.ts:346

to

to: object

Defined in: types.ts:343

node

node: string

port?

optional port: string

when?

optional when: string

Defined in: types.ts:344

---

PipelineNode

PipelineNode = LiteralNode | InputNode | TransformNode | AgentNode | RunPipelineNode | LoopNode | SwitchNode | CheckpointNode | OutputNode | EnqueueNode | CollectChildrenNode | ShellNode

Defined in: types.ts:326

---

PipelinePluginConfig

PipelinePluginConfig = object

Defined in: types.ts:80

Properties

authToken?

optional authToken: string

Defined in: types.ts:85

httpPath?

optional httpPath: string

Defined in: types.ts:83

httpPort?

optional httpPort: number

Defined in: types.ts:84

maxConcurrency?

optional maxConcurrency: number

Defined in: types.ts:82

pipelinesDir

pipelinesDir: string

Defined in: types.ts:81

queueFilePath?

optional queueFilePath: string

Defined in: types.ts:89

File path for the background queue YAML store.

queues?

optional queues: Record<string, QueueConfig>

Defined in: types.ts:91

Per-queue configuration (concurrency + resource limits). e.g. { build: { concurrency: 3, resourceLimits: { cpus: "1", memory: "2g" } } }

runsDir?

optional runsDir: string

Defined in: types.ts:87

Directory for run state (default .ripline/runs). Used by HTTP server.

---

PipelineRegistryEntry

PipelineRegistryEntry = object

Defined in: types.ts:385

Properties

definition

definition: PipelineDefinition

Defined in: types.ts:386

mtimeMs

mtimeMs: number

Defined in: types.ts:387

path

path: string

Defined in: types.ts:388

---

PipelineRunRecord

PipelineRunRecord = object

Defined in: types.ts:460

Properties

childRunIds

childRunIds: string[]

Defined in: types.ts:472

containerLogFile?

optional containerLogFile: string

Defined in: types.ts:496

Absolute path to the container log file (set when container-based execution is used).

cursor?

optional cursor: object

Defined in: types.ts:478

context

context: Record<string, unknown>

nextNodeIndex

nextNodeIndex: number

error?

optional error: string

Defined in: types.ts:488

featureBranch?

optional featureBranch: string

Defined in: types.ts:498

Feature branch created for container-based builds (e.g. "build/{runId}").

id

id: string

Defined in: types.ts:461

inputs

inputs: Record<string, unknown>

Defined in: types.ts:476

outputs?

optional outputs: Record<string, unknown>

Defined in: types.ts:477

ownerPid?

optional ownerPid: number

Defined in: types.ts:500

Host process currently responsible for advancing this run while it is in running.

parentRunId?

optional parentRunId: string

Defined in: types.ts:463

pipelineId

pipelineId: string

Defined in: types.ts:462

queueMode?

optional queueMode: QueueMode

Defined in: types.ts:469

When this run was created by an enqueue node.

queueName?

optional queueName: string

Defined in: types.ts:471

Named queue this run belongs to (from pipeline definition). Defaults to "default".

retryCount?

optional retryCount: number

Defined in: types.ts:490

Number of times this run has been retried.

retryPolicy?

optional retryPolicy: RetryPolicy

Defined in: types.ts:492

Retry policy governing automatic resumption of this run.

source?

optional source: RunSource

Defined in: types.ts:465

How this run was initiated. Defaults to 'user'.

startedAt

startedAt: number

Defined in: types.ts:474

status

status: PipelineRunStatus

Defined in: types.ts:473

steps

steps: PipelineRunStep[]

Defined in: types.ts:487

taskId?

optional taskId: string

Defined in: types.ts:467

When this run was created by an enqueue node.

updatedAt

updatedAt: number

Defined in: types.ts:475

waitFor?

optional waitFor: object

Defined in: types.ts:482

nodeId

nodeId: string

reason?

optional reason: string

resumeKey?

optional resumeKey: string

webhook_url?

optional webhook_url: string

Defined in: types.ts:494

Optional webhook URL to receive push notifications on run completion/error.

---

PipelineRunStatus

PipelineRunStatus = "pending" | "running" | "paused" | "errored" | "completed" | "needs-conflict-resolution"

Defined in: types.ts:391

---

PipelineRunStep

PipelineRunStep = object

Defined in: types.ts:399

Properties

data?

optional data: unknown

Defined in: types.ts:404

error?

optional error: string

Defined in: types.ts:405

errorCategory?

optional errorCategory: ErrorCategory

Defined in: types.ts:407

Classification of the error for retry decisions.

finishedAt?

optional finishedAt: number

Defined in: types.ts:403

iteration?

optional iteration: number

Defined in: types.ts:408

nodeId

nodeId: string

Defined in: types.ts:400

startedAt?

optional startedAt: number

Defined in: types.ts:402

status

status: "pending" | "running" | "completed" | "errored" | "skipped" | "paused"

Defined in: types.ts:401

---

QueueConfig

QueueConfig = object

Defined in: types.ts:447

Per-queue configuration with concurrency and optional resource limits.

Properties

concurrency

concurrency: number

Defined in: types.ts:449

Maximum number of concurrent jobs for this queue. Default 1.

resourceLimits?

optional resourceLimits: ContainerResourceLimits

Defined in: types.ts:451

Resource limits applied to containers spawned by this queue.

---

QueueMode

QueueMode = "batch" | "per-item"

Defined in: types.ts:411

---

RetryPolicy

RetryPolicy = object

Defined in: types.ts:105

Pipeline-level retry policy for resuming failed runs.

Properties

backoffMs

backoffMs: number

Defined in: types.ts:107

backoffMultiplier

backoffMultiplier: number

Defined in: types.ts:108

maxAttempts

maxAttempts: number

Defined in: types.ts:106

retryableCategories

retryableCategories: ErrorCategory[]

Defined in: types.ts:109

---

RiplineProfile

RiplineProfile = object

Defined in: types.ts:31

Properties

agents?

optional agents: Record<string, AgentDefinition>

Defined in: types.ts:35

Agent definitions for this profile. Merged on top of global agents (profile wins).

description?

optional description: string

Defined in: types.ts:33

inputs

inputs: Record<string, unknown>

Defined in: types.ts:38

name

name: string

Defined in: types.ts:32

skills?

optional skills: SkillsRegistry

Defined in: types.ts:37

Skills registry for this profile. Merged on top of global skills (profile wins).

---

RiplineUserConfig

RiplineUserConfig = object

Defined in: types.ts:59

Properties

backgroundQueue?

optional backgroundQueue: BackgroundQueueConfig

Defined in: types.ts:71

Background queue configuration.

claudeCode?

optional claudeCode: object

Defined in: types.ts:67

Only from ~/.ripline/config.json; never from pipeline/profile/input.

allowDangerouslySkipPermissions?

optional allowDangerouslySkipPermissions: boolean

codex?

optional codex: object

Defined in: types.ts:69

Only from ~/.ripline/config.json; never from pipeline/profile/input.

allowDangerouslySkipPermissions?

optional allowDangerouslySkipPermissions: boolean

containerBuild?

optional containerBuild: ContainerBuildUserConfig

Defined in: types.ts:77

Container build configuration. When enabled, scheduler attempts container-based execution.

defaultProfile?

optional defaultProfile: string

Defined in: types.ts:63

pipelineDir?

optional pipelineDir: string

Defined in: types.ts:60

preferredRunner?

optional preferredRunner: BuiltinAgentRunner

Defined in: types.ts:65

Preferred built-in code runner for agent nodes ("codex" or "claude-code").

profileDir?

optional profileDir: string

Defined in: types.ts:61

queues?

optional queues: Record<string, QueueConfig>

Defined in: types.ts:75

Per-queue configuration (concurrency + resource limits). e.g. { build: { concurrency: 3 } }

skillsDir?

optional skillsDir: string

Defined in: types.ts:62

telegram?

optional telegram: TelegramConfig

Defined in: types.ts:73

Telegram notification configuration.

---

RunPipelineNode

RunPipelineNode = NodeBase & object

Defined in: types.ts:231

Type Declaration

inputMapping?

optional inputMapping: Record<string, string>

mode?

optional mode: "child" | "inline"

pipelineId

pipelineId: string

type

type: "run_pipeline"

---

RunSource

RunSource = "user" | "schedule" | "background"

Defined in: types.ts:414

How a run was initiated.

---

ShellNode

ShellNode = NodeBase & object

Defined in: types.ts:304

Type Declaration

assigns?

optional assigns: string

Artifact key to assign result to. Defaults to node id.

command

command: string

Shell command to run. Supports interpolation.

container?

optional container: NodeContainerConfig | false

Container execution mode for this node. "isolated" = fresh container per node using the configured build image. Object form = custom image/env/volumes. false = force host execution even when the run has a container. When unset, inherits from run-level container config (if any).

cwd?

optional cwd: string

Working directory for the command.

failOnNonZero?

optional failOnNonZero: boolean

If true, non-zero exit code throws and fails the pipeline node. Default true.

timeoutSeconds?

optional timeoutSeconds: number

Max execution time in seconds. Default 120.

type

type: "shell"

---

SkillDefinition

SkillDefinition = McpServerConfig & object

Defined in: types.ts:26

A named skill: an MCP server config with an optional human-readable description.

Type Declaration

description?

optional description: string

---

SkillsRegistry

SkillsRegistry = Record<string, SkillDefinition>

Defined in: types.ts:29

Named library of skills available to agents.

---

SwitchNode

SwitchNode = NodeBase & object

Defined in: types.ts:261

Type Declaration

cases

cases: Record<string, object>

default?

optional default: string

expression

expression: string

type

type: "switch"

---

TaskItem

TaskItem = object

Defined in: types.ts:283

Convention for breakdown nodes: emit tasks[] for downstream enqueue node.

Properties

detail?

optional detail: string

Defined in: types.ts:286

id

id: string

Defined in: types.ts:284

priority?

optional priority: number | string

Defined in: types.ts:287

title

title: string

Defined in: types.ts:285

---

TelegramConfig

TelegramConfig = object

Defined in: types.ts:455

Configuration for Telegram notifications.

Properties

botToken

botToken: string

Defined in: types.ts:456

chatId

chatId: string

Defined in: types.ts:457

---

TransformNode

TransformNode = NodeBase & object

Defined in: types.ts:191

Type Declaration

assigns?

optional assigns: string

expression

expression: string

type

type: "transform"