agent-handover 0.1.0__py3-none-any.whl

agent_handover/__init__.py

@@ -0,0 +1,12 @@
+"""agent-handover — session handover engine for AI coding agents.
+
+Checkpointed, resumable, backend-agnostic persistent memory so an AI agent
+can end a session and the next session can pick up exactly where it left off.
+"""
+from agent_handover.checkpoint import Checkpoint
+from agent_handover.memory import MemoryStore
+from agent_handover.engine import HandoverEngine, Step
+from agent_handover.backends import GitBackend, NullBackend
+
+__version__ = "0.1.0"
+__all__ = ["Checkpoint", "MemoryStore", "HandoverEngine", "Step", "GitBackend", "NullBackend"]

agent_handover/backends.py

@@ -0,0 +1,62 @@
+"""Publish backends.
+
+The MemoryStore writes plain files; a backend decides what "persist" means
+beyond the local disk. GitBackend commits and pushes the memory root so the
+state survives machine loss and is shareable across machines/agents.
+
+Implement the Backend protocol to add others (S3, NotebookLM, vector DB...).
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Protocol
+
+
+class Backend(Protocol):
+    def publish(self, message: str, dry_run: bool = False) -> bool: ...
+
+
+class NullBackend:
+    """Local-only: files on disk are enough."""
+
+    def publish(self, message: str, dry_run: bool = False) -> bool:
+        return True
+
+
+class GitBackend:
+    def __init__(self, repo_root: Path | str, paths: list[str] | None = None,
+                 branch: str = "main", remote: str = "origin",
+                 push: bool = True, timeout: int = 60):
+        self.repo_root = Path(repo_root)
+        self.paths = paths or ["."]
+        self.branch = branch
+        self.remote = remote
+        self.push = push
+        self.timeout = timeout
+
+    def _git(self, *args: str, timeout: int | None = None) -> subprocess.CompletedProcess:
+        return subprocess.run(
+            ["git", "-C", str(self.repo_root), *args],
+            capture_output=True, text=True, timeout=timeout or self.timeout,
+        )
+
+    def publish(self, message: str, dry_run: bool = False) -> bool:
+        if dry_run:
+            return True
+        try:
+            r = self._git("add", *self.paths)
+            if r.returncode != 0:
+                return False
+            r = self._git("commit", "-m", message)
+            if r.returncode != 0:
+                combined = r.stdout + r.stderr
+                if "nothing to commit" in combined:
+                    return True  # no changes is a success, not a failure
+                return False
+            if self.push:
+                r = self._git("push", self.remote, self.branch)
+                return r.returncode == 0
+            return True
+        except subprocess.TimeoutExpired:
+            return False

agent_handover/checkpoint.py

@@ -0,0 +1,79 @@
+"""Crash-safe checkpoint for multi-step handover runs.
+
+A handover that dies halfway is worse than no handover at all: the next
+session inherits a half-written state. Every step is recorded here so an
+interrupted run can be detected and resumed.
+
+Exit-code contract (used by ``agent-handover check``):
+    0 = no resume needed (no run in progress)
+    1 = resume needed   (a run was interrupted; pending steps remain)
+    2 = last run completed
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+RESUME_NONE = 0
+RESUME_NEEDED = 1
+RESUME_COMPLETED = 2
+
+
+class Checkpoint:
+    def __init__(self, path: Path | str):
+        self.path = Path(path)
+
+    # -- persistence ---------------------------------------------------
+    def load(self) -> dict:
+        if self.path.exists():
+            with open(self.path, encoding="utf-8") as f:
+                return json.load(f)
+        return {"status": "none", "steps": {}, "started_at": None, "finished_at": None}
+
+    def _save(self, data: dict) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".tmp")
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+        tmp.replace(self.path)  # atomic on POSIX
+
+    # -- lifecycle -----------------------------------------------------
+    def start(self, step_names: list[str]) -> None:
+        data = self.load()
+        if data["status"] == "in_progress":
+            # keep existing progress; only add unknown steps
+            for name in step_names:
+                data["steps"].setdefault(name, "pending")
+        else:
+            data = {
+                "status": "in_progress",
+                "steps": {name: "pending" for name in step_names},
+                "started_at": datetime.now(timezone.utc).isoformat(),
+                "finished_at": None,
+            }
+        self._save(data)
+
+    def mark_done(self, step_name: str) -> None:
+        data = self.load()
+        data["steps"][step_name] = "done"
+        self._save(data)
+
+    def complete(self) -> None:
+        data = self.load()
+        data["status"] = "completed"
+        data["finished_at"] = datetime.now(timezone.utc).isoformat()
+        self._save(data)
+
+    # -- inspection ----------------------------------------------------
+    def pending_steps(self) -> list[str]:
+        data = self.load()
+        return [k for k, v in data.get("steps", {}).items() if v != "done"]
+
+    def resume_code(self) -> int:
+        data = self.load()
+        if data["status"] == "completed":
+            return RESUME_COMPLETED
+        if data["status"] == "in_progress":
+            return RESUME_NEEDED if self.pending_steps() else RESUME_COMPLETED
+        return RESUME_NONE

agent_handover/cli.py

@@ -0,0 +1,39 @@
+"""CLI: agent-handover check|status  (run is wired up by your own script)."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from agent_handover.checkpoint import Checkpoint
+
+DEFAULT_CHECKPOINT = Path(".agent-handover/checkpoint.json")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="agent-handover")
+    parser.add_argument("command", choices=["check", "status"])
+    parser.add_argument("--checkpoint", type=Path, default=DEFAULT_CHECKPOINT)
+    args = parser.parse_args(argv)
+
+    cp = Checkpoint(args.checkpoint)
+
+    if args.command == "check":
+        return cp.resume_code()
+
+    if args.command == "status":
+        data = cp.load()
+        print(f"status: {data['status']}")
+        for name, state in data.get("steps", {}).items():
+            mark = "x" if state == "done" else " "
+            print(f"  [{mark}] {name}")
+        pending = cp.pending_steps()
+        if data["status"] == "in_progress" and pending:
+            print(f"pending: {', '.join(pending)}")
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_handover/engine.py

@@ -0,0 +1,69 @@
+"""Handover engine: run named steps under a checkpoint, resume on failure.
+
+Design rules learned from running this in production:
+
+1. Every step is checkpointed — a crash mid-handover must be detectable
+   and resumable, never silently half-done.
+2. A PAUSE file is an absolute kill-switch for all automation. Agents that
+   write to your repos need a brake the human can pull without an editor.
+3. Remote layers fail; the local filesystem copy is the fallback that the
+   next session can always boot from.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+from agent_handover.checkpoint import Checkpoint
+
+
+@dataclass
+class Step:
+    name: str
+    run: Callable[[], None]
+
+
+class PauseError(RuntimeError):
+    pass
+
+
+class StepError(RuntimeError):
+    def __init__(self, step_name: str, cause: Exception):
+        super().__init__(f"step '{step_name}' failed: {cause}")
+        self.step_name = step_name
+        self.cause = cause
+
+
+class HandoverEngine:
+    def __init__(self, steps: list[Step], checkpoint: Checkpoint,
+                 pause_file: Path | str | None = None):
+        self.steps = steps
+        self.checkpoint = checkpoint
+        self.pause_file = Path(pause_file) if pause_file else None
+
+    def _check_pause(self) -> None:
+        if self.pause_file and self.pause_file.exists():
+            raise PauseError(f"automation paused: remove {self.pause_file} to resume")
+
+    def run(self, resume: bool = True) -> list[str]:
+        """Run all (or pending) steps. Returns the list of steps executed."""
+        self._check_pause()
+
+        pending = set(self.checkpoint.pending_steps()) if resume else None
+        self.checkpoint.start([s.name for s in self.steps])
+
+        executed: list[str] = []
+        for step in self.steps:
+            if resume and pending is not None and pending and step.name not in pending:
+                continue  # already done in the interrupted run
+            self._check_pause()
+            try:
+                step.run()
+            except Exception as exc:  # checkpoint keeps this step pending
+                raise StepError(step.name, exc) from exc
+            self.checkpoint.mark_done(step.name)
+            executed.append(step.name)
+
+        self.checkpoint.complete()
+        return executed

agent_handover/memory.py

@@ -0,0 +1,67 @@
+"""Three-layer persistent memory store, written as plain Markdown.
+
+Layer 1  session notes      — what happened in one session (append, dated)
+Layer 2  current state      — single always-overwritten snapshot ("where are we now")
+Layer 3  consolidated       — monthly compaction of old Layer-1 notes
+
+Everything is plain files under one root, so the store is git-friendly,
+diff-able, and readable by humans and by any agent that can read a file.
+A remote/semantic layer (vector DB, NotebookLM, etc.) can sit on top, but
+the filesystem copy is always the source of truth and the fallback.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+HEADER = "<!-- agent-handover | layer{layer} | {date} -->\n"
+
+
+class MemoryStore:
+    def __init__(self, root: Path | str):
+        self.root = Path(root)
+
+    # -- write ----------------------------------------------------------
+    def write(self, layer: int, content: str, tag: str = "general",
+              date_str: str | None = None, dry_run: bool = False) -> Path:
+        if layer not in (1, 2, 3):
+            raise ValueError(f"invalid layer: {layer}")
+        date_str = date_str or datetime.now().strftime("%Y-%m-%d")
+        ym = date_str[:7]
+        safe_tag = tag.replace("/", "-").replace(" ", "_")
+
+        if layer == 1:
+            target = self.root / "layer1" / ym / f"{safe_tag}-{date_str}.md"
+        elif layer == 2:
+            target = self.root / "layer2" / "current-state.md"
+        else:
+            target = self.root / "layer3" / f"{ym}-{safe_tag}-archive.md"
+
+        if not dry_run:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(
+                HEADER.format(layer=layer, date=date_str) + content,
+                encoding="utf-8",
+            )
+        return target
+
+    # -- read (fallback path when no remote layer is available) ---------
+    def read_latest(self, layer: int, tag: str | None = None) -> str:
+        if layer == 2:
+            current = self.root / "layer2" / "current-state.md"
+            return current.read_text(encoding="utf-8") if current.exists() else ""
+
+        sub = self.root / f"layer{layer}"
+        if not sub.exists():
+            return ""
+        files = sorted(sub.rglob("*.md"), key=lambda p: p.stat().st_mtime, reverse=True)
+        if tag:
+            files = [f for f in files if tag in f.name]
+        return files[0].read_text(encoding="utf-8") if files else ""
+
+    # -- compaction ------------------------------------------------------
+    def layer1_note_count(self, ym: str | None = None) -> int:
+        sub = self.root / "layer1"
+        if ym:
+            sub = sub / ym
+        return len(list(sub.rglob("*.md"))) if sub.exists() else 0

agent_handover-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: agent-handover
+Version: 0.1.0
+Summary: Session handover engine for AI coding agents: checkpointed, resumable, backend-agnostic persistent memory.
+Project-URL: Homepage, https://github.com/hikari716/agent-handover
+Project-URL: Issues, https://github.com/hikari716/agent-handover/issues
+Author: Hiroyuki Nagashima
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude,codex,context,handover,llm,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# agent-handover
+
+**Session handover engine for AI coding agents: checkpointed, resumable, backend-agnostic persistent memory.**
+
+AI coding agents (Claude Code, Codex, OpenCode, Cline, ...) are stateless between
+sessions. Every new session starts with re-explaining the project, the decisions
+already made, and what was left half-done. `agent-handover` is the small piece of
+infrastructure that fixes this: at the end of a session the agent writes a
+structured handover; at the start of the next one, it resumes from it — even if
+the previous handover crashed halfway.
+
+Extracted from a personal "AI Team OS" that has run daily handovers across
+multiple machines and agents since 2025.
+
+## The problem
+
+- **Context loss**: the next session doesn't know what the last one decided.
+- **Half-written state**: a handover that dies mid-run silently corrupts memory.
+  The next session boots from a state that is *partly* updated — worse than stale.
+- **Remote memory is fragile**: vector DBs and hosted notebooks go down.
+  If your agent's memory has no local fallback, your agent has no memory.
+
+## Design
+
+```
+┌─ session ends ──────────────────────────────────────────────┐
+│  HandoverEngine(steps, checkpoint, pause_file)              │
+│    step 1: collect session facts          ── checkpointed   │
+│    step 2: MemoryStore.write(layer=1...)  ── checkpointed   │
+│    step 3: MemoryStore.write(layer=2...)  ── checkpointed   │
+│    step 4: GitBackend.publish(...)        ── checkpointed   │
+└──────────────────────────────────────────────────────────────┘
+┌─ next session starts ───────────────────────────────────────┐
+│  $ agent-handover check    # 0=clean  1=RESUME  2=completed │
+│  read layer2/current-state.md  →  agent has context again   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Three memory layers, all plain Markdown** (git-friendly, diff-able, readable
+by humans and any agent that can read a file):
+
+| Layer | File pattern | Semantics |
+|---|---|---|
+| 1 | `layer1/YYYY-MM/<tag>-<date>.md` | session notes (append, dated) |
+| 2 | `layer2/current-state.md` | "where are we now" (always overwritten) |
+| 3 | `layer3/YYYY-MM-<tag>-archive.md` | monthly compaction of old notes |
+
+**Three rules learned in production:**
+
+1. *Every step is checkpointed.* An interrupted handover is detected
+   (`agent-handover check` → exit 1) and resumed without re-running done steps.
+2. *A `PAUSE` file is an absolute kill-switch.* Agents that write to your repos
+   need a brake a human can pull with `touch PAUSE`.
+3. *The filesystem is the source of truth.* Remote layers (NotebookLM, vector
+   stores) are optional accelerators; the local copy is always enough to boot.
+
+## Install
+
+```bash
+pip install agent-handover   # or: pip install -e . from a clone
+```
+
+## Usage
+
+```python
+from pathlib import Path
+from agent_handover import Checkpoint, HandoverEngine, MemoryStore, Step, GitBackend
+
+store = MemoryStore("memory/")
+cp = Checkpoint(".agent-handover/checkpoint.json")
+git = GitBackend(".", paths=["memory/"])
+
+engine = HandoverEngine(
+    steps=[
+        Step("session_note", lambda: store.write(1, notes, tag="refactor")),
+        Step("current_state", lambda: store.write(2, snapshot)),
+        Step("publish", lambda: git.publish("handover: session sync")),
+    ],
+    checkpoint=cp,
+    pause_file=Path.home() / ".agent_handover" / "PAUSE",
+)
+engine.run()  # resumes pending steps automatically after a crash
+```
+
+In your agent's bootstrap (CLAUDE.md / AGENTS.md):
+
+```bash
+agent-handover check   # exit 1 → finish the interrupted handover first
+```
+
+## Status & roadmap
+
+- [x] checkpointed engine, 3-layer Markdown store, git backend, pause guardrail
+- [ ] handover quality scoring (was the note actually useful next session?)
+- [ ] adapters: NotebookLM, sqlite-vec
+- [ ] `agent-handover run` with declarative step config (TOML)
+
+Issues and PRs welcome — especially reports from other agent stacks
+(Codex CLI, Cline, OpenCode).
+
+## License
+
+MIT

agent_handover-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+agent_handover/__init__.py,sha256=YJfKCSEZewy8DN7Lx49FylvPI2ZJO0uKOiJiByenu20,554
+agent_handover/backends.py,sha256=2qh_iXG6qjEXlgOe909e7fD6iusUoiY-1lNAPIYsmTQ,2105
+agent_handover/checkpoint.py,sha256=zbrtpY-AssS_1o-IyupdM1u7RcUwcU5OBikG1DqUfTQ,2819
+agent_handover/cli.py,sha256=y22JH8qKLD37HiBCg0f815WEJd4Z99iLmIx_CUNFP20,1146
+agent_handover/engine.py,sha256=1OO_jW9y6wljd-AT700XTBN-CrOXIBmk5oLpORQR7sc,2342
+agent_handover/memory.py,sha256=qNaZsn3kuQ_A47-AkJ-rD9_N-weyTGn_Jl_B5t6sFPg,2760
+agent_handover-0.1.0.dist-info/METADATA,sha256=HeDf9Lx4J1pr4skvTPDG0Qo3wKXFbtP3EhGc8-OmWU4,5184
+agent_handover-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agent_handover-0.1.0.dist-info/entry_points.txt,sha256=KRE82jpEpC5NCJgY6YAen4bi0-HadC8AjgZ0FLgrDDg,59
+agent_handover-0.1.0.dist-info/licenses/LICENSE,sha256=XT4USyOSLF7IeMcTHQh9FNXA_ZOiaYbXpUnVevWRcNQ,1075
+agent_handover-0.1.0.dist-info/RECORD,,

agent_handover-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_handover-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-handover = agent_handover.cli:main

agent_handover-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hiroyuki Nagashima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.