keepai 0.6.1__py3-none-any.whl

keep/agent.py

@@ -0,0 +1,72 @@
+"""Agent abstraction — entry point for multi-agent support (Plan #14 walking skeleton).
+
+This module defines the `Agent` Protocol that keep's daemon and CLI will
+talk to once multi-agent support is fully wired up. Plan #11 designed the
+full 5-method interface; Plan #14 is a spike that implements **only** the
+`last_message()` method to validate the abstraction is buildable.
+
+Concrete implementations live under `keep.agents.*`:
+    - `keep.agents.*` — Claude Code implementation (this plan)
+    - (future) `keep.agents.*` — OpenAI Codex CLI
+
+Design discrepancy from Plan #11 §3.1 captured in the walking skeleton
+report: `AgentMessage.ts` is typed `str | None` here, not `datetime | None`
+as originally specced. Reason: the current CC JSONL timestamp format
+(`2026-04-09T01:55:03.323Z`) does not round-trip byte-identically through
+Python's `datetime.isoformat()` (pads microseconds to 6 digits, rewrites
+`Z` to `+00:00`). The `keep read` CLI must stay byte-identical per Plan
+#14's acceptance criterion, and preserving the raw source string is the
+least invasive way to satisfy both Plan #14 and Plan #11's spirit.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AgentMessage(BaseModel):
+    """Single assistant reply from an agent session."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    text: str
+    ts: str | None = None
+    """Raw ISO8601 timestamp string from the source, preserved verbatim.
+
+    Deliberately `str`, not `datetime`: CC JSONL writes `2026-04-09T01:55:03.323Z`
+    but `datetime.fromisoformat(...).isoformat()` round-trips to
+    `2026-04-09T01:55:03.323000+00:00` — not byte-identical. Plan #14 accepts
+    this field-level deviation from Plan #11 §3.1 so the `keep read` CLI can
+    re-emit the timestamp unchanged. Plan #15+ may revisit.
+    """
+
+    turn_id: str | None = None
+    """Opaque, agent-specific identifier for cross-referencing turns.
+    Unused in Plan #14; reserved for future use."""
+
+
+class Agent(Protocol):
+    """Protocol for an AI coding agent that keep orchestrates.
+
+    Plan #14 walking skeleton only implements `last_message()`. The other
+    four methods from Plan #11 §3.2 (`status`, `poll_events`, `send`,
+    `interrupt`) are intentionally **not** declared here yet — adding them
+    as stubs would force every implementation to `NotImplementedError`
+    them, which defeats the point of Protocol typing. They will be added
+    in subsequent plans once their own walking skeletons pass.
+    """
+
+    def last_message(self, session: str) -> AgentMessage | None:
+        """Return the most recent assistant reply for `session`, or None.
+
+        None means no retrievable message: session log missing, malformed,
+        empty, or no assistant entries yet. Query method — never raises;
+        all errors collapse to None. Idempotent and non-consuming.
+
+        `session` is an agent-specific identifier (CC session name or
+        UUID, Codex thread_id, etc.). The concrete `Agent` implementation
+        interprets it.
+        """
+        ...

keep/agents/__init__.py

@@ -0,0 +1,7 @@
+"""Concrete `Agent` implementations.
+
+Each submodule hosts one implementation of `keep.agent.Agent`:
+
+- `cc` — Claude Code (this plan)
+- (future) `codex` — OpenAI Codex CLI (Plan #17 per Plan #11 §9)
+"""

keep/agents/cc.py

@@ -0,0 +1,75 @@
+"""Claude Code implementation of `keep.agent.Agent`.
+
+Plan #14 walking skeleton — only `last_message()` is implemented. The impl
+wraps the existing `keep.worker.resolve_worker` + `read_last_message`
+helpers rather than duplicating their logic, so behavior stays consistent
+with the pre-abstraction `keep read` command.
+
+Plan #14 Part 3 requires the `last_message` read path to be exercisable on
+my-laptop (Linux Python 3.12.3, no cmux installed). `resolve_worker`
+unconditionally requires cmux env vars (CMUX_WORKSPACE_ID /
+CMUX_SURFACE_ID) and `ps` reachability for the CC process, which is a hard
+block on cmux-less environments. To keep the Protocol signature clean
+while making Part 3 possible, `last_message()` accepts an **optional**
+`jsonl_path` keyword argument that short-circuits `resolve_worker`. The
+Protocol itself only advertises `last_message(session)`; the keyword arg
+is a CC-impl-specific dependency-injection hatch for tests and for
+cmux-less realistic testing.
+
+This DI hatch is **the minimum deviation from Plan #11 §3.2** required to
+make the walking skeleton testable end-to-end without cmux. It is called
+out explicitly in the Plan #14 report.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from keep.agent import AgentMessage
+from keep.worker import read_last_message, resolve_worker
+
+
+class CCAgent:
+    """Plan #14 walking skeleton CCAgent — implements `Agent.last_message` only."""
+
+    name = "claude-code"
+
+    def last_message(
+        self,
+        session: str,
+        *,
+        jsonl_path: Path | str | None = None,
+    ) -> AgentMessage | None:
+        """Return the most recent assistant reply for a CC session.
+
+        Resolution order for the JSONL file:
+
+        1. If `jsonl_path` is provided explicitly, use it directly. This is
+           the DI hatch for tests and for cmux-less realistic testing (see
+           module docstring).
+        2. Otherwise call `resolve_worker(session)` to discover the JSONL
+           via the `ps` + cmux env var path used by the rest of keep.
+
+        Returns None for any failure mode — missing file, malformed file,
+        no assistant entries yet, or unreachable session. Query method,
+        never raises. All three error branches of the underlying
+        `worker.read_last_message` collapse into None (see Plan #14 report
+        for the specific CLI error-message specificity loss this causes
+        in `keep read`).
+        """
+        if jsonl_path is not None:
+            path = Path(jsonl_path)
+        else:
+            info = resolve_worker(session)
+            if info.jsonl_path is None:
+                return None
+            path = info.jsonl_path
+
+        result = read_last_message(path)
+        if not result.get("ok"):
+            return None
+
+        return AgentMessage(
+            text=result["message"],
+            ts=result.get("timestamp") or None,
+        )