@rebon/cli-darwin-arm64 1.8.6 → 1.9.1

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

@@ -0,0 +1,370 @@
+// One loaded mod: its hooks module, its chain, its `$`, and the service
+// the plane drives it through.
+//
+// A mod is a plane plugin of one shape. It registers exactly one service,
+// `mod`, and one scope handler. The service is how rebon reaches the chain
+// — a classic hook event, a render ask, a press, a command, one of its own
+// tools — and the scope handler is where `$` binds to a session: once the
+// scope opens `session.start` fires, and from then on `$`'s seat calls have
+// somewhere to go.
+//
+// The declarations a mod loads against come from the manifest rebon
+// synthesised by scanning the hooks module (`$claudeMod` in the load
+// request's config): the commands and tools it names there are registered
+// with the host's registrar here, so the plane projects them like any
+// plugin's, and a `$.command.register` / `$.tool.register` at run time
+// refines a declared one rather than adding a name the ceiling lacks.
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
+import { HookChain } from './chain.mjs';
+import { buildEngine } from './engine.mjs';
+import { dispatchClassic } from './classic.mjs';
+import { HandlerRegistry, isElement } from './render.mjs';
+import { ClientHost } from './client.mjs';
+import { registerModRoot, unregisterModRoot } from './transpile.mjs';
+
+/// The one service every mod registers.
+export const MOD_SERVICE = 'mod';
+
+class ModError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = 'ModError';
+  }
+}
+
+const SURFACES = new Set(['tui', 'desktop', 'acp', 'web', 'mobile']);
+
+function diagnostic(level, message) {
+  process.stderr.write(`${JSON.stringify({ level, message: String(message).replace(/[\r\n]+/g, ' ').slice(0, 512) })}\n`);
+}
+
+export class Mod {
+  constructor({ pluginId, root, entry, marker }) {
+    this.pluginId = pluginId;
+    this.root = path.resolve(root);
+    this.entry = entry;
+    this.name = marker.name ?? pluginId;
+    this.version = marker.version;
+    this.options = Object.freeze({ ...(marker.options ?? {}) });
+    this.declaredCommands = marker.commands ?? [];
+    this.declaredTools = marker.tools ?? [];
+    this.chain = new HookChain({ onFailure: (failure) => this.#hookFailed(failure) });
+    this.timers = new Set();
+    this.pendingCalls = new Map();
+    this.handlers = new HandlerRegistry();
+    this.clients = new ClientHost(this);
+    this.scopeCtx = null;
+    this.facts = { cwd: this.root, sessionId: undefined, model: undefined, surface: undefined, turns: 0 };
+    this.registeredSpecs = { commands: new Map(), tools: new Map() };
+    this.engine = buildEngine(this);
+  }
+
+  /// Imports the hooks module and runs its `register`.
+  async load(importModule = (url) => import(url)) {
+    registerModRoot(this.root);
+    const file = path.resolve(this.root, this.entry);
+    let module;
+    try {
+      module = await importModule(pathToFileURL(file).href);
+    } catch (cause) {
+      throw new ModError('[ENTRY_FAILED]', `hooks module ${this.entry} failed to load: ${cause?.message ?? cause}`);
+    }
+    const register = typeof module?.register === 'function' ? module.register : module?.default?.register;
+    if (typeof register !== 'function') {
+      throw new ModError('[NO_REGISTER]', `hooks module ${this.entry} exports no register function`);
+    }
+    const on = (pattern, matcherOrHook, maybeHook) => this.chain.on(pattern, matcherOrHook, maybeHook);
+    try {
+      await register(on, this.options);
+    } catch (cause) {
+      throw new ModError('[REGISTER_FAILED]', `register() of ${this.name} failed: ${cause?.message ?? cause}`);
+    }
+  }
+
+  /// The registrar shape the host keeps for this plugin.
+  sealed() {
+    const serviceHandlers = new Map([[MOD_SERVICE, (request, ctx) => this.handleService(request, ctx)]]);
+    const toolHandlers = new Map();
+    const tools = [];
+    for (const declared of this.declaredTools) {
+      const name = declared.name;
+      tools.push({ name, description: declared.description || `Tool ${name} of the mod ${this.name}`, inputSchema: declared.inputSchema ?? { type: 'object' } });
+      toolHandlers.set(name, (request, ctx) => this.serveTool(name, request, ctx));
+    }
+    const commandHandlers = new Map();
+    const commands = [];
+    for (const declared of this.declaredCommands) {
+      const name = declared.name;
+      const definition = {
+        name,
+        description: declared.description || `/${name}, a command of the mod ${this.name}`,
+        kind: { type: 'prompt' },
+        surfaces: ['tui', 'desktop', 'acp', 'web', 'mobile'],
+      };
+      if (declared.argumentHint) definition.hint = declared.argumentHint;
+      commands.push(Object.freeze(definition));
+      commandHandlers.set(name, (request, ctx) => this.serveCommand(name, request, ctx));
+    }
+    return Object.freeze({
+      services: Object.freeze([MOD_SERVICE]),
+      eventTopics: Object.freeze([]),
+      llmProviders: Object.freeze([]),
+      llmAdapterInfo: Object.freeze({}),
+      tools: Object.freeze(tools),
+      commands: Object.freeze(commands),
+      commandHandlers,
+      serviceHandlers,
+      topicHandlers: new Map(),
+      llmAdapters: new Map(),
+      toolHandlers,
+      scopeHandlers: Object.freeze([(ctx) => this.onScopeOpen(ctx)]),
+    });
+  }
+
+  dispose() {
+    for (const timer of this.timers) { clearTimeout(timer); clearInterval(timer); }
+    this.timers.clear();
+    for (const pending of this.pendingCalls.values()) {
+      clearTimeout(pending.expiry);
+      pending.settle({ result: { error: 'the mod was unloaded' }, isError: true });
+    }
+    this.pendingCalls.clear();
+    this.handlers.clear();
+    this.clients.disposeAll();
+    this.scopeCtx = null;
+    unregisterModRoot(this.root);
+  }
+
+  // ---- the scope ------------------------------------------------------
+
+  async onScopeOpen(ctx) {
+    this.scopeCtx = ctx;
+    if (ctx.workspaceRoot) this.facts.cwd = ctx.workspaceRoot;
+    try {
+      await this.chain.dispatch('session.start', { cwd: this.facts.cwd }, async () => ({ cwd: this.facts.cwd }), this.dispatchOptions());
+    } catch (error) {
+      this.report('session.start', error);
+    }
+    return () => { if (this.scopeCtx === ctx) this.scopeCtx = null; };
+  }
+
+  seat(method, params) {
+    const ctx = this.scopeCtx;
+    if (!ctx) return Promise.reject(new ModError('[NO_SESSION]', `$.${method} was called before the mod ${this.name} was bound to a session`));
+    return ctx.seat('mods', method, { ...params });
+  }
+
+  sessionFact(name) {
+    return this.facts[name];
+  }
+
+  dispatchOptions(extra = {}) {
+    return { engine: this.engine, origin: { kind: 'engine' }, ...extra };
+  }
+
+  report(where, error) {
+    const message = `${this.name}: ${where}: ${error?.message ?? error}`;
+    diagnostic('warn', message);
+    if (this.scopeCtx) void this.seat('ui.log', { text: message, to: 'debug' }).catch(() => {});
+  }
+
+  log(text, to = 'transcript') {
+    if (this.scopeCtx) void this.seat('ui.log', { text, to }).catch(() => {});
+    else diagnostic('info', `${this.name}: ${text}`);
+  }
+
+  #hookFailed({ event, pattern, error, inCatch }) {
+    this.report(`${event} (hook on ${pattern}${inCatch ? ', its .catch' : ''})`, error);
+  }
+
+  // ---- registrations at run time ----------------------------------------
+
+  ownToolName(name) {
+    return name.startsWith('mcp__') ? name : `mcp__${this.name}__${name}`;
+  }
+
+  async registerTool(spec) {
+    if (!spec || typeof spec.name !== 'string') throw new ModError('[WRONG_SHAPE]', '$.tool.register needs { name, description, inputSchema }');
+    const full = this.ownToolName(spec.name);
+    if (!this.declaredTools.some((tool) => tool.name === full)) {
+      throw new ModError('[UNDECLARED_TOOL]', `tool ${spec.name} is not one the hooks module names in a $.tool.register({ name: "..." }) literal; spell it as one`);
+    }
+    this.registeredSpecs.tools.set(full, spec);
+    return this.seat('tool.register', { name: full, description: spec.description, inputSchema: spec.inputSchema ?? spec.input_schema ?? { type: 'object' } });
+  }
+
+  async registerCommand(spec) {
+    if (!spec || typeof spec.name !== 'string') throw new ModError('[WRONG_SHAPE]', '$.command.register needs { name, description }');
+    if (!this.declaredCommands.some((command) => command.name === spec.name)) {
+      throw new ModError('[UNDECLARED_COMMAND]', `command ${spec.name} is not one the hooks module names in a $.command.register({ name: "..." }) literal; spell it as one`);
+    }
+    this.registeredSpecs.commands.set(spec.name, spec);
+    return this.seat('command.register', { name: spec.name, description: spec.description, argumentHint: spec.argumentHint ?? null });
+  }
+
+  /// `$.tool.call`: one of this mod's own tools runs through its chain;
+  /// any other goes to rebon through the scope's `tool/invoke`.
+  async callTool(input) {
+    const tool = input?.tool;
+    if (typeof tool !== 'string') throw new ModError('[WRONG_SHAPE]', '$.tool.call needs { tool, input }');
+    if (this.declaredTools.some((declared) => declared.name === tool)) {
+      const { result } = await this.chain.dispatch('tool.call', { tool, input: input.input ?? {}, origin: { kind: 'plugin', name: this.name } }, async () => ({ deny: `no hook of ${this.name} answers ${tool}` }), this.dispatchOptions());
+      return result;
+    }
+    const ctx = this.scopeCtx;
+    if (!ctx) throw new ModError('[NO_SESSION]', `$.tool.call(${tool}) was made before the mod was bound to a session`);
+    try {
+      const result = await ctx.invoke(tool, input.input ?? {});
+      return { result, isError: false, ref: { tool } };
+    } catch (error) {
+      return { deny: error?.message ?? String(error) };
+    }
+  }
+
+  // ---- what the plane asks ----------------------------------------------
+
+  async serveTool(name, request, ctx) {
+    this.scopeCtx ??= ctx;
+    const e = { tool: name, input: request?.input ?? {}, tool_use_id: request?.toolUseId ?? null, origin: { kind: 'model' } };
+    const { result } = await this.chain.dispatch('tool.call', e, async () => ({ deny: `no hook of ${this.name} answers the tool ${name}` }), this.dispatchOptions({ signal: ctx?.signal }));
+    if (result !== null && typeof result === 'object' && typeof result.deny === 'string') {
+      throw new ModError('[TOOL_DENIED]', result.deny);
+    }
+    return result?.result ?? result ?? null;
+  }
+
+  async serveCommand(name, request, ctx) {
+    this.scopeCtx ??= ctx;
+    const answer = await this.runCommand({ command: name, args: request?.rest ?? '', raw: request?.raw ?? `/${name}`, surface: request?.surface }, ctx);
+    return typeof answer === 'string' ? answer : answer?.text ?? '';
+  }
+
+  async runCommand({ command, args, raw, surface }, ctx) {
+    const e = {
+      command,
+      args: args ?? '',
+      raw: raw ?? `/${command}${args ? ` ${args}` : ''}`,
+      origin: { kind: 'user' },
+      presentation: { surface: SURFACES.has(surface) ? surface : 'tui', isFullscreen: surface !== 'tui' },
+    };
+    const { result } = await this.chain.dispatch('command.run', e, async () => ({ text: '' }), this.dispatchOptions({ signal: ctx?.signal }));
+    if (typeof result === 'string') return { text: result };
+    if (result && typeof result === 'object') return { text: typeof result.text === 'string' ? result.text : '', context: result.context };
+    return { text: '' };
+  }
+
+  async render({ component, surface, requestId, props, viewport }) {
+    const e = { component, surface: surface ?? 'terminal', requestId, props: props ?? {}, viewport: viewport ?? undefined };
+    const engineDraws = Symbol('engine');
+    const { result } = await this.chain.dispatch('ui.render', e, async () => engineDraws, this.dispatchOptions());
+    if (result === engineDraws || result === undefined || result === null) {
+      this.clients.forget(requestId);
+      return { engine: true };
+    }
+    if (isElement(result)) {
+      const context = { component, surface: e.surface, viewport: e.viewport, requestId };
+      await this.clients.prepare(requestId, result, context);
+      const drawn = new Set();
+      const tree = this.handlers.serialize(requestId, result, (node) => {
+        drawn.add(String(node.props.key ?? ''));
+        return this.clients.draw(requestId, node, context);
+      });
+      this.clients.sweep(requestId, drawn);
+      return { tree };
+    }
+    if (typeof result === 'string') {
+      this.clients.forget(requestId);
+      return { tree: { type: 'Text', props: {}, children: [result] } };
+    }
+    return { error: `the ui.render hook of ${this.name} answered ${typeof result}, not a tree` };
+  }
+
+  async act(kind, request) {
+    const { component, surface, requestId, element } = request;
+    const base = { plugin: this.name, element, component, surface: surface ?? 'terminal', requestId };
+    const handlerName = kind === 'press' ? 'onPress' : kind === 'select' ? 'onSelect' : request.inputKind === 'change' ? 'onInput' : 'onSubmit';
+    const core = async (final) => {
+      const handler = this.handlers.handler(requestId, element, handlerName) ?? (kind === 'press' ? this.handlers.handler(requestId, element, 'onLinkPress') : undefined);
+      if (typeof handler === 'function') {
+        try {
+          await handler(kind === 'press' ? { element, href: final.href } : final.value, final);
+        } catch (error) {
+          this.report(`ui.${kind} (${handlerName} of ${element})`, error);
+        }
+      }
+      return kind === 'press' ? { element } : { element, value: final.value };
+    };
+    const e = kind === 'press'
+      ? { ...base, href: request.href }
+      : kind === 'input'
+        ? { ...base, kind: request.inputKind ?? 'submit', value: request.value ?? '' }
+        : { ...base, value: request.value };
+    const { result } = await this.chain.dispatch(`ui.${kind}`, e, core, this.dispatchOptions());
+    return result ?? {};
+  }
+
+  /// The site's focus ring about to move onto `element` (absent: off the
+  /// mod's elements), raised as `ui.focus`: `{ deny }` keeps the ring where
+  /// it is, else `{ element }` is where it lands, which a hook may rewrite.
+  async focus(request) {
+    const e = {
+      component: request.component,
+      requestId: request.requestId,
+      origin: request.origin?.kind === 'plugin' ? { kind: 'plugin', name: String(request.origin.name ?? this.name) } : { kind: 'person' },
+    };
+    if (typeof request.element === 'string') {
+      e.plugin = this.name;
+      e.element = request.element;
+    }
+    const { result } = await this.chain.dispatch('ui.focus', e, async (final) => ({ element: final.element ?? null }), this.dispatchOptions());
+    if (result && typeof result.deny === 'string') return { deny: result.deny };
+    const element = result && 'element' in result ? result.element : e.element ?? null;
+    return { element: typeof element === 'string' ? element : null };
+  }
+
+  describe() {
+    return {
+      name: this.name,
+      version: this.version ?? null,
+      root: this.root,
+      patterns: this.chain.patterns(),
+      commands: this.declaredCommands.map((command) => command.name),
+      tools: this.declaredTools.map((tool) => tool.name),
+      pendingToolCalls: this.pendingCalls.size,
+      timers: this.timers.size,
+      clients: this.clients.size,
+    };
+  }
+
+  async handleService(request, ctx) {
+    if (request === null || typeof request !== 'object') throw new ModError('[WRONG_SHAPE]', 'a mod service request is an object with a kind');
+    if (ctx && !this.scopeCtx) this.scopeCtx = ctx;
+    switch (request.kind) {
+      case 'classic': {
+        if (request.input?.cwd) this.facts.cwd = request.input.cwd;
+        if (request.input?.session_id) this.facts.sessionId = request.input.session_id;
+        return dispatchClassic(this, request);
+      }
+      case 'facts':
+        Object.assign(this.facts, request.facts ?? {});
+        return {};
+      case 'render': return this.render(request);
+      case 'press': return this.act('press', request);
+      case 'input': return this.act('input', request);
+      case 'select': return this.act('select', request);
+      case 'command': return this.runCommand(request, ctx);
+      case 'describe': return this.describe();
+      case 'forget':
+        this.handlers.forget(request.requestId);
+        this.clients.forget(request.requestId);
+        return {};
+      case 'focus': return this.focus(request);
+      case 'clientKey': return this.clients.key(request.requestId, request.element, request.key ?? {});
+      case 'clientPointer': return this.clients.pointer(request.requestId, request.element, request.pointer ?? {});
+      default:
+        throw new ModError('[UNKNOWN_KIND]', `mod service does not know the kind ${JSON.stringify(request.kind)}`);
+    }
+  }
+}

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

@@ -0,0 +1,122 @@
+// What a render hook draws with, and what leaves the process.
+//
+// `$.ui.resolve(e)` answers the element table of the surface `e` is drawn
+// on: a frozen object of constructors, the JSX tags a hook destructures.
+// Each constructor builds plain data. Before a tree crosses to rebon it is
+// serialised here: handler props are taken off and remembered by the
+// element's `key` for the instance (`requestId`) that drew them, so a press
+// reported by the surface finds its closure, and everything else is JSON.
+//
+// The tables mirror `Elements` in the Claude Code declarations: the
+// terminal alone has `Raster` and `Image`, the mobile table has no `Input`,
+// `Select` or `Client`, and `vscode` has no `Client`. A surface that cannot
+// draw an element it is handed says so on its own side; the table here is
+// what lets `e.surface` narrow the constructors a hook may reach for.
+import { ELEMENT, normalizeChildren } from './claude-code.mjs';
+
+const HANDLER_PROPS = Object.freeze(['onPress', 'onInput', 'onSubmit', 'onSelect', 'onLinkPress', 'onChange']);
+
+const TABLES = Object.freeze({
+  terminal: ['Box', 'Text', 'Button', 'Input', 'Select', 'Link', 'Code', 'Markdown', 'Client', 'Raster', 'Image'],
+  desktop: ['Box', 'Text', 'Button', 'Input', 'Select', 'Svg', 'Link', 'Code', 'Markdown', 'Client'],
+  mobile: ['Box', 'Text', 'Button', 'Svg', 'Link', 'Code', 'Markdown'],
+  vscode: ['Box', 'Text', 'Button', 'Input', 'Select', 'Svg', 'Link', 'Code', 'Markdown'],
+});
+
+export const SURFACES = Object.freeze(Object.keys(TABLES));
+
+function constructor(type) {
+  const build = (props = {}) => {
+    const { children, ...rest } = props;
+    return { [ELEMENT]: true, type, props: rest, children: normalizeChildren(children) };
+  };
+  Object.defineProperty(build, 'name', { value: type });
+  return build;
+}
+
+const tables = new Map();
+const clientTables = new Map();
+
+/// The frozen element table for `surface`; `terminal` when unknown.
+export function elementTable(surface) {
+  const name = TABLES[surface] ? surface : 'terminal';
+  if (!tables.has(name)) {
+    const table = {};
+    for (const type of TABLES[name]) table[type] = constructor(type);
+    tables.set(name, Object.freeze(table));
+  }
+  return tables.get(name);
+}
+
+/// The table a `Client`'s surface module draws with: its surface's,
+/// without `Client` (a surface module draws no Client of its own).
+export function clientElementTable(surface) {
+  const name = TABLES[surface] ? surface : 'terminal';
+  if (!clientTables.has(name)) {
+    const { Client: _client, ...rest } = elementTable(name);
+    clientTables.set(name, Object.freeze(rest));
+  }
+  return clientTables.get(name);
+}
+
+/// Remembers handler closures per drawn instance.
+export class HandlerRegistry {
+  #byInstance = new Map();
+
+  /// Serialises `tree` for `requestId`, keeping its handlers here. A
+  /// `Client` is handed to `drawClient`, and what that returns is drawn as
+  /// its one child; without it a Client goes out undrawn.
+  serialize(requestId, tree, drawClient) {
+    const handlers = new Map();
+    let autoKey = 0;
+    const walk = (node) => {
+      if (typeof node === 'string') return node;
+      if (!node || !node[ELEMENT]) return String(node);
+      if (node.type === 'Client') {
+        const props = { key: String(node.props.key ?? ''), module: String(node.props.module ?? '') };
+        for (const name of ['width', 'height', 'flexGrow']) {
+          if (node.props[name] !== undefined) props[name] = node.props[name];
+        }
+        const drawn = typeof drawClient === 'function' ? drawClient(node) : undefined;
+        return { type: 'Client', props, children: drawn === undefined ? [] : [walk(drawn)] };
+      }
+      const props = {};
+      let key = node.props.key;
+      const own = {};
+      for (const [name, value] of Object.entries(node.props)) {
+        if (HANDLER_PROPS.includes(name) && typeof value === 'function') { own[name] = value; continue; }
+        if (value === undefined) continue;
+        if (typeof value === 'function') continue;
+        props[name] = value;
+      }
+      if (Object.keys(own).length > 0) {
+        if (key === undefined || key === null || key === '') {
+          key = `auto-${++autoKey}`;
+          props.key = key;
+        }
+        handlers.set(String(key), own);
+      }
+      return { type: node.type, props, children: node.children.map(walk) };
+    };
+    const serialized = walk(tree);
+    this.#byInstance.set(requestId, handlers);
+    return serialized;
+  }
+
+  handler(requestId, key, name) {
+    return this.#byInstance.get(requestId)?.get(String(key))?.[name];
+  }
+
+  forget(requestId) {
+    this.#byInstance.delete(requestId);
+  }
+
+  clear() {
+    this.#byInstance.clear();
+  }
+}
+
+/// Whether `value` is an element a constructor built (a tree's root).
+export function isElement(value) {
+  return Boolean(value && typeof value === 'object' && value[ELEMENT]);
+}

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

@@ -0,0 +1,167 @@
+// Loading a mod's files: the module hooks that make `.tsx` and the bare
+// `claude-code` specifier resolve.
+//
+// A hooks module "is an ES module whatever its suffix", may be TypeScript,
+// may hold JSX, and imports `claude-code` for its state helpers (at run time
+// the type imports are empty, the value imports are not). None of that is
+// something Node does by itself, so this installs synchronous module hooks
+// (`module.registerHooks`) that answer for files under a registered mod root
+// and hand everything else on untouched: a Cordis entry or the host's own
+// files never pass through here.
+//
+// Order of operations on a `.tsx`: JSX to `h()` calls first
+// (`jsx-transform.mjs`), then Node's own `stripTypeScriptTypes` in
+// `transform` mode — the JSX is what the type stripper refuses, so it has to
+// be gone before the stripper sees the file.
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { registerHooks, stripTypeScriptTypes } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { transformJsx } from './jsx-transform.mjs';
+
+/// The one bare specifier a mod imports: the Claude Code runtime module.
+export const CLAUDE_CODE_SPECIFIER = 'claude-code';
+
+const SHIM_URL = new URL('./claude-code.mjs', import.meta.url).href;
+
+/// The suffixes a mod's files may carry. A file named otherwise is not a
+/// mod file, and an import of one is refused rather than guessed at.
+export const MOD_EXTENSIONS = Object.freeze(['.ts', '.tsx', '.jsx', '.js', '.mjs', '.cjs', '.mts', '.cts']);
+
+/// The suffixes tried, in order, for a relative import written without one
+/// (`./card`), as TypeScript and Claude Code resolve it.
+const IMPLIED_EXTENSIONS = Object.freeze(['.ts', '.tsx', '.mts', '.js', '.jsx', '.mjs']);
+
+/// For a `.js`-family import with no file behind it, the TypeScript source
+/// it was written against: `./util.js` naming `./util.ts`.
+const SOURCE_FOR = Object.freeze({ '.js': ['.ts', '.tsx'], '.jsx': ['.tsx'], '.mjs': ['.mts'], '.cjs': ['.cts'] });
+
+function isFile(filename) {
+  try {
+    return statSync(filename).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/// The mod file a relative import names: the file itself when it is one,
+/// else the TypeScript resolution of an import written without a suffix
+/// (`./card` → `./card.ts`, `./dir` → `./dir/index.ts`) or with the
+/// emitted one (`./util.js` → `./util.ts`). `null` when none exists.
+export function resolveModFile(filename) {
+  const extension = path.extname(filename);
+  if (MOD_EXTENSIONS.includes(extension) && isFile(filename)) return filename;
+  for (const source of SOURCE_FOR[extension] ?? []) {
+    const candidate = filename.slice(0, -extension.length) + source;
+    if (isFile(candidate)) return candidate;
+  }
+  for (const implied of IMPLIED_EXTENSIONS) {
+    if (isFile(filename + implied)) return filename + implied;
+  }
+  for (const implied of IMPLIED_EXTENSIONS) {
+    const index = path.join(filename, `index${implied}`);
+    if (isFile(index)) return index;
+  }
+  return null;
+}
+
+const roots = new Set();
+let installed = false;
+
+/// A mod root as the hooks see its files: Node resolves a module to where it
+/// really is, so a root reached through a link is also known by that.
+function rootUrls(root) {
+  const given = path.resolve(root);
+  let real = given;
+  try {
+    real = realpathSync(given);
+  } catch {
+    // Not there (yet): only the path as given can name its files.
+  }
+  return [...new Set([given, real])].map((dir) => {
+    const url = pathToFileURL(dir).href;
+    return url.endsWith('/') ? url : `${url}/`;
+  });
+}
+
+/// Says that files under `root` are a mod's, so the hooks answer for them.
+export function registerModRoot(root) {
+  for (const url of rootUrls(root)) roots.add(url);
+  install();
+}
+
+export function unregisterModRoot(root) {
+  for (const url of rootUrls(root)) roots.delete(url);
+}
+
+function underModRoot(url) {
+  for (const root of roots) if (url.startsWith(root)) return true;
+  return false;
+}
+
+/// Whether `source` holds TypeScript syntax the stripper has to remove.
+function needsTypeStrip(extension) {
+  return extension === '.ts' || extension === '.tsx' || extension === '.mts' || extension === '.cts';
+}
+
+/// Turns one mod file into the JavaScript module Node evaluates.
+export function transpileModSource(source, filename) {
+  const extension = path.extname(filename);
+  let code = source;
+  if (extension === '.tsx' || extension === '.jsx') code = transformJsx(code);
+  if (needsTypeStrip(extension)) {
+    code = stripTypeScriptTypes(code, { mode: 'transform', sourceUrl: pathToFileURL(filename).href });
+  }
+  return code;
+}
+
+function install() {
+  if (installed) return;
+  installed = true;
+  // `stripTypeScriptTypes` announces itself as experimental once per process
+  // on stderr, where the host expects one JSON diagnostic per line. The
+  // warning is known and the API is pinned by this package's tests; keep it
+  // off the host's diagnostics stream.
+  const emitWarning = process.emitWarning;
+  process.emitWarning = function filtered(warning, ...rest) {
+    if (String(warning?.message ?? warning).includes('stripTypeScriptTypes')) return undefined;
+    return emitWarning.call(process, warning, ...rest);
+  };
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      const parent = context.parentURL ?? '';
+      if (specifier === CLAUDE_CODE_SPECIFIER && underModRoot(parent)) {
+        return { url: SHIM_URL, format: 'module', shortCircuit: true };
+      }
+      if (underModRoot(parent) && (specifier.startsWith('./') || specifier.startsWith('../'))) {
+        const url = new URL(specifier, parent).href;
+        if (!underModRoot(url)) {
+          throw new Error(`[PATH_ESCAPES] ${specifier} resolves outside the mod's folder`);
+        }
+        const resolved = resolveModFile(fileURLToPath(url));
+        if (resolved === null) {
+          const extension = path.extname(fileURLToPath(url));
+          if (MOD_EXTENSIONS.includes(extension)) return nextResolve(specifier, context); // not there: Node says so
+          throw new Error(`[NOT_A_MOD_FILE] ${specifier} is not named .ts, .tsx, .jsx, .js, .mjs, .cjs, .mts or .cts, and no such file with one exists`);
+        }
+        const target = pathToFileURL(resolved).href;
+        if (!underModRoot(target)) {
+          throw new Error(`[PATH_ESCAPES] ${specifier} resolves outside the mod's folder`);
+        }
+        return { url: target, format: 'module', shortCircuit: true };
+      }
+      return nextResolve(specifier, context);
+    },
+    load(url, context, nextLoad) {
+      if (!underModRoot(url)) return nextLoad(url, context);
+      const filename = fileURLToPath(url);
+      const extension = path.extname(filename);
+      if (!MOD_EXTENSIONS.includes(extension)) return nextLoad(url, context);
+      // Read directly rather than through `nextLoad`: the default loader
+      // decides a `.ts` or `.cjs` file's format from its name, and the rule
+      // here is that a mod's file is an ES module whatever it is named.
+      const source = readFileSync(filename, 'utf8');
+      return { format: 'module', source: transpileModSource(source, filename), shortCircuit: true };
+    },
+  });
+}

package/bin/plugin-host/src/cli.mjs

@@ -143,5 +143,18 @@ if (import.meta.url === pathToFileURL(process.argv[1]).href) {
     process.exitCode = await runHost({
       input: process.stdin, output: process.stdout, error: process.stderr, loader,
     });
+    // Once the host returns there is nobody left to serve: rebon shut it
+    // down, or rebon is gone and stdin ended. A plugin's timer or open handle
+    // must not keep the process alive past that — it would outlive rebon as
+    // an orphan holding whatever the plugin opened. What was already written
+    // is flushed first; a stream that cannot flush does not hold the exit.
+    const flushed = (stream) => new Promise((resolve) => {
+      if (stream.destroyed || !stream.writable) return resolve();
+      stream.once('error', () => resolve());
+      try { stream.write('', () => resolve()); } catch { resolve(); }
+    });
+    const grace = new Promise((resolve) => setTimeout(resolve, 1000).unref());
+    await Promise.race([Promise.all([flushed(process.stdout), flushed(process.stderr)]), grace]);
+    process.exit();
   }
 }