mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-02 23:56:24 +08:00
77 lines
3.0 KiB
Plaintext
77 lines
3.0 KiB
Plaintext
---
|
|
title: Jobs & Parallel Execution
|
|
sidebarTitle: Jobs
|
|
description: Parallel job scheduling and the job state machine
|
|
---
|
|
|
|
Every unit of work in IronClaw is a **job**. Jobs run in parallel, each with isolated context, and each progressing through a defined state machine until they complete, fail, or get recovered.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
```bash
|
|
# Maximum parallel jobs
|
|
MAX_PARALLEL_JOBS=5
|
|
|
|
# Sandbox timeout (affects when jobs are considered stuck)
|
|
SANDBOX_TIMEOUT_SECS=1800
|
|
```
|
|
|
|
---
|
|
|
|
## Job State Machine
|
|
|
|
```
|
|
Pending
|
|
↓
|
|
InProgress ──────────────┬──► Completed
|
|
↑ │
|
|
│ (self-repair) └──► Failed
|
|
│
|
|
Stuck ────────────────────► Failed (if unrecoverable)
|
|
```
|
|
|
|
### States
|
|
|
|
| State | Description | Next States |
|
|
|----------------|-----------------------------------------------------|-------------------------------|
|
|
| **Pending** | Job created, queued for a worker slot | InProgress |
|
|
| **InProgress** | Worker actively running — LLM calls, tool execution | Completed, Failed, Stuck |
|
|
| **Completed** | Job finished successfully | — (terminal) |
|
|
| **Failed** | Unrecoverable error or explicit cancellation | — (terminal) |
|
|
| **Stuck** | No progress detected within timeout window | InProgress (recovery), Failed |
|
|
|
|
### Transitions
|
|
|
|
A job enters **Stuck** when the self-repair system detects it has been InProgress with no activity for longer than the configured timeout. The system then attempts recovery by re-entering InProgress with a fresh worker. If recovery fails repeatedly, the job transitions to **Failed**.
|
|
|
|
---
|
|
|
|
## Parallel Execution
|
|
|
|
IronClaw runs multiple jobs concurrently. Each job has its own isolated context — memory, tool call history, and conversation state.
|
|
|
|
| Config Variable | Default | Description |
|
|
|---------------------|---------|--------------------------------------|
|
|
| `MAX_PARALLEL_JOBS` | `5` | Maximum concurrent jobs per instance |
|
|
|
|
When all job slots are occupied, new jobs queue as **Pending** until a slot opens. The scheduler dispatches queued jobs in order of creation time.
|
|
|
|
<Note>
|
|
Increasing `MAX_PARALLEL_JOBS` increases LLM API concurrency. Set it according to your API rate limits and available system resources.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Job Tools
|
|
|
|
Four built-in tools let the agent manage jobs at runtime:
|
|
|
|
| Tool | Description |
|
|
|--------------|----------------------------------------------------------------|
|
|
| `create_job` | Create a new job with a given description and optional context |
|
|
| `list_jobs` | List all active jobs with their current state and metadata |
|
|
| `job_status` | Get detailed status for a specific job by ID |
|
|
| `cancel_job` | Cancel an InProgress or Pending job |
|