Skip to content

Commit d98dddc

Browse files
FL4TLiN3FL4TLiN3
committed
Docs: Introduce Job concept as parent of Runs
This documentation update prepares for the Job/Run hierarchy refactoring: - Job: Top-level execution unit created per `perstack run` - Run: Single Expert execution within a Job - Checkpoint: Snapshot at step end within a Run Key design decisions documented: - Each Run has independent stepNumber (starts from 1) - Job tracks totalSteps across all Runs - maxSteps applies to Job level - Interactive tools only available for Coordinator Expert - --continue/--resume-from only work with Coordinator checkpoints - Context is never shared between Experts
1 parent 09e244a commit d98dddc

File tree

7 files changed

+335
-92
lines changed

7 files changed

+335
-92
lines changed

‎docs/content/references/cli.mdx‎

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,8 @@ Providers: `anthropic`, `google`, `openai`, `ollama`, `azure-openai`, `amazon-be
4949

5050
| Option | Description | Default |
5151
|--------|-------------|---------|
52-
| `--max-steps <n>` | Maximum steps | unlimited |
53-
| `--max-retries <n>` | Max retry attempts | `5` |
52+
| `--max-steps <n>` | Maximum total steps across all Runs in a Job | unlimited |
53+
| `--max-retries <n>` | Max retry attempts per generation | `5` |
5454
| `--timeout <ms>` | Timeout per generation (ms) | `60000` |
5555

5656
### Configuration
@@ -60,22 +60,24 @@ Providers: `anthropic`, `google`, `openai`, `ollama`, `azure-openai`, `amazon-be
6060
| `--config <path>` | Path to `perstack.toml` | Auto-discover from cwd |
6161
| `--env-path <path...>` | Environment file paths | `.env`, `.env.local` |
6262

63-
### Run Management
63+
### Job and Run Management
6464

6565
| Option | Description |
6666
|--------|-------------|
67-
| `--run-id <id>` | Custom run ID (default: auto-generated) |
68-
| `--continue` | Continue latest run with new query |
69-
| `--continue-run <id>` | Continue specific run |
70-
| `--resume-from <id>` | Resume from specific checkpoint |
67+
| `--job-id <id>` | Custom Job ID (default: auto-generated) |
68+
| `--continue` | Continue latest Job with new Run |
69+
| `--continue-job <id>` | Continue specific Job with new Run |
70+
| `--resume-from <id>` | Resume from specific checkpoint (Coordinator only) |
71+
72+
**Note:** `--continue` and `--resume-from` only work with the Coordinator Expert's checkpoints. You cannot resume from a Delegated Expert's checkpoint.
7173

7274
### Interactive
7375

7476
| Option | Description |
7577
|--------|-------------|
7678
| `-i, --interactive-tool-call-result` | Treat query as interactive tool call result |
7779

78-
Use with `--continue` to respond to interactive tool calls.
80+
Use with `--continue` to respond to interactive tool calls from the Coordinator Expert.
7981

8082
### Other
8183

@@ -86,7 +88,7 @@ Use with `--continue` to respond to interactive tool calls.
8688
## Examples
8789

8890
```bash
89-
# Basic execution
91+
# Basic execution (creates new Job)
9092
npx perstack run my-expert "Review this code"
9193

9294
# With model options
@@ -96,12 +98,21 @@ npx perstack run my-expert "query" \
9698
--temperature 0.7 \
9799
--max-steps 100
98100

99-
# Continue execution
101+
# Continue Job with follow-up
100102
npx perstack run my-expert "initial query"
101103
npx perstack run my-expert "follow-up" --continue
102104

103-
# Continue specific run
104-
npx perstack run my-expert "continue" --continue-run abc123
105+
# Continue specific Job
106+
npx perstack run my-expert "continue" --continue-job job_abc123
107+
108+
# Custom Job ID
109+
npx perstack run my-expert "query" --job-id my-custom-job
110+
111+
# Resume from checkpoint
112+
npx perstack run my-expert "query" --resume-from checkpoint_xyz
113+
114+
# Respond to interactive tool call
115+
npx perstack run my-expert "user response" --continue -i
105116

106117
# Custom config
107118
npx perstack run my-expert "query" \

‎docs/content/understanding-perstack/experts.mdx‎

Lines changed: 45 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -90,37 +90,51 @@ packageName = "@eslint/mcp"
9090

9191
When you run an Expert:
9292

93-
1. The runtime loads the Expert definition from `perstack.toml` or Registry
93+
1. The runtime creates a **Job** and starts the first **Run** with your Expert (the Coordinator)
9494
2. The instruction becomes the system prompt (with [runtime meta-instructions](https://github.com/perstack-ai/perstack/blob/main/packages/runtime/src/messages/instruction-message.ts))
9595
3. Your query becomes the user message
9696
4. The LLM reasons and calls tools (skills) as needed
97-
5. Each step produces a checkpoint — a complete snapshot of the execution state
97+
5. Each step produces a checkpoint — a complete snapshot of the Run's state
9898

9999
The runtime manages the execution loop. The Expert definition declares *what* to achieve; the runtime handles *how*.
100100

101101
### Delegation
102102

103-
Experts collaborate through delegation, not shared context.
103+
Experts collaborate through delegation, not shared context. Each delegation creates a new Run within the same Job.
104104

105105
```
106-
Expert A Expert B
107-
│
108-
├─ sees delegates as tools
109-
│ (description → tool description)
110-
│
111-
├─ calls delegate ──────────────────→ starts fresh
112-
│ (writes query) (empty history, own instruction)
113-
│ │
114-
│ [checkpoint saved] ├─ executes task
115-
│ │
116-
│ ├─ calls attemptCompletion
117-
│ │ (generates run result)
118-
│ │
119-
├─ resumes ←─────────────────────────── returns run result
120-
│ (receives summary)
121-
▼
106+
Job
107+
│
108+
├── Run 1: Expert A (Coordinator)
109+
│ │
110+
│ ├─ sees delegates as tools
111+
│ │ (description → tool description)
112+
│ │
113+
│ ├─ calls delegate ─────────────────────┐
114+
│ │ (writes query) │
115+
│ │ │
116+
│ │ [Run 1 paused] │
117+
│ │ ▼
118+
│ │ ┌── Run 2: Expert B ──┐
119+
│ │ │ starts fresh │
120+
│ │ │ (empty history) │
121+
│ │ │ (own instruction) │
122+
│ │ │ │ │
123+
│ │ │ ├─ executes │
124+
│ │ │ │ │
125+
│ │ │ ├─ completes │
126+
│ │ │ │ │
127+
│ │ └───────┼─────────────┘
128+
│ │ │
129+
│ ├─ resumes ◄───────────────────────────┘
130+
│ │ (receives run result only)
131+
│ ▼
122132
```
123133

134+
<Callout type="warning">
135+
**Context is never shared between Experts.** The delegate receives only the query — no message history, no parent context. This is a deliberate design decision, not a limitation.
136+
</Callout>
137+
124138
Note the asymmetry: Expert A sees Expert B's `description` (public interface), but never its `instruction` (private implementation). This is what makes Experts composable — the caller only needs to know *what* a delegate does, not *how* it does it.
125139

126140
**Key design decisions:**
@@ -130,9 +144,21 @@ Note the asymmetry: Expert A sees Expert B's `description` (public interface), b
130144
| **Message history** | Not shared | Each Expert has a single responsibility; mixing contexts breaks focus |
131145
| **Communication** | Natural language | No schema versioning, maximum flexibility, humans and Experts use the same interface |
132146
| **State exchange** | Workspace files | Persistent, inspectable, works across restarts |
147+
| **Interactive tools** | Coordinator only | Delegated Experts cannot pause for user input — return to Coordinator instead |
133148

134149
This is intentional. Shared context leads to prompt bloat, context window exhaustion, and confused LLM reasoning. Isolated Experts stay focused.
135150

151+
### Why no interactive tools for delegates?
152+
153+
Delegated Experts run without interactive tool access. If a delegate needs clarification:
154+
155+
1. It should return what it knows (via `attemptCompletion`)
156+
2. The Coordinator receives the result
157+
3. The Coordinator can ask the user for clarification
158+
4. The Coordinator can re-delegate with better information
159+
160+
This keeps the user interface at the Coordinator level and prevents deep call chains from blocking on user input.
161+
136162
### Workspace
137163

138164
The workspace is a shared filesystem where Experts read and write files. Unlike message history, the workspace persists across Expert boundaries — this is how Experts exchange complex data.

‎docs/content/understanding-perstack/runtime.mdx‎

Lines changed: 67 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,48 @@ import { Callout } from 'nextra/components'
44

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

7+
## Execution model
8+
9+
The runtime organizes execution into a three-level hierarchy:
10+
11+
```
12+
Job (jobId)
13+
├── Run 1 (runId, Coordinator Expert)
14+
│ └── Checkpoints...
15+
├── Run 2 (runId, Delegated Expert A)
16+
│ └── Checkpoints...
17+
└── Run 3 (runId, Delegated Expert B)
18+
└── Checkpoints...
19+
```
20+
21+
| Concept | Description |
22+
|---------|-------------|
23+
| **Job** | Top-level execution unit. Created per `perstack run` invocation. Contains all Runs. |
24+
| **Run** | Single Expert execution. Each delegation creates a new Run within the same Job. |
25+
| **Checkpoint** | Snapshot at the end of each step within a Run. |
26+
27+
### Coordinator vs. Delegated Expert
28+
29+
| Role | Description |
30+
|------|-------------|
31+
| **Coordinator Expert** | The initial Expert that starts a Job. Has full capabilities. |
32+
| **Delegated Expert** | Expert started via delegation. Restricted capabilities. |
33+
34+
Key differences:
35+
36+
| Capability | Coordinator | Delegated |
37+
|------------|-------------|-----------|
38+
| Interactive tool calls | ✅ Available | ❌ Not available |
39+
| `--continue` / `--resume-from` | ✅ Supported | ❌ Not supported |
40+
| Context from parent | N/A | Only the query (no shared history) |
41+
42+
<Callout type="info">
43+
Delegated Experts cannot use interactive tools. This enforces context isolation — if a delegate needs clarification, it should return to the Coordinator, which can then interact with the user.
44+
</Callout>
45+
746
## Agent loop
847

9-
The runtime executes Experts through an agent loop:
48+
Each Run executes through an agent loop:
1049

1150
```
1251
┌─────────────────────────────────────────────────────┐
@@ -19,12 +58,23 @@ The runtime executes Experts through an agent loop:
1958

2059
The loop ends when:
2160
- LLM calls `attemptCompletion` with all todos complete (or no todos)
22-
- `maxSteps` limit reached
61+
- Job reaches `maxSteps` limit
2362
- External signal (SIGTERM/SIGINT)
2463

2564
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.
2665

27-
When todo validation passes, the LLM generates a run result — a summary of the work done. This ensures every completed run has a clear, observable outcome.
66+
### Step counting
67+
68+
Each Run maintains its own `stepNumber`, starting from 1. The Job tracks total steps across all Runs:
69+
70+
```
71+
Job (totalSteps = 8)
72+
├── Run 1: stepNumber 1 → 2 → 3 (3 steps)
73+
├── Run 2: stepNumber 1 → 2 (2 steps)
74+
└── Run 3: stepNumber 1 → 2 → 3 (3 steps)
75+
```
76+
77+
The `maxSteps` limit applies to the Job's total steps, not individual Runs.
2878

2979
### Stopping and resuming
3080

@@ -36,10 +86,12 @@ npx perstack run my-expert "query" --max-steps 50
3686
|----------------|----------|-------------|
3787
| `attemptCompletion` (no remaining todos) | Task complete | N/A |
3888
| `attemptCompletion` (remaining todos) | Continue loop | N/A (loop continues) |
39-
| `maxSteps` reached | Graceful stop at step boundary | Last checkpoint |
40-
| SIGTERM/SIGINT | Immediate stop | Previous checkpoint |
89+
| `maxSteps` reached | Graceful stop | Coordinator's last checkpoint |
90+
| SIGTERM/SIGINT | Immediate stop | Coordinator's previous checkpoint |
4191

42-
Checkpoints enable pause/resume across process restarts — useful for long-running tasks, debugging, and resource management.
92+
<Callout type="warning">
93+
`--continue` and `--resume-from` only work with the Coordinator Expert's checkpoints. You cannot resume from a Delegated Expert's checkpoint.
94+
</Callout>
4395

4496
## Deterministic state
4597

@@ -69,16 +121,19 @@ This combines **Event Sourcing** (complete history) with **Checkpoint/Restore**
69121

70122
### The `perstack/` directory
71123

72-
The runtime stores execution history in `perstack/runs/` within the workspace:
124+
The runtime stores execution history in `perstack/jobs/` within the workspace:
73125

74126
```
75127
/workspace
76128
└── perstack/
77-
└── runs/
78-
└── {runId}/
79-
├── run-setting.json # Run configuration
80-
├── checkpoint-{timestamp}-{step}-{id}.json # Execution snapshots
81-
└── event-{timestamp}-{step}-{type}.json # Execution events
129+
└── jobs/
130+
└── {jobId}/
131+
├── job.json # Job metadata
132+
└── runs/
133+
└── {runId}/
134+
├── run-setting.json # Run configuration
135+
├── checkpoint-{timestamp}-{step}-{id}.json
136+
└── event-{timestamp}-{step}-{type}.json
82137
```
83138

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

‎docs/content/using-experts/running-experts.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ npx perstack run my-expert "query"
3131

3232
Outputs JSON events to stdout. Each line is a JSON object representing an execution event.
3333

34+
Each invocation creates a new **Job** containing one or more **Runs**. See [State Management](/using-experts/state-management) for details on the execution hierarchy.
35+
3436
Use `perstack run` for:
3537
- Production deployments
3638
- CI/CD pipelines
@@ -58,5 +60,5 @@ For the complete list of options, see [CLI Reference](/references/cli).
5860

5961
## What's next
6062

61-
- [State Management](/using-experts/state-management) — pausing, resuming, and checkpoints
63+
- [State Management](/using-experts/state-management) — Jobs, Runs, and checkpoints
6264
- [CLI Reference](/references/cli) — all commands and options

0 commit comments

Comments
 (0)