@agentikos/omega-os 0.2.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/handoff.py

@@ -0,0 +1,459 @@
+"""Handoff — structured session-end memo so the next agent picks up cleanly.
+
+The 5-section contract
+----------------------
+
+Every handoff has EXACTLY these five sections, in this order:
+
+  1. **Mission** — one-sentence statement of what the session was trying
+     to achieve.
+  2. **State** — what works, what doesn't (concrete, observed runtime).
+  3. **Files touched** — exact paths (no guessing) + the relevant
+     line numbers when applicable.
+  4. **Dead ends** — what was tried and DOESN'T work, so the next agent
+     doesn't re-walk the same wall.
+  5. **Next** — the first concrete action for the next session.
+
+Why this exists
+---------------
+
+When an agent does ``/clear`` or its session times out, the next agent
+re-discovers everything from scratch — re-reads files, re-runs commands,
+re-makes the same mistakes. The handoff IS the institutional memory
+between sessions. It's not optional documentation; it's a load-bearing
+piece of the agentic OS.
+
+Storage
+-------
+
+::
+
+    $OMEGA_HOME/
+      Agentik_Coding/projects/<slug>/
+        HANDOFF.md                            ← always-latest (overwritten)
+        .omega/handoffs/<iso-ts>-<short>.md   ← timestamped archive
+
+    $OMEGA_HOME/Agentik_Runtime/sessions/<task_id>/
+      handoff.md                              ← per-task (auto-generated
+                                                  from .done.json + git
+                                                  when a worker finishes)
+
+The same dataclass + writer power all three; only the path resolution
+differs.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import time
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Handoff:
+    mission: str                           # one-sentence statement
+    state: str                             # markdown body — works vs broken
+    files_touched: list[str]               # exact paths
+    dead_ends: list[str]                   # short bullets, what NOT to retry
+    next_steps: list[str]                  # first action(s) for next session
+    author: str = ""                       # "worker" | "oracle" | "human" | ...
+    task_id: str = ""                      # optional anchor
+    mission_id: str = ""                   # optional anchor
+    project: str = ""                      # project slug if any
+    created_at: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat(
+            timespec="seconds"
+        )
+    )
+
+    def to_markdown(self) -> str:
+        """Render the canonical 5-section markdown."""
+        files = "\n".join(f"- `{p}`" for p in self.files_touched) or "_(none)_"
+        dead = "\n".join(f"- {d}" for d in self.dead_ends) or "_(none)_"
+        nxt  = "\n".join(f"{i+1}. {step}"
+                         for i, step in enumerate(self.next_steps)) \
+                or "_(none)_"
+        anchors: list[str] = []
+        if self.project:    anchors.append(f"project=`{self.project}`")
+        if self.mission_id: anchors.append(f"mission=`{self.mission_id}`")
+        if self.task_id:    anchors.append(f"task=`{self.task_id}`")
+        if self.author:     anchors.append(f"author=`{self.author}`")
+        meta = "  ·  ".join(anchors)
+        return f"""\
+# Handoff — {self.created_at}
+
+{meta}
+
+## 1. Mission
+
+{self.mission.strip()}
+
+## 2. State (what works / what doesn't)
+
+{self.state.strip() if self.state.strip() else "_(no state captured)_"}
+
+## 3. Files touched
+
+{files}
+
+## 4. Dead ends — DO NOT retry
+
+{dead}
+
+## 5. Next — start here
+
+{nxt}
+"""
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), indent=2)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "Handoff":
+        return Handoff(
+            mission=str(d.get("mission", "")),
+            state=str(d.get("state", "")),
+            files_touched=list(d.get("files_touched") or []),
+            dead_ends=list(d.get("dead_ends") or []),
+            next_steps=list(d.get("next_steps") or []),
+            author=str(d.get("author", "")),
+            task_id=str(d.get("task_id", "")),
+            mission_id=str(d.get("mission_id", "")),
+            project=str(d.get("project", "")),
+            created_at=str(
+                d.get("created_at",
+                      datetime.now(timezone.utc).isoformat(timespec="seconds"))
+            ),
+        )
+
+    @staticmethod
+    def from_markdown(text: str) -> "Handoff":
+        """Best-effort parse — reads back a handoff written by to_markdown.
+
+        Tolerant: if a section is missing or differently formatted, that
+        field comes back empty. We only require that the 5 section
+        headings appear in order; everything else is recovered.
+        """
+        sections = _split_sections(text)
+        return Handoff(
+            mission=sections.get("1", "").strip(),
+            state=sections.get("2", "").strip(),
+            files_touched=_parse_bullets(sections.get("3", "")),
+            dead_ends=_parse_bullets(sections.get("4", "")),
+            next_steps=_parse_numbered(sections.get("5", "")),
+            created_at=_extract_created_at(text),
+        )
+
+
+_SECTION_RE = re.compile(r"^##\s+(\d)\.", re.MULTILINE)
+_BULLET_RE = re.compile(r"^[-*]\s+(.+?)\s*$", re.MULTILINE)
+_NUM_RE = re.compile(r"^\d+\.\s+(.+?)\s*$", re.MULTILINE)
+_CREATED_RE = re.compile(r"^#\s+Handoff\s+—\s+(.+?)\s*$", re.MULTILINE)
+
+
+def _split_sections(text: str) -> dict[str, str]:
+    """Return ``{"1": "..body..", "2": "..", ...}`` from a 5-section handoff."""
+    matches = list(_SECTION_RE.finditer(text))
+    out: dict[str, str] = {}
+    for i, m in enumerate(matches):
+        start = m.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        # strip the heading line itself
+        body_start = text.find("\n", start)
+        if body_start == -1:
+            continue
+        out[m.group(1)] = text[body_start + 1:end].strip()
+    return out
+
+
+def _parse_bullets(body: str) -> list[str]:
+    out: list[str] = []
+    for m in _BULLET_RE.finditer(body):
+        raw = m.group(1).strip()
+        if raw == "_(none)_":
+            return []
+        # strip surrounding backticks for paths
+        raw = raw.strip("`")
+        out.append(raw)
+    return out
+
+
+def _parse_numbered(body: str) -> list[str]:
+    out: list[str] = []
+    for m in _NUM_RE.finditer(body):
+        raw = m.group(1).strip()
+        if raw == "_(none)_":
+            return []
+        out.append(raw)
+    return out
+
+
+def _extract_created_at(text: str) -> str:
+    m = _CREATED_RE.search(text)
+    if m:
+        return m.group(1).strip()
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+# ---------------------------------------------------------------------------
+# Path resolution
+# ---------------------------------------------------------------------------
+
+
+def _omega_home(home: str | Path | None) -> Path:
+    if home is not None:
+        return Path(home)
+    return Path(os.environ.get("OMEGA_HOME", str(Path.home() / "Omega")))
+
+
+def project_handoff_dir(home: Path, slug: str) -> Path:
+    """Per-project archive dir (one file per past handoff)."""
+    return home / "Agentik_Coding" / "projects" / slug / ".omega" / "handoffs"
+
+
+def project_latest_path(home: Path, slug: str) -> Path:
+    """Always-latest pointer at the project root — friendly for `cat HANDOFF.md`."""
+    return home / "Agentik_Coding" / "projects" / slug / "HANDOFF.md"
+
+
+def task_handoff_path(home: Path, task_id: str) -> Path:
+    """Per-task handoff lives next to the .done.json."""
+    return (
+        home / "Agentik_Runtime" / "sessions" / task_id / "handoff.md"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Atomic write helpers
+# ---------------------------------------------------------------------------
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    """Write `content` to `path` atomically (temp + rename + fsync)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    import threading
+    tmp = path.with_suffix(
+        path.suffix + f".tmp.{os.getpid()}.{threading.get_ident()}"
+    )
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+    with os.fdopen(fd, "w") as fh:
+        fh.write(content)
+        fh.flush()
+        try:
+            os.fsync(fh.fileno())
+        except OSError:
+            pass
+    os.replace(tmp, path)
+
+
+# ---------------------------------------------------------------------------
+# Public API — write / read / list
+# ---------------------------------------------------------------------------
+
+
+def write_handoff(
+    home: str | Path,
+    handoff: Handoff,
+    *,
+    target: str = "project",   # "project" | "task" | "both"
+) -> dict[str, str]:
+    """Persist a handoff. Returns ``{written: [path, ...]}``.
+
+    Targets:
+      * ``project`` — writes HANDOFF.md at project root + an archive copy
+                       under .omega/handoffs/<ts>-<slug>.md
+                       (requires ``handoff.project``)
+      * ``task``    — writes Agentik_Runtime/sessions/<task_id>/handoff.md
+                       (requires ``handoff.task_id``)
+      * ``both``    — both of the above
+    """
+    home = _omega_home(home)
+    md = handoff.to_markdown()
+    written: list[str] = []
+
+    if target in ("project", "both"):
+        if not handoff.project:
+            raise ValueError("target=project requires handoff.project to be set")
+        latest = project_latest_path(home, handoff.project)
+        _atomic_write(latest, md)
+        written.append(str(latest))
+        # archive copy — never overwrite
+        ts = handoff.created_at.replace(":", "").replace("-", "").replace("+", "p")
+        short = re.sub(r"[^A-Za-z0-9]+", "-", handoff.mission[:40]).strip("-") or "handoff"
+        archive = project_handoff_dir(home, handoff.project) / f"{ts}-{short}.md"
+        _atomic_write(archive, md)
+        written.append(str(archive))
+
+    if target in ("task", "both"):
+        if not handoff.task_id:
+            raise ValueError("target=task requires handoff.task_id to be set")
+        p = task_handoff_path(home, handoff.task_id)
+        _atomic_write(p, md)
+        written.append(str(p))
+
+    return {"written": written}
+
+
+def read_handoff(
+    home: str | Path,
+    *,
+    project: str | None = None,
+    task_id: str | None = None,
+) -> Handoff | None:
+    """Read the latest handoff for a project or a task. None if missing."""
+    home = _omega_home(home)
+    if project:
+        p = project_latest_path(home, project)
+    elif task_id:
+        p = task_handoff_path(home, task_id)
+    else:
+        raise ValueError("read_handoff requires either project=... or task_id=...")
+    if not p.exists():
+        return None
+    try:
+        return Handoff.from_markdown(p.read_text())
+    except OSError:
+        return None
+
+
+def list_handoffs(
+    home: str | Path, project: str,
+) -> list[dict[str, str]]:
+    """Chronological list of archived handoffs for a project (newest first)."""
+    home = _omega_home(home)
+    d = project_handoff_dir(home, project)
+    if not d.is_dir():
+        return []
+    out: list[dict[str, str]] = []
+    for f in sorted(d.glob("*.md"), reverse=True):
+        try:
+            ho = Handoff.from_markdown(f.read_text())
+        except OSError:
+            continue
+        out.append({
+            "path": str(f),
+            "created_at": ho.created_at,
+            "mission": ho.mission[:80],
+            "next_first": ho.next_steps[0] if ho.next_steps else "",
+        })
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Auto-draft from a worker's .done.json + git status
+# ---------------------------------------------------------------------------
+
+
+def from_done_signal(
+    home: str | Path, task_id: str,
+    *,
+    cwd: str | Path | None = None,
+) -> Handoff:
+    """Build a handoff draft from a worker's .done.json + the git diff at cwd.
+
+    The draft is intentionally INCOMPLETE — sections like "dead_ends" can't
+    be auto-inferred. The expectation is that a human or a follow-up agent
+    polishes it before the next /clear. The point is to seed the file
+    instead of leaving the next session with nothing.
+    """
+    home = _omega_home(home)
+    from omega_engine.done_signal import read_done
+
+    sig = read_done(home, task_id)
+    mission = ""
+    state = ""
+    files_touched: list[str] = []
+    if sig is not None:
+        # Mission inferred from the brief's intent (best-effort)
+        try:
+            from omega_engine.worker import read_brief
+            b = read_brief(home, task_id)
+            mission = b.intent[:200]
+        except Exception:  # noqa: BLE001
+            pass
+        state = sig.summary or ""
+        files_touched = list(sig.files_changed or [])
+
+    # Augment files_touched with `git diff --name-only` if a cwd is given.
+    if cwd:
+        try:
+            proc = subprocess.run(
+                ["git", "-C", str(cwd), "diff", "--name-only", "HEAD"],
+                capture_output=True, text=True, timeout=15, check=False,
+            )
+            if proc.returncode == 0:
+                for line in proc.stdout.splitlines():
+                    line = line.strip()
+                    if line and line not in files_touched:
+                        files_touched.append(line)
+        except (OSError, subprocess.SubprocessError):
+            pass
+
+    next_steps: list[str] = []
+    if sig is not None and sig.status == "pending" and sig.pending_actions:
+        next_steps = list(sig.pending_actions)
+    elif sig is not None and sig.status == "failed":
+        next_steps = [
+            f"investigate the failure: {sig.errors[0]}"
+            if sig.errors else "investigate the failure"
+        ]
+
+    return Handoff(
+        mission=mission or f"(task {task_id})",
+        state=state,
+        files_touched=files_touched,
+        dead_ends=[],
+        next_steps=next_steps,
+        author=f"worker:{task_id}",
+        task_id=task_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Template — exported so the CLI / skill can show it
+# ---------------------------------------------------------------------------
+
+
+TEMPLATE = """\
+# Handoff — <iso-timestamp>
+
+project=`<slug>`  ·  mission=`<id>`  ·  task=`<id>`  ·  author=`<who>`
+
+## 1. Mission
+
+One sentence: what was this session trying to achieve?
+
+## 2. State (what works / what doesn't)
+
+- Works: <concrete, observed runtime — e.g. "auth flow signs in, /dashboard renders">
+- Broken: <concrete, observed — e.g. "/settings throws 500 on PATCH /api/profile">
+- Verified by: <how you know — `npm test` / playwright / curl / manual>
+
+## 3. Files touched
+
+- `path/to/file1.ts`
+- `path/to/file2.tsx:42-78`
+- `tests/foo.test.ts`
+
+## 4. Dead ends — DO NOT retry
+
+- Tried <approach A>; failed because <reason>. Don't re-walk this wall.
+- Tried <approach B>; produced <wrong behaviour>. Causes <side-effect>.
+
+## 5. Next — start here
+
+1. First concrete action the next agent should take.
+2. Second concrete action (if obviously chained).
+3. Validation: how to confirm the next step worked.
+"""