@rebon/cli-darwin-arm64 0.17.2 → 0.18.0

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

@@ -0,0 +1,196 @@
+import { ProtocolError, RawJsonNumber, validateEnvelope } from './protocol.mjs';
+
+class RawNumber {
+  constructor(raw) { this.raw = raw; Object.freeze(this); }
+}
+
+class JsonParser {
+  constructor(text) { this.text = text; this.index = 0; }
+  parse() {
+    this.#space();
+    const value = this.#value('envelope');
+    this.#space();
+    if (this.index !== this.text.length) this.#error('trailing_json', 'trailing data after JSON value');
+    return value;
+  }
+  #value(role = 'value') {
+    const c = this.text[this.index];
+    if (c === '{') return this.#object(role);
+    if (c === '[') return this.#array();
+    if (c === '"') return this.#string();
+    if (c === 't') return this.#literal('true', true);
+    if (c === 'f') return this.#literal('false', false);
+    if (c === 'n') return this.#literal('null', null);
+    if (c === '-' || (c >= '0' && c <= '9')) return this.#number();
+    this.#error('malformed_json', 'expected a JSON value');
+  }
+  #object(role) {
+    this.index++;
+    const object = Object.create(null);
+    const keys = new Set();
+    this.#space();
+    if (this.text[this.index] === '}') { this.index++; return object; }
+    for (;;) {
+      if (this.text[this.index] !== '"') this.#error('malformed_json', 'object key must be a string');
+      const key = this.#string();
+      this.#space();
+      if (this.text[this.index++] !== ':') this.#error('malformed_json', 'expected colon after object key');
+      this.#space();
+      const childRole = role === 'envelope' && key === 'message' ? 'message' : 'value';
+      const value = this.#value(childRole);
+      if ((role === 'envelope' || role === 'message') && keys.has(key)) {
+        this.#error('duplicate_field', `duplicate field in ${role}`);
+      }
+      keys.add(key);
+      object[key] = value; // serde_json::Value uses the last value for opaque object duplicates.
+      this.#space();
+      const delimiter = this.text[this.index++];
+      if (delimiter === '}') return object;
+      if (delimiter !== ',') this.#error('malformed_json', 'expected comma or object end');
+      this.#space();
+    }
+  }
+  #array() {
+    this.index++;
+    const array = [];
+    this.#space();
+    if (this.text[this.index] === ']') { this.index++; return array; }
+    for (;;) {
+      array.push(this.#value());
+      this.#space();
+      const delimiter = this.text[this.index++];
+      if (delimiter === ']') return array;
+      if (delimiter !== ',') this.#error('malformed_json', 'expected comma or array end');
+      this.#space();
+    }
+  }
+  #string() {
+    this.index++;
+    let result = '';
+    for (;;) {
+      if (this.index >= this.text.length) this.#error('malformed_json', 'unterminated JSON string');
+      const c = this.text[this.index++];
+      if (c === '"') return result;
+      if (c === '\\') {
+        if (this.index >= this.text.length) this.#error('malformed_json', 'unterminated JSON escape');
+        const escape = this.text[this.index++];
+        const simple = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' }[escape];
+        if (simple !== undefined) { result += simple; continue; }
+        if (escape !== 'u') this.#error('malformed_json', 'invalid JSON escape');
+        const first = this.#hexUnit();
+        if (first >= 0xd800 && first <= 0xdbff) {
+          if (this.text.slice(this.index, this.index + 2) !== '\\u') this.#error('invalid_surrogate', 'lone high surrogate in JSON string');
+          this.index += 2;
+          const second = this.#hexUnit();
+          if (second < 0xdc00 || second > 0xdfff) this.#error('invalid_surrogate', 'invalid surrogate pair in JSON string');
+          result += String.fromCodePoint(0x10000 + ((first - 0xd800) << 10) + second - 0xdc00);
+        } else if (first >= 0xdc00 && first <= 0xdfff) {
+          this.#error('invalid_surrogate', 'lone low surrogate in JSON string');
+        } else result += String.fromCharCode(first);
+        continue;
+      }
+      if (c.charCodeAt(0) < 0x20) this.#error('malformed_json', 'unescaped control character in JSON string');
+      if (c.charCodeAt(0) >= 0xd800 && c.charCodeAt(0) <= 0xdfff) this.#error('invalid_surrogate', 'lone surrogate in JSON string');
+      result += c;
+    }
+  }
+  #hexUnit() {
+    const token = this.text.slice(this.index, this.index + 4);
+    if (!/^[0-9a-fA-F]{4}$/.test(token)) this.#error('malformed_json', 'invalid unicode escape');
+    this.index += 4;
+    return Number.parseInt(token, 16);
+  }
+  #number() {
+    const start = this.index;
+    if (this.text[this.index] === '-') this.index++;
+    if (this.text[this.index] === '0') this.index++;
+    else {
+      if (this.text[this.index] < '1' || this.text[this.index] > '9') this.#error('malformed_json', 'invalid JSON number');
+      while (this.text[this.index] >= '0' && this.text[this.index] <= '9') this.index++;
+    }
+    if (this.text[this.index] === '.') {
+      this.index++;
+      const fraction = this.index;
+      while (this.text[this.index] >= '0' && this.text[this.index] <= '9') this.index++;
+      if (fraction === this.index) this.#error('malformed_json', 'fraction requires digits');
+    }
+    if (this.text[this.index] === 'e' || this.text[this.index] === 'E') {
+      this.index++;
+      if (this.text[this.index] === '+' || this.text[this.index] === '-') this.index++;
+      const exponent = this.index;
+      while (this.text[this.index] >= '0' && this.text[this.index] <= '9') this.index++;
+      if (exponent === this.index) this.#error('malformed_json', 'exponent requires digits');
+    }
+    return new RawNumber(this.text.slice(start, this.index));
+  }
+  #literal(token, value) {
+    if (this.text.slice(this.index, this.index + token.length) !== token) this.#error('malformed_json', 'invalid JSON literal');
+    this.index += token.length;
+    return value;
+  }
+  #space() { while (' \t\r\n'.includes(this.text[this.index] ?? '\0')) this.index++; }
+  #error(code, message) { throw new ProtocolError(code, message); }
+}
+
+function exponentValue(raw) {
+  const marker = Math.max(raw.indexOf('e'), raw.indexOf('E'));
+  if (marker < 0) return 0;
+  let value = raw.slice(marker + 1);
+  let sign = 1;
+  if (value[0] === '+' || value[0] === '-') { if (value[0] === '-') sign = -1; value = value.slice(1); }
+  value = value.replace(/^0+/, '') || '0';
+  if (value.length > 9) return sign * Infinity;
+  return sign * Number(value);
+}
+
+export function parseSafeIntegerToken(raw, field) {
+  const negative = raw[0] === '-';
+  const unsigned = negative ? raw.slice(1) : raw;
+  const marker = Math.max(unsigned.indexOf('e'), unsigned.indexOf('E'));
+  const mantissa = marker < 0 ? unsigned : unsigned.slice(0, marker);
+  const dot = mantissa.indexOf('.');
+  const fractionLength = dot < 0 ? 0 : mantissa.length - dot - 1;
+  let digits = (dot < 0 ? mantissa : mantissa.slice(0, dot) + mantissa.slice(dot + 1)).replace(/^0+/, '');
+  if (!digits) return 0;
+  if (negative) throw new ProtocolError('unsafe_integer', `${field} must be a safe non-negative integer`);
+  const scale = exponentValue(unsigned) - fractionLength;
+  if (!Number.isFinite(scale)) throw new ProtocolError('unsafe_integer', `${field} must be a safe non-negative integer`);
+  if (scale < 0) {
+    const remove = -scale;
+    if (remove > digits.length || !digits.endsWith('0'.repeat(remove))) throw new ProtocolError('unsafe_integer', `${field} must be an exact integer`);
+    digits = digits.slice(0, digits.length - remove).replace(/^0+/, '') || '0';
+  } else {
+    if (digits.length + scale > 16) throw new ProtocolError('unsafe_integer', `${field} must be a safe non-negative integer`);
+    digits += '0'.repeat(scale);
+  }
+  if (digits.length > 16 || (digits.length === 16 && digits > '9007199254740991')) {
+    throw new ProtocolError('unsafe_integer', `${field} must be a safe non-negative integer`);
+  }
+  return Number(digits);
+}
+
+function materialize(value) {
+  if (value instanceof RawNumber) {
+    const number = Number(value.raw);
+    if (/^-?(?:0|[1-9][0-9]*)$/.test(value.raw) && Number.isSafeInteger(number)) return Object.is(number, -0) ? 0 : number;
+    return new RawJsonNumber(value.raw);
+  }
+  if (Array.isArray(value)) return value.map(materialize);
+  if (value && typeof value === 'object') for (const key of Object.keys(value)) value[key] = materialize(value[key]);
+  return value;
+}
+
+export function parseEnvelopeJson(text) {
+  const value = new JsonParser(text).parse();
+  if (!value || value instanceof RawNumber || Array.isArray(value) || typeof value !== 'object') throw new ProtocolError('wrong_shape', 'envelope must be an object');
+  if (!(value.protocol_version instanceof RawNumber) || value.protocol_version.raw !== '1') {
+    throw new ProtocolError('bad_version', 'protocol_version must be integer token 1');
+  }
+  value.protocol_version = 1;
+  for (const field of ['host_epoch', 'scope_generation']) {
+    if (!(value[field] instanceof RawNumber)) throw new ProtocolError('unsafe_integer', `${field} must be a JSON number`);
+    value[field] = parseSafeIntegerToken(value[field].raw, field);
+  }
+  value.message = materialize(value.message);
+  return validateEnvelope(value);
+}

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

@@ -0,0 +1,114 @@
+import { ProtocolError, identityOf } from './protocol.mjs';
+
+const scopeKey = (pluginId, scopeId) => JSON.stringify([pluginId, scopeId]);
+const key = (identity) => scopeKey(identity.plugin_id, identity.scope_id);
+const same = (a, b) => ['host_epoch','plugin_id','scope_id','scope_generation','call_id'].every((field) => a[field] === b[field]);
+
+export class CallLedger {
+  #scopes = new Map(); #calls = new Map();
+  constructor(hostEpoch) {
+    if (!Number.isSafeInteger(hostEpoch) || hostEpoch < 0) throw new ProtocolError('unsafe_integer', 'host_epoch is invalid');
+    this.hostEpoch = Object.is(hostEpoch, -0) ? 0 : hostEpoch;
+  }
+  scopeGeneration(pluginId, scopeId) { return this.#scopes.get(scopeKey(pluginId, scopeId)); }
+  advanceScope(pluginId, scopeId, generation, open = true) {
+    if (!Number.isSafeInteger(generation) || generation < 0) throw new ProtocolError('unsafe_integer', 'scope_generation is invalid');
+    const key = scopeKey(pluginId, scopeId);
+    const current = this.#scopes.get(key);
+    if (current && generation < current.generation) throw new ProtocolError('scope_generation_regression', 'scope generation regressed');
+    if (current && generation === current.generation) {
+      if (open && current.open) return 'idempotent';
+      if (!open && !current.open) return 'idempotent';
+      current.open = open;
+      return 'updated';
+    }
+    this.#scopes.set(key, { generation, open });
+    return current ? 'advanced' : 'established';
+  }
+  closeScope(pluginId, scopeId, generation) {
+    const current = this.#scopes.get(scopeKey(pluginId, scopeId));
+    if (!current) throw new ProtocolError('unknown_scope', 'scope is not registered');
+    if (generation < current.generation) throw new ProtocolError('scope_generation_regression', 'scope generation regressed');
+    if (generation === current.generation && current.open) throw new ProtocolError('scope_close_not_advanced', 'scope close must carry an advanced generation');
+    return this.advanceScope(pluginId, scopeId, generation, false);
+  }
+  register(identity, direction, owner) {
+    if (direction !== 'inbound' && direction !== 'outbound') throw new ProtocolError('bad_direction', 'call direction is invalid');
+    if (direction === 'inbound') this.#classifyEpoch(identity, true);
+    else this.#classify(identity, true);
+    if (this.#calls.has(identity.call_id)) throw new ProtocolError('call_id_reused', 'call_id is globally unique within an epoch');
+    this.#calls.set(identity.call_id, Object.freeze({ identity: identityOf(identity), direction, owner, terminal: null, registered: true }));
+  }
+  retire(identity) {
+    const current = this.#calls.get(identity.call_id);
+    if (!current || !current.registered) throw new ProtocolError('unknown_call', 'call is not registered');
+    if (!same(current.identity, identity)) throw new ProtocolError('identity_mismatch', 'full call identity does not match');
+    if (current.terminal) throw new ProtocolError('already_terminal', 'terminal call cannot be aborted');
+    this.#calls.set(identity.call_id, Object.freeze({ ...current, registered: false }));
+  }
+  terminal(envelope, direction) {
+    if (direction !== 'inbound' && direction !== 'outbound') throw new ProtocolError('bad_direction', 'terminal direction is invalid');
+    const epochStale = this.#classifyEpoch(envelope, false); if (epochStale) return { stale: epochStale };
+    const current = this.#calls.get(envelope.call_id);
+    if (current && (current.identity.plugin_id !== envelope.plugin_id || current.identity.scope_id !== envelope.scope_id))
+      throw new ProtocolError('identity_mismatch', 'plugin_id or scope_id does not match');
+    const scopeStale = direction === 'outbound' ? this.#classifyScope(envelope, false) : null; if (scopeStale) return { stale: scopeStale };
+    if (!current || !current.registered) throw new ProtocolError('unknown_call', 'call is not registered');
+    if (current.direction !== direction) throw new ProtocolError('direction_mismatch', `call belongs to ${current.direction} direction`);
+    if (!same(current.identity, envelope)) throw new ProtocolError('identity_mismatch', 'full call identity does not match');
+    if (envelope.message.type !== 'terminal') throw new ProtocolError('not_terminal', 'message is not terminal');
+    if (current.terminal) throw new ProtocolError('duplicate_terminal', `terminal already committed as ${current.terminal}`);
+    this.#calls.set(envelope.call_id, Object.freeze({ ...current, terminal: envelope.message.status }));
+    return { committed: envelope.message.status, owner: current.owner };
+  }
+  /// Validates one chunk of a call's answer. Chunks are checked, not recorded:
+  /// a stream of a million of them must not grow the ledger.
+  ///
+  /// The boundary is what the ledger owns — **a chunk after the terminal is an
+  /// error**, not a late arrival to drop. A duplicate terminal is a race two
+  /// peers can legitimately lose; a chunk after the end means the producer kept
+  /// emitting after saying it was done.
+  chunk(envelope, direction) {
+    if (direction !== 'inbound' && direction !== 'outbound') throw new ProtocolError('bad_direction', 'chunk direction is invalid');
+    const epochStale = this.#classifyEpoch(envelope, false); if (epochStale) return { stale: epochStale };
+    const current = this.#calls.get(envelope.call_id);
+    if (current && (current.identity.plugin_id !== envelope.plugin_id || current.identity.scope_id !== envelope.scope_id))
+      throw new ProtocolError('identity_mismatch', 'plugin_id or scope_id does not match');
+    const scopeStale = this.#classifyScope(envelope, false); if (scopeStale) return { stale: scopeStale };
+    if (!current || !current.registered) throw new ProtocolError('unknown_call', 'call is not registered');
+    if (current.direction !== direction) throw new ProtocolError('direction_mismatch', `call belongs to ${current.direction} direction`);
+    if (!same(current.identity, envelope)) throw new ProtocolError('identity_mismatch', 'full call identity does not match');
+    if (envelope.message.type !== 'chunk') throw new ProtocolError('not_chunk', 'message is not a chunk');
+    if (current.terminal) throw new ProtocolError('chunk_after_terminal', `call already ended as ${current.terminal}`);
+    return { accepted: true };
+  }
+  cancel(envelope) {
+    const epochStale = this.#classifyEpoch(envelope, false); if (epochStale) return { stale: epochStale };
+    const current = this.#calls.get(envelope.call_id);
+    if (current && (current.identity.plugin_id !== envelope.plugin_id || current.identity.scope_id !== envelope.scope_id))
+      throw new ProtocolError('identity_mismatch', 'plugin_id or scope_id does not match');
+    const scopeStale = this.#classifyScope(envelope, false); if (scopeStale) return { stale: scopeStale };
+    if (!current || !current.registered) throw new ProtocolError('unknown_call', 'call is not registered');
+    if (!same(current.identity, envelope)) throw new ProtocolError('identity_mismatch', 'full call identity does not match');
+    if (envelope.message.type !== 'notification' || envelope.message.method !== 'call/cancel' || envelope.message.payload !== null)
+      throw new ProtocolError('not_cancel', 'message is not an exact cancel intent');
+    return { accepted: true };
+  }
+  #classify(identity, registration) {
+    const epochStale = this.#classifyEpoch(identity, registration); if (epochStale) return epochStale;
+    return this.#classifyScope(identity, registration);
+  }
+  #classifyEpoch(identity, registration) {
+    if (identity.host_epoch < this.hostEpoch) return registration ? (() => { throw new ProtocolError('stale_identity', 'old host epoch'); })() : 'host_epoch';
+    if (identity.host_epoch > this.hostEpoch) throw new ProtocolError('future_host_epoch', 'future host epoch');
+    return null;
+  }
+  #classifyScope(identity, registration) {
+    const scope = this.#scopes.get(key(identity));
+    if (!scope) throw new ProtocolError('unknown_scope', 'scope is not registered');
+    if (identity.scope_generation < scope.generation) return registration ? (() => { throw new ProtocolError('stale_identity', 'old scope generation'); })() : 'scope_generation';
+    if (identity.scope_generation > scope.generation) throw new ProtocolError('future_scope_generation', 'future scope generation');
+    if (registration && !scope.open) throw new ProtocolError('scope_closed', 'scope is closed to admission');
+    return null;
+  }
+}

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

@@ -0,0 +1,142 @@
+// Turning a `plugin/load` request into a loaded plugin.
+//
+// The registrar is the only thing a plugin's code is handed, and it enforces
+// the same rule the Rust registry does from the other side: a plugin may
+// register a service or a topic only if its manifest declared one. Checking it
+// here as well is not redundancy for its own sake — it means the refusal names
+// the plugin's own line rather than arriving as a rejected ready report after
+// the module has already run and had its side effects.
+//
+// Registration closes when the entry module's `activate` returns. A plugin that
+// registers later would be adding capabilities the host already reported as the
+// complete set, and nothing downstream would know.
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ProtocolError } from './protocol.mjs';
+import { pluginToolDefinition, validateName } from './methods.mjs';
+
+/// Resolves an entry against its package root and refuses anything outside it.
+///
+/// The payload validator already rejects `..`, absolute entries, and
+/// backslashes; this is the check that survives a symlink or a root that is
+/// itself a relative-looking string, because it asks the filesystem's own
+/// resolver rather than the text.
+export function resolveEntry(root, entry) {
+  const base = path.resolve(root);
+  const resolved = path.resolve(base, entry);
+  const inside = resolved === base || resolved.startsWith(base + path.sep);
+  if (!inside) throw new ProtocolError('[PATH_ESCAPES]', `entry ${entry} resolves outside the package root`);
+  return pathToFileURL(resolved).href;
+}
+
+class Registrar {
+  #declaredServices; #declaredTopics; #declaredProviders; #declaredTools;
+  #services = new Map(); #topics = new Map(); #adapters = new Map();
+  #tools = new Map(); #toolHandlers = new Map(); #scopes = []; #sealed = false;
+  constructor(declaredServices, declaredTopics, declaredProviders, declaredTools) {
+    this.#declaredServices = new Set(declaredServices);
+    this.#declaredTopics = new Set(declaredTopics);
+    this.#declaredProviders = new Set(declaredProviders);
+    this.#declaredTools = new Set(declaredTools);
+  }
+
+  /// A tool differs from a service in one way that matters: it has to be
+  /// *offered* to a model, so it cannot be registered by name alone. The
+  /// manifest still declares only the name — description and schema are how a
+  /// tool describes itself, not what it is permitted to be.
+  #admitTool(definition, handler) {
+    if (this.#sealed) throw new ProtocolError('[REGISTRATION_CLOSED]', 'a tool was registered after activation finished');
+    const tool = pluginToolDefinition(definition);
+    if (typeof handler !== 'function') throw new ProtocolError('[WRONG_SHAPE]', `tool ${JSON.stringify(tool.name)} needs a function`);
+    if (!this.#declaredTools.has(tool.name)) throw new ProtocolError('[UNAUTHORIZED_REGISTER]', `tool ${JSON.stringify(tool.name)} is not declared by this plugin's manifest`);
+    if (this.#tools.has(tool.name)) throw new ProtocolError('[DUPLICATE_DECLARATION]', `tool ${JSON.stringify(tool.name)} is registered twice`);
+    this.#tools.set(tool.name, tool);
+    this.#toolHandlers.set(tool.name, handler);
+  }
+
+  #admit(kind, name, handler, declared, into) {
+    if (this.#sealed) throw new ProtocolError('[REGISTRATION_CLOSED]', `${kind} ${JSON.stringify(name)} was registered after activation finished`);
+    validateName(kind, name);
+    if (typeof handler !== 'function') throw new ProtocolError('[WRONG_SHAPE]', `${kind} ${JSON.stringify(name)} needs a function`);
+    if (!declared.has(name)) throw new ProtocolError('[UNAUTHORIZED_REGISTER]', `${kind} ${JSON.stringify(name)} is not declared by this plugin's manifest`);
+    if (into.has(name)) throw new ProtocolError('[DUPLICATE_DECLARATION]', `${kind} ${JSON.stringify(name)} is registered twice`);
+    into.set(name, handler);
+  }
+
+  /// The surface a plugin's `activate` receives. Frozen, and holding no
+  /// reference back to the host: at activation a plugin registers, it does not
+  /// reach.
+  ///
+  /// Reaching happens later and only from inside a handler, which is called as
+  /// `handler(request, ctx)`. That `ctx` is bound to the scope incarnation the
+  /// call arrived on and carries `invoke(tool, input)` — so a plugin can act on
+  /// the session it was called for and has no way to name another.
+  api() {
+    return Object.freeze({
+      service: (name, handler) => this.#admit('service', name, handler, this.#declaredServices, this.#services),
+      topic: (name, handler) => this.#admit('topic', name, handler, this.#declaredTopics, this.#topics),
+      // An llm adapter is a service under a different routing key: declared in
+      // the manifest, registered here, and answered with chunks instead of one
+      // value.
+      llm: (provider, adapter) => this.#admit('provider', provider, adapter, this.#declaredProviders, this.#adapters),
+      tool: (definition, handler) => this.#admitTool(definition, handler),
+      // Not a capability, so nothing to declare: everything a scope handle can
+      // do is gated by the declarations above. What it is, is a lifetime — the
+      // session, rather than one call inside it. A plugin that produces facts
+      // on its own schedule (an agent loop, a watcher) has no inbound call to
+      // hang them on, and requiring one would mean it could only speak when
+      // spoken to.
+      scope: (handler) => {
+        if (this.#sealed) throw new ProtocolError('[REGISTRATION_CLOSED]', 'a scope handler was registered after activation finished');
+        if (typeof handler !== 'function') throw new ProtocolError('[WRONG_SHAPE]', 'a scope handler must be a function');
+        this.#scopes.push(handler);
+      },
+    });
+  }
+
+  seal() {
+    this.#sealed = true;
+    return Object.freeze({
+      services: Object.freeze([...this.#services.keys()]),
+      eventTopics: Object.freeze([...this.#topics.keys()]),
+      llmProviders: Object.freeze([...this.#adapters.keys()]),
+      tools: Object.freeze([...this.#tools.values()]),
+      serviceHandlers: this.#services,
+      topicHandlers: this.#topics,
+      llmAdapters: this.#adapters,
+      toolHandlers: this.#toolHandlers,
+      scopeHandlers: Object.freeze([...this.#scopes]),
+    });
+  }
+}
+
+/// Imports a plugin and collects what it registered.
+///
+/// `activate` is called as `activate(api, config)`: the package says what the
+/// plugin can do, the load request's `config` says what this installation wants
+/// it to do. The second argument is opaque here — reading it is the plugin's
+/// business, and validating it is the plugin's job rather than the wire's.
+///
+/// `importModule` is injectable so the loader's rules can be tested without a
+/// file on disk for every case.
+export async function loadPlugin(request, importModule = (url) => import(url)) {
+  const url = resolveEntry(request.root, request.entry);
+  let module;
+  try {
+    module = await importModule(url);
+  } catch (cause) {
+    throw new ProtocolError('[ENTRY_FAILED]', `plugin entry ${request.entry} failed to load: ${cause?.message ?? cause}`);
+  }
+  const activate = module?.activate ?? module?.default;
+  if (typeof activate !== 'function') {
+    throw new ProtocolError('[NO_ACTIVATE]', `plugin entry ${request.entry} exports no activate function`);
+  }
+  const registrar = new Registrar(request.services, request.eventTopics, request.llmProviders, request.tools);
+  try {
+    await activate(registrar.api(), request.config);
+  } catch (cause) {
+    if (cause instanceof ProtocolError) throw cause;
+    throw new ProtocolError('[ACTIVATE_FAILED]', `plugin activation failed: ${cause?.message ?? cause}`);
+  }
+  return registrar.seal();
+}