@cjhyy/code-shell-core 0.7.0 → 0.8.0

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

@@ -1,20 +1,19 @@
 /**
  * BrowserBridge — driver-agnostic contract between the browser tools (core)
- * and whatever drives the actual browser (renderer's webview via CDP).
+ * and whatever drives the actual browser (a renderer webview, hidden main-
+ * process BrowserWindow, or external provider 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.
+ * The core tools only know this interface. Desktop can implement it with a
+ * Playwright-owned context, Electron `webContents.debugger`, or an authorized
+ * Chrome-extension CDP transport. Keeping it driver-agnostic lets those targets
+ * swap without touching the tools. Undefined on ToolContext means the current
+ * host did not provide browser automation, so 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
+    /** Per-snapshot reference id (for example s3:e1); the host maps it back to a
      *  backendDOMNodeId for the action tools. Reassigned each snapshot. */
     ref: string;
     /** ARIA role (button, link, textbox, checkbox, combobox, …). */
@@ -29,26 +28,69 @@ export interface BrowserElement {
 export interface BrowserSnapshot {
     url: string;
     title?: string;
+    /** Main-frame document identity. Changes on every cross-document navigation. */
+    documentId?: string;
+    /** Identity of this exact observation; refs belong only to this snapshot. */
+    snapshotId?: string;
     elements: BrowserElement[];
+    /** Operational/policy failure. Unlike needsHuman, this must not trigger takeover. */
+    detail?: string;
     /** 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 type BrowserResultCode = "OK" | "STALE_SNAPSHOT" | "STALE_CURSOR" | "NO_PROGRESS" | "NAVIGATION" | "BLOCKED" | "NEEDS_HUMAN" | "FAILED";
+export interface BrowserScrollState {
+    x: number;
+    y: number;
+    maxX: number;
+    maxY: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    atTop: boolean;
+    atEnd: boolean;
+}
 export interface BrowserResult {
     ok: boolean;
+    /** Stable machine-readable outcome; detail remains for the model/user. */
+    code?: BrowserResultCode;
+    /** Whether repeating the same operation without a new observation can help. */
+    retryable?: 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;
+    documentId?: string;
+    documentChanged?: boolean;
+    /** Present for scroll-like actions so callers can prove forward progress. */
+    scroll?: BrowserScrollState;
+    contentChanged?: boolean;
+}
+export interface BrowserReadOptions {
+    /** Opaque continuation returned by the previous read call. */
+    cursor?: string;
+    /** Requested chunk size; the driver clamps it to a safe maximum. */
+    maxChars?: number;
 }
 /** Result of reading the page's main textual content (扒内容). */
 export interface BrowserContent {
     ok: boolean;
     url: string;
     title?: string;
+    code?: BrowserResultCode;
+    documentId?: string;
     /** Extracted readable text (main content, scripts/styles/nav stripped). */
     text: string;
-    /** True if the text was truncated to a cap. */
+    /** Cursor represented by this response (the first page uses an implicit start). */
+    cursor?: string;
+    /** Opaque cursor for the next chunk. Absent when done. */
+    nextCursor?: string;
+    /** True when the complete normalized document text has been consumed. */
+    done?: boolean;
+    /** Stable hash of the normalized full text for progress/deduplication. */
+    contentHash?: string;
+    scroll?: BrowserScrollState;
+    /** Compatibility alias for !done. */
     truncated?: boolean;
     detail?: string;
 }
@@ -109,7 +151,7 @@ export interface BrowserBridge {
     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>;
+    readContent(options?: BrowserReadOptions): 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). */

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

@@ -1,16 +1,15 @@
 /**
  * BrowserBridge — driver-agnostic contract between the browser tools (core)
- * and whatever drives the actual browser (renderer's webview via CDP).
+ * and whatever drives the actual browser (a renderer webview, hidden main-
+ * process BrowserWindow, or external provider 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.
+ * The core tools only know this interface. Desktop can implement it with a
+ * Playwright-owned context, Electron `webContents.debugger`, or an authorized
+ * Chrome-extension CDP transport. Keeping it driver-agnostic lets those targets
+ * swap without touching the tools. Undefined on ToolContext means the current
+ * host did not provide browser automation, so tools degrade with a clear error.
  */
 /** Roles we surface as actionable/meaningful to the agent. */
 const INTERACTIVE_ROLES = new Set([
@@ -69,7 +68,7 @@ export function flattenAxTree(nodes) {
         if (node.backendDOMNodeId === undefined)
             continue;
         const sensitive = propValue(node, "protected") === true || // ARIA "protected" → password-like
-            role === "textbox" && /password|密码/i.test(name);
+            (role === "textbox" && /password|密码/i.test(name));
         counter += 1;
         const ref = `e${counter}`;
         refToBackendId[ref] = node.backendDOMNodeId;

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

@@ -21,13 +21,13 @@ 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;
+    publish?: (sessionId: string, event: StreamEvent) => void;
     /** Injectable clock for tests. */
     now?: () => number;
 }
 export declare class AgentHeartbeatPinger {
     private readonly intervalMs;
-    private readonly publish;
+    private readonly publish?;
     private readonly now;
     private timer;
     constructor(config: AgentHeartbeatConfig);

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

@@ -16,7 +16,8 @@
  * Heartbeat.ts / chat-session-manager sweeper pattern.
  */
 import { asyncAgentRegistry } from "./agent-registry.js";
-import { agentNotificationBus } from "./agent-notifications.js";
+import { notificationQueue } from "./agent-notifications.js";
+import { initialAgentProgress } from "./agent-progress.js";
 /** Default 30s — user-chosen. Stale threshold downstream is 3× (90s). */
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
 export class AgentHeartbeatPinger {
@@ -56,20 +57,35 @@ export class AgentHeartbeatPinger {
             return;
         }
         const bySession = new Map();
+        const ts = this.now();
         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;
+            if (!this.publish) {
+                notificationQueue.enqueue({
+                    kind: "progress",
+                    from: {
+                        sessionId: e.childSessionId ?? e.agentId,
+                        agentId: e.agentId,
+                        authority: "agent",
+                    },
+                    to: { sessionId: e.sessionId, authority: "agent" },
+                    delivery: "observe-only",
+                    runtimeGeneration: e.runtimeGeneration,
+                    payload: e.progress ?? initialAgentProgress(ts),
+                });
+                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 });
+            this.publish?.(sessionId, { type: "agent_heartbeat", agentIds, ts });
         }
     }
 }
@@ -79,9 +95,7 @@ export class AgentHeartbeatPinger {
  * 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),
-});
+export const agentHeartbeatPinger = new AgentHeartbeatPinger({});
 /** Start the shared pinger if not already ticking (idempotent). Call when an
  *  agent enters the background. */
 export function ensureAgentHeartbeat() {

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

@@ -1,54 +1,120 @@
 import type { BackgroundAgentCompletedEvent, StreamEvent } from "../../types.js";
-/**
- * Background-agent completion notification queue.
- *
- * Mirrors Claude Code's `commandQueue` with `mode: 'task-notification'`. A
- * background sub-agent that finishes (completed | failed) enqueues an item
- * here; the UI layer subscribes and, when the main agent is idle, drains
- * the queue and submits the formatted XML as a new user turn so the LLM
- * sees the result. Sub-agent cancellation does NOT enqueue (user explicitly
- * stopped the agent; no follow-up needed). DriveAgent cancellation does enqueue
- * so a detached external CLI job never leaves the waiting session hanging.
- *
- * The result text lives only in this queue + the eventual user message —
- * not in `asyncAgentRegistry`. Registry stays metadata-only.
- *
- * Every enqueue must carry a sessionId. The B2 shim that allowed undefined
- * sessionId (a `__legacy__` bucket fallback) is gone — callers without a
- * session context (standalone tool tests) must mint a sessionId or use the
- * test helpers in `tests/` that do. At runtime, a bad sessionId (empty or
- * non-string, e.g. a caller bypassing the type via `as any`) is logged at
- * warn level and dropped — it does NOT touch the buckets or fire the bus.
- *
- * Listeners are still process-wide: any bucket change wakes every
- * subscriber, and each subscriber filters by sessionId when reading
- * `getSnapshot(sid)`. This matches `useSyncExternalStore`'s contract.
- *
- * Process-local singleton; same lifetime contract as `asyncAgentRegistry`.
- */
+export type NotificationAuthority = "user" | "agent" | "system" | "policy";
+export interface NotificationEndpoint {
+    sessionId: string;
+    agentId?: string;
+    authority: NotificationAuthority;
+}
+export type DirectionDelivery = "next-safe-point" | "interrupt-and-redrive";
+export type ProgressDelivery = "observe-only";
+export type ResultDelivery = "idle-drain";
+export type AgentProgressPhase = "starting" | "model" | "tool" | "waiting-permission" | "compacting" | "finalizing";
+export interface AgentProgressTokens {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+export interface AgentProgressLastTool {
+    name: string;
+    state: "running" | "completed" | "failed" | "aborted";
+    startedAt?: number;
+    finishedAt?: number;
+}
+export interface DirectionPayload {
+    prompt: string;
+    origin: "agent_send_input";
+}
+export interface ProgressPayload {
+    phase: AgentProgressPhase;
+    lastTool?: AgentProgressLastTool;
+    tokens: AgentProgressTokens;
+    summary: string;
+    observedAt: number;
+}
+export interface ResultPayload {
+    workId: string;
+    name?: string;
+    description: string;
+    status: "completed" | "failed" | "cancelled";
+    workKind: "agent" | "shell" | "video" | "cc";
+    finalText?: string;
+    error?: string;
+    command?: string;
+    ccSessionId?: string;
+    changedFiles?: string[];
+    cwd?: string;
+    originClientMessageId?: string;
+    finishedAt: number;
+}
+interface NotificationEnvelopeBase<K extends "direction" | "progress" | "result", D extends DirectionDelivery | ProgressDelivery | ResultDelivery, P> {
+    schemaVersion: 1;
+    id: string;
+    kind: K;
+    from: NotificationEndpoint;
+    to: NotificationEndpoint;
+    teamId?: string;
+    correlationId?: string;
+    /** Fences process-local agent runtime generations; trusted producers only. */
+    runtimeGeneration?: number;
+    sequence: number;
+    delivery: D;
+    createdAt: number;
+    payload: P;
+    /** Deprecated read-only aliases kept for one compatibility window. */
+    readonly agentId?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly status?: "completed" | "failed" | "cancelled";
+    readonly workKind?: "agent" | "shell" | "video" | "cc";
+    readonly command?: string;
+    readonly finalText?: string;
+    readonly ccSessionId?: string;
+    readonly error?: string;
+    readonly changedFiles?: string[];
+    readonly cwd?: string;
+    readonly originClientMessageId?: string;
+    readonly enqueuedAt?: number;
+}
+export type DirectionEnvelope = NotificationEnvelopeBase<"direction", DirectionDelivery, DirectionPayload>;
+export type ProgressEnvelope = NotificationEnvelopeBase<"progress", ProgressDelivery, ProgressPayload>;
+export type ResultEnvelope = NotificationEnvelopeBase<"result", ResultDelivery, ResultPayload> & {
+    readonly agentId: string;
+    readonly description: string;
+    readonly status: "completed" | "failed" | "cancelled";
+    readonly enqueuedAt: number;
+};
+export type NotificationEnvelope = DirectionEnvelope | ProgressEnvelope | ResultEnvelope;
+export type DirectionEnvelopeDraft = Omit<DirectionEnvelope, "schemaVersion" | "id" | "sequence" | "createdAt" | "agentId" | "name" | "description" | "status" | "workKind" | "command" | "finalText" | "ccSessionId" | "error" | "changedFiles" | "cwd" | "originClientMessageId" | "enqueuedAt">;
+export type ProgressEnvelopeDraft = Omit<ProgressEnvelope, "schemaVersion" | "id" | "sequence" | "createdAt" | "agentId" | "name" | "description" | "status" | "workKind" | "command" | "finalText" | "ccSessionId" | "error" | "changedFiles" | "cwd" | "originClientMessageId" | "enqueuedAt">;
+export type ResultEnvelopeDraft = Omit<ResultEnvelope, "schemaVersion" | "id" | "sequence" | "createdAt" | "agentId" | "name" | "description" | "status" | "workKind" | "command" | "finalText" | "ccSessionId" | "error" | "changedFiles" | "cwd" | "originClientMessageId" | "enqueuedAt">;
+export type NotificationEnvelopeDraft = DirectionEnvelopeDraft | ProgressEnvelopeDraft | ResultEnvelopeDraft;
+export type DirectionRejectReason = "invalid-request" | "target-not-found" | "target-not-running" | "target-not-ready" | "not-direct-parent" | "cross-session" | "team-not-supported" | "runtime-generation-mismatch" | "intake-closed";
+export type DirectionAck = {
+    status: "queued" | "delivered" | "interrupted";
+    envelopeId: string;
+    sequence: number;
+    correlationId?: string;
+    target: NotificationEndpoint;
+    acceptedAt: number;
+} | {
+    status: "rejected";
+    reason: DirectionRejectReason;
+    target?: NotificationEndpoint;
+    rejectedAt: number;
+};
+/** Deprecated producer shape. Queue storage is always NotificationEnvelope. */
 export type NotificationItem = {
     agentId: string;
     name?: string;
     description: string;
     status: "completed" | "failed" | "cancelled";
-    /** 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/cancelled only). */
     error?: string;
-    /** Files attributed to an external DriveAgent transcript. */
     changedFiles?: string[];
-    /** DriveAgent cwd used to canonicalize path aliases in clients. */
     cwd?: string;
-    /** Client id of the real user turn that launched this background work. */
     originClientMessageId?: string;
     enqueuedAt: number;
 };
@@ -56,45 +122,34 @@ type Listener = () => void;
 declare class NotificationQueue {
     private buckets;
     private listeners;
-    enqueue(item: NotificationItem, sessionId: string): void;
-    subscribe: (cb: Listener) => (() => void);
-    getSnapshot: (sessionId: string) => readonly NotificationItem[];
-    /** Atomic: returns all items for a session and clears that bucket. */
-    drainAll(sessionId: string): NotificationItem[];
-    /**
-     * Clear one bucket (sessionId given) or every bucket (no arg). Used by
-     * tests; production code drains per-session through `drainAll`.
-     */
+    private sequences;
+    private sequenceRoutes;
+    private readonly maxSequenceRoutes;
+    enqueue(draft: NotificationEnvelopeDraft): NotificationEnvelope | undefined;
+    enqueue(item: NotificationItem, sessionId: string): ResultEnvelope | undefined;
+    subscribe: (listener: Listener) => (() => void);
+    getSnapshot: (sessionId: string) => readonly NotificationEnvelope[];
+    drain(sessionId: string, predicate: (envelope: NotificationEnvelope) => boolean): NotificationEnvelope[];
+    /** Compatibility consumer: only terminal results, never direction/progress. */
+    drainAll(sessionId: string): ResultEnvelope[];
+    clearProgress(sessionId: string, agentId: string, runtimeGeneration?: number): boolean;
+    clearDirections(sessionId: string, runtimeGeneration: number): boolean;
     reset(sessionId?: string): void;
     private notify;
 }
-export declare const notificationQueue: NotificationQueue;
-type BusHandler = (sessionId: string, event: StreamEvent) => void;
+type EnvelopeBusHandler = (envelope: NotificationEnvelope) => void;
+type LegacyBusHandler = (sessionId: string, event: StreamEvent) => void;
 declare class AgentNotificationBus {
     private handlers;
-    publish(sessionId: string, event: StreamEvent): void;
-    subscribe(handler: BusHandler): () => void;
+    publish(envelope: NotificationEnvelope): void;
+    subscribe(handler: EnvelopeBusHandler): () => void;
+    subscribe(handler: LegacyBusHandler): () => void;
 }
 export declare const agentNotificationBus: AgentNotificationBus;
-/**
- * Project a queue item to its protocol-event shape. The two types are
- * field-compatible by design (see the comment on BackgroundAgentCompletedEvent
- * in types.ts) so this is essentially an identity tag.
- */
-export declare function notificationItemToStreamEvent(item: NotificationItem): BackgroundAgentCompletedEvent;
-/**
- * Render a batch of completion notifications as the XML user-message
- * body that the main agent's LLM will see. Format is stable — main
- * agent prompts can rely on the `<background-agents-completed>` root
- * tag as a signal that this turn is a system-injected notification,
- * not a real user message.
- */
-export declare function buildNotificationMessage(items: readonly NotificationItem[]): string;
-/**
- * One-line-per-agent human summary for the chat feed. The full result
- * body goes to the LLM via buildNotificationMessage; the user sees only
- * this terse marker plus an optional inline error preview, and can
- * switch to the sub-agent's dock view if they want details.
- */
-export declare function buildNotificationSummary(items: readonly NotificationItem[]): string;
+export declare const notificationQueue: NotificationQueue;
+export declare function buildAgentDirectionMessage(envelopes: readonly DirectionEnvelope[]): string;
+export declare function notificationItemToStreamEvent(value: NotificationItem | ResultEnvelope): BackgroundAgentCompletedEvent;
+export declare function notificationEnvelopeToLegacyStreamEvent(envelope: NotificationEnvelope): StreamEvent | undefined;
+export declare function buildNotificationMessage(values: readonly (NotificationItem | ResultEnvelope)[]): string;
+export declare function buildNotificationSummary(values: readonly (NotificationItem | ResultEnvelope)[]): string;
 export {};