@agxnte/reidx 2.0.2

package/src/reidx/runtime/subagent.py

@@ -0,0 +1,174 @@
+"""Subagent runtime: lifecycle tracking + event bus for spawned child agents.
+
+The `spawn_agent` tool constructs child `Agent`s (each with its own scoped
+`PolicyEngine` and tool allowlist) and reports their lifecycle here. The TUI
+subscribes to the manager so the "active agents" panel below the status line
+knows what to render — one row per live subagent, auto-hidden when none.
+
+Threading: tool calls run in an executor thread (see ui/app.py) so
+SubagentManager mutates from worker threads. Every mutation grabs a lock and
+listeners are called with a snapshot copy so the UI can iterate without
+holding it.
+"""
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, field, replace
+from typing import Literal
+
+SubagentStatus = Literal["running", "done", "error"]
+
+
+@dataclass(frozen=True)
+class SubagentSnapshot:
+    id: str
+    name: str
+    status: SubagentStatus
+    started_at: float
+    last_action: str = ""
+    finished_at: float | None = None
+    error: str = ""
+
+    @property
+    def elapsed_seconds(self) -> float:
+        end = self.finished_at if self.finished_at is not None else time.monotonic()
+        return end - self.started_at
+
+
+@dataclass
+class _Row:
+    id: str
+    name: str
+    status: SubagentStatus
+    started_at: float
+    last_action: str = ""
+    finished_at: float | None = None
+    error: str = ""
+    # Small display grace period after finish so completed agents flash
+    # briefly before disappearing (see prune_finished).
+    linger_until: float = field(default=0.0)
+
+
+Listener = Callable[[list[SubagentSnapshot]], None]
+
+LINGER_SECONDS = 2.0
+
+
+class SubagentManager:
+    def __init__(self) -> None:
+        self._rows: dict[str, _Row] = {}
+        self._lock = threading.Lock()
+        self._listeners: list[Listener] = []
+
+    # --- subscribe --------------------------------------------------------
+
+    def subscribe(self, listener: Listener) -> Callable[[], None]:
+        with self._lock:
+            self._listeners.append(listener)
+
+        def _unsub() -> None:
+            with self._lock:
+                if listener in self._listeners:
+                    self._listeners.remove(listener)
+        return _unsub
+
+    def _notify(self) -> None:
+        # Snapshot outside the lock so listener callbacks don't reenter it.
+        snap = self.snapshot()
+        for listener in list(self._listeners):
+            try:
+                listener(snap)
+            except Exception:  # noqa: BLE001 - a broken listener must not kill agents
+                pass
+
+    # --- lifecycle --------------------------------------------------------
+
+    def start(self, name: str) -> str:
+        agent_id = uuid.uuid4().hex[:8]
+        with self._lock:
+            self._rows[agent_id] = _Row(
+                id=agent_id, name=name, status="running", started_at=time.monotonic()
+            )
+        self._notify()
+        return agent_id
+
+    def update(self, agent_id: str, *, last_action: str) -> None:
+        with self._lock:
+            row = self._rows.get(agent_id)
+            if row is None or row.status != "running":
+                return
+            row.last_action = last_action
+        self._notify()
+
+    def finish(self, agent_id: str, *, status: SubagentStatus = "done", error: str = "") -> None:
+        with self._lock:
+            row = self._rows.get(agent_id)
+            if row is None:
+                return
+            row.status = status
+            row.finished_at = time.monotonic()
+            row.error = error
+            row.linger_until = row.finished_at + LINGER_SECONDS
+        self._notify()
+
+    # --- read -------------------------------------------------------------
+
+    def snapshot(self) -> list[SubagentSnapshot]:
+        with self._lock:
+            return [
+                SubagentSnapshot(
+                    id=r.id, name=r.name, status=r.status, started_at=r.started_at,
+                    last_action=r.last_action, finished_at=r.finished_at, error=r.error,
+                )
+                for r in self._rows.values()
+            ]
+
+    def visible_rows(self) -> list[SubagentSnapshot]:
+        """Rows to actually render — running + recently-finished (linger)."""
+        now = time.monotonic()
+        with self._lock:
+            keep: list[_Row] = []
+            for row in self._rows.values():
+                if row.status == "running" or row.linger_until > now:
+                    keep.append(row)
+        return [
+            SubagentSnapshot(
+                id=r.id, name=r.name, status=r.status, started_at=r.started_at,
+                last_action=r.last_action, finished_at=r.finished_at, error=r.error,
+            )
+            for r in keep
+        ]
+
+    def prune_finished(self) -> bool:
+        """Drop finished rows past their linger window. Returns True if any
+        row was removed (so the TUI knows to invalidate and re-render). Called
+        from the spinner tick."""
+        now = time.monotonic()
+        removed = False
+        with self._lock:
+            for aid, row in list(self._rows.items()):
+                if row.status != "running" and row.linger_until <= now:
+                    del self._rows[aid]
+                    removed = True
+        if removed:
+            self._notify()
+        return removed
+
+    def any_active(self) -> bool:
+        with self._lock:
+            return any(r.status == "running" for r in self._rows.values())
+
+    # Kept for tests / debugging.
+    def _clear(self) -> None:
+        with self._lock:
+            self._rows.clear()
+
+
+# For type hints elsewhere without a heavy import.
+__all__ = ["SubagentManager", "SubagentSnapshot", "LINGER_SECONDS"]
+
+# Discourage silent replace() calls on the frozen dataclass elsewhere.
+_ = replace  # noqa: F841

package/src/reidx/session/__init__.py

@@ -0,0 +1,4 @@
+from reidx.session.models import Session, SessionStatus
+from reidx.session.store import SessionStore
+
+__all__ = ["Session", "SessionStatus", "SessionStore"]

package/src/reidx/session/models.py

@@ -0,0 +1,43 @@
+"""Session model.
+
+A Session is a first-class runtime object: identity, workspace, provider/model state,
+permission mode, status, and timestamps. Transcript and task state live alongside
+under the session storage directory (see session.store).
+"""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from reidx.policy.models import PermissionMode
+
+
+def _new_id() -> str:
+    import uuid
+
+    return uuid.uuid4().hex[:12]
+
+
+class SessionStatus(StrEnum):
+    ACTIVE = "active"
+    PAUSED = "paused"
+    ARCHIVED = "archived"
+
+
+class Session(BaseModel):
+    id: str = Field(default_factory=_new_id)
+    title: str = ""
+    workspace: Path
+    provider: str = "stub"
+    model: str = "stub-v0"
+    reasoning_effort: str = "medium"
+    permission_mode: PermissionMode = PermissionMode.BALANCED
+    status: SessionStatus = SessionStatus.ACTIVE
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    def touch(self) -> None:
+        self.updated_at = datetime.now(UTC)

package/src/reidx/session/store.py

@@ -0,0 +1,101 @@
+"""Session store: structured per-session persistence.
+
+Layout under storage_root:
+    sessions/
+      <session-id>/
+        meta.json        # Session record
+        transcript.jsonl # one Message per line (restorable into state.messages)
+        tasks.json       # task state for the session
+        events.jsonl     # runtime action log (turn summaries, lifecycle events)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from reidx.diagnostics.logger import EventLog, get_logger
+from reidx.provider.base import Message
+from reidx.session.models import Session, SessionStatus
+
+log = get_logger("reidx.session")
+
+_MAX_RESUME_MESSAGES = 100
+
+
+class SessionStore:
+    def __init__(self, storage_root: Path) -> None:
+        self.root = storage_root / "sessions"
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def _dir(self, session_id: str) -> Path:
+        return self.root / session_id
+
+    def create(self, session: Session) -> Session:
+        d = self._dir(session.id)
+        d.mkdir(parents=True, exist_ok=True)
+        self._write_meta(session)
+        log.debug("created session %s in %s", session.id, session.workspace)
+        return session
+
+    def _write_meta(self, session: Session) -> None:
+        session.touch()
+        (self._dir(session.id) / "meta.json").write_text(
+            session.model_dump_json(indent=2), encoding="utf-8"
+        )
+
+    def get(self, session_id: str) -> Session | None:
+        path = self._dir(session_id) / "meta.json"
+        if not path.exists():
+            return None
+        return Session.model_validate_json(path.read_text(encoding="utf-8"))
+
+    def update(self, session: Session) -> None:
+        if not self._dir(session.id).exists():
+            raise FileNotFoundError(f"session {session.id} not found")
+        self._write_meta(session)
+
+    def list(self) -> list[Session]:
+        sessions: list[Session] = []
+        for child in sorted(self.root.iterdir()):
+            meta = child / "meta.json"
+            if meta.exists():
+                sessions.append(Session.model_validate_json(meta.read_text(encoding="utf-8")))
+        return sessions
+
+    def set_status(self, session_id: str, status: SessionStatus) -> Session | None:
+        s = self.get(session_id)
+        if s is None:
+            return None
+        s.status = status
+        self.update(s)
+        return s
+
+    def session_dir(self, session_id: str) -> Path:
+        return self._dir(session_id)
+
+    def event_log(self, session_id: str) -> EventLog:
+        return EventLog(self._dir(session_id) / "events.jsonl")
+
+    def transcript_log(self, session_id: str) -> EventLog:
+        return EventLog(self._dir(session_id) / "transcript.jsonl")
+
+    def append_message(self, session_id: str, message: Message) -> None:
+        """Append one Message to transcript.jsonl for restorable resume."""
+        path = self._dir(session_id) / "transcript.jsonl"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        line = message.model_dump_json()
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(line + "\n")
+
+    def read_messages(self, session_id: str, limit: int = _MAX_RESUME_MESSAGES) -> list[Message]:
+        """Read transcript.jsonl back into Message objects (most recent `limit`)."""
+        path = self._dir(session_id) / "transcript.jsonl"
+        if not path.exists():
+            return []
+        lines = path.read_text(encoding="utf-8").splitlines()
+        messages: list[Message] = []
+        for line in lines[-limit:]:
+            try:
+                messages.append(Message.model_validate_json(line))
+            except Exception:  # noqa: BLE001 - skip corrupt lines
+                continue
+        return messages

package/src/reidx/tasks/__init__.py

@@ -0,0 +1,4 @@
+from reidx.tasks.models import Task, TaskStatus
+from reidx.tasks.store import TaskStore
+
+__all__ = ["Task", "TaskStatus", "TaskStore"]

package/src/reidx/tasks/models.py

@@ -0,0 +1,44 @@
+"""Task model.
+
+Structured task state — not prose steps. Tasks belong to a session, track status
+through a real state machine, and support dependencies.
+"""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+def _new_id() -> str:
+    import uuid
+
+    return uuid.uuid4().hex[:10]
+
+
+class TaskStatus(StrEnum):
+    PENDING = "pending"
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    BLOCKED = "blocked"
+    SKIPPED = "skipped"
+
+
+class Task(BaseModel):
+    id: str = Field(default_factory=_new_id)
+    session_id: str
+    title: str
+    status: TaskStatus = TaskStatus.PENDING
+    summary: str = ""
+    error: str = ""
+    depends_on: list[str] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+    meta: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    def touch(self) -> None:
+        self.updated_at = datetime.now(UTC)

package/src/reidx/tasks/store.py

@@ -0,0 +1,86 @@
+"""Task store: per-session task state persisted to tasks.json."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from reidx.diagnostics.logger import get_logger
+from reidx.tasks.models import Task, TaskStatus
+
+log = get_logger("reidx.tasks")
+
+
+class TaskStore:
+    def __init__(self, storage_root: Path, session_id: str) -> None:
+        self.path = storage_root / "sessions" / session_id / "tasks.json"
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.session_id = session_id
+
+    def _read(self) -> dict[str, Task]:
+        if not self.path.exists():
+            return {}
+        import json
+
+        text = self.path.read_text(encoding="utf-8").strip()
+        if not text:
+            return {}
+
+        data: dict[str, Task] = {}
+        for raw in json.loads(text).get("tasks", []):
+            t = Task.model_validate(raw)
+            data[t.id] = t
+        return data
+
+    def _write(self, tasks: dict[str, Task]) -> None:
+        import json
+
+        payload = {"tasks": [t.model_dump(mode="json") for t in tasks.values()]}
+        self.path.write_text(json.dumps(payload, indent=2, default=str), encoding="utf-8")
+
+    def create(
+        self,
+        title: str,
+        depends_on: list[str] | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> Task:
+        tasks = self._read()
+        t = Task(
+            session_id=self.session_id,
+            title=title,
+            depends_on=depends_on or [],
+            meta=meta or {},
+        )
+        tasks[t.id] = t
+        self._write(tasks)
+        log.debug("created task %s: %s", t.id, title)
+        return t
+
+    def get(self, task_id: str) -> Task | None:
+        return self._read().get(task_id)
+
+    def list(self) -> list[Task]:
+        return list(self._read().values())
+
+    def update_status(self, task_id: str, status: TaskStatus, summary: str = "", error: str = "") -> Task | None:
+        tasks = self._read()
+        t = tasks.get(task_id)
+        if t is None:
+            return None
+        t.status = status
+        if summary:
+            t.summary = summary
+        if error:
+            t.error = error
+        t.touch()
+        self._write(tasks)
+        return t
+
+    def add_note(self, task_id: str, note: str) -> Task | None:
+        tasks = self._read()
+        t = tasks.get(task_id)
+        if t is None:
+            return None
+        t.notes.append(note)
+        t.touch()
+        self._write(tasks)
+        return t

package/src/reidx/tools/__init__.py

@@ -0,0 +1,44 @@
+from reidx.tools.base import BaseTool, ToolContext, ToolDefinition, ToolResult
+from reidx.tools.file_tools import (
+    FindFilesTool,
+    GrepFilesTool,
+    ListDirTool,
+    PatchFileTool,
+    ReadFileTool,
+    WriteFileTool,
+    register_file_tools,
+)
+from reidx.tools.registry import ToolRegistry
+from reidx.tools.shell_tool import RunCommandTool, register_shell_tool
+from reidx.tools.spawn_agent import SpawnAgentTool, register_spawn_agent
+from reidx.tools.web_tools import WebSearchTool, register_web_tools
+
+__all__ = [
+    "BaseTool",
+    "FindFilesTool",
+    "GrepFilesTool",
+    "ListDirTool",
+    "PatchFileTool",
+    "ReadFileTool",
+    "RunCommandTool",
+    "SpawnAgentTool",
+    "ToolContext",
+    "ToolDefinition",
+    "ToolRegistry",
+    "ToolResult",
+    "WebSearchTool",
+    "WriteFileTool",
+    "register_file_tools",
+    "register_shell_tool",
+    "register_spawn_agent",
+    "register_web_tools",
+]
+
+
+def default_registry() -> ToolRegistry:
+    reg = ToolRegistry()
+    register_file_tools(reg)
+    register_shell_tool(reg)
+    register_web_tools(reg)
+    register_spawn_agent(reg)
+    return reg

package/src/reidx/tools/base.py

@@ -0,0 +1,84 @@
+"""Tool system contracts.
+
+A tool has a definition (name + description + JSON-schema parameters + risk level)
+and an execute() entry point. Tools receive a ToolContext carrying the workspace,
+writable roots, the policy engine, and an approver callable used to resolve PROMPT
+decisions into ALLOW/DENY. Tool results are structured, never raised as exceptions
+when avoidable — failures become ToolResult(ok=False, error=...).
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from reidx.policy.engine import PolicyEngine
+from reidx.policy.models import PermissionDecision, RiskLevel
+
+
+class ToolDefinition(BaseModel):
+    name: str
+    description: str
+    parameters: dict[str, Any] = Field(default_factory=dict)
+    risk: RiskLevel = RiskLevel.MEDIUM
+
+
+class ToolResult(BaseModel):
+    ok: bool = True
+    output: str = ""
+    error: str = ""
+    data: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def fail(cls, error: str) -> ToolResult:
+        return cls(ok=False, error=error)
+
+    @classmethod
+    def ok_(cls, output: str = "", **data: Any) -> ToolResult:
+        return cls(ok=True, output=output, data=data)
+
+
+# Approver signature: (prompt_text) -> bool. Supplied by the UI layer.
+Approver = Callable[[str], bool]
+
+
+@dataclass
+class ToolContext:
+    workspace_root: Path
+    policy: PolicyEngine
+    writable_roots: list[Path] = field(default_factory=list)
+    approver: Approver | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def resolve_decision(self, prompt_text: str) -> PermissionDecision:
+        """Resolve a PROMPT decision via the approver; defaults to DENY if none set."""
+        if self.approver is None:
+            return PermissionDecision.DENY
+        return PermissionDecision.ALLOW if self.approver(prompt_text) else PermissionDecision.DENY
+
+
+class BaseTool(ABC):
+    @property
+    @abstractmethod
+    def definition(self) -> ToolDefinition:
+        ...
+
+    @abstractmethod
+    def execute(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        ...
+
+    def schema(self) -> dict[str, Any]:
+        """OpenAI-style function schema for provider tool passing."""
+        d = self.definition
+        return {
+            "type": "function",
+            "function": {
+                "name": d.name,
+                "description": d.description,
+                "parameters": d.parameters or {"type": "object", "properties": {}},
+            },
+        }