sidekick-shared 0.29.0 → 0.30.0

package/dist/esm/subagentActivity.js

@@ -0,0 +1,125 @@
+/**
+ * Subagent lifecycle records as `system` session events.
+ *
+ * Codex records its multi-agent lifecycle in the parent's rollout:
+ * `item_completed` → `SubAgentActivity` items link a `spawn_agent` call to the
+ * child thread it started (`started`), mark each finished child turn
+ * (`completed`, Codex 0.150+), and note `followup_task` / `send_message`
+ * calls (`interacted`) and `interrupt_agent` calls (`interrupted`); a child's
+ * report arrives as an `agent_message` whose text starts
+ * `Message Type: FINAL_ANSWER`. With
+ * `CodexRolloutParserOptions.includeSubagentActivity`, the parser turns each
+ * into one `system` event with `origin: { kind: 'subagent-activity' }` whose
+ * `message.content` is a single `{ type: 'subagent_activity', ... }` block.
+ *
+ * Those events are bookkeeping, not messages: transcripts, context
+ * attribution, and message counts skip them, as they do task notifications.
+ *
+ * Pure: no filesystem access. Browser-safe.
+ *
+ * @module subagentActivity
+ */
+/** `origin.kind` of a subagent-activity `system` event. */
+export const SUBAGENT_ACTIVITY_ORIGIN_KIND = 'subagent-activity';
+/** `type` of the content block that carries the activity. */
+export const SUBAGENT_ACTIVITY_BLOCK_TYPE = 'subagent_activity';
+const KINDS = new Set([
+    'started',
+    'completed',
+    'interacted',
+    'interrupted',
+    'final-answer',
+]);
+const STRING_FIELDS = [
+    'callId',
+    'tool',
+    'turnId',
+    'agentThreadId',
+    'agentPath',
+    'recipient',
+    'model',
+    'reasoningEffort',
+    'parentThreadId',
+    'parentTurnId',
+    'text',
+];
+/** Whether an event is a subagent-activity `system` event (see the module docs). */
+export function isSubagentActivitySystemEvent(event) {
+    return event.type === 'system' && event.origin?.kind === SUBAGENT_ACTIVITY_ORIGIN_KIND;
+}
+/**
+ * The activity a subagent-activity `system` event carries, copied with only
+ * its known string fields; `null` for any other event or a malformed block.
+ */
+export function subagentActivityFromEvent(event) {
+    if (!isSubagentActivitySystemEvent(event))
+        return null;
+    const content = event.message?.content;
+    if (!Array.isArray(content))
+        return null;
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const raw = block;
+        if (raw.type !== SUBAGENT_ACTIVITY_BLOCK_TYPE)
+            continue;
+        if (typeof raw.kind !== 'string' || !KINDS.has(raw.kind))
+            return null;
+        const activity = { kind: raw.kind };
+        for (const field of STRING_FIELDS) {
+            const value = raw[field];
+            if (typeof value === 'string' && value.length > 0)
+                activity[field] = value;
+        }
+        return activity;
+    }
+    return null;
+}
+/** A one-line, content-free description, e.g. `Subagent /root/review started`. */
+export function describeSubagentActivity(activity) {
+    const who = activity.agentPath ?? activity.agentThreadId ?? 'subagent';
+    const name = `Subagent ${who}`;
+    switch (activity.kind) {
+        case 'started':
+            return `${name} started`;
+        case 'completed':
+            return `${name} finished a turn`;
+        case 'interacted':
+            return activity.tool === 'send_message'
+                ? `Message sent to subagent ${who}`
+                : `${name} given a follow-up task`;
+        case 'interrupted':
+            return `${name} interrupted`;
+        case 'final-answer':
+            return `${name} reported its final answer`;
+    }
+}
+const MESSAGE_HEADER = /^Message Type:[ \t]*([A-Z_]+)[ \t]*(?:\r?\n|$)/;
+/**
+ * Parses a Codex inter-agent message text. Returns `null` unless it starts
+ * with a `Message Type:` line.
+ */
+export function parseCodexAgentMessageText(text) {
+    if (typeof text !== 'string')
+        return null;
+    const header = MESSAGE_HEADER.exec(text);
+    if (!header)
+        return null;
+    const rest = text.slice(header[0].length);
+    const payloadAt = /(?:^|\n)Payload:[ \t]*(?:\r?\n|$)/.exec(rest);
+    const head = payloadAt ? rest.slice(0, payloadAt.index) : rest;
+    const payload = payloadAt ? rest.slice(payloadAt.index + payloadAt[0].length) : '';
+    const field = (name) => {
+        const match = new RegExp(`(?:^|\\n)${name}:[ \\t]*([^\\n]*)`).exec(head);
+        const value = match?.[1]?.trim();
+        return value ? value : undefined;
+    };
+    const taskName = field('Task name');
+    const sender = field('Sender');
+    return {
+        messageType: header[1],
+        ...(taskName ? { taskName } : {}),
+        ...(sender ? { sender } : {}),
+        payload,
+    };
+}

package/dist/esm/subagentDisplayState.js

@@ -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
+ */
+/** Quiet time after a clean end before a running agent reads as finished without a report (2 min). */
+export const SUBAGENT_UNREPORTED_QUIET_MS = 2 * 60_000;
+/** Parent and transcript idle time after which a running agent reads as ended (6 h). */
+export const 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.
+ */
+export 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 >= 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 > 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`. */
+export function subagentDisplayLabel(state) {
+    return LABELS[state] ?? state;
+}

package/dist/esm/subagentSpawn.js

@@ -0,0 +1,363 @@
+/**
+ * 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
+ */
+/**
+ * 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 const SUBAGENT_SPAWN_TOOL_NAMES = Object.freeze(['Agent', 'Task']);
+const SPAWN_TOOLS = new Set(SUBAGENT_SPAWN_TOOL_NAMES);
+/** Codex's raw spawn tool name, and the name the Codex parser normalizes it to. */
+const CODEX_SPAWN_RAW = 'spawn_agent';
+const CODEX_SPAWN_TOOLS = new Set([CODEX_SPAWN_RAW, 'Spawn_agent']);
+/**
+ * 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 function isCodexSubagentSpawnTool(name, input) {
+    if (typeof name === 'string' && CODEX_SPAWN_TOOLS.has(name))
+        return true;
+    return (!!input &&
+        typeof input === 'object' &&
+        input._sidekickRawToolName === CODEX_SPAWN_RAW);
+}
+/**
+ * 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 function isSubagentSpawnTool(name, input) {
+    if (typeof name === 'string' && SPAWN_TOOLS.has(name))
+        return true;
+    return isCodexSubagentSpawnTool(name, input);
+}
+/**
+ * Recognizes a Codex `spawn_agent` result (`{"task_name": "/root/x"}`, as a
+ * JSON string or object). `null` for anything else.
+ */
+export function parseCodexSpawnLaunch(result) {
+    let value = result;
+    if (typeof value !== 'string') {
+        const text = contentText(value);
+        value = text || value;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed.startsWith('{'))
+            return null;
+        try {
+            value = JSON.parse(trimmed);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const taskName = value.task_name;
+    if (typeof taskName !== 'string')
+        return null;
+    return taskName ? { agentPath: taskName } : {};
+}
+const ASYNC_LAUNCH_PREFIX = /^\s*Async agent launched successfully\b/;
+const AGENT_ID_LINE = /(?:^|\n)[ \t]*agentId:[ \t]*([A-Za-z0-9][\w.@-]*)/;
+/**
+ * Plain text of tool-result or message content: a string as-is, or the text
+ * blocks of a content array joined by newlines.
+ */
+export function contentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const typed = block;
+        if (typed.type === 'text' && typeof typed.text === 'string')
+            parts.push(typed.text);
+    }
+    return parts.join('\n');
+}
+/**
+ * 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 function parseAsyncAgentLaunch(result) {
+    const text = contentText(result);
+    if (!ASYNC_LAUNCH_PREFIX.test(text))
+        return null;
+    const match = AGENT_ID_LINE.exec(text);
+    return match ? { agentId: match[1] } : {};
+}
+const NOTIFICATION_OPEN = '<task-notification>';
+const NOTIFICATION_CLOSE = '</task-notification>';
+const NOTIFICATION_PREFIX = /^\s*<task-notification>/;
+const TAG_PATTERNS = {
+    taskId: /<task-id>\s*([\s\S]*?)\s*<\/task-id>/,
+    toolUseId: /<tool-use-id>\s*([\s\S]*?)\s*<\/tool-use-id>/,
+    status: /<status>\s*([\s\S]*?)\s*<\/status>/,
+    summary: /<summary>\s*([\s\S]*?)\s*<\/summary>/,
+    note: /<note>\s*([\s\S]*?)\s*<\/note>/,
+};
+const INTERIM_TEXT = /waiting on its own background work|background work of its own still running/i;
+function tagValue(body, pattern) {
+    const value = pattern.exec(body)?.[1]?.trim();
+    return value ? value : undefined;
+}
+/**
+ * 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 function parseTaskNotification(text) {
+    if (typeof text !== 'string')
+        return null;
+    const start = text.indexOf(NOTIFICATION_OPEN);
+    if (start < 0)
+        return null;
+    let body = text.slice(start + NOTIFICATION_OPEN.length);
+    const resultAt = body.indexOf('<result>');
+    let header = resultAt >= 0 ? body.slice(0, resultAt) : body;
+    if (resultAt < 0) {
+        const end = body.indexOf(NOTIFICATION_CLOSE);
+        if (end >= 0)
+            header = body = body.slice(0, end);
+    }
+    if (!TAG_PATTERNS.taskId.test(header))
+        header = body;
+    const taskId = tagValue(header, TAG_PATTERNS.taskId);
+    if (!taskId)
+        return null;
+    const toolUseId = tagValue(header, TAG_PATTERNS.toolUseId);
+    const status = tagValue(header, TAG_PATTERNS.status);
+    const summary = tagValue(header, TAG_PATTERNS.summary);
+    const note = tagValue(header, TAG_PATTERNS.note);
+    return {
+        taskId,
+        ...(toolUseId ? { toolUseId } : {}),
+        ...(status ? { status } : {}),
+        ...(summary ? { summary } : {}),
+        interim: INTERIM_TEXT.test(summary ?? '') || INTERIM_TEXT.test(note ?? ''),
+    };
+}
+/**
+ * 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 function taskNotificationPromptFromAttachment(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const line = raw;
+    if (line.type !== 'attachment' || !line.attachment || typeof line.attachment !== 'object') {
+        return null;
+    }
+    const attachment = line.attachment;
+    return attachment.type === 'queued_command' &&
+        attachment.commandMode === 'task-notification' &&
+        typeof attachment.prompt === 'string'
+        ? attachment.prompt
+        : 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 function isTaskNotificationSystemEvent(event) {
+    return event.type === 'system' && event.origin?.kind === 'task-notification';
+}
+/**
+ * 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 function taskNotificationFromEvent(event) {
+    if (event.type !== 'user' && event.type !== 'system')
+        return null;
+    const flagged = event.origin?.kind === 'task-notification';
+    if (event.type === 'system' && !flagged)
+        return null;
+    const text = contentText(event.message?.content);
+    if (!flagged && !NOTIFICATION_PREFIX.test(text))
+        return null;
+    return parseTaskNotification(text);
+}
+/** Maps a notification `<status>` to an outcome; unknown or missing statuses read as `completed`. */
+export function taskNotificationOutcome(status) {
+    switch (status?.toLowerCase()) {
+        case 'failed':
+            return 'failed';
+        case 'killed':
+            return 'killed';
+        case 'stopped':
+            return 'stopped';
+        default:
+            return 'completed';
+    }
+}
+const STOPPED_PLURAL = /^\s*(\d+)\s+background agents? (?:were|was) stopped by the user:\s*([\s\S]*?)\s*$/i;
+const STOPPED_SINGULAR = /^\s*Background agent "([\s\S]*)" was stopped by the user\.?\s*$/i;
+/**
+ * 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 function parseAgentsStoppedNotice(text) {
+    if (typeof text !== 'string')
+        return null;
+    const singular = STOPPED_SINGULAR.exec(text);
+    if (singular)
+        return { descriptions: [singular[1].trim()].filter(Boolean) };
+    const plural = STOPPED_PLURAL.exec(text);
+    if (!plural)
+        return null;
+    let list = plural[2].trim();
+    if (list.endsWith('.'))
+        list = list.slice(0, -1).trimEnd();
+    if (!list.startsWith('"') || !list.endsWith('"') || list.length < 2)
+        return null;
+    const descriptions = list
+        .slice(1, -1)
+        .split(/",\s*"/)
+        .map((description) => description.trim())
+        .filter(Boolean);
+    return descriptions.length > 0 ? { descriptions } : 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 function agentsStoppedNoticeFromEvent(event) {
+    if (!isTaskNotificationSystemEvent(event))
+        return null;
+    return parseAgentsStoppedNotice(contentText(event.message?.content));
+}
+/** Claude Code's `agents_killed` system line: the user killed every running background agent. */
+export 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 function isAgentsKilledSystemEvent(event) {
+    if (!event || typeof event !== 'object')
+        return false;
+    const line = event;
+    return line.type === 'system' && line.subtype === AGENTS_KILLED_SUBTYPE;
+}
+/** `origin.kind` of the opt-in `system` event made from a `task_status` attachment. */
+export const TASK_STATUS_ORIGIN_KIND = 'task-status';
+/** `type` of the content block that carries the status. */
+export const TASK_STATUS_BLOCK_TYPE = 'task_status';
+const AGENT_TASK_TYPE = 'local_agent';
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+/**
+ * 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 function taskStatusFromAttachment(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const line = raw;
+    if (line.type !== 'attachment' || !line.attachment || typeof line.attachment !== 'object') {
+        return null;
+    }
+    const attachment = line.attachment;
+    if (attachment.type !== 'task_status' || attachment.taskType !== AGENT_TASK_TYPE)
+        return null;
+    const taskId = nonEmpty(attachment.taskId);
+    const status = nonEmpty(attachment.status);
+    if (!taskId || !status)
+        return null;
+    const description = nonEmpty(attachment.description);
+    return { taskId, taskType: AGENT_TASK_TYPE, status, ...(description ? { description } : {}) };
+}
+/** Whether a task status is final (anything but `running` / `pending`). */
+export function isFinalTaskStatus(status) {
+    if (!status)
+        return false;
+    const lower = status.toLowerCase();
+    return lower !== 'running' && lower !== 'pending';
+}
+/**
+ * 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 function isTaskStatusSystemEvent(event) {
+    return event.type === 'system' && event.origin?.kind === TASK_STATUS_ORIGIN_KIND;
+}
+/** The status an opt-in task-status `system` event carries; `null` for any other event. */
+export function taskStatusFromEvent(event) {
+    if (!isTaskStatusSystemEvent(event))
+        return null;
+    const content = event.message?.content;
+    if (!Array.isArray(content))
+        return null;
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const raw = block;
+        if (raw.type !== TASK_STATUS_BLOCK_TYPE)
+            continue;
+        const taskId = nonEmpty(raw.taskId);
+        const status = nonEmpty(raw.status);
+        if (!taskId || !status)
+            return null;
+        const description = nonEmpty(raw.description);
+        return {
+            taskId,
+            taskType: nonEmpty(raw.taskType) ?? AGENT_TASK_TYPE,
+            status,
+            ...(description ? { description } : {}),
+        };
+    }
+    return 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 function describeAgentsStopped(notice) {
+    const count = notice?.descriptions.length;
+    return count
+        ? `Background agents stopped by the user (${count})`
+        : 'Background agents stopped by the user';
+}
+/** A one-line description of a task status, e.g. `Background agent "Explore auth" completed`. */
+export function describeTaskStatus(status) {
+    const name = status.description ? `Background agent "${status.description}"` : 'Background agent';
+    return `${name} ${status.status}`;
+}