aiwg
Version:
Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo
397 lines (342 loc) • 9.78 kB
YAML
# Agent Loop State Schema
# Per-loop state tracking for multi-loop support
# Issue: #268
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/ralph-loop-state/v2"
title: "Agent Loop State Schema"
description: |
Schema for per-loop state.json file. Each active loop has its own
state file in .aiwg/ralph/loops/{loop_id}/state.json
type: object
required:
- version
- loop_id
- status
- iteration
properties:
version:
type: string
pattern: "^2\\.\\d+\\.\\d+$"
default: "2.0.0"
description: "State schema version"
loop_id:
type: string
pattern: "^ralph-[a-z0-9-]+-[a-f0-9]{8}$"
description: |
Unique loop identifier matching registry entry.
Format: ralph-{slug}-{uuid8}
status:
type: string
enum:
- running # Actively iterating
- paused # Paused by user (ralph-pause)
- completing # Final verification/cleanup
- completed # Successfully finished
- failed # Failed to meet completion criteria
- aborted # User aborted (ralph-abort)
- crashed # Abnormal termination
description: "Current loop status"
iteration:
type: integer
minimum: 0
description: "Current iteration number (0-based)"
task:
type: string
description: "Task description from ralph command"
completion_criteria:
type: string
description: "Completion criteria (command or description)"
started_at:
type: string
format: date-time
description: "Loop start timestamp"
last_updated:
type: string
format: date-time
description: "Last state update timestamp"
completed_at:
type: string
format: date-time
nullable: true
description: "Completion timestamp (null if not completed)"
owner:
type: string
description: "User or system that started the loop"
pid:
type: integer
nullable: true
description: "Process ID of controlling process (null if orphaned)"
working_directory:
type: string
description: "Working directory for this loop"
configuration:
$ref: "#/$defs/LoopConfiguration"
progress:
$ref: "#/$defs/ProgressTracking"
metrics:
$ref: "#/$defs/LoopMetrics"
last_checkpoint:
type: string
nullable: true
description: "Path to most recent checkpoint"
error_context:
type: object
nullable: true
description: "Error details if status is failed/crashed"
properties:
error_message:
type: string
error_timestamp:
type: string
format: date-time
stack_trace:
type: string
recovery_attempted:
type: boolean
$defs:
LoopConfiguration:
type: object
description: "Loop execution configuration"
properties:
max_iterations:
type: integer
minimum: 1
default: 200
timeout_minutes:
type: integer
nullable: true
description: "Overall timeout (null = no timeout)"
interactive:
type: boolean
default: false
description: "Interactive mode (prompt for decisions)"
auto_test:
type: boolean
default: true
description: "Automatically run tests before completion"
checkpoint_interval:
type: integer
default: 1
description: "Create checkpoint every N iterations"
execution_mode:
type: string
enum: [strict, seeded, logged, default]
default: default
ProgressTracking:
type: object
description: "Progress and completion tracking"
properties:
completion_checks:
type: array
items:
type: object
properties:
iteration:
type: integer
timestamp:
type: string
format: date-time
passed:
type: boolean
output:
type: string
description: "History of completion criteria checks"
last_completion_check:
type: object
nullable: true
properties:
iteration:
type: integer
timestamp:
type: string
format: date-time
passed:
type: boolean
output:
type: string
estimated_completion:
type: string
nullable: true
description: "Estimated completion time (if predictable)"
LoopMetrics:
type: object
description: "Execution metrics"
properties:
total_iterations:
type: integer
description: "Total iterations executed"
successful_iterations:
type: integer
description: "Iterations that made progress"
failed_iterations:
type: integer
description: "Iterations that failed"
total_tokens:
type: integer
description: "Total tokens consumed"
total_cost_usd:
type: number
description: "Total cost in USD"
total_duration_seconds:
type: integer
description: "Total execution time"
average_iteration_time_seconds:
type: number
description: "Average time per iteration"
# State Transitions
state_transitions:
allowed:
running:
- paused
- completing
- aborted
- crashed
- failed
paused:
- running
- aborted
completing:
- completed
- failed
- crashed
completed:
- [] # Terminal state
failed:
- [] # Terminal state
aborted:
- [] # Terminal state
crashed:
- [] # Terminal state
# Operations
operations:
create_state:
description: "Initialize state for new loop"
steps:
- generate_loop_id
- create_directory: ".aiwg/ralph/loops/{loop_id}/"
- initialize_state_object
- write_state_file
- register_in_registry
update_state:
description: "Update state during execution"
validation:
- loop_id_exists
- valid_status_transition
steps:
- load_current_state
- apply_updates
- update_last_updated
- write_state_file
- update_registry_heartbeat
transition_status:
description: "Change loop status"
validation:
- valid_status_transition
steps:
- load_current_state
- validate_transition
- update_status
- update_last_updated
- write_state_file
- update_registry
record_completion_check:
description: "Record completion criteria check result"
steps:
- load_current_state
- append_to_completion_checks
- update_last_completion_check
- if_passed: transition_to_completing
- write_state_file
# File Layout
file_layout:
structure: |
.aiwg/ralph/
├── registry.json # Multi-loop registry
└── loops/
├── ralph-fix-tests-a1b2c3d4/
│ ├── state.json # Loop state
│ ├── checkpoints/
│ │ ├── iteration-001.json.gz
│ │ └── iteration-002.json.gz
│ └── analytics/
│ └── analytics.json
└── ralph-add-docs-b2c3d4e5/
├── state.json
└── ...
# Example state file
examples:
- version: "2.0.0"
loop_id: "ralph-fix-tests-a1b2c3d4"
status: running
iteration: 5
task: "fix all TypeScript errors"
completion_criteria: "npx tsc --noEmit passes"
started_at: "2026-02-02T21:00:00Z"
last_updated: "2026-02-02T21:05:30Z"
completed_at: null
owner: "roctinam"
pid: 12345
working_directory: "/mnt/dev-inbox/jmagly/ai-writing-guide"
configuration:
max_iterations: 200
timeout_minutes: 60
interactive: false
auto_test: true
checkpoint_interval: 1
execution_mode: default
progress:
completion_checks:
- iteration: 3
timestamp: "2026-02-02T21:03:00Z"
passed: false
output: "Found 12 errors"
- iteration: 5
timestamp: "2026-02-02T21:05:00Z"
passed: false
output: "Found 8 errors"
last_completion_check:
iteration: 5
timestamp: "2026-02-02T21:05:00Z"
passed: false
output: "Found 8 errors"
metrics:
total_iterations: 5
successful_iterations: 5
failed_iterations: 0
total_tokens: 25000
total_cost_usd: 0.125
total_duration_seconds: 330
average_iteration_time_seconds: 66
last_checkpoint: ".aiwg/ralph/loops/ralph-fix-tests-a1b2c3d4/checkpoints/iteration-005.json.gz"
# CLI Integration
cli_commands:
view_state:
command: "aiwg ralph-status {loop_id}"
description: "View loop state"
pause:
command: "aiwg ralph-pause {loop_id}"
description: "Transition to paused status"
resume:
command: "aiwg ralph-resume {loop_id}"
description: "Transition from paused to running"
abort:
command: "aiwg ralph-abort {loop_id}"
description: "Transition to aborted status"
# Backward Compatibility
backward_compatibility:
single_loop_mode:
legacy_path: ".aiwg/ralph/current-loop.json"
migration: |
If only one loop active and legacy path exists:
- Read legacy current-loop.json
- Convert to new state format
- Write to .aiwg/ralph/loops/{loop_id}/state.json
- Keep legacy file for tools that expect it
# References
references:
implementation:
- "#268" # Multi-loop state schemas
related:
- "@agentic/code/addons/ralph/schemas/loop-registry.yaml"
- "@agentic/code/addons/ralph/schemas/checkpoint.yaml"
- "@agentic/code/addons/ralph/schemas/iteration-analytics.yaml"