agent-sh 0.14.9 → 0.14.11

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

@@ -1,44 +1,40 @@
-import type { Component } from "@earendil-works/pi-tui";
 import type { ExtensionContext } from "agent-sh/types";
-import { AssistantMessage, ThinkingBlock, UserMessage } from "./components.js";
+import type { Renderer, RenderNodes, ToolCallView, ToolResultView } from "./renderer.js";
+import { UserMessage } from "./chat/user-message.js";
+import { AssistantMessage, type EquationRenderer } from "./chat/assistant.js";
+import { ThinkingBlock } from "./chat/thinking.js";
 import { loadDisplayResolver, type ToolResultMode } from "./display-config.js";
-import { isRenderModel, mountCall, mountResult, type RenderModel } from "./schema.js";
+import { isRenderModel, type RenderModel } from "./schema.js";
 
 export interface RenderState {
   state: Record<string, unknown>;
   invalidate: () => void;
+  nodes: RenderNodes;
 }
 
 export interface UserMessageArgs extends RenderState { text: string }
 export interface AssistantArgs extends RenderState { text: string }
 export interface ThinkingArgs extends RenderState { text: string; hidden: boolean }
 
-/** The contract ashi's frontend mutates on the call-side component. Schema
- *  renderers satisfy this via SchemaCallComponent — extension authors don't
- *  implement it directly. */
-export interface ToolCallView extends Component {
-  setStatus(opts: { exitCode: number | null; elapsedMs: number; summary?: string }): void;
-  toggleExpanded?(): void;
-}
-
-/** Result-side counterpart. setDiffRenderer receives the width-aware diff
- *  closure produced by the edit/write tool at finalize. */
-export interface ToolResultView extends Component {
-  appendChunk(chunk: string): void;
-  setDiffRenderer(fn: (width: number) => string[]): void;
-  finalize(opts: { exitCode: number | null; summary?: string }): void;
-  toggleExpanded(): void;
-}
-
 const SCHEMA_PREFIX = "ashi:render-tool:";
 
-export function registerRenderDefaults(ctx: ExtensionContext): void {
-  ctx.define("ashi:render-user-message", (args: UserMessageArgs): Component => {
-    return new UserMessage(args.text);
-  });
+export function registerRenderDefaults(ctx: ExtensionContext, renderer: Renderer): void {
+  // Cache the PNG, not the node: finalize/rehydrate can render an equation twice.
+  const equationPng = new Map<string, Buffer | null>();
+  const renderEquation: EquationRenderer = (src) => {
+    if (!equationPng.has(src)) {
+      equationPng.set(src, (ctx.call("latex:render-equation", src) as Buffer | null) ?? null);
+    }
+    const png = equationPng.get(src) ?? null;
+    return png && renderer.capabilities.images ? renderer.image(png) : null;
+  };
+
+  ctx.define("ashi:render-user-message", (args: UserMessageArgs) =>
+    new UserMessage(renderer, args.text));
 
-  ctx.define("ashi:render-assistant", (args: AssistantArgs): Component => {
-    const msg = new AssistantMessage();
+  ctx.define("ashi:render-assistant", (args: AssistantArgs) => {
+    const eq = ctx.list().includes("latex:render-equation") ? renderEquation : undefined;
+    const msg = new AssistantMessage(renderer, eq);
     if (args.text) {
       msg.appendText(args.text);
       msg.finalize();
@@ -46,8 +42,8 @@ export function registerRenderDefaults(ctx: ExtensionContext): void {
     return msg;
   });
 
-  ctx.define("ashi:render-thinking", (args: ThinkingArgs): Component => {
-    const tb = new ThinkingBlock();
+  ctx.define("ashi:render-thinking", (args: ThinkingArgs) => {
+    const tb = new ThinkingBlock(renderer);
     if (args.text) {
       tb.appendText(args.text);
       tb.finalize();
@@ -76,14 +72,12 @@ export interface ToolResultResolveArgs {
 export interface ToolHookResolver {
   call: (args: ToolCallResolveArgs) => ToolCallView;
   result: (args: ToolResultResolveArgs) => ToolResultView;
-  modeFor: (name: string) => { mode: ToolResultMode; previewLines: number };
+  modeFor: (name: string) => { mode: ToolResultMode; previewLines: number; expandedLines: number };
 }
 
-/** Resolves a tool name to a schema RenderModel — :{name} first, then :default.
- *  Cache the registered-handler set; callers can `refresh()` after extensions
- *  register new tool-specific renderers. */
 export function createToolHookResolver(
   ctx: ExtensionContext,
+  renderer: Renderer,
 ): ToolHookResolver & { refresh: () => void } {
   const resolver = loadDisplayResolver();
   let registered = new Set(ctx.list());
@@ -97,7 +91,6 @@ export function createToolHookResolver(
     throw new Error(`no render model for tool "${name}" and no ${SCHEMA_PREFIX}default registered`);
   };
 
-  // SchemaResultComponent.render(width) corrects env.width on the first frame.
   const initialWidth = (): number => process.stdout.columns ?? 80;
 
   return {
@@ -106,17 +99,17 @@ export function createToolHookResolver(
     },
     modeFor(name: string) {
       const e = resolver.resolve(name, schemaModel(name).display);
-      return { mode: e.result, previewLines: e.previewLines };
+      return { mode: e.result, previewLines: e.previewLines, expandedLines: e.expandedLines };
     },
     call(args) {
-      const { mode, previewLines } = this.modeFor(args.name);
-      return mountCall(schemaModel(args.name), args,
-        { width: initialWidth(), mode, previewLines }) as ToolCallView;
+      const { mode, previewLines, expandedLines } = this.modeFor(args.name);
+      return renderer.mountToolCall(schemaModel(args.name), args,
+        { width: initialWidth(), mode, previewLines, expandedLines });
     },
     result(args) {
-      const { mode, previewLines } = this.modeFor(args.name);
-      return mountResult(schemaModel(args.name), { ...args, title: args.name },
-        { width: initialWidth(), mode, previewLines }) as ToolResultView;
+      const { mode, previewLines, expandedLines } = this.modeFor(args.name);
+      return renderer.mountToolResult(schemaModel(args.name), { ...args, title: args.name },
+        { width: initialWidth(), mode, previewLines, expandedLines });
     },
   };
 }

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

@@ -0,0 +1,222 @@
+import { segmentsToString, type MountArgs, type MountEnv, type RenderModel, type Segment } from "./schema.js";
+
+declare const nodeBrand: unique symbol;
+export interface RenderNode {
+  readonly [nodeBrand]: true;
+}
+
+export interface StyledSink {
+  /** Pre-styled lines, painted verbatim (no reflow). */
+  setLines(lines: string[]): void;
+  setText(text: string): void;
+}
+
+export interface TextView extends StyledSink {
+  node: RenderNode;
+  setRenderFn(fn: ((width: number) => string[]) | null): void;
+}
+
+export interface MarkdownOptions {
+  color?: (t: string) => string;
+  bgColor?: (t: string) => string;
+  paddingX?: number;
+  paddingY?: number;
+  osc133Zones?: boolean;
+  /** Primary assistant response — renderers may show a role bullet; others ignore. */
+  bullet?: boolean;
+}
+
+/** Streaming: ashi pushes the full buffer each update; renderer reflows. */
+export interface MarkdownView {
+  node: RenderNode;
+  setText(full: string): void;
+}
+
+export interface ContainerView {
+  node: RenderNode;
+  addChild(child: RenderNode): void;
+  removeChild(child: RenderNode): void;
+  clear(): void;
+}
+
+export interface RenderNodes {
+  text(opts?: { paddingX?: number; paddingY?: number }): TextView;
+  markdown(opts?: MarkdownOptions): MarkdownView;
+  /** Null when the renderer can't show images. */
+  image(png: Buffer): RenderNode | null;
+  container(): ContainerView;
+  spacer(rows: number): RenderNode;
+}
+
+export interface KeyEvent {
+  matches(name: string): boolean;
+  isRelease(): boolean;
+  isRepeat(): boolean;
+}
+
+export type KeyHandler = (key: KeyEvent) => { consume: boolean } | void;
+
+export interface AutocompleteItem {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+export interface AutocompleteSuggestions {
+  items: AutocompleteItem[];
+  prefix: string;
+}
+
+export interface AutocompleteProvider {
+  getSuggestions(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+  ): Promise<AutocompleteSuggestions | null>;
+}
+
+export interface InputView {
+  node: RenderNode;
+  getText(): string;
+  setText(text: string): void;
+  /** Cursor position — the substrate's autocomplete queries the provider in line/col. */
+  getCursor(): { line: number; col: number };
+  /** Apply a completion: delete `count` chars before the cursor, insert `text`, cursor after. */
+  replaceBeforeCursor(count: number, text: string): void;
+  onChange(fn: (text: string) => void): void;
+  onSubmit(fn: (text: string) => void): void;
+  /** Default border color fn, so callers can restore after a temporary change. */
+  readonly defaultBorderColor: (t: string) => string;
+  setBorderColor(fn: (t: string) => string): void;
+  invalidate(): void;
+}
+
+export interface SelectItem {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+export interface SelectView {
+  node: RenderNode;
+  setSelectedIndex(i: number): void;
+  getSelectedItem(): SelectItem | undefined;
+  onSelect(fn: (item: SelectItem) => void | Promise<void>): void;
+  onCancel(fn: () => void): void;
+}
+
+export interface LoaderView {
+  node: RenderNode;
+  stop(): void;
+}
+
+export interface App {
+  scrollback: ContainerView;
+  footerSlot: ContainerView;
+  queueSlot: ContainerView;
+  input: InputView;
+  /** Slot rendered directly beneath the input (e.g. the autocomplete suggestion list). */
+  belowInput: ContainerView;
+  status: TextView;
+  setFocus(target: RenderNode): void;
+  focusInput(): void;
+  requestRender(force?: boolean): void;
+  /** Marks current scrollback as settled; the boundary for renderers that commit finished turns to native scrollback (Ink's <Static>). Others ignore it. */
+  commitScrollback?(): void;
+  start(): void;
+  stop(): void;
+  onKey(handler: KeyHandler): void;
+  createSelectList(items: SelectItem[], opts: { visibleRows: number }): SelectView;
+  createLoader(label: string, color: (t: string) => string, muted: (t: string) => string): LoaderView;
+}
+
+export interface ToolCallView {
+  node: RenderNode;
+  setStatus(opts: { exitCode: number | null; elapsedMs: number; summary?: string }): void;
+  toggleExpanded?(): void;
+}
+
+export interface ToolResultView {
+  node: RenderNode;
+  appendChunk(chunk: string): void;
+  /** Width-aware diff closure produced by the edit/write tool at finalize. */
+  setDiffRenderer(fn: (width: number) => string[]): void;
+  finalize(opts: { exitCode: number | null; summary?: string }): void;
+  toggleExpanded(): void;
+}
+
+export interface ToolGroupChild {
+  name: string;
+  detail: string;
+  status?: { exitCode: number | null; summary?: string };
+}
+
+/** A run of same-kind tool calls: substrate owns the state, renderer owns the look. */
+export interface ToolGroupModel {
+  kind: string;
+  icon: string;
+  children: ToolGroupChild[];
+  hidden: { count: number; ok: boolean } | null;
+  expanded: boolean;
+  open: boolean;
+}
+
+export interface ToolGroupView {
+  node: RenderNode;
+  update(model: ToolGroupModel): void;
+}
+
+/** Default tool-group rendering (`├`/`└` tree): one styled line per row, no indent. */
+export function renderToolGroupLines(model: ToolGroupModel): string[] {
+  const lines: string[] = [
+    segmentsToString([
+      { text: model.icon, style: { color: "warning" } },
+      " ",
+      { text: model.kind, style: { bold: true, color: "toolTitle" } },
+    ]),
+  ];
+  if (model.hidden) {
+    const noun = model.hidden.count === 1 ? "earlier call" : "earlier calls";
+    lines.push(segmentsToString([
+      { text: "├", style: { color: "muted" } }, " ",
+      { text: "⋯", style: { color: "muted" } }, " ",
+      { text: `${model.hidden.count} ${noun}`, style: { color: "muted" } }, " ",
+      { text: model.hidden.ok ? "✓" : "✗", style: { color: model.hidden.ok ? "success" : "error" } },
+    ]));
+  }
+  model.children.forEach((child, idx) => {
+    const segs: Segment[] = [{ text: idx === model.children.length - 1 ? "└" : "├", style: { color: "muted" } }, " "];
+    if (child.name !== model.kind) segs.push({ text: child.name, style: { bold: true, color: "toolTitle" } }, " ");
+    segs.push({ text: child.detail, style: { color: "muted" } }, " ");
+    if (!child.status) {
+      segs.push(" ", { text: "…", style: { color: "muted" } });
+    } else {
+      const ok = child.status.exitCode === null || child.status.exitCode === 0;
+      segs.push(" ", { text: ok ? "✓" : "✗", style: { color: ok ? "success" : "error" } });
+      if (child.status.summary) segs.push(" ", { text: child.status.summary, style: { color: "muted" } });
+    }
+    lines.push(segmentsToString(segs));
+  });
+  return lines;
+}
+
+export interface RendererCapabilities {
+  images: boolean;
+  /** When false, assistant/thinking fall back to plain styled text. */
+  markdownStreaming: boolean;
+  /** True only if the renderer emits its own carriage returns and wants the raw (OPOST-off) terminal; substrate keeps OPOST on otherwise so lone-`\n` renderers don't staircase. */
+  rawOutput?: boolean;
+  /** Default (omitted) frames the diff in a box; set false to receive bare hunk lines for a self-drawn gutter. */
+  diffFrame?: boolean;
+}
+
+export interface Renderer extends RenderNodes {
+  readonly capabilities: RendererCapabilities;
+  /** Visible (ANSI-aware) width of a styled string. */
+  measureWidth(text: string): number;
+  mountToolCall(model: RenderModel<unknown>, args: MountArgs, env: MountEnv): ToolCallView;
+  mountToolResult(model: RenderModel<unknown>, args: MountArgs, env: MountEnv): ToolResultView;
+  /** Omitting this opts out of grouping; substrate then renders same-kind calls individually. */
+  mountToolGroup?(): ToolGroupView;
+  mount(): App;
+}

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

@@ -0,0 +1,122 @@
+import {
+  Editor,
+  isKeyRelease,
+  isKeyRepeat,
+  Loader,
+  matchesKey,
+  ProcessTerminal,
+  SelectList,
+  TUI,
+  type Component,
+  type SelectItem as PiSelectItem,
+} from "@earendil-works/pi-tui";
+import { editorTheme, selectListTheme } from "./theme-adapters.js";
+import { createNodes, footerContainer } from "./nodes.js";
+import type {
+  App,
+  InputView,
+  KeyEvent,
+  LoaderView,
+  RenderNode,
+  SelectItem,
+  SelectView,
+} from "../../renderer.js";
+
+const asComponent = (n: RenderNode): Component => n as unknown as Component;
+const asNode = (c: Component): RenderNode => c as unknown as RenderNode;
+
+function makeInput(editor: Editor): InputView {
+  return {
+    node: asNode(editor),
+    getText: () => editor.getText(),
+    setText: (t) => editor.setText(t),
+    getCursor: () => editor.getCursor(),
+    replaceBeforeCursor: (count, text) => {
+      for (let i = 0; i < count; i++) editor.handleInput("\x7f");
+      editor.insertTextAtCursor(text);
+    },
+    onChange: (fn) => { editor.onChange = fn; },
+    onSubmit: (fn) => { editor.onSubmit = fn; },
+    defaultBorderColor: editor.borderColor,
+    setBorderColor: (fn) => { editor.borderColor = fn; },
+    invalidate: () => editor.invalidate(),
+  };
+}
+
+function makeSelect(items: SelectItem[], visibleRows: number): SelectView {
+  const picker = new SelectList(items as PiSelectItem[], visibleRows, selectListTheme());
+  return {
+    node: asNode(picker),
+    setSelectedIndex: (i) => picker.setSelectedIndex(i),
+    getSelectedItem: () => picker.getSelectedItem() as SelectItem | undefined,
+    onSelect: (fn) => { picker.onSelect = fn; },
+    onCancel: (fn) => { picker.onCancel = fn; },
+  };
+}
+
+class FlushLoader extends Loader {
+  override render(width: number): string[] {
+    const lines = super.render(width);
+    return lines[0] === "" ? lines.slice(1) : lines;
+  }
+}
+
+function makeLoader(
+  tui: TUI,
+  label: string,
+  color: (t: string) => string,
+  muted: (t: string) => string,
+): LoaderView {
+  const loader = new FlushLoader(tui, color, muted, label);
+  return { node: asNode(loader), stop: () => loader.stop() };
+}
+
+export function createApp(): App {
+  const nodes = createNodes();
+  const terminal = new ProcessTerminal();
+  const tui = new TUI(terminal);
+
+  const scrollback = nodes.container();
+  const footerSlot = footerContainer(
+    () => (scrollback.node as unknown as { children: unknown[] }).children.length > 0,
+  );
+  const queueSlot = nodes.container();
+  const status = nodes.text({ paddingX: 1 });
+  const belowInput = nodes.container();
+  const editor = new Editor(tui, editorTheme(), { paddingX: 1 });
+  const input = makeInput(editor);
+
+  tui.addChild(asComponent(scrollback.node));
+  tui.addChild(asComponent(footerSlot.node));
+  tui.addChild(asComponent(queueSlot.node));
+  tui.addChild(editor);
+  tui.addChild(asComponent(belowInput.node));
+  tui.addChild(asComponent(status.node));
+  tui.setFocus(editor);
+
+  return {
+    scrollback,
+    footerSlot,
+    queueSlot,
+    input,
+    belowInput,
+    status,
+    setFocus: (target) => tui.setFocus(asComponent(target)),
+    focusInput: () => tui.setFocus(editor),
+    requestRender: (force) => tui.requestRender(force),
+    commitScrollback: () => {},
+    start: () => tui.start(),
+    stop: () => tui.stop(),
+    onKey: (handler) =>
+      tui.addInputListener((data) => {
+        const key: KeyEvent = {
+          matches: (name) => matchesKey(data, name as Parameters<typeof matchesKey>[1]),
+          isRelease: () => isKeyRelease(data),
+          isRepeat: () => isKeyRepeat(data),
+        };
+        return handler(key) ?? undefined;
+      }),
+    createSelectList: (items, opts) => makeSelect(items, opts.visibleRows),
+    createLoader: (label, color, muted) => makeLoader(tui, label, color, muted),
+  };
+}

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

@@ -0,0 +1,23 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { Renderer } from "../../renderer.js";
+import { createNodes } from "./nodes.js";
+import { createApp } from "./app.js";
+import { mountCall, mountResult } from "./schema-mount.js";
+import { createPiTuiToolGroup } from "./tool-group.js";
+
+export function createPiTuiRenderer(): Renderer {
+  const nodes = createNodes();
+  return {
+    ...nodes,
+    capabilities: {
+      images: true,
+      markdownStreaming: true,
+      rawOutput: true,
+    },
+    measureWidth: (text) => visibleWidth(text),
+    mountToolCall: (model, args, env) => mountCall(model, args, env),
+    mountToolResult: (model, args, env) => mountResult(model, args, env),
+    mountToolGroup: () => createPiTuiToolGroup(),
+    mount: () => createApp(),
+  };
+}

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

@@ -0,0 +1,133 @@
+import {
+  Container,
+  getImageDimensions,
+  Image,
+  Markdown,
+  Spacer,
+  Text,
+  type Component,
+} from "@earendil-works/pi-tui";
+import { theme } from "../../theme.js";
+import { markdownTheme } from "./theme-adapters.js";
+import type {
+  ContainerView,
+  MarkdownOptions,
+  MarkdownView,
+  RenderNode,
+  RenderNodes,
+  TextView,
+} from "../../renderer.js";
+
+const asNode = (c: Component): RenderNode => c as unknown as RenderNode;
+const asComponent = (n: RenderNode): Component => n as unknown as Component;
+
+class MeasuredText extends Text {
+  private fn: ((width: number) => string[]) | null = null;
+  private lastWidth = -1;
+
+  setRenderFn(fn: ((width: number) => string[]) | null): void {
+    this.fn = fn;
+    this.lastWidth = -1;
+  }
+
+  override render(width: number): string[] {
+    if (this.fn && width !== this.lastWidth) {
+      this.lastWidth = width;
+      this.setText(this.fn(width).join("\n"));
+    }
+    return super.render(width);
+  }
+}
+
+const OSC133_ZONE_START = "\x1b]133;A\x07";
+const OSC133_ZONE_END = "\x1b]133;B\x07";
+const OSC133_ZONE_FINAL = "\x1b]133;C\x07";
+
+// OSC 133 zone brackets let terminals navigate between user prompts.
+class ZonedMarkdown extends Markdown {
+  override render(width: number): string[] {
+    const base = super.render(width);
+    if (base.length === 0) return base;
+    const lines = base.slice();
+    lines[0] = OSC133_ZONE_START + lines[0];
+    lines[lines.length - 1] = lines[lines.length - 1] + OSC133_ZONE_END + OSC133_ZONE_FINAL;
+    return lines;
+  }
+}
+
+class FooterSlot extends Container {
+  constructor(private readonly hasContentAbove: () => boolean) {
+    super();
+  }
+  override render(width: number): string[] {
+    if (this.children.length > 0) return super.render(width);
+    return this.hasContentAbove() ? [""] : [];
+  }
+}
+
+export function footerContainer(hasContentAbove: () => boolean): ContainerView {
+  const c = new FooterSlot(hasContentAbove);
+  return {
+    node: asNode(c),
+    addChild: (child) => c.addChild(asComponent(child)),
+    removeChild: (child) => c.removeChild(asComponent(child)),
+    clear: () => c.clear(),
+  };
+}
+
+export function createNodes(): RenderNodes {
+  return {
+    text(opts) {
+      const t = new MeasuredText("", opts?.paddingX ?? 0, opts?.paddingY ?? 0);
+      const view: TextView = {
+        node: asNode(t),
+        setText: (s) => t.setText(s),
+        setLines: (lines) => t.setText(lines.join("\n")),
+        setRenderFn: (fn) => t.setRenderFn(fn),
+      };
+      return view;
+    },
+
+    markdown(opts?: MarkdownOptions) {
+      const colorOpts =
+        opts?.color || opts?.bgColor
+          ? { ...(opts.color ? { color: opts.color } : {}), ...(opts.bgColor ? { bgColor: opts.bgColor } : {}) }
+          : undefined;
+      const Ctor = opts?.osc133Zones ? ZonedMarkdown : Markdown;
+      const md = new Ctor("", opts?.paddingX ?? 0, opts?.paddingY ?? 0, markdownTheme(), colorOpts);
+      const view: MarkdownView = {
+        node: asNode(md),
+        setText: (full) => md.setText(full),
+      };
+      return view;
+    },
+
+    image(png: Buffer): RenderNode | null {
+      const base64 = png.toString("base64");
+      const dims = getImageDimensions(base64, "image/png");
+      if (!dims) return null;
+      const img = new Image(
+        base64,
+        "image/png",
+        { fallbackColor: (t) => theme.fg("muted", t) },
+        { maxWidthCells: 60, maxHeightCells: 20 },
+        dims,
+      );
+      return asNode(img);
+    },
+
+    container(): ContainerView {
+      const c = new Container();
+      return {
+        node: asNode(c),
+        addChild: (child) => c.addChild(asComponent(child)),
+        removeChild: (child) => c.removeChild(asComponent(child)),
+        clear: () => c.clear(),
+      };
+    },
+
+    spacer(rows: number): RenderNode {
+      return asNode(new Spacer(rows));
+    },
+  };
+}