agent-lifecycle-kit 1.63.2__tar.gz → 1.64.0__tar.gz

{agent_lifecycle_kit-1.63.2/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-1.64.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 1.63.2
+Version: 1.64.0
 Summary: Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion.
 Author: Agent Lifecycle Kit contributors
 License: Apache-2.0
@@ -61,7 +61,7 @@ and start a task with:
 agent-lifecycle start --adapter <adapter-id> --file task.md
 ```
 
-The published [PyPI package](https://pypi.org/project/agent-lifecycle-kit/) supports Python 3.11-3.14; install it with `python -m pip install agent-lifecycle-kit==1.63.2`.
+The published [PyPI package](https://pypi.org/project/agent-lifecycle-kit/) supports Python 3.11-3.14; install it with `python -m pip install agent-lifecycle-kit==1.64.0`.
 Use [Quickstart](docs/guides/quickstart.md) for the first task and [Commands by task](docs/guides/commands-by-task.md) for detailed operations.
 Continue with [task workflows](docs/guides/how-alk-works.md) and
 [project profile init](docs/reference/project-workflow-profile.md),
@@ -69,7 +69,7 @@ Continue with [task workflows](docs/guides/how-alk-works.md) and
 [Lifecycle task scenarios](docs/guides/lifecycle-cookbook.md). The [planning-only](docs/reference/planning-only-launch.md)
 and [qualified frozen-task](docs/reference/qualified-host-launch.md) guides define launch boundaries.
 See [System architecture](docs/architecture/system-architecture.md), [Project comparison](docs/reference/project-comparison.md),
-and [Документация на русском](docs/ru/README.md).
+[context checkpoints](docs/reference/context-checkpoints.md), and [Документация на русском](docs/ru/README.md).
 
 ## What it gives you
 - A finish-oriented lifecycle: plan, execute, review, and prove the result.

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.64.0}/README.md

@@ -39,7 +39,7 @@ and start a task with:
 agent-lifecycle start --adapter <adapter-id> --file task.md
 ```
 
-The published [PyPI package](https://pypi.org/project/agent-lifecycle-kit/) supports Python 3.11-3.14; install it with `python -m pip install agent-lifecycle-kit==1.63.2`.
+The published [PyPI package](https://pypi.org/project/agent-lifecycle-kit/) supports Python 3.11-3.14; install it with `python -m pip install agent-lifecycle-kit==1.64.0`.
 Use [Quickstart](docs/guides/quickstart.md) for the first task and [Commands by task](docs/guides/commands-by-task.md) for detailed operations.
 Continue with [task workflows](docs/guides/how-alk-works.md) and
 [project profile init](docs/reference/project-workflow-profile.md),
@@ -47,7 +47,7 @@ Continue with [task workflows](docs/guides/how-alk-works.md) and
 [Lifecycle task scenarios](docs/guides/lifecycle-cookbook.md). The [planning-only](docs/reference/planning-only-launch.md)
 and [qualified frozen-task](docs/reference/qualified-host-launch.md) guides define launch boundaries.
 See [System architecture](docs/architecture/system-architecture.md), [Project comparison](docs/reference/project-comparison.md),
-and [Документация на русском](docs/ru/README.md).
+[context checkpoints](docs/reference/context-checkpoints.md), and [Документация на русском](docs/ru/README.md).
 
 ## What it gives you
 - A finish-oriented lifecycle: plan, execute, review, and prove the result.

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.64.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "1.63.2"
+version = "1.64.0"
 description = "Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion."
 readme = "README.md"
 requires-python = ">=3.11,<3.15"

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.64.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "1.63.2"
+__version__ = "1.64.0"

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.64.0}/src/agent_lifecycle/adapter_sessions/session_store.py

@@ -32,6 +32,7 @@ def create_session(
     session_root: Path | None = None,
     state_identity: dict[str, Any] | None = None,
     managed_workflow_proof: dict[str, Any] | None = None,
+    context_checkpoint_policy: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     session_id = uuid.uuid4().hex
     session = {
@@ -46,6 +47,7 @@ def create_session(
         },
         "stateIdentity": state_identity,
         "managedWorkflowProof": managed_workflow_proof,
+        "contextCheckpointPolicy": context_checkpoint_policy,
         "secretValuesStored": False,
         "nativeConfigWritten": False,
     }

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.64.0}/src/agent_lifecycle/adapter_sessions/unified_start.py

@@ -224,7 +224,7 @@ def _resume(*, adapter_id: str, session_id: str, session_root: Path | None) -> d
             requested_mode="auto",
             action="BLOCKED",
             input_summary=input_summary,
-            delegate_summary=_resume_summary(receipt),
+            delegate_summary=_resume_summary(receipt, session=session),
             blockers=_blocker_summaries(receipt.get("blockers")),
         )
     return build_lifecycle_start_receipt(
@@ -233,7 +233,7 @@ def _resume(*, adapter_id: str, session_id: str, session_root: Path | None) -> d
         requested_mode="auto",
         action="RESUME",
         input_summary=input_summary,
-        delegate_summary=_resume_summary(receipt),
+        delegate_summary=_resume_summary(receipt, session=session),
         lifecycle_coverage_claimed=status == "PASS" and bool(receipt.get("lifecycleCoverageClaimed")),
     )
 
@@ -997,8 +997,8 @@ def _task_summary(receipt: dict[str, Any]) -> dict[str, Any]:
     }
 
 
-def _resume_summary(receipt: dict[str, Any]) -> dict[str, Any]:
-    return {
+def _resume_summary(receipt: dict[str, Any], *, session: dict[str, Any] | None = None) -> dict[str, Any]:
+    summary = {
         "schemaVersion": receipt.get("schemaVersion"),
         "status": receipt.get("status"),
         "lineageStatus": receipt.get("lineageStatus"),
@@ -1006,6 +1006,9 @@ def _resume_summary(receipt: dict[str, Any]) -> dict[str, Any]:
         "lifecycleCoverageClaimed": bool(receipt.get("lifecycleCoverageClaimed")),
         "receiptDigest": receipt.get("receiptDigest"),
     }
+    if session and isinstance(session.get("contextCheckpointPolicy"), dict):
+        summary["contextCheckpointPolicy"] = session["contextCheckpointPolicy"]
+    return summary
 
 
 def _claims_execution(receipt: dict[str, Any]) -> bool:

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.64.0}/src/agent_lifecycle/cli/dispatch_observability.py

@@ -7,6 +7,8 @@ from pathlib import Path
 from typing import Any
 
 from agent_lifecycle.context import check_context, load_context_profile, render_context
+from agent_lifecycle.context.checkpoint_store import restore_context_checkpoint, write_context_checkpoint
+from agent_lifecycle.context.checkpoints import build_context_checkpoint
 from agent_lifecycle.context.external_memory import build_episode_retrieval_with_external_context, import_external_memory_context
 from agent_lifecycle.contracts import LifecycleError, canonical_digest, read_json_object, write_json_create
 from agent_lifecycle.goal import build_goal_progress_view, build_objective_snapshot, update_goal_record, validate_goal_record
@@ -176,9 +178,75 @@ def _dispatch_context(args: argparse.Namespace) -> dict[str, Any]:
         if args.out:
             write_json_create(Path(args.out), payload)
         return payload
+    if args.context_command == "checkpoint":
+        return _dispatch_context_checkpoint(args)
+    if args.context_command == "restore":
+        state = read_json_object(Path(args.state), label="workflow state")
+        payload = restore_context_checkpoint(
+            Path(args.checkpoint),
+            state=state,
+            session_id=args.session,
+            target_tokens=args.target_tokens,
+        )
+        if args.out:
+            write_json_create(Path(args.out), payload)
+        if payload.get("status") == "BLOCKED":
+            raise LifecycleError(
+                "context-restore-blocked",
+                "context checkpoint cannot be restored against the current workflow state",
+                {"continuation": payload},
+            )
+        return payload
     raise LifecycleError("command-not-implemented", "context command is not implemented")
 
 
+def _dispatch_context_checkpoint(args: argparse.Namespace) -> dict[str, Any]:
+    state = read_json_object(Path(args.state), label="workflow state")
+    manifest = read_json_object(Path(args.plan), label="context checkpoint plan")
+    input_payload = read_json_object(Path(args.input), label="context checkpoint input")
+    reason = str(args.reason)
+    mode = args.capture_mode
+    reason_mode = {
+        "native-hook": "NATIVE_HOOK",
+        "milestone": "MILESTONE",
+        "agent-requested": "AGENT_REQUESTED",
+        "unavailable": "UNAVAILABLE",
+    }.get(reason.lower().replace("_", "-"))
+    if mode is None and reason_mode:
+        mode = reason_mode
+    if mode is None:
+        mode = "AGENT_REQUESTED"
+    target = Path(args.out) if args.out else Path(".alk/context/checkpoints") / "checkpoint.json"
+    root = target.parent
+    _require_checkpoint_output_root(root)
+    summary = dict(input_payload)
+    capture_evidence = summary.pop("nativeHookEvidence", None) if mode == "NATIVE_HOOK" else None
+    checkpoint = build_context_checkpoint(
+        session_id=args.session,
+        run_id=str(state.get("runId", "run")),
+        adapter_id=str(args.adapter or input_payload.get("adapterId") or state.get("adapterId") or "unknown-adapter"),
+        package_id=str(manifest.get("package", {}).get("id") or state.get("packageId") or "unknown-package"),
+        plan_revision=int(manifest.get("planRevision", state.get("planRevision", 1))),
+        plan_digest=canonical_digest(manifest),
+        state_revision=int(state.get("stateRevision", 1)),
+        source_revision=str(state.get("sourceRevision", "unknown-source")),
+        capture_mode=mode,
+        reason=reason,
+        summary=summary,
+        capture_evidence=capture_evidence,
+        checkpoint_id=target.stem if args.out else None,
+        created_at=str(state.get("updatedAt") or "1970-01-01T00:00:00Z"),
+    )
+    stored = write_context_checkpoint(checkpoint, root=root)
+    return {**checkpoint, "storage": stored}
+
+
+def _require_checkpoint_output_root(root: Path) -> None:
+    resolved = root.resolve()
+    if ".alk" not in resolved.parts or not resolved.name == "checkpoints":
+        raise LifecycleError("context-checkpoint-output-root-invalid", "checkpoint output must remain in a .alk/context/checkpoints directory")
+
+
 def _dispatch_goal(args: argparse.Namespace) -> dict[str, Any] | str:
     record = read_json_object(Path(args.record), label="goal record")
     if args.goal_command == "check":

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.64.0}/src/agent_lifecycle/cli/parsers.py

@@ -610,6 +610,25 @@ def _add_context_parser(subparsers: argparse._SubParsersAction[argparse.Argument
     episode_retrieve.add_argument("--max-external-context-hints", type=int, default=4)
     episode_retrieve.add_argument("--target-tokens", type=int, default=2048)
     episode_retrieve.add_argument("--out")
+    checkpoint = context_sub.add_parser("checkpoint", help="write a bounded context checkpoint")
+    checkpoint.add_argument("--session", required=True)
+    checkpoint.add_argument("--state", required=True)
+    checkpoint.add_argument("--plan", required=True)
+    checkpoint.add_argument("--input", required=True)
+    checkpoint.add_argument("--reason", required=True)
+    checkpoint.add_argument(
+        "--capture-mode",
+        choices=["NATIVE_HOOK", "MILESTONE", "AGENT_REQUESTED", "UNAVAILABLE"],
+        default=None,
+    )
+    checkpoint.add_argument("--adapter")
+    checkpoint.add_argument("--out")
+    restore = context_sub.add_parser("restore", help="restore a bounded context continuation")
+    restore.add_argument("--checkpoint", required=True)
+    restore.add_argument("--state", required=True)
+    restore.add_argument("--session")
+    restore.add_argument("--target-tokens", type=int, default=2048)
+    restore.add_argument("--out")
 
 
 def _add_goal_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.64.0}/src/agent_lifecycle/context/__init__.py

@@ -2,13 +2,31 @@
 
 from agent_lifecycle.context.profiles import load_context_profile, validate_context_profile
 from agent_lifecycle.context.rendering import check_context, render_context
+from agent_lifecycle.context.checkpoints import (
+    build_context_checkpoint,
+    require_context_checkpoint_pass,
+    validate_context_checkpoint,
+)
+from agent_lifecycle.context.checkpoint_store import (
+    list_context_checkpoints,
+    load_context_checkpoint,
+    restore_context_checkpoint,
+    write_context_checkpoint,
+)
 
 __all__ = [
     "build_episode_context",
     "check_context",
+    "build_context_checkpoint",
     "load_context_profile",
+    "list_context_checkpoints",
+    "load_context_checkpoint",
     "render_context",
+    "restore_context_checkpoint",
+    "require_context_checkpoint_pass",
+    "validate_context_checkpoint",
     "validate_context_profile",
+    "write_context_checkpoint",
 ]
 
 

agent_lifecycle_kit-1.64.0/src/agent_lifecycle/context/checkpoint_store.py

@@ -0,0 +1,198 @@
+"""Contained local storage and bounded restoration for context checkpoints."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_bytes, canonical_digest, read_json_object
+from agent_lifecycle.contracts.redaction import redact_value
+from agent_lifecycle.context.checkpoints import (
+    CHECKPOINT_SCHEMA,
+    DEFAULT_MAX_CHECKPOINT_BYTES,
+    DEFAULT_TARGET_TOKENS,
+    require_context_checkpoint_pass,
+    validate_context_checkpoint,
+)
+
+DEFAULT_CHECKPOINT_ROOT = Path(".alk/context/checkpoints")
+MAX_CHECKPOINTS_PER_RUN = 64
+
+
+def checkpoint_path(checkpoint_id: str, *, root: Path | None = None) -> Path:
+    """Return a path contained by the configured checkpoint directory."""
+
+    if not isinstance(checkpoint_id, str) or not checkpoint_id or checkpoint_id in {".", ".."}:
+        raise LifecycleError("context-checkpoint-id-invalid", "checkpoint id is required")
+    if "/" in checkpoint_id or "\\" in checkpoint_id or "\x00" in checkpoint_id:
+        raise LifecycleError("context-checkpoint-id-invalid", "checkpoint id must be a single path component")
+    directory = root or DEFAULT_CHECKPOINT_ROOT
+    path = directory / f"{checkpoint_id}.json"
+    if not path.resolve().is_relative_to(directory.resolve()):
+        raise LifecycleError("context-checkpoint-path-escape", "checkpoint path escapes the checkpoint root")
+    return path
+
+
+def write_context_checkpoint(
+    checkpoint: dict[str, Any],
+    *,
+    root: Path | None = None,
+    max_checkpoints_per_run: int = MAX_CHECKPOINTS_PER_RUN,
+) -> dict[str, Any]:
+    """Write a checkpoint once and retain only the latest bounded set per run."""
+
+    validation = validate_context_checkpoint(checkpoint)
+    require_context_checkpoint_pass(validation)
+    path = checkpoint_path(str(checkpoint["checkpointId"]), root=root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = canonical_bytes(checkpoint) + b"\n"
+    created = not path.exists()
+    if not created:
+        existing = read_json_object(path, label="existing context checkpoint")
+        if canonical_digest(existing) != canonical_digest(checkpoint):
+            raise LifecycleError("context-checkpoint-conflict", "checkpoint id already contains a different artifact")
+    else:
+        _write_atomic(path, data)
+    _retain_latest(path.parent, run_id=str(checkpoint["runId"]), limit=max_checkpoints_per_run)
+    return {
+        "status": "PASS",
+        "path": path.as_posix(),
+        "checkpointId": checkpoint["checkpointId"],
+        "checkpointDigest": checkpoint["checkpointDigest"],
+        "created": created,
+        "retentionPolicy": "retain-latest-with-explicit-delete",
+        "maxCheckpointsPerRun": max_checkpoints_per_run,
+        "productionPromotionClaimed": False,
+    }
+
+
+def load_context_checkpoint(checkpoint_id: str, *, root: Path | None = None) -> dict[str, Any]:
+    return read_json_object(checkpoint_path(checkpoint_id, root=root), label="context checkpoint")
+
+
+def list_context_checkpoints(*, root: Path | None = None, run_id: str | None = None) -> list[dict[str, Any]]:
+    directory = (root or DEFAULT_CHECKPOINT_ROOT).resolve()
+    if not directory.exists():
+        return []
+    if not directory.is_dir():
+        raise LifecycleError("context-checkpoint-root-invalid", "checkpoint root is not a directory")
+    result: list[dict[str, Any]] = []
+    for path in sorted(directory.glob("*.json")):
+        if not path.resolve().is_relative_to(directory):
+            raise LifecycleError("context-checkpoint-path-escape", "checkpoint listing escaped the checkpoint root")
+        value = read_json_object(path, label="context checkpoint")
+        if run_id is None or value.get("runId") == run_id:
+            result.append(value)
+    return sorted(result, key=lambda item: (str(item.get("createdAt", "")), str(item.get("checkpointId", ""))))
+
+
+def restore_context_checkpoint(
+    checkpoint_path_value: Path,
+    *,
+    state: dict[str, Any],
+    session_id: str | None = None,
+    target_tokens: int = DEFAULT_TARGET_TOKENS,
+    max_checkpoint_bytes: int = DEFAULT_MAX_CHECKPOINT_BYTES,
+) -> dict[str, Any]:
+    """Return a bounded continuation packet after checking current lineage."""
+
+    checkpoint = read_json_object(checkpoint_path_value, label="context checkpoint")
+    expected = _lineage_from_state(state, session_id=session_id)
+    validation = validate_context_checkpoint(
+        checkpoint,
+        expected_lineage=expected,
+        max_checkpoint_bytes=max_checkpoint_bytes,
+        target_tokens=target_tokens,
+    )
+    if validation["status"] == "FAIL":
+        return {
+            "schemaVersion": "agent-context-continuation.v1",
+            "status": "BLOCKED",
+            "checkpointId": checkpoint.get("checkpointId"),
+            "validation": validation,
+            "implementationAuthorized": False,
+            "proofAuthority": "none",
+            "productionPromotionClaimed": False,
+        }
+    summary, redaction_applied = redact_value(checkpoint["summary"])
+    if redaction_applied:
+        return {
+            "schemaVersion": "agent-context-continuation.v1",
+            "status": "BLOCKED",
+            "checkpointId": checkpoint.get("checkpointId"),
+            "validation": {
+                **validation,
+                "status": "FAIL",
+                "blockers": [{"code": "context-restore-unredacted-sensitive-input"}],
+            },
+            "implementationAuthorized": False,
+            "proofAuthority": "none",
+            "productionPromotionClaimed": False,
+        }
+    continuation = {
+        "schemaVersion": "agent-context-continuation.v1",
+        "status": "PASS",
+        "checkpointId": checkpoint["checkpointId"],
+        "checkpointDigest": checkpoint["checkpointDigest"],
+        "lineage": {
+            key: checkpoint[key]
+            for key in ("sessionId", "runId", "adapterId", "packageId", "planRevision", "planDigest", "stateRevision", "sourceRevision")
+        },
+        "captureMode": checkpoint["captureMode"],
+        "summary": summary,
+        "referencedArtifacts": checkpoint["referencedArtifacts"],
+        "implementationAuthorized": False,
+        "proofAuthority": "none",
+        "contextLimits": {"targetTokens": target_tokens, "maxBytes": max_checkpoint_bytes},
+        "validationDigest": validation["validationDigest"],
+        "productionPromotionClaimed": False,
+    }
+    continuation["continuationDigest"] = canonical_digest(continuation)
+    if (len(canonical_bytes(continuation)) + 3) // 4 > target_tokens * 2:
+        return {
+            "schemaVersion": "agent-context-continuation.v1",
+            "status": "BLOCKED",
+            "checkpointId": checkpoint.get("checkpointId"),
+            "validation": {
+                **validation,
+                "status": "FAIL",
+                "blockers": [{"code": "context-restore-token-limit"}],
+            },
+            "implementationAuthorized": False,
+            "proofAuthority": "none",
+            "productionPromotionClaimed": False,
+        }
+    return continuation
+
+
+def _lineage_from_state(state: dict[str, Any], *, session_id: str | None) -> dict[str, Any]:
+    fields = ("runId", "packageId", "planRevision", "planDigest", "stateRevision", "sourceRevision")
+    expected = {key: state.get(key) for key in fields if key in state}
+    if session_id is not None:
+        expected["sessionId"] = session_id
+    return expected
+
+
+def _retain_latest(directory: Path, *, run_id: str, limit: int) -> None:
+    if not isinstance(limit, int) or limit < 1 or limit > MAX_CHECKPOINTS_PER_RUN:
+        raise LifecycleError("context-checkpoint-retention-invalid", "retention limit must be between 1 and 64")
+    items = list_context_checkpoints(root=directory, run_id=run_id)
+    for item in items[:-limit]:
+        path = checkpoint_path(str(item["checkpointId"]), root=directory)
+        if path.resolve().is_relative_to(directory.resolve()):
+            path.unlink()
+
+
+def _write_atomic(path: Path, data: bytes) -> None:
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    try:
+        with os.fdopen(os.open(temporary, flags, 0o644), "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        if temporary.exists():
+            temporary.unlink()