@decocms/bindings 1.3.1 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/bindings",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "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

@@ -111,7 +111,9 @@ export {
   type ReportsBinding,
   type ReportStatus,
   type ReportLifecycleStatus,
+  type CriterionItem,
   type MetricItem,
+  type RankedListRow,
   type ReportSection,
   type ReportSummary,
   type Report,
@@ -127,4 +129,6 @@ export {
   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/reports.ts

@@ -48,6 +48,50 @@ export const MetricItemSchema = z.object({
 });
 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.
@@ -70,6 +114,20 @@ export const ReportSectionSchema = z.discriminatedUnion("type", [
       .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>;
 
@@ -88,6 +146,9 @@ export type ReportLifecycleStatus = z.infer<typeof ReportLifecycleStatusSchema>;
  */
 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()
@@ -121,6 +182,58 @@ export const ReportSchema = ReportSummarySchema.extend({
 });
 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
 // ============================================================================

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 = {
@@ -106,8 +107,8 @@ type JsonSchema = {
   properties?: Record<string, unknown>;
   required?: string[];
   description?: string;
-  additionalProperties?: boolean;
-  additionalItems?: boolean;
+  additionalProperties?: boolean | Record<string, unknown>;
+  additionalItems?: boolean | Record<string, unknown>;
   items?: JsonSchema;
 };
 const JsonSchemaSchema: z.ZodType<JsonSchema> = z.lazy(() =>
@@ -117,17 +118,33 @@ const JsonSchemaSchema: z.ZodType<JsonSchema> = z.lazy(() =>
       properties: z.record(z.string(), z.unknown()).optional(),
       required: z.array(z.string()).optional(),
       description: z.string().optional(),
-      additionalProperties: z.boolean().optional(),
-      additionalItems: z.boolean().optional(),
+      additionalProperties: z
+        .union([z.boolean(), z.record(z.string(), z.unknown())])
+        .optional(),
+      additionalItems: z
+        .union([z.boolean(), z.record(z.string(), z.unknown())])
+        .optional(),
       items: JsonSchemaSchema.optional(),
     })
     .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 +154,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.",