@decocms/bindings 1.4.0 → 1.4.2

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@decocms/bindings",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",
     "test": "bun test"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.27.1",
-    "@tanstack/react-router": "1.139.7",
-    "react": "^19.2.0",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@tanstack/react-router": "1.169.2",
+    "react": "^19.2.6",
     "zod": "^4.0.0",
     "zod-from-json-schema": "^0.5.2"
   },
@@ -32,7 +32,8 @@
     "./plugin-router": "./src/core/plugin-router.tsx",
     "./ai-gateway": "./src/well-known/ai-gateway.ts",
     "./server-plugin": "./src/core/server-plugin.ts",
-    "./trigger": "./src/well-known/trigger.ts"
+    "./trigger": "./src/well-known/trigger.ts",
+    "./brand": "./src/well-known/brand.ts"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/core/binder.ts

@@ -24,7 +24,6 @@ export interface ToolBinder<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   TInput = any,
   TReturn extends object | null | boolean = object,
-  TStreamable extends boolean = boolean,
 > {
   /** The name of the tool (e.g., "DECO_CHAT_CHANNELS_JOIN") */
   name: TName;
@@ -33,12 +32,7 @@ export interface ToolBinder<
   inputSchema: ZodType<TInput>;
 
   /** Optional Zod schema for validating tool output */
-  outputSchema?: TStreamable extends true ? never : ZodType<TReturn>;
-
-  /**
-   * Whether this tool is streamable.
-   */
-  streamable?: TStreamable;
+  outputSchema?: ZodType<TReturn>;
 
   /**
    * Whether this tool is optional in the binding.
@@ -103,13 +97,6 @@ export const bindingClient = <TDefinition extends readonly ToolBinder[]>(
     forClient: (client: ServerClient): MCPClientFetchStub<TDefinition> => {
       return createMCPFetchStub<TDefinition>({
         client,
-        streamable: binder.reduce(
-          (acc, tool) => {
-            acc[tool.name] = tool.streamable === true;
-            return acc;
-          },
-          {} as Record<string, boolean>,
-        ),
       });
     },
     forConnection: (
@@ -117,13 +104,6 @@ export const bindingClient = <TDefinition extends readonly ToolBinder[]>(
     ): MCPClientFetchStub<TDefinition> => {
       return createMCPFetchStub<TDefinition>({
         connection: mcpConnection,
-        streamable: binder.reduce(
-          (acc, tool) => {
-            acc[tool.name] = tool.streamable === true;
-            return acc;
-          },
-          {} as Record<string, boolean>,
-        ),
       });
     },
   };

package/src/core/client/index.ts

@@ -1,7 +1,6 @@
 export { HTTPClientTransport } from "./http-client-transport";
 export {
   createMCPFetchStub,
-  isStreamableToolBinder,
   MCPClient,
   type CreateStubAPIOptions,
   type MCPClientFetchStub,

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

@@ -47,11 +47,6 @@ export interface ServerClient {
     callTool: Client["callTool"];
     listTools: () => Promise<ListToolsResult>;
   };
-  callStreamableTool?: (
-    tool: string,
-    args: Record<string, unknown>,
-    signal?: AbortSignal,
-  ) => Promise<Response>;
 }
 export const createServerClient = async (
   mcpServer: { connection: MCPConnection; name?: string },
@@ -73,36 +68,6 @@ export const createServerClient = async (
 
   return {
     client,
-    callStreamableTool: (tool, args, signal) => {
-      if (mcpServer.connection.type !== "HTTP") {
-        throw new Error("HTTP connection required");
-      }
-
-      const headers = new Headers(extraHeaders);
-
-      if (!headers.has("Authorization")) {
-        headers.set("Authorization", `Bearer ${mcpServer.connection.token}`);
-      }
-
-      for (const [key, value] of Object.entries(
-        mcpServer.connection.headers ?? {},
-      )) {
-        headers.set(key, value);
-      }
-
-      const url = new URL(mcpServer.connection.url);
-      // Trim trailing slashes from pathname, ensuring it starts with '/'
-      const trimmedPath = url.pathname.replace(/\/+$/, "") || "/";
-      url.pathname = `${trimmedPath}/call-tool/${encodeURIComponent(tool)}`;
-
-      return fetch(url.href, {
-        method: "POST",
-        redirect: "manual",
-        body: JSON.stringify(args),
-        headers,
-        signal,
-      });
-    },
   };
 };
 

package/src/core/client/mcp.ts

@@ -3,12 +3,6 @@ import { z } from "zod";
 import type { MCPConnection } from "../connection";
 import { createMCPClientProxy } from "./proxy";
 export type { ServerClient } from "./mcp-client";
-export const isStreamableToolBinder = (
-  toolBinder: ToolBinder,
-): toolBinder is ToolBinder<string, any, any, true> => {
-  return toolBinder.streamable === true;
-};
-
 // Default fetcher instance with API_SERVER_URL and API_HEADERS
 export const MCPClient = new Proxy(
   {} as {
@@ -69,13 +63,13 @@ export type MCPClientFetchStub<TDefinition extends readonly ToolBinder[]> = {
     }[]
   >;
 } & {
-  [K in TDefinition[number] as K["name"]]: K["streamable"] extends true
-    ? K extends ToolBinder<string, infer TInput, any, true>
-      ? (params: TInput, init?: RequestInit) => Promise<Response>
-      : never
-    : K extends ToolBinder<string, infer TInput, infer TReturn, any>
-      ? (params: TInput, init?: RequestInit) => Promise<Awaited<TReturn>>
-      : never;
+  [K in TDefinition[number] as K["name"]]: K extends ToolBinder<
+    string,
+    infer TInput,
+    infer TReturn
+  >
+    ? (params: TInput, init?: RequestInit) => Promise<Awaited<TReturn>>
+    : never;
 };
 
 export interface MCPClientRaw {
@@ -93,7 +87,6 @@ export type JSONSchemaToZodConverter = (jsonSchema: any) => z.ZodTypeAny;
 
 export interface CreateStubForClientAPIOptions {
   client: ServerClient;
-  streamable?: Record<string, boolean>;
   debugId?: () => string;
   getErrorByStatusCode?: (
     statusCode: number,
@@ -105,7 +98,6 @@ export interface CreateStubForClientAPIOptions {
 
 export interface CreateStubForConnectionAPIOptions {
   connection: MCPConnection;
-  streamable?: Record<string, boolean>;
   debugId?: () => string;
   createServerClient?: (
     mcpServer: { connection: MCPConnection; name?: string },

package/src/core/client/proxy.ts

@@ -74,16 +74,7 @@ export function createMCPClientProxy<T extends Record<string, unknown>>(
           ? { "x-trace-debug-id": debugId }
           : undefined;
 
-        const { client, callStreamableTool } = await createClient(extraHeaders);
-
-        if (options?.streamable?.[String(toolName)]) {
-          if (!callStreamableTool) {
-            throw new Error(
-              `Tool ${String(toolName)} requires streaming support but client doesn't provide callStreamableTool`,
-            );
-          }
-          return await callStreamableTool(String(toolName), args);
-        }
+        const { client } = await createClient(extraHeaders);
 
         const { structuredContent, isError, content } = await client.callTool({
           name: String(toolName),

package/src/core/plugins.ts

@@ -29,6 +29,13 @@ export interface RegisterEmptyStateParams {
   component: ReactNode;
 }
 
+export interface RegisterSettingsSidebarItemParams {
+  key: string;
+  icon: ReactNode;
+  label: string;
+  to: string;
+}
+
 export interface PluginSetupContext {
   parentRoute: AnyRoute;
   routing: {
@@ -37,6 +44,9 @@ export interface PluginSetupContext {
   };
   registerRootSidebarItem: (params: RegisterRootSidebarItemParams) => void;
   registerSidebarGroup: (params: RegisterSidebarGroupParams) => void;
+  registerSettingsSidebarItem: (
+    params: RegisterSettingsSidebarItemParams,
+  ) => void;
   registerPluginRoutes: (route: AnyRoute[]) => void;
 }
 

package/src/core/server-plugin.ts

@@ -16,9 +16,9 @@ import type { Hono } from "hono";
 import type { Kysely } from "kysely";
 
 /**
- * Subset of MeshContext exposed to server plugin tool handlers.
+ * Subset of StudioContext exposed to server plugin tool handlers.
  *
- * Plugins receive the full MeshContext at runtime but should only depend on
+ * Plugins receive the full StudioContext 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.).
  */

package/src/index.ts

@@ -123,3 +123,25 @@ export {
 
 // Re-export workflow binding types
 export { WORKFLOWS_COLLECTION_BINDING } from "./well-known/workflow";
+
+// Re-export brand binding types (for reading org brand context)
+export {
+  BrandColorsSchema,
+  type BrandColors,
+  BrandFontsSchema,
+  type BrandFonts,
+  BrandAssetsSchema,
+  type BrandAssets,
+  BrandSchema,
+  type Brand,
+  BrandGetInputSchema,
+  type BrandGetInput,
+  type BrandGetOutput,
+  BrandListInputSchema,
+  type BrandListInput,
+  BrandListOutputSchema,
+  type BrandListOutput,
+  BRAND_BINDING,
+  BrandBinding,
+  type BrandBindingClient,
+} from "./well-known/brand";

package/src/well-known/brand.ts

@@ -0,0 +1,151 @@
+/**
+ * Brand Well-Known Binding
+ *
+ * Defines the interface for reading brand context (colors, fonts, assets,
+ * voice) from an organization. External MCPs that need brand awareness
+ * can declare a dependency on this binding and call BRAND_GET / BRAND_LIST
+ * to pull structured brand data on demand.
+ *
+ * This binding includes:
+ * - BRAND_GET: Get a brand by ID (or the org default)
+ * - BRAND_LIST: List all active brands (optional)
+ */
+
+import { z } from "zod";
+import { bindingClient, type ToolBinder } from "../core/binder";
+
+// ============================================================================
+// Brand Sub-Schemas
+// ============================================================================
+
+export const BrandColorsSchema = z.object({
+  primary: z.string().optional().describe("Primary brand color (hex)"),
+  secondary: z.string().optional().describe("Secondary brand color (hex)"),
+  accent: z.string().optional().describe("Accent / highlight color (hex)"),
+  background: z.string().optional().describe("Background color (hex)"),
+  foreground: z.string().optional().describe("Foreground / text color (hex)"),
+});
+
+export type BrandColors = z.infer<typeof BrandColorsSchema>;
+
+export const BrandFontsSchema = z.object({
+  heading: z.string().optional().describe("Font family for headings"),
+  body: z.string().optional().describe("Font family for body text"),
+  code: z.string().optional().describe("Font family for code / monospace"),
+});
+
+export type BrandFonts = z.infer<typeof BrandFontsSchema>;
+
+export const BrandAssetsSchema = z.object({
+  logo: z.string().optional().describe("Logo URL"),
+  favicon: z.string().optional().describe("Favicon URL"),
+  ogImage: z.string().optional().describe("Open Graph image URL"),
+});
+
+export type BrandAssets = z.infer<typeof BrandAssetsSchema>;
+
+// ============================================================================
+// Brand Schema
+// ============================================================================
+
+export const BrandSchema = z.object({
+  id: z.string(),
+  name: z.string().describe("Brand / company name"),
+  domain: z.string().optional().describe("Company domain (e.g. example.com)"),
+  colors: BrandColorsSchema.optional().describe("Semantic color palette"),
+  fonts: BrandFontsSchema.optional().describe("Font families by role"),
+  assets: BrandAssetsSchema.optional().describe("Visual identity assets"),
+  overview: z.string().optional().describe("Company overview / description"),
+  tagline: z.string().optional().describe("Brand tagline"),
+  tone: z.string().optional().describe("Tone of voice description"),
+  metadata: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe("Extra design tokens and metadata"),
+});
+
+export type Brand = z.infer<typeof BrandSchema>;
+
+// ============================================================================
+// BRAND_GET Schemas
+// ============================================================================
+
+export const BrandGetInputSchema = z.object({
+  id: z
+    .string()
+    .optional()
+    .describe("Brand ID. Omit to get the default brand."),
+});
+
+export type BrandGetInput = z.infer<typeof BrandGetInputSchema>;
+
+export type BrandGetOutput = z.infer<typeof BrandSchema>;
+
+// ============================================================================
+// BRAND_LIST Schemas
+// ============================================================================
+
+export const BrandListInputSchema = z.object({});
+
+export type BrandListInput = z.infer<typeof BrandListInputSchema>;
+
+export const BrandListOutputSchema = z.object({
+  items: z.array(BrandSchema),
+});
+
+export type BrandListOutput = z.infer<typeof BrandListOutputSchema>;
+
+// ============================================================================
+// Brand Binding
+// ============================================================================
+
+/**
+ * Brand Binding
+ *
+ * Defines the interface for reading brand context from an organization.
+ *
+ * Required tools:
+ * - BRAND_GET: Get a single brand by ID, or the default brand when no ID
+ *
+ * Optional tools:
+ * - BRAND_LIST: List all active brands
+ */
+export const BRAND_BINDING = [
+  {
+    name: "BRAND_GET" as const,
+    inputSchema: BrandGetInputSchema,
+    outputSchema: BrandSchema,
+  },
+  {
+    name: "BRAND_LIST" as const,
+    inputSchema: BrandListInputSchema,
+    outputSchema: BrandListOutputSchema,
+    opt: true,
+  },
+] satisfies ToolBinder[];
+
+/**
+ * Brand Binding Client
+ *
+ * @example
+ * ```typescript
+ * import { BrandBinding } from "@decocms/bindings/brand";
+ *
+ * const client = BrandBinding.forConnection(connection);
+ *
+ * // Get the default brand
+ * const brand = await client.BRAND_GET({});
+ *
+ * // Get a specific brand
+ * const brand = await client.BRAND_GET({ id: "acme-corp" });
+ *
+ * // List all brands
+ * const { items } = await client.BRAND_LIST({});
+ * ```
+ */
+export const BrandBinding = bindingClient(BRAND_BINDING);
+
+/**
+ * Type helper for the Brand binding client
+ */
+export type BrandBindingClient = ReturnType<typeof BrandBinding.forConnection>;

package/src/well-known/language-model.ts

@@ -712,7 +712,6 @@ export const LANGUAGE_MODEL_BINDING = [
   {
     name: "LLM_DO_STREAM" as const,
     inputSchema: LanguageModelInputSchema,
-    streamable: true,
   },
   {
     name: "LLM_DO_GENERATE" as const,

package/src/well-known/workflow.ts

@@ -21,22 +21,22 @@ export const ToolCallActionSchema = z.object({
   transformCode: z
     .string()
     .optional()
-    .describe(`Pure TypeScript function for data transformation of the tool call result. Must be a TypeScript file that declares the Output interface and exports a default function: \`interface Output { ... } export default async function(input): Output { ... }\`
-    The input will match with the tool call outputSchema. If transformCode is not provided, the tool call result will be used as the step output. 
+    .describe(`Pure TypeScript function for data transformation of the tool call result. Must be a TypeScript file that declares the Output interface and exports a default function: \`interface Output { ... } export default async function(stepInput): Output { ... }\`
+    The stepInput will match with the tool call outputSchema. If transformCode is not provided, the tool call result will be used as the step output.
     Providing an transformCode is recommended because it both allows you to transform the data and validate it against a JSON Schema - tools are ephemeral and may return unexpected data.`),
 });
 export type ToolCallAction = z.infer<typeof ToolCallActionSchema>;
 
 export const CodeActionSchema = z.object({
   code: z.string().describe(
-    `Pure TypeScript function for data transformation. Useful to merge data from multiple steps and transform it. Must be a TypeScript file that declares the Output interface and exports a default function: \`interface Output { ... } export default async function(input): Output { ... }\`
-       The input is the resolved value of the references in the input field. Example: 
+    `Pure TypeScript function for data transformation. Useful to merge data from multiple steps and transform it. Must be a TypeScript file that declares the Output interface and exports a default function: \`interface Output { ... } export default async function(stepInput): Output { ... }\`
+       The stepInput is the resolved value of the references in the input field. Example:
        {
          "input": {
           "name": "@Step_1.name",
           "age": "@Step_2.age"
          },
-         "code": "export default function(input): Output { return { result: \`\${input.name} is \${input.age} years old.\` } }"
+         "code": "export default function(stepInput): Output { return { result: \`\${stepInput.name} is \${stepInput.age} years old.\` } }"
        }
       `,
   ),
@@ -66,19 +66,60 @@ export type StepAction = z.infer<typeof StepActionSchema>;
 /**
  * Step Config Schema - Optional configuration for retry, timeout, and looping
  */
+/**
+ * Step Condition Schema - Structured condition for bail and future `when` support.
+ * Evaluates a resolved @ref against an optional operator.
+ * If no operator is specified, checks for truthiness.
+ */
+export const StepConditionSchema = z.object({
+  ref: z
+    .string()
+    .describe(
+      "@ref to resolve and evaluate, e.g. '@validate.shouldStop' or '@input.skipProcessing'",
+    ),
+  eq: z
+    .unknown()
+    .optional()
+    .describe("Step bails if resolved value equals this"),
+  neq: z
+    .unknown()
+    .optional()
+    .describe("Step bails if resolved value does NOT equal this"),
+  gt: z
+    .number()
+    .optional()
+    .describe("Step bails if resolved value is greater than this"),
+  lt: z
+    .number()
+    .optional()
+    .describe("Step bails if resolved value is less than this"),
+});
+export type StepCondition = z.infer<typeof StepConditionSchema>;
+
 export const StepConfigSchema = z.object({
   maxAttempts: z
     .number()
+    .int()
+    .min(1)
+    .max(10)
     .optional()
     .describe("Max retry attempts on failure (default: 1, no retries)"),
   backoffMs: z
     .number()
+    .int()
+    .min(100)
+    .max(60_000)
     .optional()
     .describe("Initial delay between retries in ms (doubles each attempt)"),
   timeoutMs: z
     .number()
+    .int()
+    .min(100)
+    .max(86_400_000)
     .optional()
-    .describe("Max execution time in ms before step fails (default: 30000)"),
+    .describe(
+      "Max execution time in ms before step fails (default: 30000). Upper bound 24h.",
+    ),
   onError: z
     .enum(["fail", "continue"])
     .optional()
@@ -102,16 +143,21 @@ export type StepConfig = z.infer<typeof StepConfigSchema>;
  * - @ctx.execution_id → current workflow execution ID
  */
 
-type JsonSchema = {
+export type JsonSchema = {
   type?: string;
-  properties?: Record<string, unknown>;
+  properties?: Record<string, JsonSchema>;
   required?: string[];
   description?: string;
   additionalProperties?: boolean | Record<string, unknown>;
   additionalItems?: boolean | Record<string, unknown>;
   items?: JsonSchema;
+  format?: string;
+  enum?: string[];
+  maxLength?: number;
+  anyOf?: JsonSchema[];
+  [key: string]: unknown;
 };
-const JsonSchemaSchema: z.ZodType<JsonSchema> = z.lazy(() =>
+export const JsonSchemaSchema: z.ZodType<JsonSchema> = z.lazy(() =>
   z
     .object({
       type: z.string().optional(),
@@ -127,7 +173,7 @@ const JsonSchemaSchema: z.ZodType<JsonSchema> = z.lazy(() =>
       items: JsonSchemaSchema.optional(),
     })
     .passthrough(),
-);
+) as unknown as z.ZodType<JsonSchema>;
 
 /**
  * Step names that are reserved by the @ref system and cannot be used as step names.
@@ -170,6 +216,12 @@ export const StepSchema = z.object({
         .describe("max parallel iterations. default is 1 (sequential)"),
     })
     .optional(),
+  bail: z
+    .union([z.literal(true), StepConditionSchema])
+    .optional()
+    .describe(
+      "Early return: if true, the workflow exits with this step's output on successful completion. If a condition object, the workflow exits only when the condition is met. Bail is ignored on step error.",
+    ),
 });
 
 export type Step = z.infer<typeof StepSchema>;
@@ -324,6 +376,10 @@ export const WorkflowSchema = BaseCollectionEntitySchema.extend({
     .optional()
     .describe("Human-readable summary of what this workflow does"),
 
+  input_schema: JsonSchemaSchema.optional().describe(
+    "Optional JSON Schema describing the expected input for this workflow.",
+  ),
+
   steps: z
     .array(StepSchema)
     .describe(
@@ -370,7 +426,7 @@ export const DEFAULT_TOOL_STEP: Omit<Step, "name"> = {
     interface Input { 
       
     }
-    export default function(input) { return input.result }`,
+    export default function(stepInput) { return stepInput.result }`,
   },
   input: {
     modelId: "anthropic/claude-4.5-haiku",
@@ -399,10 +455,10 @@ export const DEFAULT_CODE_STEP: Step = {
   interface Output {
     result: unknown;
   }
-    
-  export default async function(input: Input): Promise<Output> { 
+
+  export default async function(stepInput: Input): Promise<Output> {
     return {
-      result: input.example
+      result: stepInput.example
     }
   }`,
   },
@@ -477,6 +533,7 @@ export const WORKFLOW_EXECUTION_BINDING = createCollectionBindings(
 export interface DAGStep {
   name: string;
   input?: unknown;
+  bail?: true | StepCondition;
 }
 
 /**
@@ -491,7 +548,7 @@ export function getAllRefs(input: unknown): string[] {
 
   function traverse(value: unknown) {
     if (typeof value === "string") {
-      const matches = value.match(/@(\w+)/g);
+      const matches = value.match(/@([a-zA-Z_][a-zA-Z0-9_-]*)/g);
       if (matches) {
         refs.push(...matches.map((m) => m.substring(1))); // Remove @ prefix
       }
@@ -523,13 +580,13 @@ export function getStepDependencies(
   function traverse(value: unknown) {
     if (typeof value === "string") {
       // Match @stepName or @stepName.something patterns
-      const matches = value.match(/@(\w+)/g);
+      const matches = value.match(/@([a-zA-Z_][a-zA-Z0-9_-]*)/g);
       if (matches) {
         for (const match of matches) {
           const refName = match.substring(1); // Remove @
           // Only count as dependency if it references another step
           // (not "item", "index", "input" from forEach or workflow input)
-          if (allStepNames.has(refName)) {
+          if (allStepNames.has(refName) && refName !== step.name) {
             deps.push(refName);
           }
         }
@@ -542,6 +599,12 @@ export function getStepDependencies(
   }
 
   traverse(step.input);
+
+  // Extract dependency from bail condition ref
+  if (step.bail && step.bail !== true) {
+    traverse(step.bail.ref);
+  }
+
   return [...new Set(deps)];
 }