chsum 3.0.2__tar.gz → 3.0.3__tar.gz

chsum-3.0.2/README.md → chsum-3.0.3/PKG-INFO

@@ -1,3 +1,14 @@
+Metadata-Version: 2.5
+Name: chsum
+Version: 3.0.3
+Summary: Work logs and reload-ready context from coding-agent conversations. Deterministic: no model, nothing invented.
+Author: InDate
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,claude-code,context,transcripts,work-log
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
 # chsum
 
 Work logs and reload-ready context from your coding-agent conversations —
@@ -452,8 +463,12 @@ chsum digest <ch_ref> --messages --stdout      # print it rather than write it
 chsum digest <ch_ref> --messages > out.md      # or your own path
 ```
 
-All three print in timestamp order across the transcript and its sidecars, with
-nothing filtered, deduplicated or collapsed. `--tools` and `--commands` print one
+All three print in timestamp order across the transcript and its sidecars.
+Three kinds of record are removed or merged, each because it repeats a row
+already printed or carries only harness text: a record holding nothing but a
+`<system-reminder>`, the harness's retry after a malformed tool call, and the
+task notification that points at a report delivered as a peer message — its
+status and usage move onto that report's row. `--tools` and `--commands` print one
 line per row — the call id, a `<session>:<line>` locator, local time, the tool
 name and the first line of the call. A row runs long and lets the terminal
 soft-wrap it rather than folding at a space: a command broken across lines can
@@ -465,6 +480,21 @@ cannot be used for. There is no flag or size limit behind that: the turn numbers
 below already select the part of a conversation you want, and a second way to
 ask for less would only be a worse one.
 
+A message row is labelled by the sender its record names in `origin`, so a
+report or an instruction another sender wrote never reads as yours:
+
+```
+- `410bfb1a:1157`  19:09:15  agent a3d9a4a28f0836307 returned · completed · 54k tokens · 7 tools · 56s
+- `0d02851a:1026`  12:15:53  message from key-service-be
+- `9cb6adfc/a29d93fd:216`  16:32:20  coordinator
+```
+
+A subagent's report prints once, from the parent's peer message where the
+parent holds one and from the agent's own handback call where the report
+arrived as an attachment. Only what you typed opens a turn in the parent;
+scoped to an agent, its caller's and its coordinator's messages open the
+agent's turns.
+
 Between them it prints every call, each the same single clipped line `--tools`
 gives it. A turn headed `2 tool calls · 8 commands` states how many ran and
 names none of them, which leaves the work between two replies unreadable; the
@@ -486,7 +516,8 @@ prints one tool call and its captured output whole, which is where the text a
 clipped call row actually lives.
 
 `--agents` lists every subagent the session ran and each report it sent back,
-numbered where an agent returned more than once. A report is the agent's own
+numbered where an agent returned more than once, each headed by the status and
+usage of the stop that sent it. A report is the agent's own
 document and runs to thousands of characters, so it is clipped with the cut
 marked; the row it came from names where the whole text is.
 

chsum-3.0.2/PKG-INFO → chsum-3.0.3/README.md

@@ -1,14 +1,3 @@
-Metadata-Version: 2.5
-Name: chsum
-Version: 3.0.2
-Summary: Work logs and reload-ready context from coding-agent conversations. Deterministic: no model, nothing invented.
-Author: InDate
-License-Expression: MIT
-License-File: LICENSE
-Keywords: claude,claude-code,context,transcripts,work-log
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-
 # chsum
 
 Work logs and reload-ready context from your coding-agent conversations —
@@ -463,8 +452,12 @@ chsum digest <ch_ref> --messages --stdout      # print it rather than write it
 chsum digest <ch_ref> --messages > out.md      # or your own path
 ```
 
-All three print in timestamp order across the transcript and its sidecars, with
-nothing filtered, deduplicated or collapsed. `--tools` and `--commands` print one
+All three print in timestamp order across the transcript and its sidecars.
+Three kinds of record are removed or merged, each because it repeats a row
+already printed or carries only harness text: a record holding nothing but a
+`<system-reminder>`, the harness's retry after a malformed tool call, and the
+task notification that points at a report delivered as a peer message — its
+status and usage move onto that report's row. `--tools` and `--commands` print one
 line per row — the call id, a `<session>:<line>` locator, local time, the tool
 name and the first line of the call. A row runs long and lets the terminal
 soft-wrap it rather than folding at a space: a command broken across lines can
@@ -476,6 +469,21 @@ cannot be used for. There is no flag or size limit behind that: the turn numbers
 below already select the part of a conversation you want, and a second way to
 ask for less would only be a worse one.
 
+A message row is labelled by the sender its record names in `origin`, so a
+report or an instruction another sender wrote never reads as yours:
+
+```
+- `410bfb1a:1157`  19:09:15  agent a3d9a4a28f0836307 returned · completed · 54k tokens · 7 tools · 56s
+- `0d02851a:1026`  12:15:53  message from key-service-be
+- `9cb6adfc/a29d93fd:216`  16:32:20  coordinator
+```
+
+A subagent's report prints once, from the parent's peer message where the
+parent holds one and from the agent's own handback call where the report
+arrived as an attachment. Only what you typed opens a turn in the parent;
+scoped to an agent, its caller's and its coordinator's messages open the
+agent's turns.
+
 Between them it prints every call, each the same single clipped line `--tools`
 gives it. A turn headed `2 tool calls · 8 commands` states how many ran and
 names none of them, which leaves the work between two replies unreadable; the
@@ -497,7 +505,8 @@ prints one tool call and its captured output whole, which is where the text a
 clipped call row actually lives.
 
 `--agents` lists every subagent the session ran and each report it sent back,
-numbered where an agent returned more than once. A report is the agent's own
+numbered where an agent returned more than once, each headed by the status and
+usage of the stop that sent it. A report is the agent's own
 document and runs to thousands of characters, so it is clipped with the cut
 marked; the row it came from names where the whole text is.
 

{chsum-3.0.2 → chsum-3.0.3}/chsum/core.py

@@ -667,6 +667,9 @@ _NOISE_MARKERS = (
 _NOISE_PREFIXES = (
     "## Context Usage",  # `/context` writes its report in as a user record
     "[Your previous response had no visible output",
+    "The previous response failed to produce a valid tool call",
+    "Another Claude session sent a message",
+    "The coordinator sent a message",
 )
 
 
@@ -679,6 +682,57 @@ def is_real_prompt(text: str) -> bool:
     return not any(m in t for m in _NOISE_MARKERS)
 
 
+def _origin(rec: dict) -> str:
+    """Who put a user record into the conversation: `origin.kind`, or
+    `turnOrigin`, the later spelling of the same field. "" on a tool result and
+    on records older than both."""
+    origin = rec.get("origin")
+    if isinstance(origin, dict) and origin.get("kind"):
+        return str(origin["kind"])
+    return str(rec.get("turnOrigin") or "")
+
+
+def _harness_sent(rec: dict) -> bool:
+    """A user record another sender wrote: a peer session, a coordinator, a task
+    notification. Records without the field fall through to the text rules."""
+    kind = _origin(rec)
+    return bool(kind) and kind != "human"
+
+
+_HANDBACK_LEAD = "The report follows:\n"
+
+
+def _hand_back(rec: dict) -> tuple[str, str] | None:
+    """(agent id, report) for a subagent's report delivered as a peer message.
+    The harness indents each report line by two spaces, which is removed here."""
+    origin = rec.get("origin")
+    if not (isinstance(origin, dict) and origin.get("kind") == "peer"
+            and origin.get("handback") and origin.get("from")):
+        return None
+    body = str(origin.get("body") or "")
+    _, lead, report = body.partition(_HANDBACK_LEAD)
+    report = report if lead else body
+    report = "\n".join(ln.removeprefix("  ") for ln in report.splitlines()).strip()
+    return str(origin["from"]), report
+
+
+_COORDINATOR_LEAD = re.compile(r"^The coordinator sent a message[^:]*:\s*")
+
+
+def _sent_message(rec: dict, text: str) -> tuple[str, str] | None:
+    """(label, text) for a message another sender put in the conversation: a
+    peer session, by the name it sent under, or a coordinator. The harness's
+    lead-in is dropped, which leaves the message as its sender wrote it."""
+    origin = rec.get("origin")
+    kind = _origin(rec)
+    if kind == "peer" and isinstance(origin, dict) and origin.get("body"):
+        who = origin.get("name") or origin.get("from") or "peer"
+        return f"message from {who}", str(origin["body"]).strip()
+    if kind == "coordinator":
+        return "coordinator", _COORDINATOR_LEAD.sub("", text)
+    return None
+
+
 def is_typed_prompt(text: str) -> bool:
     """`is_real_prompt`, minus `!` runs — something you did, not something you
     said. Note paths stay on `is_real_prompt`, since notes are typed via `!`."""
@@ -1552,6 +1606,8 @@ def _is_typed_prompt(rec: dict, command_ids: frozenset[str] = frozenset()) -> bo
     (`_command_prompt_ids`) — without it a slash command's body still reads as typed."""
     if rec.get("isCompactSummary") or _tool_injected(rec, command_ids):
         return False  # Claude Code's own auto-summary, or a loaded body — not typed
+    if _harness_sent(rec):
+        return False
     content = (rec.get("message") or {}).get("content")
     if isinstance(content, str):
         texts = [content]
@@ -2440,7 +2496,8 @@ def _drill_block(ref: str, path: pathlib.Path | None) -> list[str]:
     sides = subagent_transcripts(path)
     if sides:
         out.append("\nThe subagents it ran, each in its own file")
-        out += [f"- `{sc.stem.removeprefix('agent-')}` — `{sc}`" for sc in sides]
+        parent = _split_agent_ref(ref)[0]
+        out += [f"- `{parent}/{sc.stem.removeprefix('agent-')}` — `{sc}`" for sc in sides]
     out += ["\nTo read one line of it, put the number in place of `<line>`",
             f"- `sed -n '<line>p' {path} | jq`",
             "\nTo read it in full, in order",
@@ -3032,6 +3089,18 @@ _ROW_KINDS = {
 }
 
 
+# The tool a subagent returns its report through.
+_HANDBACK_TOOL = "SubagentHandback"
+_REMINDER_RE = re.compile(r"<system-reminder>.*?</system-reminder>", re.DOTALL)
+
+
+def _harness_reminder(rec: dict, text: str) -> bool:
+    """A user record the harness wrote whole: `isMeta`, and nothing left once its
+    `<system-reminder>` blocks are removed. `isMeta` alone also marks an image
+    paste, which is typed text and stays a row."""
+    return bool(rec.get("isMeta")) and not _REMINDER_RE.sub("", text).strip()
+
+
 def _short_id(tool_id: str) -> str:
     """Display form of a `tool_use` id. `toolu_` is on every one of them, so the
     prefix carries no information and costs six columns on every row."""
@@ -3045,6 +3114,12 @@ def collect_rows(path: pathlib.Path, kinds: tuple[str, ...],
     sections do all three, and these views are what they point at. `only_agent`
     narrows to one sidecar, for an agent ref."""
     out: list[_Row] = []
+    # (agent, report) the parent holds as a peer message. The same report sits
+    # in the agent's own handback call, and printing both repeats it. Keyed by
+    # the report too: a return delivered as an attachment leaves no peer record,
+    # and its handback call is then the only copy in any row.
+    handed: set[tuple[str, str]] = set()
+    stops: list[tuple[str, str, str]] = []
     for src, agent in mark_sources(path):
         if only_agent and agent != only_agent:
             continue
@@ -3066,9 +3141,19 @@ def collect_rows(path: pathlib.Path, kinds: tuple[str, ...],
         sidecars = _sidecar_ids(path)
         for lineno, rec in parsed:
             role = rec.get("type")
+            ts = str(rec.get("timestamp") or "")
+            # A notification delivered as an attachment leaves its text only in
+            # the queue record, which is where most handback stops are found.
+            body = rec.get("content")
+            if (role == "queue-operation" and rec.get("operation") == "enqueue"
+                    and isinstance(body, str)
+                    and _is_notification(body)
+                    and _points_to_handback(body)
+                    and (aid := _agent_return(body, names, sidecars))):
+                stops.append((aid, ts, _stop_note(body)))
+                continue
             if role not in ("user", "assistant"):
                 continue
-            ts = str(rec.get("timestamp") or "")
             content = (rec.get("message") or {}).get("content")
             texts: list[str] = []
             if isinstance(content, str):
@@ -3081,6 +3166,15 @@ def collect_rows(path: pathlib.Path, kinds: tuple[str, ...],
                         texts.append(part.get("text", ""))
                     elif part.get("type") == "tool_use":
                         name = str(part.get("name") or "?")
+                        report = (part.get("input") or {}).get("message")
+                        # The handback call's `message` is the agent's report and
+                        # the only copy of it in any user or assistant record: the
+                        # parent receives it as an attachment, which no row reads.
+                        if (name == _HANDBACK_TOOL and "message" in kinds
+                                and isinstance(report, str) and report.strip()):
+                            out.append(_Row(ts, agent, "message", "", report.strip(),
+                                            f"agent {agent} returned", lineno, src))
+                            continue
                         cmd = (part.get("input") or {}).get("command")
                         bash = name == "Bash" and isinstance(cmd, str) and cmd.strip()
                         kind = "command" if bash else "tool"
@@ -3094,6 +3188,8 @@ def collect_rows(path: pathlib.Path, kinds: tuple[str, ...],
             if role == "user" and _tool_injected(rec, command_ids):
                 continue
             text = "\n".join(t for t in texts if t.strip()).strip()
+            if role == "user" and _harness_reminder(rec, text):
+                continue
             # An answer to the question tool carries its text in a structured
             # field and none in the body, so the view dropped it and a window
             # numbered by turns would skip the turn a menu choice settled.
@@ -3112,25 +3208,49 @@ def collect_rows(path: pathlib.Path, kinds: tuple[str, ...],
             # it, and dropping it would leave the run with no turn 1 at all.
             starts = bool(role == "user" and (not agent or only_agent)
                           and not rec.get("isCompactSummary")
+                          and not _harness_sent(rec)
                           and (answered or is_typed_prompt(text)
                                or (only_agent and not started)))
             returned = ""
-            if role == "user" and text.lstrip().startswith("<task-notification>"):
+            if role == "user" and _is_notification(text):
                 aid = _agent_return(text, names, sidecars)
+                if aid and _points_to_handback(text):
+                    stops.append((aid, ts, _stop_note(text)))
+                    continue
                 got = _task_fields(text)
                 via = names.get(got["tool-use-id"], "")
                 returned = (f"agent {aid} returned" if aid
                             else f"{via or 'task'} {got['task-id'] or '?'} finished")
                 text = _report_text(text)
                 starts = False
+            if role == "user" and (hand := _hand_back(rec)):
+                handed.add(hand)
+                returned = f"agent {hand[0]} returned"
+                text = hand[1]
+                starts = False
+            elif role == "user" and (sent := _sent_message(rec, text)):
+                returned, text = sent
+                # Scoped to an agent, its caller's message is the agent's next
+                # prompt, as the task it was spawned with is its first.
+                starts = bool(only_agent)
+            elif role == "user" and text.startswith(_NOISE_PREFIXES):
+                continue
             if text:
                 started = started or starts
                 out.append(_Row(ts, agent, "message", "", text,
                                 returned or role, lineno, src, starts,
                                 asked=tur if answered else None))
+    out = [r for r in out if not ((r.agent, r.text) in handed and r.kind == "message"
+                                  and r.label == f"agent {r.agent} returned")]
     # A parent's line numbers and a sidecar's don't order against each other;
     # only a clock does. Same reason `mark_sources`' readers sort by timestamp.
     out.sort(key=lambda r: r.when)
+    out = _fold_stops(
+        out, stops,
+        lambda r: (r.label.removeprefix("agent ").removesuffix(" returned")
+                   if r.kind == "message" and r.label.endswith(" returned") else ""),
+        lambda r: r.when,
+        lambda r, note: dataclasses.replace(r, label=f"{r.label} · {note}"))
     TRACE.step("collect_rows", kinds=",".join(kinds), rows=len(out),
                agent=only_agent or "(all)",
                span=f"{out[0].when}→{out[-1].when}" if out else "—")
@@ -3189,6 +3309,17 @@ def _tool_names(parsed) -> dict[str, str]:
     return names
 
 
+# How a notification record opens: the bare tag, or the tag behind the harness's
+# `[SYSTEM NOTIFICATION - NOT USER INPUT]` preamble. Anchored at the start
+# either way, since a message quoting the tag mid-text is not a notification.
+_NOTIFICATION_LEADS = ("<task-notification>", "[SYSTEM NOTIFICATION")
+
+
+def _is_notification(text: str) -> bool:
+    return (text.lstrip().startswith(_NOTIFICATION_LEADS)
+            and "<task-notification>" in text)
+
+
 def _task_fields(text: str) -> dict[str, str]:
     return {f: (m.group(1).strip() if (m := r.search(text)) else "")
             for f, r in _TASK_FIELD_RE.items()}
@@ -3227,15 +3358,45 @@ class _AgentReport:
     status: str
     summary: str
     result: str
+    # The line is in the agent's own transcript, not the parent's: the report
+    # reached the parent only as an attachment, and its handback call is the
+    # one record holding it.
+    in_sidecar: bool = False
+
+
+def _handback_reports(path: pathlib.Path) -> list[_AgentReport]:
+    """Every report an agent returned through its handback call, read from its
+    own transcript."""
+    out: list[_AgentReport] = []
+    for side in subagent_transcripts(path):
+        agent = side.stem.removeprefix("agent-")
+        for lineno, raw in enumerate(side.read_text(errors="replace").splitlines(), 1):
+            try:
+                rec = json.loads(raw)
+            except json.JSONDecodeError:
+                continue
+            content = (rec.get("message") or {}).get("content") if isinstance(rec, dict) else None
+            for part in content if isinstance(content, list) else []:
+                if not (isinstance(part, dict) and part.get("type") == "tool_use"
+                        and part.get("name") == _HANDBACK_TOOL):
+                    continue
+                report = (part.get("input") or {}).get("message")
+                if isinstance(report, str) and report.strip():
+                    out.append(_AgentReport(agent, str(rec.get("timestamp") or ""),
+                                            lineno, "", "", report.strip(),
+                                            in_sidecar=True))
+    return out
 
 
 def _agent_reports(path: pathlib.Path) -> list[_AgentReport]:
     """Every subagent return recorded in a parent transcript, in order. The
-    `<task-notification>` record is where the report lands: an async agent's
+    report lands in a `<task-notification>` record, or in a peer message where
+    the agent returned it through its handback call: an async agent's
     `tool_result` carries launch metadata, not the work."""
     out: list[_AgentReport] = []
     names: dict[str, str] = {}
     sidecars = _sidecar_ids(path)
+    stops: list[tuple[str, str, str]] = []
     for lineno, raw in enumerate(path.read_text(errors="replace").splitlines(), 1):
         try:
             rec = json.loads(raw)
@@ -3244,6 +3405,10 @@ def _agent_reports(path: pathlib.Path) -> list[_AgentReport]:
         if not isinstance(rec, dict):
             continue
         names.update(_tool_names([rec]))
+        if rec.get("type") == "user" and (hand := _hand_back(rec)):
+            out.append((True, _AgentReport(hand[0], str(rec.get("timestamp") or ""),
+                                           lineno, "", "", hand[1])))
+            continue
         content = (rec.get("message") or {}).get("content")
         texts = ([content] if isinstance(content, str)
                  else [p.get("text", "") for p in content
@@ -3263,26 +3428,80 @@ def _agent_reports(path: pathlib.Path) -> list[_AgentReport]:
             # notifications reads back as one otherwise — a 52,293-char paste
             # and an assistant message on the mechanism both matched a substring
             # test, and every one of them collapsed into a single nameless agent.
-            if not text.lstrip().startswith("<task-notification>"):
+            if not _is_notification(text):
                 continue
             if not _agent_return(text, names, sidecars):
                 continue
             got = _task_fields(text)
+            if _points_to_handback(text):
+                stops.append((got["task-id"], str(rec.get("timestamp") or ""),
+                              _stop_note(text)))
+                continue
             out.append((rec.get("type") == "user",
                         _AgentReport(got["task-id"], str(rec.get("timestamp") or ""),
                                      lineno, got["status"], got["summary"],
                                      got["result"])))
+    # Undelivered, so a peer message holding the same report wins the key below.
+    out += [(False, r) for r in _handback_reports(path)]
     kept: dict[tuple, _AgentReport] = {}
     for delivered, rep in out:
         key = (rep.agent, rep.status, rep.result)
         if delivered or key not in kept:
             kept[key] = rep
-    reports = sorted(kept.values(), key=lambda r: r.line)
+    # By time: a sidecar's line numbers don't order against the parent's.
+    reports = sorted(kept.values(), key=lambda r: (r.when, r.line))
+    # A notification enqueued and then delivered is the same stop twice.
+    stops = list(dict.fromkeys(stops))
+    reports = _fold_stops(
+        reports, [s for s in stops if s[1]], lambda r: r.agent, lambda r: r.when,
+        lambda r, note: dataclasses.replace(r, status=note) if not r.status else r)
     TRACE.step("_agent_reports", reports=len(reports), records=len(out),
                agents=len({r.agent for r in reports}))
     return reports
 
 
+# The `<result>` of a notification sent after a handback call. The report sits
+# in the peer message before it, so this notification adds only the stop's
+# status and usage, which are moved onto that report's row.
+_HANDBACK_POINTER = "This agent's report was delivered to you as a message from"
+_USAGE_RE = {f: re.compile(rf"<{f}>(\d+)</{f}>")
+             for f in ("subagent_tokens", "tool_uses", "duration_ms")}
+
+
+def _stop_note(text: str) -> str:
+    """`completed · 54k tokens · 7 tools · 57s` out of a `<task-notification>`,
+    each part present only where the notification carries it."""
+    got = {f: int(m.group(1)) for f, r in _USAGE_RE.items() if (m := r.search(text))}
+    parts = [_task_fields(text)["status"]]
+    if "subagent_tokens" in got:
+        parts.append(f"{got['subagent_tokens'] / 1000:.0f}k tokens")
+    if "tool_uses" in got:
+        parts.append(_plural(got["tool_uses"], "tool"))
+    if "duration_ms" in got:
+        parts.append(_fmt_secs(got["duration_ms"] // 1000))
+    return " · ".join(p for p in parts if p)
+
+
+def _points_to_handback(text: str) -> bool:
+    return _task_fields(text)["result"].startswith(_HANDBACK_POINTER)
+
+
+def _fold_stops(rows: list, stops: list[tuple[str, str, str]], agent_of, when_of,
+                note) -> list:
+    """Each stop — (agent, time, note) of a notification that points at a
+    handback — written onto the latest report of that agent at or before its
+    time, through `note(row, text)`. A stop with no such report stays out:
+    the notification carried nothing but the pointer and its usage."""
+    rows = list(rows)
+    for agent, when, text in stops:
+        at = max((i for i, r in enumerate(rows)
+                  if agent_of(r) == agent and when_of(r) <= when), default=None,
+                 key=lambda i: when_of(rows[i]))
+        if at is not None:
+            rows[at] = note(rows[at], text)
+    return rows
+
+
 def _report_text(text: str) -> str:
     """The report out of a `<task-notification>`, clipped. Falls back to the
     one-line summary where the notification carries no result."""
@@ -3325,7 +3544,8 @@ def render_agents(meta: Meta, ref: str, reports: list[_AgentReport],
             out.append("*No report recorded.*\n")
             continue
         for i, rep in enumerate(runs, 1):
-            head = f"`{meta.uuid[:8]}:{rep.line}`  {_hhmmss(rep.when)}"
+            who = f"{meta.uuid[:8]}/{rep.agent[:8]}" if rep.in_sidecar else meta.uuid[:8]
+            head = f"`{who}:{rep.line}`  {_hhmmss(rep.when)}"
             if len(runs) > 1:
                 head = f"**Return {i} of {len(runs)}** — {head}"
             out.append(f"{head}  ·  {rep.status or 'status not recorded'}\n")
@@ -4829,6 +5049,8 @@ def _failed(body: str, is_error: bool) -> bool:
 def _typed_text(rec: dict) -> str:
     """Only the parts you typed. The harness rides `<system-reminder>` blocks in
     the same record as a prompt, and `_record_text` would quote them with it."""
+    if _harness_sent(rec):
+        return ""
     content = (rec.get("message") or {}).get("content")
     if isinstance(content, str):
         texts = [content]

{chsum-3.0.2 → chsum-3.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "chsum"
-version = "3.0.2"
+version = "3.0.3"
 description = "Work logs and reload-ready context from coding-agent conversations. Deterministic: no model, nothing invented."
 readme = "README.md"
 requires-python = ">=3.10"

chsum-3.0.3/tests/test_handbacks.py

@@ -0,0 +1,190 @@
+"""A subagent's report, from the call that returns it to the rows that print it.
+
+A report travels in up to three records: the agent's handback call in its own
+transcript, a peer message in the parent where the harness delivered it as a
+user record, and a task notification whose result points back at the peer
+message. The parent keeps the peer message only for some returns — the rest
+arrive as attachments, which no row reads — so each case below names which copy
+a row is drawn from.
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
+
+from chsum import core  # noqa: E402
+
+AGENT = "a1b2c3d4e5f6a7b8c"
+SPAWN = "toolu_01Spawn"
+PREAMBLE = ("[Subagent hand-back] The text below is the final report of a subagent "
+            "this session delegated to. The report follows:\n")
+
+
+def _user(ts: str, content, **extra) -> dict:
+    return {"type": "user", "timestamp": ts, "message": {"role": "user", "content": content},
+            **extra}
+
+
+def _handback(ts: str, report: str) -> dict:
+    return {"type": "assistant", "timestamp": ts, "message": {"role": "assistant", "content": [
+        {"type": "tool_use", "id": f"toolu_{ts[-6:-1]}", "name": "SubagentHandback",
+         "input": {"message": report}}]}}
+
+
+def _pointer(tokens: int, tools: int, ms: int) -> str:
+    return (f"<task-notification>\n<task-id>{AGENT}</task-id>\n"
+            f"<tool-use-id>{SPAWN}</tool-use-id>\n<status>completed</status>\n"
+            f"<summary>Agent \"review\" finished</summary>\n"
+            f"<result>This agent's report was delivered to you as a message from "
+            f"\"{AGENT}\" (its SubagentHandback call). Read it there; it is not "
+            f"repeated here.\n</result>\n<usage><subagent_tokens>{tokens}</subagent_tokens>"
+            f"<tool_uses>{tools}</tool_uses><duration_ms>{ms}</duration_ms></usage>\n"
+            f"</task-notification>")
+
+
+PARENT = [
+    _user("2026-09-25T04:00:00.000Z", "review the route", origin={"kind": "human"}),
+    {"type": "assistant", "timestamp": "2026-09-25T04:00:01.000Z", "message": {
+        "role": "assistant", "content": [{"type": "tool_use", "id": SPAWN, "name": "Agent",
+                                          "input": {"description": "review"}}]}},
+    _user("2026-09-25T04:00:02.000Z",
+          [{"type": "tool_result", "tool_use_id": SPAWN, "content": "launched"}]),
+    # The first return reached the parent as an attachment: its pointer is left
+    # in the queue record alone, and no peer message holds its report.
+    {"type": "queue-operation", "operation": "enqueue", "timestamp": "2026-09-25T04:02:00.000Z",
+     "content": _pointer(54154, 7, 56677)},
+    _user("2026-09-25T04:03:00.000Z", "thanks", origin={"kind": "human"}),
+    _user("2026-09-25T04:05:00.000Z",
+          f"Another Claude session sent a message:\n<agent-message from=\"{AGENT}\">\n"
+          f"{PREAMBLE}  Second report.\n  - indented once\n</agent-message>",
+          isMeta=True, turnOrigin="peer",
+          origin={"kind": "peer", "from": AGENT, "handback": True,
+                  "body": f"{PREAMBLE}  Second report.\n  - indented once\n"}),
+    _user("2026-09-25T04:05:10.000Z", _pointer(72000, 11, 61000),
+          origin={"kind": "task-notification"}, turnOrigin="task_notification"),
+    _user("2026-09-25T04:05:20.000Z",
+          "The previous response failed to produce a valid tool call. Please retry "
+          "the tool call now.", isMeta=True),
+]
+
+SIDECAR = [
+    _user("2026-09-25T04:00:03.000Z", "Review one route."),
+    _user("2026-09-25T04:00:04.000Z",
+          "<system-reminder>\nYour final report is delivered through SubagentHandback."
+          "\n</system-reminder>", isMeta=True),
+    _handback("2026-09-25T04:01:59.000Z", "First report."),
+    _handback("2026-09-25T04:04:59.000Z", "Second report.\n- indented once"),
+]
+
+
+class Senders(unittest.TestCase):
+    """A message another sender put in an agent's conversation: labelled by its
+    sender, and opening the agent's next turn when the view is scoped to it."""
+
+    def setUp(self) -> None:
+        tmp = tempfile.TemporaryDirectory(prefix="chsum-test-")
+        self.addCleanup(tmp.cleanup)
+        self.path = pathlib.Path(tmp.name) / "sess.jsonl"
+        self.path.write_text(json.dumps(_user("2026-09-25T04:00:00.000Z", "go",
+                                              origin={"kind": "human"})) + "\n")
+        side = self.path.parent / self.path.stem / "subagents" / f"agent-{AGENT}.jsonl"
+        side.parent.mkdir(parents=True)
+        recs = [
+            _user("2026-09-25T04:00:01.000Z", "Research the question."),
+            _user("2026-09-25T04:01:00.000Z",
+                  "Another Claude session sent a message while you were working:\n"
+                  "<agent-message from=\"caller\">\nWrap up now.\n</agent-message>",
+                  isMeta=True, origin={"kind": "peer", "from": "caller",
+                                       "name": "general-purpose", "body": "Wrap up now.\n"}),
+            _user("2026-09-25T04:02:00.000Z",
+                  "The coordinator sent a message while you were working: Change of "
+                  "direction.", isMeta=True, origin={"kind": "coordinator"}),
+            _user("2026-09-25T04:03:00.000Z",
+                  "[SYSTEM NOTIFICATION - NOT USER INPUT]\nThis is an automated event.\n\n"
+                  "<task-notification>\n<task-id>nested01</task-id>\n"
+                  "<tool-use-id>toolu_01Nested</tool-use-id>\n<status>completed</status>\n"
+                  "<result>Nested report.</result>\n</task-notification>",
+                  isMeta=True, origin={"kind": "task-notification"}),
+        ]
+        recs.insert(1, {"type": "assistant", "timestamp": "2026-09-25T04:00:02.000Z",
+                        "message": {"role": "assistant", "content": [
+                            {"type": "tool_use", "id": "toolu_01Nested", "name": "Agent",
+                             "input": {"description": "nested"}}]}})
+        side.write_text("".join(json.dumps(r) + "\n" for r in recs))
+
+    def test_each_sender_is_named_and_opens_the_agents_turn(self):
+        rows = [(r.label, r.text, r.starts_turn)
+                for r in core.collect_rows(self.path, core._ROW_KINDS["messages"], AGENT)
+                if r.kind == "message"]
+        self.assertEqual(rows, [
+            ("user", "Research the question.", True),
+            ("message from general-purpose", "Wrap up now.", True),
+            ("coordinator", "Change of direction.", True),
+            ("agent nested01 returned", "Nested report.", False),
+        ])
+
+
+class Handbacks(unittest.TestCase):
+
+    def setUp(self) -> None:
+        tmp = tempfile.TemporaryDirectory(prefix="chsum-test-")
+        self.addCleanup(tmp.cleanup)
+        self.path = pathlib.Path(tmp.name) / "sess.jsonl"
+        side = self.path.parent / self.path.stem / "subagents" / f"agent-{AGENT}.jsonl"
+        side.parent.mkdir(parents=True)
+        for path, recs in ((self.path, PARENT), (side, SIDECAR)):
+            path.write_text("".join(json.dumps(r) + "\n" for r in recs))
+
+    def rows(self, only_agent: str = "") -> list:
+        return [r for r in core.collect_rows(self.path, core._ROW_KINDS["messages"],
+                                             only_agent)
+                if r.kind == "message"]
+
+    def test_each_report_prints_once_with_its_stop(self):
+        returned = [(r.agent, r.text, r.label) for r in self.rows()
+                    if r.label.startswith("agent ")]
+        self.assertEqual(returned, [
+            (AGENT, "First report.",
+             f"agent {AGENT} returned · completed · 54k tokens · 7 tools · 56s"),
+            ("", "Second report.\n- indented once",
+             f"agent {AGENT} returned · completed · 72k tokens · 11 tools · 1m"),
+        ])
+
+    def test_no_row_carries_harness_text(self):
+        texts = "\n".join(r.text for r in self.rows())
+        for noise in ("system-reminder", "Another Claude session", "delivered to you",
+                      "failed to produce a valid tool call"):
+            self.assertNotIn(noise, texts)
+
+    def test_scoped_to_the_agent_its_own_reports_stay(self):
+        returned = [r.text for r in self.rows(AGENT) if r.label.startswith("agent ")]
+        self.assertEqual(returned, ["First report.", "Second report.\n- indented once"])
+
+    def test_only_typed_prompts_open_a_turn(self):
+        self.assertEqual([r.text for r in self.rows() if r.starts_turn],
+                         ["review the route", "thanks"])
+
+    def test_the_anchor_is_the_last_typed_prompt(self):
+        line, _ = core._last_prompt(self.path)
+        self.assertEqual(line, 5)
+
+    def test_agents_view_lists_every_return_with_its_source(self):
+        got = [(r.result, r.in_sidecar, r.status) for r in core._agent_reports(self.path)]
+        self.assertEqual(got, [
+            ("First report.", True, "completed · 54k tokens · 7 tools · 56s"),
+            ("Second report.\n- indented once", False,
+             "completed · 72k tokens · 11 tools · 1m"),
+        ])
+
+    def test_drill_block_names_each_agent_by_its_whole_ref(self):
+        block = "\n".join(core._drill_block("ch_0123", self.path))
+        self.assertIn(f"- `ch_0123/{AGENT}` — ", block)
+
+
+if __name__ == "__main__":
+    unittest.main()