From 6421554bfe2d59d7de504a610ac228fb9ca557f3 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Fri, 6 Nov 2026 15:08:34 +0000 Subject: [PATCH] Expose recorded background task timing and progress metadata --- docs/notes/background-task-metadata.md | 54 +++++ internal/claude/chat.go | 1 + internal/claude/claude.go | 17 +- internal/claude/task_metadata.go | 225 ++++++++++++++++++ internal/claude/task_metadata_test.go | 136 +++++++++++ internal/claude/translate.go | 27 ++- internal/codex/chat.go | 25 +- internal/codex/shell_metadata_test.go | 38 +++ internal/codex/shells.go | 14 +- internal/opencode/chat_shell_snapshot.go | 6 +- internal/protocol/chat.go | 19 +- internal/protocol/chat_shell_metadata.go | 47 ++++ internal/protocol/chat_shell_metadata_test.go | 34 +++ internal/server/chat_hub.go | 19 +- internal/server/chat_room.go | 6 +- internal/server/chat_shell_metadata_test.go | 51 ++++ 16 files changed, 688 insertions(+), 31 deletions(-) create mode 100644 docs/notes/background-task-metadata.md create mode 100644 internal/claude/task_metadata.go create mode 100644 internal/claude/task_metadata_test.go create mode 100644 internal/codex/shell_metadata_test.go create mode 100644 internal/protocol/chat_shell_metadata.go create mode 100644 internal/protocol/chat_shell_metadata_test.go create mode 100644 internal/server/chat_shell_metadata_test.go diff --git a/docs/notes/background-task-metadata.md b/docs/notes/background-task-metadata.md new file mode 100644 index 00000000..d08a2c2c --- /dev/null +++ b/docs/notes/background-task-metadata.md @@ -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. diff --git a/internal/claude/chat.go b/internal/claude/chat.go index 2da75171..5ca86696 100644 --- a/internal/claude/chat.go +++ b/internal/claude/chat.go @@ -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{} diff --git a/internal/claude/claude.go b/internal/claude/claude.go index 817ff701..92c61047 100644 --- a/internal/claude/claude.go +++ b/internal/claude/claude.go @@ -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 diff --git a/internal/claude/task_metadata.go b/internal/claude/task_metadata.go new file mode 100644 index 00000000..0c426eb0 --- /dev/null +++ b/internal/claude/task_metadata.go @@ -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 = © + } + } + 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: ©}) +} + +// 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 +} diff --git a/internal/claude/task_metadata_test.go b/internal/claude/task_metadata_test.go new file mode 100644 index 00000000..723ccb8a --- /dev/null +++ b/internal/claude/task_metadata_test.go @@ -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) + } +} diff --git a/internal/claude/translate.go b/internal/claude/translate.go index 9bc02c22..0d839a50 100644 --- a/internal/claude/translate.go +++ b/internal/claude/translate.go @@ -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 = © 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 = © } 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 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, ©) } 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, ©) } 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 © + } id := shellID(toolID) s.shellOrder = append(s.shellOrder, id) shell := protocol.ChatShell{ID: id, Status: protocol.ChatShellRunning, Command: command} diff --git a/internal/codex/chat.go b/internal/codex/chat.go index 60dc0b39..f8fd5baa 100644 --- a/internal/codex/chat.go +++ b/internal/codex/chat.go @@ -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"` diff --git a/internal/codex/shell_metadata_test.go b/internal/codex/shell_metadata_test.go new file mode 100644 index 00000000..1eb15a83 --- /dev/null +++ b/internal/codex/shell_metadata_test.go @@ -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) + } +} diff --git a/internal/codex/shells.go b/internal/codex/shells.go index 34a565f8..78618c65 100644 --- a/internal/codex/shells.go +++ b/internal/codex/shells.go @@ -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 } diff --git a/internal/opencode/chat_shell_snapshot.go b/internal/opencode/chat_shell_snapshot.go index 8559a741..e3517105 100644 --- a/internal/opencode/chat_shell_snapshot.go +++ b/internal/opencode/chat_shell_snapshot.go @@ -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) } diff --git a/internal/protocol/chat.go b/internal/protocol/chat.go index d7ef032d..797e36b6 100644 --- a/internal/protocol/chat.go +++ b/internal/protocol/chat.go @@ -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 diff --git a/internal/protocol/chat_shell_metadata.go b/internal/protocol/chat_shell_metadata.go new file mode 100644 index 00000000..a8911220 --- /dev/null +++ b/internal/protocol/chat_shell_metadata.go @@ -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) +} diff --git a/internal/protocol/chat_shell_metadata_test.go b/internal/protocol/chat_shell_metadata_test.go new file mode 100644 index 00000000..15b8baad --- /dev/null +++ b/internal/protocol/chat_shell_metadata_test.go @@ -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") + } +} diff --git a/internal/server/chat_hub.go b/internal/server/chat_hub.go index 060b32a7..5fff6f10 100644 --- a/internal/server/chat_hub.go +++ b/internal/server/chat_hub.go @@ -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)) } } } diff --git a/internal/server/chat_room.go b/internal/server/chat_room.go index 99909e17..99f94a8e 100644 --- a/internal/server/chat_room.go +++ b/internal/server/chat_room.go @@ -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) } diff --git a/internal/server/chat_shell_metadata_test.go b/internal/server/chat_shell_metadata_test.go new file mode 100644 index 00000000..96c91535 --- /dev/null +++ b/internal/server/chat_shell_metadata_test.go @@ -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") + } +}