@decocms/bindings 1.3.0 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/bindings",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",
@@ -30,6 +30,7 @@
     "./workflow": "./src/well-known/workflow.ts",
     "./plugins": "./src/core/plugins.ts",
     "./plugin-router": "./src/core/plugin-router.tsx",
+    "./ai-gateway": "./src/well-known/ai-gateway.ts",
     "./server-plugin": "./src/core/server-plugin.ts"
   },
   "engines": {

package/src/core/server-plugin.ts

@@ -40,7 +40,14 @@ export interface ServerPluginToolContext {
       structuredContent?: unknown;
     }>;
     listTools: () => Promise<{
-      tools: Array<{ name: string; description?: string }>;
+      tools: Array<{
+        name: string;
+        title?: string;
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+        outputSchema?: Record<string, unknown>;
+        annotations?: Record<string, unknown>;
+      }>;
     }>;
     close?: () => Promise<void>;
   }>;

package/src/index.ts

@@ -104,3 +104,31 @@ export {
 
 // Re-export workflow binding types
 export { WORKFLOWS_COLLECTION_BINDING } from "./well-known/workflow";
+
+// Re-export reports binding types
+export {
+  REPORTS_BINDING,
+  type ReportsBinding,
+  type ReportStatus,
+  type ReportLifecycleStatus,
+  type CriterionItem,
+  type MetricItem,
+  type RankedListRow,
+  type ReportSection,
+  type ReportSummary,
+  type Report,
+  type ReportsListInput,
+  type ReportsListOutput,
+  type ReportsGetInput,
+  type ReportsGetOutput,
+  type ReportsUpdateStatusInput,
+  type ReportsUpdateStatusOutput,
+  ReportStatusSchema,
+  ReportLifecycleStatusSchema,
+  MetricItemSchema,
+  ReportSectionSchema,
+  ReportSummarySchema,
+  ReportSchema,
+  type SectionGroup,
+  groupSections,
+} from "./well-known/reports";

package/src/well-known/ai-gateway.ts

@@ -0,0 +1,63 @@
+/**
+ * AI Gateway Billing Well-Known Binding
+ *
+ * Defines the interface for AI gateways that support billing management.
+ * Any MCP that implements this binding is recognized as a billing-capable
+ * AI gateway, regardless of its URL.
+ *
+ * Required tools:
+ * - GATEWAY_USAGE: Returns spending, usage, limits, and alert configuration
+ *
+ * Optional tools:
+ * - GATEWAY_SET_LIMIT: Configure spending limit / add credit
+ * - GATEWAY_SET_ALERT: Configure usage/balance alerts
+ */
+
+import { z } from "zod";
+import type { Binder } from "../core/binder";
+
+export const GATEWAY_USAGE_INPUT = z.object({}).strict();
+
+export const GATEWAY_USAGE_OUTPUT = z.object({
+  billing: z.object({
+    mode: z.enum(["prepaid", "postpaid"]),
+    limitPeriod: z.enum(["daily", "weekly", "monthly"]).nullable(),
+  }),
+  limit: z.object({
+    total: z.number().nullable(),
+    remaining: z.number().nullable(),
+    reset: z.string().nullable(),
+  }),
+  usage: z.object({
+    total: z.number(),
+    daily: z.number(),
+    weekly: z.number(),
+    monthly: z.number(),
+  }),
+  alert: z.object({
+    enabled: z.boolean(),
+    threshold_usd: z.number(),
+    email: z.string().nullable(),
+  }),
+  connectionId: z.string(),
+});
+
+export const AI_GATEWAY_BILLING_BINDING = [
+  {
+    name: "GATEWAY_USAGE" as const,
+    inputSchema: GATEWAY_USAGE_INPUT,
+    outputSchema: GATEWAY_USAGE_OUTPUT,
+  },
+  {
+    name: "GATEWAY_SET_LIMIT" as const,
+    inputSchema: z.object({}),
+    outputSchema: z.object({}),
+    opt: true,
+  },
+  {
+    name: "GATEWAY_SET_ALERT" as const,
+    inputSchema: z.object({}),
+    outputSchema: z.object({}),
+    opt: true,
+  },
+] as const satisfies Binder;

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

@@ -166,7 +166,10 @@ const ToolCallOutputPartSchema = z.object({
 
 /**
  * Tool Result Output Schema
- * The output of a tool result
+ * The output of a tool result.
+ * Accepts typed objects (text, json, error-text, error-json, content),
+ * execution-denied (from AI SDK tool approval flow), and raw strings
+ * (JSON-serialized outputs from mapToolResultOutput).
  */
 const ToolResultOutputSchema = z.union([
   z.object({
@@ -201,6 +204,15 @@ const ToolResultOutputSchema = z.union([
       ]),
     ),
   }),
+  z.object({
+    type: z.literal("execution-denied"),
+    reason: z.string().optional(),
+  }),
+  z
+    .string()
+    .describe(
+      "Raw or JSON-serialized output (e.g. from AI SDK mapToolResultOutput)",
+    ),
 ]);
 
 /**

package/src/well-known/reports.ts

@@ -0,0 +1,333 @@
+/**
+ * Reports Well-Known Binding
+ *
+ * Defines the interface for viewing automated reports.
+ * Any MCP that implements this binding can provide reports to the Reports plugin
+ * (e.g. performance audits, security scans, accessibility checks).
+ *
+ * This binding includes:
+ * - REPORTS_LIST: List all available reports with metadata
+ * - REPORTS_GET: Get a specific report with full content
+ */
+
+import { z } from "zod";
+import type { Binder, ToolBinder } from "../core/binder";
+
+// ============================================================================
+// Shared Schemas
+// ============================================================================
+
+/**
+ * Report status indicates the overall health/outcome of the report.
+ */
+export const ReportStatusSchema = z.enum([
+  "passing",
+  "warning",
+  "failing",
+  "info",
+]);
+export type ReportStatus = z.infer<typeof ReportStatusSchema>;
+
+/**
+ * A single metric item within a metrics section.
+ */
+export const MetricItemSchema = z.object({
+  label: z.string().describe("Metric label (e.g. 'LCP', 'Performance')"),
+  value: z.union([z.number(), z.string()]).describe("Current metric value"),
+  unit: z
+    .string()
+    .optional()
+    .describe("Unit of measurement (e.g. 's', 'ms', 'score')"),
+  previousValue: z
+    .union([z.number(), z.string()])
+    .optional()
+    .describe("Previous value for delta comparison"),
+  status: ReportStatusSchema.optional().describe(
+    "Status of this individual metric",
+  ),
+});
+export type MetricItem = z.infer<typeof MetricItemSchema>;
+
+/**
+ * A single criterion item within a criteria section.
+ */
+export const CriterionItemSchema = z.object({
+  label: z.string().describe("Short name of the criterion"),
+  description: z.string().optional().describe("Longer explanation"),
+  status: ReportStatusSchema.optional().describe(
+    "Status of this individual criterion (passing/warning/failing/info)",
+  ),
+});
+export type CriterionItem = z.infer<typeof CriterionItemSchema>;
+
+/**
+ * A single row within a ranked-list section.
+ */
+export const RankedListRowSchema = z.object({
+  position: z.number().describe("Current rank position"),
+  reference_position: z
+    .number()
+    .optional()
+    .describe(
+      "Previous rank position before reordering. Used to compute delta automatically (delta = reference_position - position).",
+    ),
+  delta: z
+    .number()
+    .optional()
+    .describe(
+      "Explicit change in position. Ignored when reference_position is provided.",
+    ),
+  label: z.string().describe("Item name"),
+  image: z.string().describe("URL of the item image"),
+  values: z
+    .array(z.union([z.string(), z.number()]))
+    .describe("Values matching columns"),
+  note: z
+    .union([
+      z.string(),
+      z.record(z.string(), z.union([z.string(), z.number()])),
+    ])
+    .optional()
+    .describe("Inline annotation or structured key-value metrics"),
+});
+export type RankedListRow = z.infer<typeof RankedListRowSchema>;
+
+/**
+ * Report sections -- polymorphic by type.
+ * Sections represent the main content blocks of a report.
+ */
+export const ReportSectionSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("markdown"),
+    content: z.string().describe("Markdown content"),
+  }),
+  z.object({
+    type: z.literal("metrics"),
+    title: z.string().optional().describe("Section title"),
+    items: z.array(MetricItemSchema).describe("Metric items"),
+  }),
+  z.object({
+    type: z.literal("table"),
+    title: z.string().optional().describe("Section title"),
+    columns: z.array(z.string()).describe("Column headers"),
+    rows: z
+      .array(z.array(z.union([z.string(), z.number(), z.null()])))
+      .describe("Table rows"),
+  }),
+  z.object({
+    type: z.literal("criteria"),
+    title: z.string().optional().describe("Section title"),
+    items: z.array(CriterionItemSchema).describe("List of criteria items"),
+  }),
+  z.object({
+    type: z.literal("note"),
+    content: z.string().describe("The note text"),
+  }),
+  z.object({
+    type: z.literal("ranked-list"),
+    title: z.string().optional().describe("Section title"),
+    rows: z.array(RankedListRowSchema).describe("Ranked items"),
+  }),
+]);
+export type ReportSection = z.infer<typeof ReportSectionSchema>;
+
+/**
+ * Lifecycle status of a report within the inbox workflow.
+ */
+export const ReportLifecycleStatusSchema = z.enum([
+  "unread",
+  "read",
+  "dismissed",
+]);
+export type ReportLifecycleStatus = z.infer<typeof ReportLifecycleStatusSchema>;
+
+/**
+ * Summary of a report returned by REPORTS_LIST.
+ */
+export const ReportSummarySchema = z.object({
+  id: z.string().describe("Unique report identifier"),
+  collectionId: z
+    .string()
+    .describe("Collection identifier used to scope reports"),
+  title: z.string().describe("Report title"),
+  category: z
+    .string()
+    .describe(
+      "Report category (e.g. 'performance', 'security', 'accessibility')",
+    ),
+  status: ReportStatusSchema.describe("Overall report status"),
+  summary: z.string().describe("One-line summary of findings"),
+  updatedAt: z.string().describe("ISO 8601 timestamp of last update"),
+  source: z
+    .string()
+    .optional()
+    .describe(
+      "Agent or service that generated the report (e.g. 'security-auditor', 'performance-monitor')",
+    ),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Free-form tags for filtering (e.g. 'homepage', 'api', 'ci')"),
+  lifecycleStatus: ReportLifecycleStatusSchema.optional().describe(
+    "Inbox lifecycle status of the report (default: unread)",
+  ),
+});
+export type ReportSummary = z.infer<typeof ReportSummarySchema>;
+
+/**
+ * Full report returned by REPORTS_GET.
+ */
+export const ReportSchema = ReportSummarySchema.extend({
+  sections: z.array(ReportSectionSchema).describe("Ordered content sections"),
+});
+export type Report = z.infer<typeof ReportSchema>;
+
+// ============================================================================
+// UI Helpers
+// ============================================================================
+
+/**
+ * Groups adjacent criteria+metrics sections into side-by-side pairs for display.
+ * In a pair, criteria always goes left and metrics always goes right,
+ * regardless of their original order.
+ */
+
+type SingleGroup = { type: "single"; section: ReportSection; idx: number };
+type SideBySideGroup = {
+  type: "side-by-side";
+  left: Extract<ReportSection, { type: "criteria" }>;
+  right: Extract<ReportSection, { type: "metrics" }>;
+  leftIdx: number;
+  rightIdx: number;
+};
+export type SectionGroup = SingleGroup | SideBySideGroup;
+
+export function groupSections(sections: ReportSection[]): SectionGroup[] {
+  const groups: SectionGroup[] = [];
+  let i = 0;
+  while (i < sections.length) {
+    const current = sections[i]!;
+    const next = sections[i + 1];
+    const isPair =
+      (current.type === "criteria" && next?.type === "metrics") ||
+      (current.type === "metrics" && next?.type === "criteria");
+
+    if (isPair) {
+      const isCriteriaFirst = current.type === "criteria";
+      const criteria = isCriteriaFirst ? current : next!;
+      const metrics = isCriteriaFirst ? next! : current;
+      const criteriaIdx = isCriteriaFirst ? i : i + 1;
+      const metricsIdx = isCriteriaFirst ? i + 1 : i;
+      groups.push({
+        type: "side-by-side",
+        left: criteria as Extract<ReportSection, { type: "criteria" }>,
+        right: metrics as Extract<ReportSection, { type: "metrics" }>,
+        leftIdx: criteriaIdx,
+        rightIdx: metricsIdx,
+      });
+      i += 2;
+    } else {
+      groups.push({ type: "single", section: current, idx: i });
+      i += 1;
+    }
+  }
+  return groups;
+}
+
+// ============================================================================
+// Tool Schemas
+// ============================================================================
+
+/**
+ * REPORTS_LIST - List all available reports with optional filters
+ */
+const ReportsListInputSchema = z.object({
+  category: z
+    .string()
+    .optional()
+    .describe("Filter by category (e.g. 'performance', 'security')"),
+  status: ReportStatusSchema.optional().describe("Filter by report status"),
+});
+
+const ReportsListOutputSchema = z.object({
+  reports: z.array(ReportSummarySchema).describe("List of report summaries"),
+});
+
+export type ReportsListInput = z.infer<typeof ReportsListInputSchema>;
+export type ReportsListOutput = z.infer<typeof ReportsListOutputSchema>;
+
+/**
+ * REPORTS_GET - Get a specific report with full content
+ */
+const ReportsGetInputSchema = z.object({
+  id: z.string().describe("Report identifier"),
+});
+
+const ReportsGetOutputSchema = ReportSchema;
+
+export type ReportsGetInput = z.infer<typeof ReportsGetInputSchema>;
+export type ReportsGetOutput = z.infer<typeof ReportsGetOutputSchema>;
+
+/**
+ * REPORTS_UPDATE_STATUS - Update the lifecycle status of a report (optional tool)
+ */
+const ReportsUpdateStatusInputSchema = z.object({
+  reportId: z.string().describe("Report identifier"),
+  lifecycleStatus: ReportLifecycleStatusSchema.describe(
+    "New lifecycle status for the report",
+  ),
+});
+
+const ReportsUpdateStatusOutputSchema = z.object({
+  success: z.boolean().describe("Whether the operation succeeded"),
+  message: z.string().optional().describe("Human-readable result message"),
+});
+
+export type ReportsUpdateStatusInput = z.infer<
+  typeof ReportsUpdateStatusInputSchema
+>;
+export type ReportsUpdateStatusOutput = z.infer<
+  typeof ReportsUpdateStatusOutputSchema
+>;
+
+// ============================================================================
+// Binding Definition
+// ============================================================================
+
+/**
+ * Reports Binding
+ *
+ * Defines the interface for viewing automated reports.
+ * Any MCP that implements this binding can be used with the Reports plugin.
+ *
+ * Required tools:
+ * - REPORTS_LIST: List available reports with optional filtering
+ * - REPORTS_GET: Get a single report with full content
+ *
+ * Optional tools:
+ * - REPORTS_UPDATE_STATUS: Update the lifecycle status of a report (unread → read → dismissed)
+ */
+export const REPORTS_BINDING = [
+  {
+    name: "REPORTS_LIST" as const,
+    inputSchema: ReportsListInputSchema,
+    outputSchema: ReportsListOutputSchema,
+  } satisfies ToolBinder<"REPORTS_LIST", ReportsListInput, ReportsListOutput>,
+  {
+    name: "REPORTS_GET" as const,
+    inputSchema: ReportsGetInputSchema,
+    outputSchema: ReportsGetOutputSchema,
+  } satisfies ToolBinder<"REPORTS_GET", ReportsGetInput, ReportsGetOutput>,
+  {
+    name: "REPORTS_UPDATE_STATUS" as const,
+    inputSchema: ReportsUpdateStatusInputSchema,
+    outputSchema: ReportsUpdateStatusOutputSchema,
+    opt: true,
+  } satisfies ToolBinder<
+    "REPORTS_UPDATE_STATUS",
+    ReportsUpdateStatusInput,
+    ReportsUpdateStatusOutput
+  >,
+] as const satisfies Binder;
+
+export type ReportsBinding = typeof REPORTS_BINDING;

package/src/well-known/workflow.ts

@@ -99,6 +99,7 @@ export type StepConfig = z.infer<typeof StepConfigSchema>;
  * Data flow uses @ref syntax:
  * - @input.field → workflow input
  * - @stepName.field → output from a previous step
+ * - @ctx.execution_id → current workflow execution ID
  */
 
 type JsonSchema = {
@@ -124,10 +125,22 @@ const JsonSchemaSchema: z.ZodType<JsonSchema> = z.lazy(() =>
     .passthrough(),
 );
 
+/**
+ * Step names that are reserved by the @ref system and cannot be used as step names.
+ * These are intercepted before step lookup in the ref resolver.
+ */
+export const RESERVED_STEP_NAMES = ["input", "item", "index", "ctx"] as const;
+
 export const StepSchema = z.object({
   name: z
     .string()
     .min(1)
+    .refine(
+      (name) => !(RESERVED_STEP_NAMES as readonly string[]).includes(name),
+      {
+        message: `Step name is reserved. Reserved names: ${RESERVED_STEP_NAMES.join(", ")}`,
+      },
+    )
     .describe(
       "Unique identifier for this step. Other steps reference its output as @name.field",
     ),
@@ -137,7 +150,7 @@ export const StepSchema = z.object({
     .record(z.string(), z.unknown())
     .optional()
     .describe(
-      "Data passed to the action. Use @ref for dynamic values: @input.field (workflow input), @stepName.field (previous step output), @item/@index (loop context). Example: { 'userId': '@input.user_id', 'data': '@fetch.result' }",
+      "Data passed to the action. Use @ref for dynamic values: @input.field (workflow input), @stepName.field (previous step output), @item/@index (loop context), @ctx.execution_id (current execution ID). Example: { 'userId': '@input.user_id', 'data': '@fetch.result', 'executionId': '@ctx.execution_id' }",
     ),
   outputSchema: JsonSchemaSchema.optional().describe(
     "Optional JSON Schema describing the expected output of the step.",