agent-sh 0.15.7 → 0.15.9

package/dist/agent/agent-loop.d.ts

@@ -84,6 +84,9 @@ export declare class AgentLoop implements AgentBackend {
     kill(): void;
     private cancel;
     private reasoningParams;
+    /** Resume-stable conversation id from the frontend (e.g. ashi); undefined
+     *  when the frontend tracks no session. */
+    private currentSessionId;
     private resolveEndpoint;
     private pullModels;
     private emitIdentity;

package/dist/agent/agent-loop.js

@@ -390,6 +390,17 @@ export class AgentLoop {
         const effort = this.thinkingLevel === "xhigh" ? "high" : this.thinkingLevel;
         return { reasoning_effort: effort };
     }
+    /** Resume-stable conversation id from the frontend (e.g. ashi); undefined
+     *  when the frontend tracks no session. */
+    currentSessionId() {
+        try {
+            const id = this.handlers.call("session:current-id");
+            return typeof id === "string" && id ? id : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     resolveEndpoint(m) {
         try {
             return this.handlers.call("agent:resolve-endpoint", { provider: m.provider, id: m.id });
@@ -1251,7 +1262,12 @@ export class AgentLoop {
             ...this.reasoningParams(),
         };
         this.bus.emit("llm:request", requestParams);
-        const stream = await this.llmClient.stream({ ...requestParams, signal });
+        const headers = this.activeEndpoint?.buildRequestHeaders?.({ sessionId: this.currentSessionId() });
+        const stream = await this.llmClient.stream({
+            ...requestParams,
+            signal,
+            ...(headers && Object.keys(headers).length ? { headers } : {}),
+        });
         try {
             for await (const chunk of stream) {
                 if (signal.aborted)

package/dist/agent/events.d.ts

@@ -21,6 +21,9 @@ declare module "../core/event-bus.js" {
             id: string;
             reasoningParams?: (level: string, model?: string) => Record<string, unknown>;
             cacheTokens?: (usage: Record<string, unknown>) => number | undefined;
+            requestHeaders?: (info: {
+                sessionId?: string;
+            }) => Record<string, string>;
         };
         "agent:models-changed": Record<string, never>;
         "config:switch-provider": {

package/dist/agent/host-types.d.ts

@@ -85,6 +85,9 @@ export interface ModelEndpoint {
     baseURL?: string;
     buildReasoningParams?: (level: string) => Record<string, unknown>;
     extractCachedTokens?: (usage: Record<string, unknown>) => number | undefined;
+    buildRequestHeaders?: (info: {
+        sessionId?: string;
+    }) => Record<string, string>;
 }
 /**
  * Capabilities the agent host adds on top of CoreContext. Only available
@@ -100,6 +103,9 @@ export interface AgentSurface {
         configure: (id: string, opts: {
             reasoningParams?: (level: string, model?: string) => Record<string, unknown>;
             cacheTokens?: (usage: Record<string, unknown>) => number | undefined;
+            requestHeaders?: (info: {
+                sessionId?: string;
+            }) => Record<string, string>;
         }) => void;
     };
     registerTool: (tool: ToolDefinition) => void;

package/dist/agent/index.js

@@ -105,6 +105,7 @@ export default function agentBackend(ctx) {
         return hook ? (level) => hook(level, model) : defaultReasoningBuilder;
     };
     const bindCacheTokens = (shapeId) => providerHooks.get(shapeId)?.cacheTokens ?? defaultCacheTokens;
+    const bindRequestHeaders = (shapeId) => providerHooks.get(shapeId)?.requestHeaders;
     const agentSurface = {
         llm: createLlmFacade({ list: ctx.list, call: ctx.call }),
         providers: {
@@ -322,6 +323,7 @@ export default function agentBackend(ctx) {
             baseURL: p.baseURL,
             buildReasoningParams: bindReasoning(shapeId, modelId),
             extractCachedTokens: bindCacheTokens(shapeId),
+            buildRequestHeaders: bindRequestHeaders(shapeId),
         };
     };
     ctx.define("agent:get-models", () => buildModels());
@@ -365,12 +367,14 @@ export default function agentBackend(ctx) {
             bus.emit("config:switch-model", { id: pendingModel, provider: pendingProvider });
         }
     });
-    bus.on("provider:configure", ({ id, reasoningParams, cacheTokens }) => {
+    bus.on("provider:configure", ({ id, reasoningParams, cacheTokens, requestHeaders }) => {
         const prev = providerHooks.get(id) ?? {};
         if (reasoningParams !== undefined)
             prev.reasoningParams = reasoningParams;
         if (cacheTokens !== undefined)
             prev.cacheTokens = cacheTokens;
+        if (requestHeaders !== undefined)
+            prev.requestHeaders = requestHeaders;
         providerHooks.set(id, prev);
     });
     bus.on("core:extensions-loaded", ({ names }) => {

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

@@ -39,6 +39,8 @@ export type StreamOpts = {
     model?: string;
     max_tokens?: number;
     signal?: AbortSignal;
+    /** Per-request transport headers, forwarded to the SDK (not request body). */
+    headers?: Record<string, string>;
 } & Record<string, unknown>;
 export type CompleteOpts = {
     messages: ChatCompletionMessageParam[];

package/dist/agent/llm-client.js

@@ -43,7 +43,7 @@ export class LlmClient {
         this.model = newConfig.model;
     }
     stream(opts) {
-        const { signal, messages, tools, model, max_tokens, ...rest } = opts;
+        const { signal, headers, messages, tools, model, max_tokens, ...rest } = opts;
         const body = {
             ...rest,
             model: model ?? this.model,
@@ -53,7 +53,7 @@ export class LlmClient {
             stream: true,
             stream_options: { include_usage: true },
         };
-        return this.client.chat.completions.create(body, { signal });
+        return this.client.chat.completions.create(body, { signal, headers });
     }
     async complete(opts) {
         const { messages, model, max_tokens, ...rest } = opts;

package/dist/agent/providers/openrouter.js

@@ -24,7 +24,17 @@ function toModalities(input) {
 }
 export default function activate(ctx) {
     const apiKey = resolveApiKey("openrouter").key;
-    ctx.agent.providers.configure("openrouter", { reasoningParams: buildReasoningParams });
+    ctx.agent.providers.configure("openrouter", {
+        reasoningParams: buildReasoningParams,
+        // x-session-id pins sticky provider routing across turns so prompt caches
+        // stay warm even when compaction rewrites the opening messages.
+        requestHeaders: ({ sessionId }) => {
+            const headers = {};
+            if (sessionId)
+                headers["x-session-id"] = sessionId;
+            return headers;
+        },
+    });
     ctx.agent.providers.register({
         id: "openrouter",
         apiKey: apiKey ?? undefined,

package/dist/shell/input-handler.js

@@ -57,7 +57,8 @@ export class InputHandler {
     loadHistory() {
         try {
             const data = fs.readFileSync(HISTORY_FILE, "utf-8");
-            this.history = data.split("\n").filter(Boolean);
+            this.history = data.split("\n").filter(Boolean)
+                .map((l) => l.replace(/\\([\\n])/g, (_, c) => c === "n" ? "\n" : "\\"));
         }
         catch {
         }
@@ -66,7 +67,8 @@ export class InputHandler {
         try {
             const { historySize } = getSettings();
             fs.mkdirSync(path.dirname(HISTORY_FILE), { recursive: true });
-            const lines = this.history.slice(-historySize);
+            const lines = this.history.slice(-historySize)
+                .map((l) => l.replace(/\\/g, "\\\\").replace(/\n/g, "\\n"));
             fs.writeFileSync(HISTORY_FILE, lines.join("\n") + "\n");
         }
         catch {
@@ -373,7 +375,7 @@ export class InputHandler {
                     this.editor.clear();
                     this.view.resetCursor();
                     this.dismissAutocomplete();
-                    if (query && query.startsWith("/")) {
+                    if (query && query.startsWith("/") && !query.includes("\n")) {
                         const spaceIdx = query.indexOf(" ");
                         const name = spaceIdx === -1 ? query : query.slice(0, spaceIdx);
                         const args = spaceIdx === -1 ? "" : query.slice(spaceIdx + 1).trim();

package/dist/shell/strategies/bash.js

@@ -40,8 +40,16 @@ export const bashStrategy = {
             '  [[ $__agent_sh_preexec_ran == 1 ]] && return',
             '  [[ -n $COMP_LINE ]] && return',
             "  __agent_sh_preexec_ran=1",
-            "  local this_cmd",
-            `  this_cmd=$(HISTTIMEFORMAT='' builtin history 1 | command sed 's/^ *[0-9]* *//')`,
+            "  local this_cmd hist_cmd",
+            `  hist_cmd=$(HISTTIMEFORMAT='' builtin history 1 | command sed 's/^ *[0-9]* *//')`,
+            "  # history 1 carries the full typed line but goes stale when the user's",
+            "  # PROMPT_COMMAND reloads history (history -c/-r). Trust it only when it",
+            "  # matches the command bash is about to run; else use $BASH_COMMAND.",
+            '  if [[ -n $hist_cmd && $hist_cmd == "$BASH_COMMAND"* ]]; then',
+            "    this_cmd=$hist_cmd",
+            "  else",
+            "    this_cmd=$BASH_COMMAND",
+            "  fi",
             `  printf '\\e]9997;${instanceTag};%s\\a' "$this_cmd"`,
             "}",
             "trap '__agent_sh_emit_preexec' DEBUG",

package/dist/shell/terminal.d.ts

@@ -1,12 +1,3 @@
-/**
- * Terminal — the user-facing I/O endpoint that a Shell talks to.
- *
- * Shell wraps a *pseudo*-terminal (the PTY the child shell sees). This
- * interface is the *real* terminal (or its substitute) on the other end:
- * bytes in, bytes out, dimensions, resize notifications. The default
- * factory wires it to process.stdin/stdout for the CLI; headless hosts
- * (multi-session web hubs, tests) supply their own.
- */
 import type { RenderSurface } from "../utils/compositor.js";
 export interface Terminal {
     write(data: string): void;
@@ -23,8 +14,8 @@ export interface Terminal {
         resume(): void;
     };
 }
-/** Default Terminal: wraps process.stdin/stdout. */
-export declare function processTerminal(): Terminal;
+/** Default Terminal: wraps process.stdin/stdout (injectable for tests). */
+export declare function processTerminal(stdin?: NodeJS.ReadStream, stdout?: NodeJS.WriteStream): Terminal;
 /**
  * No-op terminal for non-rendering hosts (tests, agent-only embeds).
  * Writes are discarded; input/resize never fire.

package/dist/shell/terminal.js

@@ -1,42 +1,60 @@
-/** Default Terminal: wraps process.stdin/stdout. */
-export function processTerminal() {
+/**
+ * Terminal — the user-facing I/O endpoint that a Shell talks to.
+ *
+ * Shell wraps a *pseudo*-terminal (the PTY the child shell sees). This
+ * interface is the *real* terminal (or its substitute) on the other end:
+ * bytes in, bytes out, dimensions, resize notifications. The default
+ * factory wires it to process.stdin/stdout for the CLI; headless hosts
+ * (multi-session web hubs, tests) supply their own.
+ */
+import { StringDecoder } from "node:string_decoder";
+/** Default Terminal: wraps process.stdin/stdout (injectable for tests). */
+export function processTerminal(stdin = process.stdin, stdout = process.stdout) {
     return {
         write(data) {
-            if (process.stdout.writable) {
+            if (stdout.writable) {
                 try {
-                    process.stdout.write(data);
+                    stdout.write(data);
                 }
                 catch { /* ignore */ }
             }
         },
         onInput(cb) {
-            const handler = (b) => cb(b.toString("utf-8"));
-            process.stdin.on("data", handler);
-            return () => { process.stdin.off("data", handler); };
+            // Stateful decode: tty chunk boundaries can land mid-way through a
+            // multibyte UTF-8 sequence (large pastes), so per-chunk toString()
+            // would emit U+FFFD for the torn halves.
+            const decoder = new StringDecoder("utf-8");
+            const handler = (b) => {
+                const text = decoder.write(b);
+                if (text)
+                    cb(text);
+            };
+            stdin.on("data", handler);
+            return () => { stdin.off("data", handler); };
         },
         onResize(cb) {
-            const handler = () => cb(process.stdout.columns || 80, process.stdout.rows || 24);
-            process.stdout.on("resize", handler);
-            return () => { process.stdout.off("resize", handler); };
+            const handler = () => cb(stdout.columns || 80, stdout.rows || 24);
+            stdout.on("resize", handler);
+            return () => { stdout.off("resize", handler); };
         },
-        cols() { return process.stdout.columns || 80; },
-        rows() { return process.stdout.rows || 24; },
+        cols() { return stdout.columns || 80; },
+        rows() { return stdout.rows || 24; },
         suspendInput() {
-            const wasRaw = process.stdin.isTTY && process.stdin.isRaw;
-            if (process.stdin.isTTY) {
+            const wasRaw = stdin.isTTY && stdin.isRaw;
+            if (stdin.isTTY) {
                 try {
-                    process.stdin.setRawMode(false);
-                    process.stdin.pause();
+                    stdin.setRawMode(false);
+                    stdin.pause();
                 }
                 catch { /* ignore */ }
             }
             return {
                 resume() {
-                    if (process.stdin.isTTY) {
+                    if (stdin.isTTY) {
                         try {
-                            process.stdin.resume();
+                            stdin.resume();
                             if (wasRaw)
-                                process.stdin.setRawMode(true);
+                                stdin.setRawMode(true);
                         }
                         catch { /* ignore */ }
                     }

package/dist/shell/tui-renderer.js

@@ -845,7 +845,7 @@ export default function activate(ctx) {
             ? getSettings().readOutputMaxLines
             : getSettings().maxCommandOutputLines;
         s.commandOutputBuffer += chunk;
-        const lines = s.commandOutputBuffer.split("\n");
+        const lines = s.commandOutputBuffer.split(/\r?\n/);
         s.commandOutputBuffer = lines.pop();
         for (const line of lines) {
             if (s.commandOutputLineCount < maxLines) {

package/dist/utils/ansi.d.ts

@@ -44,3 +44,10 @@ export declare function padEndToWidth(str: string, targetWidth: number): string;
  *  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;
+/**
+ * Sanitize text for painting at a fixed screen position: SGR (color/style)
+ * passes through; anything else that would move the cursor or mutate
+ * terminal state mid-row is dropped. Tabs become a single space so painted
+ * width matches `stripAnsi`-based measurement.
+ */
+export declare function stripCursorControls(str: string): string;

package/dist/utils/ansi.js

@@ -134,3 +134,23 @@ export function padEndToWidth(str, targetWidth) {
 export function stripAnsi(str) {
     return stripAnsiPkg(str).replace(/\r/g, "");
 }
+/**
+ * Sanitize text for painting at a fixed screen position: SGR (color/style)
+ * passes through; anything else that would move the cursor or mutate
+ * terminal state mid-row is dropped. Tabs become a single space so painted
+ * width matches `stripAnsi`-based measurement.
+ */
+export function stripCursorControls(str) {
+    // Park SGR behind NUL placeholders so the strips below can't eat their ESC bytes.
+    const sgr = [];
+    const cleaned = str
+        .replace(/\x00/g, "")
+        .replace(/\x1b\[[0-9;:]*m/g, (m) => { sgr.push(m); return "\x00"; })
+        .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g, "")
+        .replace(/\x1b\[[0-9;:?]*[ -/]*[@-~]/g, "")
+        .replace(/\x1b./g, "")
+        .replace(/\t/g, " ")
+        .replace(/[\x01-\x08\x0a-\x1f\x7f]/g, "");
+    let i = 0;
+    return cleaned.replace(/\x00/g, () => sgr[i++] ?? "");
+}

package/dist/utils/floating-panel.js

@@ -30,7 +30,7 @@
  * Usage from extensions:
  *   import { FloatingPanel } from "agent-sh/utils/floating-panel.js";
  */
-import { stripAnsi } from "./ansi.js";
+import { stripAnsi, stripCursorControls } from "./ansi.js";
 import { wrapLine } from "./markdown.js";
 import { LineEditor } from "./line-editor.js";
 import { TerminalBuffer } from "./terminal-buffer.js";
@@ -253,10 +253,11 @@ export class FloatingPanel {
         this.handlers.define(`${p}:input`, (_data) => false);
         // Default row builder: truncate and pad
         this.handlers.define(`${p}:build-row`, (content, width) => {
-            const plain = stripAnsi(content);
+            const clean = stripCursorControls(content);
+            const plain = stripAnsi(clean);
             const display = plain.length > width
-                ? content.slice(0, width - 1) + "\u2026"
-                : content;
+                ? clean.slice(0, width - 1) + "\u2026"
+                : clean;
             const pad = Math.max(0, width - stripAnsi(display).length);
             return display + " ".repeat(pad);
         });

package/dist/utils/line-editor.js

@@ -121,7 +121,7 @@ export class LineEditor {
         // paste, since typed input arrives one keystroke per chunk in raw mode.
         if (!this.inPaste && data.length > 1 && /[\r\n]/.test(data)
             && data.indexOf("\x1b[200~") === -1) {
-            this.pasteAccum = data.replace(/\r\n?/g, "\n");
+            this.pasteAccum = data;
             actions.push(...this.commitPaste());
             return actions;
         }
@@ -247,7 +247,7 @@ export class LineEditor {
     consumePasteChunk(data) {
         const endIdx = data.indexOf(PASTE_END);
         if (endIdx !== -1) {
-            this.pasteAccum += data.slice(0, endIdx).replace(/\r/g, "");
+            this.pasteAccum += data.slice(0, endIdx);
             return endIdx;
         }
         let suffixLen = 0;
@@ -258,14 +258,17 @@ export class LineEditor {
             }
         }
         const safeEnd = data.length - suffixLen;
-        this.pasteAccum += data.slice(0, safeEnd).replace(/\r/g, "");
+        this.pasteAccum += data.slice(0, safeEnd);
         if (suffixLen > 0)
             this.pendingSeq = data.slice(safeEnd);
         return -1;
     }
     commitPaste() {
         this.inPaste = false;
-        const accum = this.pasteAccum;
+        // Pasted line separators arrive as \n, \r (xterm convention), or \r\n
+        // depending on terminal; normalize on the full accumulation so a \r\n
+        // pair split across chunks still collapses to one newline.
+        const accum = this.pasteAccum.replace(/\r\n?/g, "\n");
         this.pasteAccum = "";
         if (!accum)
             return [];

package/examples/extensions/ashi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanyilun/ashi",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Ash in an interactive TUI — agent-sh's built-in agent without the shell underneath",
   "type": "module",
   "main": "dist/cli.js",

package/examples/extensions/ashi/src/chat/assistant.ts

@@ -38,7 +38,9 @@ export class AssistantMessage {
     if (this.buffer === "") this.buffer = " ";
     const blocks = this.transform([{ type: "text", text: this.buffer }]);
     if (blocks.every((b) => b.type === "text")) {
-      this.md.setText(stripTrailing(this.buffer));
+      // Render the transformed text, not the raw buffer — transforms may rewrite
+      // content in place (e.g. inline-image sentinels) while staying all-text.
+      this.md.setText(stripTrailing(blocks.map((b) => (b.type === "text" ? b.text : "")).join("")));
       return;
     }
     this.rebuild(blocks);

package/examples/extensions/ashi/src/cli.ts

@@ -34,6 +34,7 @@ import { registerCapture, type Capture } from "./capture.js";
 import { registerRenderDefaults } from "./hooks.js";
 import { registerDefaultSchemaRenderers } from "./default-schema-renderers.js";
 import { createPiTuiRenderer } from "./renderers/pi-tui/index.js";
+import { registerInlineImage, supportsInlineImages } from "./renderers/pi-tui/inline-image.js";
 import type { Renderer } from "./renderer.js";
 import { loadRendererPreference } from "./display-config.js";
 import { applyOutputMode } from "./terminal-mode.js";
@@ -177,6 +178,8 @@ async function main(): Promise<void> {
 
   const ctx = core.extensionContext({ quit: cleanup });
 
+  ctx.define("session:current-id", () => store.current().id);
+
   activateAgent(ctx);
   activateShellContext(ctx);
   await loadBuiltinExtensions(ctx);
@@ -238,6 +241,11 @@ async function main(): Promise<void> {
   registerRenderDefaults(ctx, renderer);
   registerDefaultSchemaRenderers(ctx);
 
+  // Handler presence is how producers detect that inline images are available.
+  if (rendererName === "pi-tui" && supportsInlineImages()) {
+    ctx.define("ashi:inline-image:register", (png: Buffer) => registerInlineImage(png));
+  }
+
   ctx.advise("system-prompt:frontend", (next) => {
     const base = (next() as string) ?? "";
     return base ? `${base}\n\n${ASHI_SURFACE}` : ASHI_SURFACE;

package/examples/extensions/ashi/src/frontend.ts

@@ -399,7 +399,7 @@ export function mountAshi(
       app.requestRender();
       return;
     }
-    pendingUserShell.push({ private: !!opts?.private });
+    pendingUserShell.push({ private: !!opts?.private, command: line });
     if (opts?.private) bus.emit("shell:user-exec-exclude-next", {});
     bus.emit("shell:pty-write", { data: line + "\n" });
   };
@@ -816,12 +816,13 @@ export function mountAshi(
   bus.on("shell:foreground-busy", ({ busy }) => { shellForegroundBusy = busy; });
 
   let activeUserShell: { pair: ToolPair; command: string; isPrivate: boolean } | null = null;
-  bus.on("shell:command-start", ({ command }) => {
+  bus.on("shell:command-start", () => {
     if (agentShellActive) return;
     const intent = pendingUserShell.consume();
     if (!intent) return;
     finalizeThinking();
     if (activeAssistant) { activeAssistant.finalize(); activeAssistant = null; }
+    const command = intent.command;
     const isPrivate = intent.private;
     const name = isPrivate ? "user_bash_private" : "user_bash";
     const pair = renderToolPair({
@@ -861,7 +862,7 @@ export function mountAshi(
     // Drain shell queue before queries so its output lands in the next turn's <shell_events>.
     while (queuedShellLines.length > 0) {
       const item = queuedShellLines.shift()!;
-      pendingUserShell.push({ private: item.private });
+      pendingUserShell.push({ private: item.private, command: item.line });
       if (item.private) bus.emit("shell:user-exec-exclude-next", {});
       bus.emit("shell:pty-write", { data: item.line + "\n" });
     }

package/examples/extensions/ashi/src/renderers/pi-tui/inline-image.ts

@@ -0,0 +1,145 @@
+/**
+ * Inline images in markdown text via the kitty/Ghostty Unicode placeholder
+ * protocol. The image is transmitted out-of-band (cursor-neutral); the frame
+ * carries only `cols` width-1 placeholder cells, so the renderer's wrap/measure
+ * math is unaffected and the line is never treated as an image line. kitty-only.
+ */
+import {
+  allocateImageId,
+  getCapabilities,
+  getCellDimensions,
+  getImageDimensions,
+} from "@earendil-works/pi-tui";
+
+export const SENTINEL_RE = /\x01LI:(\d+)\x01/g;
+export const PLACEHOLDER = String.fromCodePoint(0x10eeee);
+
+// kitty rowcolumn-diacritics: the Nth entry encodes row/column index N
+// (gen/rowcolumn-diacritics.txt in the kitty source).
+const DIACRITICS = [0x0305,0x030D,0x030E,0x0310,0x0312,0x033D,0x033E,0x033F,0x0346,0x034A,0x034B,0x034C,0x0350,0x0351,0x0352,0x0357,0x035B,0x0363,0x0364,0x0365,0x0366,0x0367,0x0368,0x0369,0x036A,0x036B,0x036C,0x036D,0x036E,0x036F,0x0483,0x0484,0x0485,0x0486,0x0487,0x0592,0x0593,0x0594,0x0595,0x0597,0x0598,0x0599,0x059C,0x059D,0x059E,0x059F,0x05A0,0x05A1,0x05A8,0x05A9,0x05AB,0x05AC,0x05AF,0x05C4,0x0610,0x0611,0x0612,0x0613,0x0614,0x0615,0x0616,0x0617,0x0657,0x0658,0x0659,0x065A,0x065B,0x065D,0x065E,0x06D6,0x06D7,0x06D8,0x06D9,0x06DA,0x06DB,0x06DC,0x06DF,0x06E0,0x06E1,0x06E2,0x06E4,0x06E7,0x06E8,0x06EB,0x06EC,0x0730,0x0732,0x0733,0x0735,0x0736,0x073A,0x073D,0x073F,0x0740,0x0741,0x0743,0x0745,0x0747,0x0749,0x074A,0x07EB,0x07EC,0x07ED,0x07EE,0x07EF,0x07F0,0x07F1,0x07F3,0x0816,0x0817,0x0818,0x0819,0x081B,0x081C,0x081D,0x081E,0x081F,0x0820,0x0821,0x0822,0x0823,0x0825,0x0826,0x0827,0x0829,0x082A,0x082B,0x082C,0x082D,0x0951,0x0953,0x0954,0x0F82,0x0F83,0x0F86,0x0F87,0x135D,0x135E,0x135F,0x17DD,0x193A,0x1A17,0x1A75,0x1A76,0x1A77,0x1A78,0x1A79,0x1A7A,0x1A7B,0x1A7C,0x1B6B,0x1B6D,0x1B6E,0x1B6F,0x1B70,0x1B71,0x1B72,0x1B73,0x1CD0,0x1CD1,0x1CD2,0x1CDA,0x1CDB,0x1CE0,0x1DC0,0x1DC1,0x1DC3,0x1DC4,0x1DC5,0x1DC6,0x1DC7,0x1DC8,0x1DC9,0x1DCB,0x1DCC,0x1DD1,0x1DD2,0x1DD3,0x1DD4,0x1DD5,0x1DD6,0x1DD7,0x1DD8,0x1DD9,0x1DDA,0x1DDB,0x1DDC,0x1DDD,0x1DDE,0x1DDF,0x1DE0,0x1DE1,0x1DE2,0x1DE3,0x1DE4,0x1DE5,0x1DE6,0x1DFE,0x20D0,0x20D1,0x20D4,0x20D5,0x20D6,0x20D7,0x20DB,0x20DC,0x20E1,0x20E7,0x20E9,0x20F0,0x2CEF,0x2CF0,0x2CF1,0x2DE0,0x2DE1,0x2DE2,0x2DE3,0x2DE4,0x2DE5,0x2DE6,0x2DE7,0x2DE8,0x2DE9,0x2DEA,0x2DEB,0x2DEC,0x2DED,0x2DEE,0x2DEF,0x2DF0,0x2DF1,0x2DF2,0x2DF3,0x2DF4,0x2DF5,0x2DF6,0x2DF7,0x2DF8,0x2DF9,0x2DFA,0x2DFB,0x2DFC,0x2DFD,0x2DFE,0x2DFF,0xA66F,0xA67C,0xA67D,0xA6F0,0xA6F1,0xA8E0,0xA8E1,0xA8E2,0xA8E3,0xA8E4,0xA8E5,0xA8E6,0xA8E7,0xA8E8,0xA8E9,0xA8EA,0xA8EB,0xA8EC,0xA8ED,0xA8EE,0xA8EF,0xA8F0,0xA8F1,0xAAB0,0xAAB2,0xAAB3,0xAAB7,0xAAB8,0xAABE,0xAABF,0xAAC1,0xFE20,0xFE21,0xFE22,0xFE23,0xFE24,0xFE25,0xFE26,0x10A0F,0x10A38,0x1D185,0x1D186,0x1D187,0x1D188,0x1D189,0x1D1AA,0x1D1AB,0x1D1AC,0x1D1AD,0x1D242,0x1D243,0x1D244];
+
+const ESC = "\x1b";
+const diacritic = (i: number): string =>
+  String.fromCodePoint(DIACRITICS[Math.min(i, DIACRITICS.length - 1)]!);
+
+interface Entry {
+  base64: string;
+  widthPx: number;
+  heightPx: number;
+  transmitted: boolean;
+  placedCols: number;
+}
+
+const registry = new Map<number, Entry>();
+
+export function supportsInlineImages(): boolean {
+  return getCapabilities().images === "kitty";
+}
+
+export function registerInlineImage(png: Buffer): number | null {
+  if (!supportsInlineImages()) return null;
+  const base64 = png.toString("base64");
+  const dims = getImageDimensions(base64, "image/png");
+  if (!dims || dims.heightPx <= 0) return null;
+  const id = allocateImageId();
+  registry.set(id, { base64, widthPx: dims.widthPx, heightPx: dims.heightPx, transmitted: false, placedCols: 0 });
+  return id;
+}
+
+const maxInlineCols = (): number => Math.max(8, (process.stdout.columns ?? 80) - 4);
+
+export function inlineCols(id: number, maxCols = maxInlineCols()): number | null {
+  const e = registry.get(id);
+  if (!e) return null;
+  const cell = getCellDimensions();
+  const cols = Math.round((e.widthPx / e.heightPx) * (cell.heightPx / cell.widthPx));
+  // Column index is carried by a diacritic, so cols can't exceed the table.
+  return Math.max(1, Math.min(maxCols, DIACRITICS.length, cols));
+}
+
+// Transmits once, then re-places only when cols changes (resize). `write` must
+// target the same stream as the composed frame so the data lands before the cells.
+export function emitInlineImage(id: number, cols: number, write: (s: string) => void): void {
+  const e = registry.get(id);
+  if (!e) return;
+  if (!e.transmitted) {
+    e.transmitted = true;
+    e.placedCols = cols;
+    const b64 = e.base64;
+    const CHUNK = 4096;
+    for (let i = 0; i < b64.length; i += CHUNK) {
+      const chunk = b64.slice(i, i + CHUNK);
+      const last = i + CHUNK >= b64.length;
+      write(
+        i === 0
+          ? `${ESC}_Gq=2,a=T,U=1,f=100,t=d,i=${id},c=${cols},r=1,m=${last ? 0 : 1};${chunk}${ESC}\\`
+          : `${ESC}_Gq=2,m=${last ? 0 : 1};${chunk}${ESC}\\`,
+      );
+    }
+  } else if (e.placedCols !== cols) {
+    e.placedCols = cols;
+    write(`${ESC}_Gq=2,a=p,U=1,i=${id},c=${cols},r=1${ESC}\\`);
+  }
+}
+
+// Each cell encodes the id's low 24 bits in the fg colour and its high byte in the
+// third diacritic (row, column, id-high) — allocateImageId() ids use all 32 bits.
+// `colStart` offsets the column index so an image split across lines (wrap) keeps
+// continuous columns instead of repeating its left edge.
+export function inlinePlaceholder(id: number, count: number, colStart = 0): string {
+  const hi = diacritic((id >> 24) & 255);
+  let s = `${ESC}[38;2;${(id >> 16) & 255};${(id >> 8) & 255};${id & 255}m`;
+  for (let j = 0; j < count; j++) s += PLACEHOLDER + diacritic(0) + diacritic(colStart + j) + hi;
+  return s + `${ESC}[39m`;
+}
+
+export interface InlineItem {
+  id: number;
+  cols: number;
+}
+
+// Repaint the reserved PLACEHOLDER runs as real kitty placeholder cells. Cells are
+// partitioned by each image's reserved `cols` rather than by contiguous run, so
+// adjacent images (`$a$$b$` → one fused run) and an image the wrapper split across
+// lines both keep their ids aligned. `transmit` fires once per image, when its
+// first cell is placed. Pure apart from the injected `transmit` callback.
+export function paintInlineImages(
+  lines: string[],
+  items: InlineItem[],
+  transmit: (id: number, cols: number) => void,
+): string[] {
+  if (items.length === 0) return lines;
+  let k = 0; // index of the image currently being placed
+  let placed = 0; // cells of image k already emitted across prior lines
+  return lines.map((line) => {
+    if (k >= items.length || !line.includes(PLACEHOLDER)) return line;
+    let out = "";
+    let i = 0;
+    while (i < line.length) {
+      const ch = String.fromCodePoint(line.codePointAt(i)!);
+      if (ch === PLACEHOLDER && k < items.length) {
+        const item = items[k]!;
+        let count = 0;
+        while (
+          i < line.length &&
+          String.fromCodePoint(line.codePointAt(i)!) === PLACEHOLDER &&
+          placed + count < item.cols
+        ) {
+          count++;
+          i += PLACEHOLDER.length;
+        }
+        if (placed === 0) transmit(item.id, item.cols);
+        out += inlinePlaceholder(item.id, count, placed);
+        placed += count;
+        if (placed >= item.cols) {
+          k++;
+          placed = 0;
+        }
+      } else {
+        out += ch;
+        i += ch.length;
+      }
+    }
+    return out;
+  });
+}