Ripline API Reference v0.1.0

---

Ripline API Reference / index

index

Classes

ContainerManager

Defined in: container-manager.ts:66

Constructors

Constructor

new ContainerManager(config?): ContainerManager

Defined in: container-manager.ts:72

Parameters

config?

ContainerManagerConfig = {}

Returns

ContainerManager

Accessors

trackedFailedContainers

Get Signature

get trackedFailedContainers(): readonly object[]

Defined in: container-manager.ts:174

Get the list of currently tracked failed containers (for testing/diagnostics).

Returns

readonly object[]

Methods

cleanupExpiredContainers()

cleanupExpiredContainers(): void

Defined in: container-manager.ts:153

Immediately run TTL-based cleanup of failed containers. Exposed for testing purposes.

Returns

void

dispose()

dispose(): void

Defined in: container-manager.ts:142

Stop the background cleanup timer. Call when shutting down.

Returns

void

removeContainer()

removeContainer(containerId): void

Defined in: container-manager.ts:130

Forcibly remove a container by ID.

Parameters

containerId

string

Returns

void

spawn()

spawn(options): Promise<ContainerResult>

Defined in: container-manager.ts:84

Spawn a Docker container, stream its stdout/stderr to a log file, wait for it to exit, and handle cleanup.

Parameters

options

ContainerSpawnOptions

Returns

Promise<ContainerResult>

Interfaces

ClaudeCodeRunnerConfig

Defined in: claude-code-runner.ts:47

Properties

allowDangerouslySkipPermissions?

optional allowDangerouslySkipPermissions: boolean

Defined in: claude-code-runner.ts:58

Opt-in bypass; only from user config or env, never from pipeline/profile.

allowedTools?

optional allowedTools: string[]

Defined in: claude-code-runner.ts:52

cwd?

optional cwd: string

Defined in: claude-code-runner.ts:49

disallowedTools?

optional disallowedTools: string[]

Defined in: claude-code-runner.ts:53

maxTurns?

optional maxTurns: number

Defined in: claude-code-runner.ts:54

mcpServers?

optional mcpServers: Record<string, McpServerConfig>

Defined in: claude-code-runner.ts:60

Default MCP servers applied to all runs (merged under call-level mcpServers; call-level wins).

mode

mode: "plan" | "execute"

Defined in: claude-code-runner.ts:48

model?

optional model: string

Defined in: claude-code-runner.ts:51

Default model for nodes that do not set model (e.g. claude-sonnet-4-6).

outputFormat?

optional outputFormat: "text" | "json"

Defined in: claude-code-runner.ts:56

timeoutSeconds?

optional timeoutSeconds: number

Defined in: claude-code-runner.ts:55

---

CodexRunnerConfig

Defined in: codex-runner.ts:11

Properties

allowDangerouslySkipPermissions?

optional allowDangerouslySkipPermissions: boolean

Defined in: codex-runner.ts:17

cwd?

optional cwd: string

Defined in: codex-runner.ts:13

mode

mode: "plan" | "execute"

Defined in: codex-runner.ts:12

model?

optional model: string

Defined in: codex-runner.ts:14

outputFormat?

optional outputFormat: "text" | "json"

Defined in: codex-runner.ts:16

timeoutSeconds?

optional timeoutSeconds: number

Defined in: codex-runner.ts:15

---

ContainerBuildConfig

Defined in: container-build-runner.ts:21

Properties

buildImage?

optional buildImage: string

Defined in: container-build-runner.ts:27

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

containerTimeoutMs?

optional containerTimeoutMs: number

Defined in: container-build-runner.ts:33

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

logger?

optional logger: Logger

Defined in: container-build-runner.ts:37

Logger instance.

repoPath

repoPath: string

Defined in: container-build-runner.ts:23

Absolute path to the host git repository.

resourceLimits?

optional resourceLimits: object

Defined in: container-build-runner.ts:35

Resource limits (CPU, memory) for each container.

cpus?

optional cpus: string

memory?

optional memory: string

runsDir?

optional runsDir: string

Defined in: container-build-runner.ts:39

Absolute path to the runs directory (for co-locating container logs with run records).

secretsMountPath?

optional secretsMountPath: string

Defined in: container-build-runner.ts:31

Path on host to mount as secrets inside the container.

targetBranch?

optional targetBranch: string

Defined in: container-build-runner.ts:25

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

testCommand?

optional testCommand: string

Defined in: container-build-runner.ts:29

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

---

ContainerBuildResult

Defined in: container-build-runner.ts:42

Properties

containerResult?

optional containerResult: ContainerResult

Defined in: container-build-runner.ts:46

Container result (only set if usedContainer is true).

error?

optional error: string

Defined in: container-build-runner.ts:52

Error message if container execution failed.

featureBranch?

optional featureBranch: string

Defined in: container-build-runner.ts:50

The feature branch name created for this build.

promoteResult?

optional promoteResult: PromoteStepResult

Defined in: container-build-runner.ts:48

Promote step result (only set on container success).

usedContainer

usedContainer: boolean

Defined in: container-build-runner.ts:44

Whether container-based execution was used (false = fell back to direct).

---

ContainerManagerConfig

Defined in: container-manager.ts:50

Properties

failedContainerTTL?

optional failedContainerTTL: number

Defined in: container-manager.ts:52

How long (ms) to retain failed containers before removing them. Default: 30 minutes.

logger?

optional logger: Logger

Defined in: container-manager.ts:54

Logger instance.

---

ContainerResult

Defined in: container-manager.ts:39

Properties

containerId

containerId: string

Defined in: container-manager.ts:41

Docker container ID (short hash).

exitCode

exitCode: number | null

Defined in: container-manager.ts:43

Process exit code. null if killed or timed out.

logFile

logFile: string

Defined in: container-manager.ts:47

Absolute path to the log file on host.

timedOut

timedOut: boolean

Defined in: container-manager.ts:45

Whether the container timed out.

---

ContainerSpawnOptions

Defined in: container-manager.ts:18

Properties

command?

optional command: string[]

Defined in: container-manager.ts:22

Command + args to run inside the container. If omitted, uses image default.

env?

optional env: Record<string, string>

Defined in: container-manager.ts:24

Environment variables to pass into the container.

image

image: string

Defined in: container-manager.ts:20

Docker image to run (e.g. "node:20-slim").

logFile

logFile: string

Defined in: container-manager.ts:30

Absolute path on host where stdout/stderr will be streamed.

name?

optional name: string

Defined in: container-manager.ts:32

Optional container name (must be unique). Auto-generated if omitted.

resourceLimits?

optional resourceLimits: object

Defined in: container-manager.ts:36

Resource limits (CPU, memory) applied to the container.

cpus?

optional cpus: string

memory?

optional memory: string

timeoutMs?

optional timeoutMs: number

Defined in: container-manager.ts:34

Timeout in milliseconds. Container is killed if it exceeds this. 0 = no timeout.

volumes?

optional volumes: Record<string, string>

Defined in: container-manager.ts:26

Volume mounts as host:container pairs (e.g. { "/host/path": "/container/path" }).

workdir?

optional workdir: string

Defined in: container-manager.ts:28

Working directory inside the container.

Type Aliases

ContainerStatusMapping

ContainerStatusMapping = object

Defined in: container-status-map.ts:24

Result of mapping a container build outcome to a pipeline status.

Properties

error?

optional error: string

Defined in: container-status-map.ts:32

Error message (if any) for the run record.

preserveFeatureBranch

preserveFeatureBranch: boolean

Defined in: container-status-map.ts:34

Whether the feature branch should be preserved (for manual needs-conflict-resolution resolution).

status

status: PipelineRunStatus | null

Defined in: container-status-map.ts:26

The pipeline run status to assign. null means "not handled by container path".

summary

summary: string

Defined in: container-status-map.ts:30

Human-readable summary of the outcome for logging/display.

usedContainer

usedContainer: boolean

Defined in: container-status-map.ts:28

Whether the run used container-based execution.

---

LlmAgentRunnerConfig

LlmAgentRunnerConfig = object

Defined in: llm-agent-runner.ts:3

Properties

apiKey?

optional apiKey: string

Defined in: llm-agent-runner.ts:6

baseURL?

optional baseURL: string

Defined in: llm-agent-runner.ts:7

model

model: string

Defined in: llm-agent-runner.ts:5

provider

provider: "ollama" | "openai" | "anthropic"

Defined in: llm-agent-runner.ts:4

---

NormalizedConfig

NormalizedConfig = object

Defined in: index.ts:55

Properties

authToken?

optional authToken: string

Defined in: index.ts:61

httpPath

httpPath: string

Defined in: index.ts:59

httpPort

httpPort: number

Defined in: index.ts:58

maxConcurrency

maxConcurrency: number

Defined in: index.ts:60

pipelinesDir

pipelinesDir: string

Defined in: index.ts:56

runsDir

runsDir: string

Defined in: index.ts:57

---

OpenClawPluginApi

OpenClawPluginApi = object

Defined in: integrations/openclaw/openclaw-runner.ts:5

OpenClaw plugin API surface used to run agent commands.

Properties

runtime

runtime: object

Defined in: integrations/openclaw/openclaw-runner.ts:6

system

system: object

system.runCommandWithTimeout()

runCommandWithTimeout(command, options?): Promise<{ code: number | null; signal?: string | null; stderr: string; stdout: string; }>

Parameters

command

string[]

options?

number | { input?: string; timeoutMs?: number; }

Returns

Promise<{ code: number | null; signal?: string | null; stderr: string; stdout: string; }>

---

PromoteStepParams

PromoteStepParams = object

Defined in: promote-step.ts:5

Properties

featureBranch

featureBranch: string

Defined in: promote-step.ts:7

gitTimeoutMs?

optional gitTimeoutMs: number

Defined in: promote-step.ts:11

remote?

optional remote: string

Defined in: promote-step.ts:12

repoPath

repoPath: string

Defined in: promote-step.ts:6

targetBranch

targetBranch: string

Defined in: promote-step.ts:8

testCommand

testCommand: string

Defined in: promote-step.ts:9

testTimeoutMs?

optional testTimeoutMs: number

Defined in: promote-step.ts:10

---

PromoteStepResult

PromoteStepResult = object

Defined in: promote-step.ts:17

Properties

conflictedFiles?

optional conflictedFiles: ConflictedFile[]

Defined in: promote-step.ts:23

gitOutput?

optional gitOutput: string

Defined in: promote-step.ts:22

mergeCommit?

optional mergeCommit: string

Defined in: promote-step.ts:20

message

message: string

Defined in: promote-step.ts:19

status

status: "merged" | "needs-conflict-resolution" | "test-failure" | "error"

Defined in: promote-step.ts:18

testOutput?

optional testOutput: string

Defined in: promote-step.ts:21

---

ValidationIssue

ValidationIssue = object

Defined in: pipeline-validator.ts:19

Properties

message

message: string

Defined in: pipeline-validator.ts:21

nodeId?

optional nodeId: string

Defined in: pipeline-validator.ts:23

The node ID related to the issue, if applicable.

severity

severity: ValidationSeverity

Defined in: pipeline-validator.ts:20

---

ValidationResult

ValidationResult = object

Defined in: pipeline-validator.ts:26

Properties

issues

issues: ValidationIssue[]

Defined in: pipeline-validator.ts:28

pipelineId?

optional pipelineId: string

Defined in: pipeline-validator.ts:30

Pipeline id, if parseable.

valid

valid: boolean

Defined in: pipeline-validator.ts:27

---

ValidationSeverity

ValidationSeverity = "error" | "warning"

Defined in: pipeline-validator.ts:17

Variables

default

default: object

Defined in: index.ts:128

Type Declaration

description

description: string = "Ripline pipeline engine + CLI"

id

id: string = "ripline"

name

name: string = "Ripline"

register()

register(api): void

Parameters

api

PluginApi

Returns

void

---

PROMOTE_STATUS_TO_RUN_STATUS

const PROMOTE_STATUS_TO_RUN_STATUS: Record<string, PipelineRunStatus>

Defined in: container-status-map.ts:153

All possible PromoteStepResult statuses and their corresponding run statuses. Useful for exhaustiveness checks in tests.

Functions

createClaudeCodeRunner()

createClaudeCodeRunner(config): AgentRunner

Defined in: claude-code-runner.ts:133

Create an AgentRunner that invokes the Claude Code (Agent) SDK. Use for nodes with runner: claude-code; supports plan (read-only) and execute modes.

Parameters

config

ClaudeCodeRunnerConfig

Returns

AgentRunner

---

createCodexRunner()

createCodexRunner(config): AgentRunner

Defined in: codex-runner.ts:81

Parameters

config

CodexRunnerConfig

Returns

AgentRunner

---

createLlmAgentRunner()

createLlmAgentRunner(config): AgentRunner

Defined in: llm-agent-runner.ts:49

Create an AgentRunner that calls Ollama, OpenAI, or Anthropic APIs. Use when running standalone without an external agent runner. Single model for all agent nodes.

Parameters

config

LlmAgentRunnerConfig

Returns

AgentRunner

---

createOpenClawAgentRunner()

createOpenClawAgentRunner(api): AgentRunner

Defined in: integrations/openclaw/openclaw-runner.ts:39

Create an AgentRunner that delegates to OpenClaw via openclaw agent --json. Uses the plugin API's runCommandWithTimeout so pipelines use the configured models, tools, and sandbox.

Parameters

api

OpenClawPluginApi

Returns

AgentRunner

---

isDockerAvailable()

isDockerAvailable(): boolean

Defined in: container-build-runner.ts:59

Returns

boolean

---

loadLlmAgentConfigFromFile()

loadLlmAgentConfigFromFile(cwd): LlmAgentRunnerConfig | null

Defined in: agent-runner-config.ts:95

Load LLM agent config from .ripline/agent.json or ripline.config.json (agent section). Returns null if file missing or invalid.

Parameters

cwd

string

Returns

LlmAgentRunnerConfig | null

---

mapContainerBuildToRunStatus()

mapContainerBuildToRunStatus(result): ContainerStatusMapping

Defined in: container-status-map.ts:43

Map a ContainerBuildResult to a pipeline run status and metadata.

This is the authoritative mapping used by the scheduler and exposed for integration tests to verify status correctness.

Parameters

result

ContainerBuildResult

Returns

ContainerStatusMapping

---

normalizeClaudeCodeConfigFromPlugin()

normalizeClaudeCodeConfigFromPlugin(raw): ClaudeCodeRunnerConfig | null

Defined in: agent-runner-config.ts:175

Extract Claude Code runner config from plugin config (claudeCode key).

Parameters

raw

unknown

Returns

ClaudeCodeRunnerConfig | null

---

normalizeCodexConfigFromPlugin()

normalizeCodexConfigFromPlugin(raw): CodexRunnerConfig | null

Defined in: agent-runner-config.ts:326

Parameters

raw

unknown

Returns

CodexRunnerConfig | null

---

normalizeConfig()

normalizeConfig(raw): NormalizedConfig

Defined in: index.ts:110

Parameters

raw

unknown

Returns

NormalizedConfig

---

normalizeLlmAgentConfigFromPlugin()

normalizeLlmAgentConfigFromPlugin(raw, env?): LlmAgentRunnerConfig | null

Defined in: agent-runner-config.ts:37

Extract and validate LLM agent config from plugin config (agentRunner or agent key). Fills apiKey from OPENAI_API_KEY / ANTHROPIC_API_KEY when not set.

Parameters

raw

unknown

env?

Record<string, string>

Returns

LlmAgentRunnerConfig | null

---

promoteStep()

promoteStep(params): Promise<PromoteStepResult>

Defined in: promote-step.ts:26

Parameters

params

PromoteStepParams

Returns

Promise<PromoteStepResult>

---

resolveClaudeCodeConfig()

resolveClaudeCodeConfig(options?): ClaudeCodeRunnerConfig | null

Defined in: agent-runner-config.ts:302

Resolve Claude Code config: env + config file + user config (bypass flag only from env or ~/.ripline/config.json).

Parameters

options?

cwd?

string

env?

Record<string, string>

homedir?

string

Returns

ClaudeCodeRunnerConfig | null

---

resolveCodexConfig()

resolveCodexConfig(options?): CodexRunnerConfig | null

Defined in: agent-runner-config.ts:395

Parameters

options?

cwd?

string

env?

Record<string, string>

homedir?

string

Returns

CodexRunnerConfig | null

---

resolveLlmAgentConfigFromEnv()

resolveLlmAgentConfigFromEnv(env?): LlmAgentRunnerConfig | null

Defined in: agent-runner-config.ts:69

Resolve LLM agent config from environment variables. Requires RIPLINE_AGENT_PROVIDER and RIPLINE_AGENT_MODEL.

Parameters

env?

Record<string, string>

Returns

LlmAgentRunnerConfig | null

---

resolveStandaloneLlmAgentConfig()

resolveStandaloneLlmAgentConfig(options?): LlmAgentRunnerConfig | null

Defined in: agent-runner-config.ts:127

Resolve standalone LLM agent config: overrides (e.g. CLI) > env > config file. Used by CLI when no external agent runner is provided.

Parameters

options?

cwd?

string

env?

Record<string, string>

overrides?

Partial<LlmAgentRunnerConfig>

Returns

LlmAgentRunnerConfig | null

---

runContainerBuild()

runContainerBuild(runId, pipelineId, pipelineContext, config): Promise<ContainerBuildResult>

Defined in: container-build-runner.ts:116

Attempt to run a pipeline build inside a Docker container.

Returns a result indicating whether container execution was used. If Docker is unavailable, returns { usedContainer: false } so the caller can fall back to direct execution.

Parameters

runId

string

pipelineId

string

pipelineContext

Record<string, unknown>

config

ContainerBuildConfig

Returns

Promise<ContainerBuildResult>

---

smokeTestPipelineDefinition()

smokeTestPipelineDefinition(def): object

Defined in: pipeline-validator.ts:154

Quick smoke test: verify a pipeline definition has the minimum fields needed to be loadable by the pipeline registry and schedulable.

Parameters

def

PipelineDefinition

Returns

object

pass

pass: boolean

reason?

optional reason: string

---

validateContainerBuildPipeline()

validateContainerBuildPipeline(def): ValidationResult

Defined in: pipeline-validator.ts:99

Validate that a pipeline is suitable for container-based execution through the scheduler's build queue.

Parameters

def

PipelineDefinition

Returns

ValidationResult

---

validatePipelineDefinition()

validatePipelineDefinition(def): ValidationResult

Defined in: pipeline-validator.ts:36

Validate a pipeline definition for general structural correctness.

Parameters

def

PipelineDefinition

Returns

ValidationResult