agent-sh 0.2.0 → 0.3.1

package/dist/mcp-server.js

@@ -24,13 +24,27 @@ function sendError(id, code, message) {
     send({ id, error: { code, message } });
 }
 // ── Tool definition ─────────────────────────────────────────────
+const SHELL_CWD_TOOL = {
+    name: "shell_cwd",
+    description: "Get the user's current working directory in their live shell. " +
+        "IMPORTANT: Your internal working directory may differ from the user's actual shell cwd — " +
+        "the user may have cd'd after your session started. Call this tool to get the real cwd " +
+        "before file operations if you're unsure.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+};
 const USER_SHELL_TOOL = {
     name: "user_shell",
     description: "Execute a command in the user's live terminal session. " +
         "Use this for commands that should affect the user's shell state: " +
         "cd, export, source, pushd/popd, alias, etc. " +
         "The command runs in the user's actual shell with their full environment " +
-        "(aliases, functions, PATH), not an isolated subprocess.",
+        "(aliases, functions, PATH), not an isolated subprocess. " +
+        "NOTE: Your internal cwd may be stale — the user may have cd'd. " +
+        "Check the shell context for [shell cwd:...] labels or call shell_cwd " +
+        "to determine the real working directory. Use absolute paths when possible.",
     inputSchema: {
         type: "object",
         properties: {
@@ -46,10 +60,11 @@ const SHELL_RECALL_TOOL = {
     name: "shell_recall",
     description: "Retrieve past shell commands, agent responses, and tool executions from the session history. " +
         "Use this to look up truncated output, search for previous commands or errors, " +
-        "or browse recent exchanges. Three operations: " +
-        '"search" finds exchanges matching a query, ' +
-        '"expand" retrieves full untruncated content by exchange ID, ' +
-        '"browse" lists recent exchange summaries.',
+        "or browse recent exchanges. Each entry shows [shell cwd:...] so you can see " +
+        "which directory commands were run in. Operations: " +
+        '"browse" lists recent exchange summaries with line counts, ' +
+        '"search" finds exchanges matching a regex query, ' +
+        '"expand" retrieves content by exchange ID (use start/end for specific line ranges).',
     inputSchema: {
         type: "object",
         properties: {
@@ -60,13 +75,21 @@ const SHELL_RECALL_TOOL = {
             },
             query: {
                 type: "string",
-                description: 'Search query (required for "search" operation)',
+                description: 'Search query — supports regex (required for "search" operation)',
             },
             ids: {
                 type: "array",
                 items: { type: "number" },
                 description: 'Exchange IDs to expand (required for "expand" operation)',
             },
+            start: {
+                type: "number",
+                description: "Start line number, 1-indexed (optional, for expand)",
+            },
+            end: {
+                type: "number",
+                description: "End line number, inclusive (optional, for expand)",
+            },
         },
     },
 };
@@ -127,14 +150,18 @@ async function handleRequest(id, method, params) {
             // Client acknowledgement — nothing to do
             break;
         case "tools/list":
-            sendResult(id, { tools: [USER_SHELL_TOOL, SHELL_RECALL_TOOL] });
+            sendResult(id, { tools: [SHELL_CWD_TOOL, USER_SHELL_TOOL, SHELL_RECALL_TOOL] });
             break;
         case "tools/call": {
             const toolName = params?.name;
             const args = params?.arguments ?? {};
             try {
                 let text;
-                if (toolName === "user_shell") {
+                if (toolName === "shell_cwd") {
+                    const result = await callSocket("shell/cwd", {});
+                    text = `User's current working directory: ${result.cwd}`;
+                }
+                else if (toolName === "user_shell") {
                     const command = args.command;
                     if (!command || typeof command !== "string") {
                         sendError(id, -32602, "Missing required parameter: command");
@@ -148,6 +175,8 @@ async function handleRequest(id, method, params) {
                         operation: args.operation || "browse",
                         query: args.query,
                         ids: args.ids,
+                        start: args.start,
+                        end: args.end,
                     });
                     text = result.result || "(no results)";
                 }

package/dist/settings.d.ts

@@ -0,0 +1,44 @@
+export declare const CONFIG_DIR: string;
+export interface Settings {
+    /** Extensions to load (npm packages or file paths). */
+    extensions?: string[];
+    /** Max agent query history entries to keep. */
+    historySize?: number;
+    /** Recent exchanges included in agent context window. */
+    contextWindowSize?: number;
+    /** Context budget in bytes (~4 chars per token). */
+    contextBudget?: number;
+    /** Shell output lines before truncation kicks in. */
+    shellTruncateThreshold?: number;
+    /** Lines kept from start of truncated shell output. */
+    shellHeadLines?: number;
+    /** Lines kept from end of truncated shell output. */
+    shellTailLines?: number;
+    /** Max lines for recall expand before requiring line ranges. */
+    recallExpandMaxLines?: number;
+    /** Max command output lines shown inline in TUI. */
+    maxCommandOutputLines?: number;
+    /** Max read tool output lines shown inline in TUI (0 = hide). */
+    readOutputMaxLines?: number;
+    /** Max diff lines shown before "ctrl+o to expand". */
+    diffMaxLines?: number;
+    /** Register MCP server for bridge tools (shell_cwd, user_shell, shell_recall). Default true. */
+    enableMcp?: boolean;
+}
+declare const DEFAULTS: Required<Settings>;
+/** Load settings from disk (cached after first call). */
+export declare function getSettings(): Settings & typeof DEFAULTS;
+/**
+ * Get settings for an extension, namespaced under its key in settings.json.
+ *
+ * Example settings.json:
+ *   { "latex-images": { "dpi": 600, "fgColor": "ffffff" } }
+ *
+ * Usage in extension:
+ *   const config = getExtensionSettings("latex-images", { dpi: 300, fgColor: "d4d4d4" });
+ *   // config.dpi === 600 (overridden), config.fgColor === "ffffff" (overridden)
+ */
+export declare function getExtensionSettings<T extends Record<string, unknown>>(namespace: string, defaults: T): T;
+/** Reset cached settings (for testing or after external edit). */
+export declare function reloadSettings(): void;
+export {};

package/dist/settings.js

@@ -0,0 +1,61 @@
+/**
+ * User settings loaded from ~/.agent-sh/settings.json.
+ *
+ * Settings are loaded once at startup and available synchronously
+ * throughout the app. Unknown keys are preserved on write.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+export const CONFIG_DIR = path.join(os.homedir(), ".agent-sh");
+const SETTINGS_PATH = path.join(CONFIG_DIR, "settings.json");
+const DEFAULTS = {
+    extensions: [],
+    historySize: 500,
+    contextWindowSize: 20,
+    contextBudget: 16384,
+    shellTruncateThreshold: 10,
+    shellHeadLines: 5,
+    shellTailLines: 5,
+    recallExpandMaxLines: 100,
+    maxCommandOutputLines: 3,
+    readOutputMaxLines: 0,
+    diffMaxLines: 20,
+    enableMcp: true,
+};
+let cached = null;
+/** Load settings from disk (cached after first call). */
+export function getSettings() {
+    if (!cached) {
+        try {
+            const raw = fs.readFileSync(SETTINGS_PATH, "utf-8");
+            cached = JSON.parse(raw);
+        }
+        catch {
+            cached = {};
+        }
+    }
+    return { ...DEFAULTS, ...cached };
+}
+/**
+ * Get settings for an extension, namespaced under its key in settings.json.
+ *
+ * Example settings.json:
+ *   { "latex-images": { "dpi": 600, "fgColor": "ffffff" } }
+ *
+ * Usage in extension:
+ *   const config = getExtensionSettings("latex-images", { dpi: 300, fgColor: "d4d4d4" });
+ *   // config.dpi === 600 (overridden), config.fgColor === "ffffff" (overridden)
+ */
+export function getExtensionSettings(namespace, defaults) {
+    const all = getSettings();
+    const ext = all[namespace];
+    if (ext && typeof ext === "object" && !Array.isArray(ext)) {
+        return { ...defaults, ...ext };
+    }
+    return defaults;
+}
+/** Reset cached settings (for testing or after external edit). */
+export function reloadSettings() {
+    cached = null;
+}

package/dist/shell.d.ts

@@ -6,6 +6,7 @@ export declare class Shell implements InputContext {
     private inputHandler;
     private outputParser;
     private paused;
+    private echoSkip;
     private agentActive;
     private isZsh;
     private tmpDir?;

package/dist/shell.js

@@ -10,6 +10,7 @@ export class Shell {
     inputHandler;
     outputParser;
     paused = false;
+    echoSkip = false;
     agentActive = false;
     isZsh = false;
     tmpDir;
@@ -98,6 +99,18 @@ export class Shell {
             ].join("\n") + "\n");
             shellArgs = ["--rcfile", path.join(this.tmpDir, ".bashrc")];
         }
+        // Pause stdin before spawning PTY to avoid TTY contention on macOS.
+        // The PTY will become the controlling terminal for the child shell.
+        const wasRaw = process.stdin.isTTY && process.stdin.isRaw;
+        if (process.stdin.isTTY) {
+            try {
+                process.stdin.setRawMode(false);
+                process.stdin.pause();
+            }
+            catch {
+                // Ignore
+            }
+        }
         this.ptyProcess = pty.spawn(shellBin, shellArgs, {
             name: "xterm-256color",
             cols: opts.cols,
@@ -105,6 +118,18 @@ export class Shell {
             cwd: opts.cwd,
             env,
         });
+        // Restore stdin after PTY is created
+        if (process.stdin.isTTY) {
+            try {
+                process.stdin.resume();
+                if (wasRaw) {
+                    process.stdin.setRawMode(true);
+                }
+            }
+            catch {
+                // Ignore - will be set up later in index.ts
+            }
+        }
         this.bus = opts.bus;
         this.outputParser = new OutputParser(opts.bus, opts.cwd);
         // Ensure temp dir cleanup on abnormal exit (SIGKILL won't fire this,
@@ -178,9 +203,20 @@ export class Shell {
     setupOutput() {
         this.ptyProcess.onData((data) => {
             this.outputParser.processData(data);
-            if (!this.paused) {
-                process.stdout.write(data);
+            if (this.paused)
+                return;
+            // During user_shell exec, skip the command echo (first line)
+            if (this.echoSkip) {
+                const nlIdx = data.indexOf("\n");
+                if (nlIdx === -1)
+                    return;
+                this.echoSkip = false;
+                const rest = data.slice(nlIdx + 1);
+                if (rest)
+                    process.stdout.write(rest);
+                return;
             }
+            process.stdout.write(data);
         });
     }
     setupInput() {
@@ -202,6 +238,7 @@ export class Shell {
         this.bus.on("agent:processing-done", () => {
             this.paused = false;
             this.agentActive = false;
+            this.echoSkip = true;
             this.freshPrompt();
         });
         // Permission prompts need stdout unpaused so the interactive UI renders,
@@ -217,10 +254,12 @@ export class Shell {
         // stdout is paused during agent processing, so PTY output flows through
         // OutputParser (for OSC detection) but never reaches the terminal.
         this.bus.onPipeAsync("shell:exec-request", async (payload) => {
+            this.echoSkip = true;
+            this.paused = false;
+            process.stdout.write("\n");
             const output = await new Promise((resolve, reject) => {
                 const timeout = setTimeout(() => {
                     this.bus.off("shell:command-done", handler);
-                    // Kill any hung command
                     this.ptyProcess.write("\x03");
                     reject(new Error("Shell exec timed out after 30s"));
                 }, 30_000);
@@ -230,10 +269,11 @@ export class Shell {
                     resolve({ output: e.output, cwd: e.cwd });
                 };
                 this.bus.on("shell:command-done", handler);
-                // Start capture and write to PTY
                 this.outputParser.onCommandEntered(payload.command, this.outputParser.getCwd());
                 this.ptyProcess.write(payload.command + "\r");
             });
+            this.paused = true;
+            this.echoSkip = false;
             return { ...payload, output: output.output, cwd: output.cwd, done: true };
         });
     }

package/dist/types.d.ts

@@ -2,6 +2,9 @@ import type { EventBus } from "./event-bus.js";
 import type { ContextManager } from "./context-manager.js";
 import type { AcpClient } from "./acp-client.js";
 import type { ColorPalette } from "./utils/palette.js";
+import type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
+export type { ContentBlock } from "./event-bus.js";
+export type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
 export interface AgentShellConfig {
     agentCommand: string;
     agentArgs: string[];
@@ -24,6 +27,18 @@ export interface ExtensionContext {
     quit: () => void;
     /** Override color palette slots for theming. */
     setPalette: (overrides: Partial<ColorPalette>) => void;
+    /** Register a delimiter-based content transform (e.g. $$...$$ → image). */
+    createBlockTransform: (opts: BlockTransformOptions) => void;
+    /** Register a fenced block transform (e.g. ```lang...``` → code-block). */
+    createFencedBlockTransform: (opts: FencedBlockTransformOptions) => void;
+    /** Read extension-namespaced settings from ~/.agent-sh/settings.json. */
+    getExtensionSettings: <T extends Record<string, unknown>>(namespace: string, defaults: T) => T;
+    /** Register a named handler. */
+    define: (name: string, fn: (...args: any[]) => any) => void;
+    /** Wrap a named handler. Receives `next` (original) + args. */
+    advise: (name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any) => void;
+    /** Call a named handler. */
+    call: (name: string, ...args: any[]) => any;
 }
 export interface TerminalSession {
     id: string;
@@ -49,6 +64,8 @@ export type Exchange = {
     exitCode: number | null;
     outputLines: number;
     outputBytes: number;
+    /** Who initiated this command: "user" (typed) or "agent" (via user_shell). */
+    source: "user" | "agent";
 } | {
     type: "agent_query";
     id: number;

package/dist/utils/ansi.d.ts

@@ -6,7 +6,10 @@ export declare const RED = "\u001B[31m";
 export declare const GRAY = "\u001B[90m";
 export declare const BOLD = "\u001B[1m";
 export declare const RESET = "\u001B[0m";
-/** Measure visible string length, excluding SGR (color/style) sequences. */
+/**
+ * Measure visible string length in terminal columns.
+ * Excludes SGR (color/style) sequences and accounts for CJK double-width chars.
+ */
 export declare function visibleLen(str: string): number;
 /** Strip all ANSI escape sequences (SGR, OSC, CSI, private mode) and carriage returns. */
 export declare function stripAnsi(str: string): string;

package/dist/utils/ansi.js

@@ -8,9 +8,67 @@ export const GRAY = "\x1b[90m";
 export const BOLD = "\x1b[1m";
 export const RESET = "\x1b[0m";
 // ── ANSI utility functions ───────────────────────────────────
-/** Measure visible string length, excluding SGR (color/style) sequences. */
+/**
+ * Check if a Unicode code point is a wide character (CJK, fullwidth, emoji, etc.)
+ * Returns 2 for wide chars, 1 for normal chars.
+ */
+function charWidth(codePoint) {
+    // CJK Unified Ideographs
+    if (codePoint >= 0x4e00 && codePoint <= 0x9fff)
+        return 2;
+    // CJK Unified Ideographs Extension A
+    if (codePoint >= 0x3400 && codePoint <= 0x4dbf)
+        return 2;
+    // Hangul Syllables
+    if (codePoint >= 0xac00 && codePoint <= 0xd7af)
+        return 2;
+    // CJK Unified Ideographs Extension B-F and other CJK blocks
+    if (codePoint >= 0x20000 && codePoint <= 0x2ebef)
+        return 2;
+    // Fullwidth ASCII variants
+    if (codePoint >= 0xff01 && codePoint <= 0xff5e)
+        return 2;
+    // Halfwidth Katakana (actually narrow, skip)
+    // Fullwidth bracket forms
+    if (codePoint >= 0xff5f && codePoint <= 0xff60)
+        return 2;
+    // Fullwidth symbol variants
+    if (codePoint >= 0xffe0 && codePoint <= 0xffe6)
+        return 2;
+    // Japanese hiragana and katakana
+    if (codePoint >= 0x3040 && codePoint <= 0x309f)
+        return 2;
+    if (codePoint >= 0x30a0 && codePoint <= 0x30ff)
+        return 2;
+    // CJK symbols and punctuation
+    if (codePoint >= 0x3000 && codePoint <= 0x303f)
+        return 2;
+    // Enclosed CJK letters and months
+    if (codePoint >= 0x3200 && codePoint <= 0x32ff)
+        return 2;
+    // CJK compatibility
+    if (codePoint >= 0x3300 && codePoint <= 0x33ff)
+        return 2;
+    // Hangul Jamo
+    if (codePoint >= 0x1100 && codePoint <= 0x11ff)
+        return 2;
+    // Hangul compatibility Jamo
+    if (codePoint >= 0x3130 && codePoint <= 0x318f)
+        return 2;
+    return 1;
+}
+/**
+ * Measure visible string length in terminal columns.
+ * Excludes SGR (color/style) sequences and accounts for CJK double-width chars.
+ */
 export function visibleLen(str) {
-    return str.replace(/\x1b\[[^m]*m/g, "").length;
+    // First strip ANSI escape sequences
+    const cleanStr = str.replace(/\x1b\[[^m]*m/g, "");
+    let width = 0;
+    for (const char of cleanStr) {
+        width += charWidth(char.codePointAt(0) ?? 0);
+    }
+    return width;
 }
 /** Strip all ANSI escape sequences (SGR, OSC, CSI, private mode) and carriage returns. */
 export function stripAnsi(str) {

package/dist/utils/box-frame.js

@@ -22,7 +22,8 @@ const BORDERS = {
  * @returns Array of terminal-ready lines with borders
  */
 export function renderBoxFrame(content, opts) {
-    const { width, borderColor = p.dim } = opts;
+    const { width: rawWidth, borderColor = p.dim } = opts;
+    const width = Math.max(6, rawWidth);
     const style = opts.style ?? "rounded";
     const b = BORDERS[style];
     const bc = borderColor;

package/dist/utils/diff-renderer.js

@@ -320,7 +320,7 @@ function renderSplit(diff, opts) {
     const lang = useSyntax ? detectLanguage(opts.filePath) : undefined;
     const totalWidth = opts.width;
     // 3 chars for " │ " separator
-    const colWidth = Math.floor((totalWidth - 3) / 2);
+    const colWidth = Math.max(1, Math.floor((totalWidth - 3) / 2));
     // Compute max line number width
     let maxNo = 0;
     for (const hunk of diff.hunks) {

package/dist/utils/frame-renderer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Differential frame renderer.
+ *
+ * Accepts a frame (string[]) and writes only the lines that changed
+ * compared to the previous frame.  Designed for scrolling content
+ * (not full-screen ownership like pi-tui).
+ *
+ * Fast paths:
+ *   1. First render → write everything
+ *   2. Append-only → write only new lines
+ *   3. Last line changed → \r overwrite (for spinner / partial streaming)
+ *   4. General diff → cursor-up, rewrite changed region, cursor-down
+ */
+import type { OutputWriter } from "./output-writer.js";
+export declare class FrameRenderer {
+    private writer;
+    private prevLines;
+    constructor(writer: OutputWriter);
+    /**
+     * Render a new frame, writing only the diff to the output.
+     * Each line in `lines` should NOT include a trailing newline.
+     */
+    update(lines: string[]): void;
+    /** Reset state — next update will be treated as a first render. */
+    reset(): void;
+}

package/dist/utils/frame-renderer.js

@@ -0,0 +1,76 @@
+export class FrameRenderer {
+    writer;
+    prevLines = [];
+    constructor(writer) {
+        this.writer = writer;
+    }
+    /**
+     * Render a new frame, writing only the diff to the output.
+     * Each line in `lines` should NOT include a trailing newline.
+     */
+    update(lines) {
+        const prev = this.prevLines;
+        if (prev.length === 0) {
+            // Fast path 1: first render
+            for (const line of lines) {
+                this.writer.write(line + "\n");
+            }
+            this.prevLines = lines.slice();
+            return;
+        }
+        // Find first and last changed indices
+        const minLen = Math.min(prev.length, lines.length);
+        let firstChanged = -1;
+        let lastChanged = -1;
+        for (let i = 0; i < minLen; i++) {
+            if (prev[i] !== lines[i]) {
+                if (firstChanged === -1)
+                    firstChanged = i;
+                lastChanged = i;
+            }
+        }
+        // Check for appended or removed lines
+        const appended = lines.length > prev.length;
+        const truncated = lines.length < prev.length;
+        if (firstChanged === -1 && !appended && !truncated) {
+            // No changes at all
+            this.prevLines = lines.slice();
+            return;
+        }
+        if (firstChanged === -1 && appended) {
+            // Fast path 2: only new lines appended, existing unchanged
+            for (let i = prev.length; i < lines.length; i++) {
+                this.writer.write(lines[i] + "\n");
+            }
+            this.prevLines = lines.slice();
+            return;
+        }
+        // General diff: move cursor up to first changed line, rewrite
+        const linesFromBottom = prev.length - (firstChanged === -1 ? prev.length : firstChanged);
+        if (linesFromBottom > 0) {
+            this.writer.write(`\x1b[${linesFromBottom}A`); // cursor up
+        }
+        this.writer.write("\r"); // start of line
+        // Rewrite from firstChanged to end of new frame
+        const start = firstChanged === -1 ? prev.length : firstChanged;
+        for (let i = start; i < lines.length; i++) {
+            this.writer.write(`\x1b[2K${lines[i]}\n`); // clear line + write + newline
+        }
+        // If new frame is shorter, clear remaining old lines
+        if (truncated) {
+            for (let i = lines.length; i < prev.length; i++) {
+                this.writer.write("\x1b[2K\n");
+            }
+            // Move cursor back up to end of new content
+            const extra = prev.length - lines.length;
+            if (extra > 0) {
+                this.writer.write(`\x1b[${extra}A`);
+            }
+        }
+        this.prevLines = lines.slice();
+    }
+    /** Reset state — next update will be treated as a first render. */
+    reset() {
+        this.prevLines = [];
+    }
+}

package/dist/utils/handler-registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Named handler registry with Emacs-style advice.
+ *
+ * Built-in extensions register named handlers with `define`.
+ * User extensions wrap them with `advise` — each advisor receives
+ * `next` (the previous handler) and decides whether to call it.
+ *
+ *   registry.define("render:code-block", (lang, code) => highlight(lang, code));
+ *
+ *   registry.advise("render:code-block", (next, lang, code) => {
+ *     if (lang === "latex") return renderLatex(code);
+ *     return next(lang, code);  // call original
+ *   });
+ */
+export declare class HandlerRegistry {
+    private handlers;
+    /**
+     * Register a named handler. If one already exists, it's replaced.
+     */
+    define(name: string, fn: (...args: any[]) => any): void;
+    /**
+     * Wrap a named handler with advice. The wrapper receives the
+     * previous handler as `next` and all original arguments.
+     *
+     * - Call `next(...args)` to invoke the original (around/before/after)
+     * - Don't call `next` to replace entirely (override)
+     * - Call `next` conditionally to wrap (around)
+     *
+     * Multiple advisors chain: each wraps the previous one.
+     * If no handler exists yet, `next` is a no-op.
+     */
+    advise(name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any): void;
+    /**
+     * Call a named handler. Returns undefined if no handler is registered.
+     */
+    call(name: string, ...args: any[]): any;
+    /**
+     * Check if a named handler exists.
+     */
+    has(name: string): boolean;
+}

package/dist/utils/handler-registry.js

@@ -0,0 +1,52 @@
+/**
+ * Named handler registry with Emacs-style advice.
+ *
+ * Built-in extensions register named handlers with `define`.
+ * User extensions wrap them with `advise` — each advisor receives
+ * `next` (the previous handler) and decides whether to call it.
+ *
+ *   registry.define("render:code-block", (lang, code) => highlight(lang, code));
+ *
+ *   registry.advise("render:code-block", (next, lang, code) => {
+ *     if (lang === "latex") return renderLatex(code);
+ *     return next(lang, code);  // call original
+ *   });
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export class HandlerRegistry {
+    handlers = new Map();
+    /**
+     * Register a named handler. If one already exists, it's replaced.
+     */
+    define(name, fn) {
+        this.handlers.set(name, fn);
+    }
+    /**
+     * Wrap a named handler with advice. The wrapper receives the
+     * previous handler as `next` and all original arguments.
+     *
+     * - Call `next(...args)` to invoke the original (around/before/after)
+     * - Don't call `next` to replace entirely (override)
+     * - Call `next` conditionally to wrap (around)
+     *
+     * Multiple advisors chain: each wraps the previous one.
+     * If no handler exists yet, `next` is a no-op.
+     */
+    advise(name, wrapper) {
+        const original = this.handlers.get(name) ?? (() => undefined);
+        this.handlers.set(name, (...args) => wrapper(original, ...args));
+    }
+    /**
+     * Call a named handler. Returns undefined if no handler is registered.
+     */
+    call(name, ...args) {
+        const fn = this.handlers.get(name);
+        return fn?.(...args);
+    }
+    /**
+     * Check if a named handler exists.
+     */
+    has(name) {
+        return this.handlers.has(name);
+    }
+}