Implements all four automatic checkpoint triggers defined in the specification
for the Execute phase of the plan lifecycle:
- before_tool_execute: Checkpoint created before any tool with writes=True runs
- after_tool_execute: Checkpoint created after a write tool completes successfully
- on_subplan_spawn: Checkpoint created immediately after a child plan is spawned
- on_error: Checkpoint created after any unrecoverable error in the Execute phase
Changes:
- tool/runner.py: Added optional CheckpointService and auto_checkpoint_triggers
parameters to ToolRunner. Checkpoint hooks fire around write-tool execution
when a CheckpointService is wired. Exported DEFAULT_AUTO_TRIGGERS as a public
constant (single source of truth). Made is_trigger_active() public so callers
can query the active trigger set without accessing private attributes.
- application/services/subplan_execution_service.py: Added optional
CheckpointService, auto_checkpoint_triggers, and parent_plan_id parameters.
on_subplan_spawn checkpoint fires in _execute_one_with_retry before the
first execution attempt. Now imports DEFAULT_AUTO_TRIGGERS from runner.py
(DRY fix).
- application/services/plan_executor.py: Added _is_auto_trigger_active() helper
and on_error checkpoint hooks in both _run_execute_with_stub() and
_run_execute_with_runtime() error paths. Delegates to
ToolRunner.is_trigger_active() instead of accessing private attributes
(module boundary fix).
- application/services/config_service.py: Registered new config key
core.checkpoints.auto_create_on (default: all four triggers enabled) with
env var CLEVERAGENTS_CHECKPOINT_AUTO_CREATE_ON.
- application/services/llm_actors.py: Replaced Any type for lifecycle_service
with PlanLifecycleProtocol (typed Protocol) and tool_runner with ToolRunner
type annotation. Eliminates Any usage for injected dependencies.
Tests:
- features/checkpoint_auto_triggers.feature: 15 Behave scenarios covering all
four triggers, disable-trigger behavior, no-checkpoint-service fallback, and
config key registration.
- features/steps/checkpoint_auto_triggers_tool_steps.py: Step definitions for
ToolRunner and config service scenarios (split from original 519-line file).
- features/steps/checkpoint_auto_triggers_executor_steps.py: Step definitions
for SubplanExecutionService and PlanExecutor scenarios (split from original).
Closes#3439
ISSUES CLOSED: #3439
freemo