claude-code-tools 1.28.0__tar.gz → 1.29.0__tar.gz

{claude_code_tools-1.28.0 → claude_code_tools-1.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-tools
-Version: 1.28.0
+Version: 1.29.0
 Summary: Collection of tools for working with Claude Code
 License-File: LICENSE
 Requires-Python: >=3.11

{claude_code_tools-1.28.0 → claude_code_tools-1.29.0}/claude_code_tools/__init__.py

@@ -1,3 +1,3 @@
 """Claude Code Tools - Collection of utilities for Claude Code."""
 
-__version__ = "1.28.0"
+__version__ = "1.29.0"

{claude_code_tools-1.28.0 → claude_code_tools-1.29.0}/claude_code_tools/agent_tunnel/config.py

@@ -176,6 +176,10 @@ class HttpConfig:
     token_file: str = ""
     # Name used in the fork's persona for questions arriving this way.
     platform: str = "the web"
+    # Append-only JSON-lines log of answered turns, readable at GET /turns.
+    # Empty = off. Relative paths sit beside the state file. The sender is
+    # never written to it.
+    turn_log: str = ""
 
 
 @dataclass
@@ -423,6 +427,7 @@ unset_api_key = true
 # port = 8766
 # token_file = "~/.config/agent-tunnel/http-token"
 # platform = "the web"
+# turn_log = "http-turns.jsonl"   # answered turns, no sender; GET /turns reads it
 
 [limits]
 max_concurrent = 2

{claude_code_tools-1.28.0 → claude_code_tools-1.29.0}/claude_code_tools/agent_tunnel/http_frontend.py

@@ -9,7 +9,9 @@ refresh and logging are shared with Discord and Mattermost.
 Routes (``[http]`` in the config; off unless ``port`` is set):
 
     GET  /health
-    POST /ask   {"handle": ..., "question": ..., "thread": ..., "sender": ...}
+    POST /ask   {"handle": ..., "question": ..., "thread": ..., "sender": ...,
+                 "metadata": {...}}
+    GET  /turns ?handle=...&limit=...&meta.<key>=<value>
 
 Every route requires ``X-Ask-Token: <contents of http.token_file>``.
 ``thread`` is any caller-chosen id; questions with the same handle and
@@ -20,6 +22,11 @@ whatever access the handle was shared with, because the caller picks the
 handle. The response says whether a turn ran (``ran``) separately from what
 it produced, and a failed turn is an HTTP 502 carrying the relay's own
 error text, never an empty answer.
+
+With ``[http] turn_log`` set, each answered turn is appended to that file
+with the caller's flat ``metadata`` (a docs site sends page and heading) and
+without the sender, and ``GET /turns`` returns the matching turns newest
+first. See :mod:`.turn_log`.
 """
 
 from __future__ import annotations
@@ -37,6 +44,7 @@ from aiohttp import web
 from .readonly import HTTP_THREAD_PREFIX
 from .config import TunnelConfig
 from .relay import QUEUE_NOTICE, Relay
+from .turn_log import MAX_LIMIT, TurnLog, resolve_log_path, validate_metadata
 
 logger = logging.getLogger("agent_tunnel.http")
 
@@ -148,6 +156,8 @@ async def _turn(
     thread: str,
     question: str,
     sender: str,
+    metadata: dict[str, str],
+    turn_log: Optional[TurnLog],
 ) -> web.Response:
     """Bind if new, run one relay turn, and shape the JSON reply.
 
@@ -166,6 +176,16 @@ async def _turn(
         error = problem or "the turn produced no answer"
         return _json(502, {"ran": False, "error": error, "thread": thread})
     record = relay.store.get(thread_key)
+    logged = False
+    if turn_log is not None:
+        try:
+            await turn_log.append(handle, thread, question, dest.text, metadata)
+            logged = True
+        except (OSError, ValueError):
+            # The reader still gets the answer; the response says it was not
+            # logged, and the daemon log says why.
+            logger.exception("Could not append to turn log %s", turn_log.path)
+            dest.notices.append("this turn could not be written to the turn log")
     return _json(
         200,
         {
@@ -176,6 +196,7 @@ async def _turn(
             "fork_session_id": record.fork_session_id if record else "",
             "files": [p.name for p in dest.files],
             "notices": dest.notices,
+            "logged": logged,
         },
     )
 
@@ -183,6 +204,8 @@ async def _turn(
 def make_app(cfg: TunnelConfig, relay: Relay) -> web.Application:
     """The aiohttp application; separated from serving so tests can drive it."""
     token = resolve_http_token(cfg).encode("utf-8")
+    log_path = resolve_log_path(cfg.http.turn_log, cfg.state_path)
+    turn_log = TurnLog(log_path) if log_path else None
 
     @web.middleware
     async def require_token(request: web.Request, handler: Any) -> web.Response:
@@ -225,6 +248,10 @@ def make_app(cfg: TunnelConfig, relay: Relay) -> web.Application:
             return _json(
                 400, {"ran": False, "error": "thread must match [A-Za-z0-9_.:-]{1,80}"}
             )
+        metadata, err = validate_metadata(body.get("metadata"))
+        if err:
+            status = 413 if "longer" in err else 400
+            return _json(status, {"ran": False, "error": err})
         # The same per-user cooldown the chat front-ends apply, keyed by the
         # sender the caller vouches for, else by the caller's address.
         caller = sender or (request.remote or "unknown")
@@ -236,7 +263,17 @@ def make_app(cfg: TunnelConfig, relay: Relay) -> web.Application:
             )
         thread_key = f"{HTTP_THREAD_PREFIX}{handle}:{thread}"
         try:
-            return await _turn(cfg, relay, thread_key, handle, thread, question, sender)
+            return await _turn(
+                cfg,
+                relay,
+                thread_key,
+                handle,
+                thread,
+                question,
+                sender,
+                metadata,
+                turn_log,
+            )
         except Exception:  # noqa: BLE001 - keep the JSON contract on any failure
             logger.exception("HTTP turn failed [%s]", thread_key)
             return _json(
@@ -248,9 +285,39 @@ def make_app(cfg: TunnelConfig, relay: Relay) -> web.Application:
                 },
             )
 
+    async def turns(request: web.Request) -> web.Response:
+        if turn_log is None:
+            return _json(404, {"ran": False, "error": "no [http] turn_log configured"})
+        query = request.query
+        handle = query.get("handle", "").strip().lower()
+        if not handle:
+            return _json(400, {"ran": False, "error": "handle is required"})
+        try:
+            limit = int(query.get("limit", "50"))
+        except ValueError:
+            return _json(400, {"ran": False, "error": "limit must be an integer"})
+        if not 1 <= limit <= MAX_LIMIT:
+            return _json(
+                400, {"ran": False, "error": f"limit must be 1 to {MAX_LIMIT}"}
+            )
+        filters = {
+            key[len("meta.") :]: value
+            for key, value in query.items()
+            if key.startswith("meta.")
+        }
+        try:
+            found, skipped = await asyncio.to_thread(
+                turn_log.read, handle, filters, limit
+            )
+        except OSError:
+            logger.exception("Could not read turn log %s", turn_log.path)
+            return _json(502, {"ran": False, "error": "could not read the turn log"})
+        return _json(200, {"ran": True, "turns": found, "skipped": skipped})
+
     app = web.Application(client_max_size=256 * 1024, middlewares=[require_token])
     app.router.add_get("/health", health)
     app.router.add_post("/ask", ask)
+    app.router.add_get("/turns", turns)
     return app
 
 

claude_code_tools-1.29.0/claude_code_tools/agent_tunnel/turn_log.py

@@ -0,0 +1,164 @@
+"""An append-only log of HTTP turns, and the reader behind ``GET /turns``.
+
+The daemon's thread store keeps only a trimmed recap of each conversation,
+so it cannot answer "what was asked about this page last month". When
+``[http] turn_log`` names a file, every answered HTTP turn is appended to it
+as one JSON line: when, which handle and thread, the question, the answer,
+and whatever flat ``metadata`` the caller attached (a docs site sends the
+page and heading). The sender is never written. The fork is still told who
+is asking and may repeat it in its answer, so a caller that shows the log to
+other people sends a pseudonym as the sender rather than a name or email.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping, Optional
+
+logger = logging.getLogger("agent_tunnel.turn_log")
+
+META_KEY_RE = re.compile(r"^[A-Za-z0-9_.-]{1,40}$")
+MAX_META_KEYS = 20
+MAX_META_VALUE = 4000
+MAX_LIMIT = 500
+
+
+def validate_metadata(value: Any) -> tuple[dict[str, str], str]:
+    """A caller's ``metadata`` as a flat string map, or why it is not one.
+
+    Args:
+        value: The request's ``metadata`` field; absent or null is empty.
+
+    Returns:
+        ``(metadata, "")`` on success, else ``({}, error)``. An error that
+        mentions "longer" is an over-limit value (the caller answers 413).
+    """
+    if value is None:
+        return {}, ""
+    if not isinstance(value, dict):
+        return {}, "metadata must be a JSON object"
+    if len(value) > MAX_META_KEYS:
+        return {}, f"metadata has more than {MAX_META_KEYS} keys"
+    meta: dict[str, str] = {}
+    for key, item in value.items():
+        if not META_KEY_RE.match(key):
+            return {}, "metadata keys must match [A-Za-z0-9_.-]{1,40}"
+        if not isinstance(item, str):
+            return {}, f"metadata.{key} must be a string"
+        if len(item) > MAX_META_VALUE:
+            return {}, f"metadata.{key} is longer than {MAX_META_VALUE} characters"
+        meta[key] = item
+    return meta, ""
+
+
+def resolve_log_path(configured: str, state_path: Path) -> Optional[Path]:
+    """The turn log's path, or None when logging is off.
+
+    A relative path sits beside the daemon's state file, like its other
+    runtime files.
+    """
+    if not configured:
+        return None
+    path = Path(configured).expanduser()
+    return path if path.is_absolute() else state_path.parent / path
+
+
+@dataclass
+class TurnLog:
+    """Append answered turns to a JSON-lines file and read them back."""
+
+    path: Path
+    _lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+
+    async def append(
+        self,
+        handle: str,
+        thread: str,
+        question: str,
+        answer: str,
+        metadata: Mapping[str, str],
+    ) -> None:
+        """Write one turn durably; raises OSError if it could not be written."""
+        record = {
+            "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "handle": handle,
+            "thread": thread,
+            "question": question,
+            "answer": answer,
+            "metadata": dict(metadata),
+        }
+        # ASCII escapes: a lone surrogate from JSON input is a valid str but
+        # cannot be encoded as UTF-8, and must not cost the reader an answer.
+        line = json.dumps(record) + "\n"
+        async with self._lock:
+            await asyncio.to_thread(self._write, line)
+
+    def _write(self, line: str) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        # Owner-only, like the thread store: the log holds every question
+        # and answer.
+        fd = os.open(self.path, os.O_RDWR | os.O_CREAT | os.O_APPEND, 0o600)
+        with os.fdopen(fd, "a+b") as fh:
+            if hasattr(os, "fchmod"):  # POSIX only; also narrows an older file
+                os.fchmod(fh.fileno(), 0o600)
+            # A failed earlier write can leave a record without its newline;
+            # end it first so this record stays on a line of its own.
+            end = fh.seek(0, os.SEEK_END)
+            if end:
+                fh.seek(end - 1)
+                if fh.read(1) != b"\n":
+                    fh.write(b"\n")
+            fh.write(line.encode("utf-8"))
+            fh.flush()
+            os.fsync(fh.fileno())
+
+    def read(
+        self, handle: str, meta_filters: Mapping[str, str], limit: int
+    ) -> tuple[list[dict[str, Any]], int]:
+        """Matching turns, newest first, and how many lines were unreadable.
+
+        Args:
+            handle: Only turns of this handle.
+            meta_filters: Each key must be present in a turn's metadata with
+                exactly this value.
+            limit: At most this many turns, the most recent ones.
+
+        Returns:
+            ``(turns, skipped)``; a missing file is no turns, not an error.
+        """
+        if not self.path.exists():
+            return [], 0
+        # Only the latest `limit` matches are kept while scanning, so memory
+        # stays bounded however long the log grows.
+        matches: deque[dict[str, Any]] = deque(maxlen=limit)
+        skipped = 0
+        # Bytes, decoded line by line, so one damaged line is skipped and
+        # counted rather than hiding every record after it.
+        with self.path.open("rb") as fh:
+            for raw in fh:
+                if not raw.strip():
+                    continue
+                try:
+                    turn = json.loads(raw.decode("utf-8"))
+                except (UnicodeDecodeError, json.JSONDecodeError):
+                    skipped += 1
+                    continue
+                meta = turn.get("metadata", {}) if isinstance(turn, dict) else None
+                if not isinstance(meta, dict):
+                    skipped += 1  # valid JSON, but not a turn record
+                    continue
+                if turn.get("handle") != handle:
+                    continue
+                if all(meta.get(k) == v for k, v in meta_filters.items()):
+                    matches.append(turn)
+        if skipped:
+            logger.warning("Turn log %s: %d unreadable line(s)", self.path, skipped)
+        return list(reversed(matches)), skipped

{claude_code_tools-1.28.0 → claude_code_tools-1.29.0}/docs/agent-tunnel-spec.md

@@ -58,7 +58,9 @@ safe.
   forks are read-only whatever the handle's access, the configured tool
   lists, the backends' extra args, the configured permission mode, the
   settings' MCP servers, or `allow_skip_permissions`, since the caller picks
-  the handle.
+  the handle. With `[http] turn_log` set, each answered turn is appended to
+  a JSON-lines log with the caller's flat `metadata` and never the sender;
+  `GET /turns` reads it back newest first, filtered by `meta.<key>=<value>`.
   Fields must be strings within their limits (over-limit is a 413); the
   per-user cooldown applies per `sender` (a 429 inside it). The
   response separates whether a turn ran from what it produced: a failed

{claude_code_tools-1.28.0 → claude_code_tools-1.29.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-code-tools"
-version = "1.28.0"
+version = "1.29.0"
 description = "Collection of tools for working with Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -113,7 +113,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "1.28.0"
+version = "1.29.0"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:version",