Runtime

The Perstack runtime combines probabilistic LLM reasoning with deterministic state management — making agent execution predictable, reproducible, and auditable.

Execution model

The runtime organizes execution into a three-level hierarchy:

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

Coordinator vs. Delegated Expert

Key differences:

Agent loop

Each Run executes through an agent loop:

┌─────────────────────────────────────────────────────┐
│  1. Reason    →  LLM decides next action            │
│  2. Act       →  Runtime executes tool              │
│  3. Record    →  Checkpoint saved                   │
│  4. Repeat    →  Until completion or limit          │
└─────────────────────────────────────────────────────┘

The loop ends when:

• LLM calls attemptCompletion with all todos complete (or no todos)
• Job reaches maxSteps limit
• External signal (SIGTERM/SIGINT)

When attemptCompletion is called, the runtime checks the todo list. If incomplete todos remain, they are returned to the LLM to continue work. This prevents premature completion and ensures all planned tasks are addressed.

Step counting

Step numbers are continuous across all Runs within a Job. When delegation occurs, the delegated Run continues from the parent’s step number:

Job (totalSteps = 8)
 ├── Run 1 (Coordinator): step 1 → 2 → delegates at step 3
 │                              ↓
 ├── Run 2 (Delegate A): step 3 → 4 → completes
 │                              ↓
 └── Run 1 continues: step 5 → 6 → 7 → 8

The maxSteps limit applies to the Job’s total steps across all Runs.

Stopping and resuming

npx perstack run my-expert "query" --max-steps 50

Deterministic state

LLMs are probabilistic — same input can produce different outputs. Perstack draws a clear boundary:

The “thinking” is probabilistic; the “doing” and “recording” are deterministic. This boundary enables:

• Reproducibility: Replay from any checkpoint with identical state
• Testability: Mock the LLM, test the runtime deterministically

Event, Step, Checkpoint

Runtime state is built on three concepts:

This combines Event Sourcing (complete history) with Checkpoint/Restore (efficient resume).

The perstack/ directory

The runtime stores execution history in perstack/jobs/ within the workspace:

/workspace
└── perstack/
    └── jobs/
        └── {jobId}/
            ├── job.json                                   # Job metadata
            └── runs/
                └── {runId}/
                    ├── run-setting.json                   # Run configuration
                    ├── checkpoint-{timestamp}-{step}-{id}.json
                    └── event-{timestamp}-{step}-{type}.json

This directory is managed automatically — don’t modify it manually.

Event notification

The runtime emits events for every state change. Two options:

stdout (default)

Events are written to stdout as JSON. This is the safest option for sandboxed environments — no network access required.

npx perstack run my-expert "query"

Your infrastructure reads stdout and decides what to do with events. See Sandbox Integration for the rationale.

Custom event listener

When embedding the runtime programmatically, use a callback:

import { run } from "@perstack/runtime"
 
await run(params, {
  eventListener: (event) => {
    // Send to your monitoring system, database, etc.
  }
})

Skills (MCP)

Experts use tools through MCP (Model Context Protocol). The runtime handles:

• Lifecycle: Start MCP servers with Expert, clean up on exit
• Environment isolation: Only requiredEnv variables are passed
• Error recovery: MCP failures are fed back to LLM, not thrown as runtime errors

For skill configuration, see Skills.

Providers and models

Perstack uses standard LLM features available from most providers:

• Chat completion (including PDF/image in messages)
• Tool calling

For supported providers and models, see Providers and Models.