agent-checkpoint-framework 0.1.0__tar.gz

agent_checkpoint_framework-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: agent-checkpoint-framework
+Version: 0.1.0
+Summary: Never lose work when an agent fails.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+
+# Agent Checkpoint
+
+Never lose work when an agent fails.
+
+## Features
+
+- **Industrialized OOP Structure**: Clean separation of concerns between models, storage, and management.
+- **Flexible Storage**: Abstract base class allows for multiple storage backends (In-Memory, File-system, Database).
+- **Type Safe**: Fully type-hinted and compatible with `mypy`.
+- **CI Ready**: Pre-configured with GitHub Actions, `ruff`, and `pytest`.
+
+## Architecture
+
+- `Checkpoint`: Immutable data model for agent states.
+- `Storage`: Interface for persisting and retrieving checkpoints.
+- `CheckpointManager`: Central API for creating and managing checkpoints.
+
+## Development
+
+```bash
+pip install -e .[dev]
+ruff check .
+mypy src
+pytest
+```

agent_checkpoint_framework-0.1.0/README.md

@@ -0,0 +1,25 @@
+# Agent Checkpoint
+
+Never lose work when an agent fails.
+
+## Features
+
+- **Industrialized OOP Structure**: Clean separation of concerns between models, storage, and management.
+- **Flexible Storage**: Abstract base class allows for multiple storage backends (In-Memory, File-system, Database).
+- **Type Safe**: Fully type-hinted and compatible with `mypy`.
+- **CI Ready**: Pre-configured with GitHub Actions, `ruff`, and `pytest`.
+
+## Architecture
+
+- `Checkpoint`: Immutable data model for agent states.
+- `Storage`: Interface for persisting and retrieving checkpoints.
+- `CheckpointManager`: Central API for creating and managing checkpoints.
+
+## Development
+
+```bash
+pip install -e .[dev]
+ruff check .
+mypy src
+pytest
+```

agent_checkpoint_framework-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-checkpoint-framework"
+version = "0.1.0"
+description = "Never lose work when an agent fails."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+    "mypy",
+]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=src --cov-report=term-missing"

agent_checkpoint_framework-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_checkpoint_framework-0.1.0/src/agent_checkpoint/__init__.py

@@ -0,0 +1,24 @@
+from .codec import ParseResult, emit, emit_json, parse
+from .factory import new_checkpoint, resume_from
+from .manager import CheckpointManager
+from .models import Checkpoint, CheckpointStatus, RetryStrategy
+from .storage import InMemoryStorage, Storage
+from .validator import ValidationError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Checkpoint",
+    "CheckpointStatus",
+    "RetryStrategy",
+    "ValidationError",
+    "ParseResult",
+    "parse",
+    "emit",
+    "emit_json",
+    "new_checkpoint",
+    "resume_from",
+    "CheckpointManager",
+    "Storage",
+    "InMemoryStorage",
+]

agent_checkpoint_framework-0.1.0/src/agent_checkpoint/codec.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Union
+
+from .models import Checkpoint, CheckpointStatus, RetryStrategy
+from .validator import ValidationError, validate
+
+
+@dataclass
+class ParseResult:
+    """The result of a parse operation."""
+
+    ok: bool
+    checkpoint: Optional[Checkpoint]
+    errors: List[ValidationError]
+
+
+def parse(data: Union[str, Dict[str, Any]]) -> ParseResult:
+    """
+    Parses a JSON string or dictionary into a Checkpoint object.
+    Performs validation and returns a ParseResult.
+    """
+    if isinstance(data, str):
+        try:
+            raw_dict = json.loads(data)
+        except json.JSONDecodeError as e:
+            return ParseResult(
+                ok=False,
+                checkpoint=None,
+                errors=[ValidationError("json", f"Invalid JSON: {str(e)}")],
+            )
+    else:
+        raw_dict = data
+
+    # 1. Validate the dictionary
+    errors = validate(raw_dict)
+    if errors:
+        return ParseResult(ok=False, checkpoint=None, errors=errors)
+
+    # 2. Build Checkpoint from dict
+    try:
+        # Convert enum strings to actual enum members for the constructor
+        status = CheckpointStatus(raw_dict["status"])
+
+        retry_strategy = None
+        if raw_dict.get("retry_strategy"):
+            retry_strategy = RetryStrategy(raw_dict["retry_strategy"])
+
+        checkpoint = Checkpoint(
+            # Required fields
+            ac_version=raw_dict["ac_version"],
+            checkpoint_id=raw_dict["checkpoint_id"],
+            task_id=raw_dict["task_id"],
+            agent_id=raw_dict["agent_id"],
+            emitted_at=raw_dict["emitted_at"],
+            status=status,
+            task_summary=raw_dict["task_summary"],
+            # Optional fields
+            completed_steps=raw_dict.get("completed_steps", []),
+            remaining_steps=raw_dict.get("remaining_steps", []),
+            partial_output=raw_dict.get("partial_output"),
+            failure_reason=raw_dict.get("failure_reason"),
+            confidence=raw_dict.get("confidence"),
+            retry_strategy=retry_strategy,
+            executor_hint=raw_dict.get("executor_hint"),
+            context_snapshot=raw_dict.get("context_snapshot"),
+            parent_checkpoint_id=raw_dict.get("parent_checkpoint_id"),
+        )
+        return ParseResult(ok=True, checkpoint=checkpoint, errors=[])
+    except (KeyError, ValueError, TypeError) as e:
+        # This catch-all handles unexpected type mismatches not caught by validate()
+        return ParseResult(
+            ok=False,
+            checkpoint=None,
+            errors=[ValidationError("internal", f"Failed to instantiate Checkpoint: {str(e)}")],
+        )
+
+
+def emit(checkpoint: Checkpoint) -> Dict[str, Any]:
+    """
+    Converts a Checkpoint to a dictionary for serialization.
+    Omits fields with None values entirely.
+    """
+    # Use __dict__ to avoid complex serialization of nested objects if any,
+    # but since Checkpoint is simple dataclass, this works well.
+    raw = checkpoint.__dict__.copy()
+
+    # Clean up enums and omit None values
+    clean: Dict[str, Any] = {}
+    for k, v in raw.items():
+        if v is None:
+            continue
+
+        # Handle enums
+        if isinstance(v, (CheckpointStatus, RetryStrategy)):
+            clean[k] = v.value
+        else:
+            clean[k] = v
+
+    return clean
+
+
+def emit_json(checkpoint: Checkpoint, indent: int = 2) -> str:
+    """
+    Converts a Checkpoint to a JSON string.
+    """
+    return json.dumps(emit(checkpoint), indent=indent, default=str)

agent_checkpoint_framework-0.1.0/src/agent_checkpoint/factory.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from .models import Checkpoint, CheckpointStatus
+
+
+def new_checkpoint(
+    task_id: str,
+    agent_id: str,
+    task_summary: str,
+    status: CheckpointStatus = CheckpointStatus.PARTIAL,
+) -> Checkpoint:
+    """
+    Creates a new Checkpoint for a fresh task.
+    """
+    return Checkpoint(
+        ac_version="0.1.0",
+        checkpoint_id=str(uuid.uuid4()),
+        task_id=task_id,
+        agent_id=agent_id,
+        emitted_at=datetime.now(timezone.utc).isoformat(),
+        status=status,
+        task_summary=task_summary,
+    )
+
+
+def resume_from(previous: Checkpoint, agent_id: str) -> Checkpoint:
+    """
+    Creates a new Checkpoint linked to a previous one, preserving task context.
+    """
+    return Checkpoint(
+        ac_version="0.1.0",
+        checkpoint_id=str(uuid.uuid4()),
+        task_id=previous.task_id,
+        agent_id=agent_id,
+        emitted_at=datetime.now(timezone.utc).isoformat(),
+        status=CheckpointStatus.PARTIAL,
+        task_summary=previous.task_summary,
+        completed_steps=list(previous.completed_steps),  # copy the list
+        parent_checkpoint_id=previous.checkpoint_id,
+    )

agent_checkpoint_framework-0.1.0/src/agent_checkpoint/manager.py

@@ -0,0 +1,55 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from .models import Checkpoint, CheckpointStatus, RetryStrategy
+from .storage import Storage
+
+
+class CheckpointManager:
+    """Coordinates checkpoint creation and retrieval based on SPEC.md."""
+
+    def __init__(self, storage: Storage):
+        self.storage = storage
+
+    def create_checkpoint(
+        self,
+        task_id: str,
+        agent_id: str,
+        task_summary: str,
+        status: CheckpointStatus = CheckpointStatus.PARTIAL,
+        completed_steps: Optional[List[str]] = None,
+        remaining_steps: Optional[List[str]] = None,
+        partial_output: Optional[Dict[str, Any]] = None,
+        failure_reason: Optional[str] = None,
+        confidence: Optional[float] = None,
+        retry_strategy: Optional[RetryStrategy] = None,
+        executor_hint: Optional[str] = None,
+        context_snapshot: Optional[Dict[str, Any]] = None,
+        parent_checkpoint_id: Optional[str] = None,
+    ) -> Checkpoint:
+        """Creates and saves a new checkpoint following the spec."""
+        checkpoint = Checkpoint(
+            ac_version="0.1.0",
+            checkpoint_id=str(uuid.uuid4()),
+            task_id=task_id,
+            agent_id=agent_id,
+            emitted_at=datetime.now(timezone.utc).isoformat(),
+            status=status,
+            task_summary=task_summary,
+            completed_steps=completed_steps or [],
+            remaining_steps=remaining_steps or [],
+            partial_output=partial_output or {},
+            failure_reason=failure_reason,
+            confidence=confidence,
+            retry_strategy=retry_strategy,
+            executor_hint=executor_hint,
+            context_snapshot=context_snapshot or {},
+            parent_checkpoint_id=parent_checkpoint_id,
+        )
+        self.storage.save(checkpoint)
+        return checkpoint
+
+    def get_checkpoint(self, checkpoint_id: str) -> Optional[Checkpoint]:
+        """Retrieves a checkpoint by ID."""
+        return self.storage.load(checkpoint_id)

agent_checkpoint_framework-0.1.0/src/agent_checkpoint/models.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Dict, List, Optional
+
+
+class CheckpointStatus(StrEnum):
+    """Status of the checkpoint as defined in SPEC.md."""
+
+    PARTIAL = "partial"
+    FAILED = "failed"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+
+
+class RetryStrategy(StrEnum):
+    """Strategy for continuation as defined in SPEC.md."""
+
+    RESUME = "resume"
+    RESTART = "restart"
+    ESCALATE = "escalate"
+
+
+@dataclass(frozen=True)
+class Checkpoint:
+    """
+    Represents a single point in time for an agent's state, following SPEC.md.
+
+    Validation:
+    - confidence: None or between 0.0 and 1.0 (inclusive)
+    - executor_hint: None, 'same', 'any', or starts with 'capability:'
+    """
+
+    # Required fields (no defaults)
+    ac_version: str
+    checkpoint_id: str
+    task_id: str
+    agent_id: str
+    emitted_at: str
+    status: CheckpointStatus
+    task_summary: str
+
+    # Optional fields
+    completed_steps: List[str] = field(default_factory=list)
+    remaining_steps: List[str] = field(default_factory=list)
+    partial_output: Optional[Dict[str, object]] = None
+    failure_reason: Optional[str] = None
+    confidence: Optional[float] = None
+    retry_strategy: Optional[RetryStrategy] = None
+    executor_hint: Optional[str] = None
+    context_snapshot: Optional[Dict[str, object]] = None
+    parent_checkpoint_id: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        """Validate input constraints."""
+        if self.confidence is not None:
+            if not (0.0 <= self.confidence <= 1.0):
+                raise ValueError(f"Confidence must be between 0.0 and 1.0; got {self.confidence}")
+
+        if self.executor_hint is not None:
+            if not (
+                self.executor_hint in ("same", "any")
+                or self.executor_hint.startswith("capability:")
+            ):
+                raise ValueError(
+                    f"executor_hint must be 'same', 'any', or start with 'capability:'; "
+                    f"got {self.executor_hint}"
+                )
+
+
+__all__ = ["CheckpointStatus", "RetryStrategy", "Checkpoint"]

agent_checkpoint_framework-0.1.0/src/agent_checkpoint/storage.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+
+from .models import Checkpoint
+
+
+class Storage(ABC):
+    """Abstract base class for checkpoint storage."""
+
+    @abstractmethod
+    def save(self, checkpoint: Checkpoint) -> None:
+        """Persist a checkpoint."""
+        pass
+
+    @abstractmethod
+    def load(self, checkpoint_id: str) -> Optional[Checkpoint]:
+        """Retrieve a checkpoint by ID."""
+        pass
+
+    @abstractmethod
+    def list_all(self) -> List[Checkpoint]:
+        """List all stored checkpoints."""
+        pass
+
+
+class InMemoryStorage(Storage):
+    """Simple in-memory implementation of checkpoint storage."""
+
+    def __init__(self) -> None:
+        self._checkpoints: Dict[str, Checkpoint] = {}
+
+    def save(self, checkpoint: Checkpoint) -> None:
+        self._checkpoints[checkpoint.checkpoint_id] = checkpoint
+
+    def load(self, checkpoint_id: str) -> Optional[Checkpoint]:
+        return self._checkpoints.get(checkpoint_id)
+
+    def list_all(self) -> List[Checkpoint]:
+        return list(self._checkpoints.values())

agent_checkpoint_framework-0.1.0/src/agent_checkpoint/validator.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Dict, List
+
+from .models import CheckpointStatus, RetryStrategy
+
+
+@dataclass
+class ValidationError:
+    """Represents a single validation failure."""
+
+    field: str
+    message: str
+
+
+# UUID v4 pattern (simplified but strict enough for spec compliance)
+UUID_V4_PATTERN = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", re.IGNORECASE
+)
+SEMVER_PATTERN = re.compile(r"^\d+\.\d+\.\d+$")
+
+
+def validate(data: Dict[str, Any]) -> List[ValidationError]:
+    """
+    Validates a dictionary against the agent-checkpoint specification.
+    Returns a list of ValidationError objects; an empty list indicates success.
+    """
+    errors: List[ValidationError] = []
+
+    # 1. Required fields presence and basic type check
+    required_fields = [
+        "ac_version",
+        "checkpoint_id",
+        "task_id",
+        "agent_id",
+        "emitted_at",
+        "status",
+        "task_summary",
+    ]
+
+    for field in required_fields:
+        if field not in data:
+            errors.append(ValidationError(field, "Field is missing"))
+        elif not isinstance(data[field], str) or not data[field].strip():
+            errors.append(ValidationError(field, "Field must be a non-empty string"))
+
+    # If basic requirements are missing, we still continue to check patterns for existing fields
+
+    # 2. Pattern and Logic Validations
+    if "ac_version" in data and isinstance(data["ac_version"], str):
+        if not SEMVER_PATTERN.match(data["ac_version"]):
+            errors.append(
+                ValidationError("ac_version", "Must match semver pattern \\d+\\.\\d+\\.\\d+")
+            )
+
+    # UUID checks
+    for uuid_field in ["checkpoint_id", "task_id", "parent_checkpoint_id"]:
+        if uuid_field in data and data[uuid_field] is not None:
+            if not isinstance(data[uuid_field], str):
+                errors.append(ValidationError(uuid_field, "Must be a string"))
+            elif not UUID_V4_PATTERN.match(data[uuid_field]):
+                errors.append(ValidationError(uuid_field, "Must be a valid UUID v4"))
+
+    # Timestamp check
+    if "emitted_at" in data and isinstance(data["emitted_at"], str):
+        try:
+            # Handle the 'Z' suffix which fromisoformat might not like in older 3.11 patches
+            ts = data["emitted_at"].replace("Z", "+00:00")
+            datetime.fromisoformat(ts)
+        except ValueError:
+            errors.append(ValidationError("emitted_at", "Must be a valid ISO 8601 timestamp"))
+
+    # Enum checks
+    if "status" in data and isinstance(data["status"], str):
+        if data["status"] not in [s.value for s in CheckpointStatus]:
+            errors.append(
+                ValidationError(
+                    "status", f"Must be one of: {', '.join(s.value for s in CheckpointStatus)}"
+                )
+            )
+
+    if "retry_strategy" in data and data["retry_strategy"] is not None:
+        if data["retry_strategy"] not in [r.value for r in RetryStrategy]:
+            errors.append(
+                ValidationError(
+                    "retry_strategy", f"Must be one of: {', '.join(r.value for r in RetryStrategy)}"
+                )
+            )
+
+    # Confidence check
+    if "confidence" in data and data["confidence"] is not None:
+        if not isinstance(data["confidence"], (int, float)):
+            errors.append(ValidationError("confidence", "Must be a number"))
+        elif not (0.0 <= float(data["confidence"]) <= 1.0):
+            errors.append(ValidationError("confidence", "Must be between 0.0 and 1.0"))
+
+    # Executor hint check
+    if "executor_hint" in data and data["executor_hint"] is not None:
+        val = data["executor_hint"]
+        if not isinstance(val, str):
+            errors.append(ValidationError("executor_hint", "Must be a string"))
+        elif not (val in ("same", "any") or val.startswith("capability:")):
+            errors.append(
+                ValidationError(
+                    "executor_hint", "Must be 'same', 'any', or start with 'capability:'"
+                )
+            )
+
+    return errors

agent_checkpoint_framework-0.1.0/src/agent_checkpoint_framework.egg-info/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: agent-checkpoint-framework
+Version: 0.1.0
+Summary: Never lose work when an agent fails.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+
+# Agent Checkpoint
+
+Never lose work when an agent fails.
+
+## Features
+
+- **Industrialized OOP Structure**: Clean separation of concerns between models, storage, and management.
+- **Flexible Storage**: Abstract base class allows for multiple storage backends (In-Memory, File-system, Database).
+- **Type Safe**: Fully type-hinted and compatible with `mypy`.
+- **CI Ready**: Pre-configured with GitHub Actions, `ruff`, and `pytest`.
+
+## Architecture
+
+- `Checkpoint`: Immutable data model for agent states.
+- `Storage`: Interface for persisting and retrieving checkpoints.
+- `CheckpointManager`: Central API for creating and managing checkpoints.
+
+## Development
+
+```bash
+pip install -e .[dev]
+ruff check .
+mypy src
+pytest
+```

agent_checkpoint_framework-0.1.0/src/agent_checkpoint_framework.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/agent_checkpoint/__init__.py
+src/agent_checkpoint/codec.py
+src/agent_checkpoint/factory.py
+src/agent_checkpoint/manager.py
+src/agent_checkpoint/models.py
+src/agent_checkpoint/storage.py
+src/agent_checkpoint/validator.py
+src/agent_checkpoint_framework.egg-info/PKG-INFO
+src/agent_checkpoint_framework.egg-info/SOURCES.txt
+src/agent_checkpoint_framework.egg-info/dependency_links.txt
+src/agent_checkpoint_framework.egg-info/requires.txt
+src/agent_checkpoint_framework.egg-info/top_level.txt
+tests/test_codec.py
+tests/test_factory.py
+tests/test_manager.py

agent_checkpoint_framework-0.1.0/src/agent_checkpoint_framework.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_checkpoint_framework-0.1.0/src/agent_checkpoint_framework.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest
+pytest-cov
+ruff
+mypy

agent_checkpoint_framework-0.1.0/src/agent_checkpoint_framework.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent_checkpoint

agent_checkpoint_framework-0.1.0/tests/test_codec.py

@@ -0,0 +1,108 @@
+import json
+
+import pytest
+
+from agent_checkpoint.codec import emit, emit_json, parse
+from agent_checkpoint.models import Checkpoint, CheckpointStatus
+
+
+@pytest.fixture
+def VALID_DICT():
+    return {
+        "ac_version": "0.1.0",
+        "checkpoint_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
+        "task_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
+        "agent_id": "coder-gpt-4",
+        "emitted_at": "2026-06-16T14:30:00Z",
+        "status": "partial",
+        "task_summary": "Implement auth module",
+        "confidence": 0.75,
+        "executor_hint": "same",
+        "retry_strategy": "resume",
+        "completed_steps": ["step1"],
+    }
+
+
+def test_parse_valid_dict(VALID_DICT):
+    result = parse(VALID_DICT)
+    assert result.ok is True
+    assert isinstance(result.checkpoint, Checkpoint)
+    assert result.checkpoint.status == CheckpointStatus.PARTIAL
+    assert result.checkpoint.confidence == 0.75
+
+
+def test_parse_valid_json_string(VALID_DICT):
+    json_str = json.dumps(VALID_DICT)
+    result = parse(json_str)
+    assert result.ok is True
+    assert result.checkpoint.checkpoint_id == VALID_DICT["checkpoint_id"]
+
+
+def test_parse_empty_dict():
+    result = parse({})
+    assert result.ok is False
+    # Errors should list missing required fields
+    required_fields = [
+        "ac_version",
+        "checkpoint_id",
+        "task_id",
+        "agent_id",
+        "emitted_at",
+        "status",
+        "task_summary",
+    ]
+    error_fields = [e.field for e in result.errors]
+    for field in required_fields:
+        assert field in error_fields
+
+
+@pytest.mark.parametrize(
+    "field, invalid_value",
+    [
+        ("confidence", 1.5),
+        ("checkpoint_id", "not-a-uuid"),
+    ],
+)
+def test_parse_invalid_values(VALID_DICT, field, invalid_value):
+    invalid_dict = VALID_DICT.copy()
+    invalid_dict[field] = invalid_value
+    result = parse(invalid_dict)
+    assert result.ok is False
+    assert any(e.field == field for e in result.errors)
+
+
+def test_parse_unknown_extra_field(VALID_DICT):
+    extra_dict = VALID_DICT.copy()
+    extra_dict["extra_field"] = "some value"
+    result = parse(extra_dict)
+    assert result.ok is True
+
+
+def test_emit_no_none_values(VALID_DICT):
+    checkpoint = parse(VALID_DICT).checkpoint
+    # Manually ensure some fields are None if they weren't already
+    # but the valid_dict has some Nones by omission anyway.
+    emitted = emit(checkpoint)
+    for value in emitted.values():
+        assert value is not None
+    assert "failure_reason" not in emitted
+
+
+def test_emit_json_valid_json(VALID_DICT):
+    checkpoint = parse(VALID_DICT).checkpoint
+    json_str = emit_json(checkpoint)
+    # Should be a valid JSON string
+    data = json.loads(json_str)
+    assert data["checkpoint_id"] == VALID_DICT["checkpoint_id"]
+
+
+def test_round_trip(VALID_DICT):
+    # parse(emit_json(parse(VALID_DICT).checkpoint)) returns ok=True
+    first_parse = parse(VALID_DICT)
+    assert first_parse.ok is True
+
+    json_output = emit_json(first_parse.checkpoint)
+    second_parse = parse(json_output)
+
+    assert second_parse.ok is True
+    assert second_parse.checkpoint == first_parse.checkpoint

agent_checkpoint_framework-0.1.0/tests/test_factory.py

@@ -0,0 +1,66 @@
+from datetime import datetime
+
+from agent_checkpoint.factory import new_checkpoint, resume_from
+from agent_checkpoint.models import Checkpoint, CheckpointStatus
+
+
+def test_new_checkpoint_ac_version():
+    cp = new_checkpoint("task-1", "agent-1", "summary")
+    assert cp.ac_version == "0.1.0"
+
+
+def test_new_checkpoint_id_is_uuid():
+    cp = new_checkpoint("task-1", "agent-1", "summary")
+    # Basic UUID v4 format check (8-4-4-4-12)
+    parts = cp.checkpoint_id.split("-")
+    assert len(parts) == 5
+    assert len(parts[0]) == 8
+    assert len(parts[1]) == 4
+    assert len(parts[2]) == 4
+    assert len(parts[3]) == 4
+    assert len(parts[4]) == 12
+    # UUID v4 marker
+    assert parts[2][0] == "4"
+
+
+def test_new_checkpoint_emitted_at_iso8601():
+    cp = new_checkpoint("task-1", "agent-1", "summary")
+    # Should not raise ValueError
+    datetime.fromisoformat(cp.emitted_at.replace("Z", "+00:00"))
+
+
+def test_resume_from_parent_id():
+    previous = new_checkpoint("task-1", "agent-1", "summary")
+    resumed = resume_from(previous, "agent-2")
+    assert resumed.parent_checkpoint_id == previous.checkpoint_id
+
+
+def test_resume_from_preserves_task_id():
+    previous = new_checkpoint("task-1", "agent-1", "summary")
+    resumed = resume_from(previous, "agent-2")
+    assert resumed.task_id == previous.task_id
+
+
+def test_resume_from_copies_completed_steps():
+    # Actually, let's use the constructor to make a previous with steps
+    previous_with_steps = Checkpoint(
+        ac_version="0.1.0",
+        checkpoint_id="uuid-1",
+        task_id="task-1",
+        agent_id="agent-1",
+        emitted_at="2026-06-16T14:30:00Z",
+        status=CheckpointStatus.PARTIAL,
+        task_summary="summary",
+        completed_steps=["step1", "step2"],
+    )
+    resumed = resume_from(previous_with_steps, "agent-2")
+    assert resumed.completed_steps == ["step1", "step2"]
+    # Ensure it's a copy
+    assert resumed.completed_steps is not previous_with_steps.completed_steps
+
+
+def test_resume_from_generates_new_id():
+    previous = new_checkpoint("task-1", "agent-1", "summary")
+    resumed = resume_from(previous, "agent-2")
+    assert resumed.checkpoint_id != previous.checkpoint_id
+    assert len(resumed.checkpoint_id) == 36

agent_checkpoint_framework-0.1.0/tests/test_manager.py

@@ -0,0 +1,35 @@
+from agent_checkpoint import CheckpointManager, InMemoryStorage, emit
+from agent_checkpoint.models import CheckpointStatus, RetryStrategy
+
+
+def test_checkpoint_lifecycle():
+    storage = InMemoryStorage()
+    manager = CheckpointManager(storage)
+
+    task_id = "f9e8d7c6-b5a4-4d3c-2b1a-0f9e8d7c6b5a"
+    agent_id = "coder-gpt-4"
+    summary = "Implement auth"
+
+    checkpoint = manager.create_checkpoint(
+        task_id=task_id,
+        agent_id=agent_id,
+        task_summary=summary,
+        status=CheckpointStatus.PARTIAL,
+        partial_output={"file.py": "print('hello')"},
+        retry_strategy=RetryStrategy.RESUME,
+    )
+
+    assert checkpoint.checkpoint_id is not None
+    assert checkpoint.task_id == task_id
+    assert checkpoint.agent_id == agent_id
+    assert checkpoint.status == CheckpointStatus.PARTIAL
+    assert checkpoint.partial_output == {"file.py": "print('hello')"}
+
+    retrieved = manager.get_checkpoint(checkpoint.checkpoint_id)
+    assert retrieved == checkpoint
+
+    # Test dictionary conversion for JSON compatibility
+    d = emit(checkpoint)
+    assert d["ac_version"] == "0.1.0"
+    assert d["status"] == "partial"
+    assert d["retry_strategy"] == "resume"