npm package: @perstack/runtime
Description: Perstack Runtime
Author: Wintermute Technologies, Inc.
Latest version: 0.0.147

# @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`](https://www.npmjs.com/package/perstack) package.

## Installation

```bash
npm install @perstack/runtime
```

## Usage

The primary entry point is the `run` function:

```typescript
import { run } from "@perstack/runtime"

const checkpoint = await run(
  {
    setting: {
      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:

```typescript
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`, `stoppedByInteractiveTool`, `stoppedByDelegate`, `stoppedByCancellation`

## Related Documentation

- [Runtime](https://github.com/perstack-ai/perstack/blob/main/docs/understanding-perstack/runtime.md) — Full execution model
- [State Management](https://github.com/perstack-ai/perstack/blob/main/docs/using-experts/state-management.md) — Jobs, Runs, and Checkpoints
- [Running Experts](https://github.com/perstack-ai/perstack/blob/main/docs/using-experts/running-experts.md) — CLI usage via `perstack` package