@perstack/runtime

The execution engine library for Perstack agents. This is a pure library — it has no CLI. CLI functionality is provided by the perstack package.

Installation

npm install @perstack/runtime

Usage

The primary entry point is the run function:

import { run } from "@perstack/runtime"

const checkpoint = await run(
  {
    setting: {
      model: "claude-sonnet-4-5",
      providerConfig: { providerName: "anthropic", apiKey: "..." },
      jobId: "job-123",
      runId: "run-123",
      expertKey: "researcher",
      input: { text: "Research quantum computing" },
      experts: { /* expert definitions */ },
    },
  },
  {
    eventListener: (event) => console.log(`[${event.type}]`, event),
  },
)

Public API

| Export | Description | | --- | --- | | run(input, options) | Execute an expert run. Returns a Checkpoint. | | runtimeVersion | Current runtime semver string. | | collectToolDefinitionsForExpert() | Collect tool definitions from an expert's skills. | | getLockfileExpertToolDefinitions() | Extract tool definitions from a lockfile expert entry. | | runtimeStateMachine | XState machine definition (for advanced use). |

Events

The eventListener callback receives RunEvent | RuntimeEvent objects with granular execution details:

eventListener: (event) => {
  if (event.type === "callTools") {
    console.log(`Executing ${event.toolCalls.length} tools`)
  }
}

Architecture

Job (jobId)
 ├── Run 1 (Coordinator Expert)
 │    └── Checkpoints...
 ├── Run 2 (Delegated Expert A)
 │    └── Checkpoints...
 └── Run 3 (Delegated Expert B)
      └── Checkpoints...

| Concept | Description | | --- | --- | | Job | Top-level execution unit. Contains all Runs. | | Run | Single Expert execution within a Job. | | Checkpoint | Immutable snapshot at each step boundary. Enables pause/resume. |

The runtime drives the agent loop (Reason → Act → Observe), manages checkpoints for state persistence, provides MCP-based tool execution, and handles expert-to-expert delegation.

Skill Managers

| Type | Manager | Purpose | | --- | --- | --- | | MCP (stdio/SSE) | McpSkillManager | External tools via MCP protocol | | Interactive | InteractiveSkillManager | User input tools (Coordinator only) | | Delegate | DelegateSkillManager | Expert-to-Expert calls |

State Machine

The runtime uses an XState state machine for deterministic execution flow:

Init → PreparingForStep → GeneratingToolCall → CallingMcpTools → ...
  ↓                                              ↓
ResumingFromStop                            CallingDelegates → CallingInteractiveTools
                                                                     ↓
                                               ResolvingToolResult → FinishingStep → (loop)

Terminal states: completed, stoppedByError, stoppedByExceededMaxSteps, stoppedByInteractiveTool, stoppedByDelegate, stoppedByCancellation

Related Documentation

• Runtime — Full execution model
• State Management — Jobs, Runs, and Checkpoints
• Running Experts — CLI usage via perstack package