agent-sh 0.14.10 → 0.15.0

package/dist/cli/install.js

@@ -14,7 +14,16 @@ const EXT_DIR = path.join(CONFIG_DIR, "extensions");
 export function listBundled() {
     if (!fs.existsSync(BUNDLED_DIR))
         return [];
-    return fs.readdirSync(BUNDLED_DIR).map((n) => n.replace(/\.(ts|js|mjs)$/, ""));
+    const out = [];
+    for (const d of fs.readdirSync(BUNDLED_DIR, { withFileTypes: true })) {
+        if (d.name.startsWith("."))
+            continue;
+        if (d.isDirectory())
+            out.push(d.name);
+        else if (SCRIPT_EXTS.some((ext) => d.name.endsWith(ext)))
+            out.push(d.name.replace(/\.[^.]+$/, ""));
+    }
+    return out;
 }
 /** Heuristic: a backend named "pi" is typically provided by an extension called "pi-bridge". */
 export function suggestBridgeFor(backend) {
@@ -181,6 +190,32 @@ function rewriteFileDeps(target, sourcePath) {
     if (changed)
         fs.writeFileSync(pkgJson, `${JSON.stringify(pkg, null, 2)}\n`);
 }
+/** --dev: repoint the extension's agent-sh dep at the running host's package
+ *  root, so the install builds and runs against the local (possibly unreleased)
+ *  core instead of the published registry version. npm links the file: path, so
+ *  later core rebuilds flow through without reinstalling. */
+function pinHostCore(target) {
+    const pkgJson = path.join(target, "package.json");
+    if (!fs.existsSync(pkgJson))
+        return;
+    const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
+    const sections = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+    let changed = false;
+    for (const section of sections) {
+        const deps = pkg[section];
+        if (!deps || typeof deps !== "object")
+            continue;
+        const d = deps;
+        if (typeof d["agent-sh"] !== "string")
+            continue;
+        d["agent-sh"] = `file:${PACKAGE_ROOT}`;
+        changed = true;
+    }
+    if (!changed)
+        return;
+    fs.writeFileSync(pkgJson, `${JSON.stringify(pkg, null, 2)}\n`);
+    console.log(`agent-sh: --dev — linking ${path.basename(target)} against host core at ${PACKAGE_ROOT}`);
+}
 function maybeNpmInstall(target, pkg) {
     const deps = { ...(pkg.dependencies ?? {}), ...(pkg.peerDependencies ?? {}) };
     if (Object.keys(deps).length === 0)
@@ -243,7 +278,7 @@ function linkBins(target, pkg) {
 }
 export async function runInstall(spec, opts = {}) {
     if (!spec) {
-        console.error("Usage: agent-sh install <name|file:|npm:|github:> [--force] [--sync-deps]\n\n" +
+        console.error("Usage: agent-sh install <name|file:|npm:|github:> [--force] [--sync-deps] [--dev]\n\n" +
             "Bundled extensions:\n" +
             listBundled()
                 .map((n) => `  ${n}`)
@@ -277,6 +312,8 @@ export async function runInstall(spec, opts = {}) {
         });
         try {
             rewriteFileDeps(target, resolved.sourcePath);
+            if (opts.dev)
+                pinHostCore(target);
             syncAgentShVersion(target, opts.syncDeps ?? false);
             const pkg = readPackageJson(target);
             if (pkg) {

package/dist/cli/subcommands.js

@@ -6,6 +6,7 @@ const SUBCOMMANDS = {
     install: (args) => runInstall(args[0] ?? "", {
         force: args.includes("--force"),
         syncDeps: args.includes("--sync-deps"),
+        dev: args.includes("--dev"),
     }),
     uninstall: (args) => runUninstall(args[0] ?? ""),
     list: () => runList(),

package/dist/core/event-bus.js

@@ -159,9 +159,7 @@ export class EventBus {
      * returns the original payload unchanged (with safe defaults).
      */
     async emitPipeAsync(event, payload) {
-        // Phase 1: notify (lets renderers prepare for interactive I/O)
         this.dispatch(event, payload);
-        // Phase 2: transform (extensions provide decisions)
         const listeners = this.asyncPipeListeners.get(event);
         if (!listeners)
             return payload;

package/dist/core/extension-loader.js

@@ -119,7 +119,9 @@ function createScopedContext(ctx, extensionName) {
         onDispose: (fn) => { cleanups.push(fn); },
     };
     const dispose = () => {
-        for (const fn of cleanups) {
+        // Snapshot: a re-registering cleanup appends a new cleanup, and iterating
+        // the live array would run it and undo the restore in the same pass.
+        for (const fn of cleanups.slice()) {
             try {
                 fn();
             }

package/dist/core/index.d.ts

@@ -13,7 +13,7 @@ import { HandlerRegistry } from "../utils/handler-registry.js";
 export { EventBus } from "./event-bus.js";
 export type { BusEvents, ContentBlock, BackendRegistration } from "./event-bus.js";
 export type { CoreContext, CoreConfig } from "./types.js";
-export type { AgentContext, AgentConfig, AgentSurface, AgentConfigSurface, AgentMode, LlmInterface, LlmMessage, LlmSession } from "../agent/host-types.js";
+export type { AgentContext, AgentConfig, AgentSurface, AgentConfigSurface, Model, LlmInterface, LlmMessage, LlmSession } from "../agent/host-types.js";
 export type { ShellContext, ShellConfig, ShellSurface, ShellConfigSurface, ExtensionContext, RemoteSession, RemoteSessionOptions, RenderSurface, InputModeConfig, TerminalSession, BlockTransformOptions, FencedBlockTransformOptions, AppConfig } from "../shell/host-types.js";
 export { palette, setPalette, resetPalette } from "../utils/palette.js";
 export type { ColorPalette } from "../utils/palette.js";

package/dist/core/index.js

@@ -29,10 +29,11 @@ export function createCore(config) {
     bus.setSource(instanceId);
     handlers.define("config:get-app-config", () => config);
     handlers.define("cwd", () => process.cwd());
-    // Empty defaults so registerContextProducer can advise regardless of
-    // backend. Each backend chooses how to consume the strings.
+    // Empty defaults so advisors can wrap these regardless of load order;
+    // system-prompt:frontend is where the active frontend describes its surface.
     handlers.define("dynamic-context:build", () => "");
     handlers.define("query-context:build", () => "");
+    handlers.define("system-prompt:frontend", () => "");
     const backends = new Map();
     let activeBackendName = null;
     bus.on("agent:register-backend", (backend) => {

package/dist/extensions/slash-commands/index.js

@@ -41,16 +41,21 @@ export default function activate(ctx) {
         description: "Cycle to next model, or switch to a specific one",
         handler: (args) => {
             const name = args.trim();
+            const { models, active } = bus.emitPipe("config:get-models", { models: [], active: null });
             if (!name) {
-                const { active } = bus.emitPipe("config:get-models", { models: [], active: null });
-                const label = active
-                    ? `${active.model}${active.provider ? ` [${active.provider}]` : ""}`
-                    : "none";
+                const label = active ? `${active.id} [${active.provider}]` : "none";
                 bus.emit("ui:info", { message: `Model: ${label}` });
+                return;
             }
-            else {
-                bus.emit("config:switch-model", { model: name });
+            const atIdx = name.lastIndexOf("@");
+            const id = atIdx > 0 ? name.slice(0, atIdx) : name;
+            const providerHint = atIdx > 0 ? name.slice(atIdx + 1) : undefined;
+            const found = models.find((m) => m.id === id && (!providerHint || m.provider === providerHint));
+            if (!found) {
+                bus.emit("ui:error", { message: `Unknown model: ${name}` });
+                return;
             }
+            bus.emit("config:switch-model", { id: found.id, provider: found.provider });
         },
     });
     register({
@@ -163,16 +168,16 @@ export default function activate(ctx) {
         const { models, active } = bus.emitPipe("config:get-models", { models: [], active: null });
         const counts = new Map();
         for (const m of models)
-            counts.set(m.model, (counts.get(m.model) ?? 0) + 1);
+            counts.set(m.id, (counts.get(m.id) ?? 0) + 1);
         const items = models
-            .filter((m) => m.model.toLowerCase().includes(partial))
+            .filter((m) => m.id.toLowerCase().includes(partial))
             .slice(0, 15)
             .map((m) => {
-            const ambiguous = (counts.get(m.model) ?? 0) > 1 && m.provider;
-            const qualified = ambiguous ? `${m.model}@${m.provider}` : m.model;
+            const ambiguous = (counts.get(m.id) ?? 0) > 1;
+            const qualified = ambiguous ? `${m.id}@${m.provider}` : m.id;
             return {
                 name: `/model ${qualified}`,
-                description: `${m.provider ? `[${m.provider}]` : ""}${active && m.model === active.model && m.provider === active.provider ? " (active)" : ""}`,
+                description: `[${m.provider}]${active && m.id === active.id && m.provider === active.provider ? " (active)" : ""}`,
             };
         });
         if (items.length === 0)

package/dist/shell/events.d.ts

@@ -32,6 +32,9 @@ declare module "../core/event-bus.js" {
             cols: number;
             rows: number;
         };
+        "shell:host-write": {
+            data: string;
+        };
         "shell:buffer-request": Record<string, never>;
         "shell:buffer-snapshot": {
             text: string;

package/dist/shell/index.js

@@ -7,11 +7,13 @@ import "./events.js"; // augments BusEvents with shell-owned events
 import { Shell } from "./shell.js";
 import { DefaultCompositor } from "../utils/compositor.js";
 import { TerminalBuffer } from "../utils/terminal-buffer.js";
+import { FloatingPanel } from "../utils/floating-panel.js";
 import { setPalette } from "../utils/palette.js";
 import * as streamTransform from "../utils/stream-transform.js";
 import activateShellContext from "./shell-context.js";
 import activateTuiRenderer from "./tui-renderer.js";
 import { processTerminal, surfaceFromTerminal } from "./terminal.js";
+const SHELL_SURFACE = `You're attached through a terminal shell. It shares the user's working directory, environment, and command history, and you can act on their live session — everything they run at the prompt is visible to you.`;
 /**
  * Register shell-owned handlers extensions can `ctx.call`, and attach
  * the shell surface to ctx. Must run before `loadExtensions` so user
@@ -20,6 +22,10 @@ import { processTerminal, surfaceFromTerminal } from "./terminal.js";
 export function registerShellHandlers(ctx) {
     const { bus } = ctx;
     const compositor = new DefaultCompositor(bus);
+    ctx.advise("system-prompt:frontend", (next) => {
+        const base = next() ?? "";
+        return base ? `${base}\n\n${SHELL_SURFACE}` : SHELL_SURFACE;
+    });
     const shellSurface = {
         compositor,
         setPalette,
@@ -69,6 +75,9 @@ export function registerShellHandlers(ctx) {
         terminalBufferSingleton = TerminalBuffer.createWired(ctx.bus);
         return terminalBufferSingleton;
     });
+    // bus override lets callers pass their scoped bus, so the panel's
+    // listeners unwire when the extension reloads.
+    ctx.define("floating-panel:create", (config, bus) => new FloatingPanel(bus ?? ctx.bus, config));
     activateShellContext(ctx);
     activateTuiRenderer(ctx);
 }

package/dist/shell/shell-context.d.ts

@@ -1,5 +1,5 @@
 /** Tracks PTY commands and cwd, spills long outputs, contributes per-query
- *  `<cwd>` (always) and `<shell_events>` (fresh user exchanges). Frontends
- *  without a PTY skip this and fall back to core's process.cwd() default. */
+ *  `<shell_events>` (fresh user exchanges) and — under the shell frontend —
+ *  `<cwd>`. Frontends without a PTY skip this. */
 import type { ExtensionContext } from "./host-types.js";
 export default function activate(ctx: ExtensionContext): void;

package/dist/shell/shell-context.js

@@ -1,7 +1,15 @@
 import { getSettings } from "../core/settings.js";
 import { spillOutput } from "../utils/shell-output-spill.js";
+// The cwd-drift note applies only under the shell frontend (where the agent shares
+// the user's cwd); other frontends own a fixed cwd.
+const SHELL_EVENTS_NOTE = `When the user runs shell commands, they appear as \`<shell_events>\` inside \`<query_context>\` on your next turn — use them to ground "fix this" / "what just happened" requests.`;
+const CWD_DRIFT_NOTE = `\`<cwd>\` is the working directory your own tool calls run in: relative paths resolve against it, and it follows the user's shell \`cd\`, so it can change from one turn to the next. Always act on the latest \`<cwd>\`, not one from earlier in the conversation.`;
+const PREFERENCES_NOTE = `Treat the user's commands as standing preferences: check them for recurring patterns and apply them proactively, without waiting to be asked.`;
 export default function activate(ctx) {
     const { bus } = ctx;
+    // The agent shares the user's cwd only under the shell frontend (which installs
+    // ctx.shell); other frontends — e.g. ashi — keep their own fixed cwd.
+    const ownsAgentCwd = !!ctx.shell;
     const exchanges = [];
     let nextId = 1;
     let currentCwd = process.cwd();
@@ -50,23 +58,30 @@ export default function activate(ctx) {
     bus.on("shell:agent-exec-start", () => { agentShellActive = true; });
     bus.on("shell:agent-exec-done", () => { agentShellActive = false; });
     bus.on("shell:user-exec-exclude-next", () => { nextUserExcluded = true; });
-    ctx.advise("cwd", () => currentCwd);
+    if (ownsAgentCwd)
+        ctx.advise("cwd", () => currentCwd);
     // Advise the core handler directly: this loads before the agent host
     // attaches `ctx.agent`, so the sugar isn't available yet.
     ctx.advise("query-context:build", (next) => {
         const base = next();
-        const part = (() => {
-            const cwdTag = `<cwd>${currentCwd}</cwd>`;
-            const fresh = exchanges.filter((ex) => ex.id > lastSeq && ex.source === "user");
-            if (fresh.length === 0)
-                return cwdTag;
+        const fresh = exchanges.filter((ex) => ex.id > lastSeq && ex.source === "user");
+        let shellEvents = "";
+        if (fresh.length > 0) {
             lastSeq = exchanges[exchanges.length - 1].id;
             const text = fresh.map(formatExchangeTruncated).filter(Boolean).join("\n");
-            if (!text)
-                return cwdTag;
-            return `${cwdTag}\n<shell_events>\n${text}\n</shell_events>`;
-        })();
-        return base ? `${base}\n\n${part}` : part;
+            if (text)
+                shellEvents = `<shell_events>\n${text}\n</shell_events>`;
+        }
+        const part = ownsAgentCwd
+            ? [`<cwd>${currentCwd}</cwd>`, shellEvents].filter(Boolean).join("\n")
+            : shellEvents;
+        return [base, part].filter(Boolean).join("\n\n");
+    });
+    bus.onPipe("agent:instructions", (acc) => {
+        const text = [SHELL_EVENTS_NOTE, ownsAgentCwd ? CWD_DRIFT_NOTE : "", PREFERENCES_NOTE]
+            .filter(Boolean).join("\n\n");
+        acc.instructions.push({ name: "shell-events", text });
+        return acc;
     });
     ctx.define("shell:context-recent", (n = 25) => {
         const recent = exchanges.slice(-n);

package/dist/shell/shell.js

@@ -110,6 +110,9 @@ export class Shell {
         this.bus.on("shell:pty-resize", ({ cols, rows }) => {
             this.ptyProcess.resize(cols, rows);
         });
+        this.bus.on("shell:host-write", ({ data }) => {
+            this.terminal.write(data);
+        });
         // Compat shims for the bus-event API. shell:stdout-hold maps to hard
         // mute so terminal_keys' stdout-show can't paint through the overlay.
         let holdRefcount = 0;

package/dist/shell/tui-renderer.js

@@ -222,7 +222,6 @@ export default function activate(ctx) {
             }
         }
     });
-    // Track token usage for display
     let pendingUsage = null;
     bus.on("agent:usage", (e) => { pendingUsage = e; });
     bus.on("agent:response-done", () => {

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

@@ -13,6 +13,10 @@ export interface DiffRenderOptions {
     trueColor?: boolean;
     /** Enable syntax highlighting on diff lines. Default true. */
     syntaxHighlight?: boolean;
+    /** Draw the `│` rule between the line number and the code (default true). Set false
+     *  for a flush gutter: `<n> <sigil><code>`, the row background spans the line, and
+     *  context code is left un-dimmed. */
+    gutterLine?: boolean;
 }
 export declare function detectLanguage(filePath?: string): string | undefined;
 /**

package/dist/utils/diff-renderer.js

@@ -176,17 +176,14 @@ function findChangePairs(hunk) {
     const lines = hunk.lines;
     let i = 0;
     while (i < lines.length) {
-        // Find a run of removed lines
         const removedStart = i;
         while (i < lines.length && lines[i].type === "removed")
             i++;
         const removedEnd = i;
-        // Find a run of added lines immediately after
         const addedStart = i;
         while (i < lines.length && lines[i].type === "added")
             i++;
         const addedEnd = i;
-        // Pair them 1:1
         const removedCount = removedEnd - removedStart;
         const addedCount = addedEnd - addedStart;
         const pairCount = Math.min(removedCount, addedCount);
@@ -239,25 +236,35 @@ function unifiedLayout(diff, opts) {
         lineTextW: Math.max(1, textWidth - noW - 5),
         textWidth,
         useTrueColor: opts.trueColor !== false,
+        gutterLine: opts.gutterLine !== false,
         lang: opts.syntaxHighlight !== false ? detectLanguage(opts.filePath) : undefined,
         removedPalette: { rowBg: p.errorBg, emphBg: p.errorBgEmph },
         addedPalette: { rowBg: p.successBg, emphBg: p.successBgEmph },
     };
 }
 function renderUnifiedHunk(hunk, layout) {
-    const { noW, lineTextW, textWidth, useTrueColor, lang, removedPalette, addedPalette } = layout;
+    const { noW, lineTextW, textWidth, useTrueColor, gutterLine, lang, removedPalette, addedPalette } = layout;
     const out = [];
     const pairs = findChangePairs(hunk);
     const renderedAsPartOfPair = new Set();
     const bgWidth = Math.max(1, textWidth - noW - 3);
     const gutter = (n) => `${p.dim}${n} │${p.reset} `;
+    const change = (no, sigil, bg, fg, text) => {
+        if (!gutterLine) {
+            return `${bg}${fg}${padToWidth(`${no} ${sigil} ${preserveBg(text, bg)}`, textWidth)}${p.reset}`;
+        }
+        if (useTrueColor)
+            return gutter(no) + padToWidth(`${bg}${fg}${sigil} ${preserveBg(text, bg)}`, bgWidth) + p.reset;
+        return `${gutter(no)}${fg}${sigil} ${text}${p.reset}`;
+    };
     for (let i = 0; i < hunk.lines.length; i++) {
         const line = hunk.lines[i];
         const no = String(line.type === "removed" ? (line.oldNo ?? "") : (line.newNo ?? line.oldNo ?? "")).padStart(noW);
         if (line.type === "context") {
             const raw = truncateText(line.text, lineTextW);
             const text = lang ? highlightLine(raw, lang) : raw;
-            out.push(`${gutter(no)}  ${p.dim}${text}${p.reset}`);
+            // The flush gutter dims only the line number; the code stays normal/highlighted.
+            out.push(!gutterLine ? `${p.dim}${no}${p.reset}   ${text}` : `${gutter(no)}  ${p.dim}${text}${p.reset}`);
             continue;
         }
         if (line.type === "removed") {
@@ -276,19 +283,9 @@ function renderUnifiedHunk(hunk, layout) {
                 const raw = truncateText(line.text, lineTextW);
                 removedText = lang ? highlightLine(raw, lang) : raw;
             }
-            if (useTrueColor) {
-                out.push(gutter(no) + padToWidth(`${p.errorBg}${p.error}- ${preserveBg(removedText, p.errorBg)}`, bgWidth) + p.reset);
-            }
-            else {
-                out.push(`${gutter(no)}${p.error}- ${removedText}${p.reset}`);
-            }
+            out.push(change(no, "-", p.errorBg, p.error, removedText));
             if (addedText !== null && addedNo !== null) {
-                if (useTrueColor) {
-                    out.push(gutter(addedNo) + padToWidth(`${p.successBg}${p.success}+ ${preserveBg(addedText, p.successBg)}`, bgWidth) + p.reset);
-                }
-                else {
-                    out.push(`${gutter(addedNo)}${p.success}+ ${addedText}${p.reset}`);
-                }
+                out.push(change(addedNo, "+", p.successBg, p.success, addedText));
             }
             continue;
         }
@@ -297,12 +294,7 @@ function renderUnifiedHunk(hunk, layout) {
                 continue;
             const raw = truncateText(line.text, lineTextW);
             const text = lang ? highlightLine(raw, lang) : raw;
-            if (useTrueColor) {
-                out.push(gutter(no) + padToWidth(`${p.successBg}${p.success}+ ${preserveBg(text, p.successBg)}`, bgWidth) + p.reset);
-            }
-            else {
-                out.push(`${gutter(no)}${p.success}+ ${text}${p.reset}`);
-            }
+            out.push(change(no, "+", p.successBg, p.success, text));
         }
     }
     return out;
@@ -423,19 +415,16 @@ function buildSplitRows(hunk) {
             i++;
             continue;
         }
-        // Collect a run of removed lines
         const removed = [];
         while (i < lines.length && lines[i].type === "removed") {
             removed.push(lines[i]);
             i++;
         }
-        // Collect a run of added lines
         const added = [];
         while (i < lines.length && lines[i].type === "added") {
             added.push(lines[i]);
             i++;
         }
-        // Pair them side by side
         const maxLen = Math.max(removed.length, added.length);
         for (let k = 0; k < maxLen; k++) {
             rows.push({
@@ -522,7 +511,6 @@ function trimHunksToFit(hunks, maxLines) {
                 changeCount++;
         }
     }
-    // Separators between hunks
     const separators = Math.max(0, hunks.length - 1);
     // How many context lines can we afford?
     const contextBudget = Math.max(0, maxLines - changeCount - separators);

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

@@ -50,13 +50,8 @@ export declare class HandlerRegistry {
      * Returns undefined if no handler is registered.
      */
     call(name: string, ...args: any[]): any;
-    /**
-     * Check if a named handler exists.
-     */
     has(name: string): boolean;
-    /**
-     * Names of all registered handlers. For diagnostic/introspection use.
-     */
+    /** Names of all registered handlers — for diagnostics/introspection. */
     list(): string[];
 }
 export {};

package/dist/utils/handler-registry.js

@@ -79,15 +79,10 @@ export class HandlerRegistry {
         }
         return fn(...args);
     }
-    /**
-     * Check if a named handler exists.
-     */
     has(name) {
         return this.entries.has(name);
     }
-    /**
-     * Names of all registered handlers. For diagnostic/introspection use.
-     */
+    /** Names of all registered handlers — for diagnostics/introspection. */
     list() {
         return [...this.entries.keys()];
     }

package/dist/utils/line-editor.js

@@ -309,11 +309,9 @@ export class LineEditor {
     pushHistory(line) {
         if (!line.trim())
             return;
-        // Deduplicate: remove if already at top
         if (this.history.length > 0 && this.history[0] === line)
             return;
         this.history.unshift(line);
-        // Cap history size
         if (this.history.length > 100)
             this.history.pop();
     }

package/dist/utils/palette.js

@@ -14,10 +14,10 @@ const defaultPalette = {
     warning: "\x1b[33m", // yellow
     error: "\x1b[31m", // red
     muted: "\x1b[90m", // gray
-    successBg: "\x1b[48;2;0;60;0m",
-    errorBg: "\x1b[48;2;50;0;0m",
-    successBgEmph: "\x1b[48;2;0;112;0m",
-    errorBgEmph: "\x1b[48;2;90;0;0m",
+    successBg: "\x1b[48;2;34;92;43m",
+    errorBg: "\x1b[48;2;122;41;54m",
+    successBgEmph: "\x1b[48;2;56;166;96m",
+    errorBgEmph: "\x1b[48;2;179;89;107m",
     bold: "\x1b[1m",
     dim: "\x1b[2m",
     italic: "\x1b[3m",

package/dist/utils/terminal-buffer.d.ts

@@ -47,6 +47,8 @@ export declare class TerminalBuffer {
     readScreen(opts?: {
         includeScrollback?: boolean;
     }): ScreenSnapshot;
+    /** Read the screen and wrap it as a `<terminal_buffer>` context block. */
+    formatScreen(maxLines?: number, baseContext?: string): string;
     /**
      * Get terminal screen as lines, padded/trimmed to exactly `rows` lines.
      * Clean text only (ANSI stripped).  Reads from the active buffer's

package/dist/utils/terminal-buffer.js

@@ -111,6 +111,10 @@ export class TerminalBuffer {
             cursorY: buf.cursorY,
         };
     }
+    /** Read the screen and wrap it as a `<terminal_buffer>` context block. */
+    formatScreen(maxLines, baseContext) {
+        return formatScreenContext(this.readScreen(), maxLines, baseContext);
+    }
     /**
      * Get terminal screen as lines, padded/trimmed to exactly `rows` lines.
      * Clean text only (ANSI stripped).  Reads from the active buffer's