react-agent-harness 0.0.1__tar.gz → 0.0.2__tar.gz

{react_agent_harness-0.0.1/react_agent_harness.egg-info → react_agent_harness-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: react-agent-harness
-Version: 0.0.1
+Version: 0.0.2
 Summary: Multi-agent LLM orchestration: hybrid DAG planning, two-tier memory, streaming
 Requires-Python: >=3.10
 License-File: LICENSE

{react_agent_harness-0.0.1 → react_agent_harness-0.0.2}/README.md

@@ -37,7 +37,8 @@ harness/runtime.py          AgentRuntime — single entry point, wire once run a
 harness/events.py           BusEvent + EventType — canonical event vocabulary
 harness/llm/openai.py       OpenAILLM — OpenAI adapter with usage + cost tracking
 harness/annotation.py       Annotation store + AnnotationHook — RLHF trajectory capture
-harness/hitl.py             HITL approval gate — interactive CLI, Redis checkpoint/resume
+harness/hitl.py             HITL approval gate — interactive CLI, session-allow list
+harness/checkpoint.py       CheckpointStore + _ResumeHint + maybe_resume_key — pluggable run-state persistence (file + Redis); auto-resume built into dispatch_stream / run_stream
 harness/otel.py             OTELHook — OpenTelemetry span exporter (opt-in)
 harness/executor_bridge.py  ExecutorBridge + ExecutorTool — controlled subprocess launcher with optional Docker sandboxing
 orchestrator/planner.py     Hybrid DAG orchestrator — plan, replan, synthesize
@@ -564,7 +565,7 @@ agents.register(AgentConfig(
     hitl_tools=["write_file", "delete_file"],   # these two require human approval
 ))
 
-# AgentRuntime auto-creates a FileApprovalStore when hitl_tools are present.
+# AgentRuntime auto-creates a FileCheckpointStore when hitl_tools are present.
 runtime = AgentRuntime(...)
 await runtime.run_agent("file_agent", "clean up the logs directory")
 ```
@@ -573,19 +574,19 @@ Checkpoints are written to `~/.agent-harness/checkpoints/` by default.
 Override the directory:
 
 ```python
-from harness.hitl import FileApprovalStore
+from harness.checkpoint import FileCheckpointStore
 
-runtime = AgentRuntime(..., approval_store=FileApprovalStore("/var/lib/myapp/hitl"))
+runtime = AgentRuntime(..., checkpoint_store=FileCheckpointStore("/var/lib/myapp/ckp"))
 ```
 
 For Redis-backed storage (shared across processes or machines):
 
 ```python
 import redis.asyncio as aioredis
-from harness.hitl import RedisApprovalStore
+from harness.checkpoint import RedisCheckpointStore
 
 client = aioredis.from_url("redis://localhost:6379", decode_responses=True)
-runtime = AgentRuntime(..., approval_store=RedisApprovalStore(client))
+runtime = AgentRuntime(..., checkpoint_store=RedisCheckpointStore(client))
 ```
 
 When the agent calls `write_file` or `delete_file` a prompt appears:
@@ -597,46 +598,112 @@ When the agent calls `write_file` or `delete_file` a prompt appears:
   Tool:  delete_file
   Args:  {"path": "/var/log/app.log"}
   Agent: file_agent  step=2
-  Run:   3f7a1b2c-...
+  Run:   3f7a1b2c-...:file_agent
   ID:    a1b2-c3d4
 ────────────────────────────────────────────────────────────
-  Approve? [y/n/correction]:
+  y = approve once  |  a = allow 'delete_file' for session  |  n = reject  |  <text> = steer
+  Ctrl-C to pause. Resume: python my_script.py --resume 3f7a1b2c-...:file_agent
+────────────────────────────────────────────────────────────
+  Approve? [y/n/a/correction]:
 ```
 
 **Prompt semantics:**
 
 | Input | Effect |
 |---|---|
-| `y` / `yes` | Tool runs |
+| `y` / `yes` | Tool runs once |
 | `n` / `no` | Tool skipped; agent sees a rejection observation |
+| `a` / `allow` | Tool runs **and** added to session allow-list; no further prompts for this tool (or command prefix for shell-like tools) |
 | any other text | Correction: tool skipped, text injected into `WorkingMemory` as a user message; LLM self-corrects on the next step |
 
+For shell-like tools (`shell`, `bash`, `run`, `exec`), `a` allows the **first
+word** of the command — e.g. typing `a` when approving `shell git commit ...`
+allows all `git` commands for the session but still prompts for `shell rm ...`.
+
 **Wall-time budget** is suspended while waiting for input — human think-time
 does not count against `max_wall_time_seconds`.
 
+### Step-level checkpointing
+
+Enable periodic crash-resume independent of HITL:
+
+```python
+AgentConfig(
+    agent_id="long_runner",
+    ...
+    checkpoint_every=3,   # checkpoint before every 3rd step (0 = disabled)
+)
+```
+
+The same `CheckpointStore` is used for both HITL and step checkpoints. Resume
+works with `runtime.resume(key)` regardless of how the checkpoint was created.
+
+### Checkpoint namespacing
+
+Each agent writes to its own key so orchestrated runs never overwrite each other:
+
+| Path | Checkpoint key | Stored at |
+|---|---|---|
+| Single-agent (`run_agent`, `run_routed`) | `<run_id>:<agent_id>` | `~/.agent-harness/checkpoints/<run_id>:<agent_id>.json` |
+| Orchestrated (`run`, `run_stream`) | `<run_id>` (orchestrator) + `<run_id>:<agent_id>` (each agent) | one file per agent, one file for the orchestrator |
+
+The orchestrator checkpoint stores the goal, the full plan, completed task
+results, and the replan count. It is updated after each parallel batch
+completes and deleted on clean `DONE`.
+
 ### Crash / Ctrl-C resume
 
-The run checkpoint (step number + full `WorkingMemory`) is written to Redis
-before every approval prompt. The banner prints the exact command to resume:
+The checkpoint (step number + full `WorkingMemory`) is written before every
+HITL prompt and (if `checkpoint_every > 0`) at each periodic step.
+
+**What the banner prints:**
 
+- **Single-agent run**: `--resume <run_id>:<agent_id>` — restores just that agent.
+- **Orchestrated run**: `--resume <run_id>` — restores the full orchestration.
+
+```
+  Run interrupted — checkpoint saved.
+  Resume: python my_script.py --resume 3f7a1b2c-...
 ```
-  Ctrl-C to pause. Resume: python my_script.py --resume 3f7a1b2c-...
+
+**Auto-resume — no script changes required.** When `checkpoint_store` is
+configured, `dispatch_stream` and `run_stream` detect `--resume <key>` in
+`sys.argv` automatically. Your existing script resumes transparently:
+
+```bash
+python my_script.py --resume 3f7a1b2c-...
 ```
 
-Add one line to your script to handle it:
+The runtime detects the flag, loads the checkpoint, and streams events
+identically to a fresh run. Scripts need zero resume-specific code.
+
+For **explicit control** — streaming resume or blocking resume:
 
 ```python
-from harness.hitl import maybe_resume
+# streaming (same event sequence as the original run)
+async for event in runtime.resume_stream("3f7a1b2c-..."):
+    ...
 
-result = await maybe_resume(runtime) or await runtime.run_agent("agent", "task")
+# blocking
+result = await runtime.resume("3f7a1b2c-...:file_agent")  # single-agent
+result = await runtime.resume("3f7a1b2c-...")              # orchestrated
 ```
 
-`maybe_resume` checks `sys.argv` for `--resume <run_id>`. If present it
-restores the checkpoint from Redis, re-displays the approval banner, and
-continues the run. If absent it returns `None` so the normal path runs.
-Re-running the same script with `--resume` is all the human needs to do.
+Both `resume_stream` and `resume` auto-detect the checkpoint type (agent vs
+orchestrator) from the stored data and call the right path.
+
+If you need the resume key from `sys.argv` directly:
+
+```python
+from harness.checkpoint import maybe_resume_key
+
+key = maybe_resume_key()   # returns None if --resume is absent
+```
 
-Checkpoints expire after 24 hours (configurable via `RedisApprovalStore(ttl_seconds=...)`).
+**Orchestrated resume** skips completed tasks (injects their stored results
+directly into the synthesis step) and re-runs only the tasks that had not yet
+finished. If an individual agent's HITL checkpoint is still on disk, that agent
+is resumed at its saved step rather than re-run from scratch.
 
 ### Correction steering and replanning
 
@@ -646,9 +713,10 @@ When the human types a correction instead of y/n:
   `WorkingMemory`. The LLM sees it on the next think step and self-corrects
   without replanning. Suitable for redirecting tool choice or adjusting
   parameters.
-- **Multi-agent orchestrated run**: if the correction implies a different agent
-  or task structure, call `resume_agent` with updated context instead, which
-  re-enters the orchestrator.
+- **Orchestrated run**: the correction steers only the current agent. Because
+  the orchestrator checkpoint records task results as they complete, a full
+  `runtime.resume(run_id)` after the agent finishes will continue the remaining
+  tasks with correct upstream context.
 
-The `annotation_store` and `approval_store` are independent — both can be wired
-simultaneously for RLHF data collection with HITL review.
+The `annotation_store` and `checkpoint_store` are independent — both can be
+wired simultaneously for RLHF data collection with HITL review.

{react_agent_harness-0.0.1 → react_agent_harness-0.0.2}/agents/base.py

@@ -35,6 +35,7 @@ from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Any, Final
 
+from harness.checkpoint import _ResumeHint
 from harness.events import BusEvent, EventType
 from harness.utils import fire
 from memory.manager import MemoryManager
@@ -61,6 +62,7 @@ class AgentConfig:
     confidence_from_llm: bool = True  # if False, confidence=1.0 on success
     working_memory_max_tokens: int = 8000  # WorkingMemory eviction threshold; tune per agent
     hitl_tools: list[str] = None  # tools requiring human approval; None = no HITL
+    checkpoint_every: int = 0  # write a resumable checkpoint every N steps; 0 = disabled
 
     def __post_init__(self):
         if self.hitl_tools is None:
@@ -129,7 +131,7 @@ class BaseAgent:
         tracer,
         guard,
         llm,
-        approval_store: Any | None = None,  # RedisApprovalStore — enables HITL + resume
+        checkpoint_store: Any | None = None,  # FileCheckpointStore / RedisCheckpointStore
     ) -> None:
         self.config = config
         self.role = config.role  # exposed for orchestrator planner prompt
@@ -138,10 +140,14 @@ class BaseAgent:
         self._tracer = tracer
         self._guard = guard
         self._llm = llm
-        self._approval_store = approval_store
+        self._checkpoint_store = checkpoint_store
         self._working_memory: WorkingMemory | None = None
         self._task: str = ""
         self._last_think_error: str | None = None
+        self._ckp_id: str = ""  # f"{run_id}:{agent_id}" — unique per agent per run
+        self._resume_key: str = (
+            ""  # key printed in --resume banner; set by orchestrator to outer run_id
+        )
 
     # ── Streaming entry point (canonical) ─────────────────────────────────────
 
@@ -151,6 +157,9 @@ class BaseAgent:
         run_id: str | None = None,
     ) -> AsyncGenerator[BusEvent, None]:
         run_id = run_id or str(uuid.uuid4())
+        self._ckp_id = f"{run_id}:{self.config.agent_id}"
+        if not self._resume_key:
+            self._resume_key = self._ckp_id
         self._task = task
         self._working_memory = WorkingMemory(
             llm=self._llm,
@@ -161,8 +170,17 @@ class BaseAgent:
         await self._working_memory.append("system", system, pinned=True)
         await self._working_memory.append("user", task)
 
-        async for event in self._run_stream_internal(run_id):
-            yield event
+        async with _ResumeHint(
+            self._resume_key,
+            self._checkpoint_store,
+            f"Agent {self.config.agent_id}",
+            check_key=self._ckp_id,
+        ) as hint:
+            async for event in self._run_stream_internal(run_id):
+                if event.type == EventType.TASK_DONE:
+                    await self._clear_checkpoint(run_id)
+                    hint.done = True
+                yield event
 
     async def _resume_stream(
         self,
@@ -177,13 +195,25 @@ class BaseAgent:
         The approval prompt is shown again; once the human responds the
         tool runs (or the correction is injected) before the loop continues.
         """
+        self._ckp_id = f"{run_id}:{self.config.agent_id}"
+        if not self._resume_key:
+            self._resume_key = self._ckp_id
         if pending:
             async for event in self._replay_pending_step(run_id, pending):
                 yield event
             start_step = pending["step"] + 1
 
-        async for event in self._run_stream_internal(run_id, start_step=start_step):
-            yield event
+        async with _ResumeHint(
+            self._resume_key,
+            self._checkpoint_store,
+            f"Agent {self.config.agent_id}",
+            check_key=self._ckp_id,
+        ) as hint:
+            async for event in self._run_stream_internal(run_id, start_step=start_step):
+                if event.type == EventType.TASK_DONE:
+                    await self._clear_checkpoint(run_id)
+                    hint.done = True
+                yield event
 
     async def _run_stream_internal(
         self,
@@ -246,11 +276,31 @@ class BaseAgent:
 
     # ── ReAct Loop (stream) ───────────────────────────────────────────────────
 
+    async def _write_step_checkpoint(self, run_id: str, step: int) -> None:
+        if self._checkpoint_store is None:
+            return
+        await self._checkpoint_store.write(
+            self._ckp_id,
+            {
+                "run_id": run_id,
+                "agent_id": self.config.agent_id,
+                "task": self._task,
+                "step": step,
+                "memory": self._working_memory.to_dict(),
+            },
+        )
+
     async def _react_stream(
         self, run_id: str, start_step: int = 0
     ) -> AsyncGenerator[BusEvent, None]:
         for step in range(start_step, self.config.max_steps):
             self._guard.check()
+            if (
+                self._checkpoint_store is not None
+                and self.config.checkpoint_every > 0
+                and step % self.config.checkpoint_every == 0
+            ):
+                await self._write_step_checkpoint(run_id, step)
 
             # Think — yields TOKEN events when the LLM client supports streaming.
             response = None
@@ -337,7 +387,9 @@ class BaseAgent:
                     if approval is None or approval.approved:
                         approved.append(act)
                     elif approval.correction:
-                        await self._inject_human_guidance(response, approval.correction, run_id)
+                        await self._inject_human_guidance(
+                            response, approval.correction, run_id, step
+                        )
                         correction_injected = True
                         break
                     # else: rejected — drop from batch silently
@@ -366,7 +418,7 @@ class BaseAgent:
                         for act in parallel_actions
                     ]
                 )
-                await self._clear_checkpoint(run_id)
+                await self._commit_checkpoint(run_id, step)
 
                 combined: list[dict] = []
                 for i, (act, obs) in enumerate(zip(parallel_actions, observations, strict=False)):
@@ -611,14 +663,17 @@ class BaseAgent:
         Returns ApprovalResponse if the tool is gated, None if not.
         Writes a crash-resumable checkpoint to the store before blocking on stdin.
         """
-        if not (self._approval_store and tool_name in self.config.hitl_tools):
+        if not (self._checkpoint_store and tool_name in self.config.hitl_tools):
             return None
 
-        from harness.hitl import ApprovalRequest, request_approval
+        from harness.hitl import ApprovalRequest, is_session_allowed, request_approval
+
+        if is_session_allowed(tool_name, tool_args):
+            return None  # fast-path: human already allowed this tool/prefix for session
 
         approval_id = str(uuid.uuid4())
-        await self._approval_store.write_checkpoint(
-            run_id,
+        await self._checkpoint_store.write(
+            self._ckp_id,
             {
                 "run_id": run_id,
                 "agent_id": self.config.agent_id,
@@ -637,14 +692,13 @@ class BaseAgent:
         return await request_approval(
             ApprovalRequest(
                 approval_id=approval_id,
-                run_id=run_id,
+                run_id=self._resume_key,  # standalone: ckp_id; orchestrated: outer run_id
                 agent_id=self.config.agent_id,
                 tool=tool_name,
                 args=tool_args,
                 step=step,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             ),
-            self._approval_store,
             self._guard,
         )
 
@@ -666,24 +720,49 @@ class BaseAgent:
         approval = await self._gate_tool(run_id, step, tool_name, tool_args, response)
         if approval is not None:
             if approval.correction:
-                await self._inject_human_guidance(response, approval.correction, run_id)
+                await self._inject_human_guidance(response, approval.correction, run_id, step)
                 return _HITL_CORRECTION
             if not approval.approved:
-                await self._clear_checkpoint(run_id)
+                await self._commit_checkpoint(run_id, step)
                 return f"Tool rejected by human: {approval.correction or 'no reason given'}"
         obs = await self._execute_tool(tool_name, tool_args)
-        await self._clear_checkpoint(run_id)
+        if approval is not None:
+            # HITL was involved — overwrite pending checkpoint with clean state.
+            # Non-HITL tools leave the step checkpoint intact for the next iteration.
+            await self._commit_checkpoint(run_id, step)
         return obs
 
-    async def _inject_human_guidance(self, response: dict, correction: str, run_id: str) -> None:
-        """Append human correction to WorkingMemory and clear the checkpoint."""
+    async def _inject_human_guidance(
+        self, response: dict, correction: str, run_id: str, step: int
+    ) -> None:
+        """Append human correction to WorkingMemory and commit a clean checkpoint."""
         await self._working_memory.append("assistant", json.dumps(response))
         await self._working_memory.append("user", f"Human guidance: {correction}")
-        await self._clear_checkpoint(run_id)
+        await self._commit_checkpoint(run_id, step)
+
+    async def _commit_checkpoint(self, run_id: str, step: int) -> None:
+        """Overwrite checkpoint with current state (no pending field).
+
+        Called after HITL resolves or a tool completes so the stored state
+        always reflects reality — no stale 'pending' approval marker, and
+        the step position is preserved for crash-resume.
+        """
+        if self._checkpoint_store is None:
+            return
+        await self._checkpoint_store.write(
+            self._ckp_id,
+            {
+                "run_id": run_id,
+                "agent_id": self.config.agent_id,
+                "task": self._task,
+                "step": step,
+                "memory": self._working_memory.to_dict(),
+            },
+        )
 
     async def _clear_checkpoint(self, run_id: str) -> None:
-        if self._approval_store:
-            await self._approval_store.clear_checkpoint(run_id)
+        if self._checkpoint_store:
+            await self._checkpoint_store.delete(self._ckp_id)
 
     async def _replay_pending_step(
         self,
@@ -701,19 +780,18 @@ class BaseAgent:
         approval = await request_approval(
             ApprovalRequest(
                 approval_id=pending["approval_id"],
-                run_id=run_id,
+                run_id=self._resume_key,  # standalone: ckp_id; orchestrated: outer run_id
                 agent_id=self.config.agent_id,
                 tool=tool_name,
                 args=tool_args,
                 step=step,
                 timestamp=datetime.now(timezone.utc).isoformat(),
             ),
-            self._approval_store,
             self._guard,
         )
 
         if approval.correction:
-            await self._inject_human_guidance(llm_response, approval.correction, run_id)
+            await self._inject_human_guidance(llm_response, approval.correction, run_id, step)
             return
 
         observation = (
@@ -740,7 +818,7 @@ class BaseAgent:
                 else observation
             )
             await self._working_memory.append("user", f"Observation: {obs_text}")
-        await self._clear_checkpoint(run_id)
+        await self._commit_checkpoint(run_id, step)
 
 
 # ── Response normalization (module-level for testability) ────────────────────

react_agent_harness-0.0.2/harness/checkpoint.py

@@ -0,0 +1,165 @@
+"""
+harness/checkpoint.py — Pluggable checkpoint store for run state persistence.
+
+Used by both the HITL approval gate (crash-resume) and periodic step
+checkpointing (checkpoint_every on AgentConfig).
+
+A checkpoint is a plain dict written under a run_id key.  The schema is
+defined by the caller — agents write {run_id, agent_id, task, step, memory}
+with an optional {pending: ...} field added by the HITL gate.
+
+Two backends ship out of the box:
+
+    FileCheckpointStore  — zero deps, one JSON file per run_id
+    RedisCheckpointStore — for distributed / multi-process setups
+
+Both share the same three-method interface so callers are backend-agnostic.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+
+def maybe_resume_key() -> str | None:
+    """
+    Extract the --resume <key> value from sys.argv, or return None.
+
+    Called automatically by AgentRuntime.dispatch_stream / run_stream so that
+    scripts resume transparently without any resume-specific code.  Also
+    available for scripts that need the key explicitly.
+    """
+    args = sys.argv[1:]
+    if "--resume" not in args:
+        return None
+    idx = args.index("--resume")
+    if idx + 1 >= len(args):
+        print("Usage: --resume <ckp_id>", file=sys.stderr)
+        sys.exit(1)
+    return args[idx + 1]
+
+
+class FileCheckpointStore:
+    """
+    Zero-dependency checkpoint store backed by JSON files.
+
+    Default directory: ~/.agent-harness/checkpoints/
+    Override with the CHECKPOINT_DIR env var or by passing checkpoint_dir.
+    """
+
+    def __init__(self, checkpoint_dir: str | Path | None = None) -> None:
+        self._dir = Path(
+            checkpoint_dir
+            or os.environ.get("CHECKPOINT_DIR", Path.home() / ".agent-harness" / "checkpoints")
+        )
+        self._dir.mkdir(parents=True, exist_ok=True)
+
+    def _path(self, run_id: str) -> Path:
+        return self._dir / f"{run_id}.json"
+
+    async def write(self, run_id: str, data: dict) -> None:
+        self._path(run_id).write_text(json.dumps(data, default=str, indent=2))
+
+    async def read(self, run_id: str) -> dict | None:
+        path = self._path(run_id)
+        if not path.exists():
+            return None
+        return json.loads(path.read_text())
+
+    async def delete(self, run_id: str) -> None:
+        path = self._path(run_id)
+        if path.exists():
+            path.unlink()
+
+    @classmethod
+    def purge_old(cls, days: int = 7, checkpoint_dir: str | Path | None = None) -> int:
+        """Delete checkpoint files older than `days`. Returns count removed."""
+        store = cls(checkpoint_dir)
+        cutoff = time.time() - days * 86_400
+        removed = 0
+        for p in store._dir.glob("*.json"):
+            if p.stat().st_mtime < cutoff:
+                p.unlink()
+                removed += 1
+        return removed
+
+
+class RedisCheckpointStore:
+    """
+    Checkpoint store backed by Redis.
+
+    Checkpoints expire after ttl_seconds (default 24 h).
+
+    Usage:
+        import redis.asyncio as redis
+        client = redis.Redis(host="localhost", decode_responses=True)
+        store = RedisCheckpointStore(client)
+    """
+
+    _KEY = "ckp:{}"
+
+    def __init__(self, client: Any, ttl_seconds: int = 86_400) -> None:
+        self._r = client
+        self._ttl = ttl_seconds
+
+    async def write(self, run_id: str, data: dict) -> None:
+        await self._r.set(self._KEY.format(run_id), json.dumps(data, default=str), ex=self._ttl)
+
+    async def read(self, run_id: str) -> dict | None:
+        raw = await self._r.get(self._KEY.format(run_id))
+        return json.loads(raw) if raw else None
+
+    async def delete(self, run_id: str) -> None:
+        await self._r.delete(self._KEY.format(run_id))
+
+
+class _ResumeHint:
+    """
+    Async context manager that prints a --resume hint to stderr on interruption,
+    but only when a checkpoint actually exists in the store.
+
+    Two keys:
+      check_key  — where the checkpoint lives in the store (verified on exit).
+                   Defaults to resume_key when not supplied.
+      resume_key — printed in the hint; what the human passes to --resume.
+
+    For orchestrated agents these differ: check_key is the namespaced agent key
+    (f"{run_id}:{agent_id}") while resume_key is the bare orchestrator run_id.
+
+    Set ``hint.done = True`` before leaving the managed block to suppress the
+    message on clean success.
+    """
+
+    def __init__(
+        self,
+        resume_key: str,
+        checkpoint_store: Any,
+        label: str = "Run",
+        *,
+        check_key: str | None = None,
+    ) -> None:
+        self._resume_key = resume_key
+        self._check_key = check_key if check_key is not None else resume_key
+        self._store = checkpoint_store
+        self._label = label
+        self.done: bool = False
+
+    async def __aenter__(self) -> _ResumeHint:
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> bool:
+        if not self.done and self._store is not None and self._resume_key:
+            checkpoint = await self._store.read(self._check_key)
+            if checkpoint is not None:
+                script = sys.argv[0] if sys.argv else "your_script.py"
+                print(
+                    f"\n  {self._label} interrupted — checkpoint saved."
+                    f"\n  Resume: python {script} --resume {self._resume_key}\n",
+                    file=sys.stderr,
+                )
+        return False