@rebon/cli-darwin-arm64 0.17.2 → 0.18.0

package/bin/compose-runtime/src/web-runtime.mjs

@@ -0,0 +1,209 @@
+// The composition's `ctx.web` seat, on the plugin plane.
+//
+// Ported from `js/compose/web-runtime.js`. The dsh-facing surface is
+// unchanged and verbatim: providers register with
+// `ctx.web.registerSearchProvider` / `registerFetchProvider` (duplicate ids
+// throw WEB_DUPLICATE_PROVIDER, the exact disposer comes back), and
+// `search`/`fetch` resolve their provider at EXECUTION time with dsh's
+// five-state rules — a configured id wins or fails loudly, never falls back;
+// otherwise exactly one usable provider auto-selects. `maxResults` truncation
+// (capSources) is enforced on the way out.
+//
+// Deployment default: the `rebon` builtin provider, backed by rebon's own
+// WebSearch/WebFetch tools through `tool/invoke`, is always registered, and the
+// configured id DEFAULTS to `"rebon"`. So a plugin provider takes over only
+// when configured, and dsh's AMBIGUOUS state is unreachable unless the default
+// is explicitly cleared. **A plugin whose tool reaches `ctx.web` therefore
+// causes a `tool/invoke` of rebon's WebSearch, attributed to that plugin** —
+// which is why such a plugin declares `WebSearch`/`WebFetch` in
+// `invokableTools`. The attribution is the point: rebon can always answer who
+// caused a tool to run.
+//
+// What changed: `emit('web/provider-registered', …)` and the shared serve pump
+// are gone. A registered provider is *reported* — it appears in the plugin's
+// load report as a service named `web:<kind>:<id>`, which is also how rebon
+// dispatches into it.
+import { Service } from 'cordis';
+import { WebError } from '@deepseek-ai/dsh-web';
+import { invokeTool, withCall } from './bridge.mjs';
+import { sinkOf } from './registry.mjs';
+
+/** The service-name namespace a plugin web provider is served under. */
+export const webTarget = (kind, id) => `web:${kind}:${id}`;
+
+/** dsh WebRuntime.resolveProvider, transcribed. */
+function resolveProvider(configuredId, providers) {
+  if (configuredId !== undefined) {
+    const provider = providers.get(configuredId);
+    if (!provider) {
+      throw new WebError(
+        `configured web provider "${configuredId}" is not registered`,
+        'WEB_PROVIDER_CONFIGURED_MISSING',
+      );
+    }
+    if (!provider.available()) {
+      throw new WebError(
+        `configured web provider "${configuredId}" is registered but unavailable`,
+        'WEB_PROVIDER_CONFIGURED_UNAVAILABLE',
+      );
+    }
+    return provider;
+  }
+  const usable = [...providers.values()].filter((provider) => {
+    try {
+      return !!provider.available();
+    } catch {
+      return false;
+    }
+  });
+  if (usable.length === 0) {
+    throw new WebError('no usable web provider is registered', 'WEB_PROVIDER_UNAVAILABLE');
+  }
+  if (usable.length > 1) {
+    const ids = usable.map((provider) => provider.id).join(', ');
+    throw new WebError(
+      `multiple usable web providers are registered (${ids}); configure one explicitly`,
+      'WEB_PROVIDER_AMBIGUOUS',
+    );
+  }
+  return usable[0];
+}
+
+/** dsh capSources: enforce `maxResults` on the way back. */
+function capSources(result, maxResults) {
+  if (maxResults === undefined || (result.sources?.length ?? 0) <= maxResults) return result;
+  return { ...result, sources: result.sources.slice(0, maxResults), truncated: true };
+}
+
+/**
+ * The rebon builtin search provider: reaches rebon's WebSearch tool and maps
+ * the `{query, answer, results}` contract into dsh's result vocabulary.
+ */
+const rebonBuiltinSearch = {
+  id: 'rebon',
+  available: () => true,
+  async search(request, _signal) {
+    const out = await invokeTool('WebSearch', { query: String(request?.query ?? '') });
+    const sources = (out?.results ?? [])
+      .map((entry) => ({
+        url: String(entry?.url ?? ''),
+        ...(entry?.title ? { title: String(entry.title) } : {}),
+        ...(entry?.snippet ? { snippet: String(entry.snippet) } : {}),
+      }))
+      .filter((source) => source.url.length > 0);
+    return {
+      ...(out?.answer ? { content: String(out.answer) } : {}),
+      sources,
+      truncated: false,
+    };
+  },
+};
+
+/**
+ * The rebon builtin fetch provider over rebon's WebFetch tool. The tool
+ * returns extracted text, not raw transport facts, so `statusCode` is the
+ * 200 the extraction implies and the body is `text` — a documented v1
+ * approximation, not a transport claim.
+ */
+const rebonBuiltinFetch = {
+  id: 'rebon',
+  available: () => true,
+  async fetch(request, _signal) {
+    const out = await invokeTool('WebFetch', { url: String(request?.url ?? '') });
+    const content =
+      typeof out === 'string' ? out : String(out?.content ?? out?.text ?? JSON.stringify(out));
+    return {
+      url: String(request?.url ?? ''),
+      statusCode: 200,
+      body: { kind: 'text', content },
+      truncated: false,
+    };
+  },
+};
+
+export default class RebonWebRuntime extends Service {
+  constructor(ctx, options) {
+    super(ctx, 'web');
+    const config = options?.web ?? {};
+    const configured = (value) =>
+      typeof value === 'string' && value.trim().length > 0 ? value.trim() : 'rebon';
+    this.searchProviderId = configured(config?.searchProvider);
+    this.fetchProviderId = configured(config?.fetchProvider);
+    this.searchProviders = new Map([['rebon', rebonBuiltinSearch]]);
+    this.fetchProviders = new Map([['rebon', rebonBuiltinFetch]]);
+  }
+
+  registerSearchProvider(provider) {
+    return this._register(this.searchProviders, 'search', provider);
+  }
+
+  registerFetchProvider(provider) {
+    return this._register(this.fetchProviders, 'fetch', provider);
+  }
+
+  _register(store, kind, provider) {
+    if (typeof provider?.id !== 'string' || provider.id.length === 0) {
+      throw new TypeError('a web provider must declare a non-empty string `id`');
+    }
+    if (store.has(provider.id)) {
+      throw new WebError(
+        `a web provider with id "${provider.id}" is already registered`,
+        'WEB_DUPLICATE_PROVIDER',
+      );
+    }
+    const runtime = this;
+    let available = false;
+    try {
+      available = !!provider.available();
+    } catch {}
+    // `available` is a registration-time snapshot: a static composition's
+    // configuration does not change under it. Documented v1 semantics,
+    // carried over unchanged.
+    const sink = sinkOf(this.ctx);
+    sink?.service(webTarget(kind, provider.id), (input, callCtx) =>
+      withCall(callCtx, () => runtime._serve(kind, provider.id, input, callCtx.signal)));
+    sink?.webProvider(kind, provider.id, available);
+    // Caller-fork RAII (the Service proxy binds this.ctx to the registrant):
+    // plugin disposal removes the provider, and a call arriving afterwards is
+    // refused rather than answered by a provider nobody can revoke.
+    return this.ctx.effect(() => {
+      store.set(provider.id, provider);
+      return () => {
+        store.delete(provider.id);
+      };
+    });
+  }
+
+  /** rebon-dispatched execution of one plugin provider (seat rules applied). */
+  async _serve(kind, id, input, signal) {
+    const store = kind === 'search' ? this.searchProviders : this.fetchProviders;
+    const provider = store.get(id);
+    if (provider === undefined) {
+      throw new WebError(
+        `web provider "${id}" is no longer registered in this composition`,
+        'WEB_PROVIDER_UNAVAILABLE',
+      );
+    }
+    if (kind === 'search') {
+      const request = {
+        query: String(input?.query ?? ''),
+        ...(input?.maxResults !== undefined ? { maxResults: input.maxResults } : {}),
+      };
+      return capSources(await provider.search(request, signal), request.maxResults);
+    }
+    return provider.fetch({ url: String(input?.url ?? '') }, signal);
+  }
+
+  /** dsh consumer API: run one search through the selected provider. */
+  async search(request, signal) {
+    const provider = resolveProvider(this.searchProviderId, this.searchProviders);
+    const result = await provider.search(request, signal);
+    return capSources(result, request?.maxResults);
+  }
+
+  /** dsh consumer API: retrieve one URL through the selected provider. */
+  async fetch(request, signal) {
+    const provider = resolveProvider(this.fetchProviderId, this.fetchProviders);
+    return provider.fetch(request, signal);
+  }
+}

package/bin/plugin-host/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@rebon/plugin-host",
+  "version": "0.0.0-private",
+  "private": true,
+  "type": "module",
+  "license": "MIT OR Apache-2.0",
+  "engines": { "node": ">=24.19.0 <25" },
+  "scripts": { "test": "node --test test/*.test.mjs" },
+  "bin": { "rebon-plugin-host": "./src/cli.mjs" },
+  "exports": { ".": "./src/sdk.mjs" }
+}

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

@@ -0,0 +1,64 @@
+import { randomUUID } from 'node:crypto';
+import { cancel, notification, request, ProtocolError } from './protocol.mjs';
+
+export function createPluginBridge({ trustedPluginId, scopeBinding, transport, ledger, idFactory = randomUUID }) {
+  if (typeof trustedPluginId !== 'string') throw new TypeError('trustedPluginId must be a string');
+  if (typeof idFactory !== 'function') throw new TypeError('idFactory must be a function');
+  const pending = new Map();
+  const makeIdentity = () => Object.freeze({ host_epoch: scopeBinding.hostEpoch, plugin_id: trustedPluginId,
+    scope_id: scopeBinding.scopeId, scope_generation: scopeBinding.scopeGeneration, call_id: idFactory() });
+  const call = (method, payload, { signal } = {}) => {
+    if (signal !== undefined && !(signal instanceof AbortSignal)) throw new TypeError('signal must be an AbortSignal');
+    const identity = makeIdentity();
+    ledger.register(identity, 'outbound', trustedPluginId);
+    let resolvePromise, rejectPromise;
+    const promise = new Promise((resolve, reject) => { resolvePromise = resolve; rejectPromise = reject; });
+    let settled = false; let cancelSent = false; let requestSent = false; let abortWanted = signal?.aborted ?? false; let listenerAdded = false;
+    const cleanup = () => {
+      if (listenerAdded) { signal.removeEventListener('abort', onAbort); listenerAdded = false; }
+      pending.delete(identity.call_id);
+    };
+    const settle = (action, value) => {
+      if (settled) return;
+      settled = true; cleanup(); action(value);
+    };
+    const sendCancel = () => {
+      if (settled || cancelSent || !requestSent) return Promise.resolve();
+      cancelSent = true;
+      return Promise.resolve().then(() => transport.send(cancel(identity))).catch((error) => settle(rejectPromise, error));
+    };
+    const onAbort = () => {
+      if (settled) return;
+      abortWanted = true;
+      if (requestSent) void sendCancel();
+    };
+    pending.set(identity.call_id, { identity, resolve: (value) => settle(resolvePromise, value), reject: (error) => settle(rejectPromise, error) });
+    if (signal && !signal.aborted) {
+      signal.addEventListener('abort', onAbort, { once: true });
+      listenerAdded = true;
+    }
+    Promise.resolve().then(() => transport.send(request(identity, method, payload))).then(() => {
+      if (settled) return;
+      requestSent = true;
+      if (abortWanted) return sendCancel();
+    }).catch((error) => {
+      if (!settled) ledger.retire(identity);
+      settle(rejectPromise, error);
+    });
+    return promise;
+  };
+  const notify = (method, payload) => Promise.resolve().then(() => transport.send(notification(makeIdentity(), method, payload)));
+  const receive = (envelope) => {
+    const disposition = ledger.terminal(envelope, 'outbound');
+    if (disposition.stale) return;
+    const item = pending.get(envelope.call_id);
+    if (!item) throw new ProtocolError('unknown_call', 'no pending bridge call');
+    if (envelope.message.status === 'success') item.resolve(envelope.message.payload);
+    else {
+      const error = new ProtocolError(envelope.message.status, `call ended with ${envelope.message.status}`);
+      error.payload = envelope.message.payload;
+      item.reject(error);
+    }
+  };
+  return Object.freeze({ call, notify, receive, pendingCount: () => pending.size });
+}

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

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+import { NdjsonDecoder, SerializedWriter } from './framing.mjs';
+import { PluginHost } from './host.mjs';
+import { loadPlugin } from './loader.mjs';
+import { ProtocolError } from './protocol.mjs';
+
+export function diagnostic(stream, code, message) {
+  const bounded = String(message).replace(/[\r\n]+/g, ' ').slice(0, 512);
+  stream.write(`${JSON.stringify({ level: 'error', code, message: bounded })}\n`);
+}
+export function installHostConsole(stream) {
+  const write = (level, values) => stream.write(`${JSON.stringify({ level, message: values.map(String).join(' ').slice(0, 512) })}\n`);
+  return Object.freeze({ log: (...v) => write('info', v), info: (...v) => write('info', v), warn: (...v) => write('warn', v), error: (...v) => write('error', v) });
+}
+
+// Frames are not handled one-at-a-time.
+//
+// A request handler may itself call rebon — that is the whole Node → rebon
+// direction — and the answer to that call arrives as a frame on this very
+// stream. Awaiting each dispatch before reading the next would mean the handler
+// waits for a frame the loop cannot read until the handler returns: a deadlock
+// that no amount of care inside a plugin can avoid. So dispatches are tracked
+// rather than awaited, and everything that needs them finished waits here.
+/// Loads the module that decides what a plugin package *is*.
+///
+/// The host itself knows one shape: a module exporting `activate`. Anything
+/// else — a Cordis plugin mounted into a shared composition realm, say — is a
+/// different answer to the same question, and the host has no business knowing
+/// which answers exist. So rebon names the module that does, and this loads it.
+///
+/// The module exports `createLoader({ next })` and returns `{ load, unload }`;
+/// `next` is the built-in loader, so an adapter that does not recognise a
+/// package hands it back rather than reimplementing it.
+export async function resolveLoader(specifier, error) {
+  if (!specifier) return {};
+  const url = specifier.startsWith('file:') ? specifier : pathToFileURL(specifier).href;
+  const module = await import(url);
+  if (typeof module.createLoader !== 'function') {
+    throw new ProtocolError('loader_invalid', `${specifier} exports no createLoader`);
+  }
+  const seams = await module.createLoader({ next: loadPlugin });
+  if (typeof seams?.load !== 'function') {
+    throw new ProtocolError('loader_invalid', `${specifier} produced no load function`);
+  }
+  return seams;
+}
+
+export async function runHost({ input, output, error, loader }) {
+  const decoder = new NdjsonDecoder();
+  const writer = new SerializedWriter(output);
+  const host = new PluginHost(writer, loader ?? {});
+  const running = new Set();
+  let fatal = null;
+  const track = (promise) => {
+    const tracked = promise.catch((cause) => { fatal ??= cause; }).finally(() => running.delete(tracked));
+    running.add(tracked);
+  };
+  // Draining rather than a single `Promise.all`: a dispatch that is still
+  // running can schedule another one, and the process must not exit under it.
+  const quiesce = async () => { while (running.size > 0) await Promise.all([...running]); };
+  try {
+    for await (const chunk of input) {
+      for (const frame of decoder.push(chunk)) {
+        if (fatal) throw fatal;
+        if (host.shuttingDown) throw new ProtocolError('frame_after_shutdown', 'frame received after shutdown');
+        track(host.accept(frame));
+      }
+      if (fatal) throw fatal;
+      if (host.shuttingDown) { await quiesce(); if (fatal) throw fatal; return 0; }
+    }
+    decoder.finish();
+    await quiesce();
+    if (fatal) throw fatal;
+    diagnostic(error, 'connection_lost', 'stdin reached EOF before successful shutdown');
+    return 3;
+  } catch (cause) {
+    // Terminals already owed still have to reach stdout: a caller waiting on
+    // one is not made whole by the host exiting with a diagnosis.
+    await quiesce();
+    const code = cause?.code ?? 'host_failure';
+    diagnostic(error, code, cause?.message ?? 'host failed');
+    return code === 'write_error' ? 4 : 2;
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const flag = process.argv.indexOf('--loader');
+  const specifier = flag >= 0 ? process.argv[flag + 1] : process.env.REBON_PLUGIN_LOADER;
+  let loader;
+  try {
+    loader = await resolveLoader(specifier, process.stderr);
+  } catch (cause) {
+    // A host that cannot build the loader rebon asked for must not fall back to
+    // the built-in one: it would load a different set of plugins than the one
+    // rebon believes it asked for, and say nothing.
+    diagnostic(process.stderr, cause?.code ?? 'loader_failure', cause?.message ?? 'loader failed');
+    process.exitCode = 2;
+  }
+  if (loader !== undefined) {
+    process.exitCode = await runHost({
+      input: process.stdin, output: process.stdout, error: process.stderr, loader,
+    });
+  }
+}

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

@@ -0,0 +1,113 @@
+import { MAX_FRAME_BYTES, ProtocolError, validateEnvelope } from './protocol.mjs';
+import { parseEnvelopeJson } from './json.mjs';
+
+export class FramingError extends ProtocolError {}
+
+export class NdjsonDecoder {
+  #segments = []; #byteCount = 0; #failed = false; #copiedBytes = 0;
+  constructor(maxFrameBytes = MAX_FRAME_BYTES) { this.maxFrameBytes = maxFrameBytes; }
+  get stats() { return Object.freeze({ retained_bytes: this.#byteCount, copied_bytes: this.#copiedBytes }); }
+  push(chunk) {
+    if (this.#failed) throw new FramingError('poisoned', 'decoder is poisoned');
+    if (!Buffer.isBuffer(chunk) && !(chunk instanceof Uint8Array)) return this.#fail('wrong_chunk', 'input chunk must be bytes');
+    const input = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    const frames = [];
+    let start = 0;
+    for (let index = 0; index < input.length; index++) {
+      if (input[index] !== 0x0a) continue;
+      this.#append(input.subarray(start, index));
+      let bytes = this.#join();
+      this.#segments = []; this.#byteCount = 0;
+      if (bytes.at(-1) === 0x0d) bytes = bytes.subarray(0, -1);
+      if (bytes.length > this.maxFrameBytes) return this.#fail('frame_too_large', `frame exceeds ${this.maxFrameBytes} bytes`);
+      if (bytes.length === 0) return this.#fail('empty_frame', 'NDJSON frame is empty');
+      if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        return this.#fail('utf8_bom', 'UTF-8 BOM is not permitted');
+      }
+      try {
+        const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+        frames.push(parseEnvelopeJson(text));
+      } catch (error) {
+        if (error instanceof ProtocolError) return this.#fail(error.code, error.message);
+        return this.#fail('invalid_utf8', 'frame is not valid UTF-8');
+      }
+      start = index + 1;
+    }
+    this.#append(input.subarray(start));
+    if (this.#byteCount > this.maxFrameBytes
+        && !(this.#byteCount === this.maxFrameBytes + 1 && this.#lastByte() === 0x0d)) {
+      return this.#fail('frame_too_large', `frame exceeds ${this.maxFrameBytes} bytes`);
+    }
+    return frames;
+  }
+  finish() {
+    if (this.#failed) throw new FramingError('poisoned', 'decoder is poisoned');
+    if (this.#byteCount) return this.#fail('incomplete_frame', `EOF with unterminated ${this.#byteCount}-byte frame`);
+  }
+  #append(bytes) {
+    if (!bytes.length) return;
+    const copy = Buffer.from(bytes);
+    this.#segments.push(copy); this.#byteCount += copy.length; this.#copiedBytes += copy.length;
+  }
+  #join() {
+    if (this.#segments.length === 1) return this.#segments[0];
+    this.#copiedBytes += this.#byteCount;
+    return Buffer.concat(this.#segments, this.#byteCount);
+  }
+  #lastByte() { return this.#segments.at(-1)?.at(-1); }
+  #fail(code, message) { this.#failed = true; this.#segments = []; this.#byteCount = 0; throw new FramingError(code, message); }
+}
+
+export function encodeFrame(value, maxFrameBytes = MAX_FRAME_BYTES) {
+  const normalized = validateEnvelope(value);
+  let text;
+  try { text = JSON.stringify(normalized); } catch { throw new FramingError('encode_error', 'envelope cannot be encoded'); }
+  const bytes = Buffer.from(text);
+  if (bytes.length > maxFrameBytes) throw new FramingError('frame_too_large', `frame exceeds ${maxFrameBytes} bytes`);
+  return Buffer.concat([bytes, Buffer.from('\n')]);
+}
+
+export class SerializedWriter {
+  #tail = Promise.resolve(); #error;
+  constructor(stream, maxFrameBytes = MAX_FRAME_BYTES) { this.stream = stream; this.maxFrameBytes = maxFrameBytes; }
+  send(value) {
+    if (this.#error) return Promise.reject(this.#error);
+    const bytes = encodeFrame(value, this.maxFrameBytes);
+    const operation = this.#tail.then(() => {
+      if (this.#error) throw this.#error;
+      return this.#write(bytes);
+    });
+    this.#tail = operation.catch((error) => { this.#error ??= error; });
+    return operation;
+  }
+  async flush() { await this.#tail; if (this.#error) throw this.#error; }
+  #write(bytes) {
+    return new Promise((resolve, reject) => {
+      let callbackDone = false; let accepted; let drainSeen = false; let settled = false;
+      const cleanup = () => { this.stream.removeListener('error', onError); this.stream.removeListener('drain', onDrain); };
+      const fail = (cause) => {
+        if (settled) return;
+        settled = true; cleanup();
+        const error = cause instanceof FramingError ? cause
+          : new FramingError('write_error', `protocol output failed: ${cause?.code ?? 'stream error'}`);
+        this.#error ??= error; reject(error);
+      };
+      const complete = () => {
+        if (settled || accepted === undefined || !callbackDone || (!accepted && !drainSeen)) return;
+        settled = true; cleanup(); resolve();
+      };
+      const onError = (error) => fail(error);
+      const onDrain = () => { drainSeen = true; complete(); };
+      this.stream.once('error', onError);
+      this.stream.once('drain', onDrain);
+      try {
+        accepted = this.stream.write(bytes, (error) => {
+          if (error) { setImmediate(() => fail(error)); return; }
+          callbackDone = true; complete();
+        });
+        if (accepted) this.stream.removeListener('drain', onDrain);
+        complete();
+      } catch (error) { fail(error); }
+    });
+  }
+}