agent-sh 0.6.0 → 0.8.0

package/dist/token-budget.js

@@ -0,0 +1,50 @@
+/**
+ * Unified token budget manager.
+ *
+ * Splits a model's context window between two streams:
+ *   - Shell context (user shell commands and outputs — situational awareness)
+ *   - Conversation (agent messages and tool results — task continuity)
+ *
+ * The budget accounts for fixed overhead (system prompt, tool definitions,
+ * response reserve) and divides the remaining space by a configurable ratio.
+ */
+import { getSettings } from "./settings.js";
+/** Overhead estimates (tokens). */
+const SYSTEM_PROMPT_OVERHEAD = 800;
+const DYNAMIC_CONTEXT_OVERHEAD = 500; // conventions, metadata, skills list
+const TOKENS_PER_TOOL_DEFINITION = 50;
+const RESPONSE_RESERVE = 8192; // matches llm-client.ts default max_tokens
+/** Fallback when contextWindow is unknown. */
+const DEFAULT_CONTEXT_WINDOW = 60_000;
+export class TokenBudget {
+    contextWindow;
+    toolCount;
+    constructor(contextWindow, toolCount = 0) {
+        this.contextWindow = contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+        this.toolCount = toolCount;
+    }
+    /** Update when model or tool set changes. */
+    update(contextWindow, toolCount) {
+        if (contextWindow != null)
+            this.contextWindow = contextWindow;
+        if (toolCount != null)
+            this.toolCount = toolCount;
+    }
+    /** Total tokens available for shell context + conversation content. */
+    get contentBudget() {
+        const overhead = SYSTEM_PROMPT_OVERHEAD +
+            DYNAMIC_CONTEXT_OVERHEAD +
+            this.toolCount * TOKENS_PER_TOOL_DEFINITION +
+            RESPONSE_RESERVE;
+        return Math.max(0, this.contextWindow - overhead);
+    }
+    /** Token budget for the shell context stream. */
+    get shellBudgetTokens() {
+        const ratio = getSettings().shellContextRatio;
+        return Math.floor(this.contentBudget * ratio);
+    }
+    /** Token budget for the conversation messages stream. */
+    get conversationBudgetTokens() {
+        return this.contentBudget - this.shellBudgetTokens;
+    }
+}

package/dist/types.d.ts

@@ -4,6 +4,8 @@ import type { LlmClient } from "./utils/llm-client.js";
 import type { ColorPalette } from "./utils/palette.js";
 import type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
 import type { ToolDefinition } from "./agent/types.js";
+import type { TerminalBuffer } from "./utils/terminal-buffer.js";
+import type { FloatingPanel, FloatingPanelConfig } from "./utils/floating-panel.js";
 export type { ContentBlock } from "./event-bus.js";
 export type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
 /** A model entry in the cycling list, optionally tied to a provider. */
@@ -66,6 +68,17 @@ export interface ExtensionContext {
     advise: (name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any) => void;
     /** Call a named handler. */
     call: (name: string, ...args: any[]) => any;
+    /**
+     * Shared headless terminal buffer mirroring PTY output.
+     * Lazily created on first access. Returns null if @xterm/headless is not installed.
+     */
+    terminalBuffer: TerminalBuffer | null;
+    /**
+     * Create a floating panel overlay. The panel composites a bordered box
+     * over the terminal with input routing, dimmed background, and
+     * handler-based customization.
+     */
+    createFloatingPanel: (config: FloatingPanelConfig) => FloatingPanel;
 }
 /**
  * Configuration for a registered input mode.
@@ -88,12 +101,6 @@ export interface TerminalSession {
     done: boolean;
     resolve?: (value: void) => void;
 }
-export interface ToolCallRecord {
-    tool: string;
-    args: Record<string, unknown>;
-    output: string;
-    exitCode: number | null;
-}
 export type Exchange = {
     type: "shell_command";
     id: number;
@@ -111,20 +118,4 @@ export type Exchange = {
     id: number;
     timestamp: number;
     query: string;
-} | {
-    type: "agent_response";
-    id: number;
-    timestamp: number;
-    response: string;
-    toolCalls: ToolCallRecord[];
-} | {
-    type: "tool_execution";
-    id: number;
-    timestamp: number;
-    tool: string;
-    args: Record<string, unknown>;
-    output: string;
-    exitCode: number | null;
-    outputLines: number;
-    outputBytes: number;
 };

package/dist/utils/ansi.d.ts

@@ -11,5 +11,15 @@ export declare const RESET = "\u001B[0m";
  * Excludes SGR (color/style) sequences and accounts for CJK double-width chars.
  */
 export declare function visibleLen(str: string): number;
+/**
+ * Truncate a string to fit within `maxWidth` visible columns.
+ * Accounts for CJK double-width characters. Appends `…` if truncated.
+ */
+export declare function truncateToWidth(str: string, maxWidth: number): string;
+/**
+ * Pad a string with spaces to fill `targetWidth` visible columns.
+ * Accounts for CJK double-width characters.
+ */
+export declare function padEndToWidth(str: string, targetWidth: number): string;
 /** 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

@@ -70,6 +70,33 @@ export function visibleLen(str) {
     }
     return width;
 }
+/**
+ * Truncate a string to fit within `maxWidth` visible columns.
+ * Accounts for CJK double-width characters. Appends `…` if truncated.
+ */
+export function truncateToWidth(str, maxWidth) {
+    const clean = str.replace(/\x1b\[[^m]*m/g, "");
+    let width = 0;
+    let i = 0;
+    for (const char of clean) {
+        const cw = charWidth(char.codePointAt(0) ?? 0);
+        if (width + cw > maxWidth - 1) {
+            // Need room for the "…" (1 column wide)
+            return clean.slice(0, i) + "…";
+        }
+        width += cw;
+        i += char.length;
+    }
+    return clean;
+}
+/**
+ * Pad a string with spaces to fill `targetWidth` visible columns.
+ * Accounts for CJK double-width characters.
+ */
+export function padEndToWidth(str, targetWidth) {
+    const gap = targetWidth - visibleLen(str);
+    return gap > 0 ? str + " ".repeat(gap) : str;
+}
 /** Strip all ANSI escape sequences (SGR, OSC, CSI, private mode) and carriage returns. */
 export function stripAnsi(str) {
     return str

package/dist/utils/floating-panel.d.ts

@@ -0,0 +1,227 @@
+import { TerminalBuffer } from "./terminal-buffer.js";
+import { HandlerRegistry } from "./handler-registry.js";
+import type { EventBus } from "../event-bus.js";
+import type { BorderStyle } from "./box-frame.js";
+export interface FloatingPanelConfig {
+    /** Key sequence that toggles the panel (e.g. "\x1c" for Ctrl+\). */
+    trigger: string;
+    /** Panel width. Number = columns, string with % = percentage. Default: "80%". */
+    width?: number | string;
+    /** Max width in columns. Default: 100. */
+    maxWidth?: number;
+    /** Panel height. Number = rows, string with % = percentage. Default: "60%". */
+    height?: number | string;
+    /** Min content rows inside the panel. Default: 6. */
+    minHeight?: number;
+    /** Border style. Default: "rounded". */
+    borderStyle?: BorderStyle;
+    /**
+     * Show dimmed terminal content behind the panel. Default: true.
+     * Requires @xterm/headless — falls back to blank background if unavailable.
+     */
+    dimBackground?: boolean;
+    /** Auto-dismiss delay in ms when done (0 = auto-prompt for follow-up). Default: 0. */
+    autoDismissMs?: number;
+    /** Icon shown before the input cursor. Default: "\u276f". */
+    promptIcon?: string;
+    /**
+     * Pre-existing TerminalBuffer to reuse. If provided, the panel will
+     * not create its own headless terminal. Useful when sharing a buffer
+     * with other features (e.g. context injection, terminal_read tool).
+     */
+    terminalBuffer?: TerminalBuffer;
+    /**
+     * Handler namespace prefix. Default: "panel".
+     * All handlers are registered as `{prefix}:render-content`,
+     * `{prefix}:submit`, etc. Use different prefixes for multiple panels.
+     */
+    handlerPrefix?: string;
+}
+/**
+ * Context passed to the render-content handler.
+ */
+export interface RenderContext {
+    /** Available width for content (inside box, excluding borders and padding). */
+    width: number;
+    /** Available height for content (rows inside box). */
+    height: number;
+    /** Current panel phase. */
+    phase: Phase;
+    /** Current input buffer text (during input phase). */
+    inputBuffer: string;
+    /** Current input cursor position (during input phase). */
+    inputCursor: number;
+    /** Current scroll offset. */
+    scrollOffset: number;
+    /** Built-in content lines (from appendText/appendLine). */
+    contentLines: readonly string[];
+    /** Current partial line being streamed. */
+    partialLine: string;
+}
+/**
+ * Result from render-content handler.
+ */
+export interface RenderResult {
+    lines: string[];
+    /** Optional cursor position within the content area. */
+    cursor?: {
+        row: number;
+        col: number;
+    };
+}
+/**
+ * Box geometry computed from config + terminal size.
+ */
+export interface BoxGeometry {
+    /** Terminal columns. */
+    cols: number;
+    /** Terminal rows. */
+    rows: number;
+    /** Box width in columns (including borders). */
+    boxW: number;
+    /** Box height in rows (including borders). */
+    boxH: number;
+    /** Box top offset (0-indexed row). */
+    boxTop: number;
+    /** Box left offset (0-indexed column). */
+    boxLeft: number;
+    /** Usable content width inside box. */
+    contentW: number;
+    /** Usable content height inside box. */
+    contentH: number;
+}
+/**
+ * Context passed to the render-frame handler.
+ */
+export interface FrameContext {
+    /** Box geometry. */
+    geo: BoxGeometry;
+    /** Content render result (from render-content handler). */
+    content: RenderResult;
+    /** Background lines from the terminal buffer (null if no dimming). */
+    bgLines: string[] | null;
+    /** Current panel phase. */
+    phase: Phase;
+    /** Current title text. */
+    title: string;
+    /** Current footer text. */
+    footer: string;
+    /** Border characters for the configured border style. */
+    border: {
+        tl: string;
+        tr: string;
+        bl: string;
+        br: string;
+        h: string;
+        v: string;
+    };
+}
+/**
+ * Result from render-frame handler.
+ */
+export interface FrameResult {
+    /** One string per terminal row. */
+    rows: string[];
+    /** ANSI sequence to position the cursor (empty string if no cursor). */
+    cursorSeq: string;
+}
+export type Phase = "idle" | "input" | "active" | "done";
+export declare class FloatingPanel {
+    private readonly config;
+    private readonly bus;
+    private readonly border;
+    private readonly externalBuffer;
+    private readonly prefix;
+    /**
+     * Handler registry for this panel. Extensions use `handlers.advise()`
+     * to customize rendering and behavior.
+     *
+     * Registered handlers:
+     *   - `{prefix}:render-content(ctx: RenderContext) -> RenderResult`
+     *   - `{prefix}:render-frame(ctx: FrameContext) -> FrameResult`
+     *   - `{prefix}:render-border-top(ctx: FrameContext) -> string`
+     *   - `{prefix}:render-border-bottom(ctx: FrameContext) -> string`
+     *   - `{prefix}:composite-row(content: string, bgLine: string|null, boxLeft: number, boxW: number, cols: number) -> string`
+     *   - `{prefix}:submit(query: string) -> void`
+     *   - `{prefix}:dismiss() -> void`
+     *   - `{prefix}:show() -> void`
+     *   - `{prefix}:input(data: string) -> boolean`
+     *   - `{prefix}:build-row(content: string, width: number) -> string`
+     */
+    readonly handlers: HandlerRegistry;
+    private buffer;
+    private bufferInitialized;
+    /** All byte sequences that should be recognized as the trigger key. */
+    private readonly triggerSeqs;
+    private phase;
+    private _visible;
+    private _passthrough;
+    private editor;
+    private contentLines;
+    private currentPartialLine;
+    private scrollOffset;
+    private userScrolled;
+    private title;
+    private footer;
+    private renderTimer;
+    private resizeHandler;
+    private prevFrame;
+    private suppressNextRedraw;
+    private autoDismissTimer;
+    private ptyBuffer;
+    private usedAltScreen;
+    private wrapCache;
+    private wrapCacheWidth;
+    private passthroughTimer;
+    private prevSerialized;
+    constructor(bus: EventBus, config: FloatingPanelConfig, handlers?: HandlerRegistry);
+    private registerDefaultHandlers;
+    private wireEvents;
+    /** Check whether data matches any encoding of the trigger key. */
+    private isTrigger;
+    private ensureBuffer;
+    /** Whether the panel has an active conversation (may be hidden). */
+    get active(): boolean;
+    /** Whether the panel is currently visible on screen. */
+    get visible(): boolean;
+    get terminalBuffer(): TerminalBuffer | null;
+    /** Open a fresh panel with a new conversation. */
+    open(): void;
+    /** Hide the panel without destroying conversation state. */
+    hide(): void;
+    /** Show the panel again after hide(), preserving conversation. */
+    show(): void;
+    /** Fully destroy the panel, resetting all state. */
+    dismiss(): void;
+    /** Common screen enter logic shared by open() and show(). */
+    private enterScreen;
+    appendText(text: string): void;
+    appendLine(line: string): void;
+    updateLastLine(fn: (line: string) => string): void;
+    clearContent(): void;
+    setTitle(title: string): void;
+    setFooter(footer: string): void;
+    setActive(): void;
+    setDone(): void;
+    scrollUp(lines?: number): void;
+    scrollDown(lines?: number): void;
+    getInput(): string;
+    requestRender(): void;
+    private handleIntercept;
+    /** Handle scroll input. Returns true if consumed. */
+    private handleScroll;
+    private handleInputKey;
+    /** Compute box geometry from config + current terminal size. */
+    computeGeometry(): BoxGeometry;
+    private buildFrame;
+    private scheduleRender;
+    private render;
+    /** Full screen teardown: exit alt screen, release stdout, force redraw. */
+    private teardownScreen;
+    /** Start rendering TerminalBuffer directly (no overlay box). */
+    private startPassthrough;
+    private stopPassthrough;
+    /** Render the TerminalBuffer's screen content directly (no overlay). */
+    private renderPassthrough;
+    private resolveSize;
+}