sidekick-shared 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to sidekick-shared will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.30.0] - 2026-11-01
+
+### Added
+
+- **Codex subagent activity (opt-in).** `CodexRolloutParserOptions.includeSubagentActivity` turns Codex's `SubAgentActivity` records (`started`, `completed`, `interacted`, `interrupted`) and `FINAL_ANSWER` agent messages into `system` events with `origin: { kind: 'subagent-activity' }`. Read them with `subagentActivityFromEvent()` / `isSubagentActivitySystemEvent()`; `describeSubagentActivity()` and `parseCodexAgentMessageText()` help display them. The Codex reader turns the option on; transcripts, context sources and the aggregator's counters skip these events.
+- **Codex subagent lifecycles.** `EventAggregator` follows `spawn_agent` from its `{"task_name"}` launch to `completed` or `FINAL_ANSWER` (matched by agent path); `followup_task` reopens a child, `interrupt_agent` stops it, and a failed spawn is `failed`. `isCodexSubagentSpawnTool()` and `parseCodexSpawnLaunch()` are exported.
+- **Codex child discovery.** `scanSubagents()` recurses to every depth and reports `SubagentStats.filePath`, `spawnToolUseId`, `agentNickname`, `agentPath`, `parentAgentId`, `depth` and `endedCleanly`, with stats from the child's own records. `CodexDatabase.getSpawnedDescendantThreads()` and `isCodexSubagentThread()` are exported.
+- **Settling agents that never report.** `EventAggregator.applySubagentEvidence({ agentId?, toolUseId?, finished?, stoppedByUser? }, timestamp)` lets a host apply meta-file evidence. In-stream evidence settles running agents too: `agents_killed` system lines (`SystemSessionEvent.subtype` is kept), stop notices (`parseAgentsStoppedNotice()`, `agentsStoppedNoticeFromEvent()`) and post-compaction task status (`taskStatusFromAttachment()`, `taskStatusFromEvent()`, `isTaskStatusSystemEvent()`). `SubagentLifecycle` gains `settledBy` and `agentPath`. `resolveSubagentDisplayState(lifecycle, trace?, { now, parentLastActivity })` adds the reversible display states `finished-unreported` (clean end, quiet for `SUBAGENT_UNREPORTED_QUIET_MS`) and `ended` (parent idle for `SUBAGENT_PARENT_IDLE_ENDED_MS`); `subagentDisplayLabel()` names them. `SubagentTrace` gains `lastActivityAt` and `endedCleanly`. `EventAggregator.getLastEventTime()` is a cheap getter.
+- **Compressed Codex rollouts (opt-in).** `includeCompressedRollouts` on `createSessionProviders()` / `CodexProviderOptions`, `collectPromptHistory()`, `collectSessionPromptHistory()` and `findToolCallOrigins()` reads `.jsonl.zst` rollouts when `zlib.zstdDecompressSync` exists (`isZstdDecompressionAvailable()`), and skips them with a diagnostic otherwise. `readRolloutText()`, `readRolloutBuffer()`, `resolveRolloutPath()`, `isCompressedRolloutPath()` and `COMPRESSED_ROLLOUT_SUFFIX` are exported; `walkRolloutFiles()` and `findCodexRolloutFile()` take `includeCompressed`. Live tailing stays `.jsonl`-only, and a `.jsonl` is preferred over its `.zst` twin.
+- **Reader resets.** Optional `SessionReader.lastReset()` returns `{ reason: 'truncated' | 'rewritten' | 'replaced', previousPosition }` for the last restart.
+
+### Fixed
+
+- **Rewritten or replaced session files.** The Claude Code and Codex readers check the open file's identity and first 4 KiB on every changed read, as `createJsonlTail()` does, and restart from 0 when the file was rewritten or replaced, not only when it shrank. `ProviderReaderSessionWatcher` and `SessionMonitor.poll()` checked `wasTruncated()` before reading, which counted a truncated file's events twice (and left `SessionMonitor`'s aggregator wrong); both now read first and reset before delivering the replay.
+- **Codex child rollouts.** Records a forked child inherits from its parent (before `subagent_history_start_ordinal`, after an embedded ancestor `session_meta`) are no longer parsed as the child's, and the child's own first `session_meta` is kept. Inherited tool calls were counted in subagent stats; token totals were unaffected.
+- **Codex active-session detection** skips subagent threads.
+
+### Changed
+
+- `PermissionMode` (and `permissionModeSchema`) add `'auto'` and `'dontAsk'`; unknown future modes are still dropped rather than rejected. `EventAggregator` now tracks the mode from followed events too.
+- `SessionReader.wasTruncated()` is true whenever the last `readNew()` restarted from offset 0: after a truncation, a rewrite or a replacement.
+- `isSubagentSpawnTool()` also matches Codex `spawn_agent`. `SUBAGENT_SPAWN_TOOL_NAMES` and `isAssistantTurnSubagentTool()` stay Claude Code-only.
+- With `includeTaskNotifications`, `extractSessionEvents()` and the JSONL watcher also emit `system` events for post-compaction `task_status` attachments and stop notices. The Claude Code provider's reader turns it on, so its consumers can see these rare events.
+- `classifyTool()`: `wait` is `other` (Codex code-mode cell waits) and `interrupt_agent` is `subagent`.
+- `SNAPSHOT_SCHEMA_VERSION` is 7, so saved aggregator snapshots replay once.
+
+## [0.29.1] - 2026-11-01
+
+### Fixed
+
+- **Claude Code `Agent` spawns are tracked.** Claude Code renamed its subagent tool from `Task` to `Agent`. `EventAggregator`, the subagent trace parser and scanner, the `Agent` tool summary and `isAssistantTurnSubagentTool()` recognize both names (OpenCode's `task` still maps to `Task`).
+- **Background agents complete when they finish, not at launch.** An `Async agent launched` result keeps the lifecycle running and records the agent id; a `<task-notification>` completes it with `outcome: 'completed' | 'failed' | 'killed' | 'stopped'`. An interim notification keeps or puts the agent back to running. A foreground spawn still running at a snapshot completes after `restore()`.
+- **Unknown permission modes no longer drop events.** `extractSessionEvents` rejected every line whose `permissionMode` it didn't know, such as Claude Code's `auto`, losing prompts, tool results and notifications. The unknown mode is now dropped and the line kept; `PermissionMode` is unchanged.
+- **Lookups keyed by ids that match `Object.prototype` members.** `getModelPricing`, `resolveModelPricing` (which returned no `provenance` for `constructor` and `__proto__`), `getModelContextWindowSize` / `resolveModelContextWindow`, `getModelInfo`, `normalizeToolName`, `formatToolSummary` and `parseZaiQuotaError` read only own keys, and catalog, observed-window and LiteLLM tables store a `__proto__` id as data.
+- **Snapshot resume can verify the source file.** `isSnapshotValid(snapshot, size, sourcePath)` also checks the file's identity, the digest of its first 4 KiB and the newline before the offset, and rejects a snapshot without `sourceCheckpoint`; without `sourcePath` it behaves as before. Restoring `readerState` keeps the Claude usage deduper and the Codex parser state, so a response split across the snapshot point is counted once.
+
+### Added
+
+- `isSubagentSpawnTool()`, `SUBAGENT_SPAWN_TOOL_NAMES`, `parseTaskNotification()`, `taskNotificationFromEvent()`, `isTaskNotificationSystemEvent()` and the `TaskNotification` / `SubagentOutcome` types (root and `browser`).
+- `extractSessionEvents(raw, { includeTaskNotifications })` (`ExtractSessionEventsOptions`, also from `sidekick-shared/schemas`) and `CreateWatcherOptions.includeTaskNotifications`. When enabled, Claude Code's mid-turn `queued_command` task-notification attachments become one `system` event with `origin: { kind: 'task-notification' }`. The Claude Code provider's reader enables it; the default is off.
+- `SubagentLifecycle.agentId` / `background` / `outcome`; `SubagentTrace.filePath` / `spawnToolUseId` / `parentAgentId` / `background` / `finished` / `stoppedByUser`. `readAgentMeta()` (type `AgentMeta`) also returns `toolUseId`, `parentAgentId`, `requestShape`, `finished` and `stoppedByUser`. `scanSubagentTraces` links traces exactly by meta `parentAgentId` and spawn id before falling back to heuristics.
+- `captureJsonlCheckpoint(filePath, offset)` and `verifyJsonlCheckpoint(filePath, checkpoint)` (root and `node`); `SessionSnapshot.sourceCheckpoint` and `readerState`.
+- Optional `getResumeState()` / `restoreResumeState(state)` on `SessionReader` and `SessionWatcher`, implemented by the Claude Code and Codex readers and the JSONL and reader-backed watchers. `ClaudeUsageDeduper.exportState()` / `importState()` (`ClaudeUsageDedupeState`) and `CodexRolloutParser.exportResumeState()` / `importResumeState()` (`CodexRolloutResumeState`). `CodexReader.seekTo()` defers its re-parse to the first read, which a successful `restoreResumeState()` makes unnecessary.
+
+### Changed
+
+- `SubagentTrace.parentToolUseId` holds the spawning tool-use id from Claude Code's meta file when present, as its documentation says. Heuristic links keep storing the parent's agent id there and also set `parentAgentId`; top-level traces are those without a parent agent.
+
 ## [0.29.0] - 2026-11-01
 
 ### Fixed