prompture 1.13.2.dev1__tar.gz → 1.13.3.dev1__tar.gz

{prompture-1.13.2.dev1 → prompture-1.13.3.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.13.2.dev1
+Version: 1.13.3.dev1
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT

{prompture-1.13.2.dev1 → prompture-1.13.3.dev1}/prompture/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.13.2.dev1'
-__version_tuple__ = version_tuple = (1, 13, 2, 'dev1')
+__version__ = version = '1.13.3.dev1'
+__version_tuple__ = version_tuple = (1, 13, 3, 'dev1')
 
 __commit_id__ = commit_id = None

{prompture-1.13.2.dev1 → prompture-1.13.3.dev1}/prompture/cli/cli.py

@@ -202,7 +202,12 @@ def test_suite(specfile: str, providers: str | None, models: str | None, fmt: st
 
 
 @cli.command()
-@click.option("--port", default=0, type=int, help="Port on 127.0.0.1 (default: a free one the OS picks).")
+@click.option(
+    "--port",
+    default=None,
+    type=int,
+    help="Port on 127.0.0.1 (default: 47811 when free, else one the OS picks). 0 = always let the OS pick.",
+)
 @click.option(
     "--db", "db_path", default=None, type=click.Path(), help="Usage ledger (default ~/.prompture/usage/usage.db)."
 )
@@ -222,7 +227,19 @@ def test_suite(specfile: str, providers: str | None, models: str | None, fmt: st
     default=True,
     help="Run queued coding-agent steps one after another for companion apps (default: on).",
 )
-def companion(port: int, db_path: str | None, exit_with_pid: int | None, coding_tools: bool, automations: bool) -> None:
+@click.option(
+    "--router/--no-router",
+    default=True,
+    help="Let companion apps route Claude Code and Codex through this companion (default: on).",
+)
+def companion(
+    port: int | None,
+    db_path: str | None,
+    exit_with_pid: int | None,
+    coding_tools: bool,
+    automations: bool,
+    router: bool,
+) -> None:
     """Serve this machine's Prompture usage to desktop companions (no hub needed).
 
     Reads the usage ledger every Prompture call writes to, plus rate-limit
@@ -230,16 +247,35 @@ def companion(port: int, db_path: str | None, exit_with_pid: int | None, coding_
     the same companion API as prompture-hub. The address and a bearer token are
     written to ~/.prompture/companion.json. If a companion is already running,
     this prints its address and exits.
+
+    With the router on, a companion app can point Claude Code and Codex at it
+    (their model traffic then passes through, or goes to any Prompture model),
+    so the companion prefers the same port each time: 47811.
     """
     from ..companion import Automations, CodingToolSource, CompanionServer, LedgerSource, running_instance
+    from ..companion.server import DEFAULT_PORT
+    from ..companion.tool_routing import ToolRouting
 
     existing = running_instance()
     if existing:
         click.echo(f"Prompture companion already running at {existing['url']} (pid {existing.get('pid')}).")
         return
-    server = CompanionServer(
-        LedgerSource(db_path), port=port, coding_tools=CodingToolSource() if coding_tools else None
-    )
+
+    def make(on_port: int) -> CompanionServer:
+        return CompanionServer(
+            LedgerSource(db_path),
+            port=on_port,
+            coding_tools=CodingToolSource() if coding_tools else None,
+            tool_routing=ToolRouting() if router else None,
+        )
+
+    if port is None:
+        try:
+            server = make(DEFAULT_PORT)
+        except OSError:  # taken: any free port works, routing follows it
+            server = make(0)
+    else:
+        server = make(port)
     if automations:
         server.automations = Automations(bus=server.bus, limits=server.rate_limits)
     click.echo(f"Prompture companion on {server.url} - ledger {server.ledger.db_path}")

{prompture-1.13.2.dev1 → prompture-1.13.3.dev1}/prompture/companion/coding_tools.py

@@ -11,7 +11,14 @@ adapts it to the companion API:
 - plan windows (Codex from its logs; Claude Code only when opted in) join
   ``/v1/limits`` as ``source: "plan"`` targets;
 - ``/v1/tools`` lists every agent: installed, runnable by Prompture, and its
-  usage for the period.
+  usage for the period;
+- a Claude Code or Codex turn in progress shows as a running call: a
+  ``request.started`` event when it starts (id ``agent:<agent>:<session>``),
+  ``request.activity`` when its model or state changes, and ``request.ended``
+  when it's over (see :mod:`prompture.infra.coding_agent_activity`). Its usage
+  still arrives as ``request.finished`` events for the calls it made. With
+  Claude Code's hooks installed (:mod:`.hook`), a turn stuck on a permission
+  prompt shows ``state: "waiting"``.
 
 Costs are what the same tokens would cost on the API; subscriptions don't
 bill per token. Only token counts, model names, times and folder names are
@@ -29,6 +36,7 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any
 
+from ..infra.coding_agent_activity import ActiveTurn, AgentActivity
 from ..infra.coding_agent_usage import AgentCall, CodingAgentUsage, UsageReader, coding_agents_overview
 from .live import LiveBus
 from .summary import UsageRow, window_start
@@ -39,6 +47,10 @@ logger = logging.getLogger("prompture.companion")
 OVERVIEW_TTL = 60.0
 #: How far back calls are kept: a year of activity, plus a week of slack.
 RETENTION = timedelta(days=372)
+#: How long a turn waiting on the user stays listed after its log went quiet.
+WAITING_TTL = 6 * 3600.0
+#: Hook events that mean the agent is working again (a prompt, a tool starting or done).
+WORKING_HOOKS = {"UserPromptSubmit", "PreToolUse", "PostToolUse", "SubagentStop"}
 #: Companion choices that outlive a restart (today: whether Claude plan windows are fetched).
 PREFS_FILE = Path.home() / ".prompture" / "companion-prefs.json"
 
@@ -51,6 +63,22 @@ def _load_prefs(path: Path) -> dict[str, Any]:
     return data if isinstance(data, dict) else {}
 
 
+def turn_event(turn: ActiveTurn, name: str, state: str = "working") -> dict[str, Any]:
+    """A ``request.started`` payload for an agent turn in progress."""
+    return {
+        "request_id": turn.request_id,
+        "ts": turn.since.isoformat(),
+        "key_id": None,
+        "key_name": name,
+        "model": turn.model or turn.agent,
+        "project": turn.project,
+        "endpoint": "coding-agent",
+        "stream": True,
+        "state": state,
+        "tool": turn.agent,
+    }
+
+
 def call_event(call: AgentCall, name: str) -> dict[str, Any]:
     """A ``request.finished`` payload for an agent call, shaped like the ledger's."""
     return {
@@ -91,6 +119,7 @@ class CodingToolSource:
         cache_dir: str | Path | None = None,
         readers: list[UsageReader] | None = None,
         prefs_file: str | Path | None = PREFS_FILE,
+        activity: AgentActivity | None = None,
     ) -> None:
         from ..infra.coding_agent_readers import ClaudeCodeReader, CodexReader
         from ..infra.coding_agent_usage import USAGE_READERS
@@ -110,6 +139,16 @@ class CodingToolSource:
                 readers = [claude, codex, *others]
         self.usage = CodingAgentUsage(readers, retention=RETENTION)
         self.names = {r.agent: r.display_name for r in readers}
+        if activity is None:
+            roots = {r.agent: getattr(r, "root", None) for r in readers}
+            if "claude" in roots or "codex" in roots:
+                activity = AgentActivity(roots.get("claude"), roots.get("codex"))
+        self.activity = activity
+        self._turns: dict[str, ActiveTurn] = {}
+        self._states: dict[str, str] = {}
+        #: State reported by an agent's hooks, per turn: ``(state, monotonic time)``.
+        self._hooked: dict[str, tuple[str, float]] = {}
+        self._turn_lock = threading.Lock()
         self._overview: tuple[float, list[dict[str, Any]]] | None = None
 
     @property
@@ -176,10 +215,71 @@ class CodingToolSource:
         """``request.finished`` payloads for calls at or after ``since``, newest last."""
         return [self.event(c) for c in self.usage.calls(since)[-limit:]]
 
-    def tail(self, bus: LiveBus, stop: threading.Event, interval: float = 3.0) -> None:
-        """Publish a ``request.finished`` event for every call logged from now on."""
-        self.refresh(force=True)
-        while not stop.wait(interval):
+    def publish_turns(self, bus: LiveBus) -> None:
+        """Publish how the agents' running turns changed since the last call."""
+        if self.activity is None:
+            return
+        with self._turn_lock:
+            turns = {t.request_id: t for t in self.activity.scan()}
+            now = time.monotonic()
+            for rid, (state, at) in self._hooked.items():
+                # A permission prompt writes nothing to the log; the turn is still on.
+                if state == "waiting" and rid not in turns and rid in self._turns and now - at < WAITING_TTL:
+                    turns[rid] = self._turns[rid]
+            for rid, turn in turns.items():
+                before = self._turns.get(rid)
+                state = self._hooked.get(rid, ("working", 0.0))[0]
+                if before is None:
+                    bus.publish("request.started", turn_event(turn, self.names.get(turn.agent, turn.agent), state))
+                elif (before.model != turn.model and turn.model) or self._states.get(rid) != state:
+                    bus.publish(
+                        "request.activity", {"request_id": rid, "model": turn.model or turn.agent, "state": state}
+                    )
+                self._states[rid] = state
+            for rid in self._turns.keys() - turns.keys():
+                gone = self._turns[rid]
+                self._states.pop(rid, None)
+                self._hooked.pop(rid, None)
+                bus.publish(
+                    "request.ended", {"request_id": rid, "tool": gone.agent, "key_name": self.names.get(gone.agent)}
+                )
+            self._turns = turns
+
+    def hook_event(self, bus: LiveBus, agent: str, event: str, session: str) -> None:
+        """Apply one event an agent's hooks reported (see :mod:`.hook`), then publish what changed.
+
+        ``Notification`` during a turn means it waits on the user (a permission
+        prompt); a prompt or a tool starting or finishing means it works again;
+        ``Stop`` / ``SessionEnd`` end it.
+        """
+        rid = f"agent:{agent}:{session}"
+        with self._turn_lock:
+            if event in ("Stop", "SessionEnd"):
+                self._hooked.pop(rid, None)
+            elif event == "Notification":
+                if rid in self._turns:
+                    self._hooked[rid] = ("waiting", time.monotonic())
+            elif event in WORKING_HOOKS:
+                self._hooked[rid] = ("working", time.monotonic())
+        self.publish_turns(bus)
+
+    def tail(self, bus: LiveBus, stop: threading.Event, interval: float = 2.0) -> None:
+        """Publish agent calls as they're logged, and agent turns as they start and end."""
+        first = True
+        while True:
+            try:
+                self.publish_turns(bus)
+            except Exception:
+                logger.debug("coding agent activity scan failed", exc_info=True)
+            if first:
+                # The first read takes in the whole history (seconds); turns in progress show before it.
+                first = False
+                try:
+                    self.refresh(force=True)
+                except Exception:
+                    logger.debug("coding tool scan failed", exc_info=True)
+            if stop.wait(interval):
+                break
             try:
                 for call in sorted(self.refresh(force=True), key=lambda c: c.ts):
                     if datetime.now(timezone.utc) - call.ts < timedelta(minutes=30):

prompture-1.13.3.dev1/prompture/companion/hook.py

@@ -0,0 +1,75 @@
+"""Coding-agent hook: tells the local companion what an agent is doing, the moment it happens.
+
+Claude Code runs ``python -m prompture.companion.hook claude`` on the events
+:mod:`.tool_routing` installs (a prompt, tools starting and finishing,
+notifications, the end of a turn) and passes the event as JSON on stdin. This
+forwards the event's name and session id — nothing else — to the companion
+named in ``~/.prompture/companion.json``, which turns them into live state:
+``Notification`` mid-turn is a permission prompt waiting on the user.
+
+It always exits 0 without output, quickly, whether or not a companion runs, so
+it never gets in the agent's way.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+STATE_FILE = Path.home() / ".prompture" / "companion.json"
+TIMEOUT = 1.5
+
+
+def payload(agent: str, raw: str) -> dict[str, Any] | None:
+    """What is sent for one hook event: the agent, the event name and the session id."""
+    try:
+        data = json.loads(raw or "{}")
+    except ValueError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    event, session = data.get("hook_event_name"), data.get("session_id")
+    if not isinstance(event, str) or not isinstance(session, str) or not session:
+        return None
+    return {"agent": agent, "event": event, "session": session}
+
+
+def send(body: dict[str, Any], state_file: Path = STATE_FILE) -> bool:
+    """Post *body* to the running companion; ``False`` when there is none."""
+    try:
+        state = json.loads(state_file.read_text(encoding="utf-8"))
+        url, token = str(state["url"]), str(state["token"])
+    except (OSError, ValueError, KeyError, TypeError):
+        return False
+    if not url.startswith(("http://127.0.0.1:", "http://localhost:")):
+        return False  # only ever talk to this machine
+    request = urllib.request.Request(
+        f"{url}/v1/hooks",
+        data=json.dumps(body).encode(),
+        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=TIMEOUT):  # nosec B310 - loopback http only, checked above
+            return True
+    except OSError:
+        return False
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    agent = args[0] if args else "claude"
+    try:
+        body = payload(agent, sys.stdin.read())
+        if body:
+            send(body)
+    except Exception:  # a hook must never fail the agent
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{prompture-1.13.2.dev1 → prompture-1.13.3.dev1}/prompture/companion/live.py

@@ -1,7 +1,9 @@
 """In-process live event bus behind a companion's ``GET /v1/live``.
 
 Producers publish an event when a call starts, produces its first token,
-changes activity and finishes. Events carry metadata only: ids, model,
+changes activity and finishes. ``request.ended`` closes a running entry that
+has no ``request.finished`` of its own (a coding agent's turn, whose calls are
+reported separately). Events carry metadata only: ids, model,
 project, status, tokens, cost, timings — never prompt or completion text.
 
 The bus keeps the last :data:`RING_SIZE` events, so a client that reconnects
@@ -59,7 +61,7 @@ class LiveBus:
                 self.in_flight[request_id] = {**event, "_mono": time.monotonic()}
             elif request_id in self.in_flight and type_ in ("request.first_token", "request.activity"):
                 self.in_flight[request_id].update({k: v for k, v in data.items() if k != "request_id"})
-            elif type_ == "request.finished" and request_id:
+            elif type_ in ("request.finished", "request.ended") and request_id:
                 self.in_flight.pop(request_id, None)
             subscribers = list(self._subscribers)
         for sub in subscribers: