@rebon/cli-linux-x64 0.17.3 → 0.18.0

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

@@ -0,0 +1,256 @@
+// Payload schemas for the methods that carry one. Mirrors
+// `crates/rebon-plugin-protocol/src/methods.rs`; the shared corpus at
+// `crates/rebon-plugin-protocol/tests/fixtures/v1/methods.json` is what keeps
+// the two honest. Codes are the bracketed tokens that corpus pins, which is a
+// different vocabulary from `protocol.mjs`'s framing codes on purpose: they
+// answer different questions and are pinned by different corpora.
+//
+// Validation order is part of the contract. A payload with two problems reports
+// the first one in declaration order, and both languages must pick the same one.
+import { ProtocolError, PLATFORM_PLUGIN_ID, plain } from './protocol.mjs';
+
+export const PLUGIN_LOAD_METHOD = 'plugin/load';
+export const PLUGIN_UNLOAD_METHOD = 'plugin/unload';
+export const SERVICE_CALL_METHOD = 'service/call';
+export const EVENT_DELIVER_METHOD = 'event/deliver';
+export const EVENT_SUBSCRIBE_METHOD = 'event/subscribe';
+export const EVENT_UNSUBSCRIBE_METHOD = 'event/unsubscribe';
+export const EVENT_EMIT_METHOD = 'event/emit';
+export const TOOL_INVOKE_METHOD = 'tool/invoke';
+export const LLM_STREAM_METHOD = 'llm/stream';
+export const TOOL_CALL_METHOD = 'tool/call';
+export const SEAT_CALL_METHOD = 'seat/call';
+
+export const MAX_NAME_BYTES = 128;
+export const MAX_DECLARATIONS = 256;
+// A tool description is read by a model, so it is spent out of every turn's
+// context budget for as long as the tool is offered. The bound is part of the
+// contract, not a defensive habit.
+export const MAX_DESCRIPTION_BYTES = 4096;
+
+// Rust bounds a name by its UTF-8 byte length. Measuring UTF-16 units here
+// would accept names Rust rejects, which is exactly the kind of drift a plugin
+// author discovers only on the other host.
+const byteLength = (value) => Buffer.byteLength(value, 'utf8');
+// `\p{Cc}` is the Unicode category Rust's `char::is_control` tests.
+const CONTROL = /\p{Cc}/u;
+
+function shape(value, required, optional, where) {
+  if (!plain(value)) throw new ProtocolError('[WRONG_SHAPE]', `${where} must be a plain object`);
+  const known = new Set([...required, ...optional]);
+  for (const key of Object.keys(value)) {
+    if (!known.has(key)) throw new ProtocolError('[UNKNOWN_FIELD]', `${where} has unknown field ${JSON.stringify(key)}`);
+  }
+  for (const key of required) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      throw new ProtocolError('[MISSING_FIELD]', `${where} is missing field ${JSON.stringify(key)}`);
+    }
+  }
+}
+
+function string(value, where) {
+  if (typeof value !== 'string') throw new ProtocolError('[WRONG_SHAPE]', `${where} must be a string`);
+  return value;
+}
+
+export function validateName(kind, name) {
+  if (name.length === 0) throw new ProtocolError('[EMPTY_NAME]', `${kind} name must not be empty`);
+  if (byteLength(name) > MAX_NAME_BYTES) throw new ProtocolError('[NAME_TOO_LONG]', `${kind} name is longer than ${MAX_NAME_BYTES} bytes`);
+  if (CONTROL.test(name)) throw new ProtocolError('[CONTROL_CHARACTER]', `${kind} name contains a control character`);
+  return name;
+}
+
+export const MAX_PATH_BYTES = 4096;
+
+// `path.isAbsolute` answers for the platform it runs on, which is right for
+// using a path and wrong for agreeing about one: this rule is read by both
+// languages on whichever machine runs CI. A supervisor and its host always run
+// on the same machine, so both spellings count.
+const looksAbsolute = (value) => /^[/\\]/.test(value) || /^[A-Za-z]:[/\\]/.test(value);
+
+function pathShape(kind, value) {
+  if (value.length === 0) throw new ProtocolError('[EMPTY_NAME]', `${kind} path must not be empty`);
+  if (byteLength(value) > MAX_PATH_BYTES) throw new ProtocolError('[PATH_TOO_LONG]', `${kind} path is longer than ${MAX_PATH_BYTES} bytes`);
+  if (CONTROL.test(value)) throw new ProtocolError('[CONTROL_CHARACTER]', `${kind} path contains a control character`);
+  return value;
+}
+
+export function validateAbsolutePath(kind, value) {
+  pathShape(kind, value);
+  if (!looksAbsolute(value)) throw new ProtocolError('[PATH_NOT_ABSOLUTE]', `${kind} path must be absolute`);
+  return value;
+}
+
+export function validateRelativePath(kind, value) {
+  pathShape(kind, value);
+  if (looksAbsolute(value)) throw new ProtocolError('[PATH_NOT_RELATIVE]', `${kind} path must be relative to the package root`);
+  if (value.includes('\\') || value.split('/').some((part) => part === '..' || part === '')) {
+    throw new ProtocolError('[PATH_ESCAPES]', `${kind} path leaves the package root`);
+  }
+  return value;
+}
+
+export function validatePluginId(pluginId) {
+  validateName('plugin', pluginId);
+  if (pluginId === PLATFORM_PLUGIN_ID) throw new ProtocolError('[RESERVED_PLUGIN_ID]', `plugin id ${PLATFORM_PLUGIN_ID} is reserved for platform control traffic`);
+  return pluginId;
+}
+
+// Absent lists default to empty, matching serde's `#[serde(default)]`. The
+// length bound is checked before the entries, and each entry's own validity
+// before the duplicate check — same order as Rust.
+function declarations(value, kind, where) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new ProtocolError('[WRONG_SHAPE]', `${where} must be an array`);
+  if (value.length > MAX_DECLARATIONS) throw new ProtocolError('[TOO_MANY_DECLARATIONS]', `${where} declares ${value.length} entries, over the ${MAX_DECLARATIONS} limit`);
+  const seen = new Set();
+  for (const entry of value) {
+    validateName(kind, string(entry, `${where} entry`));
+    if (seen.has(entry)) throw new ProtocolError('[DUPLICATE_DECLARATION]', `${where} declares ${JSON.stringify(entry)} twice`);
+    seen.add(entry);
+  }
+  return Object.freeze([...value]);
+}
+
+export function pluginLoadRequest(input) {
+  shape(input, ['pluginId', 'root', 'entry'], ['services', 'eventTopics', 'publishedTopics', 'llmProviders', 'tools', 'invokableTools', 'seats', 'config'], 'plugin/load payload');
+  return Object.freeze({
+    pluginId: validatePluginId(string(input.pluginId, 'pluginId')),
+    root: validateAbsolutePath('root', string(input.root, 'root')),
+    entry: validateRelativePath('entry', string(input.entry, 'entry')),
+    services: declarations(input.services, 'service', 'services'),
+    eventTopics: declarations(input.eventTopics, 'topic', 'eventTopics'),
+    // What it may publish, as opposed to what it listens to. Two powers, two
+    // lists — the same separation `tools` and `invokableTools` keep.
+    publishedTopics: declarations(input.publishedTopics, 'topic', 'publishedTopics'),
+    llmProviders: declarations(input.llmProviders, 'provider', 'llmProviders'),
+    tools: declarations(input.tools, 'tool', 'tools'),
+    // The one declared list with no registered counterpart: a plugin calls
+    // these rather than providing them, which is why its name says so.
+    invokableTools: declarations(input.invokableTools, 'tool', 'invokableTools'),
+    seats: declarations(input.seats, 'seat', 'seats'),
+    // Opaque: what a plugin's configuration means is the plugin's contract, and
+    // an absent one is `null` rather than a missing field — the same rule every
+    // other payload slot follows.
+    config: input.config === undefined ? null : input.config,
+  });
+}
+
+export function pluginToolDefinition(input) {
+  shape(input, ['name', 'description', 'inputSchema'], [], 'tool definition');
+  const name = validateName('tool', string(input.name, 'name'));
+  const description = string(input.description, 'description');
+  if (description.length === 0) throw new ProtocolError('[EMPTY_DESCRIPTION]', `tool ${JSON.stringify(name)} has no description, so a model cannot know when to use it`);
+  if (byteLength(description) > MAX_DESCRIPTION_BYTES) throw new ProtocolError('[DESCRIPTION_TOO_LONG]', `tool ${JSON.stringify(name)} has a description over the ${MAX_DESCRIPTION_BYTES} byte limit`);
+  return Object.freeze({ name, description, inputSchema: input.inputSchema });
+}
+
+function toolDefinitions(value, where) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new ProtocolError('[WRONG_SHAPE]', `${where} must be an array`);
+  if (value.length > MAX_DECLARATIONS) throw new ProtocolError('[TOO_MANY_DECLARATIONS]', `${where} declares ${value.length} entries, over the ${MAX_DECLARATIONS} limit`);
+  const seen = new Set();
+  const out = [];
+  for (const entry of value) {
+    const tool = pluginToolDefinition(entry);
+    if (seen.has(tool.name)) throw new ProtocolError('[DUPLICATE_DECLARATION]', `${where} declares ${JSON.stringify(tool.name)} twice`);
+    seen.add(tool.name);
+    out.push(tool);
+  }
+  return Object.freeze(out);
+}
+
+export function pluginReadyReport(input) {
+  shape(input, ['pluginId'], ['services', 'eventTopics', 'llmProviders', 'tools'], 'plugin/load terminal payload');
+  return Object.freeze({
+    pluginId: validatePluginId(string(input.pluginId, 'pluginId')),
+    services: declarations(input.services, 'service', 'services'),
+    eventTopics: declarations(input.eventTopics, 'topic', 'eventTopics'),
+    llmProviders: declarations(input.llmProviders, 'provider', 'llmProviders'),
+    tools: toolDefinitions(input.tools, 'tools'),
+  });
+}
+
+export function pluginUnloadRequest(input) {
+  shape(input, ['pluginId'], [], 'plugin/unload payload');
+  return Object.freeze({ pluginId: validatePluginId(string(input.pluginId, 'pluginId')) });
+}
+
+export function pluginDrainReport(input) {
+  shape(input, ['pluginId'], ['outstandingCalls', 'revokedSubscriptions'], 'plugin/unload terminal payload');
+  return Object.freeze({
+    pluginId: validatePluginId(string(input.pluginId, 'pluginId')),
+    outstandingCalls: declarations(input.outstandingCalls, 'call', 'outstandingCalls'),
+    revokedSubscriptions: declarations(input.revokedSubscriptions, 'subscription', 'revokedSubscriptions'),
+  });
+}
+
+export function serviceCallRequest(input) {
+  shape(input, ['service', 'request'], [], 'service/call payload');
+  return Object.freeze({ service: validateName('service', string(input.service, 'service')), request: input.request });
+}
+
+export function eventSubscribeRequest(input) {
+  shape(input, ['subscription', 'topic'], [], 'event/subscribe payload');
+  return Object.freeze({
+    subscription: validateName('subscription', string(input.subscription, 'subscription')),
+    topic: validateName('topic', string(input.topic, 'topic')),
+  });
+}
+
+export function eventUnsubscribeRequest(input) {
+  shape(input, ['subscription'], [], 'event/unsubscribe payload');
+  return Object.freeze({ subscription: validateName('subscription', string(input.subscription, 'subscription')) });
+}
+
+export function eventDelivery(input) {
+  shape(input, ['subscription', 'topic', 'event'], [], 'event/deliver payload');
+  return Object.freeze({
+    subscription: validateName('subscription', string(input.subscription, 'subscription')),
+    topic: validateName('topic', string(input.topic, 'topic')),
+    event: input.event,
+  });
+}
+
+export function eventEmitRequest(input) {
+  shape(input, ['topic', 'event'], [], 'event/emit payload');
+  return Object.freeze({
+    topic: validateName('topic', string(input.topic, 'topic')),
+    event: input.event,
+  });
+}
+
+export function toolInvokeRequest(input) {
+  shape(input, ['tool', 'input'], [], 'tool/invoke payload');
+  return Object.freeze({ tool: validateName('tool', string(input.tool, 'tool')), input: input.input });
+}
+
+export function llmStreamRequest(input) {
+  shape(input, ['provider', 'request'], [], 'llm/stream payload');
+  return Object.freeze({ provider: validateName('provider', string(input.provider, 'provider')), request: input.request });
+}
+
+export function seatCallRequest(input) {
+  shape(input, ['seat', 'method', 'params'], [], 'seat/call payload');
+  return Object.freeze({
+    seat: validateName('seat', string(input.seat, 'seat')),
+    method: validateName('method', string(input.method, 'method')),
+    params: input.params,
+  });
+}
+
+/// The corpus's `kind` names, so a shared case table can dispatch by name.
+export const VALIDATORS = Object.freeze({
+  plugin_load: pluginLoadRequest,
+  plugin_ready: pluginReadyReport,
+  plugin_unload: pluginUnloadRequest,
+  plugin_drain: pluginDrainReport,
+  service_call: serviceCallRequest,
+  event_subscribe: eventSubscribeRequest,
+  event_unsubscribe: eventUnsubscribeRequest,
+  event_deliver: eventDelivery,
+  event_emit: eventEmitRequest,
+  tool_invoke: toolInvokeRequest,
+  llm_stream: llmStreamRequest,
+  seat_call: seatCallRequest,
+});

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

@@ -0,0 +1,129 @@
+export const PROTOCOL_VERSION = 1;
+export const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+export const MAX_SAFE_WIRE_INTEGER = Number.MAX_SAFE_INTEGER;
+export const PLATFORM_PLUGIN_ID = '$rebon/platform';
+export const PLATFORM_CONTROL_SCOPE_ID = '$rebon/control';
+export const PLATFORM_CONTROL_GENERATION = 0;
+export const CALL_CANCEL_METHOD = 'call/cancel';
+
+export class ProtocolError extends Error {
+  constructor(code, message) { super(message); this.name = 'ProtocolError'; this.code = code; }
+}
+
+export class RawJsonNumber {
+  constructor(raw) { this.raw = raw; Object.freeze(this); }
+  valueOf() { return Number(this.raw); }
+  toJSON() { throw new ProtocolError('raw_number', 'raw JSON number cannot be emitted without an explicit schema conversion'); }
+}
+
+const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+export const plain = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+
+function exact(value, keys, where) {
+  if (!plain(value)) throw new ProtocolError('wrong_shape', `${where} must be a plain object`);
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    throw new ProtocolError('unknown_field', `${where} must have exactly: ${expected.join(', ')}`);
+  }
+  for (const key of expected) if (!own(value, key)) throw new ProtocolError('wrong_shape', `${where}.${key} is required`);
+}
+
+function wireInteger(value, field) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new ProtocolError('unsafe_integer', `${field} must be a safe non-negative integer`);
+  return Object.is(value, -0) ? 0 : value;
+}
+function string(value, field) {
+  if (typeof value !== 'string') throw new ProtocolError('wrong_shape', `${field} must be a string`);
+  return value;
+}
+function cloneJson(value, seen = new Set()) {
+  if (value instanceof RawJsonNumber) return value;
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new ProtocolError('invalid_payload', 'payload numbers must be finite JSON numbers');
+    return Object.is(value, -0) ? 0 : value;
+  }
+  if (typeof value !== 'object') throw new ProtocolError('invalid_payload', 'payload must be JSON-compatible');
+  if (seen.has(value)) throw new ProtocolError('invalid_payload', 'payload must not be cyclic');
+  seen.add(value);
+  let copy;
+  if (Array.isArray(value)) copy = value.map((item) => cloneJson(item, seen));
+  else {
+    if (!plain(value)) throw new ProtocolError('invalid_payload', 'payload objects must have a plain prototype');
+    copy = Object.create(null);
+    for (const key of Object.keys(value)) copy[key] = cloneJson(value[key], seen);
+  }
+  seen.delete(value);
+  return Object.freeze(copy);
+}
+
+/// Every name a message object may carry, whatever its variant.
+const MESSAGE_FIELDS = ['type', 'method', 'status', 'payload'];
+
+/// Checks a message object in the order the other language does.
+///
+/// The order is the contract, not an implementation detail. A name nobody knows
+/// is refused before the variant is even decided; then the fields every variant
+/// needs; only then a name that is real but belongs to a different variant.
+/// Collapsing these into one set comparison would report "you left out payload"
+/// as "unknown field", which sends a sender to the wrong place — and would say
+/// something different from the Rust side for the same bytes.
+function messageShape(message, fields) {
+  if (!plain(message)) throw new ProtocolError('wrong_shape', 'message must be a plain object');
+  for (const key of Object.keys(message)) {
+    if (!MESSAGE_FIELDS.includes(key)) throw new ProtocolError('unknown_field', `message has unknown field ${JSON.stringify(key)}`);
+  }
+  for (const key of ['type', 'payload']) {
+    if (!own(message, key)) throw new ProtocolError('wrong_shape', `message.${key} is required`);
+  }
+  for (const key of Object.keys(message)) {
+    if (!fields.includes(key)) throw new ProtocolError('unknown_field', `message must have exactly: ${[...fields].sort().join(', ')}`);
+  }
+  for (const key of fields) {
+    if (!own(message, key)) throw new ProtocolError('wrong_shape', `message.${key} is required`);
+  }
+}
+
+export function validateEnvelope(input) {
+  exact(input, ['protocol_version','host_epoch','plugin_id','scope_id','scope_generation','call_id','message'], 'envelope');
+  if (input.protocol_version !== PROTOCOL_VERSION) throw new ProtocolError('bad_version', `protocol_version must be ${PROTOCOL_VERSION}`);
+  const type = plain(input.message) ? input.message.type : undefined;
+  // A chunk carries no method: it belongs to the call whose identity it rides,
+  // and that call's method already said what it means.
+  const fields = type === 'terminal' ? ['type','status','payload']
+    : type === 'chunk' ? ['type','payload']
+    : ['type','method','payload'];
+  if (!['request','terminal','notification','chunk'].includes(type)) throw new ProtocolError('wrong_shape', 'message.type is invalid');
+  messageShape(input.message, fields);
+  const message = type === 'terminal'
+    ? Object.freeze({ type, status: terminalStatus(input.message.status), payload: cloneJson(input.message.payload) })
+    : type === 'chunk'
+      ? Object.freeze({ type, payload: cloneJson(input.message.payload) })
+      : Object.freeze({ type, method: string(input.message.method, 'message.method'), payload: cloneJson(input.message.payload) });
+  return Object.freeze({
+    protocol_version: PROTOCOL_VERSION,
+    host_epoch: wireInteger(input.host_epoch, 'host_epoch'),
+    plugin_id: string(input.plugin_id, 'plugin_id'),
+    scope_id: string(input.scope_id, 'scope_id'),
+    scope_generation: wireInteger(input.scope_generation, 'scope_generation'),
+    call_id: string(input.call_id, 'call_id'),
+    message,
+  });
+}
+function terminalStatus(status) {
+  if (!['success','error','cancelled'].includes(status)) throw new ProtocolError('bad_status', 'terminal status is invalid');
+  return status;
+}
+export function identityOf(envelope) {
+  return Object.freeze({ host_epoch: envelope.host_epoch, plugin_id: envelope.plugin_id, scope_id: envelope.scope_id,
+    scope_generation: envelope.scope_generation, call_id: envelope.call_id });
+}
+export function envelope(identity, message) { return validateEnvelope({ protocol_version: PROTOCOL_VERSION, ...identity, message }); }
+export function terminal(identity, status, payload) { return envelope(identity, { type: 'terminal', status, payload }); }
+export function request(identity, method, payload) { return envelope(identity, { type: 'request', method, payload }); }
+export function notification(identity, method, payload) { return envelope(identity, { type: 'notification', method, payload }); }
+export function chunk(identity, payload) { return envelope(identity, { type: 'chunk', payload }); }
+export function cancel(target) { return notification(target, CALL_CANCEL_METHOD, null); }
+export function isPlatformControl(value) { return value.plugin_id === PLATFORM_PLUGIN_ID && value.scope_id === PLATFORM_CONTROL_SCOPE_ID && value.scope_generation === 0; }

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

@@ -0,0 +1,7 @@
+export function createPluginApi(boundBridge) {
+  if (!boundBridge || typeof boundBridge.call !== 'function' || typeof boundBridge.notify !== 'function') throw new TypeError('boundBridge is invalid');
+  return Object.freeze({
+    call(method, payload, options = {}) { return boundBridge.call(method, payload, options); },
+    notify(method, payload) { return boundBridge.notify(method, payload); },
+  });
+}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@rebon/cli-linux-x64",
-  "version": "0.17.3",
+  "version": "0.18.0",
   "description": "Agent cli for coding and more.",
   "license": "MIT OR Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
   "bin": {
     "rebon": "bin/rebon"
   },