sidekick-shared 0.29.0 → 0.30.0

package/dist/aggregation/EventAggregator.d.ts

@@ -13,8 +13,12 @@ import type { EventAggregatorOptions, AggregatedTokens, ModelUsageStats, BurnRat
 import type { SerializedFrequencyState } from './FrequencyTracker';
 import type { SerializedHeatmapState } from './HeatmapTracker';
 import type { SerializedPatternState } from './PatternExtractor';
-/** Schema version for serialized snapshots. v6: token totals count each Claude response and Codex call once. */
-export declare const SNAPSHOT_SCHEMA_VERSION = 6;
+/**
+ * Schema version for serialized snapshots. v6: token totals count each Claude
+ * response and Codex call once. v7: subagent lifecycles track Codex spawns and
+ * record what settled a background agent (`settledBy`).
+ */
+export declare const SNAPSHOT_SCHEMA_VERSION = 7;
 /**
  * JSON-serializable snapshot of EventAggregator state.
  * Used by session snapshot sidecar files for fast resume.
@@ -83,6 +87,21 @@ export interface SerializedAggregatorState {
     patternState?: SerializedPatternState;
     heatmapState?: SerializedHeatmapState;
 }
+/**
+ * Host-supplied evidence about how a subagent ended, for
+ * {@link EventAggregator.applySubagentEvidence}: Claude Code's
+ * `agent-<id>.meta.json` flags, matched by agent id or spawning tool_use id.
+ */
+export interface SubagentEvidence {
+    /** The agent id (Claude Code's `agent-<id>` name, or a Codex child thread id). */
+    agentId?: string;
+    /** The spawning tool_use id (meta `toolUseId`). */
+    toolUseId?: string;
+    /** Meta `finished`: the background agent is done. `false` reopens an agent `meta` settled. */
+    finished?: boolean;
+    /** Meta `stoppedByUser`: the user stopped the agent. */
+    stoppedByUser?: boolean;
+}
 /**
  * Parses dependency references from a todo item's content text.
  *
@@ -139,6 +158,8 @@ export declare class EventAggregator {
     private activeTaskId;
     private subagents;
     private pendingSubagents;
+    /** Codex `spawn_agent` calls still waiting for their result (always a background launch). */
+    private pendingCodexSpawns;
     private planExtractor;
     private planState;
     private planEnteredAt;
@@ -173,6 +194,8 @@ export declare class EventAggregator {
     getBurnRate(): BurnRateInfo;
     getTaskState(): TaskState;
     getSubagents(): SubagentLifecycle[];
+    /** Timestamp of the last counted event (`getMetrics().lastEventTime`), without building the metrics. */
+    getLastEventTime(): string | null;
     getPlan(): PlanState | null;
     getContextAttribution(): ContextAttribution;
     getTimeline(): TimelineEvent[];
@@ -226,7 +249,78 @@ export declare class EventAggregator {
     private isGoalGateTask;
     private extractSubagentFromEvent;
     private extractSubagentFromFollowEvent;
+    private trackSubagentSpawn;
+    /**
+     * The spawning tool call's result. A foreground agent ends here; a
+     * background launch only reports the agent id (a Codex spawn, its agent
+     * path), and the agent keeps running until a notification or another
+     * record says it ended.
+     */
+    private resolveSubagentResult;
+    private markBackgroundLaunch;
     private completeSubagent;
+    private finishSubagent;
+    /** Puts a settled agent back to running (it resumed). */
+    private reopenSubagent;
+    /**
+     * Settles a lifecycle that is still running (and its task card). Agents
+     * already settled are left alone: a stop notice or status can name agents
+     * that finished earlier.
+     */
+    private settleRunningSubagent;
+    /**
+     * Moves an agent's task card with its lifecycle: `null` back to in
+     * progress, a failure to deleted, any other outcome to completed.
+     */
+    private settleAgentTask;
+    /**
+     * Applies a background task's notification to the subagent it reports on,
+     * matched by the spawning tool_use id (or by agent id when the notification
+     * has none). The latest notification wins: an interim one ("waiting on its
+     * own background work") keeps or puts the agent back to running, a final one
+     * completes it. Notifications for background shell tasks match nothing.
+     */
+    private applyTaskNotification;
+    private findNotifiedSubagent;
+    /**
+     * Applies host evidence about a subagent (Claude Code's meta flags):
+     * `stoppedByUser` settles a running agent as `stopped`, `finished` as
+     * `completed` (`settledBy: 'meta'`). Agents already settled some other way
+     * keep their outcome; `finished: false` reopens an agent that only meta
+     * settled. Matches by `toolUseId`, then `agentId` (the newest such agent),
+     * and records the agent id when matched by tool_use id.
+     *
+     * @param timestamp ISO time to record as the completion (the agent's last
+     *   activity, when the host knows it)
+     * @returns Whether a lifecycle changed
+     */
+    applySubagentEvidence(evidence: SubagentEvidence, timestamp: string): boolean;
+    /** The newest lifecycle with this spawning tool_use id, else with this agent id. */
+    private findSubagent;
+    /** `agents_killed`: the user killed every running background agent. */
+    private applyAgentsKilled;
+    /**
+     * "N background agents were stopped by the user: "A", "B"": settles the
+     * running agents with those descriptions, the newest first for repeats.
+     */
+    private applyAgentsStopped;
+    /** A background agent's final `task_status` attachment, matched by agent id. */
+    private applyTaskStatus;
+    /**
+     * A Codex subagent lifecycle record: `started` links the spawn to its child
+     * thread; `completed` (a child turn finished) and `final-answer` (the
+     * child's report, matched by its agent path) complete it; `interacted`
+     * after `followup_task` puts it back to running (a `send_message` does
+     * not: it does not start a turn); `interrupted` (`interrupt_agent`) settles
+     * it as `stopped`, since the child keeps its thread and a follow-up can
+     * run it again, like a user stop rather than a kill.
+     */
+    private applySubagentActivity;
+    /** The newest lifecycle with this Codex agent path (with `runningFirst`, a running one first). */
+    private findSubagentByPath;
+    private applySubagentFollowRecord;
+    private addSubagentTimeline;
+    private addTaskNotificationTimeline;
     private extractPlanFromSessionEvent;
     private processPlanFollowEvent;
     private convertExtractedPlanToPlanState;