Skip to content

feature: Export a stranded tool call with its measured duration #2046

Open

Description

@mrsabath

Part of #1810. Follow-up to #1906 §2, deferred out of the toolCall record so it does not block the export.

Problem

A tool call can end without a result, and the timeline already handles the case: when an agent finishes a tool and then cannot reach the model to report back — a lid closed, a VPN dropped — endStrandedTools ends the span at the first failed dial to a model host. Its own doc records why the pass exists: one 9-minute Bash drew as 8 hours before it, and the dial it cuts at measured within a fraction of a second of the tool's real end against Claude Code's transcripts.

The pairing package cannot see this case. core/session/toolpair was extracted from buildAgents alone (#2041), and endStrandedTools runs afterwards from Build, needing t.Agents, t.Turns and t.Hosts — none of which the pairing has. So a stranded call matches none of the four reasons toolpair knows (result, background, ended_run, stopped, abandoned).

The spec names the reason (endReason: "stranded", T31) and leaves where the cut runs Open (§2.2).

Why this is not cosmetic

Measured on one 30-day laptop archive: 56 dial-failed tunnel rows and 30 dial_failed errors. Stranding fires on real traffic.

Until this lands, a stranded call exports as abandoned, because lastAsk[agent] is after its start and that branch catches it. An abandoned call carries no duration (T16), so the export silently drops the timing of a call that did finish and was measured accurately.

That biases the part of the data the export exists to answer: a stranded call is disproportionately a long one — a closed laptop lid strands the 9-minute Bash, not the 24 ms Edit. So the undercount lands in the heavy tail, which is what §3.3's duration bands and any sandbox density figure turn on.

Two options

A. Carry the host-failure times into the pairing. toolpair.Calls gains an input — the failed-dial times per host — and decides stranded beside the other four reasons.

  • For: the reason lives where every other reason lives; one place to read when the rules change.
  • Against: changes the pairing's signature and its inputs. The pass is matched by host, not by agent (see below), so the input is not simply "this agent's failures".

B. Apply the stranding cut in the export, over the records it is about to write.

Author leans A, for #2041's reason: a closing case that exists twice drifts. But B is defensible if carrying host state into toolpair turns out to drag Hosts with it.

Three things the implementer needs to know

  1. HasEnd must include stranded. toolpair.EndReason.HasEnd() is result || background today. A stranded call HAS an end, so without this omitempty drops the duration of one that measured 0 ms (spec T16's cross-PR note).
  2. stranded wins over result and background when both apply. The result can arrive hours later once the network is back; buildAgents ends the call on it and the stranding pass then moves End back to the dial. So resultSeq stays present, and durationMs ends at the dial, not at resultSeq — the one case where those two disagree (spec §4.4a).
  3. The cut is matched by host, not by agent, and that bounds what stranded claims. endStrandedTools's documented shortcut: is that a blip in any other agent — a parent included — ends a tool whose own branch had no success first, so a subagent's long Bash can be cut where the main agent retried. Two agents stranded by one outage both end at its first failure. The upstream note says to revisit if CONNECTs come to carry the agent id.

Also worth fixing with it

timeline.Tool has no field for this: a stranded span is neither lost nor open, so a consumer filtering both still totals an outage-adjacent span as ordinary tool time. docs/session-export.md warns about it in prose (#2009), but exposing endReason on the span would make it checkable. That needs a timeline.Tool JSON change and an agentop story, so it is a separate decision — noted here so the two are not solved twice.

Where it lives

  • core/session/toolpair — the reason, and whichever input option A needs
  • core/session/timeline/timeline.go — endStrandedTools, and lostFor in agents.go
  • core/sessionexport — the record's endReason, if option B
  • docs/superpowers/specs/2026-11-19-tool-call-export-record-design.md — §2.2's Open item, T16, T31

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

Activity

  1. added
    enhancementNew feature or request
    laptopThe local (laptop) tool: install, abctl, the numbers
    on Nov 21, 2026
  2. webchang commented on Nov 21, 2026

    @webchang
    Member

    From the consumer side: our trajectory format (rossoctl/trajectory-schema v2.2) and its converter for the toolCall export already take this case as specified in #2009.

    • endReason: "stranded" maps to an end reason stranded that requires a duration. Its durationMs and its resultSeq (when a result arrived later) are kept as given, and the end reason is never inferred from resultSeq.
    • backgrounded (T32a) maps to its own flag, so a call that is both stranded and backgrounded keeps both facts.

    That makes item 1 a hard requirement for us, not just a nicety. We tested a stranded record whose durationMs was omitted: it converts to a file our validator rejects, because a stranded call must carry its duration. So please make HasEnd include stranded before the export writes it. Until then, the interim abandoned (with no duration) converts cleanly.

  3. webchang commented on Nov 21, 2026

    @webchang
    Member

    A small update to my previous comment: our converter now (trajectory-schema v2.2.1) handles a stranded record without durationMs gracefully. It reports the record and writes the call without the end reason, so the output stays valid instead of being rejected. Item 1 still matters as much as before, though: without HasEnd including stranded, both the reason and the measured duration of such a call would be lost on our side.

  4. webchang commented on Nov 21, 2026

    @webchang
    Member

    @mrsabath, a short summary of our two comments above, for when you pick this up:

    Our trajectory format and its converter for the toolCall export already support this case, as #2009 specifies it. A stranded call keeps its measured durationMs, and its resultSeq if a result arrives later. The end reason is never inferred from resultSeq. The backgrounded flag (T32a) is kept separately, so a call that is both stranded and backgrounded keeps both facts.

    Item 1 in this issue is the part that matters most to us: HasEnd must include stranded. If it doesn't, the zero-omission rule drops a measured 0 ms duration. When we tested a stranded record without durationMs, our converter could no longer keep the call's reason or its duration. It now reports the record and writes the call without the reason, so the output stays valid, but the facts are lost. Until this lands, the interim export as "abandoned" (with no duration) converts cleanly on our side.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestlaptopThe local (laptop) tool: install, abctl, the numbers

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions