agent-sh 0.15.0 → 0.15.2

package/src/core/event-bus.ts

@@ -0,0 +1,252 @@
+import { EventEmitter } from "node:events";
+
+export interface BackendRegistration {
+  name: string;
+  kill: () => void;
+  start?: () => Promise<void>;
+}
+
+/** Typed event map — every event has a known payload shape. */
+export interface BusEvents {
+  "core:extensions-loaded": { names: string[] };
+
+  /** Cross-cutting "config might have changed, repaint" signal. */
+  "config:changed": Record<string, never>;
+
+  /** Universal UI feedback channel (any frontend may render; silently
+   *  ignored without one). */
+  "ui:info": { message: string };
+  "ui:error": { message: string };
+  "ui:suggestion": { text: string };
+
+  /** Backend registry — core owns these; every backend (ash, bridges)
+   *  emits register, switch/list flow through here too. */
+  "agent:register-backend": BackendRegistration;
+  "config:get-backends": { names: string[]; active: string | null };
+  "config:switch-backend": { name: string };
+  "config:list-backends": Record<string, never>;
+}
+
+// ── Content block types (used by transform pipeline) ────────────
+
+export type ContentBlock =
+  | { type: "text"; text: string }
+  | { type: "code-block"; language: string; code: string }
+  | { type: "image"; data: Buffer }
+  | { type: "raw"; escape: string };
+
+type Listener<T> = (payload: T) => void;
+type PipeListener<T> = (payload: T) => T;
+type AsyncPipeListener<T> = (payload: T) => T | Promise<T>;
+
+/** Envelope stamped on every emitted event. */
+export interface BusMeta {
+  source: string;   // emitting agent's instanceId
+  ts: number;       // milliseconds since epoch
+  id: string;       // monotonic per-bus, "<source>:<n>"
+  name: string;
+}
+
+export type AnyListener = (name: string, payload: unknown, meta: BusMeta) => void;
+
+/**
+ * Typed event bus with two modes:
+ * - emit/on/off: fire-and-forget notifications
+ * - emitPipe/onPipe: synchronous transform chain where each listener
+ *   can modify the payload before passing to the next
+ */
+export class EventBus {
+  private emitter = new EventEmitter().setMaxListeners(0);
+  private pipeListeners = new Map<string, PipeListener<any>[]>();
+  private asyncPipeListeners = new Map<string, AsyncPipeListener<any>[]>();
+  private source = "0000";
+  private nextSeq = 0;
+  private anyListeners: AnyListener[] = [];
+
+  /** Set the source id stamped onto every emitted event. */
+  setSource(src: string): void {
+    this.source = src;
+  }
+
+  /** Subscribe to every emitted event with full envelope. Returns unsubscribe. */
+  onAny(fn: AnyListener): () => void {
+    this.anyListeners.push(fn);
+    return () => {
+      const i = this.anyListeners.indexOf(fn);
+      if (i !== -1) this.anyListeners.splice(i, 1);
+    };
+  }
+
+  /** Stamp + dispatch — used by every emit path. */
+  private dispatch(name: string, payload: unknown): void {
+    if (this.anyListeners.length > 0) {
+      const meta: BusMeta = {
+        source: this.source,
+        ts: Date.now(),
+        id: `${this.source}:${this.nextSeq++}`,
+        name,
+      };
+      for (const fn of this.anyListeners) {
+        try { fn(name, payload, meta); } catch { /* swallow */ }
+      }
+    }
+    this.emitter.emit(name, payload);
+  }
+
+  /** Subscribe to a fire-and-forget event. */
+  on<K extends keyof BusEvents>(
+    event: K,
+    fn: Listener<BusEvents[K]>,
+  ): void {
+    this.emitter.on(event, fn);
+  }
+
+  /** Unsubscribe from a fire-and-forget event. */
+  off<K extends keyof BusEvents>(
+    event: K,
+    fn: Listener<BusEvents[K]>,
+  ): void {
+    this.emitter.off(event, fn);
+  }
+
+  /** Emit a fire-and-forget event. */
+  emit<K extends keyof BusEvents>(
+    event: K,
+    payload: BusEvents[K],
+  ): void {
+    this.dispatch(event, payload);
+  }
+
+  /** Re-dispatch an event with externally-supplied meta. Used by bridges
+   *  and replay tools to preserve the original source/ts/id of remote or
+   *  recorded events instead of restamping them as locally originated. */
+  relay(meta: BusMeta, payload: unknown): void {
+    if (this.anyListeners.length > 0) {
+      for (const fn of this.anyListeners) {
+        try { fn(meta.name, payload, meta); } catch { /* swallow */ }
+      }
+    }
+    this.emitter.emit(meta.name, payload);
+  }
+
+  /**
+   * Transform-then-notify: run the payload through any registered pipe
+   * listeners (transforms), then emit the final result to regular `on`
+   * listeners (renderers). This enables content pipelines where extensions
+   * modify data (e.g. render LaTeX → terminal image) before renderers see it.
+   */
+  emitTransform<K extends keyof BusEvents>(
+    event: K,
+    payload: BusEvents[K],
+  ): void {
+    let transformed: BusEvents[K];
+    try {
+      transformed = this.emitPipe(event, payload);
+    } catch (err) {
+      if (process.env.DEBUG) {
+        process.stderr.write(`[event-bus] pipe error on ${String(event)}: ${err}\n`);
+      }
+      transformed = payload; // fall back to untransformed
+    }
+    this.dispatch(event, transformed);
+  }
+
+  /** Register a transform listener for a pipeline event. */
+  onPipe<K extends keyof BusEvents>(
+    event: K,
+    fn: PipeListener<BusEvents[K]>,
+  ): void {
+    let listeners = this.pipeListeners.get(event);
+    if (!listeners) {
+      listeners = [];
+      this.pipeListeners.set(event, listeners);
+    }
+    listeners.push(fn);
+  }
+
+  /** Remove a transform listener from a pipeline event. */
+  offPipe<K extends keyof BusEvents>(
+    event: K,
+    fn: PipeListener<BusEvents[K]>,
+  ): void {
+    const listeners = this.pipeListeners.get(event);
+    if (!listeners) return;
+    const idx = listeners.indexOf(fn);
+    if (idx !== -1) listeners.splice(idx, 1);
+  }
+
+  /**
+   * Emit a pipeline event — each registered pipe listener receives the
+   * output of the previous one. Returns the final transformed payload.
+   * If no listeners are registered, returns the original payload unchanged.
+   */
+  emitPipe<K extends keyof BusEvents>(
+    event: K,
+    payload: BusEvents[K],
+  ): BusEvents[K] {
+    const listeners = this.pipeListeners.get(event);
+    if (!listeners) return payload;
+    let result = payload;
+    for (const fn of listeners) {
+      try {
+        const out = fn(result);
+        if (out && typeof (out as any).then === "function") {
+          console.error(`[event-bus] Warning: async handler in sync pipe "${String(event)}" — use onPipeAsync instead`);
+          continue;
+        }
+        result = out;
+      } catch (err) {
+        console.error(`[event-bus] Pipe handler error in "${String(event)}":`, err instanceof Error ? err.message : err);
+      }
+    }
+    return result;
+  }
+
+  /** Remove an async transform listener from a pipeline event. */
+  offPipeAsync<K extends keyof BusEvents>(
+    event: K,
+    fn: AsyncPipeListener<BusEvents[K]>,
+  ): void {
+    const listeners = this.asyncPipeListeners.get(event);
+    if (!listeners) return;
+    const idx = listeners.indexOf(fn);
+    if (idx !== -1) listeners.splice(idx, 1);
+  }
+
+  /** Register an async transform listener for a pipeline event. */
+  onPipeAsync<K extends keyof BusEvents>(
+    event: K,
+    fn: AsyncPipeListener<BusEvents[K]>,
+  ): void {
+    let listeners = this.asyncPipeListeners.get(event);
+    if (!listeners) {
+      listeners = [];
+      this.asyncPipeListeners.set(event, listeners);
+    }
+    listeners.push(fn);
+  }
+
+  /**
+   * Emit an async pipeline event. Two phases:
+   * 1. Notify — fire regular `on` listeners synchronously (e.g., TUI flushes state)
+   * 2. Transform — run async pipe listeners in series, each receiving the
+   *    output of the previous (e.g., extension provides a permission decision)
+   *
+   * Returns the final transformed payload. If no pipe listeners are registered,
+   * returns the original payload unchanged (with safe defaults).
+   */
+  async emitPipeAsync<K extends keyof BusEvents>(
+    event: K,
+    payload: BusEvents[K],
+  ): Promise<BusEvents[K]> {
+    this.dispatch(event, payload);
+
+    const listeners = this.asyncPipeListeners.get(event);
+    if (!listeners) return payload;
+    let result = payload;
+    for (const fn of listeners) {
+      result = await fn(result);
+    }
+    return result;
+  }
+}

package/src/core/extension-loader.ts

@@ -0,0 +1,347 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ExtensionContext } from "../shell/host-types.js";
+import type { EventBus } from "./event-bus.js";
+import { CONFIG_DIR, getSettings } from "./settings.js";
+
+const EXT_DIR = path.join(CONFIG_DIR, "extensions");
+
+const TS_EXTS = [".ts", ".tsx", ".mts"];
+const SCRIPT_EXTS = [".js", ".mjs", ".ts", ".tsx", ".mts"];
+
+let tsRegistered = false;
+let tsxUnregister: (() => Promise<void>) | null = null;
+
+/**
+ * Register tsx's ESM loader for .ts file support.
+ *
+ * Called before importing .ts extensions. The tsx loader uses Node's
+ * module.register() which creates a background thread with a MessageChannel.
+ * On reload, the old loader may become stale (the MessageChannel port can be
+ * GC'd or the loader thread can stop responding), so we unregister the old
+ * handle and re-register on each reload.
+ *
+ * Initial load: registers fresh.
+ * Reload: unregisters old handle, registers new one.
+ * Non-reload calls within the same load: no-op (tsRegistered guard).
+ */
+async function ensureTsSupport(force = false): Promise<void> {
+  if (tsRegistered && !force) return;
+  try {
+    if (tsxUnregister) {
+      try { await tsxUnregister(); } catch { /* ignore stale handle */ }
+    }
+    const { register } = await import("tsx/esm/api");
+    tsxUnregister = register();
+    tsRegistered = true;
+  } catch {
+    // tsx not available — TS extensions will fail with a clear error
+  }
+}
+
+// ── Scoped context for reloadable extensions ────────────────────
+
+type Cleanup = () => void;
+
+/**
+ * Wrap an ExtensionContext to track all registrations (bus.on, advise,
+ * command:register, plus all agent/shell surface registrars). Returns
+ * the wrapped context and a dispose() that tears down everything
+ * registered through it.
+ */
+function createScopedContext(ctx: ExtensionContext, extensionName: string): { scoped: ExtensionContext; dispose: () => void } {
+  const cleanups: Cleanup[] = [];
+  const bus = ctx.bus;
+
+  const scopedBus: EventBus = Object.create(bus);
+  scopedBus.on = ((event: any, fn: any) => {
+    bus.on(event, fn);
+    cleanups.push(() => bus.off(event, fn));
+  }) as typeof bus.on;
+  scopedBus.onPipe = ((event: any, fn: any) => {
+    bus.onPipe(event, fn);
+    cleanups.push(() => bus.offPipe(event, fn));
+  }) as typeof bus.onPipe;
+
+  // Wrap any (name, fn) → unsubscribe registrar so its disposer runs on teardown.
+  const trackUnsub = <A, B>(fn: (a: A, b: B) => () => void) => (a: A, b: B) => {
+    const unsub = fn(a, b);
+    cleanups.push(unsub);
+    return unsub;
+  };
+
+  // ── substrate / sugar ──────────────────────────────────────
+  const scopedAdvise: typeof ctx.advise = trackUnsub(ctx.advise);
+  // Without this, reloading an extension stacks its commands (old + new)
+  // in the slash-commands registry.
+  const scopedRegisterCommand: typeof ctx.registerCommand = (name, description, handler) => {
+    ctx.registerCommand(name, description, handler);
+    cleanups.push(() => bus.emit("command:unregister", { name }));
+  };
+  const scopedAdviseCommand: typeof ctx.adviseCommand = trackUnsub(ctx.adviseCommand);
+
+  // ── agent surface (optional — bridge backends omit it) ───
+  const agent = ctx.agent;
+  let scopedAgent: typeof agent;
+  if (agent) {
+    scopedAgent = {
+      ...agent,
+      registerTool: (tool) => {
+        agent.registerTool(tool);
+        cleanups.push(() => agent.unregisterTool(tool.name));
+      },
+      adviseTool: trackUnsub(agent.adviseTool),
+      adviseToolSchema: trackUnsub(agent.adviseToolSchema),
+      registerInstruction: (name, text) => {
+        agent.registerInstruction(name, text);
+        cleanups.push(() => agent.removeInstruction(name));
+      },
+      adviseInstruction: trackUnsub(agent.adviseInstruction),
+      registerSkill: (name, description, filePath) => {
+        agent.registerSkill(name, description, filePath);
+        cleanups.push(() => agent.removeSkill(name));
+      },
+      adviseSkill: trackUnsub(agent.adviseSkill),
+      registerContextProducer: (name, producer, opts) => {
+        const dispose = agent.registerContextProducer(name, producer, opts);
+        cleanups.push(dispose);
+        return dispose;
+      },
+    };
+  }
+
+  // ── shell surface (optional — headless backends omit it) ──
+  const shell = ctx.shell;
+  let scopedShell: typeof shell;
+  if (shell) {
+    scopedShell = {
+      ...shell,
+      adviseInputMode: trackUnsub(shell.adviseInputMode),
+    };
+  }
+
+  const scoped: ExtensionContext = {
+    ...ctx,
+    bus: scopedBus,
+    advise: scopedAdvise,
+    registerCommand: scopedRegisterCommand,
+    adviseCommand: scopedAdviseCommand,
+    agent: scopedAgent,
+    shell: scopedShell,
+    onDispose: (fn: () => void) => { cleanups.push(fn); },
+  };
+
+  const dispose = () => {
+    // Snapshot: a re-registering cleanup appends a new cleanup, and iterating
+    // the live array would run it and undo the restore in the same pass.
+    for (const fn of cleanups.slice()) {
+      try { fn(); } catch { /* ignore */ }
+    }
+    cleanups.length = 0;
+  };
+
+  return { scoped, dispose };
+}
+
+const extensionDisposers = new Map<string, () => void>();
+
+
+/**
+ * Load extensions from three sources (merged, deduplicated):
+ *
+ * 1. CLI flags: -e / --extensions (npm packages or file paths)
+ * 2. settings.json: ~/.agent-sh/settings.json → extensions[]
+ * 3. Extensions dir: ~/.agent-sh/extensions/ (files and directories with index.{ts,js})
+ *
+ * Extension specifiers resolve as:
+ *   - File path (relative or absolute) → import directly
+ *   - Bare name → npm package (Node resolution)
+ *
+ * Each module should export a default or named `activate(ctx)` function.
+ * Errors are non-fatal — logged via ui:error and skipped.
+ */
+export async function loadExtensions(
+  ctx: ExtensionContext,
+  cliExtensions?: string[],
+): Promise<string[]> {
+  const specifiers: string[] = [];
+
+  if (cliExtensions) {
+    specifiers.push(...cliExtensions);
+  }
+
+  const settings = getSettings();
+  if (settings.extensions.length > 0) {
+    specifiers.push(...settings.extensions);
+  }
+
+  const userSpecifiers = await discoverUserExtensions(ctx);
+  specifiers.push(...userSpecifiers);
+
+  const seen = new Set<string>();
+  const unique = specifiers.filter((s) => {
+    if (seen.has(s)) return false;
+    seen.add(s);
+    return true;
+  });
+
+  const loaded = await loadSpecifiers(unique, ctx, false);
+  return loaded;
+}
+
+async function discoverUserExtensions(ctx: ExtensionContext): Promise<string[]> {
+  const specifiers: string[] = [];
+  const disabled = new Set(getSettings().disabledExtensions ?? []);
+
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = await fs.readdir(EXT_DIR, { withFileTypes: true });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return specifiers;
+    ctx.bus.emit("ui:error", {
+      message: `Failed to read extensions directory ${EXT_DIR}: ${err instanceof Error ? err.message : String(err)}`,
+    });
+    return specifiers;
+  }
+
+  for (const entry of entries) {
+    // Disable check: directory name for dir-extensions, or basename sans
+    // extension for file-extensions. Lets settings.json turn one off
+    // without renaming it.
+    const nameForDisable = entry.name.replace(/\.[^.]+$/, "");
+    if (disabled.has(nameForDisable)) continue;
+
+    const fullPath = path.join(EXT_DIR, entry.name);
+    try {
+      const isDir = entry.isDirectory() ||
+        (entry.isSymbolicLink() && (await fs.stat(fullPath)).isDirectory());
+      if (isDir) {
+        const indexFile = await findIndex(fullPath);
+        if (indexFile) specifiers.push(indexFile);
+      } else if (SCRIPT_EXTS.some((ext) => entry.name.endsWith(ext))) {
+        specifiers.push(fullPath);
+      }
+    } catch (err) {
+      ctx.bus.emit("ui:error", {
+        message: `Failed to inspect extension ${fullPath}: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  }
+  return specifiers;
+}
+
+async function loadSpecifiers(
+  specifiers: string[],
+  ctx: ExtensionContext,
+  bustCache: boolean,
+): Promise<string[]> {
+  const loaded: string[] = [];
+  for (const specifier of specifiers) {
+    try {
+      let importPath = await resolveSpecifier(specifier);
+
+      if (TS_EXTS.some((ext) => importPath.endsWith(ext))) {
+        await ensureTsSupport(bustCache);
+      }
+      if (bustCache) {
+        const sep = importPath.includes("?") ? "&" : "?";
+        importPath += `${sep}t=${Date.now()}`;
+      }
+      const mod = await import(importPath);
+      // tsx may double-wrap default exports: mod.default.default
+      const activate = typeof mod.default === "function"
+        ? mod.default
+        : typeof mod.default?.default === "function"
+          ? mod.default.default
+          : mod.activate;
+      if (typeof activate === "function") {
+        const base = path.basename(specifier).replace(/\.(ts|js|mjs|mts|tsx)$/, "");
+        const name = base === "index" ? path.basename(path.dirname(specifier)) : base;
+
+        // Awaiting activate() lets extensions with async setup (e.g.
+        // openrouter fetching its model catalog) finish before we move
+        // on; a 10s outer timeout in index.ts guards against hangs.
+        extensionDisposers.get(name)?.();
+        const { scoped, dispose } = createScopedContext(ctx, name);
+        await activate(scoped);
+        extensionDisposers.set(name, dispose);
+        loaded.push(name);
+      }
+    } catch (err) {
+      ctx.bus.emit("ui:error", {
+        message: `Failed to load extension ${specifier}: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  }
+  return loaded;
+}
+
+/**
+ * Reload user extensions (from ~/.agent-sh/extensions/).
+ * Tears down old registrations, busts the module cache, and re-activates.
+ */
+export async function reloadExtensions(ctx: ExtensionContext): Promise<string[]> {
+  const specifiers = await discoverUserExtensions(ctx);
+  return loadSpecifiers(specifiers, ctx, true);
+}
+
+/**
+ * Find an index file in a directory extension.
+ */
+async function findIndex(dir: string): Promise<string | null> {
+  for (const ext of SCRIPT_EXTS) {
+    const candidate = path.join(dir, `index${ext}`);
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve a specifier to an importable string.
+ *
+ * - Relative path (starts with ".") → resolve from cwd, file:// URL
+ * - Absolute path → file:// URL (directories resolved to index file)
+ * - Bare name → npm package (let Node resolve)
+ */
+async function resolveSpecifier(specifier: string): Promise<string> {
+  let resolved: string;
+
+  if (specifier.startsWith(".")) {
+    resolved = path.resolve(process.cwd(), specifier);
+  } else if (path.isAbsolute(specifier)) {
+    resolved = specifier;
+  } else {
+    // Distinguish bare npm specifier from a relative path lacking "./".
+    // Scoped packages ("@scope/pkg") contain "/" but are npm specifiers,
+    // so the "@" prefix takes precedence over the "/" heuristic.
+    if (specifier.includes("/") && !specifier.startsWith("@")) {
+      resolved = path.resolve(process.cwd(), specifier);
+    } else {
+      return specifier;
+    }
+  }
+
+  try {
+    const stat = await fs.stat(resolved);
+    if (stat.isDirectory()) {
+      const indexFile = await findIndex(resolved);
+      if (indexFile) {
+        return `file://${indexFile}`;
+      }
+      throw new Error(`No index file found in ${resolved}`);
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      // Not a directory, treat as file
+    } else if (err instanceof Error && err.message.startsWith("No index")) {
+      throw err;
+    }
+  }
+
+  return `file://${resolved}`;
+}