@decocms/bindings 1.2.0 → 1.3.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@decocms/bindings",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",
     "test": "bun test"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.25.3",
+    "@modelcontextprotocol/sdk": "1.26.0",
     "@tanstack/react-router": "1.139.7",
     "react": "^19.2.0",
     "zod": "^4.0.0",
@@ -35,6 +35,11 @@
   "engines": {
     "node": ">=24.0.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/decocms/mesh.git",
+    "directory": "packages/bindings"
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/core/client/mcp-client.ts

@@ -47,7 +47,7 @@ export interface ServerClient {
     callTool: Client["callTool"];
     listTools: () => Promise<ListToolsResult>;
   };
-  callStreamableTool: (
+  callStreamableTool?: (
     tool: string,
     args: Record<string, unknown>,
     signal?: AbortSignal,

package/src/core/client/proxy.ts

@@ -77,7 +77,12 @@ export function createMCPClientProxy<T extends Record<string, unknown>>(
         const { client, callStreamableTool } = await createClient(extraHeaders);
 
         if (options?.streamable?.[String(toolName)]) {
-          return callStreamableTool(String(toolName), args);
+          if (!callStreamableTool) {
+            throw new Error(
+              `Tool ${String(toolName)} requires streaming support but client doesn't provide callStreamableTool`,
+            );
+          }
+          return await callStreamableTool(String(toolName), args);
         }
 
         const { structuredContent, isError, content } = await client.callTool({
@@ -111,7 +116,17 @@ export function createMCPClientProxy<T extends Record<string, unknown>>(
             )}`,
           );
         }
-        return structuredContent;
+
+        // Prefer structuredContent, but fall back to parsing content[0].text
+        // structuredContent may be undefined if the response doesn't include it
+        // (e.g., SDK version mismatch, schema parsing stripping unknown fields)
+        if (structuredContent !== undefined) {
+          return structuredContent;
+        }
+        const textContent = (content as { text: string }[])?.[0]?.text;
+        return typeof textContent === "string"
+          ? safeParse(textContent)
+          : undefined;
       }
 
       async function listToolsFn() {

package/src/core/plugin-context-provider.tsx

@@ -1,37 +1,20 @@
 /**
- * Plugin Context Provider
+ * Plugin Context Provider Types
  *
- * React context provider and hook for accessing plugin context.
+ * The runtime implementations (PluginContextProvider, usePluginContext)
+ * have moved to @decocms/mesh-sdk/plugins. Only types remain here
+ * for backwards compatibility.
  */
 
-import { createContext, useContext, type ReactNode } from "react";
 import type { Binder } from "./binder";
 import type { PluginContext, PluginContextPartial } from "./plugin-context";
-
-// Internal context stores the partial version (nullable connection fields)
-// The hook return type depends on the options passed
-const PluginContextInternal = createContext<PluginContextPartial | null>(null);
+import type { ReactNode } from "react";
 
 export interface PluginContextProviderProps<TBinding extends Binder> {
   value: PluginContext<TBinding> | PluginContextPartial<TBinding>;
   children: ReactNode;
 }
 
-/**
- * Provider component for plugin context.
- * Used by the mesh app layout to provide context to plugin routes.
- */
-export function PluginContextProvider<TBinding extends Binder>({
-  value,
-  children,
-}: PluginContextProviderProps<TBinding>) {
-  return (
-    <PluginContextInternal.Provider value={value as PluginContextPartial}>
-      {children}
-    </PluginContextInternal.Provider>
-  );
-}
-
 /**
  * Options for usePluginContext hook.
  */
@@ -42,53 +25,3 @@ export interface UsePluginContextOptions {
    */
   partial?: boolean;
 }
-
-/**
- * Hook to access the plugin context with typed tool caller.
- *
- * @template TBinding - The binding type for typed tool calls
- * @param options - Optional settings
- * @param options.partial - Set to true in empty state components where connection may not exist
- * @throws Error if used outside of PluginContextProvider
- * @throws Error if connection is null but partial option is not set
- *
- * @example
- * ```tsx
- * // In route component (connection guaranteed by layout)
- * const { toolCaller, connection } = usePluginContext<typeof REGISTRY_APP_BINDING>();
- * const result = await toolCaller("COLLECTION_REGISTRY_APP_LIST", { limit: 20 });
- *
- * // In empty state component (no connection available)
- * const { session, org } = usePluginContext<typeof REGISTRY_APP_BINDING>({ partial: true });
- * ```
- */
-export function usePluginContext<TBinding extends Binder = Binder>(options: {
-  partial: true;
-}): PluginContextPartial<TBinding>;
-export function usePluginContext<
-  TBinding extends Binder = Binder,
->(): PluginContext<TBinding>;
-export function usePluginContext<TBinding extends Binder = Binder>(
-  options?: UsePluginContextOptions,
-): PluginContext<TBinding> | PluginContextPartial<TBinding> {
-  const context = useContext(PluginContextInternal);
-  if (!context) {
-    throw new Error(
-      "usePluginContext must be used within a PluginContextProvider",
-    );
-  }
-
-  // If partial mode, return as-is with nullable fields
-  if (options?.partial) {
-    return context as PluginContextPartial<TBinding>;
-  }
-
-  // Otherwise, assert that connection exists (routes should always have one)
-  if (!context.connectionId || !context.connection || !context.toolCaller) {
-    throw new Error(
-      "usePluginContext requires a valid connection. Use { partial: true } in empty state components.",
-    );
-  }
-
-  return context as PluginContext<TBinding>;
-}

package/src/core/plugin-router.tsx

@@ -17,19 +17,20 @@ import {
 import type { PluginSetupContext } from "./plugins";
 
 /**
- * Prepends the plugin base path (/$org/$pluginId) to a route path.
+ * Prepends the plugin base path (/$org/$project/$pluginId) to a route path.
  * Handles both absolute plugin paths (starting with /) and relative paths.
  */
 function prependBasePath(
   to: string | undefined,
   org: string,
+  project: string,
   pluginId: string,
 ): string {
-  if (!to) return `/${org}/${pluginId}`;
+  if (!to) return `/${org}/${project}/${pluginId}`;
 
   // If path starts with /, it's relative to the plugin root
   if (to.startsWith("/")) {
-    return `/${org}/${pluginId}${to}`;
+    return `/${org}/${project}/${pluginId}${to}`;
   }
 
   // Otherwise, it's already a full path or relative
@@ -122,8 +123,9 @@ export function createPluginRouter<TRoutes extends AnyRoute | AnyRoute[]>(
      */
     useNavigate: () => {
       const navigate = useNavigate();
-      const { org, pluginId } = useParams({ strict: false }) as {
+      const { org, project, pluginId } = useParams({ strict: false }) as {
         org: string;
+        project: string;
         pluginId: string;
       };
 
@@ -134,13 +136,14 @@ export function createPluginRouter<TRoutes extends AnyRoute | AnyRoute[]>(
           search?: TRouteById<TTo>["types"]["fullSearchSchema"];
         },
       ) => {
-        const to = prependBasePath(options.to, org, pluginId);
+        const to = prependBasePath(options.to, org, project, pluginId);
 
         return navigate({
           ...options,
           to,
           params: {
             org,
+            project,
             pluginId,
             ...(options.params as Record<string, string>),
           },
@@ -168,12 +171,13 @@ export function createPluginRouter<TRoutes extends AnyRoute | AnyRoute[]>(
         children?: ReactNode;
       },
     ) {
-      const { org, pluginId } = useParams({ strict: false }) as {
+      const { org, project, pluginId } = useParams({ strict: false }) as {
         org: string;
+        project: string;
         pluginId: string;
       };
 
-      const to = prependBasePath(props.to as string, org, pluginId);
+      const to = prependBasePath(props.to as string, org, project, pluginId);
 
       return (
         <TanStackLink
@@ -181,6 +185,7 @@ export function createPluginRouter<TRoutes extends AnyRoute | AnyRoute[]>(
           to={to}
           params={{
             org,
+            project,
             pluginId,
             ...props.params,
           }}

package/src/core/plugins.ts

@@ -18,6 +18,13 @@ export interface RegisterRootSidebarItemParams {
   label: string;
 }
 
+export interface RegisterSidebarGroupParams {
+  id: string;
+  label: string;
+  items: RegisterRootSidebarItemParams[];
+  defaultExpanded?: boolean;
+}
+
 export interface RegisterEmptyStateParams {
   component: ReactNode;
 }
@@ -29,6 +36,7 @@ export interface PluginSetupContext {
     lazyRouteComponent: typeof lazyRouteComponent;
   };
   registerRootSidebarItem: (params: RegisterRootSidebarItemParams) => void;
+  registerSidebarGroup: (params: RegisterSidebarGroupParams) => void;
   registerPluginRoutes: (route: AnyRoute[]) => void;
 }
 
@@ -50,13 +58,17 @@ export interface PluginRenderHeaderProps {
  * Client plugins are separate from server plugins to avoid bundling
  * server code into the client bundle.
  */
-export interface ClientPlugin<TBinding extends Binder> {
+export interface ClientPlugin<TBinding extends Binder = Binder> {
   id: string;
   /**
    * Short description of the plugin shown in the settings UI.
    */
   description?: string;
-  binding: TBinding;
+  /**
+   * Binding schema used to filter compatible connections.
+   * Omit for plugins that manage their own connection (e.g. self MCP).
+   */
+  binding?: TBinding;
   setup?: PluginSetup;
   /**
    * Optional custom layout component for this plugin.
@@ -96,10 +108,9 @@ export {
   type RouteById,
 } from "./plugin-router";
 
-// Re-export plugin context provider and hook (React components)
-export {
-  PluginContextProvider,
-  usePluginContext,
-  type PluginContextProviderProps,
-  type UsePluginContextOptions,
+// Note: PluginContextProvider and usePluginContext have been moved to @decocms/mesh-sdk/plugins.
+// Types are re-exported here for backwards compatibility.
+export type {
+  PluginContextProviderProps,
+  UsePluginContextOptions,
 } from "./plugin-context-provider";

package/src/core/server-plugin.ts

@@ -6,6 +6,7 @@
  * - API routes (authenticated and public)
  * - Database migrations
  * - Storage factories
+ * - Event handlers (via the event bus)
  *
  * Server plugins are separate from client plugins to avoid bundling
  * server code into the client bundle.
@@ -15,15 +16,45 @@ import type { Hono } from "hono";
 import type { Kysely } from "kysely";
 
 /**
- * Tool definition compatible with MCP tools.
- * This is a simplified type - the actual implementation uses the full ToolDefinition from mesh.
+ * Subset of MeshContext exposed to server plugin tool handlers.
+ *
+ * Plugins receive the full MeshContext at runtime but should only depend on
+ * these properties. This keeps the plugin contract stable and avoids coupling
+ * plugins to Mesh internals (db, vault, tracer, etc.).
+ */
+export interface ServerPluginToolContext {
+  organization: { id: string } | null;
+  access: { check: () => Promise<void> };
+  auth: {
+    user?: { id: string; email?: string; name?: string };
+  };
+  /** Kysely database instance for direct queries. */
+  db: Kysely<unknown>;
+  createMCPProxy: (connectionId: string) => Promise<{
+    callTool: (args: {
+      name: string;
+      arguments?: Record<string, unknown>;
+    }) => Promise<{
+      isError?: boolean;
+      content?: Array<{ type?: string; text?: string }>;
+      structuredContent?: unknown;
+    }>;
+    listTools: () => Promise<{
+      tools: Array<{ name: string; description?: string }>;
+    }>;
+    close?: () => Promise<void>;
+  }>;
+}
+
+/**
+ * Tool definition for server plugins.
  */
 export interface ServerPluginToolDefinition {
   name: string;
   description?: string;
   inputSchema: unknown;
   outputSchema?: unknown;
-  handler: (input: unknown, ctx: unknown) => Promise<unknown>;
+  handler: (input: unknown, ctx: ServerPluginToolContext) => Promise<unknown>;
 }
 
 /**
@@ -51,6 +82,63 @@ export interface ServerPluginContext {
   };
 }
 
+/**
+ * Event handler context provided to plugin event handlers.
+ * Contains the organization ID and a publish function for emitting follow-up events.
+ */
+export interface ServerPluginEventContext {
+  /** Organization ID the events belong to */
+  organizationId: string;
+  /** Connection ID of the SELF MCP for this organization */
+  connectionId: string;
+  /** Publish a follow-up event to the event bus */
+  publish: (
+    type: string,
+    subject: string,
+    data?: Record<string, unknown>,
+    options?: { deliverAt?: string },
+  ) => Promise<void>;
+  /** Create an MCP proxy client for calling tools on a connection */
+  createMCPProxy: (connectionId: string) => Promise<{
+    callTool: (
+      params: { name: string; arguments?: Record<string, unknown> },
+      resultSchema?: unknown,
+      options?: { timeout?: number },
+    ) => Promise<{
+      content?: unknown;
+      structuredContent?: unknown;
+      isError?: boolean;
+    }>;
+    close: () => Promise<void>;
+  }>;
+}
+
+/**
+ * Startup context provided to plugin onStartup hooks.
+ * Contains the database and a publish function for emitting recovery events.
+ */
+export interface ServerPluginStartupContext {
+  /** Database instance */
+  db: Kysely<unknown>;
+  /** Publish an event to the event bus for a given organization */
+  publish: (
+    organizationId: string,
+    event: { type: string; subject: string; data?: Record<string, unknown> },
+  ) => Promise<void>;
+}
+
+/**
+ * Event definition for a CloudEvent received by a plugin.
+ */
+export interface ServerPluginEvent {
+  id: string;
+  type: string;
+  source: string;
+  subject?: string;
+  data?: unknown;
+  time?: string;
+}
+
 /**
  * Server Plugin interface.
  *
@@ -95,6 +183,35 @@ export interface ServerPlugin {
    * Called during context initialization.
    */
   createStorage?: (ctx: ServerPluginContext) => unknown;
+
+  /**
+   * Event handler for this plugin.
+   *
+   * When defined, the system will:
+   * 1. Auto-subscribe the SELF connection to the specified event types per-organization
+   * 2. Route matching events from the event bus to this handler
+   *
+   * Events are durable (persisted in the event bus) with at-least-once delivery.
+   * The handler receives batches of events and a context for publishing follow-up events.
+   */
+  onEvents?: {
+    /** Event type patterns this plugin handles (e.g., "workflow.execution.created") */
+    types: string[];
+    /** Handle a batch of events. Errors are logged but don't affect other plugins. */
+    handler: (
+      events: ServerPluginEvent[],
+      ctx: ServerPluginEventContext,
+    ) => Promise<void> | void;
+  };
+
+  /**
+   * Startup hook called once after the event bus is ready.
+   *
+   * Use this to recover from crashes (e.g., resume stuck workflow executions).
+   * Called after storage is initialized and the event bus worker has started.
+   * Errors are logged but don't prevent other plugins from starting.
+   */
+  onStartup?: (ctx: ServerPluginStartupContext) => Promise<void>;
 }
 
 /**

package/src/index.ts

@@ -101,3 +101,6 @@ export {
   type DeleteObjectsInput,
   type DeleteObjectsOutput,
 } from "./well-known/object-storage";
+
+// Re-export workflow binding types
+export { WORKFLOWS_COLLECTION_BINDING } from "./well-known/workflow";

package/src/well-known/workflow.ts

@@ -79,6 +79,12 @@ export const StepConfigSchema = z.object({
     .number()
     .optional()
     .describe("Max execution time in ms before step fails (default: 30000)"),
+  onError: z
+    .enum(["fail", "continue"])
+    .optional()
+    .describe(
+      "What to do when this step fails: 'fail' aborts the workflow, 'continue' skips the error and proceeds",
+    ),
 });
 export type StepConfig = z.infer<typeof StepConfigSchema>;