agent-sh 0.15.0 → 0.15.2

package/src/extensions/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Cross-cutting built-ins, toggleable via `disabledBuiltins`.
+ * Module-owned built-ins activate inline:
+ *   shell-context, tui-renderer → registerShellHandlers (src/shell/)
+ *   ash (a specific backend)    → activateAgent         (src/agent/)
+ *   rolling-history              → activateRollingHistory (src/cli/)
+ *   backend registry             → createCore           (src/core/)
+ */
+import type { ExtensionContext } from "../shell/host-types.js";
+
+type ActivateFn = (ctx: ExtensionContext) => void;
+
+export const BUILTIN_EXTENSIONS: Array<{
+  name: string;
+  load: () => Promise<ActivateFn>;
+}> = [
+  { name: "slash-commands",    load: () => import("./slash-commands/index.js").then(m => m.default) },
+  { name: "file-autocomplete", load: () => import("./file-autocomplete.js").then(m => m.default) },
+];
+
+/**
+ * Load built-in extensions sequentially, skipping any in the disabled list.
+ * Returns the names of extensions that were loaded.
+ */
+export async function loadBuiltinExtensions(
+  ctx: ExtensionContext,
+  disabled: string[] = [],
+): Promise<string[]> {
+  const disabledSet = new Set(disabled);
+  const loaded: string[] = [];
+  for (const ext of BUILTIN_EXTENSIONS) {
+    if (disabledSet.has(ext.name)) continue;
+    const activate = await ext.load();
+    activate(ctx);
+    loaded.push(ext.name);
+  }
+  return loaded;
+}

package/src/extensions/slash-commands/events.ts

@@ -0,0 +1,14 @@
+/** Events slash-commands owns. */
+declare module "../../core/event-bus.js" {
+  interface BusEvents {
+    "command:register": {
+      name: string;
+      description: string;
+      handler: (args: string) => Promise<void> | void;
+    };
+    "command:unregister": { name: string };
+    "command:execute": { name: string; args: string };
+  }
+}
+
+export {};

package/src/extensions/slash-commands/index.ts

@@ -0,0 +1,269 @@
+/**
+ * Slash commands extension.
+ *
+ * Registers built-in slash commands on the event bus:
+ * - Listens for "command:register" to accept commands from extensions
+ * - Responds to "autocomplete:request" pipe for /-prefixed completions
+ * - Handles "command:execute" events and dispatches to matching handler
+ * - Uses "ui:info"/"ui:error" for user feedback (no direct TUI dependency)
+ *
+ * Argument completion is composable: any extension can onPipe("autocomplete:request")
+ * and check payload.command / payload.commandArgs to add completions for any command.
+ */
+import "./events.js";
+import { palette as p } from "../../utils/palette.js";
+import type { ExtensionContext } from "../../shell/host-types.js";
+import { discoverSkills, loadSkillContent, type Skill } from "../../agent/skills.js";
+import { reloadExtensions } from "../../core/extension-loader.js";
+
+interface SlashCommand {
+  name: string;
+  description: string;
+  handler: (args: string) => Promise<void> | void;
+}
+
+export default function activate(ctx: ExtensionContext): void {
+  const { bus } = ctx;
+  const commands = new Map<string, SlashCommand>();
+
+  const register = (cmd: SlashCommand) => {
+    const name = cmd.name.startsWith("/") ? cmd.name : `/${cmd.name}`;
+    if (commands.has(name)) {
+      throw new Error(`Command "${name}" already registered. Use ctx.adviseCommand() to wrap it.`);
+    }
+    commands.set(name, { ...cmd, name });
+    ctx.define(`command:${name}`, cmd.handler);
+  };
+
+  // ── Built-in commands ─────────────────────────────────────────
+
+  register({
+    name: "/help",
+    description: "Show available commands",
+    handler: () => {
+      const maxLen = Math.max(...[...commands.values()].map(c => c.name.length));
+      const pad = maxLen + 2;
+      const lines = [...commands.values()].map(
+        (c) => `  ${p.accent}${c.name.padEnd(pad)}${p.reset} ${c.description}`
+      );
+      bus.emit("ui:info", { message: "Available commands:\n" + lines.join("\n") });
+    },
+  });
+
+  register({
+    name: "/model",
+    description: "Cycle to next model, or switch to a specific one",
+    handler: (args) => {
+      const name = args.trim();
+      const { models, active } = bus.emitPipe("config:get-models", { models: [], active: null });
+      if (!name) {
+        const label = active ? `${active.id} [${active.provider}]` : "none";
+        bus.emit("ui:info", { message: `Model: ${label}` });
+        return;
+      }
+      const atIdx = name.lastIndexOf("@");
+      const id = atIdx > 0 ? name.slice(0, atIdx) : name;
+      const providerHint = atIdx > 0 ? name.slice(atIdx + 1) : undefined;
+      const found = models.find((m) => m.id === id && (!providerHint || m.provider === providerHint));
+      if (!found) {
+        bus.emit("ui:error", { message: `Unknown model: ${name}` });
+        return;
+      }
+      bus.emit("config:switch-model", { id: found.id, provider: found.provider });
+    },
+  });
+
+  register({
+    name: "/thinking",
+    description: "Set thinking/reasoning effort level",
+    handler: (args) => {
+      const level = args.trim();
+      if (!level) {
+        const { level: current, levels, supported } = bus.emitPipe("config:get-thinking", { level: "off", levels: [], supported: true });
+        const status = supported ? current : `${current} (not supported by current model)`;
+        bus.emit("ui:info", { message: `Thinking: ${status} (options: ${levels.join(", ")})` });
+      } else {
+        bus.emit("config:set-thinking", { level });
+      }
+    },
+  });
+
+  register({
+    name: "/backend",
+    description: "List or switch agent backend",
+    handler: (args) => {
+      const name = args.trim();
+      if (!name) {
+        bus.emit("config:list-backends", {});
+      } else {
+        bus.emit("config:switch-backend", { name });
+      }
+    },
+  });
+
+  register({
+    name: "/reload",
+    description: "Reload user extensions from ~/.agent-sh/extensions/",
+    handler: async () => {
+      const names = await reloadExtensions(ctx);
+      if (names.length > 0) {
+        bus.emit("ui:info", { message: `Reloaded: ${names.join(", ")}` });
+      } else {
+        bus.emit("ui:info", { message: "No extensions to reload." });
+      }
+    },
+  });
+
+  // Handler form so extensions can trigger reload programmatically
+  // (e.g. an ash-callable reload_extensions tool in superash).
+  ctx.define("extensions:reload", async () => {
+    return await reloadExtensions(ctx);
+  });
+
+  // ── Extension registration ────────────────────────────────────
+
+  bus.on("command:register", (cmd) => {
+    register(cmd);
+  });
+
+  bus.on("command:unregister", ({ name }) => {
+    const key = name.startsWith("/") ? name : `/${name}`;
+    commands.delete(key);
+    // Handler entry retained so external advisors survive a reload of the owner.
+  });
+
+  // ── Skill commands (/skill:<name>) ────────────────────────────
+
+  const getSkills = (): Skill[] => {
+    const cwd = (ctx.call("cwd") as string) ?? process.cwd();
+    return discoverSkills(cwd);
+  };
+
+  const handleSkillCommand = (skillName: string, args: string) => {
+    const skills = getSkills();
+    const skill = skills.find(s => s.name === skillName);
+    if (!skill) {
+      bus.emit("ui:error", { message: `Unknown skill: ${skillName}` });
+      return;
+    }
+
+    const content = loadSkillContent(skill);
+    if (!content) {
+      bus.emit("ui:error", { message: `Failed to load skill: ${skillName}` });
+      return;
+    }
+
+    const query = args.trim()
+      ? `${content}\n\n${args.trim()}`
+      : content;
+    bus.emit("agent:submit", { query });
+  };
+
+  // ── Autocomplete: command names ───────────────────────────────
+
+  bus.onPipe("autocomplete:request", (payload) => {
+    if (!payload.buffer.startsWith("/")) return payload;
+    // Argument completion is handled by separate pipe handlers below
+    if (payload.command) return payload;
+
+    const prefix = payload.buffer.toLowerCase();
+    const matching = [...commands.values()]
+      .filter((c) => c.name.toLowerCase().startsWith(prefix))
+      .map((c) => ({ name: c.name, description: c.description }));
+
+    // Skill commands
+    if (prefix.startsWith("/skill:") || "/skill:".startsWith(prefix)) {
+      const skills = getSkills();
+      for (const skill of skills) {
+        const name = `/skill:${skill.name}`;
+        if (name.toLowerCase().startsWith(prefix)) {
+          matching.push({ name, description: skill.description });
+        }
+      }
+    }
+
+    if (matching.length === 0) return payload;
+    return { ...payload, items: [...payload.items, ...matching] };
+  });
+
+  // ── Autocomplete: /model arguments ─────────────────────────────
+
+  bus.onPipe("autocomplete:request", (payload) => {
+    if (payload.command !== "/model") return payload;
+    const partial = (payload.commandArgs ?? "").toLowerCase();
+    const { models, active } = bus.emitPipe("config:get-models", { models: [], active: null });
+    const counts = new Map<string, number>();
+    for (const m of models) counts.set(m.id, (counts.get(m.id) ?? 0) + 1);
+    const items = models
+      .filter((m) => m.id.toLowerCase().includes(partial))
+      .slice(0, 15)
+      .map((m) => {
+        const ambiguous = (counts.get(m.id) ?? 0) > 1;
+        const qualified = ambiguous ? `${m.id}@${m.provider}` : m.id;
+        return {
+          name: `/model ${qualified}`,
+          description: `[${m.provider}]${active && m.id === active.id && m.provider === active.provider ? " (active)" : ""}`,
+        };
+      });
+    if (items.length === 0) return payload;
+    return { ...payload, items: [...payload.items, ...items] };
+  });
+
+  // ── Autocomplete: /thinking arguments ─────────────────────────
+
+  bus.onPipe("autocomplete:request", (payload) => {
+    if (payload.command !== "/thinking") return payload;
+    const partial = (payload.commandArgs ?? "").toLowerCase();
+    const { level: current, levels } = bus.emitPipe("config:get-thinking", { level: "off", levels: [], supported: true });
+    const items = levels
+      .filter((l) => l.startsWith(partial))
+      .map((l) => ({
+        name: `/thinking ${l}`,
+        description: l === current ? "(active)" : "",
+      }));
+    if (items.length === 0) return payload;
+    return { ...payload, items: [...payload.items, ...items] };
+  });
+
+  // ── Autocomplete: /backend arguments ──────────────────────────
+
+  bus.onPipe("autocomplete:request", (payload) => {
+    if (payload.command !== "/backend") return payload;
+    const partial = (payload.commandArgs ?? "").toLowerCase();
+    const { names, active } = bus.emitPipe("config:get-backends", { names: [], active: null });
+    const items = names
+      .filter((n) => n.toLowerCase().startsWith(partial))
+      .map((n) => ({
+        name: `/backend ${n}`,
+        description: n === active ? "(active)" : "",
+      }));
+    if (items.length === 0) return payload;
+    return { ...payload, items: [...payload.items, ...items] };
+  });
+
+  // ── Dispatch ──────────────────────────────────────────────────
+
+  bus.on("command:execute", (e) => {
+    if (e.name.startsWith("/skill:")) {
+      const skillName = e.name.slice("/skill:".length);
+      handleSkillCommand(skillName, e.args);
+      return;
+    }
+
+    const cmd = commands.get(e.name);
+    if (cmd) {
+      const result = ctx.call(`command:${e.name}`, e.args);
+      if (result instanceof Promise) {
+        result.catch((err) => {
+          bus.emit("ui:error", {
+            message: err instanceof Error ? err.message : String(err),
+          });
+        });
+      }
+    } else {
+      bus.emit("ui:info", {
+        message: `Unknown command: ${e.name}. Type /help for available commands.`,
+      });
+    }
+  });
+}

package/src/shell/events.ts

@@ -0,0 +1,73 @@
+/** Events owned by the shell subsystem. */
+declare module "../core/event-bus.js" {
+  interface BusEvents {
+    "shell:command-start": { command: string; cwd: string };
+    "shell:command-done": {
+      command: string;
+      output: string;
+      outputRaw: string;
+      cwd: string;
+      exitCode: number | null;
+    };
+    "shell:cwd-change": { cwd: string };
+    "shell:foreground-busy": { busy: boolean };
+    "shell:agent-exec-start": Record<string, never>;
+    "shell:agent-exec-done": Record<string, never>;
+
+    /** Mark the next user-emitted shell command as excluded from <shell_events>. */
+    "shell:user-exec-exclude-next": Record<string, never>;
+
+    "shell:pty-data": { raw: string };
+    "shell:pty-write": { data: string };
+    "shell:pty-resize": { cols: number; rows: number };
+
+    "shell:host-write": { data: string };
+
+    "shell:buffer-request": Record<string, never>;
+    "shell:buffer-snapshot": {
+      text: string;
+      altScreen: boolean;
+      cursor: { x: number; y: number };
+    };
+
+    "shell:stdout-hold": Record<string, never>;
+    "shell:stdout-release": Record<string, never>;
+    "shell:stdout-show": Record<string, never>;
+    "shell:stdout-hide": Record<string, never>;
+
+    /** Sync pipe: handled=true suppresses default redraw. */
+    "shell:redraw-prompt": {
+      cwd: string;
+      kind: "fresh" | "redraw";
+      handled: boolean;
+    };
+
+    /** Async pipe: extension → user's PTY. */
+    "shell:exec-request": {
+      command: string;
+      output: string;
+      cwd: string;
+      exitCode: number | null;
+      done: boolean;
+    };
+
+    "input-mode:register": import("./host-types.js").InputModeConfig;
+    "input:keypress": { key: string };
+    "input:intercept": { data: string; consumed: boolean };
+    "input:redraw": Record<string, never>;
+
+    "compositor:write": { stream: string; text: string };
+
+    /** Sync pipe: extensions append items. */
+    "autocomplete:request": {
+      buffer: string;
+      /** "/backend" or null if not a command. */
+      command: string | null;
+      /** Text after the command name, or null. */
+      commandArgs: string | null;
+      items: { name: string; description: string }[];
+    };
+  }
+}
+
+export {};

package/src/shell/host-types.ts

@@ -0,0 +1,150 @@
+import type { EventBus } from "../core/event-bus.js";
+import type { CoreConfig, CoreContext } from "../core/types.js";
+import type { AgentSurface } from "../agent/host-types.js";
+import type { ColorPalette } from "../utils/palette.js";
+import type { Compositor, RenderSurface } from "../utils/compositor.js";
+import type { BlockTransformOptions, FencedBlockTransformOptions } from "../utils/stream-transform.js";
+
+export type { BlockTransformOptions, FencedBlockTransformOptions } from "../utils/stream-transform.js";
+export type { RenderSurface } from "../utils/compositor.js";
+
+// ── Remote sessions ──────────────────────────────────────────────
+
+export interface RemoteSessionOptions {
+  /** The surface to render agent output to. */
+  surface: RenderSurface;
+  /** Suppress response borders (default: true). */
+  suppressBorders?: boolean;
+  /** Suppress user query box (default: false).
+   *  True for sessions with their own input (rsplit, overlay).
+   *  False for sessions where input comes from the main shell (split). */
+  suppressQueryBox?: boolean;
+  /** Suppress usage stats line (default: true). */
+  suppressUsage?: boolean;
+}
+
+export interface RemoteSession {
+  /** Submit a query to the agent from this session. */
+  submit(query: string): void;
+  /** The surface this session renders to. */
+  readonly surface: RenderSurface;
+  /** Whether this session is currently active. */
+  readonly active: boolean;
+  /** Tear down — restores all routing and advisors. */
+  close(): void;
+}
+
+// ── Input modes ──────────────────────────────────────────────────
+
+/**
+ * Configuration for a registered input mode.
+ * Extensions emit "input-mode:register" with this shape to add new modes.
+ */
+export interface InputModeConfig {
+  id: string;              // unique identifier, e.g. "agent", "translate"
+  trigger: string;         // single char trigger at empty line start: "?", ">"
+  label: string;           // human-readable label shown in prompt
+  promptIcon: string;      // the chevron/icon character, e.g. "❯", "⟩"
+  indicator: string;       // status indicator shown before the icon, e.g. "❓", "●"
+  onSubmit(query: string, bus: EventBus): void;
+  returnToSelf: boolean;   // re-enter this mode after agent processing?
+}
+
+export interface TerminalSession {
+  id: string;
+  command: string;
+  output: string;
+  exitCode: number | null;
+  done: boolean;
+  resolve?: (value: void) => void;
+}
+
+// ── Shell-host surface ───────────────────────────────────────────
+
+/**
+ * Capabilities the shell host adds to the extension context, exposed
+ * on the nested `ctx.shell` field. Available only when the TUI shell
+ * frontend is loaded; under headless backends these methods are silent
+ * no-ops (bus emits with no listeners).
+ */
+export interface ShellSurface {
+  /** Routes named render streams ("agent", "query", "status", or any
+   *  extension-defined name) to terminal surfaces. Frontends register
+   *  default surfaces during activation; extensions can `redirect()`
+   *  to capture output. Shell-scoped because today only the TUI uses
+   *  it — bus events are the wire for other frontends. */
+  compositor: Compositor;
+
+  /** Override color palette slots for theming. */
+  setPalette: (overrides: Partial<ColorPalette>) => void;
+
+  /** Register a delimiter-based content transform (e.g. $$...$$ → image). */
+  createBlockTransform: (opts: BlockTransformOptions) => void;
+  /** Register a fenced block transform (e.g. ```lang...``` → code-block). */
+  createFencedBlockTransform: (opts: FencedBlockTransformOptions) => void;
+
+  /** Wrap an input mode's `onSubmit`. Lets extensions transform queries
+   *  on the way to the agent (logging, redaction, vetoing). The mode
+   *  must already be registered via the `input-mode:register` bus event. */
+  adviseInputMode: (
+    id: string,
+    advisor: (
+      next: (query: string, bus: EventBus) => void,
+      query: string,
+      bus: EventBus,
+    ) => void,
+  ) => () => void;
+
+  /** Create a remote session that routes agent output to a surface and
+   *  optionally accepts queries. Handles compositor routing, shell
+   *  lifecycle advisors, and chrome suppression. */
+  createRemoteSession: (opts: RemoteSessionOptions) => RemoteSession;
+}
+
+/** Substrate + shell surface. Use this when an extension only touches
+ *  shell features (themes, palette, transforms) and doesn't need the
+ *  agent surface. */
+export type ShellContext = CoreContext & { shell: ShellSurface };
+
+// ── Extension-facing context ─────────────────────────────────────
+
+/**
+ * What extension `activate()` functions receive. Substrate (`CoreContext`)
+ * + slash-command registration + host surfaces, which are **optional**
+ * because hosts attach them on activation: under headless backends
+ * `ctx.shell` is undefined; under bridge backends `ctx.agent` may be
+ * undefined too. Extensions guard with `ctx.shell?.foo()` /
+ * `if (!ctx.agent) return;`, or type their parameter as the narrower
+ * `AgentContext` / `ShellContext` to declare host requirements (those
+ * variants make the surface non-optional). When both hosts are required,
+ * intersect them at the use site: `ctx: AgentContext & ShellContext`.
+ */
+export type ExtensionContext = CoreContext & {
+  registerCommand: (name: string, description: string, handler: (args: string) => Promise<void> | void) => void;
+  /** Wrap an already-registered command's handler. Name is normalized
+   *  (leading `/` optional). */
+  adviseCommand: (
+    name: string,
+    advisor: (
+      next: (args: string) => Promise<void> | void,
+      args: string,
+    ) => Promise<void> | void,
+  ) => () => void;
+  agent?: AgentSurface;
+  shell?: ShellSurface;
+};
+
+// ── Shell-host config surface ────────────────────────────────────
+
+export interface ShellConfigSurface {
+  /** Shell binary (e.g. /bin/zsh) launched by the PTY frontend. */
+  shell?: string;
+}
+
+export type ShellConfig = CoreConfig & ShellConfigSurface;
+
+/** The full application config — substrate + agent + shell startup options.
+ *  Prefer this in CLI/embedder code; layered names (`CoreConfig`,
+ *  `AgentConfig`, `ShellConfig`) are for code that cares about which
+ *  host owns which fields. */
+export type AppConfig = CoreConfig & import("../agent/host-types.js").AgentConfigSurface & ShellConfigSurface;