@kb-labs/workflow-runtime

Runtime adapters and step executors for the KB Labs workflow engine.

Vision & Purpose

@kb-labs/workflow-runtime provides runtime adapters and step executors for workflow execution. It includes local runner for in-process execution, sandbox runner for plugin commands, context management, and signal handling.

Core Goals

• Local Runner: Execute steps in-process
• Sandbox Runner: Execute plugin commands in sandboxed environment
• Context Management: Step execution context with environment and secrets
• Signal Handling: Proper cancellation and timeout handling

Package Status

• Version: 0.1.0
• Stage: Stable
• Status: Production Ready ✅

Architecture

High-Level Overview

Workflow Runtime
    │
    ├──► Local Runner (in-process execution)
    ├──► Sandbox Runner (plugin commands)
    ├──► Context Management
    └──► Signal Handling

Key Components

1. LocalRunner (runners/local-runner.ts): Execute steps in-process
2. SandboxRunner (runners/sandbox-runner.ts): Execute plugin commands in sandbox
3. Context (context.ts): Step execution context creation
4. Types (types.ts): Type definitions

✨ Features

• Local execution for shell commands
• Sandbox execution for plugin commands
• Context management with environment and secrets
• Signal handling for cancellation and timeouts
• Artifact support for step outputs
• Event emission for step observability
• Tracing support for distributed tracing

📦 API Reference

Main Exports

Runner Classes

• LocalRunner: Execute steps in-process
• SandboxRunner: Execute plugin commands in sandbox

Context Functions

• createStepContext(input): Create step execution context

Types & Interfaces

• Runner: Runner interface
• StepContext: Step execution context
• StepExecutionRequest: Step execution request
• StepExecutionResult: Step execution result

Types & Interfaces

Runner

interface Runner {
  execute(request: StepExecutionRequest): Promise<StepExecutionResult>;
}

StepContext

interface StepContext {
  runId: string;
  jobId: string;
  stepId: string;
  attempt: number;
  env: Record<string, string>;
  secrets: Record<string, string>;
  artifacts?: ArtifactClient;
  events?: RuntimeEvents;
  logger: RuntimeLogger;
  trace?: RuntimeTrace;
  pluginContext?: PluginContext;
}

StepExecutionRequest

interface StepExecutionRequest {
  spec: StepSpec;
  context: StepContext;
  workspace?: string;
  signal?: AbortSignal;
}

StepExecutionResult

type StepExecutionResult = 
  | StepExecutionSuccess 
  | StepExecutionFailure;

interface StepExecutionSuccess {
  status: 'success';
  outputs?: Record<string, unknown>;
}

interface StepExecutionFailure {
  status: 'failed' | 'cancelled';
  error: {
    message: string;
    code?: string;
    stack?: string;
    details?: Record<string, unknown>;
  };
}

🔧 Configuration

Configuration Options

LocalRunner Options

• shell: Shell to use (default: process.env.SHELL or 'bash')

SandboxRunner Options

• timeoutMs: Timeout in milliseconds
• resolveCommand: Command resolver function

Environment Variables

• SHELL: Shell to use for local runner
• LOG_LEVEL: Logging level

🔗 Dependencies

Runtime Dependencies

• @kb-labs/workflow-artifacts (workspace:*): Workflow artifacts
• @kb-labs/workflow-constants (workspace:*): Workflow constants
• @kb-labs/workflow-contracts (workspace:*): Workflow contracts
• @kb-labs/plugin-manifest (link:../../../kb-labs-plugin/packages/manifest): Plugin manifest
• @kb-labs/plugin-runtime (link:../../../kb-labs-plugin/packages/runtime): Plugin runtime
• execa (^9.4.0): Process execution
• pino (^9.4.0): Logger
• pathe (^1.1.1): Path utilities

Development Dependencies

• @kb-labs/devkit (link:../../../kb-labs-devkit): DevKit presets
• @types/node (^24.3.3): Node.js types
• tsup (^8.5.0): TypeScript bundler
• typescript (^5.6.3): TypeScript compiler
• vitest (^3.2.4): Test runner

🧪 Testing

Test Structure

src/__tests__/
└── (tests to be added)

Test Coverage

• Current Coverage: ~0% (tests to be added)
• Target Coverage: 90%

📈 Performance

Performance Characteristics

• Time Complexity: O(1) for execution setup, O(n) for step execution
• Space Complexity: O(1)
• Bottlenecks: Step execution time

🔒 Security

Security Considerations

• Sandbox Execution: Plugin commands execute in sandbox
• Permission Checking: Capability checks before execution
• Secrets Management: Secrets passed via context
• Signal Handling: Proper cancellation handling

Known Vulnerabilities

• None

🐛 Known Issues & Limitations

Known Issues

• None currently

Limitations

• Local Runner: Only supports shell commands
• Sandbox Runner: Requires command resolver configuration

Future Improvements

• More Runner Types: Additional runner types
• Enhanced Context: More context features

🔄 Migration & Breaking Changes

Migration from Previous Versions

No breaking changes in current version (0.1.0).

Breaking Changes in Future Versions

• None planned

📚 Examples

Example 1: Local Runner

import { LocalRunner } from '@kb-labs/workflow-runtime';
import { createStepContext } from '@kb-labs/workflow-runtime';

const runner = new LocalRunner({ shell: 'bash' });

const context = createStepContext({
  runId: 'run-123',
  jobId: 'job-abc',
  stepId: 'step-xyz',
  env: { NODE_ENV: 'production' },
});

const result = await runner.execute({
  spec: {
    name: 'build',
    uses: 'builtin:shell',
    with: { command: 'npm run build' },
  },
  context,
});

Example 2: Sandbox Runner

import { SandboxRunner } from '@kb-labs/workflow-runtime';

const runner = new SandboxRunner({
  timeoutMs: 30000,
  resolveCommand: async (commandRef, request) => {
    // Resolve plugin command
    return {
      manifest,
      handler,
      permissions,
      pluginRoot,
    };
  },
});

const result = await runner.execute({
  spec: {
    name: 'review',
    uses: 'plugin:ai-review:review',
    with: { input: '...' },
  },
  context,
});

Example 3: Context with Artifacts

import { createStepContext } from '@kb-labs/workflow-runtime';
import { createFileSystemArtifactClient } from '@kb-labs/workflow-artifacts';

const artifacts = createFileSystemArtifactClient({
  baseDir: '/tmp/artifacts',
});

const context = createStepContext({
  runId: 'run-123',
  jobId: 'job-abc',
  stepId: 'step-xyz',
  artifacts,
});

🤝 Contributing

See CONTRIBUTING.md for development guidelines.

📄 License

MIT © KB Labs