Expose recorded background task timing and progress metadata
This commit is contained in:
@@ -0,0 +1,54 @@
|
||||
# Recorded background-task metadata
|
||||
|
||||
`ChatShell` now carries optional `started_at`/`updated_at` (epoch milliseconds),
|
||||
`task_type`, `description`, `progress`, `last_tool`, and nullable `duration_ms`,
|
||||
`tool_count`, `token_count`. A missing counter stays absent; an explicitly
|
||||
reported zero is preserved. Duration is backend-reported runtime, distinct from
|
||||
a client clock's elapsed time since a recorded start.
|
||||
|
||||
Sources and limits:
|
||||
|
||||
- Claude's initiating Bash/Agent/Task `tool_use` transcript entry supplies its
|
||||
recorded timestamp and description. A matching live envelope timestamp is used
|
||||
when present. Known running tasks can recover this timing from the durable
|
||||
transcript by tool-use ID, including after detachable-host replay. The host's
|
||||
own creation time and server read/replay wall clock are never task start times.
|
||||
- Claude `task_started` correlates task ID and tool-use ID. `task_progress` and
|
||||
structured completion messages retain reported usage duration, tool/token
|
||||
counts, progress summary, description and last tool. Fields were verified in
|
||||
the official [Agent SDK TypeScript reference](https://code.claude.com/docs/en/agent-sdk/typescript)
|
||||
(`SDKTaskStartedMessage`, `SDKTaskProgressMessage`, `SDKTaskNotificationMessage`).
|
||||
Those SDK events do not require timestamps; absent timestamps stay unknown.
|
||||
- Codex item lifecycle notifications expose `startedAtMs`/`completedAtMs` in the
|
||||
installed App Server schema. These supply recorded command timing. Historical
|
||||
`commandExecution.durationMs` supplies reported runtime; historical ThreadItems
|
||||
have no per-command start, so a readback without an observed start remains
|
||||
unknown. The unrelated thread/turn start is not substituted.
|
||||
- The currently supported OpenCode shell shape has no verified timing fields.
|
||||
Those remain absent. Its shared in-flight snapshot reconciliation preserves
|
||||
metadata rather than dropping it, and counts retained metadata bytes.
|
||||
|
||||
Partial frames and authoritative readback preserve known metadata for the same
|
||||
shell identity; another identity cannot borrow it. Terminal events retain the
|
||||
metadata while removing tasks from the running set. Repeated progress does not
|
||||
reset start times or regress reported counters. Descriptions/progress are capped
|
||||
at 2KiB, task types at 128 bytes and last-tool names at 256 bytes. Existing server
|
||||
replay and readback byte budgets now include these retained strings.
|
||||
|
||||
Claude's optional transcript enrichment uses a serialized scan, a 30-second
|
||||
missing-path lookup backoff, a 5-second scan throttle, and size/mtime/target-set
|
||||
fingerprints (including failed or oversized reads). It streams at most 64MiB with
|
||||
the existing transcript line limit and retains only requested tool-call metadata.
|
||||
Missing, malformed or oversized transcripts do not fail the primary task list.
|
||||
No new source file indexing or background reader is introduced.
|
||||
|
||||
Checks: focused Claude, Codex, protocol, OpenCode and server tests passed; tests
|
||||
cover live metadata, partial/stale frames, explicit zero/absent counters, silent
|
||||
host-style replay, durable transcript timestamps, missing/oversized-source retry,
|
||||
exit state, authoritative removal, source limits and retained byte budgets. No
|
||||
shared services were restarted, no real chats were changed and no TUI code changed.
|
||||
|
||||
Focused race tests also passed for Claude, Codex and protocol. Logs:
|
||||
`/private/tmp/pipelines-background-metadata-checks.log` and
|
||||
`/private/tmp/pipelines-background-metadata-race.log`. Final same-ID blank-command
|
||||
partial-frame assertion passed in protocol/server tests.
|
||||
Reference in New Issue
Block a user