cctally 1.38.1 → 1.40.0

package/bin/_lib_conversation_query.py

@@ -11,10 +11,12 @@ deduped session_entries row (idx_entries_dedup), via the shared pricing helper
 — never per physical fragment and never from cost_usd_raw (often NULL).
 """
 from __future__ import annotations
+import base64 as _base64
 import json as _json
 import os
 import re
 import sqlite3
+from datetime import datetime as _datetime
 
 # Public surface (Plan 2): shipped in the npm tarball + brew formula + public
 # mirror — imported by the dashboard's conversation endpoints at runtime.
@@ -24,6 +26,9 @@ from _lib_pricing import _calculate_entry_cost
 # content block the same way the parser does at ingest — reuse the parser's
 # _stringify so the full (un-capped) result text matches the cached/capped one.
 from _lib_conversation import _stringify
+# #177 S4: the media-route reader walks a content array with the SAME ordinal
+# generator the ingest placeholders used, so "media item N" addresses one item.
+from _lib_conversation import iter_media_items
 
 
 # Mirror of dashboard/web/src/conversations/systemMarkers.ts::MARKER_RE — anchored
@@ -389,14 +394,15 @@ def _turn_usage_map(conn, turn_keys):
     return usage
 
 
-def get_conversation(conn, session_id, *, after=None, limit=500):
-    """Reader payload for one session (spec §3.2). Returns None for an unknown
-    session. Dedups logical messages by (session_id, uuid) (canonical = earliest
-    timestamp), groups assistant fragments into turn items by (msg_id, req_id),
-    joins cost once, anchors a turn on its prose-bearing fragment, and exposes
-    every member fragment uuid for jump resolution. Cursor over (timestamp_utc,
-    id); ~500 items/page."""
-    limit = max(1, min(int(limit), 1000))
+def _assemble_session(conn, session_id):
+    """Shared assembly for get_conversation / get_conversation_outline (#177 S5).
+
+    Runs the full dedup → turn-grouping → fold → sweep → meta-classify →
+    cost/usage-stamp pipeline over the WHOLE session and returns the
+    pre-pagination state, so the outline's turns match the reader's items 1:1
+    BY CONSTRUCTION (Codex F8 — one grouping pass, never two implementations).
+    Returns None for an unknown session.
+    """
     exists = conn.execute(
         "SELECT 1 FROM conversation_messages WHERE session_id=? LIMIT 1",
         (session_id,)).fetchone()
@@ -489,6 +495,8 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
     agent_link = {}     # tool_use id -> (agent_id, raw_meta)
     ask_link = {}       # tool_use id -> (answers, annotations)  (#177 S2)
     bash_link = {}      # tool_use id -> (stderr, interrupted)   (#177 S3)
+    web_search_link = {}  # tool_use id -> web_search payload    (#177 S4)
+    web_fetch_link = {}   # tool_use id -> web_fetch payload     (#177 S4)
     task_link = {}      # tool_use id -> {"task_id", "task_list"}  (Task* checklist)
     for it in items:
         for b in it["blocks"]:
@@ -510,6 +518,12 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
                 bintr = b.pop("bash_interrupted", None)
                 if b.get("tool_use_id") is not None and (bstderr is not None or bintr):
                     bash_link[b["tool_use_id"]] = (bstderr, bool(bintr))
+                ws = b.pop("web_search", None)              # #177 S4
+                if ws is not None and b.get("tool_use_id") is not None:
+                    web_search_link[b["tool_use_id"]] = ws
+                wf = b.pop("web_fetch", None)               # #177 S4
+                if wf is not None and b.get("tool_use_id") is not None:
+                    web_fetch_link[b["tool_use_id"]] = wf
                 tid_ = b.pop("task_id", None)               # Task* checklist
                 tlist_ = b.pop("task_list", None)
                 if b.get("tool_use_id") is not None and (tid_ is not None or tlist_ is not None):
@@ -553,6 +567,9 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
                                        "truncated": bool(res_block.get("truncated")),
                                        "full_length": res_block.get("full_length"),
                                        "is_error": bool(res_block.get("is_error"))}
+                res_media = res_block.get("media")    # #177 S4: public render-ready key
+                if res_media:
+                    use_block["result"]["media"] = res_media
             owner["member_uuids"].append(tr["anchor"]["uuid"])
             drop.add(id(tr))
         # else: leave tr standalone (orphan / multi-owner / mixed) — a folded
@@ -583,6 +600,14 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
                             b["stderr"] = blink[0]
                         if blink[1]:
                             b["interrupted"] = True
+                    if b.get("name") == "WebSearch":         # #177 S4: name-keyed
+                        wslink = web_search_link.get(b["tool_use_id"])
+                        if wslink is not None:
+                            b["web_search"] = wslink
+                    if b.get("name") == "WebFetch":          # #177 S4: name-keyed
+                        wflink = web_fetch_link.get(b["tool_use_id"])
+                        if wflink is not None:
+                            b["web_fetch"] = wflink
 
     # ---- Phase 3b: fold the Task* op stream into per-run checklist snapshots ----
     _fold_task_runs(items, task_link)
@@ -670,6 +695,26 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
     for it in items:
         it.pop("_source_tool_use_id", None)
 
+    return {"items": items, "logical": logical,
+            "subagent_meta": subagent_meta, "header_cost": header_cost}
+
+
+def get_conversation(conn, session_id, *, after=None, limit=500):
+    """Reader payload for one session (spec §3.2). Returns None for an unknown
+    session. Dedups logical messages by (session_id, uuid) (canonical = earliest
+    timestamp), groups assistant fragments into turn items by (msg_id, req_id),
+    joins cost once, anchors a turn on its prose-bearing fragment, and exposes
+    every member fragment uuid for jump resolution. Cursor over (timestamp_utc,
+    id); ~500 items/page."""
+    limit = max(1, min(int(limit), 1000))
+    asm = _assemble_session(conn, session_id)
+    if asm is None:
+        return None
+    items = asm["items"]
+    logical = asm["logical"]
+    subagent_meta = asm["subagent_meta"]
+    header_cost = asm["header_cost"]
+
     # Cursor pagination over the item list (anchored to each item's canonical id).
     # A non-None `after` that matches no item's anchor (stale/deleted cursor)
     # yields an EMPTY page — never silently re-serves the head (M1).
@@ -720,6 +765,104 @@ def get_conversation(conn, session_id, *, after=None, limit=500):
     }
 
 
+_OUTLINE_LABEL_CAP = 120
+
+
+def _outline_label(text):
+    """First non-blank line, capped at _OUTLINE_LABEL_CAP chars ('' when none)."""
+    for ln in (text or "").splitlines():
+        s = ln.strip()
+        if s:
+            return s[:_OUTLINE_LABEL_CAP]
+    return ""
+
+
+def _parse_outline_ts(ts):
+    if not ts:
+        return None
+    try:
+        return _datetime.fromisoformat(str(ts).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def get_conversation_outline(conn, session_id):
+    """Full-session per-turn skeleton + aggregates (#177 S5, spec §1).
+
+    No pagination — every grouped turn, but only skeleton fields (no inputs,
+    no result bodies, no full prose). `ts` is NULLABLE (Codex F6); stats and
+    every consumer tolerate it. Stats derive from the SAME assembled items the
+    reader pages (Codex F8). Returns None for an unknown session.
+    """
+    asm = _assemble_session(conn, session_id)
+    if asm is None:
+        return None
+    items, logical = asm["items"], asm["logical"]
+    turns = []
+    turn_counts = {"total": 0, "human": 0, "assistant": 0, "tool_result": 0, "meta": 0}
+    tool_counts, models = {}, {}
+    error_count = 0
+    tokens = {"input": 0, "output": 0, "cache_creation": 0, "cache_read": 0}
+    for it in items:
+        kind = it["kind"]
+        turn_counts["total"] += 1
+        if kind in turn_counts:
+            turn_counts[kind] += 1
+        t = {"uuid": it["anchor"]["uuid"], "kind": kind, "ts": it["ts"],
+             "label": _outline_label(it.get("text", "")),
+             "member_uuids": list(it["member_uuids"]),
+             "subagent_key": it["subagent_key"], "parent_uuid": it["parent_uuid"],
+             "is_sidechain": it["is_sidechain"]}
+        tools, thinking = [], []
+        for b in it["blocks"]:
+            bk = b.get("kind")
+            if bk in ("tool_call", "tool_use"):
+                res = b.get("result")
+                err = bool(res and res.get("is_error"))
+                tools.append({"name": b.get("name"), "is_error": err})
+            elif bk == "tool_result":                  # orphan error channel (spec delta b)
+                tools.append({"name": None, "is_error": bool(b.get("is_error"))})
+            elif bk == "thinking":
+                ln = _outline_label(b.get("text", ""))
+                if ln:
+                    thinking.append(ln)
+        for tref in tools:
+            if tref["is_error"]:
+                error_count += 1
+            if tref["name"]:
+                tool_counts[tref["name"]] = tool_counts.get(tref["name"], 0) + 1
+        if tools:
+            t["tools"] = tools
+        if thinking:
+            t["thinking"] = thinking
+        if kind == "assistant":
+            if it.get("model"):
+                t["model"] = it["model"]
+                models[it["model"]] = models.get(it["model"], 0) + 1
+            tok = it.get("tokens")
+            if tok is not None:
+                t["tokens"] = tok
+                for k in tokens:
+                    tokens[k] += tok.get(k, 0)
+        if kind == "meta":
+            t["meta_kind"] = it.get("meta_kind")
+            t["skill_name"] = it.get("skill_name")
+            if not t["label"]:
+                t["label"] = _outline_label(it.get("skill_name") or "")
+        turns.append(t)
+    ts_vals = [r[2] for r in logical if r[2]]
+    d0 = _parse_outline_ts(ts_vals[0] if ts_vals else None)
+    d1 = _parse_outline_ts(ts_vals[-1] if ts_vals else None)
+    duration = int((d1 - d0).total_seconds()) if d0 and d1 else None
+    return {"session_id": session_id,
+            "subagent_meta": asm["subagent_meta"],
+            "stats": {"turns": turn_counts, "tool_counts": tool_counts,
+                      "error_count": error_count, "models": models,
+                      "duration_seconds": duration, "tokens": tokens,
+                      "cost_usd": asm["header_cost"]},
+            "turns": turns}
+
+
 _TASK_TRIO = ("TaskCreate", "TaskUpdate", "TaskList")
 
 
@@ -1317,3 +1460,117 @@ def read_full_payload(source_path, byte_offset, tool_use_id, which):
                 resp["stderr"] = tur["stderr"][:_FULL_PAYLOAD_CEILING]   # per-stream bound (see above)
             return resp
     return None
+
+
+# ---------------------------------------------------------------------------
+# #177 S4: on-demand media kernel. The route re-reads the source JSONL line by
+# byte_offset (the #178 mechanism), decodes the base64 of the addressed media
+# ordinal, and serves the raw bytes — nothing is ever written to cache.db.
+# ---------------------------------------------------------------------------
+_MEDIA_LINE_CEILING = 64 * 1024 * 1024     # raw line read cap (pathological guard)
+_MEDIA_PAYLOAD_CEILING = 20 * 1024 * 1024  # decoded cap; enforced on ENCODED length
+# Response Content-Type is the matched constant — never an echoed transcript string.
+_MEDIA_TYPE_ALLOWLIST = {
+    "image/png": "image/png", "image/jpeg": "image/jpeg",
+    "image/gif": "image/gif", "image/webp": "image/webp",
+    "application/pdf": "application/pdf",
+}
+
+
+def locate_media(conn, session_id, *, tool_use_id=None, uuid=None, index=0):
+    """``(source_path, byte_offset)`` for the row whose stored placeholder
+    carries media ordinal ``index`` — tool_use_id mode reads tool_result
+    ``media[]``; uuid mode reads user-content image/document blocks. Mirrors
+    locate_tool_payload: instr() prefilter (never LIKE — ids contain ``_``),
+    candidates parsed + exact-matched, deterministic ORDER BY matching
+    get_conversation. ``None`` -> 404. Pre-reingest rows have no placeholder
+    and correctly 404 (the client renders the badge for them anyway)."""
+    if tool_use_id is not None:
+        rows = conn.execute(
+            "SELECT source_path, byte_offset, blocks_json FROM conversation_messages "
+            "WHERE session_id=? AND instr(blocks_json, ?) > 0 "
+            "ORDER BY timestamp_utc, id", (session_id, tool_use_id)).fetchall()
+    else:
+        rows = conn.execute(
+            "SELECT source_path, byte_offset, blocks_json FROM conversation_messages "
+            "WHERE session_id=? AND uuid=? ORDER BY timestamp_utc, id",
+            (session_id, uuid)).fetchall()
+    for source_path, byte_offset, blocks_json in rows:
+        try:
+            blocks = _json.loads(blocks_json)
+        except (ValueError, TypeError):
+            continue
+        if not isinstance(blocks, list):
+            continue
+        for b in blocks:
+            if not isinstance(b, dict):
+                continue
+            if tool_use_id is not None:
+                if (b.get("kind") == "tool_result"
+                        and b.get("tool_use_id") == tool_use_id):
+                    for m in b.get("media") or []:
+                        if isinstance(m, dict) and m.get("index") == index:
+                            return source_path, byte_offset
+            elif (b.get("kind") in ("image", "document")
+                    and b.get("index") == index):
+                return source_path, byte_offset
+    return None
+
+
+def read_media_bytes(source_path, byte_offset, *, tool_use_id=None, uuid=None,
+                     index=0):
+    """Re-read the source line and return ``("ok", media_type, raw_bytes)`` for
+    media ordinal ``index``, else ``("unsupported"|"too_large"|"gone", None,
+    None)`` (-> 404 / 413 / 410). The decoded cap is enforced as an
+    ENCODED-length precheck — never decode-then-measure (Codex F4); decode is
+    strict (validate=True; binascii.Error subclasses ValueError). The media
+    walk IS iter_media_items — the same generator the ingest placeholders used,
+    so ordinals cannot drift (spec §4.1 chokepoint)."""
+    try:
+        with open(source_path, "rb") as fh:
+            fh.seek(byte_offset)
+            line = fh.readline(_MEDIA_LINE_CEILING + 1)
+        if len(line) > _MEDIA_LINE_CEILING:
+            return ("too_large", None, None)
+        obj = _json.loads(line)
+    except (OSError, ValueError):
+        return ("gone", None, None)
+    if not isinstance(obj, dict):
+        return ("gone", None, None)
+    content = (obj.get("message") or {}).get("content")
+    if not isinstance(content, list):
+        return ("gone", None, None)
+    if tool_use_id is not None:
+        target = None
+        for b in content:
+            if (isinstance(b, dict) and b.get("type") == "tool_result"
+                    and b.get("tool_use_id") == tool_use_id):
+                target = b.get("content")
+                break
+        if target is None:
+            return ("gone", None, None)
+    else:
+        target = content
+    item = None
+    for idx, m in iter_media_items(target):
+        if idx == index:
+            item = m
+            break
+    if item is None:
+        return ("gone", None, None)
+    source = item.get("source")
+    if not isinstance(source, dict):
+        return ("gone", None, None)
+    media_type = _MEDIA_TYPE_ALLOWLIST.get(source.get("media_type"))
+    if media_type is None:
+        return ("unsupported", None, None)
+    data = source.get("data")
+    if not isinstance(data, str):
+        return ("gone", None, None)
+    if len(data) > _MEDIA_PAYLOAD_CEILING * 4 // 3:
+        return ("too_large", None, None)
+    try:
+        raw = _base64.b64decode(data, validate=True)
+    except ValueError:
+        return ("gone", None, None)
+    return ("ok", media_type, raw)