sidekick-shared 0.29.0 → 0.30.0

package/dist/subagentDisplayState.d.ts

@@ -0,0 +1,81 @@
+/**
+ * How to show a subagent: its lifecycle's outcome once something settled
+ * it, otherwise `running`, unless its transcript or its parent says it has
+ * stopped in all but name.
+ *
+ * Some background agents never get a final notification (they stopped after
+ * an interim "may resume" notice, the user stopped them from the UI, or a
+ * restart killed them). Their lifecycles stay `running`. This rule reads
+ * them as:
+ *
+ * - `finished-unreported`: the transcript ended cleanly (last assistant turn
+ *   `end_turn` / `stop_sequence`, no tool call unanswered) and has been quiet
+ *   for {@link SUBAGENT_UNREPORTED_QUIET_MS}.
+ * - `ended`: neither the parent session nor the transcript has been active for
+ *   {@link SUBAGENT_PARENT_IDLE_ENDED_MS}.
+ *
+ * Neither is stored: the state is recomputed from the latest data on every
+ * call, so an agent that resumes (its transcript grows, or a later
+ * notification reopens its lifecycle) reads as `running` again. Silence alone
+ * is never enough for `finished-unreported`: live agents can be quiet for
+ * hours.
+ *
+ * Pure: no filesystem access. Browser-safe.
+ *
+ * @module subagentDisplayState
+ */
+import type { SubagentLifecycle } from './aggregation/types';
+/** Quiet time after a clean end before a running agent reads as finished without a report (2 min). */
+export declare const SUBAGENT_UNREPORTED_QUIET_MS: number;
+/** Parent and transcript idle time after which a running agent reads as ended (6 h). */
+export declare const SUBAGENT_PARENT_IDLE_ENDED_MS: number;
+/** How a subagent is shown. The last four are lifecycle outcomes. */
+export type SubagentDisplayStateName = 'running' | 'finished-unreported' | 'ended' | 'completed' | 'failed' | 'stopped' | 'killed';
+/** Why a subagent reads as it does. */
+export type SubagentDisplayReason = 
+/** Its lifecycle is settled; the state is the outcome. */
+'settled'
+/** Claude Code's meta flags (`finished`, `stoppedByUser`) on a running lifecycle. */
+ | 'meta'
+/** The transcript ended cleanly and has been quiet. */
+ | 'clean-end'
+/** The parent session (and the transcript) has been idle. */
+ | 'parent-idle';
+export interface SubagentDisplayState {
+    state: SubagentDisplayStateName;
+    /** Absent for a plain `running`. */
+    reason?: SubagentDisplayReason;
+}
+/** The lifecycle fields the rule reads. */
+export type SubagentDisplayLifecycle = Pick<SubagentLifecycle, 'status' | 'outcome'>;
+/**
+ * Transcript facts the rule reads; a `SubagentTrace`, or a `SubagentStats`
+ * mapped with `lastActivityAt: stats.endTime`.
+ */
+export interface SubagentDisplayTrace {
+    /** The transcript ended cleanly (see `SubagentTrace.endedCleanly`). */
+    endedCleanly?: boolean;
+    /** Time of the transcript's last record. */
+    lastActivityAt?: Date | string | number;
+    /** Claude Code meta `finished`. */
+    finished?: boolean;
+    /** Claude Code meta `stoppedByUser`. */
+    stoppedByUser?: boolean;
+}
+export interface SubagentDisplayOptions {
+    /** The current time (epoch ms or a Date). */
+    now: number | Date;
+    /** Time of the parent session's last event, when known. */
+    parentLastActivity?: Date | string | number | null;
+}
+/**
+ * Resolves how to show a subagent (see the module docs). Settled lifecycles
+ * map to their outcome (`completed` when none is recorded). A running one is
+ * `stopped` / `completed` when its meta flags say so, `finished-unreported`
+ * after a clean end and {@link SUBAGENT_UNREPORTED_QUIET_MS} of quiet,
+ * `ended` when the parent and transcript have both been idle for longer than
+ * {@link SUBAGENT_PARENT_IDLE_ENDED_MS}, and `running` otherwise.
+ */
+export declare function resolveSubagentDisplayState(lifecycle: SubagentDisplayLifecycle, trace: SubagentDisplayTrace | null | undefined, options: SubagentDisplayOptions): SubagentDisplayState;
+/** A short label: `running`, `finished (no report)`, `ended`, `completed`, `failed`, `stopped`, `killed`. */
+export declare function subagentDisplayLabel(state: SubagentDisplayStateName): string;

package/dist/subagentDisplayState.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * How to show a subagent: its lifecycle's outcome once something settled
+ * it, otherwise `running`, unless its transcript or its parent says it has
+ * stopped in all but name.
+ *
+ * Some background agents never get a final notification (they stopped after
+ * an interim "may resume" notice, the user stopped them from the UI, or a
+ * restart killed them). Their lifecycles stay `running`. This rule reads
+ * them as:
+ *
+ * - `finished-unreported`: the transcript ended cleanly (last assistant turn
+ *   `end_turn` / `stop_sequence`, no tool call unanswered) and has been quiet
+ *   for {@link SUBAGENT_UNREPORTED_QUIET_MS}.
+ * - `ended`: neither the parent session nor the transcript has been active for
+ *   {@link SUBAGENT_PARENT_IDLE_ENDED_MS}.
+ *
+ * Neither is stored: the state is recomputed from the latest data on every
+ * call, so an agent that resumes (its transcript grows, or a later
+ * notification reopens its lifecycle) reads as `running` again. Silence alone
+ * is never enough for `finished-unreported`: live agents can be quiet for
+ * hours.
+ *
+ * Pure: no filesystem access. Browser-safe.
+ *
+ * @module subagentDisplayState
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBAGENT_PARENT_IDLE_ENDED_MS = exports.SUBAGENT_UNREPORTED_QUIET_MS = void 0;
+exports.resolveSubagentDisplayState = resolveSubagentDisplayState;
+exports.subagentDisplayLabel = subagentDisplayLabel;
+/** Quiet time after a clean end before a running agent reads as finished without a report (2 min). */
+exports.SUBAGENT_UNREPORTED_QUIET_MS = 2 * 60_000;
+/** Parent and transcript idle time after which a running agent reads as ended (6 h). */
+exports.SUBAGENT_PARENT_IDLE_ENDED_MS = 6 * 60 * 60_000;
+function toMs(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    const ms = value instanceof Date ? value.getTime() : new Date(value).getTime();
+    return Number.isFinite(ms) ? ms : undefined;
+}
+/**
+ * Resolves how to show a subagent (see the module docs). Settled lifecycles
+ * map to their outcome (`completed` when none is recorded). A running one is
+ * `stopped` / `completed` when its meta flags say so, `finished-unreported`
+ * after a clean end and {@link SUBAGENT_UNREPORTED_QUIET_MS} of quiet,
+ * `ended` when the parent and transcript have both been idle for longer than
+ * {@link SUBAGENT_PARENT_IDLE_ENDED_MS}, and `running` otherwise.
+ */
+function resolveSubagentDisplayState(lifecycle, trace, options) {
+    if (lifecycle.status !== 'running') {
+        return { state: lifecycle.outcome ?? 'completed', reason: 'settled' };
+    }
+    if (trace?.stoppedByUser)
+        return { state: 'stopped', reason: 'meta' };
+    if (trace?.finished)
+        return { state: 'completed', reason: 'meta' };
+    const now = toMs(options.now) ?? Date.now();
+    const lastActivity = toMs(trace?.lastActivityAt);
+    if (trace?.endedCleanly &&
+        lastActivity !== undefined &&
+        now - lastActivity >= exports.SUBAGENT_UNREPORTED_QUIET_MS) {
+        return { state: 'finished-unreported', reason: 'clean-end' };
+    }
+    const parentLast = toMs(options.parentLastActivity);
+    if (parentLast !== undefined) {
+        const latest = Math.max(parentLast, lastActivity ?? -Infinity);
+        if (now - latest > exports.SUBAGENT_PARENT_IDLE_ENDED_MS) {
+            return { state: 'ended', reason: 'parent-idle' };
+        }
+    }
+    return { state: 'running' };
+}
+const LABELS = {
+    running: 'running',
+    'finished-unreported': 'finished (no report)',
+    ended: 'ended',
+    completed: 'completed',
+    failed: 'failed',
+    stopped: 'stopped',
+    killed: 'killed',
+};
+/** A short label: `running`, `finished (no report)`, `ended`, `completed`, `failed`, `stopped`, `killed`. */
+function subagentDisplayLabel(state) {
+    return LABELS[state] ?? state;
+}

package/dist/subagentSpawn.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Recognizes subagent spawns, background-task notifications, and the other
+ * records that settle a background agent.
+ *
+ * Claude Code's subagent tool is `Agent`; `Task` is its earlier name (and the
+ * name OpenCode's `task` tool is normalized to). A background agent's spawning
+ * tool call gets its result right away ("Async agent launched successfully.")
+ * and its completion arrives later as a `<task-notification>` block, delivered
+ * either as a user line or as a mid-turn `queued_command` attachment. When no
+ * notification comes, a `task_status` attachment, an `agents_killed` system
+ * line, or a plain-text "background agents were stopped by the user" notice
+ * can still say how it ended.
+ *
+ * Codex spawns with `spawn_agent` (parsed as `Spawn_agent`); its result
+ * (`{"task_name": "/root/x"}`) is always a background launch.
+ *
+ * Pure: no filesystem access, so it is safe for browser bundles.
+ *
+ * @module subagentSpawn
+ */
+import type { SubagentOutcome } from './aggregation/types';
+import type { SessionEvent } from './types/sessionEvent';
+/**
+ * Claude Code / OpenCode tool names that spawn a subagent: `Agent` (current)
+ * and `Task` (earlier name). Codex's `spawn_agent` is not in this list;
+ * {@link isSubagentSpawnTool} recognizes it as well.
+ */
+export declare const SUBAGENT_SPAWN_TOOL_NAMES: readonly string[];
+/**
+ * Whether a tool call is Codex's `spawn_agent`: by name (`Spawn_agent` as
+ * parsed, or the raw `spawn_agent`), or by the raw name the Codex parser keeps
+ * in the input (`_sidekickRawToolName`).
+ */
+export declare function isCodexSubagentSpawnTool(name: string | null | undefined, input?: unknown): boolean;
+/**
+ * Whether a tool call spawns a subagent: one of
+ * {@link SUBAGENT_SPAWN_TOOL_NAMES} (`Agent`, `Task`), or Codex's
+ * `spawn_agent` (see {@link isCodexSubagentSpawnTool}; pass the call's input
+ * to also match on its raw name).
+ */
+export declare function isSubagentSpawnTool(name: string | null | undefined, input?: unknown): boolean;
+/** A Codex `spawn_agent` result: the child was started in the background. */
+export interface CodexSpawnLaunch {
+    /** The child's agent path (`task_name` in the result), e.g. `/root/review_builder`. */
+    agentPath?: string;
+}
+/**
+ * Recognizes a Codex `spawn_agent` result (`{"task_name": "/root/x"}`, as a
+ * JSON string or object). `null` for anything else.
+ */
+export declare function parseCodexSpawnLaunch(result: unknown): CodexSpawnLaunch | null;
+/** A spawning tool result that launched the agent in the background. */
+export interface AsyncAgentLaunch {
+    /** The agent id Claude Code reported (`agentId: <id>`), when present. */
+    agentId?: string;
+}
+/**
+ * Plain text of tool-result or message content: a string as-is, or the text
+ * blocks of a content array joined by newlines.
+ */
+export declare function contentText(content: unknown): string;
+/**
+ * Recognizes the immediate result of a background spawn
+ * (`Async agent launched successfully.` … `agentId: <id> …`). Accepts the
+ * result text or the raw tool-result content. Returns `null` for anything
+ * else, including a finished foreground agent's result.
+ */
+export declare function parseAsyncAgentLaunch(result: unknown): AsyncAgentLaunch | null;
+/** Fields of a `<task-notification>` block. */
+export interface TaskNotification {
+    /** `<task-id>`: the background agent's id (or a background shell task's id). */
+    taskId: string;
+    /** `<tool-use-id>`: the tool call that started the background work. */
+    toolUseId?: string;
+    /** `<status>` as written, e.g. `completed`, `failed`, `killed`, `stopped`. */
+    status?: string;
+    /** `<summary>`, e.g. `Agent "Explore auth" finished`. */
+    summary?: string;
+    /**
+     * The agent stopped while background work of its own is still running; it
+     * may resume, and the same task id notifies again.
+     */
+    interim: boolean;
+}
+/**
+ * Parses the first `<task-notification>` block in `text`. Whitespace and
+ * newlines between tags, missing fields, and unknown extra fields are
+ * tolerated; the block needs a `<task-id>`. Fields are read before the
+ * agent's own `<result>` output, which may quote anything.
+ */
+export declare function parseTaskNotification(text: unknown): TaskNotification | null;
+/**
+ * The `<task-notification>` prompt of a raw Claude Code attachment line
+ * (`{ type: 'attachment', attachment: { type: 'queued_command', commandMode:
+ * 'task-notification', prompt } }`), which is how a notification that lands
+ * mid-turn is recorded. `null` for any other value.
+ */
+export declare function taskNotificationPromptFromAttachment(raw: unknown): string | null;
+/**
+ * The synthetic `system` event `extractSessionEvents(raw, {
+ * includeTaskNotifications: true })` makes from a mid-turn task-notification
+ * attachment. It is bookkeeping, not a message or a prompt.
+ */
+export declare function isTaskNotificationSystemEvent(event: SessionEvent): boolean;
+/**
+ * The task notification an event carries: a user line with
+ * `origin.kind === 'task-notification'` or whose text starts with
+ * `<task-notification>`, or the opt-in synthetic system event. `null` otherwise.
+ */
+export declare function taskNotificationFromEvent(event: SessionEvent): TaskNotification | null;
+/** Maps a notification `<status>` to an outcome; unknown or missing statuses read as `completed`. */
+export declare function taskNotificationOutcome(status: string | undefined): SubagentOutcome;
+/** A plain-text notice that the user stopped background agents. */
+export interface AgentsStoppedNotice {
+    /** The stopped agents' descriptions, as the notice quotes them. */
+    descriptions: string[];
+}
+/**
+ * Parses Claude Code's plain-text notice that the user stopped background
+ * agents: `2 background agents were stopped by the user: "A", "B".` (a
+ * `queued_command` attachment's prompt) or `Background agent "A" was stopped
+ * by the user.` (a queue-operation line). `null` for any other text.
+ */
+export declare function parseAgentsStoppedNotice(text: unknown): AgentsStoppedNotice | null;
+/**
+ * The stop notice a task-notification event carries (a `queued_command`
+ * prompt that is plain text, not a `<task-notification>` block). `null`
+ * otherwise.
+ */
+export declare function agentsStoppedNoticeFromEvent(event: SessionEvent): AgentsStoppedNotice | null;
+/** Claude Code's `agents_killed` system line: the user killed every running background agent. */
+export declare const AGENTS_KILLED_SUBTYPE = "agents_killed";
+/**
+ * Whether an event, or a raw Claude Code JSONL line, is an `agents_killed`
+ * system line (`{ type: 'system', subtype: 'agents_killed' }`).
+ */
+export declare function isAgentsKilledSystemEvent(event: unknown): boolean;
+/** A background agent's status from a Claude Code `task_status` attachment. */
+export interface SubagentTaskStatus {
+    /** The background agent's id. */
+    taskId: string;
+    /** `local_agent` for background agents. */
+    taskType: string;
+    /** As written: `running`, `completed`, `failed`, `killed`, `stopped`, … */
+    status: string;
+    description?: string;
+}
+/** `origin.kind` of the opt-in `system` event made from a `task_status` attachment. */
+export declare const TASK_STATUS_ORIGIN_KIND = "task-status";
+/** `type` of the content block that carries the status. */
+export declare const TASK_STATUS_BLOCK_TYPE = "task_status";
+/**
+ * The background agent's status a raw Claude Code `task_status` attachment
+ * line reports (`{ type: 'attachment', attachment: { type: 'task_status',
+ * taskId, taskType: 'local_agent', status, description } }`). `null` for any
+ * other value, including background shell tasks (`local_bash`).
+ */
+export declare function taskStatusFromAttachment(raw: unknown): SubagentTaskStatus | null;
+/** Whether a task status is final (anything but `running` / `pending`). */
+export declare function isFinalTaskStatus(status: string | undefined): boolean;
+/**
+ * The synthetic `system` event `extractSessionEvents(raw, {
+ * includeTaskNotifications: true })` makes from a background agent's
+ * `task_status` attachment. It is bookkeeping, not a message or a prompt.
+ */
+export declare function isTaskStatusSystemEvent(event: SessionEvent): boolean;
+/** The status an opt-in task-status `system` event carries; `null` for any other event. */
+export declare function taskStatusFromEvent(event: SessionEvent): SubagentTaskStatus | null;
+/**
+ * A one-line description of a stop: `Background agents stopped by the user (2)`,
+ * or, for an `agents_killed` line (`null`), `Background agents stopped by the user`.
+ */
+export declare function describeAgentsStopped(notice: AgentsStoppedNotice | null): string;
+/** A one-line description of a task status, e.g. `Background agent "Explore auth" completed`. */
+export declare function describeTaskStatus(status: SubagentTaskStatus): string;