@decocms/bindings 1.0.1-alpha.11 → 1.0.1-alpha.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/bindings",
-  "version": "1.0.1-alpha.11",
+  "version": "1.0.1-alpha.13",
   "type": "module",
   "scripts": {
     "test": "vitest run",
@@ -19,7 +19,8 @@
     "./connection": "./src/core/connection.ts",
     "./client": "./src/core/client/index.ts",
     "./mcp": "./src/well-known/mcp.ts",
-    "./agent": "./src/well-known/agent.ts"
+    "./agent": "./src/well-known/agent.ts",
+    "./workflow": "./src/well-known/workflow.ts"
   },
   "devDependencies": {
     "vitest": "3.2.4"

package/src/index.ts

@@ -13,3 +13,10 @@ export {
   type ToolBinder,
   type ToolWithSchemas,
 } from "./core/binder";
+
+// Re-export registry binding types
+export {
+  MCPRegistryServerSchema,
+  type RegistryAppCollectionEntity,
+  REGISTRY_APP_BINDING,
+} from "./well-known/registry";

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

@@ -17,17 +17,229 @@ import {
   createCollectionBindings,
 } from "./collections";
 
+/**
+ * JSON Value Schema
+ * Represents any valid JSON value: null, string, number, boolean, object, or array
+ */
+const JSONValueSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.null(),
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.record(z.string(), JSONValueSchema),
+    z.array(JSONValueSchema),
+  ]),
+);
+
+/**
+ * Provider Options Schema
+ * Additional provider-specific options passed through to the provider
+ */
+const ProviderOptionsSchema = z
+  .record(z.string(), z.record(z.string(), JSONValueSchema))
+  .optional()
+  .describe(
+    "Additional provider-specific options. Outer record keyed by provider name, inner by option key",
+  );
+
+/**
+ * Text Part Schema
+ * Text content part of a prompt
+ */
+const TextPartSchema = z.object({
+  type: z.literal("text"),
+  text: z.string().describe("The text content"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Data Content Schema
+ * File data can be Uint8Array (as base64 string), base64 encoded string, or URL string
+ */
+const DataContentSchema = z
+  .union([z.string(), z.instanceof(Uint8Array)])
+  .describe("File data as base64 encoded string, URL string, or Uint8Array");
+
+/**
+ * File Part Schema
+ * File content part of a prompt
+ */
+const FilePartSchema = z.object({
+  type: z.literal("file"),
+  filename: z.string().optional().describe("Optional filename of the file"),
+  data: DataContentSchema,
+  mediaType: z
+    .string()
+    .describe("IANA media type of the file (e.g., image/png, audio/mp3)"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Reasoning Part Schema
+ * Reasoning content part of a prompt
+ */
+const ReasoningPartSchema = z.object({
+  type: z.literal("reasoning"),
+  text: z.string().describe("The reasoning text"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Tool Call Part Schema
+ * Tool call content part of a prompt (usually generated by the AI model)
+ */
+const ToolCallPartSchema = z.object({
+  type: z.literal("tool-call"),
+  toolCallId: z
+    .string()
+    .describe("ID of the tool call, used to match with tool result"),
+  toolName: z.string().describe("Name of the tool being called"),
+  input: z
+    .unknown()
+    .describe(
+      "Arguments of the tool call (JSON-serializable object matching tool input schema)",
+    ),
+  providerExecuted: z
+    .boolean()
+    .optional()
+    .describe("Whether the tool call will be executed by the provider"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Tool Result Output Schema
+ * The output of a tool result
+ */
+const ToolResultOutputSchema = z.union([
+  z.object({
+    type: z.literal("text"),
+    value: z.string(),
+  }),
+  z.object({
+    type: z.literal("json"),
+    value: JSONValueSchema,
+  }),
+  z.object({
+    type: z.literal("error-text"),
+    value: z.string(),
+  }),
+  z.object({
+    type: z.literal("error-json"),
+    value: JSONValueSchema,
+  }),
+  z.object({
+    type: z.literal("content"),
+    value: z.array(
+      z.union([
+        z.object({
+          type: z.literal("text"),
+          text: z.string().describe("Text content"),
+        }),
+        z.object({
+          type: z.literal("media"),
+          data: z.string().describe("Base-64 encoded media data"),
+          mediaType: z.string().describe("IANA media type"),
+        }),
+      ]),
+    ),
+  }),
+]);
+
+/**
+ * Tool Result Part Schema
+ * Tool result content part of a prompt
+ */
+const ToolResultPartSchema = z.object({
+  type: z.literal("tool-result"),
+  toolCallId: z
+    .string()
+    .describe("ID of the tool call that this result is associated with"),
+  toolName: z.string().describe("Name of the tool that generated this result"),
+  output: ToolResultOutputSchema.describe("Result of the tool call"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * System Message Schema
+ */
+const SystemMessageSchema = z.object({
+  role: z.literal("system"),
+  content: z.string().describe("System message content"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * User Message Schema
+ */
+const UserMessageSchema = z.object({
+  role: z.literal("user"),
+  content: z
+    .array(z.union([TextPartSchema, FilePartSchema]))
+    .describe("User message content parts (text or file)"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Assistant Message Schema
+ */
+const AssistantMessageSchema = z.object({
+  role: z.literal("assistant"),
+  content: z
+    .array(
+      z.union([
+        TextPartSchema,
+        FilePartSchema,
+        ReasoningPartSchema,
+        ToolCallPartSchema,
+        ToolResultPartSchema,
+      ]),
+    )
+    .describe(
+      "Assistant message content parts (text, file, reasoning, tool-call, or tool-result)",
+    ),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Tool Message Schema
+ */
+const ToolMessageSchema = z.object({
+  role: z.literal("tool"),
+  content: z
+    .array(ToolResultPartSchema)
+    .describe("Tool message content (tool results)"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Language Model Message Schema
+ * A message in a language model prompt
+ */
+export const LanguageModelMessageSchema = z.union([
+  SystemMessageSchema,
+  UserMessageSchema,
+  AssistantMessageSchema,
+  ToolMessageSchema,
+]);
+
+/**
+ * Language Model Prompt Schema
+ * A prompt is a list of messages based on LanguageModelV2Prompt from @ai-sdk/provider
+ */
+export const LanguageModelPromptSchema = z
+  .array(LanguageModelMessageSchema)
+  .describe("A list of messages forming the prompt");
+
 /**
  * Language Model Call Options Schema
  * Based on LanguageModelV2CallOptions from @ai-sdk/provider
  */
 export const LanguageModelCallOptionsSchema = z.object({
   // Core parameters
-  prompt: z
-    .any()
-    .describe(
-      "A language mode prompt is a standardized prompt type (messages, system, etc.)",
-    ),
+  prompt: LanguageModelPromptSchema.describe(
+    "A language model prompt is a standardized prompt type (array of messages with roles: system, user, assistant, tool)",
+  ),
 
   // Generation parameters
   maxOutputTokens: z

package/src/well-known/mcp.ts

@@ -4,7 +4,7 @@
  * Defines the interface for retrieving MCP configuration.
  */
 
-import { z } from "zod/v3";
+import { z } from "zod";
 import type { Binder } from "../core/binder";
 
 /**

package/src/well-known/registry.ts

@@ -0,0 +1,128 @@
+/**
+ * Registry App Well-Known Binding
+ *
+ * Defines the interface for accessing public registry apps.
+ * Any MCP that implements this binding can provide a list of available apps
+ * with their configurations and tools.
+ *
+ * This binding includes:
+ * - Collection bindings for LIST and GET operations (read-only)
+ * - Only exposes public apps (unlisted: false)
+ * - Removes sensitive fields (connection details, workspace info)
+ */
+
+import { z } from "zod";
+import {
+  BaseCollectionEntitySchema,
+  createCollectionBindings,
+} from "./collections";
+
+/**
+ * Tool definition schema from registry
+ */
+const RegistryToolSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().optional(),
+  inputSchema: z.record(z.unknown()),
+  outputSchema: z.record(z.unknown()).optional(),
+});
+
+/**
+ * MCP Registry Server schema extending Collection Entity base
+ * Combines BaseCollectionEntitySchema with MCP Registry Spec format
+ * https://spec.modelcontextprotocol.io/specification/2025-03-26/registry/
+ */
+export const MCPRegistryServerSchema = BaseCollectionEntitySchema.extend({
+  // MCP Registry Spec structure
+  _meta: z
+    .object({
+      "io.decocms": z
+        .object({
+          id: z.string(),
+          verified: z.boolean(),
+          scopeName: z.string(),
+          appName: z.string(),
+          friendlyName: z.string().nullable().optional(),
+          metadata: z.record(z.unknown()).nullable().optional(),
+          publishedAt: z.string().datetime().optional(),
+          updatedAt: z.string().datetime().optional(),
+          tools: z
+            .array(RegistryToolSchema)
+            .nullable()
+            .optional()
+            .describe("Available tools exposed by this app"),
+        })
+        .optional(),
+    })
+    .optional(),
+  server: z.object({
+    $schema: z.string().optional(),
+    _meta: z.record(z.unknown()).optional(),
+    name: z.string().describe("The server name (scope/app)"),
+    title: z.string().optional().describe("User-friendly title"),
+    description: z.string().optional().describe("Server description"),
+    icons: z
+      .array(
+        z.object({
+          src: z.string(),
+          mimeType: z.string().optional(),
+          sizes: z.array(z.string()).optional(),
+          theme: z.enum(["light", "dark"]).optional(),
+        }),
+      )
+      .optional(),
+    remotes: z
+      .array(
+        z.object({
+          type: z.enum(["http", "stdio", "sse"]),
+          url: z.string().optional(),
+          headers: z.array(z.unknown()).optional(),
+        }),
+      )
+      .optional(),
+    packages: z.array(z.unknown()).optional(),
+    repository: z
+      .object({
+        url: z.string(),
+        source: z.string().optional(),
+        subfolder: z.string().optional(),
+      })
+      .optional(),
+    version: z.string().optional(),
+    websiteUrl: z.string().optional(),
+  }),
+});
+
+export type RegistryAppCollectionEntity = z.infer<
+  typeof MCPRegistryServerSchema
+>;
+
+/**
+ * Registry App Collection Binding (read-only)
+ *
+ * Collection bindings for registry apps (read-only).
+ * Provides LIST and GET operations for public apps.
+ * Only includes public apps (unlisted: false).
+ *
+ * Returns servers in MCP Registry Spec format with:
+ * - _meta: DecoCMS-specific metadata (id, verified, tools, etc.)
+ * - server: MCP Registry Spec compliant server definition
+ */
+const REGISTRY_APP_COLLECTION_BINDING = createCollectionBindings(
+  "registry_app",
+  MCPRegistryServerSchema,
+  { readOnly: true },
+);
+
+/**
+ * Registry App Binding
+ *
+ * Defines the interface for accessing public registry apps.
+ * Any MCP that implements this binding can provide a searchable list of apps.
+ *
+ * Required tools:
+ * - COLLECTION_REGISTRY_APP_LIST: List available apps with filtering and pagination
+ * - COLLECTION_REGISTRY_APP_GET: Get a single app by ID
+ */
+export const REGISTRY_APP_BINDING = REGISTRY_APP_COLLECTION_BINDING;

package/src/well-known/workflow.ts

@@ -0,0 +1,297 @@
+/**
+ * Workflows Well-Known Binding
+ *
+ * Defines the interface for workflow providers.
+ * Any MCP that implements this binding can expose configurable workflows,
+ * executions, step results, and events via collection bindings.
+ *
+ * This binding uses collection bindings for LIST and GET operations (read-only).
+ */
+
+import { z } from "zod";
+import type { Binder } from "../core/binder";
+import {
+  BaseCollectionEntitySchema,
+  createCollectionBindings,
+} from "./collections";
+
+export const ToolCallActionSchema = z.object({
+  connectionId: z.string().describe("Integration connection ID"),
+  toolName: z.string().describe("Name of the tool to call"),
+});
+export type ToolCallAction = z.infer<typeof ToolCallActionSchema>;
+
+export const CodeActionSchema = z.object({
+  code: z.string().describe("TypeScript code for pure data transformation"),
+});
+export type CodeAction = z.infer<typeof CodeActionSchema>;
+export const SleepActionSchema = z.union([
+  z.object({
+    sleepMs: z.number().describe("Milliseconds to sleep"),
+  }),
+  z.object({
+    sleepUntil: z.string().describe("ISO date string or @ref to sleep until"),
+  }),
+]);
+
+export const WaitForSignalActionSchema = z.object({
+  signalName: z
+    .string()
+    .describe("Name of the signal to wait for (must be unique per execution)"),
+  timeoutMs: z
+    .number()
+    .optional()
+    .describe("Maximum time to wait in milliseconds (default: no timeout)"),
+  description: z
+    .string()
+    .optional()
+    .describe("Human-readable description of what this signal is waiting for"),
+});
+export type WaitForSignalAction = z.infer<typeof WaitForSignalActionSchema>;
+
+export const StepActionSchema = z.union([
+  ToolCallActionSchema.describe(
+    "Call an external tool (non-deterministic, checkpointed)",
+  ),
+  CodeActionSchema.describe(
+    "Pure TypeScript data transformation (deterministic, replayable)",
+  ),
+  SleepActionSchema.describe("Wait for time"),
+  WaitForSignalActionSchema.describe("Wait for external signal"),
+]);
+export type StepAction = z.infer<typeof StepActionSchema>;
+/**
+ * Step Schema - Unified schema for all step types
+ *
+ * Step types:
+ * - tool: Call external service via MCP (non-deterministic, checkpointed)
+ * - transform: Pure TypeScript data transformation (deterministic, replayable)
+ * - sleep: Wait for time
+ * - waitForSignal: Block until external signal (human-in-the-loop)
+ */
+export const StepSchema = z.object({
+  name: z.string().min(1).describe("Unique step name within workflow"),
+  action: StepActionSchema,
+  input: z
+    .record(z.unknown())
+    .optional()
+    .describe(
+      "Input object with @ref resolution or default values. Example: { 'user_id': '@input.user_id', 'product_id': '@input.product_id' }",
+    ),
+  config: z
+    .object({
+      maxAttempts: z.number().default(3).describe("Maximum retry attempts"),
+      backoffMs: z
+        .number()
+        .default(1000)
+        .describe("Initial backoff in milliseconds"),
+      timeoutMs: z.number().default(10000).describe("Timeout in milliseconds"),
+    })
+    .optional()
+    .describe("Step configuration (max attempts, backoff, timeout)"),
+});
+
+export type Step = z.infer<typeof StepSchema>;
+
+/**
+ * Trigger Schema - Fire another workflow when execution completes
+ */
+export const TriggerSchema = z.object({
+  /**
+   * Target workflow ID to execute
+   */
+  workflowId: z.string().describe("Target workflow ID to trigger"),
+
+  /**
+   * Input for the new execution (uses @refs like step inputs)
+   * Maps output data to workflow input fields.
+   *
+   * If any @ref doesn't resolve (property missing), this trigger is SKIPPED.
+   */
+  input: z
+    .record(z.unknown())
+    .describe(
+      "Input mapping with @refs from current workflow output. Example: { 'user_id': '@stepName.output.user_id' }",
+    ),
+});
+
+export type Trigger = z.infer<typeof TriggerSchema>;
+
+/**
+ * Workflow Execution Status
+ *
+ * States:
+ * - pending: Created but not started
+ * - running: Currently executing
+ * - completed: Successfully finished
+ * - cancelled: Manually cancelled
+ */
+
+const WorkflowExecutionStatusEnum = z
+  .enum(["pending", "running", "completed", "cancelled"])
+  .default("pending");
+export type WorkflowExecutionStatus = z.infer<
+  typeof WorkflowExecutionStatusEnum
+>;
+
+/**
+ * Workflow Execution Schema
+ *
+ * Includes lock columns and retry tracking.
+ */
+export const WorkflowExecutionSchema = BaseCollectionEntitySchema.extend({
+  workflow_id: z.string(),
+  status: WorkflowExecutionStatusEnum,
+  input: z.record(z.unknown()).optional(),
+  output: z.unknown().optional(),
+  parent_execution_id: z.string().nullish(),
+  completed_at_epoch_ms: z.number().nullish(),
+  locked_until_epoch_ms: z.number().nullish(),
+  lock_id: z.string().nullish(),
+  retry_count: z.number().default(0),
+  max_retries: z.number().default(10),
+  error: z.string().nullish(),
+});
+export type WorkflowExecution = z.infer<typeof WorkflowExecutionSchema>;
+
+/**
+ * Execution Step Result Schema
+ *
+ * Includes attempt tracking and error history.
+ */
+export const WorkflowExecutionStepResultSchema =
+  BaseCollectionEntitySchema.extend({
+    execution_id: z.string(),
+    step_id: z.string(),
+
+    input: z.record(z.unknown()).nullish(),
+    output: z.unknown().nullish(), // Can be object or array (forEach steps produce arrays)
+    error: z.string().nullish(),
+    completed_at_epoch_ms: z.number().nullish(),
+  });
+export type WorkflowExecutionStepResult = z.infer<
+  typeof WorkflowExecutionStepResultSchema
+>;
+/**
+ * Event Type Enum
+ *
+ * Event types for the unified events table:
+ * - signal: External signal (human-in-the-loop)
+ * - timer: Durable sleep wake-up
+ * - message: Inter-workflow communication (send/recv)
+ * - output: Published value (setEvent/getEvent)
+ * - step_started: Observability - step began
+ * - step_completed: Observability - step finished
+ * - workflow_started: Workflow began execution
+ * - workflow_completed: Workflow finished
+ */
+export const EventTypeEnum = z.enum([
+  "signal",
+  "timer",
+  "message",
+  "output",
+  "step_started",
+  "step_completed",
+  "workflow_started",
+  "workflow_completed",
+]);
+
+export type EventType = z.infer<typeof EventTypeEnum>;
+
+/**
+ * Workflow Event Schema
+ *
+ * Unified events table for signals, timers, messages, and observability.
+ */
+export const WorkflowEventSchema = BaseCollectionEntitySchema.extend({
+  execution_id: z.string(),
+  type: EventTypeEnum,
+  name: z.string().nullish(),
+  payload: z.unknown().optional(),
+  visible_at: z.number().nullish(),
+  consumed_at: z.number().nullish(),
+  source_execution_id: z.string().nullish(),
+});
+
+export type WorkflowEvent = z.infer<typeof WorkflowEventSchema>;
+
+/**
+ * Workflow entity schema for workflows
+ * Extends BaseCollectionEntitySchema with workflow-specific fields
+ * Base schema already includes: id, title, created_at, updated_at, created_by, updated_by
+ */
+export const WorkflowSchema = BaseCollectionEntitySchema.extend({
+  description: z.string().optional().describe("Workflow description"),
+
+  /**
+   * Steps organized into phases.
+   * - Phases execute sequentially
+   * - Steps within a phase execute in parallel
+   */
+  steps: z
+    .array(z.array(StepSchema))
+    .describe("2D array: phases (sequential) containing steps (parallel)"),
+
+  /**
+   * Triggers to fire when execution completes successfully
+   */
+  triggers: z
+    .array(TriggerSchema)
+    .optional()
+    .describe("Workflows to trigger on completion"),
+});
+
+export type Workflow = z.infer<typeof WorkflowSchema>;
+
+/**
+ * WORKFLOW Collection Binding
+ *
+ * Collection bindings for workflows (read-only).
+ * Provides LIST and GET operations for workflows.
+ */
+export const WORKFLOWS_COLLECTION_BINDING = createCollectionBindings(
+  "workflow",
+  WorkflowSchema,
+);
+
+export const WORKFLOW_EXECUTIONS_COLLECTION_BINDING = createCollectionBindings(
+  "workflow_execution",
+  WorkflowExecutionSchema,
+  {
+    readOnly: true,
+  },
+);
+
+export const WORKFLOW_STEP_RESULTS_COLLECTION_BINDING =
+  createCollectionBindings(
+    "workflow_execution_step_results",
+    WorkflowExecutionStepResultSchema,
+    {
+      readOnly: true,
+    },
+  );
+
+export const WORKFLOW_EVENTS_COLLECTION_BINDING = createCollectionBindings(
+  "workflow_events",
+  WorkflowEventSchema,
+  {
+    readOnly: true,
+  },
+);
+
+/**
+ * WORKFLOWS Binding
+ *
+ * Defines the interface for workflow providers.
+ * Any MCP that implements this binding can provide configurable workflows.
+ *
+ * Required tools:
+ * - COLLECTION_WORKFLOW_LIST: List available workflows with their configurations
+ * - COLLECTION_WORKFLOW_GET: Get a single workflow by ID (includes steps and triggers)
+ */
+export const WORKFLOWS_BINDING = [
+  ...WORKFLOWS_COLLECTION_BINDING,
+  ...WORKFLOW_EXECUTIONS_COLLECTION_BINDING,
+  ...WORKFLOW_STEP_RESULTS_COLLECTION_BINDING,
+  ...WORKFLOW_EVENTS_COLLECTION_BINDING,
+] as const satisfies Binder;