@rebon/cli-darwin-arm64 1.8.7 → 1.9.2

package/bin/mods-runtime/src/claude-code.mjs

@@ -0,0 +1,101 @@
+// The `claude-code` module a mod imports at run time.
+//
+// The type imports (`import type { Register } from 'claude-code'`) are
+// erased before this file is reached. What survives are the value imports:
+// `h` and `Fragment`, which JSX compiles against (also installed as globals,
+// since a hooks module may use JSX without importing anything), and the
+// state library — `atom`, `derive`, `read`, `update`, `memberOf` — which the
+// mods reference says comes from the same import.
+//
+// An element is plain data: `{ type, props, children }`, nothing a surface
+// cannot read as JSON. Handler props (`onPress`, `onInput`, ...) are kept by
+// the mod's own render registry and never leave the process; see
+// `render.mjs`.
+
+/// The marker the surface table's constructors leave on what they build.
+export const ELEMENT = Symbol.for('rebon.mod.element');
+
+export function Fragment(props) {
+  return { [ELEMENT]: true, type: 'Fragment', props: {}, children: normalizeChildren(props?.children) };
+}
+
+/// JSX factory. `type` is a constructor from `$.ui.resolve(e)` (a function),
+/// `Fragment`, or — refused later by validation — a string tag.
+export function h(type, props, ...children) {
+  const flat = normalizeChildren(children);
+  const given = props === null || props === undefined ? {} : { ...props };
+  if (typeof type === 'function') return type({ ...given, children: flat });
+  return { [ELEMENT]: true, type: String(type), props: given, children: flat };
+}
+
+/// Children as a flat list of elements and strings; `null`, `undefined` and
+/// booleans draw nothing, numbers draw as text.
+export function normalizeChildren(children) {
+  const out = [];
+  const push = (child) => {
+    if (child === null || child === undefined || typeof child === 'boolean') return;
+    if (Array.isArray(child)) { child.forEach(push); return; }
+    if (typeof child === 'number' || typeof child === 'bigint') { out.push(String(child)); return; }
+    if (typeof child === 'string') { out.push(child); return; }
+    if (typeof child === 'object' && child[ELEMENT]) {
+      if (child.type === 'Fragment') { child.children.forEach(push); return; }
+      out.push(child);
+      return;
+    }
+    out.push(String(child));
+  };
+  push(children);
+  return out;
+}
+
+if (typeof globalThis.h !== 'function') globalThis.h = h;
+if (typeof globalThis.Fragment !== 'function') globalThis.Fragment = Fragment;
+
+// ---- the state library -----------------------------------------------
+
+const ATOM = Symbol.for('rebon.mod.atom');
+const DERIVED = Symbol.for('rebon.mod.derived');
+
+/// A named value in `$.state` with an initial value, by typed reference.
+export function atom(ref, initial, options = {}) {
+  return Object.freeze({ [ATOM]: true, ref: Object.freeze({ ...ref }), initial, options: Object.freeze({ ...options }) });
+}
+
+/// A value computed from other atoms while drawing.
+export function derive(sources, compute) {
+  return Object.freeze({ [DERIVED]: true, sources: Object.freeze([...sources]), compute });
+}
+
+/// A member of a state family, named by `e`'s instance.
+export function memberOf(family, e) {
+  const id = typeof e === 'string' ? e : e?.requestId ?? e?.id;
+  return atom({ ...family.ref, id }, family.initial, family.options);
+}
+
+/// Reads an atom (or a derived value) through `$`, subscribing the drawing.
+export async function read($, source) {
+  if (source?.[DERIVED]) {
+    const values = await Promise.all(source.sources.map((inner) => read($, inner)));
+    return source.compute(...values);
+  }
+  if (!source?.[ATOM]) throw new TypeError('read() takes an atom or a derived value');
+  const { value } = await $.state.get(source.ref);
+  return value === undefined ? source.initial : value;
+}
+
+/// Reads, applies and writes with a version check, again on a miss, so two
+/// updates before a redraw both land.
+export async function update($, source, fn) {
+  if (!source?.[ATOM]) throw new TypeError('update() takes an atom');
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const current = await $.state.get(source.ref);
+    const value = fn(current.value === undefined ? source.initial : current.value);
+    const written = await $.state.set(source.ref, value, { ifVersion: current.version });
+    if (written.isWritten !== false) return written.value;
+  }
+  throw new Error(`update(): ${source.ref.plugin}.${source.ref.key} kept changing underneath`);
+}
+
+export function isAtom(value) {
+  return Boolean(value?.[ATOM]);
+}

package/bin/mods-runtime/src/client.mjs

@@ -0,0 +1,316 @@
+// The `Client` element: a mod's surface module, run here, drawn there.
+//
+// In Claude Code a `Client` runs its surface module on the terminal's own
+// drawing thread. Rebon's surfaces are not JavaScript, so the instance lives
+// where the mod does, in this process: its function, its local state, its
+// timers and its key listener. When the mod's render hook draws a tree
+// holding a `<Client key module props width height />`, the instance under
+// that key is called with its props and the region it was given, and what it
+// returns travels to the surface as the Client's one child. A `setState`, a
+// tick or a key asks the surface to draw the site again (`ui.invalidate`),
+// which runs the render hook and the instance once more with its state kept.
+//
+// The surface hands back what the person does to the region: keys while the
+// Client holds the site's focus ring (`clientKey`), clicks (`clientPointer`).
+// `surface.post(data)` raises `ui.message` on the mod's chain; a hook that
+// answers `{ props }` hands the instance its next props until the render
+// hook draws different ones.
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { clientElementTable, isElement } from './render.mjs';
+import { resolveModFile } from './transpile.mjs';
+
+/// Renders in a row that each `setState` without a key, pointer, tick or
+/// new props between: a render loop, and the instance unmounts.
+const RENDER_LOOP_STREAK = 3;
+/// The least interval `surface.every` runs at.
+const MIN_TICK_MS = 16;
+/// How much a post may hold, serialised.
+const MAX_POST_CHARS = 100_000;
+
+function instanceId(requestId, key) {
+  return `${requestId}\u0000${key}`;
+}
+
+/// The cells a `width` / `height` prop gives out of `available`: a count, a
+/// percentage of it, or all of it when the prop says neither.
+export function regionCells(value, available) {
+  const room = Math.max(0, Math.floor(available ?? 0));
+  if (typeof value === 'number' && Number.isFinite(value)) return Math.max(0, Math.min(room, Math.floor(value)));
+  if (typeof value === 'string' && value.trim().endsWith('%')) {
+    const percent = Number.parseFloat(value);
+    if (Number.isFinite(percent)) return Math.max(0, Math.floor((room * Math.min(100, percent)) / 100));
+  }
+  return room;
+}
+
+/// The function a surface module exports: its default, else its one
+/// PascalCase export.
+export function moduleFunction(namespace) {
+  if (typeof namespace?.default === 'function') return namespace.default;
+  const named = Object.entries(namespace ?? {}).filter(([name, value]) => /^[A-Z]/.test(name) && typeof value === 'function');
+  return named.length === 1 ? named[0][1] : undefined;
+}
+
+export class ClientHost {
+  #instances = new Map();
+  #invalidateQueued = false;
+
+  constructor(mod, { importModule = (url) => import(url) } = {}) {
+    this.mod = mod;
+    this.importModule = importModule;
+  }
+
+  /// Loads the surface module of every `Client` in `tree` that has no
+  /// running instance yet, ahead of the drawing, which is synchronous.
+  async prepare(requestId, tree, context) {
+    for (const node of clientNodes(tree)) {
+      const key = String(node.props.key ?? '');
+      const module = String(node.props.module ?? '');
+      if (!key || !module) continue;
+      const id = instanceId(requestId, key);
+      const held = this.#instances.get(id);
+      if (held && held.module === module) continue;
+      if (held) this.#unmount(held);
+      const instance = this.#newInstance(requestId, key, module, context);
+      this.#instances.set(id, instance);
+      try {
+        instance.fn = await this.#load(module);
+      } catch (error) {
+        instance.failed = error?.message ?? String(error);
+        this.mod.report(`Client ${module}`, error);
+      }
+    }
+  }
+
+  /// What the instance under `node`'s key draws now, as an element.
+  draw(requestId, node, context) {
+    const key = String(node.props.key ?? '');
+    const instance = this.#instances.get(instanceId(requestId, key));
+    const { Text } = clientElementTable(context.surface);
+    if (!instance) return Text({ dimColor: true, children: `Client ${key} is not loaded` });
+    instance.context = context;
+    instance.columns = regionCells(node.props.width, context.viewport?.columns);
+    instance.rows = regionCells(node.props.height, context.viewport?.rows);
+    const treeProps = JSON.stringify(node.props.props ?? null);
+    if (treeProps !== instance.lastTreeProps) {
+      instance.lastTreeProps = treeProps;
+      instance.props = node.props.props;
+      instance.propsOverride = undefined;
+      instance.loopStreak = 0;
+    }
+    if (instance.failed !== undefined) {
+      return Text({ dimColor: true, children: `${instance.module} stopped: ${instance.failed}` });
+    }
+    instance.setStateInDraw = false;
+    instance.drawing = true;
+    let drawn;
+    try {
+      drawn = instance.fn(instance.propsOverride !== undefined ? instance.propsOverride : instance.props, instance.surface);
+    } catch (error) {
+      this.#fail(instance, error);
+      return Text({ dimColor: true, children: `${instance.module} stopped: ${instance.failed}` });
+    } finally {
+      instance.drawing = false;
+    }
+    instance.loopStreak = instance.setStateInDraw ? instance.loopStreak + 1 : 0;
+    if (instance.loopStreak >= RENDER_LOOP_STREAK) {
+      this.#fail(instance, new Error(`setState on ${RENDER_LOOP_STREAK} renders in a row with nothing between: a render loop`));
+      return Text({ dimColor: true, children: `${instance.module} stopped: ${instance.failed}` });
+    }
+    if (typeof drawn === 'string') return Text({ children: drawn });
+    if (!isElement(drawn)) return Text({ dimColor: true, children: '' });
+    return drawn;
+  }
+
+  /// Unmounts the instances under `requestId` its latest drawing no longer
+  /// holds.
+  sweep(requestId, keys) {
+    for (const instance of [...this.#instances.values()]) {
+      if (instance.requestId === requestId && !keys.has(instance.key)) this.#unmount(instance);
+    }
+  }
+
+  /// Unmounts every instance of one site (its pane closed).
+  forget(requestId) {
+    this.sweep(requestId, new Set());
+  }
+
+  disposeAll() {
+    for (const instance of [...this.#instances.values()]) this.#unmount(instance);
+  }
+
+  /// A key the person pressed while the Client held the focus ring.
+  key(requestId, element, event) {
+    const instance = this.#instances.get(instanceId(requestId, String(element)));
+    if (!instance || instance.failed !== undefined || typeof instance.keyFn !== 'function') return { heard: false };
+    instance.loopStreak = 0;
+    try {
+      instance.keyFn(Object.freeze({ ...keyEvent(event) }));
+    } catch (error) {
+      this.#fail(instance, error);
+    }
+    return { heard: true };
+  }
+
+  /// A pointer event over the Client's region, region-relative.
+  pointer(requestId, element, event) {
+    const instance = this.#instances.get(instanceId(requestId, String(element)));
+    if (!instance || instance.failed !== undefined || typeof instance.pointerFn !== 'function') return { heard: false };
+    instance.loopStreak = 0;
+    try {
+      instance.pointerFn(Object.freeze({ ...event }));
+    } catch (error) {
+      this.#fail(instance, error);
+    }
+    return { heard: true };
+  }
+
+  /// How many instances run; for tests and `describe`.
+  get size() {
+    return this.#instances.size;
+  }
+
+  // ---- inside ----------------------------------------------------------
+
+  async #load(module) {
+    const base = path.resolve(this.mod.root, path.dirname(this.mod.entry));
+    const wanted = path.resolve(base, module);
+    const root = this.mod.root.endsWith(path.sep) ? this.mod.root : this.mod.root + path.sep;
+    if (!wanted.startsWith(root)) throw new Error(`[PATH_ESCAPES] the Client module ${module} is outside the mod's folder`);
+    const file = resolveModFile(wanted);
+    if (file === null) throw new Error(`[NO_MODULE] the Client module ${module} names no file`);
+    const namespace = await this.importModule(pathToFileURL(file).href);
+    const fn = moduleFunction(namespace);
+    if (typeof fn !== 'function') throw new Error(`[NO_COMPONENT] ${module} exports no default function and no one PascalCase function`);
+    return fn;
+  }
+
+  #newInstance(requestId, key, module, context) {
+    const host = this;
+    const instance = {
+      requestId, key, module, context,
+      fn: undefined, failed: undefined,
+      state: undefined, props: undefined, propsOverride: undefined, lastTreeProps: undefined,
+      columns: 0, rows: 0,
+      timers: new Set(), keyFn: undefined, pointerFn: undefined,
+      drawing: false, setStateInDraw: false, loopStreak: 0,
+      pendingPost: undefined, postQueued: false,
+    };
+    instance.surface = Object.freeze({
+      get elements() { return clientElementTable(instance.context?.surface); },
+      get state() { return instance.state; },
+      get columns() { return instance.columns; },
+      get rows() { return instance.rows; },
+      setState(next) {
+        instance.state = next;
+        if (instance.drawing) instance.setStateInDraw = true;
+        host.#invalidate();
+      },
+      every(ms, fn) {
+        const timer = setInterval(() => {
+          if (instance.failed !== undefined) return;
+          instance.loopStreak = 0;
+          try { fn(); } catch (error) { host.#fail(instance, error); }
+        }, Math.max(MIN_TICK_MS, Number(ms) || 0));
+        instance.timers.add(timer);
+        return () => { clearInterval(timer); instance.timers.delete(timer); };
+      },
+      onKey(fn) {
+        instance.keyFn = fn;
+        return () => { if (instance.keyFn === fn) instance.keyFn = undefined; };
+      },
+      onPointer(fn) {
+        instance.pointerFn = fn;
+        return () => { if (instance.pointerFn === fn) instance.pointerFn = undefined; };
+      },
+      post(data) {
+        let text;
+        try { text = JSON.stringify(data); } catch { return; }
+        if (text === undefined || text.length > MAX_POST_CHARS) return;
+        instance.pendingPost = JSON.parse(text);
+        if (instance.postQueued) return;
+        instance.postQueued = true;
+        setTimeout(() => host.#deliver(instance), 0);
+      },
+    });
+    return instance;
+  }
+
+  async #deliver(instance) {
+    instance.postQueued = false;
+    if (instance.failed !== undefined || !this.#instances.has(instanceId(instance.requestId, instance.key))) return;
+    const data = instance.pendingPost;
+    instance.pendingPost = undefined;
+    const e = {
+      surface: instance.context?.surface ?? 'terminal',
+      component: instance.context?.component ?? 'Pane',
+      requestId: instance.requestId,
+      element: instance.key,
+      module: instance.module,
+      data,
+    };
+    try {
+      const { result } = await this.mod.chain.dispatch('ui.message', e, async () => ({}), this.mod.dispatchOptions());
+      if (result && typeof result === 'object' && result.props !== undefined) {
+        instance.propsOverride = result.props;
+        instance.loopStreak = 0;
+        this.#invalidate();
+      }
+    } catch (error) {
+      this.mod.report(`ui.message from ${instance.module}`, error);
+    }
+  }
+
+  #fail(instance, error) {
+    instance.failed = error?.message ?? String(error);
+    this.#stopTimers(instance);
+    this.mod.report(`Client ${instance.module}`, error);
+    this.#invalidate();
+  }
+
+  #stopTimers(instance) {
+    for (const timer of instance.timers) clearInterval(timer);
+    instance.timers.clear();
+  }
+
+  #unmount(instance) {
+    this.#stopTimers(instance);
+    instance.keyFn = undefined;
+    instance.pointerFn = undefined;
+    this.#instances.delete(instanceId(instance.requestId, instance.key));
+  }
+
+  /// One redraw of the mod's sites per turn of the event loop, however many
+  /// instances asked.
+  #invalidate() {
+    if (this.#invalidateQueued) return;
+    this.#invalidateQueued = true;
+    setTimeout(() => {
+      this.#invalidateQueued = false;
+      if (this.mod.scopeCtx) void this.mod.seat('ui.invalidate', { event: 'ui.render' }).catch(() => {});
+    }, 0);
+  }
+}
+
+/// The `Client` elements in a tree a render hook returned, in order.
+export function clientNodes(tree) {
+  const out = [];
+  const walk = (node) => {
+    if (!isElement(node)) return;
+    if (node.type === 'Client') { out.push(node); return; }
+    for (const child of node.children ?? []) walk(child);
+  };
+  walk(tree);
+  return out;
+}
+
+/// A key as `ClientKeyEvent` spells it: the name, and only the modifiers
+/// held.
+function keyEvent(event) {
+  const out = { key: String(event?.key ?? '') };
+  if (event?.ctrl) out.ctrl = true;
+  if (event?.shift) out.shift = true;
+  if (event?.meta) out.meta = true;
+  return out;
+}

package/bin/mods-runtime/src/engine.mjs

@@ -0,0 +1,196 @@
+// `$`, the engine interface a mod's hooks are handed.
+//
+// Flat, `<noun>.<method>`, frozen. The nouns here are the core ones a
+// hooks module reaches for in the Claude Code declarations; what each does
+// on Rebon is one of three things:
+//
+// * answered locally — `plugin`, `ui.resolve`, `clock`, the timer half of
+//   the chain's own life;
+// * answered by the `mods` seat over `seat/call` — display (`ui.status`,
+//   `ui.toast`, `ui.log`, panes), state and store, files, processes, the
+//   network, settings, environment, the session's facts;
+// * dispatched through the chain itself — `prompt.submit`, `command.run`,
+//   `tool.call` on a tool the mod registered.
+//
+// A seat call made before the mod's scope opened, or after it closed,
+// rejects naming that: a mod that acts on its own schedule starts from
+// `session.start`, which fires once the scope is open.
+import { elementTable } from './render.mjs';
+
+/// The seat the engine interface is answered by on the Rust side.
+export const MODS_SEAT = 'mods';
+
+export function buildEngine(mod) {
+  const seat = (method, params = {}) => mod.seat(method, params);
+  const timers = mod.timers;
+
+  const $ = {
+    plugin: Object.freeze({ name: mod.name, root: mod.root }),
+
+    ui: Object.freeze({
+      resolve: (e) => elementTable(e?.surface),
+      status: (text) => { void seat('ui.status', { text: text ?? null }); },
+      toast: (text, options = {}) => { void seat('ui.toast', { text, ...options }); },
+      log: (text, options = {}) => { void seat('ui.log', { text: String(text), to: options.to ?? 'transcript' }); },
+      notice: (toolUseId, text) => { void seat('ui.notice', { toolUseId, text: text ?? null }); },
+      invalidate: (event = 'ui.render') => { void seat('ui.invalidate', { event }); },
+      open: (pane) => seat('ui.open', pane),
+      close: (pane) => {
+        if (pane?.id !== undefined) mod.clients.forget(String(pane.id));
+        return seat('ui.close', pane);
+      },
+      panes: () => seat('ui.panes', {}),
+      focus: (args) => seat('ui.focus', args),
+      scroll: (args) => seat('ui.scroll', args),
+      copy: (args) => seat('ui.copy', args),
+      selection: () => seat('ui.selection', {}),
+      ask: (question, options) => seat('ui.ask', { question, options: Array.isArray(options) ? { choices: options } : options ?? {} }),
+      blit: async () => ({ deny: 'the terminal raster is not drawn on Rebon' }),
+    }),
+
+    state: Object.freeze({
+      get: (ref) => seat('state.get', { ref }),
+      set: (ref, value, options = {}) => seat('state.set', { ref, value, ...options }),
+    }),
+
+    store: Object.freeze({
+      get: (key) => seat('store.get', { key }),
+      set: (key, value) => seat('store.set', { key, value }),
+      delete: (key) => seat('store.delete', { key }),
+      keys: () => seat('store.keys', {}),
+    }),
+
+    clock: Object.freeze({
+      now: () => Date.now(),
+      sleep: (ms, options = {}) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { timers.delete(timer); resolve(); }, ms);
+        timers.add(timer);
+        options.signal?.addEventListener('abort', () => { clearTimeout(timer); timers.delete(timer); reject(new Error('sleep aborted')); }, { once: true });
+      }),
+      after: (ms, fn) => {
+        const timer = setTimeout(() => { timers.delete(timer); runTimer(mod, fn); }, ms);
+        timers.add(timer);
+        return Object.freeze({ cancel: () => { clearTimeout(timer); timers.delete(timer); } });
+      },
+      every: (ms, fn) => {
+        const timer = setInterval(() => runTimer(mod, fn), Math.max(10, ms));
+        timers.add(timer);
+        return Object.freeze({ cancel: () => { clearInterval(timer); timers.delete(timer); } });
+      },
+    }),
+
+    session: Object.freeze({
+      id: () => mod.sessionFact('sessionId'),
+      cwd: () => mod.sessionFact('cwd'),
+      root: () => mod.sessionFact('cwd'),
+      model: () => mod.sessionFact('model'),
+      surface: () => mod.sessionFact('surface'),
+      surfaces: () => seat('session.surfaces', {}),
+      turns: () => mod.sessionFact('turns'),
+      messages: (args = {}) => seat('session.messages', args),
+      usage: (args = {}) => seat('session.usage', args),
+      version: () => seat('session.version', {}),
+      repo: () => seat('session.repo', {}),
+      append: (args) => seat('session.append', args),
+      send: (args) => seat('session.send', args),
+      compact: (args = {}) => seat('session.compact', args),
+      authorize: () => seat('session.authorize', {}),
+    }),
+
+    turn: Object.freeze({
+      abort: (input = {}) => seat('turn.abort', input),
+    }),
+
+    prompt: Object.freeze({
+      submit: (input) => seat('prompt.submit', typeof input === 'string' ? { text: input } : input),
+      fill: (input) => seat('prompt.fill', input),
+      suggest: (input) => seat('prompt.suggest', typeof input === 'string' ? { text: input } : input),
+      read: () => seat('prompt.read', {}),
+      compose: (args = {}) => seat('prompt.compose', args),
+    }),
+
+    tool: Object.freeze({
+      list: () => seat('tool.list', {}),
+      call: (input) => mod.callTool(input),
+      check: (input) => seat('tool.check', input),
+      register: (spec) => mod.registerTool(spec),
+    }),
+
+    command: Object.freeze({
+      list: () => seat('command.list', {}),
+      run: (input) => seat('command.run', typeof input === 'string' ? { command: input } : input),
+      register: (spec) => mod.registerCommand(spec),
+    }),
+
+    config: Object.freeze({
+      list: () => seat('config.list', {}),
+      set: (input) => seat('config.set', input),
+    }),
+
+    settings: Object.freeze({
+      read: (args = {}) => seat('settings.read', args),
+    }),
+
+    env: Object.freeze({
+      get: (name) => seat('env.get', { name }),
+      set: (name, value) => seat('env.set', { name, value: value ?? null }),
+    }),
+
+    fs: Object.freeze({
+      read: (path, options = {}) => seat('fs.read', { path, ...options }),
+      write: (path, text) => seat('fs.write', { path, text }),
+      list: (path) => seat('fs.list', { path: path ?? null }),
+      exists: (path) => seat('fs.exists', { path }),
+      stat: (path, options = {}) => seat('fs.stat', { path, ...options }),
+      ancestors: (request) => seat('fs.ancestors', request),
+    }),
+
+    process: Object.freeze({
+      run: (argv, init = {}) => seat('process.run', { argv: [...argv], ...init }),
+      spawn: async (request) => {
+        // No streaming on this plane: the child runs to completion and its
+        // output comes back whole, which is what `run` answers.
+        const done = await seat('process.run', { argv: [...request.argv], cwd: request.cwd, env: request.env, input: request.input });
+        return { ...done, isStreamed: false };
+      },
+    }),
+
+    http: Object.freeze({
+      fetch: (url, init = {}) => seat('http.fetch', { url: String(url), ...init }),
+    }),
+
+    model: Object.freeze({
+      complete: (request, options = {}) => seat('model.complete', { ...request, ...options }),
+      fork: (request) => seat('model.fork', request),
+      classify: (text, labels, options = {}) => seat('model.classify', { text, labels: [...labels], ...options }),
+    }),
+
+    agent: Object.freeze({
+      list: () => seat('agent.list', {}),
+      spawn: (input) => seat('agent.spawn', input),
+      register: (spec) => seat('agent.register', spec),
+    }),
+
+    mcp: Object.freeze({
+      call: (server, tool, args = {}) => mod.callTool({ tool: `mcp__${server}__${tool}`, input: args }),
+      connect: (server) => seat('mcp.connect', { server }),
+    }),
+
+    audio: Object.freeze({
+      play: async () => ({ isPlayed: false, reason: 'no-audio' }),
+      speak: async () => ({ isSpoken: false, reason: 'no-audio' }),
+    }),
+
+    telemetry: Object.freeze({
+      log: (entry) => { void seat('ui.log', { text: JSON.stringify(entry), to: 'debug' }); },
+      mark: () => {},
+    }),
+  };
+  return Object.freeze($);
+}
+
+function runTimer(mod, fn) {
+  Promise.resolve()
+    .then(() => fn(mod.engine))
+    .catch((error) => mod.report('timer', error));
+}

package/bin/mods-runtime/src/index.mjs

@@ -0,0 +1,58 @@
+// The package's root export: the loader seam for Claude Code mods.
+//
+// A mod — a Claude Code plugin of function hooks, `.claude-plugin/plugin.json`
+// beside a `hooks/hooks.json` naming one hooks module — is a plane plugin of
+// a shape the host's own loader does not know. This decides it is one by
+// reading the load request, not the module: rebon marks the request's
+// `config.$claudeMod` when it synthesised the manifest from the plugin's
+// folder, so what loads here is exactly what rebon said it was loading.
+//
+// `createLoader({ next })` is the host's contract: `next` is the loader a
+// request this one does not recognise is handed to, untouched.
+import { Mod, MOD_SERVICE } from './mod.mjs';
+
+export { MOD_SERVICE };
+export { transformJsx } from './jsx-transform.mjs';
+export { transpileModSource } from './transpile.mjs';
+export { HookChain, patternSelects, matcherSelects } from './chain.mjs';
+export { elementTable, SURFACES } from './render.mjs';
+
+const mods = new Map();
+
+/// The marker rebon puts on a mod's load request.
+export const MARKER = '$claudeMod';
+
+/// Whether a load request is a mod's.
+export function isModRequest(request) {
+  const marker = request?.config?.[MARKER];
+  return marker !== null && typeof marker === 'object' && !Array.isArray(marker);
+}
+
+export async function createLoader({ next }) {
+  return {
+    async load(request) {
+      if (!isModRequest(request)) return next(request);
+      const mod = new Mod({
+        pluginId: request.pluginId,
+        root: request.root,
+        entry: request.entry,
+        marker: request.config[MARKER],
+      });
+      await mod.load();
+      mods.set(request.pluginId, mod);
+      return mod.sealed();
+    },
+    async unload(pluginId) {
+      const mod = mods.get(pluginId);
+      if (!mod) return false;
+      mods.delete(pluginId);
+      mod.dispose();
+      return true;
+    },
+  };
+}
+
+/// The mods this process has loaded, by plugin id.
+export function loadedMods() {
+  return new Map(mods);
+}