turnloop 0.1.0__py3-none-any.whl

turnloop/sessions/models.py

@@ -0,0 +1,139 @@
+"""Session state.
+
+A Session owns the conversation, the todo list, and the accounting. It does not
+own the model, the tools or the UI — a subagent gets its own Session and shares
+nothing but the permission engine.
+
+Two views of history exist deliberately:
+
+* `messages` — what gets sent to the model, i.e. post-compaction.
+* the JSONL on disk — every message ever, uncompacted.
+
+Keeping the raw record is what makes `/rewind`, replay-mode experiments and
+after-the-fact analysis possible. Compaction is a context-window strategy, not a
+data-retention policy.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from turnloop.core.ids import new_id
+from turnloop.core.messages import Message, ToolUseBlock, Usage
+
+TodoStatus = Literal["pending", "in_progress", "completed"]
+
+
+class Todo(BaseModel):
+    content: str = Field(description="Imperative form, e.g. 'Add the retry test'.")
+    activeForm: str = Field(
+        default="", description="Present continuous, e.g. 'Adding the retry test'."
+    )
+    status: TodoStatus = "pending"
+
+
+@dataclass(slots=True)
+class CostState:
+    usage: Usage = field(default_factory=Usage)
+    cost_usd: float = 0.0
+    requests: int = 0
+    # Per-provider rollup, so a subagent on a cheaper model is visible separately.
+    by_provider: dict[str, float] = field(default_factory=dict)
+
+    def add(self, provider: str, usage: Usage, cost: float) -> None:
+        self.usage = self.usage + usage
+        self.cost_usd += cost
+        self.requests += 1
+        self.by_provider[provider] = self.by_provider.get(provider, 0.0) + cost
+
+
+@dataclass
+class Session:
+    session_id: str = field(default_factory=lambda: new_id("ses"))
+    started_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    provider: str = "mock"
+    model: str = ""
+    cwd: str = ""
+
+    messages: list[Message] = field(default_factory=list)
+    todos: list[Todo] = field(default_factory=list)
+    cost: CostState = field(default_factory=CostState)
+
+    turn: int = 0
+    compactions: int = 0
+    parent_id: str | None = None  # set for subagent sessions
+    subagent_type: str | None = None
+
+    # Set by the store when persistence is enabled.
+    store: object | None = None
+
+    # --- history -----------------------------------------------------------
+
+    def append(self, message: Message) -> Message:
+        self.messages.append(message)
+        if self.store is not None:
+            self.store.write_message(message)  # type: ignore[attr-defined]
+        return message
+
+    def replace_history(self, messages: list[Message]) -> None:
+        """Used by compaction. The on-disk log is not rewritten."""
+        self.messages = messages
+
+    @property
+    def last_assistant(self) -> Message | None:
+        for msg in reversed(self.messages):
+            if msg.role == "assistant":
+                return msg
+        return None
+
+    def pending_tool_uses(self) -> list[ToolUseBlock]:
+        """tool_use blocks in the last assistant message with no result yet.
+
+        An orphaned tool_use is a hard 400 from every provider, so this is checked
+        after an interrupted turn before the next request goes out.
+        """
+        last = self.last_assistant
+        if last is None:
+            return []
+        answered = {
+            b.tool_use_id
+            for msg in self.messages
+            for b in msg.tool_results
+        }
+        return [b for b in last.tool_uses if b.id not in answered]
+
+    # --- todos -------------------------------------------------------------
+
+    def set_todos(self, todos: list[Todo]) -> None:
+        self.todos = todos
+        if self.store is not None:
+            self.store.write_record("todos", {"todos": [t.model_dump() for t in todos]})  # type: ignore[attr-defined]
+
+    def todo_summary(self) -> str:
+        if not self.todos:
+            return ""
+        marks = {"pending": "[ ]", "in_progress": "[~]", "completed": "[x]"}
+        return "\n".join(f"{marks[t.status]} {t.content}" for t in self.todos)
+
+    # --- metadata ----------------------------------------------------------
+
+    def summary_line(self) -> str:
+        for msg in self.messages:
+            if msg.role == "user" and msg.text.strip():
+                return " ".join(msg.text.split())[:120]
+        return "(no user message)"
+
+    def meta(self) -> dict:
+        return {
+            "session_id": self.session_id,
+            "started_at": self.started_at.isoformat(),
+            "provider": self.provider,
+            "model": self.model,
+            "cwd": self.cwd,
+            "parent_id": self.parent_id,
+            "subagent_type": self.subagent_type,
+        }

turnloop/sessions/store.py

@@ -0,0 +1,271 @@
+"""Session persistence: append-only JSONL, one record per line.
+
+Append-only and flushed per line, so a hard kill (or a Ctrl-C during a 29-minute
+cold boot) loses at most the record being written. A single JSON document
+rewritten each turn would lose the whole session instead.
+
+Compaction is recorded as an event rather than by rewriting history:
+
+    {"kind": "compaction", "payload": {"summary": ..., "replaced": [0, 42]}}
+
+so replaying the log yields the compacted view the model actually saw, while the
+raw messages remain available for experiments and for `/rewind`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+from turnloop.core.messages import Message
+from turnloop.sessions.models import CostState, Session, Todo
+
+RecordKind = Literal[
+    "meta", "message", "compaction", "todos", "tool_metrics",
+    "permission", "hook", "error", "usage",
+]
+
+
+@dataclass(slots=True)
+class SessionInfo:
+    session_id: str
+    path: Path
+    started_at: datetime
+    provider: str
+    messages: int
+    summary: str
+
+
+class SessionStore:
+    """Writes one session's JSONL. Reading is done by the classmethods."""
+
+    def __init__(self, path: Path, session: Session):
+        self.path = path
+        self.session = session
+        self._seq = 0
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._fh = self.path.open("a", encoding="utf-8", newline="\n")
+        self.write_record("meta", session.meta())
+
+    # --- writing -----------------------------------------------------------
+
+    def write_record(self, kind: RecordKind, payload: dict) -> None:
+        self._seq += 1
+        line = json.dumps(
+            {
+                "seq": self._seq,
+                "ts": datetime.now(UTC).isoformat(),
+                "kind": kind,
+                "payload": payload,
+            },
+            ensure_ascii=False,
+            default=str,
+        )
+        self._fh.write(line + "\n")
+        self._fh.flush()
+        # fsync every line would triple the cost of a tool-heavy turn; flushing
+        # is enough to survive a process kill, which is the failure we care about.
+
+    def write_message(self, message: Message) -> None:
+        self.write_record("message", message.model_dump(mode="json"))
+
+    def write_compaction(self, tier: str, summary: str, replaced: tuple[int, int],
+                         tokens_before: int, tokens_after: int) -> None:
+        self.write_record(
+            "compaction",
+            {
+                "tier": tier,
+                "summary": summary,
+                "replaced": list(replaced),
+                "tokens_before": tokens_before,
+                "tokens_after": tokens_after,
+            },
+        )
+
+    def write_tool_metrics(self, name: str, metrics: dict[str, Any]) -> None:
+        self.write_record("tool_metrics", {"tool": name, **metrics})
+
+    def close(self) -> None:
+        try:
+            self._fh.close()
+        except Exception:  # noqa: BLE001
+            pass
+
+    # --- creating / loading ------------------------------------------------
+
+    @staticmethod
+    def sessions_dir(project_root: Path) -> Path:
+        return project_root / ".turnloop" / "sessions"
+
+    @classmethod
+    def attach(cls, session: Session, project_root: Path) -> SessionStore:
+        path = cls.sessions_dir(project_root) / f"{session.session_id}.jsonl"
+        store = cls(path, session)
+        session.store = store
+        return store
+
+    @classmethod
+    def list_sessions(cls, project_root: Path) -> list[SessionInfo]:
+        directory = cls.sessions_dir(project_root)
+        if not directory.is_dir():
+            return []
+        infos: list[SessionInfo] = []
+        for path in directory.glob("*.jsonl"):
+            info = cls._peek(path)
+            if info is not None:
+                infos.append(info)
+        infos.sort(key=lambda i: i.started_at, reverse=True)
+        return infos
+
+    @classmethod
+    def _peek(cls, path: Path) -> SessionInfo | None:
+        """Read a session's headline data without parsing every message."""
+        provider = "?"
+        started = datetime.fromtimestamp(path.stat().st_mtime, tz=UTC)
+        count = 0
+        summary = ""
+        try:
+            with path.open("r", encoding="utf-8") as fh:
+                for line in fh:
+                    if not line.strip():
+                        continue
+                    try:
+                        record = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    kind = record.get("kind")
+                    payload = record.get("payload") or {}
+                    if kind == "meta":
+                        provider = payload.get("provider", provider)
+                        if ts := payload.get("started_at"):
+                            try:
+                                started = datetime.fromisoformat(ts)
+                            except ValueError:
+                                pass
+                    elif kind == "message":
+                        count += 1
+                        if not summary and payload.get("role") == "user":
+                            text = "".join(
+                                b.get("text", "")
+                                for b in payload.get("content", [])
+                                if b.get("type") == "text"
+                            )
+                            summary = " ".join(text.split())[:120]
+        except OSError:
+            return None
+        return SessionInfo(
+            session_id=path.stem,
+            path=path,
+            started_at=started,
+            provider=provider,
+            messages=count,
+            summary=summary,
+        )
+
+    @classmethod
+    def resume(cls, project_root: Path, session_id: str | None = None) -> Session | None:
+        """Rebuild a Session from its log, applying recorded compactions.
+
+        The returned session continues writing to the *same* file, so a resumed
+        conversation stays one coherent record rather than a chain of fragments.
+        """
+        if session_id in (None, "__last__"):
+            infos = cls.list_sessions(project_root)
+            if not infos:
+                return None
+            path = infos[0].path
+        else:
+            path = cls.sessions_dir(project_root) / f"{session_id}.jsonl"
+            if not path.is_file():
+                return None
+
+        session = Session(session_id=path.stem)
+        messages: list[Message] = []
+        todos: list[Todo] = []
+        cost = CostState()
+
+        with path.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                try:
+                    record = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                kind = record.get("kind")
+                payload = record.get("payload") or {}
+
+                if kind == "meta":
+                    session.provider = payload.get("provider", session.provider)
+                    session.model = payload.get("model", session.model)
+                    session.cwd = payload.get("cwd", session.cwd)
+                elif kind == "message":
+                    try:
+                        messages.append(Message.model_validate(payload))
+                    except Exception:  # noqa: BLE001 - skip a corrupt line, keep the session
+                        continue
+                elif kind == "compaction":
+                    lo, hi = (payload.get("replaced") or [0, 0])[:2]
+                    tail = messages[hi:]
+                    summary = payload.get("summary", "")
+                    messages = (
+                        [Message.user_text(summary, compaction=True), *tail] if summary else tail
+                    )
+                    session.compactions += 1
+                elif kind == "todos":
+                    todos = [Todo.model_validate(t) for t in payload.get("todos", [])]
+                elif kind == "usage":
+                    cost.add(
+                        payload.get("provider", "?"),
+                        _usage(payload),
+                        float(payload.get("cost_usd", 0.0)),
+                    )
+
+        session.messages = messages
+        session.todos = todos
+        session.cost = cost
+        session.turn = sum(1 for m in messages if m.role == "user")
+
+        store = cls(path, session)
+        session.store = store
+        return session
+
+
+def _usage(payload: dict):
+    from turnloop.core.messages import Usage
+
+    return Usage(
+        input_tokens=payload.get("input_tokens", 0),
+        output_tokens=payload.get("output_tokens", 0),
+        cache_read_tokens=payload.get("cache_read_tokens", 0),
+        cache_write_tokens=payload.get("cache_write_tokens", 0),
+    )
+
+
+def default_project_dir(project_root: Path) -> Path:
+    d = project_root / ".turnloop"
+    d.mkdir(parents=True, exist_ok=True)
+    gitignore = d / ".gitignore"
+    if not gitignore.exists():
+        # Sessions contain file contents and command output. They are local
+        # working data, not something to commit by accident.
+        gitignore.write_text("sessions/\nsettings.local.json\n", encoding="utf-8")
+    return d
+
+
+def clear_sessions(project_root: Path) -> int:
+    directory = SessionStore.sessions_dir(project_root)
+    if not directory.is_dir():
+        return 0
+    removed = 0
+    for path in directory.glob("*.jsonl"):
+        try:
+            os.remove(path)
+            removed += 1
+        except OSError:
+            pass
+    return removed

turnloop/tools/ask.py

@@ -0,0 +1,133 @@
+"""AskUserQuestion — a structured prompt with options.
+
+Free-text questions are a poor interface in a terminal: the user has to type an
+answer while a turn is parked, and the model gets prose it must re-interpret.
+Options are answerable with one keystroke and unambiguous to consume.
+
+The failure mode this tool must avoid is being used as a substitute for judgment.
+Its description says so explicitly, and it is unavailable to subagents — a child
+agent blocking on the parent's modal is a deadlock waiting to happen.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from turnloop.permissions.engine import PermissionRequest
+from turnloop.tools.base import Tool, ToolContext, ToolOutput
+
+
+class Option(BaseModel):
+    label: str = Field(description="Short choice text, 1-5 words.")
+    description: str = Field(default="", description="What choosing this means.")
+
+
+class Question(BaseModel):
+    header: str = Field(description="Very short label, max 12 chars.")
+    question: str = Field(description="The full question.")
+    options: list[Option] = Field(description="2-4 mutually exclusive choices.")
+    multi_select: bool = Field(default=False, description="Allow several answers.")
+
+
+class AskArgs(BaseModel):
+    questions: list[Question] = Field(description="1-4 questions to ask together.")
+
+
+class AskUserQuestionTool(Tool):
+    name = "AskUserQuestion"
+    Args = AskArgs
+    read_only = True
+    parallel_safe = False
+    timeout_s = None  # a human is answering; there is no meaningful timeout
+
+    descriptions = {
+        "terse": """
+Ask the user to choose between options. Only when the answer genuinely changes
+what you build — otherwise pick the sensible default and proceed.
+""",
+        "normal": """
+Ask the user a question with concrete options.
+
+- Use this only when you are blocked on a decision that is genuinely theirs: two
+  readings of their request would lead to materially different work.
+- Do not use it for choices with an obvious default, for facts you can determine
+  by reading the code, or to ask permission to continue.
+- 1-4 questions, each with 2-4 options. Put your recommendation first and mark it
+  "(Recommended)".
+- Ask everything you need in one call rather than interrogating turn by turn.
+""",
+        "verbose": """
+Ask the user a question with concrete options.
+
+Arguments:
+- `questions`: 1-4 questions. Each has `header` (a very short chip label, max 12
+  characters), `question` (the full text), `options` (2-4 choices with a `label`
+  and a `description` of what that choice implies), and `multi_select`.
+
+When to use it:
+- You are blocked on a decision that is the user's to make, where proceeding on an
+  assumption would either be unsafe or waste the work if the guess is wrong.
+- Genuinely ambiguous requirements, where two readings lead to materially
+  different implementations.
+
+When not to use it:
+- The choice has a conventional default. Pick it, say you did, and continue.
+- The answer is discoverable by reading the code or the configuration. Go and read.
+- You want approval to proceed. Proceed; the permission system handles consent for
+  anything consequential.
+- You are unsure whether your work is good. Verify it instead.
+
+Guidance:
+- Ask everything at once. A sequence of single questions is exhausting to answer.
+- Order options with your recommendation first, labeled "(Recommended)".
+- Make option descriptions say what will *happen*, not what the option *is*.
+- The user can always answer something you did not list, so do not add an "other"
+  option.
+""",
+    }
+
+    async def run(self, args: AskArgs, ctx: ToolContext) -> ToolOutput:
+        if not args.questions:
+            return ToolOutput.error("no questions supplied")
+        if ctx.depth > 0:
+            return ToolOutput.error(
+                "Subagents cannot ask the user questions — nobody is watching your "
+                "output. Make a reasonable assumption, state it in your final "
+                "message, and continue."
+            )
+
+        answers: list[str] = []
+        for question in args.questions:
+            request = PermissionRequest(
+                tool_name=self.name,
+                target=question.header,
+                summary=question.question,
+                args_preview=_render(question),
+                is_read_only=True,
+                suggested_rule="",
+                reason="choice",
+            )
+            decision = await ctx.ask(request)
+            if not decision.approved and not decision.reason:
+                answers.append(f"{question.header}: (the user dismissed this question)")
+                continue
+            answers.append(f"{question.header}: {decision.reason or '(no answer)'}")
+
+        return ToolOutput(
+            content="The user answered:\n" + "\n".join(answers),
+            display="\n".join(answers),
+            metrics={"questions": len(args.questions)},
+        )
+
+    def summary(self, args: AskArgs) -> str:  # type: ignore[override]
+        first = args.questions[0].question if args.questions else ""
+        return f"Asking: {first[:60]}"
+
+
+def _render(question: Question) -> str:
+    lines = [question.question, ""]
+    for i, option in enumerate(question.options, start=1):
+        lines.append(f"{i}. {option.label}")
+        if option.description:
+            lines.append(f"   {option.description}")
+    return "\n".join(lines)