@decocms/bindings 1.0.8 → 1.0.9

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@decocms/bindings",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",
     "test": "bun test"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.25.1",
+    "@modelcontextprotocol/sdk": "1.25.2",
+    "@tanstack/react-router": "1.139.7",
+    "react": "^19.2.0",
     "zod": "^4.0.0",
     "zod-from-json-schema": "^0.5.2"
   },
@@ -20,7 +22,9 @@
     "./mcp": "./src/well-known/mcp.ts",
     "./assistant": "./src/well-known/assistant.ts",
     "./prompt": "./src/well-known/prompt.ts",
-    "./workflow": "./src/well-known/workflow.ts"
+    "./workflow": "./src/well-known/workflow.ts",
+    "./plugins": "./src/core/plugins.ts",
+    "./plugin-router": "./src/core/plugin-router.tsx"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/core/binder.ts

@@ -177,3 +177,46 @@ export function createBindingChecker<TDefinition extends readonly ToolBinder[]>(
     },
   };
 }
+
+/**
+ * Generic connection type for binding checking.
+ * Any connection object with a tools array can be checked.
+ */
+export interface ConnectionForBinding {
+  tools?: Array<{
+    name: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+  }> | null;
+}
+
+/**
+ * Checks if a connection implements a binding by validating its tools.
+ * Used by plugin layouts to filter connections by binding.
+ */
+export function connectionImplementsBinding(
+  connection: ConnectionForBinding,
+  binding: Binder,
+): boolean {
+  const tools = connection.tools;
+
+  if (!tools || tools.length === 0) {
+    return false;
+  }
+
+  // Prepare tools for checker (only input schema, skip output for detection)
+  const toolsForChecker = tools.map((t) => ({
+    name: t.name,
+    inputSchema: t.inputSchema,
+  }));
+
+  // Create binding checker without output schemas
+  const bindingForChecker = binding.map((b) => ({
+    name: b.name,
+    inputSchema: b.inputSchema,
+    opt: b.opt,
+  }));
+
+  const checker = createBindingChecker(bindingForChecker);
+  return checker.isImplementedBy(toolsForChecker);
+}

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

@@ -0,0 +1,94 @@
+/**
+ * Plugin Context Provider
+ *
+ * React context provider and hook for accessing plugin context.
+ */
+
+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);
+
+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.
+ */
+export interface UsePluginContextOptions {
+  /**
+   * Set to true when calling from an empty state component.
+   * This returns nullable connection fields since no valid connection exists.
+   */
+  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-context.ts

@@ -0,0 +1,183 @@
+/**
+ * Plugin Context Types
+ *
+ * Provides typed context for plugins to access their selected connection
+ * and call tools with full type safety based on the plugin's binding.
+ */
+
+import type { Binder, ToolBinder } from "./binder";
+import type { z } from "zod";
+
+/**
+ * Connection entity shape provided by the layout.
+ */
+export interface PluginConnectionEntity {
+  id: string;
+  title: string;
+  icon: string | null;
+  description: string | null;
+  app_name: string | null;
+  app_id: string | null;
+  tools: Array<{
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+  }> | null;
+  metadata: Record<string, unknown> | null;
+}
+
+/**
+ * Organization context.
+ */
+export interface PluginOrgContext {
+  id: string;
+  slug: string;
+  name: string;
+}
+
+/**
+ * User session provided to plugins.
+ */
+export interface PluginSession {
+  user: {
+    id: string;
+    name: string;
+    email: string;
+    image?: string | null;
+  };
+}
+
+/**
+ * Helper type to extract tool by name from a binding.
+ */
+type ExtractToolByName<TBinding extends Binder, TName extends string> = Extract<
+  TBinding[number],
+  { name: TName }
+>;
+
+/**
+ * Typed tool caller for a specific binding.
+ * Provides type-safe tool calls based on the binding definition.
+ *
+ * @template TBinding - The binding type to derive tool types from
+ */
+export type TypedToolCaller<TBinding extends Binder> = <
+  TName extends TBinding[number]["name"] & string,
+>(
+  toolName: TName,
+  args: ExtractToolByName<TBinding, TName> extends ToolBinder<
+    TName,
+    infer TInput,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    infer _TOutput
+  >
+    ? TInput extends z.ZodType
+      ? z.infer<TInput>
+      : TInput
+    : unknown,
+) => Promise<
+  ExtractToolByName<TBinding, TName> extends ToolBinder<
+    TName,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    infer _TInput,
+    infer TOutput
+  >
+    ? TOutput extends z.ZodType
+      ? z.infer<TOutput>
+      : TOutput
+    : unknown
+>;
+
+/**
+ * Base plugin context with connection fields always available.
+ * Used by plugin routes where layout guarantees a valid connection.
+ *
+ * @template TBinding - The binding type the plugin requires
+ *
+ * @example
+ * ```tsx
+ * // In plugin route component (connection guaranteed)
+ * const { toolCaller, connection } = usePluginContext<typeof REGISTRY_APP_BINDING>();
+ *
+ * // toolCaller and connection are non-null
+ * const result = await toolCaller("COLLECTION_REGISTRY_APP_LIST", { limit: 20 });
+ * ```
+ */
+export interface PluginContext<TBinding extends Binder = Binder> {
+  /**
+   * The selected connection ID.
+   * Always defined in routes (layout handles empty state separately).
+   */
+  connectionId: string;
+
+  /**
+   * The selected connection entity.
+   * Always defined in routes.
+   */
+  connection: PluginConnectionEntity;
+
+  /**
+   * Typed tool caller for the selected connection.
+   * Call MCP tools with full type safety based on the plugin's binding.
+   */
+  toolCaller: TypedToolCaller<TBinding>;
+
+  /**
+   * Organization context.
+   * Always available.
+   */
+  org: PluginOrgContext;
+
+  /**
+   * Current user session.
+   * Available when user is authenticated.
+   */
+  session: PluginSession | null;
+}
+
+/**
+ * Partial plugin context with nullable connection fields.
+ * Used by empty state components where no valid connection exists.
+ *
+ * @template TBinding - The binding type the plugin requires
+ *
+ * @example
+ * ```tsx
+ * // In empty state component (no connection)
+ * const { session, org } = usePluginContext<typeof REGISTRY_APP_BINDING>({ partial: true });
+ *
+ * // connection, connectionId, toolCaller are null
+ * ```
+ */
+export interface PluginContextPartial<TBinding extends Binder = Binder> {
+  /**
+   * The selected connection ID.
+   * Null when no valid connection is available.
+   */
+  connectionId: string | null;
+
+  /**
+   * The selected connection entity.
+   * Null when no valid connection is available.
+   */
+  connection: PluginConnectionEntity | null;
+
+  /**
+   * Typed tool caller for the selected connection.
+   * Null when no valid connection is available.
+   */
+  toolCaller: TypedToolCaller<TBinding> | null;
+
+  /**
+   * Organization context.
+   * Always available.
+   */
+  org: PluginOrgContext;
+
+  /**
+   * Current user session.
+   * Available when user is authenticated.
+   */
+  session: PluginSession | null;
+}

package/src/core/plugin-router.tsx

@@ -0,0 +1,226 @@
+import type { ReactNode } from "react";
+import {
+  createRoute,
+  lazyRouteComponent,
+  Route,
+  useNavigate,
+  useParams,
+  useSearch,
+  useLocation,
+  Link as TanStackLink,
+  type AnyRoute,
+  type RouteIds,
+  type RouteById,
+  type LinkProps,
+  type NavigateOptions,
+} from "@tanstack/react-router";
+import type { PluginSetupContext } from "./plugins";
+
+/**
+ * Prepends the plugin base path (/$org/$pluginId) to a route path.
+ * Handles both absolute plugin paths (starting with /) and relative paths.
+ */
+function prependBasePath(
+  to: string | undefined,
+  org: string,
+  pluginId: string,
+): string {
+  if (!to) return `/${org}/${pluginId}`;
+
+  // If path starts with /, it's relative to the plugin root
+  if (to.startsWith("/")) {
+    return `/${org}/${pluginId}${to}`;
+  }
+
+  // Otherwise, it's already a full path or relative
+  return to;
+}
+
+/**
+ * Creates a typed plugin router from a route factory function.
+ *
+ * Routes are registered directly under ctx.parentRoute (which already has
+ * component: Outlet). Return an array of sibling routes for multiple pages.
+ *
+ * @example
+ * ```tsx
+ * export const storeRouter = createPluginRouter((ctx) => {
+ *   const indexRoute = ctx.routing.createRoute({
+ *     getParentRoute: () => ctx.parentRoute,
+ *     path: "/",
+ *     component: ctx.routing.lazyRouteComponent(() => import("./routes/page.tsx")),
+ *   });
+ *
+ *   const detailRoute = ctx.routing.createRoute({
+ *     getParentRoute: () => ctx.parentRoute,
+ *     path: "/$appName",
+ *     component: ctx.routing.lazyRouteComponent(() => import("./routes/detail.tsx")),
+ *     validateSearch: z.object({ tab: z.string().optional() }),
+ *   });
+ *
+ *   return [indexRoute, detailRoute];
+ * });
+ *
+ * // In plugin setup - register each route
+ * export const storePlugin: AnyPlugin = {
+ *   id: "store",
+ *   setup: (ctx) => {
+ *     const routes = storeRouter.createRoutes(ctx);
+ *     for (const route of routes) {
+ *       ctx.registerRootPluginRoute(route);
+ *     }
+ *   },
+ * };
+ *
+ * // In components
+ * function DetailPage() {
+ *   const { appName } = storeRouter.useParams({ from: "/$appName" });
+ *   const { tab } = storeRouter.useSearch({ from: "/$appName" });
+ *
+ *   const navigate = storeRouter.useNavigate();
+ *   navigate({ to: "/$appName", params: { appName: "other" } });
+ * }
+ * ```
+ */
+export function createPluginRouter<TRoutes extends AnyRoute | AnyRoute[]>(
+  createRoutes: (ctx: PluginSetupContext) => TRoutes,
+) {
+  // Extract route type from array or single route
+  type TRoute = TRoutes extends (infer R)[] ? R : TRoutes;
+  type TRouteId = TRoute extends AnyRoute ? RouteIds<TRoute> : never;
+  type TRouteById<TId extends TRouteId> = TRoute extends AnyRoute
+    ? RouteById<TRoute, TId>
+    : never;
+
+  return {
+    /**
+     * Create the route tree. Call this in your plugin's setup().
+     */
+    createRoutes,
+
+    /**
+     * Get route params with TanStack's type inference.
+     */
+    useParams: <TFrom extends TRouteId>(_options: { from: TFrom }) => {
+      return useParams({
+        strict: false,
+      }) as TRouteById<TFrom>["types"]["allParams"];
+    },
+
+    /**
+     * Get search params with TanStack's type inference.
+     */
+    useSearch: <TFrom extends TRouteId>(_options: { from: TFrom }) => {
+      return useSearch({
+        strict: false,
+      }) as TRouteById<TFrom>["types"]["fullSearchSchema"];
+    },
+
+    /**
+     * Navigate within the plugin.
+     * Automatically prepends /$org/$pluginId to the path.
+     */
+    useNavigate: () => {
+      const navigate = useNavigate();
+      const { org, pluginId } = useParams({ strict: false }) as {
+        org: string;
+        pluginId: string;
+      };
+
+      return <TTo extends TRouteId>(
+        options: Omit<NavigateOptions, "to" | "params"> & {
+          to: TTo;
+          params?: TRouteById<TTo>["types"]["allParams"];
+          search?: TRouteById<TTo>["types"]["fullSearchSchema"];
+        },
+      ) => {
+        const to = prependBasePath(options.to, org, pluginId);
+
+        return navigate({
+          ...options,
+          to,
+          params: {
+            org,
+            pluginId,
+            ...(options.params as Record<string, string>),
+          },
+        } as NavigateOptions);
+      };
+    },
+
+    /**
+     * Get the current location.
+     */
+    useLocation: () => {
+      return useLocation();
+    },
+
+    /**
+     * Link component for plugin navigation.
+     * Automatically prepends /$org/$pluginId to the path.
+     */
+    Link: function PluginLink<TTo extends TRouteId>(
+      props: Omit<LinkProps, "to" | "params" | "search"> & {
+        to: TTo;
+        params?: TRouteById<TTo>["types"]["allParams"];
+        search?: TRouteById<TTo>["types"]["fullSearchSchema"];
+        className?: string;
+        children?: ReactNode;
+      },
+    ) {
+      const { org, pluginId } = useParams({ strict: false }) as {
+        org: string;
+        pluginId: string;
+      };
+
+      const to = prependBasePath(props.to as string, org, pluginId);
+
+      return (
+        <TanStackLink
+          {...(props as LinkProps)}
+          to={to}
+          params={{
+            org,
+            pluginId,
+            ...props.params,
+          }}
+        />
+      );
+    },
+
+    /**
+     * Type helpers
+     */
+    _types: {
+      routes: undefined as unknown as TRoutes,
+      routeIds: undefined as unknown as TRouteId,
+    },
+  };
+}
+
+/**
+ * Type helper to extract route IDs from a plugin router
+ */
+export type PluginRouteIds<
+  TRouter extends ReturnType<typeof createPluginRouter>,
+> = TRouter["_types"]["routeIds"];
+
+/**
+ * Type helper to extract routes from a plugin router
+ */
+export type PluginRoutes<
+  TRouter extends ReturnType<typeof createPluginRouter>,
+> = TRouter["_types"]["routes"];
+
+// Re-export TanStack utilities for plugins
+export {
+  createRoute,
+  lazyRouteComponent,
+  Route,
+  TanStackLink as Link,
+  useNavigate,
+  useParams,
+  useSearch,
+  useLocation,
+};
+export type { AnyRoute, RouteIds, RouteById };

package/src/core/plugins.ts

@@ -0,0 +1,81 @@
+import {
+  createRoute,
+  lazyRouteComponent,
+  type AnyRoute,
+} from "@tanstack/react-router";
+import { Binder } from "./binder";
+import type { ReactNode } from "react";
+import type { PluginConnectionEntity } from "./plugin-context";
+
+export interface ToolViewItem {
+  toolName: string;
+  label: string;
+  icon: ReactNode;
+}
+
+export interface RegisterRootSidebarItemParams {
+  icon: ReactNode;
+  label: string;
+}
+
+export interface RegisterEmptyStateParams {
+  component: ReactNode;
+}
+
+export interface PluginSetupContext {
+  parentRoute: AnyRoute;
+  routing: {
+    createRoute: typeof createRoute;
+    lazyRouteComponent: typeof lazyRouteComponent;
+  };
+  registerRootSidebarItem: (params: RegisterRootSidebarItemParams) => void;
+  registerPluginRoutes: (route: AnyRoute[]) => void;
+}
+
+export type PluginSetup = (context: PluginSetupContext) => void;
+
+/**
+ * Props passed to plugin's renderHeader function.
+ */
+export interface PluginRenderHeaderProps {
+  connections: PluginConnectionEntity[];
+  selectedConnectionId: string;
+  onConnectionChange: (connectionId: string) => void;
+}
+
+export interface Plugin<TBinding extends Binder> {
+  id: string;
+  /**
+   * Short description of the plugin shown in the settings UI.
+   */
+  description?: string;
+  binding: TBinding;
+  setup: PluginSetup;
+  /**
+   * Optional custom layout component for this plugin.
+   * If not provided, a default layout with connection selector will be used.
+   * @deprecated Use renderHeader and renderEmptyState instead.
+   */
+  LayoutComponent?: React.ComponentType;
+  /**
+   * Render the header with connection selector.
+   * Receives the list of valid connections and current selection handlers.
+   */
+  renderHeader?: (props: PluginRenderHeaderProps) => ReactNode;
+  /**
+   * Render the empty state when no valid connections are available.
+   */
+  renderEmptyState?: () => ReactNode;
+}
+
+export type AnyPlugin = Plugin<any>;
+
+// Re-export plugin router utilities
+export {
+  createPluginRouter,
+  type PluginRouteIds,
+  type PluginRoutes,
+  type AnyRoute,
+  type RouteIds,
+  type RouteById,
+} from "./plugin-router";

package/src/index.ts

@@ -8,12 +8,32 @@
 // Re-export core binder types and utilities
 export {
   createBindingChecker,
+  bindingClient,
+  connectionImplementsBinding,
   type Binder,
   type BindingChecker,
   type ToolBinder,
   type ToolWithSchemas,
+  type ConnectionForBinding,
 } from "./core/binder";
 
+// Re-export plugin context types and provider
+export {
+  type PluginContext,
+  type PluginContextPartial,
+  type PluginConnectionEntity,
+  type PluginOrgContext,
+  type PluginSession,
+  type TypedToolCaller,
+} from "./core/plugin-context";
+
+export {
+  PluginContextProvider,
+  usePluginContext,
+  type PluginContextProviderProps,
+  type UsePluginContextOptions,
+} from "./core/plugin-context-provider";
+
 // Re-export registry binding types
 export {
   MCPRegistryServerSchema,
@@ -70,3 +90,21 @@ export {
   EventBusBinding,
   type EventBusBindingClient,
 } from "./well-known/event-bus";
+
+// Re-export object storage binding types
+export {
+  OBJECT_STORAGE_BINDING,
+  type ObjectStorageBinding,
+  type ListObjectsInput,
+  type ListObjectsOutput,
+  type GetObjectMetadataInput,
+  type GetObjectMetadataOutput,
+  type GetPresignedUrlInput,
+  type GetPresignedUrlOutput,
+  type PutPresignedUrlInput,
+  type PutPresignedUrlOutput,
+  type DeleteObjectInput,
+  type DeleteObjectOutput,
+  type DeleteObjectsInput,
+  type DeleteObjectsOutput,
+} from "./well-known/object-storage";

package/src/well-known/assistant.ts

@@ -3,7 +3,7 @@
  *
  * Defines the interface for AI assistant providers.
  * Any MCP that implements this binding can provide configurable AI assistants
- * with a system prompt and runtime configuration (gateway + model).
+ * with a system prompt and runtime configuration (virtual MCP + model).
  *
  * This binding uses collection bindings for full CRUD operations.
  */
@@ -37,10 +37,12 @@ export const AssistantSchema = BaseCollectionEntitySchema.extend({
     .describe("System prompt that defines the assistant's behavior"),
 
   /**
-   * Selected gateway for this assistant (single gateway).
-   * This gateway determines which MCP tools are exposed to chat.
+   * Selected virtual MCP (agent) for this assistant.
+   * This virtual MCP determines which MCP tools are exposed to chat.
    */
-  gateway_id: z.string().describe("Gateway ID to use for this assistant"),
+  virtual_mcp_id: z
+    .string()
+    .describe("Virtual MCP ID to use for this assistant"),
 
   /**
    * Selected model for this assistant (model id + the connection where it lives).
@@ -75,7 +77,7 @@ export const ASSISTANTS_COLLECTION_BINDING = createCollectionBindings(
  *
  * Required tools:
  * - COLLECTION_ASSISTANT_LIST: List available AI assistants with their configurations
- * - COLLECTION_ASSISTANT_GET: Get a single assistant by ID (includes system_prompt, gateway_id, model)
+ * - COLLECTION_ASSISTANT_GET: Get a single assistant by ID (includes system_prompt, virtual_mcp_id, model)
  *
  * Optional tools:
  * - COLLECTION_ASSISTANT_CREATE: Create a new assistant

package/src/well-known/event-bus.ts

@@ -150,10 +150,10 @@ export const EventSubscribeOutputSchema = z.object({
     enabled: z.boolean().describe("Whether subscription is enabled"),
 
     /** Created timestamp */
-    createdAt: z.union([z.string(), z.date()]).describe("Created timestamp"),
+    createdAt: z.string().datetime().describe("Created timestamp (ISO 8601)"),
 
     /** Updated timestamp */
-    updatedAt: z.union([z.string(), z.date()]).describe("Updated timestamp"),
+    updatedAt: z.string().datetime().describe("Updated timestamp (ISO 8601)"),
   }),
 });
 
@@ -209,10 +209,10 @@ export const SubscriptionDetailSchema = z.object({
   enabled: z.boolean().describe("Whether subscription is enabled"),
 
   /** Created timestamp */
-  createdAt: z.union([z.string(), z.date()]).describe("Created timestamp"),
+  createdAt: z.string().datetime().describe("Created timestamp (ISO 8601)"),
 
   /** Updated timestamp */
-  updatedAt: z.union([z.string(), z.date()]).describe("Updated timestamp"),
+  updatedAt: z.string().datetime().describe("Updated timestamp (ISO 8601)"),
 });
 
 export type SubscriptionDetail = z.infer<typeof SubscriptionDetailSchema>;

package/src/well-known/object-storage.ts

@@ -0,0 +1,257 @@
+/**
+ * Object Storage Well-Known Binding
+ *
+ * Defines the interface for S3-compatible object storage operations.
+ * Any MCP that implements this binding can provide file/object management
+ * for buckets and objects.
+ *
+ * This binding includes:
+ * - LIST_OBJECTS: List objects with pagination and prefix filtering
+ * - GET_OBJECT_METADATA: Get object metadata (HEAD operation)
+ * - GET_PRESIGNED_URL: Generate presigned URL for downloading
+ * - PUT_PRESIGNED_URL: Generate presigned URL for uploading
+ * - DELETE_OBJECT: Delete a single object
+ * - DELETE_OBJECTS: Batch delete multiple objects
+ */
+
+import { z } from "zod";
+import type { Binder, ToolBinder } from "../core/binder";
+
+// ============================================================================
+// Tool Schemas
+// ============================================================================
+
+/**
+ * LIST_OBJECTS - List objects in the bucket with pagination support
+ */
+const ListObjectsInputSchema = z.object({
+  prefix: z
+    .string()
+    .optional()
+    .describe("Filter objects by prefix (e.g., 'folder/' for folder contents)"),
+  maxKeys: z
+    .number()
+    .optional()
+    .default(1000)
+    .describe("Maximum number of keys to return (default: 1000)"),
+  continuationToken: z
+    .string()
+    .optional()
+    .describe("Token for pagination from previous response"),
+  delimiter: z
+    .string()
+    .optional()
+    .describe(
+      "Delimiter for grouping keys (typically '/'). When set, commonPrefixes returns folder paths.",
+    ),
+});
+
+const ListObjectsOutputSchema = z.object({
+  objects: z.array(
+    z.object({
+      key: z.string().describe("Object key/path"),
+      size: z.number().describe("Object size in bytes"),
+      lastModified: z.string().describe("Last modified timestamp"),
+      etag: z.string().describe("Entity tag for the object"),
+    }),
+  ),
+  nextContinuationToken: z
+    .string()
+    .optional()
+    .describe("Token for fetching next page of results"),
+  isTruncated: z.boolean().describe("Whether there are more results available"),
+  commonPrefixes: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Folder paths when delimiter is used (e.g., ['photos/2024/', 'photos/2025/'])",
+    ),
+});
+
+export type ListObjectsInput = z.infer<typeof ListObjectsInputSchema>;
+export type ListObjectsOutput = z.infer<typeof ListObjectsOutputSchema>;
+
+/**
+ * GET_OBJECT_METADATA - Get object metadata using HEAD operation
+ */
+const GetObjectMetadataInputSchema = z.object({
+  key: z.string().describe("Object key/path to get metadata for"),
+});
+
+const GetObjectMetadataOutputSchema = z.object({
+  contentType: z.string().optional().describe("MIME type of the object"),
+  contentLength: z.number().describe("Size of the object in bytes"),
+  lastModified: z.string().describe("Last modified timestamp"),
+  etag: z.string().describe("Entity tag for the object"),
+  metadata: z
+    .record(z.string(), z.string())
+    .optional()
+    .describe("Custom metadata key-value pairs"),
+});
+
+export type GetObjectMetadataInput = z.infer<
+  typeof GetObjectMetadataInputSchema
+>;
+export type GetObjectMetadataOutput = z.infer<
+  typeof GetObjectMetadataOutputSchema
+>;
+
+/**
+ * GET_PRESIGNED_URL - Generate a presigned URL for downloading an object
+ */
+const GetPresignedUrlInputSchema = z.object({
+  key: z.string().describe("Object key/path to generate URL for"),
+  expiresIn: z
+    .number()
+    .optional()
+    .describe(
+      "URL expiration time in seconds (default: from state config or 3600)",
+    ),
+});
+
+const GetPresignedUrlOutputSchema = z.object({
+  url: z.string().describe("Presigned URL for downloading the object"),
+  expiresIn: z.number().describe("Expiration time in seconds that was used"),
+});
+
+export type GetPresignedUrlInput = z.infer<typeof GetPresignedUrlInputSchema>;
+export type GetPresignedUrlOutput = z.infer<typeof GetPresignedUrlOutputSchema>;
+
+/**
+ * PUT_PRESIGNED_URL - Generate a presigned URL for uploading an object
+ */
+const PutPresignedUrlInputSchema = z.object({
+  key: z.string().describe("Object key/path for the upload"),
+  expiresIn: z
+    .number()
+    .optional()
+    .describe(
+      "URL expiration time in seconds (default: from state config or 3600)",
+    ),
+  contentType: z
+    .string()
+    .optional()
+    .describe("MIME type for the object being uploaded"),
+});
+
+const PutPresignedUrlOutputSchema = z.object({
+  url: z.string().describe("Presigned URL for uploading the object"),
+  expiresIn: z.number().describe("Expiration time in seconds that was used"),
+});
+
+export type PutPresignedUrlInput = z.infer<typeof PutPresignedUrlInputSchema>;
+export type PutPresignedUrlOutput = z.infer<typeof PutPresignedUrlOutputSchema>;
+
+/**
+ * DELETE_OBJECT - Delete a single object
+ */
+const DeleteObjectInputSchema = z.object({
+  key: z.string().describe("Object key/path to delete"),
+});
+
+const DeleteObjectOutputSchema = z.object({
+  success: z.boolean().describe("Whether the deletion was successful"),
+  key: z.string().describe("The key that was deleted"),
+});
+
+export type DeleteObjectInput = z.infer<typeof DeleteObjectInputSchema>;
+export type DeleteObjectOutput = z.infer<typeof DeleteObjectOutputSchema>;
+
+/**
+ * DELETE_OBJECTS - Delete multiple objects in batch
+ */
+const DeleteObjectsInputSchema = z.object({
+  keys: z
+    .array(z.string())
+    .max(1000)
+    .describe("Array of object keys/paths to delete (max 1000)"),
+});
+
+const DeleteObjectsOutputSchema = z.object({
+  deleted: z.array(z.string()).describe("Array of successfully deleted keys"),
+  errors: z
+    .array(
+      z.object({
+        key: z.string(),
+        message: z.string(),
+      }),
+    )
+    .describe("Array of errors for failed deletions"),
+});
+
+export type DeleteObjectsInput = z.infer<typeof DeleteObjectsInputSchema>;
+export type DeleteObjectsOutput = z.infer<typeof DeleteObjectsOutputSchema>;
+
+// ============================================================================
+// Binding Definition
+// ============================================================================
+
+/**
+ * Object Storage Binding
+ *
+ * Defines the interface for S3-compatible object storage operations.
+ * Any MCP that implements this binding can be used with the Object Storage plugin
+ * to provide a file browser UI.
+ *
+ * Required tools:
+ * - LIST_OBJECTS: List objects with prefix filtering and pagination
+ * - GET_OBJECT_METADATA: Get object metadata (HEAD)
+ * - GET_PRESIGNED_URL: Generate download URL
+ * - PUT_PRESIGNED_URL: Generate upload URL
+ * - DELETE_OBJECT: Delete single object
+ * - DELETE_OBJECTS: Batch delete objects
+ */
+export const OBJECT_STORAGE_BINDING = [
+  {
+    name: "LIST_OBJECTS" as const,
+    inputSchema: ListObjectsInputSchema,
+    outputSchema: ListObjectsOutputSchema,
+  } satisfies ToolBinder<"LIST_OBJECTS", ListObjectsInput, ListObjectsOutput>,
+  {
+    name: "GET_OBJECT_METADATA" as const,
+    inputSchema: GetObjectMetadataInputSchema,
+    outputSchema: GetObjectMetadataOutputSchema,
+  } satisfies ToolBinder<
+    "GET_OBJECT_METADATA",
+    GetObjectMetadataInput,
+    GetObjectMetadataOutput
+  >,
+  {
+    name: "GET_PRESIGNED_URL" as const,
+    inputSchema: GetPresignedUrlInputSchema,
+    outputSchema: GetPresignedUrlOutputSchema,
+  } satisfies ToolBinder<
+    "GET_PRESIGNED_URL",
+    GetPresignedUrlInput,
+    GetPresignedUrlOutput
+  >,
+  {
+    name: "PUT_PRESIGNED_URL" as const,
+    inputSchema: PutPresignedUrlInputSchema,
+    outputSchema: PutPresignedUrlOutputSchema,
+  } satisfies ToolBinder<
+    "PUT_PRESIGNED_URL",
+    PutPresignedUrlInput,
+    PutPresignedUrlOutput
+  >,
+  {
+    name: "DELETE_OBJECT" as const,
+    inputSchema: DeleteObjectInputSchema,
+    outputSchema: DeleteObjectOutputSchema,
+  } satisfies ToolBinder<
+    "DELETE_OBJECT",
+    DeleteObjectInput,
+    DeleteObjectOutput
+  >,
+  {
+    name: "DELETE_OBJECTS" as const,
+    inputSchema: DeleteObjectsInputSchema,
+    outputSchema: DeleteObjectsOutputSchema,
+  } satisfies ToolBinder<
+    "DELETE_OBJECTS",
+    DeleteObjectsInput,
+    DeleteObjectsOutput
+  >,
+] as const satisfies Binder;
+
+export type ObjectStorageBinding = typeof OBJECT_STORAGE_BINDING;

package/src/well-known/workflow.ts

@@ -164,9 +164,11 @@ export type WorkflowExecutionStatus = z.infer<
  * Includes lock columns and retry tracking.
  */
 export const WorkflowExecutionSchema = BaseCollectionEntitySchema.extend({
-  gateway_id: z
+  virtual_mcp_id: z
     .string()
-    .describe("ID of the gateway that will be used to execute the workflow"),
+    .describe(
+      "ID of the virtual MCP (agent) that will be used to execute the workflow",
+    ),
   status: WorkflowExecutionStatusEnum.describe(
     "Current status of the workflow execution",
   ),