@cjhyy/code-shell-core 0.5.0-rc.0

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

@@ -0,0 +1,197 @@
+import { logger } from "../../logging/logger.js";
+// Stable empty reference so `getSnapshot(sid)` returns the same array
+// identity across calls when the bucket is empty. React's
+// useSyncExternalStore compares snapshots by identity to decide whether
+// to re-render — a fresh `[]` each call would cause render loops.
+const EMPTY = Object.freeze([]);
+/**
+ * Runtime guard for sessionId. The static type is already `string` on
+ * the public surface, but a caller bypassing the type system via
+ * `as any` (or a stale JS-only consumer) could still smuggle in
+ * undefined / "". We refuse those, log once, and let the agent path
+ * continue — a buggy plugin shouldn't crash the engine.
+ */
+function isValidSessionId(sid) {
+    return typeof sid === "string" && sid.length > 0;
+}
+class NotificationQueue {
+    buckets = new Map();
+    listeners = new Set();
+    enqueue(item, sessionId) {
+        if (!isValidSessionId(sessionId)) {
+            logger.warn("notification_queue.invalid_session_id", {
+                agentId: item.agentId,
+                status: item.status,
+                sessionIdType: typeof sessionId,
+            });
+            return;
+        }
+        const next = [...(this.buckets.get(sessionId) ?? []), item];
+        this.buckets.set(sessionId, next);
+        this.notify();
+        // B2.2 — also publish to the protocol-facing bus. The bus is a
+        // separate listener set so existing TUI subscribers (which poll the
+        // queue via getSnapshot/drainAll) are unaffected. The server
+        // subscribes on construction and forwards each event to its client
+        // via the existing `agent/streamEvent` notification path.
+        agentNotificationBus.publish(sessionId, notificationItemToStreamEvent(item));
+    }
+    subscribe = (cb) => {
+        this.listeners.add(cb);
+        return () => {
+            this.listeners.delete(cb);
+        };
+    };
+    getSnapshot = (sessionId) => {
+        if (!isValidSessionId(sessionId))
+            return EMPTY;
+        return this.buckets.get(sessionId) ?? EMPTY;
+    };
+    /** Atomic: returns all items for a session and clears that bucket. */
+    drainAll(sessionId) {
+        if (!isValidSessionId(sessionId))
+            return [];
+        const items = this.buckets.get(sessionId);
+        if (!items || items.length === 0)
+            return [];
+        this.buckets.delete(sessionId);
+        this.notify();
+        return items;
+    }
+    /**
+     * Clear one bucket (sessionId given) or every bucket (no arg). Used by
+     * tests; production code drains per-session through `drainAll`.
+     */
+    reset(sessionId) {
+        if (sessionId === undefined) {
+            if (this.buckets.size === 0)
+                return;
+            this.buckets.clear();
+        }
+        else {
+            if (!this.buckets.has(sessionId))
+                return;
+            this.buckets.delete(sessionId);
+        }
+        this.notify();
+    }
+    notify() {
+        for (const cb of this.listeners) {
+            try {
+                cb();
+            }
+            catch {
+                // isolate per-listener errors
+            }
+        }
+    }
+}
+export const notificationQueue = new NotificationQueue();
+class AgentNotificationBus {
+    handlers = new Set();
+    publish(sessionId, event) {
+        if (!isValidSessionId(sessionId)) {
+            // Mirrors NotificationQueue.enqueue — refuse undefined / "" so the
+            // server-side subscriber never has to defend against it.
+            logger.warn("agent_notification_bus.invalid_session_id", {
+                agentId: event.agentId,
+                status: event.status,
+                sessionIdType: typeof sessionId,
+            });
+            return;
+        }
+        for (const handler of this.handlers) {
+            try {
+                handler(sessionId, event);
+            }
+            catch {
+                // isolate per-listener errors
+            }
+        }
+    }
+    subscribe(handler) {
+        this.handlers.add(handler);
+        return () => {
+            this.handlers.delete(handler);
+        };
+    }
+}
+export const agentNotificationBus = new 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 function notificationItemToStreamEvent(item) {
+    const event = {
+        type: "background_agent_completed",
+        agentId: item.agentId,
+        description: item.description,
+        status: item.status,
+        enqueuedAt: item.enqueuedAt,
+    };
+    if (item.name !== undefined)
+        event.name = item.name;
+    if (item.finalText !== undefined)
+        event.finalText = item.finalText;
+    if (item.error !== undefined)
+        event.error = item.error;
+    return event;
+}
+/**
+ * Escape XML-special characters. We only emit a fixed handful of tags, so
+ * we can hand-roll this rather than pulling in a full encoder. Attribute
+ * values get the quote escape too; element bodies don't need it.
+ */
+function escapeXmlText(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function escapeXmlAttr(s) {
+    return escapeXmlText(s).replace(/"/g, "&quot;");
+}
+/**
+ * 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 function buildNotificationMessage(items) {
+    const agents = items
+        .map((item) => {
+        const nameAttr = item.name ? ` name="${escapeXmlAttr(item.name)}"` : "";
+        const opening = `  <agent id="${escapeXmlAttr(item.agentId)}"${nameAttr} status="${item.status}">`;
+        const desc = `    <description>${escapeXmlText(item.description)}</description>`;
+        const body = item.status === "completed"
+            ? `    <result>\n${escapeXmlText(item.finalText ?? "")}\n    </result>`
+            : `    <error>${escapeXmlText(item.error ?? "")}</error>`;
+        return [opening, desc, body, "  </agent>"].join("\n");
+    })
+        .join("\n");
+    return [
+        "<background-agents-completed>",
+        agents,
+        "</background-agents-completed>",
+        "",
+        "Above are results from background agents that finished while you were idle. Address them appropriately — summarize for the user, continue work, or ignore if no longer relevant.",
+    ].join("\n");
+}
+/**
+ * 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 function buildNotificationSummary(items) {
+    const header = "📨 background agents completed";
+    const rows = items.map((item) => {
+        const badge = item.status === "completed" ? "✓" : "✗";
+        const namePart = item.name ? `${item.name}  ·  ` : "";
+        const statusPart = item.status === "failed" ? `  ·  failed: ${item.error ?? "unknown"}` : "";
+        return `  └─ ${namePart}${item.description}  ·  ${badge}${statusPart}`;
+    });
+    return [header, ...rows].join("\n");
+}

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

@@ -0,0 +1,67 @@
+/**
+ * In-process async agent registry.
+ *
+ * When an Agent tool call uses run_in_background: true, the sub-agent
+ * runs detached from the current turn. We need somewhere to track
+ * agentId → status / result / cancel handle so the parent agent can
+ * later check on it (AgentStatus) or cancel it (AgentCancel).
+ *
+ * Lifetime: process-local. Crashing the process loses these — that's
+ * the same contract Claude Code's Agent.run_in_background gives, and
+ * the right boundary: long-running cross-process work belongs to
+ * RunManager, not here.
+ */
+export type AsyncAgentStatus = "running" | "completed" | "failed" | "cancelled";
+/**
+ * Minimal structural shape for an entry in an agent's transcript. We avoid
+ * importing the UI's `ChatEntry` here to prevent a tool-system → ui import
+ * direction. Consumers (the UI dock) widen this type via `as ChatEntry[]`
+ * at their boundary.
+ */
+export interface AgentTranscriptEntry {
+    id: string;
+    type: string;
+    [key: string]: unknown;
+}
+export interface AsyncAgentEntry {
+    agentId: string;
+    /** Short kind label shown in the dock (e.g. "Explore", "Plan"). */
+    name?: string;
+    description: string;
+    status: AsyncAgentStatus;
+    startedAt: number;
+    finishedAt?: number;
+    /** finishedAt + 30_000. Dock filters rows past this. */
+    finishedFadeAt?: number;
+    abort: () => void;
+    /** Stream events recorded by run_in_background agents for UI view-switching. */
+    transcript?: AgentTranscriptEntry[];
+}
+declare class AsyncAgentRegistry {
+    private agents;
+    private listeners;
+    private snapshot;
+    subscribe: (cb: () => void) => (() => void);
+    getSnapshot: () => AsyncAgentEntry[];
+    hasRunning: () => boolean;
+    private notify;
+    register(entry: AsyncAgentEntry): void;
+    appendToTranscript(agentId: string, entry: AgentTranscriptEntry): void;
+    /**
+     * Re-emit the registry change signal after callers mutate an agent's
+     * transcript array in place (patching or filtering entries). Required
+     * because `notify` rebuilds the snapshot and tells React subscribers to
+     * re-read.
+     */
+    touchTranscript(agentId: string): void;
+    get(agentId: string): AsyncAgentEntry | undefined;
+    list(): AsyncAgentEntry[];
+    private markFinished;
+    markCompleted(agentId: string): void;
+    markFailed(agentId: string): void;
+    markCancelled(agentId: string): void;
+    cancel(agentId: string): boolean;
+    reset(): void;
+}
+export declare const asyncAgentRegistry: AsyncAgentRegistry;
+export {};

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

@@ -0,0 +1,126 @@
+/**
+ * In-process async agent registry.
+ *
+ * When an Agent tool call uses run_in_background: true, the sub-agent
+ * runs detached from the current turn. We need somewhere to track
+ * agentId → status / result / cancel handle so the parent agent can
+ * later check on it (AgentStatus) or cancel it (AgentCancel).
+ *
+ * Lifetime: process-local. Crashing the process loses these — that's
+ * the same contract Claude Code's Agent.run_in_background gives, and
+ * the right boundary: long-running cross-process work belongs to
+ * RunManager, not here.
+ */
+class AsyncAgentRegistry {
+    agents = new Map();
+    listeners = new Set();
+    snapshot = [];
+    // ── observer API (React useSyncExternalStore compatible) ──────────────
+    subscribe = (cb) => {
+        this.listeners.add(cb);
+        return () => {
+            this.listeners.delete(cb);
+        };
+    };
+    getSnapshot = () => {
+        return this.snapshot;
+    };
+    hasRunning = () => {
+        return this.snapshot.some((e) => e.status === "running");
+    };
+    notify() {
+        this.snapshot = [...this.agents.values()];
+        for (const cb of this.listeners) {
+            try {
+                cb();
+            }
+            catch {
+                // isolate per-listener errors
+            }
+        }
+    }
+    // ── mutators ──────────────────────────────────────────────────────────
+    register(entry) {
+        this.agents.set(entry.agentId, entry);
+        this.notify();
+    }
+    appendToTranscript(agentId, entry) {
+        const e = this.agents.get(agentId);
+        if (!e)
+            return;
+        if (!e.transcript)
+            e.transcript = [];
+        e.transcript.push(entry);
+        this.notify();
+    }
+    /**
+     * Re-emit the registry change signal after callers mutate an agent's
+     * transcript array in place (patching or filtering entries). Required
+     * because `notify` rebuilds the snapshot and tells React subscribers to
+     * re-read.
+     */
+    touchTranscript(agentId) {
+        if (!this.agents.has(agentId))
+            return;
+        this.notify();
+    }
+    get(agentId) {
+        return this.agents.get(agentId);
+    }
+    list() {
+        return [...this.agents.values()];
+    }
+    markFinished(agentId, status) {
+        const e = this.agents.get(agentId);
+        if (!e)
+            return;
+        if (e.status !== "running")
+            return;
+        e.status = status;
+        e.finishedAt = Date.now();
+        e.finishedFadeAt = e.finishedAt + 30_000;
+        this.notify();
+    }
+    markCompleted(agentId) {
+        this.markFinished(agentId, "completed");
+    }
+    markFailed(agentId) {
+        this.markFinished(agentId, "failed");
+    }
+    markCancelled(agentId) {
+        this.markFinished(agentId, "cancelled");
+    }
+    cancel(agentId) {
+        const e = this.agents.get(agentId);
+        if (!e)
+            return false;
+        if (e.status !== "running")
+            return false;
+        try {
+            e.abort();
+        }
+        catch {
+            // ignore abort errors — we still mark cancelled
+        }
+        e.status = "cancelled";
+        e.finishedAt = Date.now();
+        e.finishedFadeAt = e.finishedAt + 30_000;
+        this.notify();
+        return true;
+    }
+    reset() {
+        for (const e of this.agents.values()) {
+            if (e.status === "running") {
+                try {
+                    e.abort();
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        this.agents.clear();
+        this.notify();
+    }
+}
+export const asyncAgentRegistry = new AsyncAgentRegistry();

package/dist/tool-system/builtin/agent-transcript-translator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Translate child Engine StreamEvents into ChatEntry-shaped objects so the
+ * AgentDock detail view (which reuses App.renderEntry) can show a sub-agent's
+ * conversation in the same visual language as the main feed.
+ *
+ * The transcript is the canonical record for one background sub-agent. State
+ * (current thinking entry, currently-streaming assistant_text, in-flight
+ * tool_start map) lives in a per-agent translator. Each translator instance
+ * appends ChatEntry-shaped objects via `append` and mutates them via `update`,
+ * mirroring how App.tsx's handleStreamEvent talks to chatStore but isolated to
+ * a single agent's transcript.
+ *
+ * The output shapes intentionally match `src/ui/store.ts#ChatEntryData` so the
+ * existing renderEntry switch picks them up without code changes.
+ */
+import type { StreamEvent } from "../../types.js";
+/**
+ * Create a transcript translator scoped to one background sub-agent. Returned
+ * function is a StreamCallback drop-in: feed it the child Engine's events and
+ * it maintains the agent's transcript in `asyncAgentRegistry`.
+ */
+export declare function createTranscriptTranslator(agentId: string): (event: StreamEvent) => void;

package/dist/tool-system/builtin/agent-transcript-translator.js

@@ -0,0 +1,160 @@
+import { asyncAgentRegistry, } from "./agent-registry.js";
+let entryIdCounter = 0;
+function nextId(agentId) {
+    return `bg-${agentId}-${++entryIdCounter}`;
+}
+/**
+ * Create a transcript translator scoped to one background sub-agent. Returned
+ * function is a StreamCallback drop-in: feed it the child Engine's events and
+ * it maintains the agent's transcript in `asyncAgentRegistry`.
+ */
+export function createTranscriptTranslator(agentId) {
+    // Local state for THIS agent. Background sub-agents run independently so
+    // each gets its own translator; no cross-agent state.
+    let streamingAssistantId;
+    let thinkingId;
+    // toolCallId → tool_start entry id. Lets tool_use_args_delta find the right
+    // tool_start to patch.
+    const toolStartByCallId = new Map();
+    function patchEntry(entryId, patch) {
+        const a = asyncAgentRegistry.get(agentId);
+        if (!a?.transcript)
+            return;
+        const idx = a.transcript.findIndex((e) => e.id === entryId);
+        if (idx < 0)
+            return;
+        a.transcript[idx] = patch(a.transcript[idx]);
+        asyncAgentRegistry.touchTranscript(agentId);
+    }
+    function dropEntry(entryId) {
+        const a = asyncAgentRegistry.get(agentId);
+        if (!a?.transcript)
+            return;
+        a.transcript = a.transcript.filter((e) => e.id !== entryId);
+        asyncAgentRegistry.touchTranscript(agentId);
+    }
+    function append(data) {
+        const id = nextId(agentId);
+        asyncAgentRegistry.appendToTranscript(agentId, {
+            ...data,
+            id,
+        });
+        return id;
+    }
+    return (event) => {
+        switch (event.type) {
+            // ── thinking ─────────────────────────────────────────────────
+            case "stream_request_start": {
+                if (thinkingId) {
+                    dropEntry(thinkingId);
+                    thinkingId = undefined;
+                }
+                thinkingId = append({ type: "thinking", agentId });
+                break;
+            }
+            case "thinking_delta": {
+                // Sub-agent thinking content is collapsed in the dock view — we
+                // don't replicate the verb spinner. Keep the empty thinking
+                // placeholder; renderEntry shows it as a spinner row.
+                break;
+            }
+            // ── assistant text (streaming) ───────────────────────────────
+            case "text_delta": {
+                if (thinkingId) {
+                    dropEntry(thinkingId);
+                    thinkingId = undefined;
+                }
+                if (streamingAssistantId) {
+                    patchEntry(streamingAssistantId, (e) => ({
+                        ...e,
+                        text: String(e.text ?? "") + event.text,
+                    }));
+                }
+                else {
+                    streamingAssistantId = append({
+                        type: "assistant_text",
+                        text: event.text,
+                        streaming: true,
+                        agentId,
+                    });
+                }
+                break;
+            }
+            // ── tool call ────────────────────────────────────────────────
+            case "tool_use_start": {
+                if (streamingAssistantId) {
+                    patchEntry(streamingAssistantId, (e) => ({ ...e, streaming: false }));
+                    streamingAssistantId = undefined;
+                }
+                if (thinkingId) {
+                    dropEntry(thinkingId);
+                    thinkingId = undefined;
+                }
+                const tc = event.toolCall;
+                const startId = append({
+                    type: "tool_start",
+                    toolName: tc.toolName,
+                    args: tc.args,
+                    toolCallId: tc.id,
+                    agentId,
+                });
+                if (tc.id)
+                    toolStartByCallId.set(tc.id, startId);
+                append({ type: "tool_running", toolName: tc.toolName, agentId });
+                break;
+            }
+            case "tool_use_args_delta": {
+                const ev = event;
+                const startId = toolStartByCallId.get(ev.toolCallId);
+                if (!startId)
+                    break;
+                patchEntry(startId, (e) => ({ ...e, args: ev.args }));
+                break;
+            }
+            case "tool_result": {
+                const r = event.result;
+                const a = asyncAgentRegistry.get(agentId);
+                if (a?.transcript) {
+                    a.transcript = a.transcript.filter((e) => !(e.type === "tool_running" && e.toolName === r.toolName));
+                    asyncAgentRegistry.touchTranscript(agentId);
+                }
+                append({
+                    type: "tool_result",
+                    toolName: r.toolName,
+                    result: r.result,
+                    error: r.error,
+                    agentId,
+                });
+                break;
+            }
+            // ── lifecycle: finalize streaming on turn end ───────────────
+            case "turn_complete":
+            case "tombstone": {
+                if (streamingAssistantId) {
+                    patchEntry(streamingAssistantId, (e) => ({ ...e, streaming: false }));
+                    streamingAssistantId = undefined;
+                }
+                if (thinkingId) {
+                    dropEntry(thinkingId);
+                    thinkingId = undefined;
+                }
+                break;
+            }
+            // ── errors surface as a card in the transcript ──────────────
+            case "error": {
+                if (thinkingId) {
+                    dropEntry(thinkingId);
+                    thinkingId = undefined;
+                }
+                append({
+                    type: "error",
+                    error: event.error,
+                    agentId,
+                });
+                break;
+            }
+            default:
+                break;
+        }
+    };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Built-in Agent tool — spawn a sub-agent to handle a task.
+ *
+ * Creates a new Engine instance with its own transcript,
+ * runs the task to completion, and returns the result text.
+ * Supports AbortSignal for cascading cancellation.
+ * Supports onStream for real-time output passthrough.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const agentToolDef: ToolDefinition;
+export declare function agentTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const agentStatusToolDef: ToolDefinition;
+export declare function agentStatusTool(args: Record<string, unknown>): Promise<string>;
+export declare const agentCancelToolDef: ToolDefinition;
+export declare function agentCancelTool(args: Record<string, unknown>): Promise<string>;