Expose recorded background task timing and progress metadata

This commit is contained in:
2026-11-06 15:08:34 +00:00
parent c9a4cd0bf6
commit 6421554bfe
16 changed files with 688 additions and 31 deletions
+54
View File
@@ -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.
+1
View File
@@ -634,6 +634,7 @@ func (c *Chat) Shells(ctx context.Context, id string) ([]protocol.ChatShell, err
return []protocol.ChatShell{}, nil
}
s.awaitReady(ctx)
s.enrichShellStarts()
s.mu.Lock()
defer s.mu.Unlock()
result := []protocol.ChatShell{}
+12 -5
View File
@@ -316,11 +316,18 @@ type session struct {
// shown once in the next turn.
envNotices []string
subs map[chan protocol.ChatEventFrame]struct{}
approvals map[string]*pendingApproval
forms map[string]*pendingForm
shells map[string]*shellSnapshot
shellOrder []string
subs map[chan protocol.ChatEventFrame]struct{}
approvals map[string]*pendingApproval
forms map[string]*pendingForm
shells map[string]*shellSnapshot
shellOrder []string
shellMetadataMu sync.Mutex
shellLookupAfter time.Time
shellScanAfter time.Time
shellTranscriptPath string
shellTranscriptSize int64
shellTranscriptMtime int64
shellTranscriptTargets map[string]bool
usage *protocol.ChatEventFrame
compaction *protocol.ChatEventFrame
+225
View File
@@ -0,0 +1,225 @@
package claude
import (
"bufio"
"encoding/json"
"errors"
"io"
"os"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
func applyToolMetadata(shell *protocol.ChatShell, name string, input json.RawMessage, timestamp string) {
if shell.StartedAt == 0 {
if stamp, ok := transcriptTime(timestamp); ok && stamp > 0 {
shell.StartedAt = stamp
}
}
if shell.TaskType == "" {
if name == "Bash" {
shell.TaskType = "shell"
} else {
shell.TaskType = "agent"
}
}
var fields struct {
Description string `json:"description"`
}
if json.Unmarshal(input, &fields) == nil && fields.Description != "" && shell.Description == "" {
shell.Description = boundedText(fields.Description, 2048)
}
}
// SDK task events identify the initiating tool use, then task_id correlates
// progress messages which omit tool_use_id. They do not all carry a timestamp.
// Missing event times stay absent: replay wall time is not task creation time.
func (s *session) handleTaskMetadata(raw []byte) {
var event struct {
TaskID string `json:"task_id"`
ToolUseID string `json:"tool_use_id"`
TaskType string `json:"task_type"`
Description string `json:"description"`
Summary string `json:"summary"`
LastTool string `json:"last_tool_name"`
Timestamp string `json:"timestamp"`
Usage struct {
DurationMS *int64 `json:"duration_ms"`
Tools *int64 `json:"tool_uses"`
Tokens *int64 `json:"total_tokens"`
} `json:"usage"`
}
if json.Unmarshal(raw, &event) != nil {
return
}
s.mu.Lock()
snapshot := s.shells[event.ToolUseID]
if snapshot == nil && event.TaskID != "" {
for _, candidate := range s.shells {
if candidate.taskID == event.TaskID {
snapshot = candidate
break
}
}
}
if snapshot == nil {
s.mu.Unlock()
return
}
if event.TaskID != "" {
snapshot.taskID = event.TaskID
}
// Out-of-order readback/progress must not replace newer recorded progress.
if event.Usage.DurationMS != nil && snapshot.shell.DurationMS != nil && *event.Usage.DurationMS < *snapshot.shell.DurationMS {
s.mu.Unlock()
return
}
shell := &snapshot.shell
if event.TaskType != "" {
shell.TaskType = boundedText(event.TaskType, 128)
}
if event.Description != "" {
shell.Description = boundedText(event.Description, 2048)
}
if event.Summary != "" {
shell.Progress = boundedText(event.Summary, 2048)
}
if event.LastTool != "" {
shell.LastTool = boundedText(event.LastTool, 256)
}
if stamp, ok := transcriptTime(event.Timestamp); ok && stamp > shell.UpdatedAt {
shell.UpdatedAt = stamp
}
keepCounter := func(target **int64, value *int64) {
if value != nil && *value >= 0 && (*target == nil || *value >= **target) {
copy := *value
*target = &copy
}
}
keepCounter(&shell.DurationMS, event.Usage.DurationMS)
keepCounter(&shell.ToolCount, event.Usage.Tools)
keepCounter(&shell.TokenCount, event.Usage.Tokens)
copy := *shell
s.mu.Unlock()
s.emit(protocol.ChatEventFrame{SessionID: s.id, Kind: protocol.ChatEventShell, Shell: &copy})
}
// The durable transcript records the timestamp of each initiating tool call.
// Enrich known tasks only; historical tool calls do not establish membership.
// The size/mtime key avoids repeatedly scanning an unchanged transcript when
// an older task has no recorded initiating message. Reads keep the existing
// transcript byte/line limits and never fail the primary task-list request.
func (s *session) enrichShellStarts() {
// A separate lock serializes optional metadata IO without holding the chat
// state lock. The clock below schedules retries only, never a task timestamp.
s.shellMetadataMu.Lock()
defer s.shellMetadataMu.Unlock()
s.mu.Lock()
wanted := map[string]bool{}
for id, snapshot := range s.shells {
if snapshot.shell.Status == protocol.ChatShellRunning && snapshot.shell.StartedAt == 0 {
wanted[id] = true
}
}
s.mu.Unlock()
if len(wanted) == 0 {
return
}
now := time.Now()
if now.Before(s.shellScanAfter) {
return
}
s.shellScanAfter = now.Add(5 * time.Second)
path := s.shellTranscriptPath
if path == "" {
if now.Before(s.shellLookupAfter) {
return
}
s.shellLookupAfter = now.Add(30 * time.Second)
path = findTranscriptFile(s.id)
if path == "" {
return
}
s.shellTranscriptPath = path
}
info, err := os.Stat(path)
if err != nil {
if !now.Before(s.shellLookupAfter) {
s.shellTranscriptPath = ""
}
return
}
covered := true
for id := range wanted {
if !s.shellTranscriptTargets[id] {
covered = false
break
}
}
if covered && s.shellTranscriptSize == info.Size() && s.shellTranscriptMtime == info.ModTime().UnixNano() {
return
}
// Cache failures too: an oversized/malformed unchanged file is not scanned
// again on every list refresh. A changed file gets another bounded attempt.
s.shellTranscriptSize, s.shellTranscriptMtime = info.Size(), info.ModTime().UnixNano()
s.shellTranscriptTargets = wanted
if info.Size() > maxTranscriptBytes {
return
}
records, err := readShellStartRecords(path, wanted)
if err != nil {
return
}
s.mu.Lock()
defer s.mu.Unlock()
for id, record := range records {
if snapshot := s.shells[id]; snapshot != nil {
applyToolMetadata(&snapshot.shell, record.name, record.input, record.timestamp)
}
}
}
type shellStartRecord struct {
name string
input json.RawMessage
timestamp string
}
// Retain only the targeted tool-call metadata, not an entire conversation.
func readShellStartRecords(path string, wanted map[string]bool) (map[string]shellStartRecord, error) {
file, err := os.Open(path)
if err != nil {
return nil, err
}
defer file.Close()
bounded := &io.LimitedReader{R: file, N: maxTranscriptBytes + 1}
scanner := bufio.NewScanner(bounded)
scanner.Buffer(make([]byte, 0, 64<<10), maxLineBytes)
records := map[string]shellStartRecord{}
for scanner.Scan() {
var entry transcriptEntry
if json.Unmarshal(scanner.Bytes(), &entry) != nil || entry.Type != "assistant" || entry.IsSidechain {
continue
}
for _, block := range decodeBlocks(entry.Message.Content) {
if block.Type != "tool_use" || !wanted[block.ID] {
continue
}
if _, seen := records[block.ID]; seen {
continue
}
if stamp, ok := transcriptTime(entry.Timestamp); !ok || stamp <= 0 {
continue
}
records[block.ID] = shellStartRecord{name: block.Name, input: truncateJSON(block.Input, 64<<10), timestamp: entry.Timestamp}
}
}
if err := scanner.Err(); err != nil {
return nil, err
}
if bounded.N <= 0 {
return nil, errors.New("Claude task transcript exceeded read limit")
}
return records, nil
}
+136
View File
@@ -0,0 +1,136 @@
package claude
import (
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
func TestTaskProgressPreservesRecordedMetadataAndExit(t *testing.T) {
chat, s := backgroundSession(t)
source := toolUse(t, "toolu_meta", "Agent", map[string]any{"description": "Review release", "run_in_background": true})
var start map[string]any
json.Unmarshal(source, &start)
start["timestamp"] = "2026-11-05T09:18:00Z"
s.handleLine(nil, line(t, start))
s.handleLine(nil, line(t, map[string]any{"type": "system", "subtype": "task_started", "task_id": "task-meta", "tool_use_id": "toolu_meta", "task_type": "local_agent", "description": "Review release"}))
progress := map[string]any{"type": "system", "subtype": "task_progress", "task_id": "task-meta", "description": "Reviewing changes", "summary": "Checking focused tests", "last_tool_name": "Bash", "timestamp": "2026-11-05T09:20:00Z", "usage": map[string]any{"duration_ms": 120000, "tool_uses": 4, "total_tokens": 1500}}
s.handleLine(nil, line(t, progress))
tasks := running(t, chat)
if len(tasks) != 1 {
t.Fatalf("tasks=%+v", tasks)
}
task := tasks[0]
if task.StartedAt != 1793870280000 || task.UpdatedAt != 1793870400000 || task.TaskType != "local_agent" || task.Description != "Reviewing changes" || task.Progress != "Checking focused tests" || task.LastTool != "Bash" || *task.ToolCount != 4 || *task.TokenCount != 1500 || *task.DurationMS != 120000 {
t.Fatalf("metadata=%+v", task)
}
// A duplicate initiating message must not reset the progress snapshot.
s.handleLine(nil, line(t, start))
progress["usage"] = map[string]any{"duration_ms": 1000, "tool_uses": 1, "total_tokens": 1}
progress["summary"] = "stale"
s.handleLine(nil, line(t, progress))
task = running(t, chat)[0]
if task.StartedAt != 1793870280000 || task.Progress != "Checking focused tests" || *task.ToolCount != 4 || task.TaskType != "local_agent" || task.Description != "Reviewing changes" {
t.Fatalf("regressed metadata=%+v", task)
}
s.handleLine(nil, line(t, map[string]any{"type": "system", "subtype": "task_notification", "tool_use_id": "toolu_meta", "status": "completed", "summary": "Review complete", "usage": map[string]any{"duration_ms": 180000, "tool_uses": 5, "total_tokens": 2000}}))
if len(running(t, chat)) != 0 {
t.Fatal("task did not exit")
}
s.mu.Lock()
ended := s.shells["toolu_meta"].shell
s.mu.Unlock()
if ended.Status != protocol.ChatShellExited || ended.StartedAt != task.StartedAt || *ended.DurationMS != 180000 || ended.Progress != "Review complete" {
t.Fatalf("ended=%+v", ended)
}
}
func TestTaskStartRecoveredFromTranscriptAcrossReplay(t *testing.T) {
config := t.TempDir()
t.Setenv("CLAUDE_CONFIG_DIR", config)
dir := filepath.Join(config, "projects", "fixture")
if err := os.MkdirAll(dir, 0700); err != nil {
t.Fatal(err)
}
source := toolUse(t, "toolu_replay", "Bash", map[string]any{"command": "sleep 30", "run_in_background": true})
var entry map[string]any
json.Unmarshal(source, &entry)
entry["timestamp"] = "2026-11-05T09:18:00Z"
raw := line(t, entry)
if err := os.WriteFile(filepath.Join(dir, "ses_bg.jsonl"), append(raw, '\n'), 0600); err != nil {
t.Fatal(err)
}
for range 2 {
chat, s := backgroundSession(t)
s.silent = true // Reattached hosts reconstruct from the same original lines.
s.handleLine(nil, source) // CLI stream itself has no timestamp.
task := running(t, chat)[0]
if task.StartedAt != 1793870280000 || task.TaskType != "shell" {
t.Fatalf("transcript start=%+v", task)
}
again := running(t, chat)[0]
if task.StartedAt != again.StartedAt {
t.Fatal("read reset start")
}
}
}
func TestMissingTaskTimingAndInvalidCountersStayUnknown(t *testing.T) {
chat, s := backgroundSession(t)
s.handleLine(nil, toolUse(t, "toolu_unknown", "Agent", map[string]any{"description": "Unknown timing"}))
s.handleLine(nil, line(t, map[string]any{"type": "system", "subtype": "task_progress", "tool_use_id": "toolu_unknown", "timestamp": "invalid", "summary": strings.Repeat("p", 4000), "usage": map[string]any{"duration_ms": -1, "tool_uses": -2, "total_tokens": -3}}))
task := running(t, chat)[0]
if task.StartedAt != 0 || task.UpdatedAt != 0 || task.DurationMS != nil || task.ToolCount != nil || task.TokenCount != nil || len(task.Progress) > 2100 {
t.Fatalf("invented/unbounded metadata=%+v", task)
}
}
func TestOptionalTranscriptLookupBacksOffAndCachesOversizedFiles(t *testing.T) {
config := t.TempDir()
t.Setenv("CLAUDE_CONFIG_DIR", config)
chat, s := backgroundSession(t)
s.handleLine(nil, toolUse(t, "toolu_cache", "Bash", map[string]any{"command": "sleep 30", "run_in_background": true}))
if task := running(t, chat)[0]; task.StartedAt != 0 {
t.Fatal("invented missing transcript time")
}
if s.shellLookupAfter.IsZero() || s.shellScanAfter.IsZero() {
t.Fatal("missing lookup has no retry backoff")
}
dir := filepath.Join(config, "projects", "fixture")
if err := os.MkdirAll(dir, 0700); err != nil {
t.Fatal(err)
}
path := filepath.Join(dir, "ses_bg.jsonl")
f, err := os.Create(path)
if err != nil {
t.Fatal(err)
}
if err = f.Truncate(maxTranscriptBytes + 1); err != nil {
t.Fatal(err)
}
f.Close()
s.shellLookupAfter = time.Time{}
s.shellScanAfter = time.Time{}
running(t, chat)
if s.shellTranscriptSize != maxTranscriptBytes+1 || s.shellTranscriptMtime == 0 {
t.Fatal("oversized read did not cache fingerprint")
}
// A repaired/changed source is read on the next retry; a prior failure is
// neither a fabricated start nor a permanent inability to enrich the task.
raw := toolUse(t, "toolu_cache", "Bash", map[string]any{"command": "sleep 30"})
var entry map[string]any
json.Unmarshal(raw, &entry)
entry["timestamp"] = "2026-11-05T09:18:00Z"
if err := os.WriteFile(path, append(line(t, entry), '\n'), 0600); err != nil {
t.Fatal(err)
}
s.shellScanAfter = time.Time{}
if task := running(t, chat)[0]; task.StartedAt != 1793870280000 {
t.Fatalf("repaired source not read: %+v", task)
}
}
+24 -3
View File
@@ -18,6 +18,7 @@ import (
// ---- CLI line envelope -----------------------------------------------------
type lineEnvelope struct {
Timestamp string `json:"timestamp"`
Type string `json:"type"`
Subtype string `json:"subtype"`
UUID string `json:"uuid"`
@@ -120,6 +121,10 @@ func (s *session) handleLine(p *process, line []byte) {
case "rate_limit_event":
s.handleRateLimit(envelope.RateLimitInfo)
case "system":
if envelope.Subtype == "task_started" || envelope.Subtype == "task_progress" {
s.handleTaskMetadata(line)
return
}
if envelope.Subtype == "task_notification" {
s.finishNotifiedTask(line)
return
@@ -464,6 +469,10 @@ func (s *session) handleAssistant(envelope lineEnvelope) {
}
}
if shell != nil {
snapshot := s.shells[block.ID]
applyToolMetadata(&snapshot.shell, block.Name, input, envelope.Timestamp)
copy := snapshot.shell
shell = &copy
frames = append(frames, protocol.ChatEventFrame{SessionID: s.id, Kind: protocol.ChatEventShell, Shell: shell})
}
}
@@ -556,7 +565,8 @@ func (s *session) handleUser(envelope lineEnvelope) {
snapshot.output = snapshot.output[:commandOutputCap]
}
}
frame = &protocol.ChatShell{ID: snapshot.shell.ID, Status: snapshot.shell.Status, Command: snapshot.shell.Command, Exit: snapshot.shell.Exit}
copy := snapshot.shell
frame = &copy
}
s.mu.Unlock()
if frame != nil {
@@ -738,6 +748,7 @@ type shellSnapshot struct {
// background marks a command or subagent that may outlive its tool call:
// its immediate result only says it started.
background bool
taskID string
}
// backgroundRequested reports a Bash call asked to run in the background.
@@ -782,6 +793,7 @@ var (
// finishNotifiedTask handles the SDK's structured completion message for a
// background task, the counterpart of the <task-notification> text.
func (s *session) finishNotifiedTask(line []byte) {
s.handleTaskMetadata(line)
var notice struct {
ToolUseID string `json:"tool_use_id"`
Status string `json:"status"`
@@ -807,7 +819,8 @@ func (s *session) endShellsLocked() []*protocol.ChatShell {
continue
}
snapshot.shell.Status = protocol.ChatShellExited
ended = append(ended, &protocol.ChatShell{ID: snapshot.shell.ID, Status: snapshot.shell.Status, Command: snapshot.shell.Command})
copy := snapshot.shell
ended = append(ended, &copy)
}
sort.Slice(ended, func(i, j int) bool { return ended[i].ID < ended[j].ID })
return ended
@@ -840,7 +853,8 @@ func (s *session) finishBackgroundTasks(text string) {
snapshot.size = int64(len(snapshot.output))
}
}
frames = append(frames, &protocol.ChatShell{ID: snapshot.shell.ID, Status: snapshot.shell.Status, Command: snapshot.shell.Command, Exit: snapshot.shell.Exit})
copy := snapshot.shell
frames = append(frames, &copy)
}
s.mu.Unlock()
for _, frame := range frames {
@@ -859,6 +873,13 @@ func (s *session) recordShellLocked(toolID, command string) *protocol.ChatShell
if toolID == "" {
return nil
}
if prior := s.shells[toolID]; prior != nil {
if command != "" {
prior.shell.Command = command
}
copy := prior.shell
return &copy
}
id := shellID(toolID)
s.shellOrder = append(s.shellOrder, id)
shell := protocol.ChatShell{ID: id, Status: protocol.ChatShellRunning, Command: command}
+17 -8
View File
@@ -818,12 +818,14 @@ func (c *Chat) handleNotification(msg rpcMessage) {
return
}
var params struct {
ThreadID string `json:"threadId"`
TurnID string `json:"turnId"`
ItemID string `json:"itemId"`
Delta string `json:"delta"`
Item json.RawMessage `json:"item"`
Turn struct {
StartedAtMS int64 `json:"startedAtMs"`
CompletedAtMS int64 `json:"completedAtMs"`
ThreadID string `json:"threadId"`
TurnID string `json:"turnId"`
ItemID string `json:"itemId"`
Delta string `json:"delta"`
Item json.RawMessage `json:"item"`
Turn struct {
ID string `json:"id"`
Status string `json:"status"`
} `json:"turn"`
@@ -861,9 +863,9 @@ func (c *Chat) handleNotification(msg rpcMessage) {
c.mu.Unlock()
c.emit(stepFrame(params.ThreadID, protocol.ChatStepEnded, completedID))
case "item/started":
c.handleItem(params.ThreadID, params.ItemID, params.Item, false, params.TurnID)
c.handleTimedItem(params.ThreadID, params.ItemID, params.Item, false, params.StartedAtMS, 0, params.TurnID)
case "item/completed":
c.handleItem(params.ThreadID, params.ItemID, params.Item, true, params.TurnID)
c.handleTimedItem(params.ThreadID, params.ItemID, params.Item, true, 0, params.CompletedAtMS, params.TurnID)
case "thread/compacted":
// Deprecated ContextCompactedNotification has only threadId/turnId.
// Modern item lifecycles are correlated more precisely; never let this
@@ -890,6 +892,10 @@ func (c *Chat) handleNotification(msg rpcMessage) {
}
func (c *Chat) handleItem(threadID, itemID string, raw json.RawMessage, completed bool, nativeTurnID ...string) {
c.handleTimedItem(threadID, itemID, raw, completed, 0, 0, nativeTurnID...)
}
func (c *Chat) handleTimedItem(threadID, itemID string, raw json.RawMessage, completed bool, startedAt, completedAt int64, nativeTurnID ...string) {
var record item
if err := json.Unmarshal(raw, &record); err != nil {
return
@@ -897,6 +903,7 @@ func (c *Chat) handleItem(threadID, itemID string, raw json.RawMessage, complete
if record.ID == "" {
record.ID = itemID
}
record.startedAtMS, record.completedAtMS = startedAt, completedAt
switch record.Type {
case "contextCompaction":
if record.ID == "" {
@@ -994,6 +1001,8 @@ func (t turn) createdAtMillis() int64 {
}
type item struct {
startedAtMS int64
completedAtMS int64
Raw json.RawMessage `json:"-"`
ID string `json:"id"`
ClientID string `json:"clientId"`
+38
View File
@@ -0,0 +1,38 @@
package codex
import (
"encoding/json"
"testing"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
func TestCommandLifecycleUsesRecordedTimingAndKeepsItAcrossReadback(t *testing.T) {
c := &Chat{subs: map[string]map[chan protocol.ChatEventFrame]struct{}{}}
c.handleNotification(rpcMessage{Method: "item/started", Params: json.RawMessage(`{"threadId":"thread","turnId":"turn","startedAtMs":1793870280123,"item":{"id":"cmd","type":"commandExecution","command":"sleep 30","status":"inProgress"}}`)})
c.recordCommand("thread", item{ID: "cmd", Command: "sleep 30", Status: "inProgress"}, false)
id := codexShellID("thread", "cmd")
c.mu.Lock()
task := c.commands["thread"][id].shell
c.mu.Unlock()
if task.StartedAt != 1793870280123 || task.TaskType != "command" || task.UpdatedAt != 0 {
t.Fatalf("start=%+v", task)
}
c.handleNotification(rpcMessage{Method: "item/completed", Params: json.RawMessage(`{"threadId":"thread","turnId":"turn","completedAtMs":1793870310123,"item":{"id":"cmd","type":"commandExecution","command":"sleep 30","status":"completed","durationMs":30000}}`)})
c.mu.Lock()
task = c.commands["thread"][id].shell
c.mu.Unlock()
if task.StartedAt != 1793870280123 || task.UpdatedAt != 1793870310123 || task.DurationMS == nil || *task.DurationMS != 30000 || task.Status != protocol.ChatShellExited {
t.Fatalf("completion=%+v", task)
}
}
func TestHistoricalCommandDoesNotInventAStart(t *testing.T) {
c := &Chat{}
duration := int64(1200)
c.recordCommand("thread", item{ID: "cmd", Status: "inProgress", DurationMS: &duration}, false)
task := c.commands["thread"][codexShellID("thread", "cmd")].shell
if task.StartedAt != 0 || task.UpdatedAt != 0 || task.DurationMS == nil || *task.DurationMS != 1200 {
t.Fatalf("history=%+v", task)
}
}
+13 -1
View File
@@ -51,7 +51,19 @@ func (c *Chat) recordCommand(thread string, i item, emit bool) {
status = protocol.ChatShellRunning
}
snapshot := old
snapshot.shell = protocol.ChatShell{ID: id, Command: i.Command, Status: status, Exit: i.ExitCode}
snapshot.shell.ID, snapshot.shell.Status = id, status
snapshot.shell.Command, snapshot.shell.Exit = i.Command, i.ExitCode
snapshot.shell.TaskType = "command"
if i.startedAtMS > 0 && i.startedAtMS <= 8640000000000000 && snapshot.shell.StartedAt == 0 {
snapshot.shell.StartedAt = i.startedAtMS
}
if i.completedAtMS > snapshot.shell.UpdatedAt && i.completedAtMS <= 8640000000000000 {
snapshot.shell.UpdatedAt = i.completedAtMS
}
if i.DurationMS != nil && *i.DurationMS >= 0 && (snapshot.shell.DurationMS == nil || *i.DurationMS >= *snapshot.shell.DurationMS) {
duration := *i.DurationMS
snapshot.shell.DurationMS = &duration
}
if snapshot.shell.Command == "" {
snapshot.shell.Command = old.shell.Command
}
+4 -2
View File
@@ -26,7 +26,9 @@ func (s *ShellSnapshot) Record(shell *protocol.ChatShell) {
s.changes = make(map[string]protocol.ChatShell)
}
old := s.changes[shell.ID]
n := s.bytes - len(old.ID) - len(old.Command) + len(shell.ID) + len(shell.Command)
merged := protocol.PreserveChatShellMetadata(*shell, old)
shell = &merged
n := s.bytes - len(old.ID) - protocol.ChatShellRetainedBytes(old) + len(shell.ID) + protocol.ChatShellRetainedBytes(*shell)
if n > MaxResponse || (old.ID == "" && len(s.changes) >= chatShellIdentityLimit) {
s.overflow = true
return
@@ -51,7 +53,7 @@ func (s *ShellSnapshot) Merge(shells []protocol.ChatShell) ([]protocol.ChatShell
}
for id, shell := range s.changes {
if shell.Status == protocol.ChatShellRunning {
byID[id] = shell
byID[id] = protocol.PreserveChatShellMetadata(shell, byID[id])
} else {
delete(byID, id)
}
+15 -4
View File
@@ -835,11 +835,22 @@ type ChatAnswerRequest struct {
Answers map[string]any `json:"answers"`
}
// ChatShell carries only backend-recorded facts. Timing is epoch milliseconds;
// absent optional values mean unknown, never the time the list was read.
type ChatShell struct {
ID string `json:"id"`
Status string `json:"status,omitempty"`
Command string `json:"command,omitempty"`
Exit *int `json:"exit,omitempty"`
ID string `json:"id"`
Status string `json:"status,omitempty"`
Command string `json:"command,omitempty"`
Exit *int `json:"exit,omitempty"`
StartedAt int64 `json:"started_at,omitempty"`
UpdatedAt int64 `json:"updated_at,omitempty"`
TaskType string `json:"task_type,omitempty"`
Description string `json:"description,omitempty"`
Progress string `json:"progress,omitempty"`
LastTool string `json:"last_tool,omitempty"`
DurationMS *int64 `json:"duration_ms,omitempty"`
ToolCount *int64 `json:"tool_count,omitempty"`
TokenCount *int64 `json:"token_count,omitempty"`
}
// ChatShellOutputQuery names one selected shell and a bounded absolute-byte
+47
View File
@@ -0,0 +1,47 @@
package protocol
// PreserveChatShellMetadata carries recorded facts through partial lifecycle
// frames/readback. It never fills unknown times from a clock. Shell identities
// must match; different tasks cannot lend one another metadata.
func PreserveChatShellMetadata(shell, prior ChatShell) ChatShell {
if shell.ID == "" || shell.ID != prior.ID {
return shell
}
if shell.Command == "" {
shell.Command = prior.Command
}
if shell.StartedAt <= 0 {
shell.StartedAt = prior.StartedAt
}
if shell.UpdatedAt < prior.UpdatedAt {
shell.UpdatedAt = prior.UpdatedAt
}
if shell.TaskType == "" {
shell.TaskType = prior.TaskType
}
if shell.Description == "" {
shell.Description = prior.Description
}
if shell.Progress == "" {
shell.Progress = prior.Progress
}
if shell.LastTool == "" {
shell.LastTool = prior.LastTool
}
keepCounter := func(next, old *int64) *int64 {
if next == nil || *next < 0 || (old != nil && *next < *old) {
return old
}
return next
}
shell.DurationMS = keepCounter(shell.DurationMS, prior.DurationMS)
shell.ToolCount = keepCounter(shell.ToolCount, prior.ToolCount)
shell.TokenCount = keepCounter(shell.TokenCount, prior.TokenCount)
return shell
}
// ChatShellRetainedBytes counts the retained strings (not output pages) used by
// the server and in-flight readback byte budgets.
func ChatShellRetainedBytes(shell ChatShell) int {
return len(shell.Command) + len(shell.TaskType) + len(shell.Description) + len(shell.Progress) + len(shell.LastTool)
}
@@ -0,0 +1,34 @@
package protocol
import (
"encoding/json"
"testing"
)
func TestShellMetadataPartialFrameAndExplicitZero(t *testing.T) {
zero := int64(0)
tools := int64(4)
prior := ChatShell{ID: "task", Command: "sleep 30", StartedAt: 1793870280000, UpdatedAt: 1793870400000, Description: "Review", Progress: "Checking", TaskType: "agent", LastTool: "Bash", ToolCount: &tools, TokenCount: &zero}
current := PreserveChatShellMetadata(ChatShell{ID: "task", Status: ChatShellRunning}, prior)
if current.Command != "sleep 30" || current.StartedAt != prior.StartedAt || current.Description != "Review" || current.ToolCount == nil || *current.ToolCount != 4 || current.TokenCount == nil || *current.TokenCount != 0 {
t.Fatalf("metadata lost: %+v", current)
}
raw, err := json.Marshal(current)
if err != nil {
t.Fatal(err)
}
var wire map[string]any
if err = json.Unmarshal(raw, &wire); err != nil {
t.Fatal(err)
}
if value, exists := wire["token_count"]; !exists || value != float64(0) {
t.Fatalf("zero counter disappeared: %s", raw)
}
if _, exists := wire["duration_ms"]; exists {
t.Fatal("unknown duration was invented")
}
foreign := PreserveChatShellMetadata(ChatShell{ID: "foreign"}, prior)
if foreign.StartedAt != 0 || foreign.Description != "" {
t.Fatal("foreign metadata leaked")
}
}
+13 -6
View File
@@ -377,16 +377,23 @@ func (t *chatTurn) applyShell(shell *protocol.ChatShell) {
}
t.shellOrder = removeShellID(t.shellOrder, shell.ID)
delete(t.shells, shell.ID)
t.shrink(len(old.Command))
t.shrink(protocol.ChatShellRetainedBytes(old))
return
}
if t.shells == nil {
t.shells = map[string]protocol.ChatShell{}
}
if _, ok := t.shells[shell.ID]; !ok {
if !t.retain(len(shell.Command)) {
return
}
old, exists := t.shells[shell.ID]
merged := protocol.PreserveChatShellMetadata(*shell, old)
shell = &merged
delta := protocol.ChatShellRetainedBytes(*shell) - protocol.ChatShellRetainedBytes(old)
if delta > 0 && !t.retain(delta) {
return
}
if delta < 0 {
t.shrink(-delta)
}
if !exists {
t.shellOrder = append(t.shellOrder, shell.ID)
}
t.shells[shell.ID] = *shell
@@ -395,7 +402,7 @@ func (t *chatTurn) applyShell(shell *protocol.ChatShell) {
t.shellOrder = t.shellOrder[1:]
if dropped, ok := t.shells[id]; ok {
delete(t.shells, id)
t.shrink(len(dropped.Command))
t.shrink(protocol.ChatShellRetainedBytes(dropped))
}
}
}
+4 -2
View File
@@ -561,13 +561,15 @@ func (h *chatHub) replaceShells(sessionID string, shells []protocol.ChatShell) {
func (h *chatHub) replaceShellsLocked(sessionID string, shells []protocol.ChatShell) {
turn := h.turnLocked(sessionID)
prior := turn.shells
for _, shell := range turn.shells {
turn.shrink(len(shell.Command))
turn.shrink(protocol.ChatShellRetainedBytes(shell))
}
turn.shells = nil
turn.shellOrder = nil
for i := range shells {
turn.applyShell(&shells[i])
merged := protocol.PreserveChatShellMetadata(shells[i], prior[shells[i].ID])
turn.applyShell(&merged)
}
h.noteActivityLocked(sessionID)
}
@@ -0,0 +1,51 @@
package server
import (
"strings"
"testing"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
func TestShellMetadataSurvivesPartialReplayAndUsesByteBudget(t *testing.T) {
turn := &chatTurn{}
task := protocol.ChatShell{ID: "task", Status: protocol.ChatShellRunning, Command: "sleep 30", StartedAt: 1793870280000, Description: "Review release", Progress: "Checking tests"}
turn.applyShell(&task)
size := protocol.ChatShellRetainedBytes(task)
if turn.size != size {
t.Fatalf("metadata not counted: size=%d want=%d", turn.size, size)
}
turn.applyShell(&protocol.ChatShell{ID: "task", Status: protocol.ChatShellRunning})
if turn.shells["task"].Command != "sleep 30" || turn.shells["task"].StartedAt != task.StartedAt || turn.shells["task"].Progress != "Checking tests" || turn.size != size {
t.Fatal("partial frame lost metadata/budget")
}
turn.applyShell(&protocol.ChatShell{ID: "task", Status: protocol.ChatShellRunning, Command: "sleep 30", Description: strings.Repeat("x", chatRetainedLimit)})
if !turn.overflow || turn.size != size {
t.Fatal("metadata bypassed byte cap")
}
turn.applyShell(&protocol.ChatShell{ID: "task", Status: protocol.ChatShellExited})
if turn.size != 0 || len(turn.shells) != 0 {
t.Fatal("exit did not release metadata budget")
}
}
func TestAuthoritativeShellReadbackPreservesKnownTiming(t *testing.T) {
hub := newChatHub()
task := protocol.ChatShell{ID: "task", Status: protocol.ChatShellRunning, Command: "sleep 30", StartedAt: 1793870280000, Description: "Review"}
hub.replaceShells("session", []protocol.ChatShell{task})
hub.replaceShells("session", []protocol.ChatShell{{ID: "task", Status: protocol.ChatShellRunning, Command: "sleep 30"}})
hub.mu.Lock()
turn := hub.turnLocked("session")
got := turn.shells["task"]
size := turn.size
hub.mu.Unlock()
if got.StartedAt != task.StartedAt || got.Description != "Review" || size != protocol.ChatShellRetainedBytes(task) {
t.Fatalf("readback lost timing: %+v size=%d", got, size)
}
hub.replaceShells("session", nil)
hub.mu.Lock()
defer hub.mu.Unlock()
if turn.size != 0 || len(turn.shells) != 0 {
t.Fatal("stale shell metadata remained after authoritative removal")
}
}