agent-sh 0.10.1 → 0.10.3

package/README.md

@@ -4,6 +4,7 @@ An agent that lives in a shell — not a shell that lives in an agent.
 
 [![npm version](https://img.shields.io/npm/v/agent-sh.svg)](https://www.npmjs.com/package/agent-sh)
 [![license](https://img.shields.io/npm/l/agent-sh.svg)](https://github.com/guanyilun/agent-sh/blob/main/LICENSE)
+[![website](https://img.shields.io/badge/website-agent--sh.dev-blue)](https://agent-sh.dev)
 
 ![demo](assets/demo.gif)
 

package/dist/agent/agent-loop.js

@@ -97,7 +97,8 @@ export class AgentLoop {
         // Shell-history-shaped log. Default writes go through the advisable
         // `history:append` handler registered below; extensions swap the
         // backend without touching this wiring.
-        this.historyFile = new HistoryFile({ instanceId: this.instanceId });
+        const filePath = process.env.AGENT_SH_HISTORY_FILE || getSettings().historyFilePath;
+        this.historyFile = new HistoryFile({ instanceId: this.instanceId, filePath });
         this.conversation = new ConversationState(this.handlers, this.instanceId);
         // Fall back to a single-mode placeholder if the caller passed an
         // empty array (agent-backend does this pre-resolution).
@@ -280,6 +281,9 @@ export class AgentLoop {
             if (beforeTokens > this.peakConversationTokens) {
                 this.peakConversationTokens = beforeTokens;
             }
+            // The "File unchanged" stub assumes the prior read output is still
+            // in context; compaction can evict it. Clear so the next read re-emits.
+            this.fileReadCache.clear();
         });
         on("shell:cwd-change", ({ cwd }) => {
             const projectSkills = discoverProjectSkills(cwd);
@@ -1035,7 +1039,10 @@ export class AgentLoop {
             const contextWindow = this.currentMode.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
             const threshold = Math.floor((contextWindow - RESPONSE_RESERVE) * getSettings().autoCompactThreshold);
             if (totalEstimate > threshold) {
-                const result = this.compactWithHooks(threshold);
+                // Compact deeply — shallow targets buy only 1–2 turns of runway on
+                // tool-heavy workloads.
+                const target = Math.floor(threshold * 0.25);
+                const result = this.compactWithHooks(target, 6);
                 if (!result) {
                     // Auto-compact fired but nothing was evictable. This can happen
                     // in short conversations with heavy tool output where the pin

package/dist/agent/history-file.d.ts

@@ -2,6 +2,7 @@ import { type NuclearEntry } from "./nuclear-form.js";
 export declare class HistoryFile {
     readonly instanceId: string;
     private filePath;
+    private lockPath;
     constructor(opts?: {
         filePath?: string;
         instanceId?: string;

package/dist/agent/history-file.js

@@ -12,14 +12,21 @@ import * as crypto from "node:crypto";
 import { CONFIG_DIR, getSettings } from "../settings.js";
 import { serializeEntry, deserializeEntry, formatNuclearLine, isReadOnly, } from "./nuclear-form.js";
 const HISTORY_PATH = path.join(CONFIG_DIR, "history");
-const LOCK_PATH = HISTORY_PATH + ".lock";
 const LOCK_STALE_MS = 10_000; // consider lock stale after 10s
 export class HistoryFile {
     instanceId;
     filePath;
+    lockPath;
     constructor(opts) {
         this.filePath = opts?.filePath ?? HISTORY_PATH;
+        this.lockPath = this.filePath + ".lock";
         this.instanceId = opts?.instanceId ?? crypto.randomBytes(2).toString("hex");
+        // Custom paths may target a dir that doesn't exist yet; create sync so
+        // the first append() can't race with the mkdir.
+        try {
+            fss.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        }
+        catch { /* ignore */ }
     }
     /**
      * Append entries atomically. Uses O_APPEND for concurrency safety.
@@ -218,16 +225,16 @@ export class HistoryFile {
         try {
             // Check for stale lock
             try {
-                const stat = await fs.stat(LOCK_PATH);
+                const stat = await fs.stat(this.lockPath);
                 if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
-                    await fs.unlink(LOCK_PATH).catch(() => { });
+                    await fs.unlink(this.lockPath).catch(() => { });
                 }
             }
             catch {
                 // Lock doesn't exist — good
             }
             // O_EXCL ensures atomicity
-            const fd = await fs.open(LOCK_PATH, fss.constants.O_CREAT | fss.constants.O_EXCL | fss.constants.O_WRONLY);
+            const fd = await fs.open(this.lockPath, fss.constants.O_CREAT | fss.constants.O_EXCL | fss.constants.O_WRONLY);
             await fd.close();
             return true;
         }
@@ -236,6 +243,6 @@ export class HistoryFile {
         }
     }
     async releaseLock() {
-        await fs.unlink(LOCK_PATH).catch(() => { });
+        await fs.unlink(this.lockPath).catch(() => { });
     }
 }

package/dist/agent/nuclear-form.d.ts

@@ -43,6 +43,8 @@ export declare function createSessionMarker(iid: string, seq?: number): NuclearE
 export declare function isSessionMarker(entry: NuclearEntry): boolean;
 /** Read-only tools whose results are dropped at Tier 1→2 (agent can re-read). */
 export declare const READ_ONLY_TOOLS: Set<string>;
+export declare function registerReadOnlyTool(name: string): void;
+export declare function unregisterReadOnlyTool(name: string): void;
 /** State-changing tools whose summaries are kept in nuclear memory. */
 export declare const WRITE_TOOLS: Set<string>;
 /**

package/dist/agent/nuclear-form.js

@@ -15,6 +15,14 @@ export function isSessionMarker(entry) {
 export const READ_ONLY_TOOLS = new Set([
     "read_file", "grep", "glob", "ls", "search",
 ]);
+/** Extensions opt their tools in via ToolRegistry.register when readOnly is set. */
+const extraReadOnlyTools = new Set();
+export function registerReadOnlyTool(name) {
+    extraReadOnlyTools.add(name);
+}
+export function unregisterReadOnlyTool(name) {
+    extraReadOnlyTools.delete(name);
+}
 /** State-changing tools whose summaries are kept in nuclear memory. */
 export const WRITE_TOOLS = new Set([
     "write_file", "edit_file", "write", "edit", "patch",
@@ -188,7 +196,9 @@ export function deserializeEntry(line) {
 // ── Classification helpers ────────────────────────────────────────
 /** Check if a nuclear entry represents a read-only action (should be dropped). */
 export function isReadOnly(entry) {
-    return entry.kind === "tool" && entry.tool != null && READ_ONLY_TOOLS.has(entry.tool);
+    if (entry.kind !== "tool" || entry.tool == null)
+        return false;
+    return READ_ONLY_TOOLS.has(entry.tool) || extraReadOnlyTools.has(entry.tool);
 }
 // ── Internal helpers ──────────────────────────────────────────────
 function truncate(text, maxLen) {

package/dist/agent/system-prompt.js

@@ -89,7 +89,7 @@ function loadConventionFiles(dir) {
  * Static system prompt — identical across all queries, cacheable.
  * Contains only identity and behavioral instructions.
  */
-export const STATIC_SYSTEM_PROMPT = `You are an AI coding assistant running inside agent-sh, a terminal shell.
+export const STATIC_SYSTEM_PROMPT = `You are ash, an AI coding assistant running inside agent-sh, a terminal shell.
 You have access to the user's shell environment and can read, write, and execute code.
 You share the user's working directory, environment variables, and shell history.
 agent-sh documentation is at ${path.join(CODE_DIR, "docs")} — start with README.md for an index. Read the docs when you need to understand how the runtime works.

package/dist/agent/tool-registry.js

@@ -1,3 +1,4 @@
+import { registerReadOnlyTool, unregisterReadOnlyTool } from "./nuclear-form.js";
 /**
  * Registry for agent tools. Holds tool definitions and converts them
  * to OpenAI-compatible function schemas for API calls.
@@ -6,9 +7,14 @@ export class ToolRegistry {
     tools = new Map();
     register(tool) {
         this.tools.set(tool.name, tool);
+        if (tool.readOnly)
+            registerReadOnlyTool(tool.name);
+        else
+            unregisterReadOnlyTool(tool.name);
     }
     unregister(name) {
         this.tools.delete(name);
+        unregisterReadOnlyTool(name);
     }
     get(name) {
         return this.tools.get(name);

package/dist/agent/types.d.ts

@@ -77,6 +77,9 @@ export interface ToolDefinition {
     showOutput?: boolean;
     /** Whether this tool may modify files — triggers file watcher (default: false). */
     modifiesFiles?: boolean;
+    /** Results are re-fetchable; nuclear compaction drops the tool_result
+     *  body on eviction (like the builtin read_file/grep/ls). Default: false. */
+    readOnly?: boolean;
     /** Whether to gate execution via permission:request (default: false). */
     requiresPermission?: boolean;
     /** Derive display metadata (icon kind, file paths) for the TUI. */

package/dist/extensions/tui-renderer.js

@@ -48,7 +48,8 @@ function createRenderState() {
         spinnerOpts: {},
         spinnerInterval: null,
         spinnerStartTime: 0,
-        toolLineOpen: false,
+        openTool: null,
+        pendingToolCompletes: new Map(),
         currentToolKind: undefined,
         toolStartTime: 0,
         toolExitCode: null,
@@ -58,6 +59,7 @@ function createRenderState() {
         commandOverflowLines: [],
         toolGroupKind: undefined,
         toolGroupCount: 0,
+        toolGroupCompletedCount: 0,
         toolGroupAllOk: true,
         toolGroupRendered: 0,
         toolGroupSummaries: [],
@@ -231,6 +233,9 @@ export default function activate(ctx) {
             return;
         s.isThinking = false;
         if (pendingUsage && s.renderer) {
+            // Flush any buffered partial line first — otherwise responses that
+            // don't end with a newline emit the usage line before their final text.
+            s.renderer.flush();
             const { prompt_tokens, completion_tokens } = pendingUsage;
             const maxTokens = backendInfo?.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
             s.renderer.writeLine("");
@@ -300,29 +305,26 @@ export default function activate(ctx) {
                 group.headerShown = true;
                 s.toolGroupKind = kind;
                 s.toolGroupCount = 0;
+                s.toolGroupCompletedCount = 0;
                 s.toolGroupRendered = 0;
                 s.toolGroupAllOk = true;
                 s.toolGroupSummaries = [];
             }
             s.toolGroupCount++;
             if (s.toolGroupRendered < GROUP_MAX_VISIBLE) {
-                showToolCall(e.title, "", {
-                    ...e,
-                    batchIndex: e.batchIndex,
-                    batchTotal: e.batchTotal,
-                    groupContinuation: true,
-                });
+                showToolCall(e.title, "", { ...e, groupContinuation: true });
                 s.toolGroupRendered++;
             }
+            // Record identity so late completes (after a premature finalize
+            // from a cross-kind standalone start) can render as labeled ⎿ lines.
+            if (e.toolCallId) {
+                s.pendingToolCompletes.set(e.toolCallId, { title: e.title });
+            }
         }
         else {
             // Standalone tool — single in its batch kind, or not groupable
             finalizeToolGroup();
-            showToolCall(e.title, "", {
-                ...e,
-                batchIndex: e.batchIndex,
-                batchTotal: e.batchTotal,
-            });
+            showToolCall(e.title, "", { ...e });
         }
     });
     bus.on("agent:tool-completed", (e) => {
@@ -336,10 +338,17 @@ export default function activate(ctx) {
             // Don't restart spinner between grouped tools — it's already running from group start.
             if (e.resultDisplay?.summary)
                 s.toolGroupSummaries.push(e.resultDisplay.summary);
+            if (e.toolCallId)
+                s.pendingToolCompletes.delete(e.toolCallId);
+            s.toolGroupCompletedCount++;
             s.currentToolKind = undefined;
         }
         else {
-            showToolComplete(e.exitCode, e.resultDisplay);
+            // Route by callId — tools that lost the inline slot get a labeled ⎿ line.
+            const pending = e.toolCallId ? s.pendingToolCompletes.get(e.toolCallId) : undefined;
+            if (pending)
+                s.pendingToolCompletes.delete(e.toolCallId);
+            showToolComplete(e.exitCode, e.resultDisplay, pending?.title);
             s.currentToolKind = undefined;
             s.spinnerStartTime = 0;
             startThinkingSpinner();
@@ -734,37 +743,37 @@ export default function activate(ctx) {
                 // Grouped tools: close the line immediately — checkmarks go on the ⎿ summary
                 s.renderer.writeLine(`  ${batchPrefix}${lines[lines.length - 1]}`);
                 drain();
-                s.toolLineOpen = false;
             }
             else {
                 out().write(`  ${batchPrefix}${lines[lines.length - 1]}`);
-                s.toolLineOpen = true;
+                if (extra?.toolCallId)
+                    s.openTool = { callId: extra.toolCallId, title };
             }
         }
         s.hadToolCalls = true;
         s.commandOutputLineCount = 0;
         s.commandOutputOverflow = 0;
     }
-    function showToolComplete(exitCode, resultDisplay) {
+    function showToolComplete(exitCode, resultDisplay, labelTitle) {
         if (!s.renderer)
             return;
         stopCurrentSpinner();
         const elapsed = s.toolStartTime ? formatElapsed(Date.now() - s.toolStartTime) : "";
         const mark = ctx.call("tui:render-tool-complete", exitCode, elapsed, resultDisplay?.summary);
-        if (s.toolLineOpen && s.commandOutputLineCount === 0) {
+        if (!labelTitle && s.openTool && s.commandOutputLineCount === 0) {
             out().write(` ${mark}\n`);
-            s.toolLineOpen = false;
+            s.openTool = null;
         }
         else {
             closeToolLine();
             flushCommandOutput();
-            s.renderer.writeLine(`  ${mark}`);
+            s.renderer.writeLine(labelTitle
+                ? `  ${p.muted}⎿${p.reset} ${p.dim}${labelTitle}${p.reset} ${mark}`
+                : `  ${mark}`);
             drain();
         }
-        // Render structured body if present
-        if (resultDisplay?.body) {
+        if (resultDisplay?.body)
             renderResultBody(resultDisplay.body);
-        }
     }
     function renderResultBody(body) {
         if (!s.renderer)
@@ -813,18 +822,23 @@ export default function activate(ctx) {
         }
     }
     function closeToolLine() {
-        if (s.toolLineOpen) {
+        if (s.openTool) {
             out().write("\n");
-            s.toolLineOpen = false;
+            // Stash identity so the completion renders as ⎿ labeled, not orphan ✓.
+            s.pendingToolCompletes.set(s.openTool.callId, { title: s.openTool.title });
+            s.openTool = null;
         }
     }
-    /** Finalize a group of collapsed tool calls, rendering the summary. */
+    /** Render the group aggregate ⎿ line, or skip if no members have
+     *  completed yet (late completes will render individually as ⎿ labeled). */
     function finalizeToolGroup() {
-        if (s.toolGroupCount <= 1) {
-            // 0–1 tools: standalone, nothing to finalize
+        const skipAggregate = s.toolGroupCount > 1 && s.toolGroupCompletedCount === 0;
+        if (s.toolGroupCount <= 1 || skipAggregate) {
             s.toolGroupKind = undefined;
             s.toolGroupCount = 0;
+            s.toolGroupCompletedCount = 0;
             s.toolGroupRendered = 0;
+            s.toolGroupAllOk = true;
             s.toolGroupSummaries = [];
             return;
         }
@@ -836,6 +850,7 @@ export default function activate(ctx) {
         drain();
         s.toolGroupKind = undefined;
         s.toolGroupCount = 0;
+        s.toolGroupCompletedCount = 0;
         s.toolGroupAllOk = true;
         s.toolGroupRendered = 0;
         s.toolGroupSummaries = [];

package/dist/settings.d.ts

@@ -42,6 +42,13 @@ export interface Settings {
     historyMaxBytes?: number;
     /** Number of prior history entries to load on startup (default: 50). */
     historyStartupEntries?: number;
+    /**
+     * Override the history file path. Defaults to `~/.agent-sh/history`.
+     * The `AGENT_SH_HISTORY_FILE` env var takes precedence over this setting.
+     * Use a per-project path to keep sessions isolated (e.g. embedding apps
+     * that boot agent-sh as a library against a specific working tree).
+     */
+    historyFilePath?: string;
     /** Auto-compact threshold as fraction of conversation budget (0-1, default 0.5). */
     autoCompactThreshold?: number;
     /** Max command output lines shown inline in TUI. */

package/dist/settings.js

@@ -21,6 +21,7 @@ const DEFAULTS = {
     shellTailLines: 10,
     historyMaxBytes: 104857600, // 100MB — history is only accessed via search/expand, never loaded wholesale
     historyStartupEntries: 100,
+    historyFilePath: undefined,
     autoCompactThreshold: 0.5,
     maxCommandOutputLines: 3,
     readOutputMaxLines: 10,

package/dist/shell/input-handler.js

@@ -218,6 +218,12 @@ export class InputHandler {
                 this.lineBuffer = "";
                 this.ctx.writeToPty(ch);
             }
+            else if (ch === "\x0b" || ch === "\x15") {
+                // Ctrl-K / Ctrl-U kill the line in the shell; mirror that so the
+                // mode-trigger check sees an empty buffer. Not cursor-accurate.
+                this.lineBuffer = "";
+                this.ctx.writeToPty(ch);
+            }
             else if (ch === "\x1b") {
                 // Escape sequence — forward the entire sequence to the PTY but
                 // don't let it corrupt lineBuffer.  Skip CSI (ESC [ ... final)

package/dist/utils/ansi.d.ts

@@ -7,26 +7,40 @@ export declare const GRAY = "\u001B[90m";
 export declare const BOLD = "\u001B[1m";
 export declare const RESET = "\u001B[0m";
 /**
- * Check if a Unicode code point is a wide character (CJK, fullwidth, emoji, etc.)
- * Returns 2 for wide chars, 1 for normal chars, 0 for combining chars.
+ * Width of a single Unicode code point in terminal columns.
  *
- * Based on East Asian Width and Unicode categories.
+ * For correct rendering of emoji clusters (ZWJ, flags, skin-tone, VS16)
+ * prefer `clusterWidth` or `visibleLen`, which segment graphemes first.
+ * This code-point-level primitive is kept for callers that iterate over
+ * chars for wrap-detection purposes (e.g. CJK line-break rules).
  */
 export declare function charWidth(codePoint: number): number;
+/**
+ * Width of one grapheme cluster in terminal columns. Handles ZWJ sequences,
+ * regional-indicator flags, skin-tone modifiers, and VS16 emoji presentation.
+ */
+export declare function clusterWidth(cluster: string): number;
 /**
  * Measure visible string length in terminal columns.
- * Excludes SGR (color/style) sequences and accounts for CJK double-width chars.
+ * Excludes SGR (color/style) sequences, and counts each grapheme cluster
+ * (emoji, CJK, combining marks) as one terminal-visible unit.
  */
 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.
+ * Iterates by grapheme cluster so emoji sequences (ZWJ, flags, VS16) are
+ * kept intact rather than split mid-cluster. Appends `…` if truncated.
  */
 export declare function truncateToWidth(str: string, maxWidth: number): string;
+/** Truncate to visible width while preserving SGR sequences — use when
+ *  input carries color/bold codes. `truncateToWidth` strips them. */
+export declare function truncateAnsiToWidth(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. */
+/** Strip ANSI escape sequences and carriage returns.
+ *  Delegates escape handling to the `strip-ansi` package (covers SGR, OSC,
+ *  CSI, private-mode, 8-bit CSI, and newer variants). `\r` is not an escape
+ *  but callers rely on it being stripped alongside. */
 export declare function stripAnsi(str: string): string;

package/dist/utils/ansi.js

@@ -1,3 +1,5 @@
+import stringWidth from "string-width";
+import stripAnsiPkg from "strip-ansi";
 // ── ANSI escape code constants ────────────────────────────────
 export const CYAN = "\x1b[36m";
 export const DIM = "\x1b[2m";
@@ -8,162 +10,127 @@ export const GRAY = "\x1b[90m";
 export const BOLD = "\x1b[1m";
 export const RESET = "\x1b[0m";
 // ── ANSI utility functions ───────────────────────────────────
+// Reused across iterations. Segmenter construction is not free, and the API
+// is pure (no per-call state) so a module-level instance is safe.
+const GRAPHEME_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 /**
- * Check if a Unicode code point is a wide character (CJK, fullwidth, emoji, etc.)
- * Returns 2 for wide chars, 1 for normal chars, 0 for combining chars.
+ * Width of a single Unicode code point in terminal columns.
  *
- * Based on East Asian Width and Unicode categories.
+ * For correct rendering of emoji clusters (ZWJ, flags, skin-tone, VS16)
+ * prefer `clusterWidth` or `visibleLen`, which segment graphemes first.
+ * This code-point-level primitive is kept for callers that iterate over
+ * chars for wrap-detection purposes (e.g. CJK line-break rules).
  */
 export function charWidth(codePoint) {
-    // Combining characters (zero width)
-    if (codePoint >= 0x0300 && codePoint <= 0x036f)
-        return 0; // Combining Diacritical Marks
-    if (codePoint >= 0x1ab0 && codePoint <= 0x1aff)
-        return 0; // Combining Diacritical Marks Extended
-    if (codePoint >= 0x1dc0 && codePoint <= 0x1dff)
-        return 0; // Combining Diacritical Marks Supplement
-    if (codePoint >= 0x20d0 && codePoint <= 0x20ff)
-        return 0; // Combining Diacritical Marks for Symbols
-    if (codePoint >= 0xfe20 && codePoint <= 0xfe2f)
-        return 0; // Combining Half Marks
-    if (codePoint >= 0xfe00 && codePoint <= 0xfe0f)
-        return 0; // Variation Selectors
-    if (codePoint >= 0xe0100 && codePoint <= 0xe01ef)
-        return 0; // Variation Selectors Supplement
-    // Emoji and symbols that render as wide (2 columns)
-    // Emoji presentation sequences and keycap
-    if (codePoint === 0x20e3)
-        return 2; // Combining Enclosing Keycap
-    // Emoji blocks
-    if (codePoint >= 0x1f600 && codePoint <= 0x1f64f)
-        return 2; // Emoticons
-    if (codePoint >= 0x1f300 && codePoint <= 0x1f5ff)
-        return 2; // Misc Symbols and Pictographs
-    if (codePoint >= 0x1f680 && codePoint <= 0x1f6ff)
-        return 2; // Transport and Map
-    if (codePoint >= 0x1f700 && codePoint <= 0x1f77f)
-        return 2; // Alchemical Symbols
-    if (codePoint >= 0x1f780 && codePoint <= 0x1f7ff)
-        return 2; // Geometric Shapes Extended
-    if (codePoint >= 0x1f800 && codePoint <= 0x1f8ff)
-        return 2; // Supplemental Arrows-C
-    if (codePoint >= 0x1f900 && codePoint <= 0x1f9ff)
-        return 2; // Supplemental Symbols and Pictographs
-    if (codePoint >= 0x1fa00 && codePoint <= 0x1faff)
-        return 2; // Chess Symbols, Symbols and Pictographs Extended-A
-    // NOTE: 0x2300-0x23ff (Misc Technical), 0x2600-0x26ff (Misc Symbols),
-    // and 0x2700-0x27bf (Dingbats) are intentionally NOT width 2 — these ranges
-    // contain mostly "Ambiguous" width characters that render as 1 column in
-    // non-CJK terminal locales (e.g. ❯, ⌘, ★, ♦).
-    // Regional indicator symbols (flag emoji components)
-    if (codePoint >= 0x1f1e6 && codePoint <= 0x1f1ff)
-        return 2;
-    // 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;
-    // 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;
+    return stringWidth(String.fromCodePoint(codePoint));
+}
+/**
+ * Width of one grapheme cluster in terminal columns. Handles ZWJ sequences,
+ * regional-indicator flags, skin-tone modifiers, and VS16 emoji presentation.
+ */
+export function clusterWidth(cluster) {
+    return stringWidth(cluster);
+}
+/** Strip SGR (color/style) sequences from a string. */
+function stripSGR(str) {
+    return str.replace(/\x1b\[[^m]*m/g, "");
 }
 /**
  * Measure visible string length in terminal columns.
- * Excludes SGR (color/style) sequences and accounts for CJK double-width chars.
+ * Excludes SGR (color/style) sequences, and counts each grapheme cluster
+ * (emoji, CJK, combining marks) as one terminal-visible unit.
  */
 export function visibleLen(str) {
-    // 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;
+    return stringWidth(stripSGR(str));
 }
 /**
  * Truncate a string to fit within `maxWidth` visible columns.
- * Accounts for CJK double-width characters. Appends `…` if truncated.
+ * Iterates by grapheme cluster so emoji sequences (ZWJ, flags, VS16) are
+ * kept intact rather than split mid-cluster. Appends `…` if truncated.
  */
 export function truncateToWidth(str, maxWidth) {
-    const clean = str.replace(/\x1b\[[^m]*m/g, "");
+    const clean = stripSGR(str);
     if (maxWidth <= 0)
         return "";
-    // First check if the entire string fits
-    let fullWidth = 0;
-    for (const char of clean) {
-        fullWidth += charWidth(char.codePointAt(0) ?? 0);
-    }
-    if (fullWidth <= maxWidth)
+    if (visibleLen(clean) <= maxWidth)
         return clean;
-    // String doesn't fit — truncate with "…"
-    // At maxWidth=1 the ellipsis alone fills the budget.
     if (maxWidth === 1)
         return "…";
-    // Reserve 1 column for "…", so target content width is maxWidth - 1
     const target = maxWidth - 1;
     let width = 0;
-    let i = 0;
-    for (const char of clean) {
-        const cw = charWidth(char.codePointAt(0) ?? 0);
+    let out = "";
+    for (const { segment } of GRAPHEME_SEGMENTER.segment(clean)) {
+        const cw = clusterWidth(segment);
         if (width + cw > target)
             break;
         width += cw;
-        i += char.length;
+        out += segment;
     }
-    // If nothing fit (first char is wider than target), just show the ellipsis
-    // rather than emit a character that would overflow the budget.
-    if (i === 0)
+    if (out === "")
         return "…";
-    return clean.slice(0, i) + "…";
+    return out + "…";
+}
+/** Truncate to visible width while preserving SGR sequences — use when
+ *  input carries color/bold codes. `truncateToWidth` strips them. */
+export function truncateAnsiToWidth(str, maxWidth) {
+    if (maxWidth <= 0)
+        return "";
+    if (visibleLen(str) <= maxWidth)
+        return str;
+    if (maxWidth === 1)
+        return "…";
+    const target = maxWidth - 1;
+    // Walk the string preserving SGR escapes in-place; buffer text between
+    // escapes and segment it into graphemes to count width correctly.
+    let width = 0;
+    let out = "";
+    let buf = "";
+    let i = 0;
+    const flushBuf = () => {
+        if (!buf)
+            return false;
+        for (const { segment } of GRAPHEME_SEGMENTER.segment(buf)) {
+            const cw = clusterWidth(segment);
+            if (width + cw > target) {
+                buf = "";
+                return true; // budget exhausted
+            }
+            width += cw;
+            out += segment;
+        }
+        buf = "";
+        return false;
+    };
+    while (i < str.length) {
+        if (str[i] === "\x1b" && str[i + 1] === "[") {
+            const end = str.indexOf("m", i);
+            if (end !== -1) {
+                if (flushBuf())
+                    break;
+                out += str.slice(i, end + 1);
+                i = end + 1;
+                continue;
+            }
+        }
+        const cp = str.codePointAt(i) ?? 0;
+        const chLen = cp > 0xffff ? 2 : 1;
+        buf += str.slice(i, i + chLen);
+        i += chLen;
+    }
+    flushBuf();
+    return out + "\x1b[0m…";
 }
 /**
  * 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. */
+/** Strip ANSI escape sequences and carriage returns.
+ *  Delegates escape handling to the `strip-ansi` package (covers SGR, OSC,
+ *  CSI, private-mode, 8-bit CSI, and newer variants). `\r` is not an escape
+ *  but callers rely on it being stripped alongside. */
 export function stripAnsi(str) {
-    return str
-        .replace(/\x1b\][^\x07]*\x07/g, "") // OSC sequences
-        .replace(/\x1b\[[^m]*m/g, "") // SGR (color) sequences
-        .replace(/\x1b\[\?[^a-zA-Z]*[a-zA-Z]/g, "") // private mode sequences
-        .replace(/\x1b\[[^a-zA-Z]*[a-zA-Z]/g, "") // CSI sequences
-        .replace(/\r/g, ""); // carriage returns
+    return stripAnsiPkg(str).replace(/\r/g, "");
 }

package/dist/utils/llm-client.d.ts

@@ -12,6 +12,10 @@ export interface LlmClientConfig {
     apiKey: string;
     baseURL?: string;
     model: string;
+    /** Sent as OpenRouter X-Title; ignored by other providers. */
+    appName?: string;
+    /** Sent as OpenRouter HTTP-Referer; ignored by other providers. */
+    appUrl?: string;
 }
 export declare class LlmClient {
     private config;

package/dist/utils/llm-client.js

@@ -6,6 +6,12 @@
  * (command suggestions, completions).
  */
 import OpenAI from "openai";
+function attributionHeaders(config) {
+    return {
+        "HTTP-Referer": config.appUrl ?? "https://agent-sh.dev",
+        "X-Title": config.appName ?? "agent-sh",
+    };
+}
 export class LlmClient {
     config;
     client;
@@ -15,6 +21,7 @@ export class LlmClient {
         this.client = new OpenAI({
             apiKey: config.apiKey,
             baseURL: config.baseURL,
+            defaultHeaders: attributionHeaders(config),
         });
         this.model = config.model;
     }
@@ -24,6 +31,7 @@ export class LlmClient {
         this.client = new OpenAI({
             apiKey: newConfig.apiKey,
             baseURL: newConfig.baseURL,
+            defaultHeaders: attributionHeaders(newConfig),
         });
         this.model = newConfig.model;
     }

package/dist/utils/markdown.d.ts

@@ -2,6 +2,10 @@ export declare const MAX_CONTENT_WIDTH = 90;
 /**
  * Word-wrap a string (which may contain ANSI codes) to a maximum visible width.
  * Returns an array of lines, each fitting within `maxWidth` visible characters.
+ *
+ * Handles CJK text by breaking between wide characters and applying basic
+ * CJK rules (closing punctuation sticks to the previous line; opening
+ * punctuation sticks to the next).
  */
 export declare function wrapLine(text: string, maxWidth: number): string[];
 /**

package/dist/utils/markdown.js

@@ -1,9 +1,65 @@
-import { visibleLen, truncateToWidth, padEndToWidth, charWidth } from "./ansi.js";
+import { visibleLen, truncateAnsiToWidth, padEndToWidth, charWidth } from "./ansi.js";
 import { palette as p } from "./palette.js";
 export const MAX_CONTENT_WIDTH = 90;
+// CJK line-breaking rules: closing punctuation must not start a line,
+// opening punctuation must not end a line. Both CJK fullwidth and ASCII
+// equivalents are included so mixed text wraps correctly.
+const CJK_NO_LINE_START = new Set([
+    "。", "，", "、", "．", "；", "：", "！", "？",
+    "）", "」", "』", "】", "》", "〉", "〕", "］", "｝",
+    "・", "々", "〜", "～", "ー",
+    ".", ",", ";", ":", "!", "?", ")", "]", "}",
+]);
+const CJK_NO_LINE_END = new Set([
+    "（", "「", "『", "【", "《", "〈", "〔", "［", "｛",
+    "(", "[", "{",
+]);
+/**
+ * Tokenize a visible-text run into units suitable for wrapping.
+ * Each width-2 character (CJK, fullwidth, emoji) becomes its own token so the
+ * wrapper can break between them; ASCII runs stay together as word tokens.
+ */
+function tokenizeVisible(text) {
+    const tokens = [];
+    let ascii = "";
+    const flush = () => { if (ascii) {
+        tokens.push(ascii);
+        ascii = "";
+    } };
+    let i = 0;
+    while (i < text.length) {
+        const cp = text.codePointAt(i) ?? 0;
+        const chLen = cp > 0xffff ? 2 : 1;
+        const ch = text.slice(i, i + chLen);
+        if (ch === " ") {
+            flush();
+            let spaces = "";
+            while (i < text.length && text[i] === " ") {
+                spaces += " ";
+                i += 1;
+            }
+            tokens.push(spaces);
+            continue;
+        }
+        if (charWidth(cp) === 2) {
+            flush();
+            tokens.push(ch);
+            i += chLen;
+            continue;
+        }
+        ascii += ch;
+        i += chLen;
+    }
+    flush();
+    return tokens;
+}
 /**
  * Word-wrap a string (which may contain ANSI codes) to a maximum visible width.
  * Returns an array of lines, each fitting within `maxWidth` visible characters.
+ *
+ * Handles CJK text by breaking between wide characters and applying basic
+ * CJK rules (closing punctuation sticks to the previous line; opening
+ * punctuation sticks to the next).
  */
 export function wrapLine(text, maxWidth) {
     if (!(maxWidth > 0))
@@ -11,40 +67,44 @@ export function wrapLine(text, maxWidth) {
     if (visibleLen(text) <= maxWidth)
         return [text];
     const result = [];
-    // Split into segments: ANSI codes and visible text
     const segments = text.match(/(\x1b\[[^m]*m|[^\x1b]+)/g) || [text];
-    let currentLine = "";
-    let currentWidth = 0;
-    let activeStyles = ""; // track ANSI styles to reapply after wraps
+    let lineTokens = [];
+    let lineWidth = 0;
+    let activeStyles = "";
+    let lastVisibleIdx = -1;
+    const commit = () => {
+        result.push(lineTokens.join("") + p.reset);
+        lineTokens = activeStyles ? [activeStyles] : [];
+        lineWidth = 0;
+        lastVisibleIdx = -1;
+    };
     for (const seg of segments) {
         if (seg.startsWith("\x1b[")) {
-            // ANSI code — track it, add to current line
-            currentLine += seg;
-            if (seg === p.reset) {
+            lineTokens.push(seg);
+            if (seg === p.reset)
                 activeStyles = "";
-            }
-            else {
+            else
                 activeStyles += seg;
-            }
             continue;
         }
-        // Visible text — split into words
-        const words = seg.split(/( +)/);
-        for (const word of words) {
-            if (word.length === 0)
+        for (const token of tokenizeVisible(seg)) {
+            const tokenWidth = visibleLen(token);
+            const isSpace = token[0] === " ";
+            if (lineWidth + tokenWidth <= maxWidth) {
+                lineTokens.push(token);
+                lineWidth += tokenWidth;
+                if (!isSpace)
+                    lastVisibleIdx = lineTokens.length - 1;
                 continue;
-            const wordWidth = visibleLen(word);
-            if (currentWidth + wordWidth <= maxWidth) {
-                currentLine += word;
-                currentWidth += wordWidth;
             }
-            else if (currentWidth === 0) {
-                // Single word longer than maxWidth — hard break by visible width
-                let remaining = word;
+            // Token doesn't fit on the current line.
+            if (isSpace)
+                continue; // spaces at wrap points are dropped
+            if (lineWidth === 0) {
+                // Token longer than the entire line — hard-break by char width.
+                let remaining = token;
                 while (remaining.length > 0) {
-                    // Find the largest prefix that fits
-                    let fitLen = 0;
-                    let fitWidth = 0;
+                    let fitLen = 0, fitWidth = 0;
                     for (const ch of remaining) {
                         const cw = charWidth(ch.codePointAt(0) ?? 0);
                         if (fitWidth + cw > maxWidth)
@@ -52,37 +112,47 @@ export function wrapLine(text, maxWidth) {
                         fitWidth += cw;
                         fitLen += ch.length;
                     }
-                    if (fitLen === 0) {
-                        // Even one char doesn't fit — force take one char to avoid infinite loop
+                    if (fitLen === 0)
                         fitLen = remaining[0]?.length ?? 1;
-                    }
                     const chunk = remaining.slice(0, fitLen);
                     remaining = remaining.slice(fitLen);
-                    currentLine += chunk;
-                    if (remaining.length > 0) {
-                        result.push(currentLine + p.reset);
-                        currentLine = activeStyles;
-                        currentWidth = 0;
-                    }
-                    else {
-                        currentWidth += fitWidth;
-                    }
+                    lineTokens.push(chunk);
+                    lineWidth += visibleLen(chunk);
+                    lastVisibleIdx = lineTokens.length - 1;
+                    if (remaining.length > 0)
+                        commit();
                 }
+                continue;
             }
-            else {
-                // Wrap to next line
-                result.push(currentLine + p.reset);
-                currentLine = activeStyles;
-                currentWidth = 0;
-                // Skip leading spaces on new line
-                const trimmed = word.replace(/^ +/, "");
-                currentLine += trimmed;
-                currentWidth = visibleLen(trimmed);
+            // Rule (a): closing punctuation must not start a line. Allow up to 2
+            // columns of overflow so the punctuation stays with its phrase.
+            if (CJK_NO_LINE_START.has(token)) {
+                lineTokens.push(token);
+                lineWidth += tokenWidth;
+                commit();
+                continue;
+            }
+            // Rule (b): opening punctuation must not end a line. Pull the trailing
+            // opener down to the next line with us.
+            let carried = [];
+            if (lastVisibleIdx >= 0 && CJK_NO_LINE_END.has(lineTokens[lastVisibleIdx])) {
+                carried = lineTokens.splice(lastVisibleIdx);
+                while (lineTokens.length > 0 && /^ +$/.test(lineTokens[lineTokens.length - 1])) {
+                    lineTokens.pop();
+                }
             }
+            commit();
+            for (const t of carried) {
+                lineTokens.push(t);
+                lineWidth += visibleLen(t);
+            }
+            lineTokens.push(token);
+            lineWidth += tokenWidth;
+            lastVisibleIdx = lineTokens.length - 1;
         }
     }
-    if (currentLine.length > 0) {
-        result.push(currentLine);
+    if (lineWidth > 0) {
+        result.push(lineTokens.join(""));
     }
     return result;
 }
@@ -188,23 +258,31 @@ export class MarkdownRenderer {
             while (row.length < numCols)
                 row.push("");
         }
-        // Calculate column widths from content
+        // Width from rendered cell — raw `**bold**` over-counts by 4 per pair.
         const colWidths = new Array(numCols).fill(0);
         for (const row of dataRows) {
             for (let c = 0; c < numCols; c++) {
-                colWidths[c] = Math.max(colWidths[c], visibleLen(row[c]));
+                colWidths[c] = Math.max(colWidths[c], visibleLen(this.renderInline(row[c])));
             }
         }
-        // Shrink columns proportionally if total exceeds content width
-        // Account for separators: " │ " between cols (3 chars each) + 2 outer padding
+        // Tables bypass the prose width cap — borders guide the eye, so wider is fine.
         const separatorWidth = (numCols - 1) * 3;
-        const availableWidth = this.contentWidth - separatorWidth;
-        const totalWidth = colWidths.reduce((a, b) => a + b, 0);
-        if (totalWidth > availableWidth && availableWidth > numCols) {
-            const scale = availableWidth / totalWidth;
-            for (let c = 0; c < numCols; c++) {
-                colWidths[c] = Math.max(1, Math.floor(colWidths[c] * scale));
+        const tableWidth = Math.max(10, this.width - 2);
+        const availableWidth = tableWidth - separatorWidth;
+        // Shrink the widest column one step at a time until the table fits.
+        // Preserves natural width on narrow columns — proportional scaling
+        // over-truncates when only one column is oversized.
+        let total = colWidths.reduce((a, b) => a + b, 0);
+        while (total > availableWidth && availableWidth > numCols) {
+            let maxIdx = 0;
+            for (let c = 1; c < numCols; c++) {
+                if (colWidths[c] > colWidths[maxIdx])
+                    maxIdx = c;
             }
+            if (colWidths[maxIdx] <= 1)
+                break;
+            colWidths[maxIdx]--;
+            total--;
         }
         // Render rows
         const hasHeader = sepIdx.includes(1) && dataRows.length > 1;
@@ -216,7 +294,14 @@ export class MarkdownRenderer {
             const isHeader = hasHeader && i === 0;
             const cells = row.map((cell, c) => {
                 const w = colWidths[c];
-                const text = visibleLen(cell) > w ? truncateToWidth(cell, w) : padEndToWidth(cell, w);
+                const rendered = this.renderInline(cell);
+                // Truncation can yield width < w when a CJK double-width char
+                // won't fit the remaining budget — always re-pad to keep cells
+                // aligned with the border grid.
+                const clipped = visibleLen(rendered) > w
+                    ? truncateAnsiToWidth(rendered, w)
+                    : rendered;
+                const text = padEndToWidth(clipped, w);
                 return isHeader ? `${p.bold}${text}${p.reset}` : text;
             });
             this.writeLine(`${p.dim}│${p.reset} ${cells.join(` ${p.dim}│${p.reset} `)} ${p.dim}│${p.reset}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",
@@ -34,6 +34,10 @@
       "types": "./dist/extensions/index.d.ts",
       "default": "./dist/extensions/index.js"
     },
+    "./shell": {
+      "types": "./dist/shell/shell.d.ts",
+      "default": "./dist/shell/shell.js"
+    },
     "./utils/stream-transform": {
       "types": "./dist/utils/stream-transform.d.ts",
       "default": "./dist/utils/stream-transform.js"
@@ -70,6 +74,14 @@
       "types": "./dist/agent/token-budget.d.ts",
       "default": "./dist/agent/token-budget.js"
     },
+    "./agent/history-file": {
+      "types": "./dist/agent/history-file.d.ts",
+      "default": "./dist/agent/history-file.js"
+    },
+    "./agent/nuclear-form": {
+      "types": "./dist/agent/nuclear-form.d.ts",
+      "default": "./dist/agent/nuclear-form.js"
+    },
     "./executor": {
       "types": "./dist/executor.d.ts",
       "default": "./dist/executor.js"
@@ -114,6 +126,8 @@
     "marked": "^17.0.6",
     "node-pty": "^1.2.0-beta.12",
     "openai": "^6.34.0",
+    "string-width": "^8.2.0",
+    "strip-ansi": "^7.2.0",
     "tsx": "^4.19.0"
   },
   "devDependencies": {