cctally 1.72.0 → 1.73.0

package/bin/_cctally_transcript.py

@@ -48,12 +48,43 @@ def cmd_transcript(args) -> int:
 
 # ---- export ----------------------------------------------------------------
 
+_SPEED_ONLY_CODEX_MSG = "transcript: --speed applies only to Codex conversations"
+_PENDING_EXPORT_MSG = (
+    "transcript: Codex conversation is not yet normalized "
+    "(migration 025 runs on the next cache open) — retry shortly")
+
+
+def _emit_export(md: str, output) -> None:
+    """Byte-exact emission shared by the bare and qualified export paths: the exact
+    UTF-8 bytes to ``--output`` or to stdout (no ``print``, no added trailing
+    newline — the render already ends in exactly one), so the CLI byte-matches
+    ``GET /api/conversation/<id>/export``."""
+    data = md.encode("utf-8")
+    if output:
+        pathlib.Path(output).write_bytes(data)
+    else:
+        sys.stdout.buffer.write(data)
+        sys.stdout.buffer.flush()
+
+
 def _cmd_transcript_export(args) -> int:
     c = _cctally()
     session_id = args.session_id
     scope = getattr(args, "scope", "all")
     raw = bool(getattr(args, "raw", False))
     output = getattr(args, "output", None)
+    speed_arg = getattr(args, "speed", None)   # None sentinel = flag omitted
+
+    if session_id.startswith("v1."):
+        return _cmd_transcript_export_qualified(
+            c, session_id, scope, raw, output, speed_arg)
+
+    # Legacy bare Claude path — byte-untouched. --speed is Codex pricing behavior,
+    # so an explicit value on any non-Codex ref is a usage error (resolved-source
+    # rule, §4.1) — never a silent no-op.
+    if speed_arg is not None:
+        eprint(_SPEED_ONLY_CODEX_MSG)
+        return 2
 
     conn = c.open_cache_db()
     try:
@@ -69,19 +100,68 @@ def _cmd_transcript_export(args) -> int:
     finally:
         conn.close()
 
-    data = md.encode("utf-8")
-    if output:
-        pathlib.Path(output).write_bytes(data)
-    else:
-        # Byte-exact: raw bytes to stdout, no `print`, no added trailing newline.
-        sys.stdout.buffer.write(data)
-        sys.stdout.buffer.flush()
+    _emit_export(md, output)
+    return 0
+
+
+def _cmd_transcript_export_qualified(
+        c, session_id, scope, raw, output, speed_arg) -> int:
+    """Qualified (``v1.``) export via the neutral dispatch layer (§4.1). Anonymized
+    by default with the QUALIFIED provider-aware plan (§3.6); ``--raw`` escapes.
+    Byte-matches ``GET /api/conversation/<v1key>/export`` in both modes."""
+    disp = c._load_sibling("_lib_conversation_dispatch")
+    cref = disp.resolve_conversation_ref(session_id)
+    # Resolved-source --speed rejection (§4.1): explicit --speed (any value,
+    # including auto) is a usage error unless the ref resolves to source == codex.
+    if speed_arg is not None and (cref is None or cref.source != "codex"):
+        eprint(_SPEED_ONLY_CODEX_MSG)
+        return 2
+    speed = c._resolve_codex_speed(speed_arg or "auto")
+
+    conn = c.open_cache_db()
+    try:
+        env = disp.neutral_export(
+            conn, session_id, scope=scope, effective_speed=speed)
+        status = env.get("status")
+        if status == "normalization_pending":
+            eprint(_PENDING_EXPORT_MSG)
+            return 1
+        if status == "validation_error":
+            eprint(f"transcript: scope {scope!r} is not supported for a Codex "
+                   f"conversation (only the whole-conversation export)")
+            return 2
+        if status != "ok":
+            eprint(f"transcript: no conversation found for key {session_id!r}")
+            return 1
+        md = env["markdown"]
+        if not raw:
+            cq = c._load_sibling("_lib_conversation_query")
+            anon = c._load_sibling("_lib_conversation_anon")
+            plan = cq.build_anon_plan_for_sources(
+                conn, home_dir=os.path.expanduser("~"),
+                sources={cref.source})
+            md = anon.scrub_text(md, plan)
+    finally:
+        conn.close()
+
+    _emit_export(md, output)
     return 0
 
 
 # ---- search ----------------------------------------------------------------
 
 def _cmd_transcript_search(args) -> int:
+    if getattr(args, "source", "claude") == "codex":
+        return _cmd_transcript_search_codex(args)
+    # Legacy Claude path (byte-frozen). --cursor is Codex-only pagination — using
+    # it with --source claude is a usage error, never a silent no-op (§4.3).
+    if getattr(args, "cursor", None) is not None:
+        eprint("transcript: --cursor requires --source codex")
+        return 2
+    return _cmd_transcript_search_claude(args)
+
+
+def _cmd_transcript_search_claude(args) -> int:
     c = _cctally()
     query = args.query
     kind = getattr(args, "kind", "all")
@@ -131,6 +211,142 @@ def _cmd_transcript_search(args) -> int:
     return 0
 
 
+# ---- search (Codex) --------------------------------------------------------
+
+_CODEX_SEARCH_PENDING_MSG = (
+    "transcript: Codex conversations are not yet normalized "
+    "(migration 025 runs on the next cache open); no results yet")
+
+
+def _cmd_transcript_search_codex(args) -> int:
+    """``transcript search --source codex`` (§4.3). The Codex search kernel has no
+    filter axes and paginates by opaque cursor, so ``--offset`` and the Claude-only
+    filter flags are usage errors, and ``--cursor`` carries the external cursor."""
+    c = _cctally()
+    query = args.query
+    kind = getattr(args, "kind", "all")
+    limit = getattr(args, "limit", 50)
+    cursor = getattr(args, "cursor", None)
+    as_json = bool(getattr(args, "json", False))
+
+    # Pagination + filter axes the Codex kernel does not have → exit 2 (silently
+    # ignoring a filter would fabricate results).
+    if getattr(args, "offset", 0):
+        eprint("transcript: --offset is not supported with --source codex "
+               "(use --cursor)")
+        return 2
+    rejected = []
+    if getattr(args, "project", None):
+        rejected.append("--project")
+    if getattr(args, "model", None):
+        rejected.append("--model")
+    if getattr(args, "date_from", None):
+        rejected.append("--date-from")
+    if getattr(args, "date_to", None):
+        rejected.append("--date-to")
+    if getattr(args, "cost_min", None) is not None:
+        rejected.append("--cost-min")
+    if getattr(args, "cost_max", None) is not None:
+        rejected.append("--cost-max")
+    if getattr(args, "rebuild_min", None) is not None:
+        rejected.append("--rebuild-min")
+    if rejected:
+        eprint(f"transcript: {', '.join(rejected)} not supported with "
+               f"--source codex")
+        return 2
+
+    disp = c._load_sibling("_lib_conversation_dispatch")
+    # Validate the external cursor up front → exit 2 on a bad token.
+    if cursor is not None:
+        try:
+            disp.decode_search_cursor(cursor)
+        except disp.InvalidSearchCursor:
+            eprint("transcript: invalid --cursor")
+            return 2
+
+    conn = c.open_cache_db()
+    try:
+        result = disp.neutral_search(
+            conn, query, source="codex", kind=kind,
+            effective_speed=c._resolve_codex_speed("auto"),
+            limit=limit, cursor=cursor)
+    finally:
+        conn.close()
+
+    # normalization_pending: an empty, exit-0 answer with one stderr note — search
+    # is navigation, and "nothing yet" is truthful (§4.3).
+    if result.get("status") == "normalization_pending":
+        eprint(_CODEX_SEARCH_PENDING_MSG)
+
+    if as_json:
+        payload = c.stamp_schema_version(_codex_search_to_camel(result, query))
+        print(_json_dumps(payload))
+        return 0
+    _render_codex_search_table(args, result)
+    return 0
+
+
+def _codex_search_to_camel(result: dict, query: str) -> dict:
+    """The pinned, stamped-first camelCase Codex search envelope (§4.3):
+    ``{schemaVersion, source, query, mode, total, hits[...], nextCursor}``. The
+    leading ``schemaVersion`` is inserted by ``stamp_schema_version``."""
+    hits = [
+        {
+            "conversationKey": h.get("conversation_key"),
+            "itemKey": h.get("item_key"),
+            "title": h.get("title"),
+            "snippet": h.get("snippet"),
+            "badges": h.get("badges", []),
+            "lastActivityUtc": h.get("last_activity_utc"),
+            "projectLabel": h.get("project_label"),
+        }
+        for h in result.get("hits", [])
+    ]
+    return {
+        "source": "codex",
+        "query": result.get("query", query),
+        "mode": result.get("mode"),
+        "total": result.get("total", 0),
+        "hits": hits,
+        "nextCursor": (result.get("page") or {}).get("cursor"),
+    }
+
+
+def _render_codex_search_table(args, result: dict) -> None:
+    """Codex human table: Key / When / Project / Kinds / Snippet (§4.3). ``Key`` is
+    the full untruncated ``v1.`` conversation key (so search → export pipes);
+    ``When`` renders ``last_activity_utc`` through the display-tz chokepoint;
+    ``Project`` is ``—`` when null; ``Kinds`` are the hit badges."""
+    c = _cctally()
+    hits = result.get("hits", [])
+    if not hits:
+        print("No matching transcripts.")
+        return
+    tz = c.resolve_display_tz(args, c.load_config())
+    rows = []
+    for h in hits:
+        last = h.get("last_activity_utc")
+        when = c.format_display_dt(
+            last, tz, fmt="%Y-%m-%d %H:%M", suffix=True) if last else ""
+        kinds = ",".join(h.get("badges") or []) or "-"
+        rows.append([
+            h.get("conversation_key") or "",     # full, untruncated key
+            when,
+            h.get("project_label") or "—",
+            kinds,
+            (h.get("snippet") or "").strip(),
+        ])
+    table = _boxed_table(
+        ["Key", "When", "Project", "Kinds", "Snippet"], rows,
+        ["left", "left", "left", "left", "left"])
+    print(table)
+    total = result.get("total", len(hits))
+    print(f"\n{len(hits)} of {total} match(es)")
+    next_cursor = (result.get("page") or {}).get("cursor")
+    if next_cursor:
+        print(f"next: --cursor {next_cursor}")
+
+
 def _json_dumps(payload) -> str:
     import json
     return json.dumps(payload, indent=2)

package/bin/_lib_codex_conversation_export.py

@@ -0,0 +1,124 @@
+"""#294 S7 — deterministic Codex conversation Markdown renderer (§3.3).
+
+The Codex sibling of ``_lib_conversation_export`` (Claude). Pure and I/O-free: the
+whole input is the neutral detail envelope ``get_codex_conversation`` produces
+(items + blocks + per-turn cost + tokens + threading), so the render is a pure
+function of a fixed DB + effective_speed — no ambient width, version, or clock
+inputs, so a fixture golden only stales on a real data/pricing change.
+
+Provider-truthful throughout: native Codex token labels
+(``input``/``output``/``cached_input``/``reasoning_output``, never Claude cache
+vocabulary), per-turn cost with the unattributed bucket rendered as an explicit
+line, and children listed as ``v1.`` conversation-key references — NEVER inlined
+(a Codex child is its own conversation; inlining would double-export and break
+cost-once).
+"""
+from __future__ import annotations
+
+
+def _money(value: float | None) -> str:
+    """Deterministic USD formatting (no locale / ambient inputs)."""
+    return f"${(value or 0.0):.4f}"
+
+
+def _token_line(tokens: dict | None) -> str:
+    """Provider-native token summary — Codex fields only."""
+    t = tokens or {}
+    return (f"input {int(t.get('input', 0) or 0)} · "
+            f"output {int(t.get('output', 0) or 0)} · "
+            f"cached_input {int(t.get('cached_input', 0) or 0)} · "
+            f"reasoning_output {int(t.get('reasoning_output', 0) or 0)}")
+
+
+def _blockquote(text: str) -> str:
+    """Render ``text`` as a Markdown blockquote (one ``> `` per line)."""
+    lines = (text or "").splitlines() or [""]
+    return "\n".join(f"> {ln}" if ln else ">" for ln in lines)
+
+
+def _fence(text: str) -> str:
+    return f"```\n{text}\n```" if text else "_(empty)_"
+
+
+_ITEM_HEADER = {
+    "user": "## 👤 User",
+    "assistant": "## 🤖 Assistant",
+    "event": "## 🗓 Event",
+}
+
+
+def _render_block(b: dict) -> str:
+    bk = b.get("kind")
+    text = (b.get("text") or "").strip()
+    if bk == "reasoning":
+        return "> 💭 Reasoning\n>\n" + _blockquote(text) if text else ""
+    if bk == "tool_call":
+        detail = b.get("detail") if isinstance(b.get("detail"), dict) else {}
+        name = detail.get("name")
+        head = f"**🔧 Tool call: {name}**" if name else "**🔧 Tool call**"
+        chunks = [head]
+        if text:
+            chunks.append(_fence(text))
+        output = b.get("output")
+        if isinstance(output, dict):
+            otext = (output.get("text") or "").strip()
+            chunks.append("**Output**")
+            chunks.append(_fence(otext))
+        return "\n\n".join(c for c in chunks if c)
+    if bk == "tool_output":
+        return "**🔧 Tool output**\n\n" + _fence(text)
+    if bk == "event":
+        return f"> 🗓 {text}" if text else ""
+    # user / assistant prose block
+    return text
+
+
+def _render_item(it: dict) -> str:
+    kind = it.get("kind")
+    header = _ITEM_HEADER.get(kind, f"## {kind}")
+    ts = it.get("timestamp_utc") or ""
+    if ts:
+        header += f"  ·  {ts}"
+    model = it.get("model")
+    if kind == "assistant" and model:
+        header += f"  ·  {model}"
+    chunks = [header]
+    for b in it.get("blocks", []):
+        rendered = _render_block(b)
+        if rendered:
+            chunks.append(rendered)
+    cost = it.get("cost_usd")
+    if cost is not None:
+        chunks.append(f"_Cost: {_money(cost)} · {_token_line(it.get('tokens'))}_")
+    return "\n\n".join(c for c in chunks if c)
+
+
+def render_codex_conversation_markdown(detail: dict) -> str:
+    """Render a whole Codex conversation (an ``ok`` detail envelope) to Markdown.
+
+    Deterministic for a fixed ``detail``. Children appear only as ``v1.`` reference
+    lines — never inlined. The pending / not_found envelopes are handled upstream
+    (this renderer only ever sees ``ok``)."""
+    title = (detail.get("title") or "").strip()
+    parts = [f"# {title}" if title else "# Codex conversation"]
+    parent = detail.get("parent")
+    if isinstance(parent, dict) and parent.get("conversation_key"):
+        parts.append(
+            f"_Parent: {(parent.get('title') or '').strip()} "
+            f"(`{parent['conversation_key']}`)_")
+    for it in detail.get("items", []):
+        parts.append(_render_item(it))
+    unattr = detail.get("unattributed_cost_usd")
+    if unattr:
+        parts.append(f"_Unattributed cost: {_money(unattr)}_")
+    parts.append(
+        f"_Total cost: {_money(detail.get('total_cost_usd'))} · "
+        f"{_token_line(detail.get('tokens'))}_")
+    children = detail.get("children") or []
+    if children:
+        lines = ["## Child conversations"]
+        for c in children:
+            lines.append(
+                f"- {(c.get('title') or '').strip()} (`{c.get('conversation_key')}`)")
+        parts.append("\n".join(lines))
+    return "\n\n".join(p for p in parts if p).rstrip() + "\n"