agent-sh 0.14.11 → 0.15.0

package/examples/extensions/ashi/docs/ui-surface-protocol.md

@@ -0,0 +1,163 @@
+# ashi UI surfaces
+
+How an extension drives ashi's terminal UI — post a notice, add a status-bar segment, pin a
+widget above the input, or ask the user a question.
+
+ashi doesn't hand extensions a `ui` object. Instead it answers a small set of **bus events**
+and **named handlers**, so the same extension degrades gracefully under a frontend that doesn't
+implement a given surface (and under headless/RPC use). There are three shapes:
+
+- **Notices** are fire-and-forget bus events (`ctx.bus.emit`).
+- **Status segments and docks** are *pull* pipes (`ctx.bus.onPipe`): ashi asks for contributions
+  while it repaints and you append yours — ashi owns the layout.
+- **Dialogs** are request/response calls (`await ctx.call(...)`) that resolve when the user answers.
+
+## Setup
+
+For typed events, import the augmentation once (types only — no runtime cost):
+
+```ts
+import "@guanyilun/ashi/events";
+```
+
+`ui:*` names are meant to work under any ashi-compatible frontend; `ashi:*` names are specific to
+ashi's terminal UI. Before a `ctx.call(...)` that must return a value, feature-detect:
+
+```ts
+if (ctx.list().includes("ui:select")) { /* … */ }
+```
+
+Bus emits (`ui:notify`, the `*:invalidate` nudges) need no detection — they're no-ops when nothing
+is listening.
+
+## Timing
+
+Extensions load before ashi mounts, so the surfaces aren't all live at `activate()` time:
+
+- **Pull contributors (`status`, `dock`, any `onPipe`) can be registered any time** — ashi reads them
+  on its next repaint, so registering during `activate()` is fine; the first paint picks them up.
+- **Imperative surfaces (notify, dialogs, editor) are ready once ashi has mounted.** From a command
+  or key handler they're always ready. To use one at startup, wait for the `ashi:ready` event:
+
+  ```ts
+  ctx.bus.on("ashi:ready", () => createUi(ctx).notify("loaded"));
+  ```
+
+The helper degrades (`select`/`input` → `undefined`, `confirm` → `false`) if called before a frontend
+answers, so a premature call can't throw; a premature `notify` is simply dropped.
+
+## Post a notice
+
+```ts
+ctx.bus.emit("ui:notify", { message: "Saved.", level: "success" });
+// level: "info" (default) | "warn" | "error" | "success"
+```
+
+Appends a themed line to the transcript.
+
+## Add a status-bar segment
+
+Contribute to the footer; ashi appends your segment and owns placement:
+
+```ts
+ctx.bus.onPipe("ui:status", (p) => ({
+  segments: [...p.segments, { id: "build", text: "✓ build ok", color: "success" }],
+}));
+```
+
+A segment is `{ id: string; text: string; color?: ThemeColor }`, where `ThemeColor` is a theme name
+such as `"accent"`, `"success"`, `"warning"`, `"error"`, or `"muted"`. When your data changes
+outside a repaint, ask ashi to re-pull:
+
+```ts
+ctx.bus.emit("ui:status:invalidate", {});
+```
+
+## Pin a widget above the input
+
+Same pull model, but you build the view from the renderer's node factory (so you never import a
+TUI library):
+
+```ts
+ctx.bus.onPipe("ashi:dock:above-input", (p) => {
+  const line = p.nodes.text({ paddingX: 1 });
+  line.setText("📌 2 todos remaining");
+  return { ...p, views: [...p.views, line.node] };
+});
+
+// after a change:
+ctx.bus.emit("ashi:dock:invalidate", {});
+```
+
+`p.nodes` offers `text`, `markdown`, `container`, `spacer`, and `image`. Return the payload
+unchanged to contribute nothing — the dock takes zero space when empty.
+
+## Ask the user
+
+```ts
+const fruit = await ctx.call("ui:select", {
+  title: "Pick a fruit",
+  items: [
+    { value: "apple", label: "Apple", description: "crisp" },
+    { value: "banana", label: "Banana" },
+  ],
+});                      // → the chosen value, or undefined if cancelled
+
+const ok = await ctx.call("ui:confirm", { title: "Delete it?" });   // → boolean
+
+const name = await ctx.call("ui:input", {
+  title: "Name?",        // hint shown above the input
+  prefill: "untitled",   // optional starting text
+});                      // → the text, or undefined if cancelled (Esc)
+```
+
+Only one dialog (or built-in picker) is open at a time; a call made while one is open resolves
+`undefined`.
+
+## Read or seed the input
+
+```ts
+const draft = ctx.call("ui:editor:get-text") as string;
+ctx.call("ui:editor:set-text", "/commit ");
+```
+
+## Typed helper
+
+If you're willing to depend on `@guanyilun/ashi`, `createUi(ctx)` wraps everything above with
+full types and no magic strings. Request/response surfaces also degrade on their own — `select`
+and `input` resolve `undefined`, `confirm` resolves `false` — when no frontend answers:
+
+```ts
+import { createUi } from "@guanyilun/ashi/ui";
+
+const ui = createUi(ctx);
+ui.notify("Saved.", "success");
+const fruit = await ui.select({ title: "Pick", items: [{ value: "a", label: "Apple" }] });
+const seg = ui.status(() => ({ id: "build", text: "✓ ok", color: "success" })); // seg.refresh() / seg.remove()
+const widget = ui.dock((nodes) => {
+  const t = nodes.text({ paddingX: 1 });
+  t.setText("📌 note");
+  return t.node;
+});
+```
+
+The raw events and calls above carry no build-time dependency on ashi — reach for them if you
+want a dependency-free extension. The helper is the same protocol with types and degradation
+bolted on.
+
+## Not yet available
+
+Floating/overlay panels and fully custom interactive components aren't exposed — the renderer
+contract has no free-placement layer yet. Use the dock, dialogs, and notices above.
+
+## Working example
+
+[`ashi-ui-demo.ts`](../../ashi-ui-demo.ts) exercises every surface through the typed helper. Load
+it and try the commands:
+
+```
+ashi -e ashi-ui-demo
+/ui-demo        # select → confirm → input, then a notice
+/ui-demo-bump   # update the status segment
+/ui-demo-dock   # toggle the pinned widget
+```

package/examples/extensions/ashi/package.json

@@ -16,6 +16,14 @@
     "./renderer": {
       "types": "./dist/renderer.d.ts",
       "import": "./dist/renderer.js"
+    },
+    "./events": {
+      "types": "./dist/events.d.ts",
+      "import": "./dist/events.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "import": "./dist/ui.js"
     }
   },
   "files": [
@@ -60,7 +68,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.74.0",
-    "agent-sh": "^0.14.10",
+    "agent-sh": "^0.14.11",
     "chalk": "^5.5.0",
     "cli-highlight": "^2.1.11"
   },

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

@@ -2,6 +2,9 @@ import type { ExtensionContext } from "agent-sh/types";
 import type { MultiSessionStore } from "./multi-session-store.js";
 import type { AgentShMessage as AgentMessage } from "agent-sh/session-store";
 
+interface DiffEntry { diff: unknown; filePath: string }
+export interface NestedDiff extends DiffEntry { name: string }
+
 // liveEntryIds is parallel to the live messages array; null slots are synthetics (e.g. compaction summaries) with no entry.
 export interface Capture {
   flush(): Promise<void>;
@@ -14,21 +17,56 @@ export function registerCapture(
   getStore: () => MultiSessionStore,
 ): Capture {
   let liveEntryIds: (string | null)[] = [];
-  const diffMeta = new Map<string, { diff: unknown; filePath: string }>();
+  // A bridged tool call re-emitted under a synthetic id has no conversation message
+  // of its own, so bucket its diff under the enclosing real call for replay as a
+  // separate edit pair.
+  const diffMeta = new Map<string, DiffEntry>();
+  const nestedDiffs = new Map<string, NestedDiff[]>();
+  const summaryMeta = new Map<string, string>();
+  const bridgedNames = new Map<string, string>();
+  let activeRealToolId: string | undefined;
+
+  // `nested` is a bridge-set bus convention (a host tool run inside another tool),
+  // not on the core event type — read it defensively.
+  const isNested = (e: unknown): boolean => !!(e as { nested?: boolean }).nested;
+
+  ctx.bus.on("agent:tool-started", (e) => {
+    const id = e.toolCallId;
+    if (!id) return;
+    if (isNested(e)) bridgedNames.set(id, e.name ?? e.title);
+    else activeRealToolId = id;
+  });
 
   ctx.bus.on("agent:tool-completed", (e) => {
     const id = e.toolCallId;
-    const body = e.resultDisplay?.body;
-    if (id && body?.kind === "diff") {
-      diffMeta.set(id, { diff: body.diff, filePath: body.filePath });
+    if (!id) return;
+    const display = e.resultDisplay;
+    const body = display?.body;
+    if (isNested(e)) {
+      if (body?.kind === "diff" && activeRealToolId) {
+        const arr = nestedDiffs.get(activeRealToolId) ?? [];
+        arr.push({ name: bridgedNames.get(id) ?? "edit_file", diff: body.diff, filePath: body.filePath });
+        nestedDiffs.set(activeRealToolId, arr);
+      }
+      return;
     }
+    // resultDisplay isn't persisted; capture the summary for every tool so resume
+    // doesn't fall back to re-deriving only a handful.
+    if (typeof display?.summary === "string" && display.summary) summaryMeta.set(id, display.summary);
+    if (body?.kind === "diff") diffMeta.set(id, { diff: body.diff, filePath: body.filePath });
   });
 
   const enrich = (m: AgentMessage): AgentMessage => {
     if (m.role !== "tool" || !m.tool_call_id) return m;
-    const meta = diffMeta.get(m.tool_call_id);
-    if (!meta) return m;
-    return { ...m, meta: { ...m.meta, diff: meta.diff, filePath: meta.filePath } };
+    const single = diffMeta.get(m.tool_call_id);
+    const nested = nestedDiffs.get(m.tool_call_id);
+    const summary = summaryMeta.get(m.tool_call_id);
+    if (!single && !nested && !summary) return m;
+    const meta: Record<string, unknown> = { ...m.meta };
+    if (single) { meta.diff = single.diff; meta.filePath = single.filePath; }
+    if (nested) meta.diffs = nested;
+    if (summary) meta.summary = summary;
+    return { ...m, meta };
   };
 
   const writeNewMessages = async (): Promise<void> => {

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

@@ -1,23 +1,11 @@
 import type { ContainerView, MarkdownView, RenderNode, RenderNodes } from "../renderer.js";
 
-export type EquationRenderer = (latexSrc: string) => RenderNode | null;
+export type RenderBlock =
+  | { type: "text"; text: string }
+  | { type: "code-block"; language: string; code: string }
+  | { type: "image"; data: Buffer };
 
-type LatexSegment = { type: "text"; value: string } | { type: "latex"; value: string };
-
-function segmentLatex(text: string): LatexSegment[] {
-  const segments: LatexSegment[] = [];
-  let i = 0;
-  while (i < text.length) {
-    const open = text.indexOf("$$", i);
-    if (open === -1) { segments.push({ type: "text", value: text.slice(i) }); break; }
-    const close = text.indexOf("$$", open + 2);
-    if (close === -1) { segments.push({ type: "text", value: text.slice(i) }); break; }
-    if (open > i) segments.push({ type: "text", value: text.slice(i, open) });
-    segments.push({ type: "latex", value: text.slice(open + 2, close).trim() });
-    i = close + 2;
-  }
-  return segments;
-}
+export type ContentTransform = (blocks: RenderBlock[]) => RenderBlock[];
 
 export class AssistantMessage {
   readonly node: RenderNode;
@@ -25,7 +13,7 @@ export class AssistantMessage {
   private md: MarkdownView;
   private buffer = "";
 
-  constructor(private nodes: RenderNodes, private renderEquation?: EquationRenderer) {
+  constructor(private nodes: RenderNodes, private transform: ContentTransform = (b) => b) {
     this.container = nodes.container();
     this.md = nodes.markdown({ paddingX: 1, bullet: true });
     this.container.addChild(nodes.spacer(1));
@@ -46,37 +34,29 @@ export class AssistantMessage {
 
   finalize(): void {
     if (this.buffer === "") this.buffer = " ";
-    if (this.renderEquation && this.buffer.includes("$$")) {
-      this.rebuildWithEquations();
-    } else {
+    const blocks = this.transform([{ type: "text", text: this.buffer }]);
+    if (blocks.every((b) => b.type === "text")) {
       this.md.setText(this.buffer);
+      return;
     }
+    this.rebuild(blocks);
   }
 
-  private rebuildWithEquations(): void {
-    const segments = segmentLatex(this.buffer);
-    if (!segments.some((s) => s.type === "latex")) {
-      this.md.setText(this.buffer);
-      return;
-    }
+  private rebuild(blocks: RenderBlock[]): void {
     this.container.clear();
     this.container.addChild(this.nodes.spacer(1));
-    for (const seg of segments) {
-      if (seg.type === "text") {
-        if (seg.value.trim()) {
-          const m = this.nodes.markdown({ paddingX: 1 });
-          m.setText(seg.value);
-          this.container.addChild(m.node);
-        }
-      } else {
-        const eq = this.renderEquation!(seg.value);
-        if (eq) {
-          this.container.addChild(eq);
-        } else {
-          const m = this.nodes.markdown({ paddingX: 1 });
-          m.setText(`$$${seg.value}$$`);
-          this.container.addChild(m.node);
-        }
+    for (const block of blocks) {
+      if (block.type === "image") {
+        const img = this.nodes.image(block.data);
+        if (img) this.container.addChild(img);
+      } else if (block.type === "code-block") {
+        const m = this.nodes.markdown({ paddingX: 1 });
+        m.setText(`\`\`\`${block.language}\n${block.code}\n\`\`\``);
+        this.container.addChild(m.node);
+      } else if (block.text.trim()) {
+        const m = this.nodes.markdown({ paddingX: 1 });
+        m.setText(block.text);
+        this.container.addChild(m.node);
       }
     }
   }

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

@@ -1,5 +1,5 @@
 import type { RenderNode, RenderNodes } from "../renderer.js";
-import { theme } from "../theme.js";
+import { theme, type ThemeColor } from "../theme.js";
 
 export class InfoLine {
   readonly node: RenderNode;
@@ -18,3 +18,22 @@ export class ErrorLine {
     this.node = t.node;
   }
 }
+
+export type NoticeLevel = "info" | "warn" | "error" | "success";
+
+const NOTICE: Record<NoticeLevel, { color: ThemeColor; prefix: string }> = {
+  info: { color: "muted", prefix: "" },
+  success: { color: "success", prefix: "✓ " },
+  warn: { color: "warning", prefix: "! " },
+  error: { color: "error", prefix: "✗ " },
+};
+
+export class NoticeLine {
+  readonly node: RenderNode;
+  constructor(nodes: RenderNodes, message: string, level: NoticeLevel = "info") {
+    const { color, prefix } = NOTICE[level];
+    const t = nodes.text({ paddingX: 1 });
+    t.setText(`${theme.fg(color, prefix)}${theme.fg(color, message)}`);
+    this.node = t.node;
+  }
+}

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

@@ -24,6 +24,7 @@ function headlessTerminal(): Terminal {
   };
 }
 
+import "./events.js";
 import { mountAshi } from "./frontend.js";
 import { MultiSessionStore } from "./multi-session-store.js";
 import { registerForkCommands, applyBranchMessages } from "./commands.js";
@@ -38,6 +39,18 @@ import { loadRendererPreference } from "./display-config.js";
 import { applyOutputMode } from "./terminal-mode.js";
 import * as os from "node:os";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Package root (dist/cli.js and src/cli.ts both sit one level down) — the running copy.
+const ASHI_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const ASHI_SURFACE = `You're attached through ashi, an interactive terminal UI. A person is at the keyboard reading your replies as they render — address them directly and keep the exchange conversational.
+
+Your working directory is ${process.cwd()}; your tools run there and it stays fixed. The user can also run shell commands with a \`!\` prefix — those run in a separate shell that may sit elsewhere, and don't change your working directory.
+
+ashi's own source lives at ${ASHI_ROOT}. Read it when the user asks how the TUI works, or wants to change how it looks or behaves:
+- ${path.join(ASHI_ROOT, "README.md")} — what ashi is and how rendering decouples into swappable render extensions
+- ${path.join(ASHI_ROOT, "EXTENDING.md")} — the render-extension contract
+- ${path.join(ASHI_ROOT, "src")} — the frontend, session capture/resume, and the pi-tui renderer`;
 
 function parseArgs(argv: string[]): AppConfig & { extensions?: string[]; continueLast: boolean; renderer?: string } {
   let model: string | undefined;
@@ -167,7 +180,7 @@ async function main(): Promise<void> {
 
   activateAgent(ctx);
   activateShellContext(ctx);
-  await loadBuiltinExtensions(ctx, ["rolling-history"]);
+  const builtinExtensions = await loadBuiltinExtensions(ctx);
 
   const shell = new Shell({
     bus: core.bus,
@@ -226,12 +239,15 @@ async function main(): Promise<void> {
   registerRenderDefaults(ctx, renderer);
   registerDefaultSchemaRenderers(ctx);
 
-  ctx.advise("system-prompt:build", (next) => `${next()}\n\n<cwd>${process.cwd()}</cwd>`);
+  ctx.advise("system-prompt:frontend", (next) => {
+    const base = (next() as string) ?? "";
+    return base ? `${base}\n\n${ASHI_SURFACE}` : ASHI_SURFACE;
+  });
 
   const handle = mountAshi(ctx, getStore, capture, renderer);
   stopFrontend = handle.stop;
 
-  (core.bus.emit as (event: string, payload: unknown) => void)("ashi:ready", {});
+  core.bus.emit("ashi:ready", {});
 
   registerForkCommands(ctx, getStore, handle.openTreePicker, handle.rebuildChat, capture);
   registerSessionCommands(ctx, getStore, capture, {
@@ -246,6 +262,12 @@ async function main(): Promise<void> {
     applyBranchMessages(ctx, getStore, capture);
     await handle.rebuildChat();
     ctx.bus.emit("ui:info", { message: `continued session ${resumeId.slice(0, 12)}…` });
+  } else {
+    // New-session only: skip on resume so a restored transcript isn't prefixed with this.
+    const loadedExtensions = [...new Set([...builtinExtensions, ...loaded])];
+    if (loadedExtensions.length > 0) {
+      ctx.bus.emit("ui:info", { message: `extensions: ${loadedExtensions.join(" · ")}` });
+    }
   }
 
   process.on("SIGTERM", cleanup);

package/examples/extensions/ashi/src/clipboard-image.ts

@@ -25,7 +25,7 @@ export async function readClipboardImage(): Promise<CapturedImage | null> {
       "-e", `set fp to open for access POSIX file ${JSON.stringify(tmp)} with write permission`,
       "-e", "write png_data to fp",
       "-e", "close access fp",
-    ]);
+    ], { timeout: 10_000 });
   } catch {
     return null;
   }

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

@@ -0,0 +1,67 @@
+import type { App, Renderer } from "./renderer.js";
+import { InfoLine } from "./chat/lines.js";
+
+export interface SelectChoice {
+  value: string;
+  label: string;
+  description?: string;
+}
+export interface SelectOpts {
+  title?: string;
+  items: SelectChoice[];
+}
+export interface ConfirmOpts {
+  title: string;
+}
+
+export interface DialogGuard {
+  isOpen(): boolean;
+  setOpen(open: boolean): void;
+}
+
+export interface Dialogs {
+  select(opts: SelectOpts): Promise<string | undefined>;
+  confirm(opts: ConfirmOpts): Promise<boolean>;
+}
+
+export function createDialogs(app: App, renderer: Renderer, guard: DialogGuard): Dialogs {
+  const select = (opts: SelectOpts): Promise<string | undefined> => {
+    if (guard.isOpen() || opts.items.length === 0) return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+      const hint = new InfoLine(renderer, opts.title ?? "↑↓ move · enter: select · esc: cancel");
+      const picker = app.createSelectList(
+        opts.items.map((c) => ({ value: c.value, label: c.label, description: c.description })),
+        { visibleRows: Math.min(15, Math.max(1, opts.items.length)) },
+      );
+      let settled = false;
+      const close = (result?: string): void => {
+        if (settled) return;
+        settled = true;
+        guard.setOpen(false);
+        app.footerSlot.removeChild(picker.node);
+        app.footerSlot.removeChild(hint.node);
+        app.focusInput();
+        app.requestRender();
+        resolve(result);
+      };
+      picker.onSelect((item) => close(item.value));
+      picker.onCancel(() => close());
+      guard.setOpen(true);
+      app.footerSlot.addChild(hint.node);
+      app.footerSlot.addChild(picker.node);
+      app.setFocus(picker.node);
+      app.requestRender();
+    });
+  };
+
+  const confirm = (opts: ConfirmOpts): Promise<boolean> =>
+    select({
+      title: opts.title,
+      items: [
+        { value: "yes", label: "Yes" },
+        { value: "no", label: "No" },
+      ],
+    }).then((v) => v === "yes");
+
+  return { select, confirm };
+}

package/examples/extensions/ashi/src/display-config.ts

@@ -31,6 +31,7 @@ interface AshiSettings extends Record<string, unknown> {
   display?: Record<string, Partial<ToolEntryConfig>>;
   groupMaxVisible?: number;
   renderer?: string;
+  imageScale?: number;
 }
 
 export function loadRendererPreference(): string | undefined {
@@ -45,6 +46,12 @@ export function loadGroupMaxVisible(): number {
   return Math.floor(v);
 }
 
+export function loadImageScale(fallback: number): number {
+  const v = getExtensionSettings<AshiSettings>("ashi", {}).imageScale;
+  if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) return fallback;
+  return v;
+}
+
 function mergeEntry(base: ToolEntryConfig, patch?: Partial<ToolEntryConfig>): ToolEntryConfig {
   if (!patch) return { ...base };
   return {

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

@@ -0,0 +1,31 @@
+import type { EventBus } from "agent-sh/event-bus";
+import type { App, Renderer } from "./renderer.js";
+
+export interface Dock {
+  refresh(): void;
+}
+
+export function createDock(app: App, renderer: Renderer, bus: EventBus): Dock {
+  const container = renderer.container();
+  let mounted = false;
+
+  const refresh = (): void => {
+    container.clear();
+    const { views } = bus.emitPipe("ashi:dock:above-input", { nodes: renderer, views: [] });
+    for (const view of views) container.addChild(view);
+    // Mount only when non-empty: an always-present footer child (even empty) defeats the
+    // footer slot's blank-line spacing above the input.
+    if (views.length > 0 && !mounted) {
+      app.footerSlot.addChild(container.node);
+      mounted = true;
+    } else if (views.length === 0 && mounted) {
+      app.footerSlot.removeChild(container.node);
+      mounted = false;
+    }
+    app.requestRender();
+  };
+
+  bus.on("ashi:dock:invalidate", refresh);
+  refresh();
+  return { refresh };
+}

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

@@ -0,0 +1,16 @@
+// ui:* names are neutral by intent but declared HERE in ashi, not core, on purpose: a name
+// graduates to core's BusEvents only when a second frontend outside ashi speaks it
+// (see docs/ui-surface-protocol.md). ashi:* names carry TUI vocabulary and stay ashi-owned.
+import type { RenderNode, RenderNodes } from "./renderer.js";
+import type { StatusSegment } from "./status-footer.js";
+
+declare module "agent-sh/event-bus" {
+  interface BusEvents {
+    "ui:notify": { message: string; level?: "info" | "warn" | "error" | "success" };
+    "ui:status": { segments: StatusSegment[] };
+    "ui:status:invalidate": Record<string, never>;
+    "ashi:dock:above-input": { nodes: RenderNodes; views: RenderNode[] };
+    "ashi:dock:invalidate": Record<string, never>;
+    "ashi:ready": Record<string, never>;
+  }
+}