@qping/plugin-bus 0.1.0 → 0.3.0

package/dist/node.mjs

@@ -0,0 +1,851 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/framing.ts
+var framing_exports = {};
+__export(framing_exports, {
+  FrameDecoder: () => FrameDecoder,
+  MAX_FRAME_BYTES: () => MAX_FRAME_BYTES,
+  PREFIX_BYTES: () => PREFIX_BYTES,
+  encodeFrame: () => encodeFrame,
+  encodeFrameString: () => encodeFrameString
+});
+function encodeFrame(payload) {
+  const length = payload.length;
+  const frame = Buffer.alloc(PREFIX_BYTES + length);
+  frame[0] = length & 255;
+  frame[1] = length >> 8 & 255;
+  frame[2] = length >> 16 & 255;
+  frame[3] = length >> 24 & 255;
+  payload.copy(frame, PREFIX_BYTES);
+  return frame;
+}
+function encodeFrameString(json) {
+  return encodeFrame(Buffer.from(json, "utf8"));
+}
+var MAX_FRAME_BYTES, PREFIX_BYTES, FrameDecoder;
+var init_framing = __esm({
+  "src/framing.ts"() {
+    MAX_FRAME_BYTES = 4 * 1024 * 1024;
+    PREFIX_BYTES = 4;
+    FrameDecoder = class {
+      prefixBuf = Buffer.alloc(PREFIX_BYTES);
+      prefixFilled = 0;
+      payload = null;
+      payloadFilled = 0;
+      payloadLength = 0;
+      fatal = false;
+      pending = Buffer.alloc(0);
+      feed(chunk) {
+        const empty = { hasFrame: false, payload: Buffer.alloc(0), isFatal: false };
+        if (this.fatal) {
+          return { hasFrame: false, payload: Buffer.alloc(0), isFatal: true };
+        }
+        let current;
+        if (this.pending.length > 0) {
+          current = Buffer.concat([this.pending, chunk]);
+          this.pending = Buffer.alloc(0);
+        } else {
+          current = chunk;
+        }
+        let offset = 0;
+        while (offset < current.length) {
+          if (this.payload === null) {
+            const need = PREFIX_BYTES - this.prefixFilled;
+            const take = Math.min(need, current.length - offset);
+            current.copy(this.prefixBuf, this.prefixFilled, offset, offset + take);
+            this.prefixFilled += take;
+            offset += take;
+            if (this.prefixFilled < PREFIX_BYTES) {
+              return empty;
+            }
+            this.payloadLength = this.prefixBuf[0] | this.prefixBuf[1] << 8 | this.prefixBuf[2] << 16 | this.prefixBuf[3] << 24;
+            if (this.payloadLength < 0 || this.payloadLength > MAX_FRAME_BYTES) {
+              this.fatal = true;
+              return { hasFrame: false, payload: Buffer.alloc(0), isFatal: true };
+            }
+            if (this.payloadLength === 0) {
+              this.reset();
+              this.bufferLeftover(current, offset);
+              return { hasFrame: true, payload: Buffer.alloc(0), isFatal: false };
+            }
+            this.payload = Buffer.alloc(this.payloadLength);
+            this.payloadFilled = 0;
+          }
+          const payloadNeed = this.payloadLength - this.payloadFilled;
+          const payloadTake = Math.min(payloadNeed, current.length - offset);
+          current.copy(this.payload, this.payloadFilled, offset, offset + payloadTake);
+          this.payloadFilled += payloadTake;
+          offset += payloadTake;
+          if (this.payloadFilled >= this.payloadLength) {
+            const out = this.payload;
+            this.reset();
+            this.bufferLeftover(current, offset);
+            return { hasFrame: true, payload: out, isFatal: false };
+          }
+        }
+        return empty;
+      }
+      bufferLeftover(src, offset) {
+        if (offset < src.length) {
+          this.pending = src.subarray(offset);
+        }
+      }
+      reset() {
+        this.prefixFilled = 0;
+        this.payload = null;
+        this.payloadFilled = 0;
+        this.payloadLength = 0;
+      }
+    };
+  }
+});
+
+// src/bootstrap.ts
+import readline from "node:readline/promises";
+import { randomBytes as randomBytes2 } from "node:crypto";
+
+// src/transport.ts
+init_framing();
+import { connect as netConnect } from "node:net";
+
+// src/protocol.ts
+var MessageKind = {
+  Request: "request",
+  Response: "response",
+  Event: "event"
+};
+var ErrorCode = {
+  ProtocolMismatch: "ProtocolMismatch",
+  HandshakeFailed: "HandshakeFailed",
+  CapabilityNotDeclared: "CapabilityNotDeclared",
+  CapabilityDenied: "CapabilityDenied",
+  InvalidPayload: "InvalidPayload",
+  MessageTooLarge: "MessageTooLarge",
+  RouteNotFound: "RouteNotFound",
+  RequestTimeout: "RequestTimeout",
+  TooManyRequests: "TooManyRequests",
+  TransportDisconnected: "TransportDisconnected",
+  PluginUnavailable: "PluginUnavailable",
+  InternalError: "InternalError",
+  Cancelled: "Cancelled",
+  RateLimited: "RateLimited"
+};
+var ProtocolVersion = "3.0";
+var EndpointIds = {
+  NodeMain: "node-main",
+  Host: "host"
+};
+var Routes = {
+  Bus: {
+    Handshake: "bus.handshake",
+    Ping: "bus.ping",
+    Cancel: "bus.cancel",
+    Subscribe: "bus.subscribe",
+    Unsubscribe: "bus.unsubscribe"
+  },
+  Prefix: {
+    PluginCall: "plugin.call.",
+    HostCall: "host.call.",
+    PluginEvent: "plugin.event.",
+    HostEvent: "host.event.",
+    Diagnostics: "diagnostics."
+  },
+  PluginCall: {
+    Initialize: "plugin.call.initialize",
+    Search: "plugin.call.search",
+    InvokeAction: "plugin.call.invokeAction"
+  },
+  HostEvent: {
+    Initialize: "host.event.initialize",
+    Search: "host.event.search",
+    Key: "host.event.key",
+    DetailAction: "host.event.detailAction",
+    LanguageChanged: "host.event.languageChanged",
+    ThemeChanged: "host.event.themeChanged",
+    InputActionCaptured: "host.event.inputActionCaptured"
+  }
+};
+function pluginCallRoute(method) {
+  return method.startsWith(Routes.Prefix.PluginCall) ? method : `${Routes.Prefix.PluginCall}${method}`;
+}
+function hostCallRoute(method) {
+  return method.startsWith(Routes.Prefix.HostCall) ? method : `${Routes.Prefix.HostCall}${method}`;
+}
+function pluginEventRoute(subjectId) {
+  return subjectId.startsWith(Routes.Prefix.PluginEvent) ? subjectId : `${Routes.Prefix.PluginEvent}${subjectId}`;
+}
+function canonicalStringify(value) {
+  return JSON.stringify(stripNulls(value));
+}
+function stripNulls(value) {
+  if (value === null || value === void 0) return void 0;
+  if (Array.isArray(value)) return value.map(stripNulls);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      const stripped = stripNulls(v);
+      if (stripped !== void 0) out[k] = stripped;
+    }
+    return out;
+  }
+  return value;
+}
+
+// src/transport.ts
+var NodeTransport = class {
+  socket = null;
+  messageHandlers = /* @__PURE__ */ new Set();
+  disconnectHandlers = /* @__PURE__ */ new Set();
+  closed = false;
+  onMessage(handler) {
+    this.messageHandlers.add(handler);
+    return () => {
+      this.messageHandlers.delete(handler);
+    };
+  }
+  onDisconnect(handler) {
+    this.disconnectHandlers.add(handler);
+  }
+  get isConnected() {
+    return this.socket !== null && !this.closed;
+  }
+  /** Connects to a Windows named pipe (\\.\pipe\<name>). */
+  async connect(pipePath) {
+    this.socket = netConnect(pipePath);
+    await new Promise((resolve, reject) => {
+      this.socket.once("connect", () => resolve());
+      this.socket.once("error", (err) => reject(err));
+    });
+    const { FrameDecoder: FrameDecoder2 } = await Promise.resolve().then(() => (init_framing(), framing_exports));
+    const decoder = new FrameDecoder2();
+    this.socket.on("data", (chunk) => {
+      let result = decoder.feed(chunk);
+      if (result.isFatal) {
+        this.handleDisconnect();
+        return;
+      }
+      while (result.hasFrame) {
+        try {
+          const env = JSON.parse(result.payload.toString("utf8"));
+          for (const h of this.messageHandlers) h(env);
+        } catch {
+          this.handleDisconnect();
+          return;
+        }
+        result = decoder.feed(Buffer.alloc(0));
+        if (result.isFatal) {
+          this.handleDisconnect();
+          return;
+        }
+      }
+    });
+    this.socket.on("close", () => this.handleDisconnect());
+    this.socket.on("error", () => this.handleDisconnect());
+  }
+  /** Serializes an envelope to a length-prefixed frame and writes it. */
+  send(env) {
+    if (!this.socket || this.closed) {
+      throw new Error("transport is not connected");
+    }
+    this.socket.write(encodeFrameString(canonicalStringify(env)));
+  }
+  async close() {
+    this.closed = true;
+    if (this.socket) {
+      this.socket.end();
+      await new Promise((resolve) => {
+        if (this.socket.destroyed) return resolve();
+        this.socket.once("close", () => resolve());
+      });
+      this.socket = null;
+    }
+  }
+  handleDisconnect() {
+    if (this.closed) return;
+    this.closed = true;
+    for (const h of this.disconnectHandlers) h();
+  }
+};
+
+// src/router.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+var requestScope = new AsyncLocalStorage();
+var DefaultHostCallTimeoutMs = 3e4;
+function remainingTimeoutMs() {
+  const scope = requestScope.getStore();
+  if (!scope || scope.deadlineMs == null) {
+    return void 0;
+  }
+  return scope.deadlineMs - Date.now();
+}
+function resolveHostCallTimeoutMs(explicit) {
+  const remaining = remainingTimeoutMs();
+  if (explicit != null) {
+    return remaining == null ? explicit : Math.min(explicit, remaining);
+  }
+  return remaining ?? DefaultHostCallTimeoutMs;
+}
+function deadlineFromTimeoutMs(timeoutMs) {
+  if (typeof timeoutMs !== "number" || timeoutMs <= 0) {
+    return null;
+  }
+  return Date.now() + timeoutMs;
+}
+var HandlerRouter = class {
+  handlers = /* @__PURE__ */ new Map();
+  pendingHostCalls = /* @__PURE__ */ new Map();
+  pluginId = "p";
+  entryId = "e";
+  sessionId = "s";
+  endpointId = EndpointIds.NodeMain;
+  /** Injected transport send fn; tests can override `router.send` directly. */
+  send;
+  constructor(deps) {
+    this.send = deps.send;
+  }
+  /** Sets the bound identity stamped on outbound messages (after handshake). */
+  setIdentity(ids) {
+    this.pluginId = ids.pluginId;
+    this.entryId = ids.entryId;
+    this.sessionId = ids.sessionId;
+    this.endpointId = ids.endpointId;
+  }
+  handle(route, handler) {
+    this.handlers.set(route, handler);
+  }
+  /** Dispatches an inbound request/response. Returns once handled. */
+  async dispatch(env) {
+    if (env.kind === MessageKind.Response) {
+      this.handleHostResponse(env);
+      return;
+    }
+    if (env.kind !== MessageKind.Request) return;
+    if (env.route === Routes.Bus.Ping) {
+      this.send(this.responseFor(env, { ok: true }));
+      return;
+    }
+    const handler = this.handlers.get(env.route);
+    if (!handler) {
+      this.send(this.errorResponseFor(env, ErrorCode.RouteNotFound, `route '${env.route}' has no handler`));
+      return;
+    }
+    const deadlineMs = deadlineFromTimeoutMs(env.timeoutMs);
+    try {
+      const result = await requestScope.run(
+        { deadlineMs },
+        () => handler(env.payload, { sessionId: env.sessionId })
+      );
+      this.send(this.responseFor(env, result ?? {}));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.send(this.errorResponseFor(env, ErrorCode.InternalError, message));
+    }
+  }
+  /** Calls a host.call.* capability and resolves with the response payload. */
+  callHost(route, payload, timeoutMs) {
+    const effectiveTimeoutMs = resolveHostCallTimeoutMs(timeoutMs);
+    if (effectiveTimeoutMs <= 0) {
+      return Promise.reject(new Error(`host call ${route} timed out (no time remaining)`));
+    }
+    return new Promise((resolve, reject) => {
+      const id = randomBytesHex();
+      const req = {
+        version: ProtocolVersion,
+        id,
+        traceId: id,
+        sessionId: this.sessionId,
+        pluginId: this.pluginId,
+        entryId: this.entryId,
+        endpointId: this.endpointId,
+        kind: MessageKind.Request,
+        route,
+        timeoutMs: effectiveTimeoutMs,
+        payload
+      };
+      const pending = { resolve, reject, route };
+      this.pendingHostCalls.set(id, pending);
+      const timer = setTimeout(() => {
+        if (this.pendingHostCalls.has(id)) {
+          this.pendingHostCalls.delete(id);
+          reject(new Error(`host call ${route} timed out after ${effectiveTimeoutMs}ms`));
+        }
+      }, effectiveTimeoutMs);
+      const origResolve = pending.resolve;
+      const origReject = pending.reject;
+      pending.resolve = (v) => {
+        clearTimeout(timer);
+        origResolve(v);
+      };
+      pending.reject = (e) => {
+        clearTimeout(timer);
+        origReject(e);
+      };
+      this.send(req);
+    });
+  }
+  handleHostResponse(env) {
+    if (!env.correlationId) return;
+    const pending = this.pendingHostCalls.get(env.correlationId);
+    if (!pending) return;
+    this.pendingHostCalls.delete(env.correlationId);
+    if (env.error) {
+      pending.reject(new Error(`${env.error.code}: ${env.error.message}`));
+    } else {
+      pending.resolve(env.payload);
+    }
+  }
+  responseFor(req, payload) {
+    return {
+      version: ProtocolVersion,
+      id: randomBytesHex(),
+      correlationId: req.id,
+      traceId: req.traceId,
+      sessionId: req.sessionId,
+      pluginId: req.pluginId,
+      entryId: req.entryId,
+      endpointId: this.endpointId,
+      kind: MessageKind.Response,
+      route: req.route,
+      payload
+    };
+  }
+  errorResponseFor(req, code, message) {
+    return {
+      ...this.responseFor(req, null),
+      payload: void 0,
+      error: { code, message, retryable: false }
+    };
+  }
+};
+function randomBytesHex() {
+  return randomBytes(16).toString("hex");
+}
+
+// src/bootstrap.ts
+var SUPPORTED_VERSIONS = [ProtocolVersion];
+async function runPlugin(handlers) {
+  const { pipePath, token } = await readBootstrapLine();
+  const transport = new NodeTransport();
+  await transport.connect(pipePath);
+  const identity = await completeHandshake(transport, token);
+  const router = new HandlerRouter({ send: (env) => transport.send(env) });
+  router.setIdentity(identity);
+  const HOST_LOST_MS = 15e3;
+  let lastPingAt = Date.now();
+  const watchdog = setInterval(() => {
+    if (Date.now() - lastPingAt > HOST_LOST_MS) {
+      clearInterval(watchdog);
+      process.exit(1);
+    }
+  }, 1e3);
+  watchdog.unref?.();
+  transport.onDisconnect(() => {
+    clearInterval(watchdog);
+    process.exit(1);
+  });
+  transport.onMessage((env) => {
+    if (env.route === Routes.Bus.Ping) lastPingAt = Date.now();
+    router.dispatch(env);
+  });
+  for (const [route, handler] of Object.entries(handlers)) {
+    router.handle(route, handler);
+  }
+  return {
+    transport,
+    router,
+    close: async () => {
+      clearInterval(watchdog);
+      await transport.close();
+    }
+  };
+}
+async function readBootstrapLine() {
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  try {
+    const line = await new Promise((resolve, reject) => {
+      rl.once("line", (l) => resolve(l));
+      rl.once("close", () => reject(new Error("stdin closed before bootstrap line")));
+    });
+    const [pipePath, token] = line.split("	");
+    if (!pipePath || !token) {
+      throw new Error(`malformed bootstrap line: ${JSON.stringify(line)}`);
+    }
+    return { pipePath, token };
+  } finally {
+    rl.close();
+  }
+}
+async function completeHandshake(transport, token, timeoutMs = 1e4) {
+  const id = randomBytes2(16).toString("hex");
+  const req = {
+    version: ProtocolVersion,
+    id,
+    traceId: id,
+    sessionId: "",
+    pluginId: "",
+    entryId: "",
+    endpointId: EndpointIds.NodeMain,
+    kind: MessageKind.Request,
+    route: Routes.Bus.Handshake,
+    timeoutMs,
+    payload: {
+      version: ProtocolVersion,
+      supportedVersions: SUPPORTED_VERSIONS,
+      token
+    }
+  };
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      unsubscribe();
+      reject(new Error(`bus.handshake timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    const unsubscribe = transport.onMessage((env) => {
+      if (env.kind !== MessageKind.Response || env.correlationId !== id) return;
+      clearTimeout(timer);
+      unsubscribe();
+      if (env.error) {
+        reject(new Error(`${env.error.code}: ${env.error.message}`));
+        return;
+      }
+      const p = env.payload ?? {};
+      const pluginId = String(p.pluginId ?? "");
+      const entryId = String(p.entryId ?? "");
+      const sessionId = String(p.sessionId ?? "");
+      const endpointId = String(p.endpointId ?? EndpointIds.NodeMain);
+      if (!pluginId || !entryId || !sessionId) {
+        reject(new Error("bus.handshake success response missing bound identity"));
+        return;
+      }
+      resolve({ pluginId, entryId, sessionId, endpointId });
+    });
+    transport.send(req);
+  });
+}
+
+// src/hostEnv.ts
+function asTheme(value) {
+  return value === "light" ? "light" : "dark";
+}
+function asHostEnv(payload) {
+  return {
+    locale: typeof payload?.locale === "string" ? payload.locale : "en-US",
+    fallbackLocale: typeof payload?.fallbackLocale === "string" ? payload.fallbackLocale : "en-US",
+    theme: asTheme(payload?.theme)
+  };
+}
+
+// src/actions.ts
+var Key = {
+  Enter: "Enter",
+  Tab: "Tab",
+  Space: "Space",
+  Delete: "Delete",
+  Backspace: "Backspace",
+  Escape: "Escape",
+  Left: "Left",
+  Right: "Right",
+  Up: "Up",
+  Down: "Down",
+  A: "A",
+  B: "B",
+  C: "C",
+  D: "D",
+  E: "E",
+  F: "F",
+  G: "G",
+  H: "H",
+  I: "I",
+  J: "J",
+  K: "K",
+  L: "L",
+  M: "M",
+  N: "N",
+  O: "O",
+  P: "P",
+  Q: "Q",
+  R: "R",
+  S: "S",
+  T: "T",
+  U: "U",
+  V: "V",
+  W: "W",
+  X: "X",
+  Y: "Y",
+  Z: "Z",
+  D0: "D0",
+  D1: "D1",
+  D2: "D2",
+  D3: "D3",
+  D4: "D4",
+  D5: "D5",
+  D6: "D6",
+  D7: "D7",
+  D8: "D8",
+  D9: "D9",
+  F1: "F1",
+  F2: "F2",
+  F3: "F3",
+  F4: "F4",
+  F5: "F5",
+  F6: "F6",
+  F7: "F7",
+  F8: "F8",
+  F9: "F9",
+  F10: "F10",
+  F11: "F11",
+  F12: "F12"
+};
+var Modifiers = {
+  None: 0,
+  Control: 1,
+  Alt: 2,
+  ControlAlt: 3,
+  Shift: 4,
+  ControlShift: 5,
+  AltShift: 6,
+  ControlAltShift: 7
+};
+var HostAction = {
+  Copy: "copy",
+  CopyAndPaste: "copyAndPaste",
+  AddClipboardHistory: "addClipboardHistory",
+  Execute: "execute",
+  OpenInExplorer: "openInExplorer",
+  OpenInBrowser: "openInBrowser",
+  OpenPlugin: "openPlugin",
+  Run: "run",
+  Kill: "kill"
+};
+function toActionManifest(definition) {
+  const entry = {
+    id: definition.id,
+    title: definition.title
+  };
+  if (definition.description) entry.description = definition.description;
+  if (definition.hotkey) entry.hotkey = definition.hotkey;
+  return entry;
+}
+
+// src/node.ts
+var ItemCacheLimit = 1e3;
+var SessionCacheLimit = 8;
+var Plugin = class {
+  #handlers = /* @__PURE__ */ new Map();
+  #actions = /* @__PURE__ */ new Map();
+  #searchHandler = null;
+  #initializeHandler = null;
+  #runtime = null;
+  #itemsBySession = /* @__PURE__ */ new Map();
+  initialize(handler) {
+    this.#initializeHandler = handler;
+    return this;
+  }
+  search(handler) {
+    this.#searchHandler = handler;
+    return this;
+  }
+  /**
+   * Registers every action this plugin offers. The list is sent to the host in the initialize
+   * response, so the host knows the ids, labels and hotkeys before any search runs; search items
+   * and the detail page then reference them by id only.
+   */
+  actions(definitions) {
+    if (!Array.isArray(definitions)) {
+      throw new Error("plugin.actions requires an array of action definitions.");
+    }
+    for (const definition of definitions) {
+      if (!definition?.id) {
+        throw new Error("plugin.actions requires every action to have an id.");
+      }
+      if (this.#actions.has(definition.id)) {
+        throw new Error(`plugin.actions has a duplicate action id: ${definition.id}`);
+      }
+      if (typeof definition.execute !== "function") {
+        throw new Error(`plugin.actions requires an execute function for action: ${definition.id}`);
+      }
+      this.#actions.set(definition.id, definition);
+    }
+    return this;
+  }
+  handle(action, handler) {
+    if (!action || typeof action !== "string") {
+      throw new Error("plugin.handle requires an action name.");
+    }
+    if (typeof handler !== "function") {
+      throw new Error("plugin.handle requires a handler.");
+    }
+    this.#handlers.set(action, handler);
+    return this;
+  }
+  /** Publishes a plugin.event.<subjectId> event to all webviews in the session. */
+  publish(subjectId, payload = {}) {
+    if (!this.#runtime) throw new Error("plugin not started");
+    const route = pluginEventRoute(subjectId);
+    this.#runtime.transport.send({
+      version: ProtocolVersion,
+      id: crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+      traceId: crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+      sessionId: "",
+      pluginId: "",
+      entryId: "",
+      endpointId: EndpointIds.NodeMain,
+      kind: MessageKind.Event,
+      route,
+      payload
+    });
+  }
+  /** Calls a host.call.<method> capability and awaits the response.
+   *  `timeoutMs` defaults to the remaining timeout of the inbound plugin.call
+   *  (from a page `bus.call`) when inside a handler; otherwise 30s.
+   */
+  hostCall(method, params = {}, timeoutMs) {
+    if (!this.#runtime) return Promise.reject(new Error("plugin not started"));
+    return this.#runtime.router.callHost(hostCallRoute(method), params, timeoutMs);
+  }
+  /** Connects to the host pipe and begins dispatching. Must be called last. */
+  async start() {
+    const routes = this.buildRoutes();
+    this.#runtime = await runPlugin(routes);
+  }
+  /**
+   * Builds the v3 route map from the fluent registrations. Exposed for unit testing the mapping
+   * without connecting a pipe.
+   */
+  buildRoutes() {
+    const routes = {};
+    routes[Routes.PluginCall.Initialize] = async (p) => {
+      const result = this.#initializeHandler ? await this.#initializeHandler(asInitializeParams(p)) : {};
+      const body = result && typeof result === "object" ? { ...result } : {};
+      return { ...body, actions: [...this.#actions.values()].map(toActionManifest) };
+    };
+    if (this.#searchHandler) {
+      routes[Routes.PluginCall.Search] = async (p, request) => {
+        const result = await this.#searchHandler(asSearchParams(p));
+        return { items: this.#trackItems(request?.sessionId ?? "default", result?.items ?? []) };
+      };
+    }
+    if (this.#actions.size > 0) {
+      routes[Routes.PluginCall.InvokeAction] = (p, request) => this.#invokeAction(request?.sessionId ?? "default", p);
+    }
+    for (const [action, handler] of this.#handlers) {
+      const route = pluginCallRoute(action);
+      if (!routes[route]) {
+        routes[route] = async (p) => {
+          const ctx = extractContext(p, action);
+          return handler(p ?? {}, ctx);
+        };
+      }
+    }
+    return routes;
+  }
+  async stop() {
+    if (this.#runtime) await this.#runtime.close();
+  }
+  /** Remembers the full items and returns the trimmed rows the host actually renders. */
+  #trackItems(sessionId, items) {
+    const sessionItems = this.#sessionItems(sessionId);
+    const wire = [];
+    for (const item of items) {
+      if (!item || typeof item !== "object") continue;
+      const id = typeof item.id === "string" ? item.id : "";
+      if (id) {
+        sessionItems.delete(id);
+        sessionItems.set(id, item);
+      }
+      wire.push(toWireItem(item));
+    }
+    while (sessionItems.size > ItemCacheLimit) {
+      const oldest = sessionItems.keys().next();
+      if (oldest.done) break;
+      sessionItems.delete(oldest.value);
+    }
+    return wire;
+  }
+  async #invokeAction(sessionId, payload) {
+    const env = asHostEnv(payload);
+    const actionId = typeof payload?.actionId === "string" ? payload.actionId : "";
+    const itemId = typeof payload?.itemId === "string" ? payload.itemId : "";
+    const query = typeof payload?.query === "string" ? payload.query : "";
+    const definition = this.#actions.get(actionId);
+    if (!definition) {
+      throw new Error(`unknown action: ${actionId}`);
+    }
+    const outcome = await definition.execute({
+      ...env,
+      actionId,
+      itemId,
+      query,
+      item: this.#itemsBySession.get(sessionId)?.get(itemId)
+    });
+    return outcome ?? {};
+  }
+  #sessionItems(sessionId) {
+    const key = sessionId || "default";
+    let items = this.#itemsBySession.get(key);
+    if (!items) {
+      items = /* @__PURE__ */ new Map();
+      this.#itemsBySession.set(key, items);
+      while (this.#itemsBySession.size > SessionCacheLimit) {
+        const oldest = this.#itemsBySession.keys().next();
+        if (oldest.done) break;
+        this.#itemsBySession.delete(oldest.value);
+      }
+    }
+    return items;
+  }
+};
+function toWireItem(item) {
+  const wire = {
+    id: item.id,
+    title: item.title
+  };
+  if (typeof item.subtitle === "string") wire.subtitle = item.subtitle;
+  if (typeof item.priority === "number") wire.priority = item.priority;
+  if (item.icon) wire.icon = item.icon;
+  if (Array.isArray(item.actions)) wire.actions = item.actions.filter((id) => typeof id === "string");
+  return wire;
+}
+function asInitializeParams(p) {
+  const messages = p?.messages;
+  return {
+    ...asHostEnv(p),
+    messages: isStringRecord(messages) ? messages : {}
+  };
+}
+function asSearchParams(p) {
+  return {
+    ...asHostEnv(p),
+    query: typeof p?.query === "string" ? p.query : "",
+    mode: p?.mode === "plugin" ? "plugin" : "global"
+  };
+}
+function isStringRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((v) => typeof v === "string");
+}
+function extractContext(p, action) {
+  return {
+    ...asHostEnv(p),
+    action,
+    itemId: typeof p?.itemId === "string" ? p.itemId : "",
+    query: typeof p?.query === "string" ? p.query : ""
+  };
+}
+function createPlugin() {
+  return new Plugin();
+}
+export {
+  HostAction,
+  Key,
+  Modifiers,
+  Plugin,
+  createPlugin
+};