@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.10

package/dist/stt/transcribe.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Speech-to-text transcription service (voice input / dictation).
+ *
+ * A NON-tool, pure "creds + audio bytes → text" service: the desktop composer
+ * records the user's voice and calls this to fill the input box (Codex-style
+ * dictation). It is deliberately NOT an agent tool — the user is speaking their
+ * own prompt, not asking the model to transcribe a file.
+ *
+ * Targets the OpenAI-compatible `/audio/transcriptions` endpoint, which a single
+ * adapter covers across OpenAI (whisper-1 / gpt-4o-transcribe), Groq
+ * (whisper-large-v3-turbo), and self-hosted whisper.cpp servers — they share
+ * the same multipart wire shape; only baseUrl + model differ.
+ *
+ * `fetch` is injected so this is unit-testable without network (mirrors
+ * image-providers.ts). Production callers pass the global `fetch`.
+ */
+export interface TranscribeCreds {
+    baseUrl: string;
+    apiKey: string;
+}
+export interface TranscribeRequest {
+    /** Raw audio bytes (NOT base64) — e.g. a webm/opus recording. */
+    audio: Uint8Array;
+    /** MIME type of the audio, e.g. "audio/webm". */
+    mimeType: string;
+    /** Multipart part filename hint (extension matters to some servers). */
+    filename: string;
+    /** Model id, e.g. "gpt-4o-transcribe" | "whisper-1". */
+    model: string;
+    creds: TranscribeCreds;
+    /** Optional ISO-639-1 language hint (improves accuracy / latency). */
+    language?: string;
+    /** Optional cancellation signal forwarded to fetch. */
+    signal?: AbortSignal;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export type TranscribeResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Transcribe audio via an OpenAI-compatible `/audio/transcriptions` endpoint.
+ * Posts multipart/form-data (file + model + response_format[+ language]) with a
+ * Bearer key; reads `{ text }` from the JSON response. Do NOT set Content-Type
+ * manually — fetch derives the multipart boundary from the FormData body.
+ */
+export declare function transcribe(req: TranscribeRequest): Promise<TranscribeResult>;

package/dist/stt/transcribe.js

@@ -0,0 +1,65 @@
+/**
+ * Speech-to-text transcription service (voice input / dictation).
+ *
+ * A NON-tool, pure "creds + audio bytes → text" service: the desktop composer
+ * records the user's voice and calls this to fill the input box (Codex-style
+ * dictation). It is deliberately NOT an agent tool — the user is speaking their
+ * own prompt, not asking the model to transcribe a file.
+ *
+ * Targets the OpenAI-compatible `/audio/transcriptions` endpoint, which a single
+ * adapter covers across OpenAI (whisper-1 / gpt-4o-transcribe), Groq
+ * (whisper-large-v3-turbo), and self-hosted whisper.cpp servers — they share
+ * the same multipart wire shape; only baseUrl + model differ.
+ *
+ * `fetch` is injected so this is unit-testable without network (mirrors
+ * image-providers.ts). Production callers pass the global `fetch`.
+ */
+/**
+ * Transcribe audio via an OpenAI-compatible `/audio/transcriptions` endpoint.
+ * Posts multipart/form-data (file + model + response_format[+ language]) with a
+ * Bearer key; reads `{ text }` from the JSON response. Do NOT set Content-Type
+ * manually — fetch derives the multipart boundary from the FormData body.
+ */
+export async function transcribe(req) {
+    const fetchImpl = req.fetchImpl ?? fetch;
+    // Trim trailing slashes so `${baseUrl}/audio/...` doesn't double up.
+    const baseUrl = req.creds.baseUrl.replace(/\/+$/, "");
+    const form = new FormData();
+    // Copy into a fresh Uint8Array so the Blob gets a clean ArrayBuffer (avoids
+    // SharedArrayBuffer / byteOffset typing issues across runtimes).
+    const buf = Uint8Array.from(req.audio);
+    form.append("file", new Blob([buf], { type: req.mimeType }), req.filename);
+    form.append("model", req.model);
+    form.append("response_format", "json");
+    if (req.language)
+        form.append("language", req.language);
+    let resp;
+    try {
+        resp = await fetchImpl(`${baseUrl}/audio/transcriptions`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${req.creds.apiKey}` },
+            body: form,
+            signal: req.signal,
+        });
+    }
+    catch (err) {
+        return { ok: false, error: `request failed: ${err.message}` };
+    }
+    if (!resp.ok) {
+        const body = (await resp.text().catch(() => "")).slice(0, 500);
+        return { ok: false, error: `transcription API returned ${resp.status}: ${body}` };
+    }
+    let json;
+    try {
+        json = await resp.json();
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse transcription response: ${err.message}` };
+    }
+    const text = json?.text;
+    if (typeof text !== "string") {
+        const preview = JSON.stringify(json).slice(0, 500);
+        return { ok: false, error: `no text in transcription response: ${preview}` };
+    }
+    return { ok: true, text };
+}

package/dist/tool-system/browser-bridge.d.ts

@@ -0,0 +1,226 @@
+/**
+ * BrowserBridge — driver-agnostic contract between the browser tools (core)
+ * and whatever drives the actual browser (renderer's webview via CDP).
+ *
+ * Spec: docs/superpowers/specs/2026-06-16-browser-automation-mvp.md
+ *
+ * The core tools only know this interface. The renderer implements it on top
+ * of the webview's `webContents.debugger` (CDP): observe via
+ * Accessibility.getFullAXTree, act via DOM.getBoxModel → Input.dispatchMouseEvent.
+ * Keeping it driver-agnostic means a future implementation (a hidden
+ * BrowserWindow for unattended runs, or an external engine) can swap in without
+ * touching the tools. Undefined on ToolContext → headless / no panel → tools
+ * degrade with a clear error.
+ */
+/** One interactive element from the page's accessibility tree. */
+export interface BrowserElement {
+    /** Per-snapshot reference id (e1, e2, …); the renderer maps it back to a
+     *  backendDOMNodeId for the action tools. Reassigned each snapshot. */
+    ref: string;
+    /** ARIA role (button, link, textbox, checkbox, combobox, …). */
+    role: string;
+    /** Accessible name (visible text / label). May be empty. */
+    name: string;
+    /** True for password/sensitive inputs — value is never captured (security). */
+    sensitive?: boolean;
+    /** Optional value for non-sensitive inputs (e.g. current textbox text). */
+    value?: string;
+}
+export interface BrowserSnapshot {
+    url: string;
+    title?: string;
+    elements: BrowserElement[];
+    /** Set when the page needs the user to act (login wall / 2FA) — agent should
+     *  hand control back to the user rather than retry. */
+    needsHuman?: string;
+}
+export interface BrowserResult {
+    ok: boolean;
+    /** Human-readable detail (error reason, or short success note). */
+    detail?: string;
+    /** True when a ref no longer resolves (DOM changed) → agent should re-snapshot. */
+    staleRef?: boolean;
+}
+/** Result of reading the page's main textual content (扒内容). */
+export interface BrowserContent {
+    ok: boolean;
+    url: string;
+    title?: string;
+    /** Extracted readable text (main content, scripts/styles/nav stripped). */
+    text: string;
+    /** True if the text was truncated to a cap. */
+    truncated?: boolean;
+    detail?: string;
+}
+/** One hyperlink extracted from the page (a[href]). */
+export interface BrowserLink {
+    /** Visible link text (trimmed, may be empty for icon-only links). */
+    text: string;
+    /** Absolute URL (href resolved against the page). */
+    url: string;
+}
+/** One image extracted from the page (img[src]). */
+export interface BrowserImage {
+    /** Absolute image URL (src resolved against the page). */
+    url: string;
+    /** alt text if present (helps the agent know what the image is). */
+    alt?: string;
+    /** Per-extract ref (imgN) — pass to browser_observe(image) to see its pixels. */
+    ref?: string;
+}
+/** One video extracted from the page (<video src> / <source src>). */
+export interface BrowserVideo {
+    /** Absolute video URL (src resolved against the page). */
+    url: string;
+}
+/**
+ * Result of extracting the page's link/image URLs (扒链接/图片地址).
+ * The a11y snapshot deliberately omits href/src (token economy); this is the
+ * explicit opt-in for "I need the actual URLs" — e.g. collect article links,
+ * find a video/image source to hand to yt-dlp/curl.
+ */
+export interface BrowserExtract {
+    ok: boolean;
+    url: string;
+    title?: string;
+    links: BrowserLink[];
+    images: BrowserImage[];
+    /** Video/source URLs found on the page (a downloader like yt-dlp can fetch). */
+    videos: BrowserVideo[];
+    /** True if any list was capped (page had more) — narrow the page first. */
+    truncated?: boolean;
+    detail?: string;
+}
+/** A captured image's bytes, ready to become a vision ContentBlock. */
+export interface BrowserImageData {
+    ok: boolean;
+    /** base64 (no data: prefix). */
+    base64?: string;
+    /** "image/jpeg" | "image/png" | … */
+    mediaType?: string;
+    /** ref the image came from (so the tool can label which image is which). */
+    ref?: string;
+    detail?: string;
+}
+export interface BrowserBridge {
+    snapshot(): Promise<BrowserSnapshot>;
+    click(ref: string): Promise<BrowserResult>;
+    type(ref: string, text: string): Promise<BrowserResult>;
+    navigate(url: string): Promise<BrowserResult>;
+    scroll(dir: "up" | "down", amount?: number): Promise<BrowserResult>;
+    /** Read the page's main readable text content (for summarizing / extraction). */
+    readContent(): Promise<BrowserContent>;
+    /** Extract the page's hyperlink + image URLs (href/src the a11y tree omits). */
+    extractLinks(): Promise<BrowserExtract>;
+    /** Wait until the page finishes loading (or a timeout). */
+    waitForLoad(timeoutMs?: number): Promise<BrowserResult>;
+    /** Hover over an element by ref (reveal hover-dependent menus/tooltips). */
+    hover(ref: string): Promise<BrowserResult>;
+    /**
+     * Select an option in a native <select> by ref. `value` matches an option's
+     * value or visible text. Custom <div> dropdowns are NOT this — click to expand
+     * them and click the option from the next snapshot.
+     */
+    selectOption(ref: string, value: string): Promise<BrowserResult>;
+    /**
+     * Press a key (or combination) on the focused element / a given ref. `key` is
+     * a key name ("Enter", "Tab", "Escape", "ArrowDown") or a combination
+     * ("Control+a"). Focuses `ref` first if given (so the key lands there).
+     */
+    pressKey(key: string, ref?: string): Promise<BrowserResult>;
+    /**
+     * Fetch the real pixels of page images by ref (e.g. 小红书 笔记配图) so a
+     * vision model can SEE their content. Fetched in-page (carries the page's
+     * cookies → beats hotlink protection). One result per requested ref.
+     */
+    fetchImages(refs: string[]): Promise<BrowserImageData[]>;
+    /**
+     * Screenshot the viewport, or a single element's box if `ref` given (a
+     * <video> ref → its current frame). For "see the rendered layout / canvas /
+     * chart" — when the a11y tree isn't enough.
+     */
+    screenshot(ref?: string): Promise<BrowserImageData>;
+    /** List the open browser tabs (the agent picks one to drive via switchTab). */
+    listTabs(): Promise<BrowserTab[]>;
+    /** Make a tab the active automation target (subsequent actions drive it). */
+    switchTab(tabId: string): Promise<BrowserResult>;
+}
+/** One open browser tab, as the agent sees it. */
+export interface BrowserTab {
+    /** Stable id (the desktop webContents id, as a string). */
+    tabId: string;
+    url: string;
+    title: string;
+    /** True for the tab automation currently drives. */
+    active: boolean;
+}
+/**
+ * Minimal shape of a CDP Accessibility.getFullAXTree node we depend on.
+ * (The real payload has more fields; we read only these.)
+ */
+export interface AXNode {
+    nodeId: string;
+    ignored?: boolean;
+    role?: {
+        value?: string;
+    };
+    name?: {
+        value?: string;
+    };
+    value?: {
+        value?: string;
+    };
+    backendDOMNodeId?: number;
+    properties?: Array<{
+        name: string;
+        value?: {
+            value?: unknown;
+        };
+    }>;
+}
+/**
+ * Pure: flatten a CDP accessibility tree into the compact, ref-tagged element
+ * list the LLM sees. Token-economical (role + name + key props only, no DOM
+ * markup). Returns elements in tree order with refs e1, e2, …, plus a
+ * `refToBackendId` map the caller (renderer) keeps so action tools can resolve
+ * a ref back to a backendDOMNodeId.
+ *
+ * Filtering: drop ignored nodes; keep nodes whose role is interactive (or that
+ * are explicitly focusable), and that have a name OR are a value input. Password
+ * / sensitive inputs are marked `sensitive` and their value is NEVER included.
+ */
+export declare function flattenAxTree(nodes: AXNode[]): {
+    elements: BrowserElement[];
+    refToBackendId: Record<string, number>;
+};
+/** Default cap for extracted page text (chars) — keeps content within a sane
+ *  token budget; the agent can scroll + re-read for more. */
+export declare const CONTENT_CHAR_CAP = 12000;
+/** Cap for extracted links/images per call — keeps the result token-bounded;
+ *  a busy page can have thousands of <a>/<img>. The agent narrows the page
+ *  (navigate/scroll) and re-extracts for more. */
+export declare const EXTRACT_LINK_CAP = 200;
+/**
+ * In-page JS (string) that collects deduped, absolute link + image URLs and
+ * returns them as a JSON-serializable object. Run via CDP Runtime.evaluate with
+ * returnByValue. Kept here (not in the renderer) so the extraction contract is
+ * defined alongside its types and is unit-testable. `cap` bounds each list;
+ * `truncated` is set when either hit the cap.
+ *
+ * - Links: <a href> with a real navigable href (skips javascript:/empty/#-only).
+ * - Images: <img src> (skips empty/data: noise beyond a length sanity bound is
+ *   left to the page; data URLs are dropped — they're inline, not fetchable URLs).
+ * - URLs are absolute (the DOM's .href/.src already resolve against the base).
+ */
+export declare function buildExtractLinksScript(cap?: number): string;
+/**
+ * Pure: normalize raw extracted page text — collapse runs of whitespace/blank
+ * lines, trim, and cap to `cap` chars (marking truncation). The renderer pulls
+ * raw innerText via CDP; this keeps the cleanup logic testable and consistent.
+ */
+export declare function cleanPageText(raw: string, cap?: number): {
+    text: string;
+    truncated: boolean;
+};
+/** Render a snapshot's element list as the compact text block shown to the LLM. */
+export declare function renderElementList(elements: BrowserElement[]): string;

package/dist/tool-system/browser-bridge.js

@@ -0,0 +1,163 @@
+/**
+ * BrowserBridge — driver-agnostic contract between the browser tools (core)
+ * and whatever drives the actual browser (renderer's webview via CDP).
+ *
+ * Spec: docs/superpowers/specs/2026-06-16-browser-automation-mvp.md
+ *
+ * The core tools only know this interface. The renderer implements it on top
+ * of the webview's `webContents.debugger` (CDP): observe via
+ * Accessibility.getFullAXTree, act via DOM.getBoxModel → Input.dispatchMouseEvent.
+ * Keeping it driver-agnostic means a future implementation (a hidden
+ * BrowserWindow for unattended runs, or an external engine) can swap in without
+ * touching the tools. Undefined on ToolContext → headless / no panel → tools
+ * degrade with a clear error.
+ */
+/** Roles we surface as actionable/meaningful to the agent. */
+const INTERACTIVE_ROLES = new Set([
+    "button",
+    "link",
+    "textbox",
+    "searchbox",
+    "checkbox",
+    "radio",
+    "combobox",
+    "listbox",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "tab",
+    "switch",
+    "slider",
+    "option",
+]);
+/** Input-ish roles whose value we may show (unless sensitive). */
+const VALUE_ROLES = new Set(["textbox", "searchbox", "combobox", "slider"]);
+function propValue(node, name) {
+    return node.properties?.find((p) => p.name === name)?.value?.value;
+}
+/**
+ * Pure: flatten a CDP accessibility tree into the compact, ref-tagged element
+ * list the LLM sees. Token-economical (role + name + key props only, no DOM
+ * markup). Returns elements in tree order with refs e1, e2, …, plus a
+ * `refToBackendId` map the caller (renderer) keeps so action tools can resolve
+ * a ref back to a backendDOMNodeId.
+ *
+ * Filtering: drop ignored nodes; keep nodes whose role is interactive (or that
+ * are explicitly focusable), and that have a name OR are a value input. Password
+ * / sensitive inputs are marked `sensitive` and their value is NEVER included.
+ */
+export function flattenAxTree(nodes) {
+    const elements = [];
+    const refToBackendId = {};
+    let counter = 0;
+    for (const node of nodes) {
+        if (node.ignored)
+            continue;
+        const role = node.role?.value;
+        if (!role)
+            continue;
+        const focusable = propValue(node, "focusable") === true;
+        if (!INTERACTIVE_ROLES.has(role) && !focusable)
+            continue;
+        const name = (node.name?.value ?? "").trim();
+        const isValueRole = VALUE_ROLES.has(role);
+        // Skip nameless non-input noise (e.g. a focusable wrapper with no label).
+        if (!name && !isValueRole)
+            continue;
+        // backendDOMNodeId is required to act on the element later; without it the
+        // element isn't actionable, so don't surface it.
+        if (node.backendDOMNodeId === undefined)
+            continue;
+        const sensitive = propValue(node, "protected") === true || // ARIA "protected" → password-like
+            role === "textbox" && /password|密码/i.test(name);
+        counter += 1;
+        const ref = `e${counter}`;
+        refToBackendId[ref] = node.backendDOMNodeId;
+        const el = { ref, role, name };
+        if (sensitive) {
+            el.sensitive = true; // value intentionally omitted
+        }
+        else if (isValueRole) {
+            const v = node.value?.value?.toString();
+            if (v)
+                el.value = v;
+        }
+        elements.push(el);
+    }
+    return { elements, refToBackendId };
+}
+/** Default cap for extracted page text (chars) — keeps content within a sane
+ *  token budget; the agent can scroll + re-read for more. */
+export const CONTENT_CHAR_CAP = 12_000;
+/** Cap for extracted links/images per call — keeps the result token-bounded;
+ *  a busy page can have thousands of <a>/<img>. The agent narrows the page
+ *  (navigate/scroll) and re-extracts for more. */
+export const EXTRACT_LINK_CAP = 200;
+/**
+ * In-page JS (string) that collects deduped, absolute link + image URLs and
+ * returns them as a JSON-serializable object. Run via CDP Runtime.evaluate with
+ * returnByValue. Kept here (not in the renderer) so the extraction contract is
+ * defined alongside its types and is unit-testable. `cap` bounds each list;
+ * `truncated` is set when either hit the cap.
+ *
+ * - Links: <a href> with a real navigable href (skips javascript:/empty/#-only).
+ * - Images: <img src> (skips empty/data: noise beyond a length sanity bound is
+ *   left to the page; data URLs are dropped — they're inline, not fetchable URLs).
+ * - URLs are absolute (the DOM's .href/.src already resolve against the base).
+ */
+export function buildExtractLinksScript(cap = EXTRACT_LINK_CAP) {
+    return `(function(){
+    var cap=${cap};
+    var links=[],images=[],lt=false,it=false,seenL={},seenI={};
+    var as=document.querySelectorAll('a[href]');
+    for(var i=0;i<as.length;i++){
+      var a=as[i],u=a.href;
+      if(!u||u.indexOf('javascript:')===0||u==='#'||u.charAt(u.length-1)==='#'&&u.indexOf('#')===u.length-1)continue;
+      if(seenL[u])continue;seenL[u]=1;
+      if(links.length>=cap){lt=true;break;}
+      links.push({text:(a.textContent||'').trim().slice(0,200),url:u});
+    }
+    var ims=document.querySelectorAll('img[src]');
+    for(var j=0;j<ims.length;j++){
+      var im=ims[j],s=im.src;
+      if(!s||s.indexOf('data:')===0)continue;
+      if(seenI[s])continue;seenI[s]=1;
+      if(images.length>=cap){it=true;break;}
+      var o={url:s};var alt=(im.getAttribute('alt')||'').trim();if(alt)o.alt=alt.slice(0,200);
+      images.push(o);
+    }
+    return {links:links,images:images,truncated:lt||it};
+  })()`;
+}
+/**
+ * Pure: normalize raw extracted page text — collapse runs of whitespace/blank
+ * lines, trim, and cap to `cap` chars (marking truncation). The renderer pulls
+ * raw innerText via CDP; this keeps the cleanup logic testable and consistent.
+ */
+export function cleanPageText(raw, cap = CONTENT_CHAR_CAP) {
+    const normalized = raw
+        .replace(/\r\n?/g, "\n")
+        .replace(/[ \t\f\v]+/g, " ")
+        .replace(/ *\n */g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    if (normalized.length <= cap)
+        return { text: normalized, truncated: false };
+    return { text: normalized.slice(0, cap) + "\n…(truncated)", truncated: true };
+}
+/** Render a snapshot's element list as the compact text block shown to the LLM. */
+export function renderElementList(elements) {
+    if (elements.length === 0)
+        return "(no interactive elements found)";
+    return elements
+        .map((e) => {
+        const namePart = e.name ? ` "${e.name}"` : "";
+        const valuePart = e.sensitive
+            ? " [sensitive]"
+            : e.value
+                ? ` =${JSON.stringify(e.value)}`
+                : "";
+        return `[ref=${e.ref}] ${e.role}${namePart}${valuePart}`;
+    })
+        .join("\n");
+}

package/dist/tool-system/builtin/agent-heartbeat.d.ts

@@ -0,0 +1,49 @@
+/**
+ * AgentHeartbeatPinger (B: background-agent visibility) — while background
+ * sub-agents are running, emit a periodic `agent_heartbeat` per parent session
+ * so the UI knows they're alive even during long LLM-request silence (no
+ * tool_use / no text for minutes). Decided over mtime/event-stream liveness
+ * because the worker KNOWS an agent is mid-request and can keep reporting it,
+ * whereas a quiet event stream looks dead.
+ *
+ * Liveness model deliberately NOT a separate heartbeat-file here — the file +
+ * pid (Heartbeat.ts / isProcessAlive) is for cross-restart interrupted
+ * detection (phase C). This pinger is the live "still working" UI signal only.
+ *
+ * Lifecycle (anti-leak): single timer, stored + cleared; `unref()` so it never
+ * pins the process open; `start()` idempotent; self-stops emitting when no
+ * agent runs but keeps the (unref'd) tick cheap. Mirrors the proven
+ * Heartbeat.ts / chat-session-manager sweeper pattern.
+ */
+import type { StreamEvent } from "../../types.js";
+/** Default 30s — user-chosen. Stale threshold downstream is 3× (90s). */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+export interface AgentHeartbeatConfig {
+    intervalMs?: number;
+    /** Sink for each heartbeat event (server forwards to the client). */
+    publish: (sessionId: string, event: StreamEvent) => void;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+export declare class AgentHeartbeatPinger {
+    private readonly intervalMs;
+    private readonly publish;
+    private readonly now;
+    private timer;
+    constructor(config: AgentHeartbeatConfig);
+    /** Begin periodic heartbeats. Idempotent — a second call is a no-op. */
+    start(): void;
+    stop(): void;
+    /** One heartbeat cycle: group running agents by session and publish. */
+    private tick;
+}
+/**
+ * Process-wide pinger that publishes to the agentNotificationBus (the same
+ * channel background-agent completions use → the protocol server forwards each
+ * event to the client). `ensureRunning()` is called when an agent backgrounds;
+ * the pinger self-stops once no agent is running, so a fresh handoff re-arms it.
+ */
+export declare const agentHeartbeatPinger: AgentHeartbeatPinger;
+/** Start the shared pinger if not already ticking (idempotent). Call when an
+ *  agent enters the background. */
+export declare function ensureAgentHeartbeat(): void;

package/dist/tool-system/builtin/agent-heartbeat.js

@@ -0,0 +1,89 @@
+/**
+ * AgentHeartbeatPinger (B: background-agent visibility) — while background
+ * sub-agents are running, emit a periodic `agent_heartbeat` per parent session
+ * so the UI knows they're alive even during long LLM-request silence (no
+ * tool_use / no text for minutes). Decided over mtime/event-stream liveness
+ * because the worker KNOWS an agent is mid-request and can keep reporting it,
+ * whereas a quiet event stream looks dead.
+ *
+ * Liveness model deliberately NOT a separate heartbeat-file here — the file +
+ * pid (Heartbeat.ts / isProcessAlive) is for cross-restart interrupted
+ * detection (phase C). This pinger is the live "still working" UI signal only.
+ *
+ * Lifecycle (anti-leak): single timer, stored + cleared; `unref()` so it never
+ * pins the process open; `start()` idempotent; self-stops emitting when no
+ * agent runs but keeps the (unref'd) tick cheap. Mirrors the proven
+ * Heartbeat.ts / chat-session-manager sweeper pattern.
+ */
+import { asyncAgentRegistry } from "./agent-registry.js";
+import { agentNotificationBus } from "./agent-notifications.js";
+/** Default 30s — user-chosen. Stale threshold downstream is 3× (90s). */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+export class AgentHeartbeatPinger {
+    intervalMs;
+    publish;
+    now;
+    timer = null;
+    constructor(config) {
+        this.intervalMs = config.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this.publish = config.publish;
+        this.now = config.now ?? Date.now;
+    }
+    /** Begin periodic heartbeats. Idempotent — a second call is a no-op. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.tick(), this.intervalMs);
+        // Never keep the process alive just for heartbeats.
+        if (typeof this.timer === "object" && "unref" in this.timer) {
+            this.timer.unref();
+        }
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** One heartbeat cycle: group running agents by session and publish. */
+    tick() {
+        const running = asyncAgentRegistry.getSnapshot().filter((e) => e.status === "running");
+        if (running.length === 0) {
+            // Nothing left to ping — self-stop so the timer doesn't tick forever
+            // after the last background agent finishes. start() re-arms on the next
+            // handoff. (Idempotent stop.)
+            this.stop();
+            return;
+        }
+        const bySession = new Map();
+        for (const e of running) {
+            // Background agents always carry their spawning sessionId; skip any
+            // legacy/ad-hoc entry without one (can't address a heartbeat to nobody).
+            if (!e.sessionId)
+                continue;
+            const list = bySession.get(e.sessionId);
+            if (list)
+                list.push(e.agentId);
+            else
+                bySession.set(e.sessionId, [e.agentId]);
+        }
+        const ts = this.now();
+        for (const [sessionId, agentIds] of bySession) {
+            this.publish(sessionId, { type: "agent_heartbeat", agentIds, ts });
+        }
+    }
+}
+/**
+ * Process-wide pinger that publishes to the agentNotificationBus (the same
+ * channel background-agent completions use → the protocol server forwards each
+ * event to the client). `ensureRunning()` is called when an agent backgrounds;
+ * the pinger self-stops once no agent is running, so a fresh handoff re-arms it.
+ */
+export const agentHeartbeatPinger = new AgentHeartbeatPinger({
+    publish: (sessionId, event) => agentNotificationBus.publish(sessionId, event),
+});
+/** Start the shared pinger if not already ticking (idempotent). Call when an
+ *  agent enters the background. */
+export function ensureAgentHeartbeat() {
+    agentHeartbeatPinger.start();
+}

package/dist/tool-system/builtin/agent-notifications.d.ts

@@ -1,4 +1,4 @@
-import type { BackgroundAgentCompletedEvent } from "../../types.js";
+import type { BackgroundAgentCompletedEvent, StreamEvent } from "../../types.js";
 /**
  * Background-agent completion notification queue.
  *
@@ -30,8 +30,17 @@ export type NotificationItem = {
     name?: string;
     description: string;
     status: "completed" | "failed";
+    /** What kind of background work this was (lets UIs localize the toast). */
+    workKind?: "agent" | "shell" | "video" | "cc";
+    /** For workKind === "shell": the command that ran. */
+    command?: string;
     /** Final assistant text (completed only). */
     finalText?: string;
+    /** For workKind === "cc": the external claude session id this drove, so the
+     *  result is recoverable from ~/.claude/projects/.../<ccSessionId>.jsonl even
+     *  if this notification is lost, and the user sees a real session id (not just
+     *  an opaque background jobId). */
+    ccSessionId?: string;
     /** Error message (failed only). */
     error?: string;
     enqueuedAt: number;
@@ -53,10 +62,10 @@ declare class NotificationQueue {
     private notify;
 }
 export declare const notificationQueue: NotificationQueue;
-type BusHandler = (sessionId: string, event: BackgroundAgentCompletedEvent) => void;
+type BusHandler = (sessionId: string, event: StreamEvent) => void;
 declare class AgentNotificationBus {
     private handlers;
-    publish(sessionId: string, event: BackgroundAgentCompletedEvent): void;
+    publish(sessionId: string, event: StreamEvent): void;
     subscribe(handler: BusHandler): () => void;
 }
 export declare const agentNotificationBus: AgentNotificationBus;