@decocms/mesh-sdk 1.2.2 → 1.2.3

package/src/lib/bridge-transport.ts

@@ -1,434 +1,6 @@
-import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
-import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-
-/**
- * Bridge MCP Transport
- *
- * High-performance bridge transport for MCP communication within the same process.
- * Uses direct callbacks with microtask scheduling to avoid serialization overhead
- * and minimize event loop impact.
- *
- * ## Design
- *
- * - **Zero serialization**: Messages are passed as JavaScript objects by reference
- * - **Microtask scheduling**: Uses `queueMicrotask` to avoid deep recursion while
- *   maintaining message ordering
- * - **Direct callbacks**: No Web API overhead (EventTarget, MessageChannel, etc.)
- *
- * ## Usage
- *
- * ```ts
- * import { createBridgeTransportPair } from "@decocms/mesh-sdk";
- * import { Client } from "@modelcontextprotocol/sdk/client/index.js";
- * import { Server } from "@modelcontextprotocol/sdk/server/index.js";
- *
- * const { client: clientTransport, server: serverTransport } =
- *   createBridgeTransportPair();
- *
- * const client = new Client({ name: "test-client", version: "1.0.0" });
- * const server = new Server({ name: "test-server", version: "1.0.0" });
- *
- * await server.connect(serverTransport);
- * await client.connect(clientTransport);
- *
- * // Now client and server can communicate via bridge
- * ```
- */
-
-type TransportSide = "client" | "server";
-
-/**
- * Maximum number of messages that can be queued before throwing an error.
- * This prevents unbounded memory growth if one side sends faster than the other processes.
- */
-const MAX_QUEUE_SIZE = 10_000;
-
-/**
- * Internal channel that manages bidirectional message queues between client and server.
- */
-class BridgeChannel {
-  private clientQueue: JSONRPCMessage[] = [];
-  private serverQueue: JSONRPCMessage[] = [];
-  private clientClosed = false;
-  private serverClosed = false;
-  private clientFlushScheduled = false;
-  private serverFlushScheduled = false;
-
-  // Use type-only forward reference to avoid circular dependency
-  private clientTransport?: { deliverMessage(message: JSONRPCMessage): void };
-  private serverTransport?: { deliverMessage(message: JSONRPCMessage): void };
-
-  /**
-   * Register transports with the channel and link them to each other.
-   * This sets up both message delivery and close notifications.
-   */
-  registerTransports(
-    client: BridgeClientTransport,
-    server: BridgeServerTransport,
-  ): void {
-    this.clientTransport = client;
-    this.serverTransport = server;
-    // Link transports to each other for close notifications
-    client.setOppositeTransport(server);
-    server.setOppositeTransport(client);
-  }
-
-  /**
-   * Get the queue for a specific side (opposite of sender)
-   */
-  private getQueue(side: TransportSide): JSONRPCMessage[] {
-    return side === "client" ? this.clientQueue : this.serverQueue;
-  }
-
-  /**
-   * Check if the target side is closed
-   */
-  isClosed(side: TransportSide): boolean {
-    return side === "client" ? this.clientClosed : this.serverClosed;
-  }
-
-  /**
-   * Mark a side as closed
-   */
-  close(side: TransportSide): void {
-    if (side === "client") {
-      this.clientClosed = true;
-      this.clientQueue = [];
-    } else {
-      this.serverClosed = true;
-      this.serverQueue = [];
-    }
-  }
-
-  /**
-   * Enqueue a message to the target side's queue
-   * @throws Error if queue size exceeds MAX_QUEUE_SIZE
-   */
-  enqueue(side: TransportSide, message: JSONRPCMessage): void {
-    if (this.isClosed(side)) {
-      // Silent no-op when target is closed (matches stdio transport behavior)
-      return;
-    }
-
-    const queue = this.getQueue(side);
-
-    // Prevent unbounded memory growth
-    if (queue.length >= MAX_QUEUE_SIZE) {
-      throw new Error(
-        `BridgeTransport: ${side} queue overflow (max ${MAX_QUEUE_SIZE} messages). ` +
-          "The receiver may not be processing messages fast enough.",
-      );
-    }
-
-    queue.push(message);
-
-    // Schedule flush if not already scheduled
-    if (side === "client" && !this.clientFlushScheduled) {
-      this.scheduleFlush("client");
-    } else if (side === "server" && !this.serverFlushScheduled) {
-      this.scheduleFlush("server");
-    }
-  }
-
-  /**
-   * Schedule a flush operation for the given side using microtask scheduling.
-   * This frees the event loop and prevents deep recursion.
-   */
-  private scheduleFlush(side: TransportSide): void {
-    if (side === "client") {
-      this.clientFlushScheduled = true;
-    } else {
-      this.serverFlushScheduled = true;
-    }
-
-    queueMicrotask(() => {
-      this.flush(side);
-    });
-  }
-
-  /**
-   * Flush all messages from the queue for a specific side
-   * and deliver them to the appropriate transport
-   */
-  flush(side: TransportSide): void {
-    const queue = this.getQueue(side);
-
-    // Reset scheduled flag
-    if (side === "client") {
-      this.clientFlushScheduled = false;
-    } else {
-      this.serverFlushScheduled = false;
-    }
-
-    // If closed, clear queue and return
-    if (this.isClosed(side)) {
-      queue.length = 0;
-      return;
-    }
-
-    // Get the transport for this side
-    const transport =
-      side === "client" ? this.clientTransport : this.serverTransport;
-
-    if (!transport) {
-      // Transport not registered yet, messages will be processed when it starts
-      return;
-    }
-
-    // Drain queue in FIFO order and deliver to transport
-    // Continue draining even if transport isn't ready yet - deliverMessage will check
-    while (queue.length > 0) {
-      const message = queue.shift()!;
-      transport.deliverMessage(message);
-    }
-  }
-
-  /**
-   * Close both sides of the channel
-   */
-  closeBoth(): void {
-    this.close("client");
-    this.close("server");
-  }
-}
-
-/**
- * Base transport implementation shared by client and server transports
- */
-abstract class BaseBridgeTransport implements Transport {
-  protected channel: BridgeChannel;
-  protected side: TransportSide;
-  protected started = false;
-  protected closed = false;
-  private _onmessage?: (message: JSONRPCMessage) => void;
-  private _onerror?: (error: Error) => void;
-  private _onclose?: () => void;
-
-  constructor(channel: BridgeChannel, side: TransportSide) {
-    this.channel = channel;
-    this.side = side;
-  }
-
-  get onmessage(): ((message: JSONRPCMessage) => void) | undefined {
-    return this._onmessage;
-  }
-
-  set onmessage(fn: ((message: JSONRPCMessage) => void) | undefined) {
-    this._onmessage = fn;
-    // If transport is started and onmessage is set, flush any queued messages
-    if (fn && this.started && !this.closed) {
-      this.channel.flush(this.side);
-    }
-  }
-
-  get onerror(): ((error: Error) => void) | undefined {
-    return this._onerror;
-  }
-
-  set onerror(fn: ((error: Error) => void) | undefined) {
-    this._onerror = fn;
-  }
-
-  get onclose(): (() => void) | undefined {
-    return this._onclose;
-  }
-
-  set onclose(fn: (() => void) | undefined) {
-    this._onclose = fn;
-  }
-
-  /**
-   * Start the transport. For bridge transports, this is a no-op
-   * but required by the Transport interface.
-   */
-  async start(): Promise<void> {
-    if (this.started) {
-      throw new Error(
-        `${this.side === "client" ? "BridgeClientTransport" : "BridgeServerTransport"} already started! If using Client/Server class, note that connect() calls start() automatically.`,
-      );
-    }
-    this.started = true;
-    // Process any messages that were queued before start
-    // If onmessage is already set, flush immediately; otherwise it will flush when onmessage is set
-    if (this._onmessage && !this.closed) {
-      this.channel.flush(this.side);
-    }
-  }
-
-  /**
-   * Send a message to the opposite side
-   */
-  async send(message: JSONRPCMessage): Promise<void> {
-    if (this.closed) {
-      // Silent no-op when transport is closed (matches stdio transport behavior)
-      return Promise.resolve();
-    }
-
-    const targetSide: TransportSide =
-      this.side === "client" ? "server" : "client";
-    this.channel.enqueue(targetSide, message);
-
-    // Resolve immediately - message delivery is async via microtask
-    return Promise.resolve();
-  }
-
-  /**
-   * Close the transport
-   */
-  async close(): Promise<void> {
-    if (!this.started || this.closed) {
-      return;
-    }
-
-    this.closed = true;
-    this.channel.close(this.side);
-
-    // Notify opposite side that we closed
-    const oppositeTransport = this.getOppositeTransport();
-    if (oppositeTransport && !oppositeTransport.closed) {
-      oppositeTransport._onclose?.();
-    }
-
-    this._onclose?.();
-  }
-
-  /**
-   * Get reference to the opposite transport (set by factory)
-   */
-  protected abstract getOppositeTransport(): BaseBridgeTransport | undefined;
-
-  /**
-   * Set reference to opposite transport (called by factory)
-   */
-  abstract setOppositeTransport(transport: BaseBridgeTransport): void;
-
-  /**
-   * Internal method to deliver a message to this transport
-   * Called by the channel during flush operations
-   */
-  deliverMessage(message: JSONRPCMessage): void {
-    if (!this.started || this.channel.isClosed(this.side)) {
-      return;
-    }
-
-    try {
-      this._onmessage?.(message);
-    } catch (error) {
-      this._onerror?.(error as Error);
-    }
-  }
-}
-
-/**
- * Client-side bridge transport
- */
-export class BridgeClientTransport extends BaseBridgeTransport {
-  private oppositeTransport?: BridgeServerTransport;
-
-  constructor(channel: BridgeChannel) {
-    super(channel, "client");
-  }
-
-  protected getOppositeTransport(): BaseBridgeTransport | undefined {
-    return this.oppositeTransport;
-  }
-
-  setOppositeTransport(transport: BaseBridgeTransport): void {
-    if (!(transport instanceof BridgeServerTransport)) {
-      throw new Error("Opposite transport must be BridgeServerTransport");
-    }
-    this.oppositeTransport = transport;
-  }
-
-  override async start(): Promise<void> {
-    await super.start();
-    // Callbacks will be set by MCP SDK after start()
-    // We use property setters to sync them with internal handlers
-  }
-
-  override async send(message: JSONRPCMessage): Promise<void> {
-    await super.send(message);
-  }
-}
-
-/**
- * Server-side bridge transport
- */
-export class BridgeServerTransport extends BaseBridgeTransport {
-  private oppositeTransport?: BridgeClientTransport;
-
-  constructor(channel: BridgeChannel) {
-    super(channel, "server");
-  }
-
-  protected getOppositeTransport(): BaseBridgeTransport | undefined {
-    return this.oppositeTransport;
-  }
-
-  setOppositeTransport(transport: BaseBridgeTransport): void {
-    if (!(transport instanceof BridgeClientTransport)) {
-      throw new Error("Opposite transport must be BridgeClientTransport");
-    }
-    this.oppositeTransport = transport;
-  }
-
-  override async start(): Promise<void> {
-    await super.start();
-    // Callbacks will be set by MCP SDK after start()
-    // We use property setters to sync them with internal handlers
-  }
-
-  override async send(message: JSONRPCMessage): Promise<void> {
-    await super.send(message);
-  }
-}
-
-/**
- * Result of creating a bridge transport pair
- */
-export interface BridgeTransportPair {
-  /**
-   * Client-side transport (for MCP Client)
-   */
-  client: BridgeClientTransport;
-  /**
-   * Server-side transport (for MCP Server)
-   */
-  server: BridgeServerTransport;
-  /**
-   * Internal channel (for advanced use cases)
-   */
-  channel: BridgeChannel;
-}
-
-/**
- * Create a pair of bridge transports for client-server communication.
- *
- * Uses microtask scheduling for message delivery, which frees the event loop
- * and prevents deep recursion while maintaining message ordering.
- *
- * @returns A pair of transports connected via a bridge channel
- *
- * @example
- * ```ts
- * const { client, server } = createBridgeTransportPair();
- *
- * const mcpClient = new Client({ name: "test", version: "1.0.0" });
- * const mcpServer = new Server({ name: "test", version: "1.0.0" });
- *
- * await mcpServer.connect(server);
- * await mcpClient.connect(client);
- *
- * // Now client and server can communicate via bridge
- * ```
- */
-export function createBridgeTransportPair(): BridgeTransportPair {
-  const channel = new BridgeChannel();
-  const client = new BridgeClientTransport(channel);
-  const server = new BridgeServerTransport(channel);
-
-  // Register transports with channel (also links them for close notifications)
-  channel.registerTransports(client, server);
-
-  return { client, server, channel };
-}
+export {
+  createBridgeTransportPair,
+  BridgeClientTransport,
+  BridgeServerTransport,
+  type BridgeTransportPair,
+} from "@decocms/mcp-utils";

package/src/lib/constants.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { StudioPackAgentId, isStudioPackAgent } from "./constants";
+
+describe("StudioPackAgentId", () => {
+  test("generates the Store Manager id with the org suffix", () => {
+    expect(StudioPackAgentId.STORE_MANAGER("org_xyz")).toBe(
+      "studio-store-manager_org_xyz",
+    );
+  });
+});
+
+describe("isStudioPackAgent", () => {
+  test("recognises every studio-pack manager id, including the new store-manager", () => {
+    expect(isStudioPackAgent("studio-agent-manager_org_xyz")).toBe(true);
+    expect(isStudioPackAgent("studio-automation-manager_org_xyz")).toBe(true);
+    expect(isStudioPackAgent("studio-connection-manager_org_xyz")).toBe(true);
+    expect(isStudioPackAgent("studio-store-manager_org_xyz")).toBe(true);
+  });
+
+  test("rejects unrelated ids", () => {
+    expect(isStudioPackAgent(null)).toBe(false);
+    expect(isStudioPackAgent(undefined)).toBe(false);
+    expect(isStudioPackAgent("vir_abc")).toBe(false);
+    expect(isStudioPackAgent("decopilot_org_xyz")).toBe(false);
+  });
+});

package/src/lib/constants.ts

@@ -26,6 +26,8 @@ export const WellKnownOrgMCPId = {
   COMMUNITY_REGISTRY: (org: string) => `${org}_community-registry`,
   /** Dev Assets MCP - local file storage for development */
   DEV_ASSETS: (org: string) => `${org}_dev-assets`,
+  /** Site Diagnostics agent (note: prefix-first format, not org-first) */
+  SITE_DIAGNOSTICS: (org: string) => `site-diagnostics_${org}`,
 };
 
 /**
@@ -84,7 +86,7 @@ export function getWellKnownCommunityRegistryConnection(): ConnectionCreateData
     title: "MCP Registry",
     description: "Community MCP registry with thousands of handy MCPs",
     connection_type: "HTTP",
-    connection_url: "https://sites-registry.decocache.com/mcp",
+    connection_url: "https://sites-registry.deco.site/mcp",
     icon: "https://assets.decocache.com/decocms/cd7ca472-0f72-463a-b0de-6e44bdd0f9b4/mcp.png",
     app_name: "mcp-registry",
     app_id: null,
@@ -169,38 +171,6 @@ export function getWellKnownDevAssetsConnection(
   };
 }
 
-/**
- * Get well-known connection definition for OpenRouter.
- * Used by the chat UI to offer a one-click install when no model provider is connected.
- */
-export function getWellKnownOpenRouterConnection(
-  opts: { id?: string } = {},
-): ConnectionCreateData {
-  return {
-    id: opts.id,
-    title: "OpenRouter",
-    description: "Access hundreds of LLM models from a single API",
-    icon: "https://assets.decocache.com/decocms/b2e2f64f-6025-45f7-9e8c-3b3ebdd073d8/openrouter_logojpg.jpg",
-    app_name: "openrouter",
-    app_id: "openrouter",
-    connection_type: "HTTP",
-    connection_url: "https://sites-openrouter.decocache.com/mcp",
-    connection_token: null,
-    connection_headers: null,
-    oauth_config: null,
-    configuration_state: null,
-    configuration_scopes: null,
-    metadata: {
-      source: "chat",
-      verified: false,
-      scopeName: "deco",
-      toolsCount: 0,
-      publishedAt: null,
-      repository: null,
-    },
-  };
-}
-
 /**
  * Get well-known connection definition for MCP Studio.
  * Used by agents and workflows pages to offer installation when no provider is connected.
@@ -227,57 +197,141 @@ export function getWellKnownMcpStudioConnection(): ConnectionCreateData {
 }
 
 /**
- * Get well-known Decopilot Virtual MCP entity.
- * This is the default agent that aggregates ALL org connections.
+ * Build a paired `{ is, get }` helper for an org-scoped well-known agent id
+ * of shape `${prefix}${orgId}`. Centralizes the trivial check/slice/format
+ * logic that every well-known agent used to hand-roll.
  *
- * @param organizationId - Organization ID
- * @returns VirtualMCPEntity representing the Decopilot agent
+ * `is(id)` returns the orgId when `id` matches the prefix; `null` otherwise.
+ * `get(orgId)` mints the well-known id.
  */
-export function getWellKnownDecopilotVirtualMCP(
-  organizationId: string,
-): VirtualMCPEntity {
+function createWellKnownAgentPrefix(prefix: string): {
+  is: (id: string | null | undefined) => string | null;
+  get: (organizationId: string) => string;
+} {
   return {
-    id: getDecopilotId(organizationId),
-    organization_id: organizationId,
-    title: "Decopilot",
-    description: "Default agent that aggregates all organization connections",
-    icon: "https://assets.decocache.com/decocms/fd07a578-6b1c-40f1-bc05-88a3b981695d/f7fc4ffa81aec04e37ae670c3cd4936643a7b269.png",
+    is(id) {
+      if (!id) return null;
+      if (!id.startsWith(prefix)) return null;
+      return id.slice(prefix.length) || null;
+    },
+    get(organizationId) {
+      return `${prefix}${organizationId}`;
+    },
+  };
+}
+
+/**
+ * Build a well-known agent VirtualMCPEntity with sensible defaults
+ * (status active, system creator, empty connections, etc.). Only the
+ * id/title/description/icon and optional instructions vary across agents.
+ */
+function defineWellKnownAgentVMCP(opts: {
+  id: string;
+  organizationId: string;
+  title: string;
+  description: string;
+  icon: string;
+  instructions?: string | null;
+}): VirtualMCPEntity {
+  return {
+    id: opts.id,
+    organization_id: opts.organizationId,
+    title: opts.title,
+    description: opts.description,
+    icon: opts.icon,
     status: "active",
     created_at: new Date().toISOString(),
     updated_at: new Date().toISOString(),
     created_by: "system",
     updated_by: undefined,
-    metadata: { instructions: null },
-    subtype: null,
-    connections: [], // Empty connections array - gateway.ts will populate with all org connections
+    metadata: { instructions: opts.instructions ?? null },
+    pinned: false,
+    connections: [],
   };
 }
 
-/**
- * Decopilot ID prefix constant
- */
-const DECOPILOT_PREFIX = "decopilot_";
+// ---- Decopilot ----
+// Default agent that aggregates ALL org connections. Gateway populates
+// the connections array at lookup time.
+const decopilotPrefix = createWellKnownAgentPrefix("decopilot_");
+export const isDecopilot = decopilotPrefix.is;
+export const getDecopilotId = decopilotPrefix.get;
+
+export function getWellKnownDecopilotVirtualMCP(
+  organizationId: string,
+): VirtualMCPEntity {
+  return defineWellKnownAgentVMCP({
+    id: getDecopilotId(organizationId),
+    organizationId,
+    title: "Decopilot",
+    description: "Default agent that aggregates all organization connections",
+    icon: "https://assets.decocache.com/decocms/fd07a578-6b1c-40f1-bc05-88a3b981695d/f7fc4ffa81aec04e37ae670c3cd4936643a7b269.png",
+  });
+}
+
+// ---- Brand-Context Setup ----
+// Guided-onboarding agent for the brand-context preset task. The
+// `brand_context_setup` built-in is injected by `dispatchRun` when this
+// id is seen; the system prompt lives in `metadata.instructions`.
+const brandContextSetupPrefix = createWellKnownAgentPrefix(
+  "brand-context-setup_",
+);
+export const isBrandContextSetup = brandContextSetupPrefix.is;
+export const getBrandContextSetupId = brandContextSetupPrefix.get;
+
+const BRAND_CONTEXT_SETUP_INSTRUCTIONS = `
+You are running the brand-context onboarding for the user's organization. Your only job in this thread is to set up the organization's brand context:
+
+1. If the user hasn't already given you a website URL, ask for it in one short message. Accept whatever URL they give — don't quibble about format.
+2. As soon as you have a URL, call the \`brand_context_setup\` tool exactly once with that URL.
+3. After the tool returns success, briefly confirm to the user what was captured (brand name + domain) in one or two sentences. Do not list every color or font.
+4. Do NOT call any other tools in this thread. Do NOT call \`brand_context_setup\` more than once.
+
+If the tool returns an error, surface the error message to the user and ask whether they want to try a different URL.
+`.trim();
+
+export function getWellKnownBrandContextSetupVirtualMCP(
+  organizationId: string,
+): VirtualMCPEntity {
+  return defineWellKnownAgentVMCP({
+    id: getBrandContextSetupId(organizationId),
+    organizationId,
+    title: "Brand context setup",
+    description:
+      "Guided onboarding agent that extracts brand context from a website URL.",
+    icon: "https://assets.decocache.com/decocms/fd07a578-6b1c-40f1-bc05-88a3b981695d/f7fc4ffa81aec04e37ae670c3cd4936643a7b269.png",
+    instructions: BRAND_CONTEXT_SETUP_INSTRUCTIONS,
+  });
+}
+
+// ---- Site Diagnostics ----
+const siteDiagnosticsPrefix = createWellKnownAgentPrefix("site-diagnostics_");
+export const isSiteDiagnostics = siteDiagnosticsPrefix.is;
+export const getSiteDiagnosticsId = siteDiagnosticsPrefix.get;
 
 /**
- * Check if a connection or virtual MCP ID is the Decopilot agent.
- *
- * @param id - Connection or virtual MCP ID to check
- * @returns The organization ID if the ID matches the Decopilot pattern (decopilot_{orgId}), null otherwise
+ * Studio Pack agent ID generators (org-scoped)
  */
-export function isDecopilot(id: string | null | undefined): string | null {
-  if (!id) return null;
-  if (!id.startsWith(DECOPILOT_PREFIX)) return null;
-  return id.slice(DECOPILOT_PREFIX.length) || null;
-}
+export const StudioPackAgentId = {
+  AGENT_MANAGER: (orgId: string) => `studio-agent-manager_${orgId}`,
+  AUTOMATION_MANAGER: (orgId: string) => `studio-automation-manager_${orgId}`,
+  CONNECTION_MANAGER: (orgId: string) => `studio-connection-manager_${orgId}`,
+  STORE_MANAGER: (orgId: string) => `studio-store-manager_${orgId}`,
+  BRAND_MANAGER: (orgId: string) => `studio-brand-manager_${orgId}`,
+} as const;
 
 /**
- * Get the Decopilot ID for a given organization.
- *
- * @param organizationId - Organization ID
- * @returns The Decopilot ID in the format `decopilot_{organizationId}`
+ * Check if a connection or virtual MCP ID is a Studio Pack agent.
  */
-export function getDecopilotId(organizationId: string): string {
-  return `${DECOPILOT_PREFIX}${organizationId}`;
+export function isStudioPackAgent(id: string | null | undefined): boolean {
+  if (!id) return false;
+  return (
+    id.startsWith("studio-agent-manager_") ||
+    id.startsWith("studio-automation-manager_") ||
+    id.startsWith("studio-connection-manager_") ||
+    id.startsWith("studio-store-manager_") ||
+    id.startsWith("studio-brand-manager_")
+  );
 }
 
 export function getWellKnownDecopilotConnection(