@decocms/runtime 1.2.14 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/runtime",
-  "version": "1.2.14",
+  "version": "1.3.0",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",
@@ -22,7 +22,9 @@
     "./bindings": "./src/bindings/index.ts",
     "./asset-server": "./src/asset-server/index.ts",
     "./tools": "./src/tools.ts",
-    "./decopilot": "./src/decopilot.ts"
+    "./decopilot": "./src/decopilot.ts",
+    "./triggers": "./src/triggers.ts",
+    "./trigger-storage": "./src/trigger-storage.ts"
   },
   "peerDependencies": {
     "ai": ">=6.0.0"

package/src/decopilot.ts

@@ -105,7 +105,7 @@ export async function streamAgent(
 
   const credentialId = params.credentialId ?? config.credentialId;
   const thinking = params.thinking ?? config.thinking;
-  const hasModels = credentialId && thinking?.id;
+  const hasModels = thinking?.id;
 
   const request = {
     messages: params.messages,

package/src/tools.ts

@@ -1050,9 +1050,6 @@ export const createMCPServer = <
 
       // Only close transport for non-streaming responses
       if (!isStreaming) {
-        console.debug(
-          "[MCP Transport] Closing transport for non-streaming response",
-        );
         try {
           await transport.close?.();
         } catch {
@@ -1063,10 +1060,6 @@ export const createMCPServer = <
       return response;
     } catch (error) {
       // On error, always try to close transport to prevent leaks
-      console.debug(
-        "[MCP Transport] Closing transport due to error:",
-        error instanceof Error ? error.message : error,
-      );
       try {
         await transport.close?.();
       } catch {

package/src/trigger-storage.ts

@@ -0,0 +1,195 @@
+/**
+ * Built-in TriggerStorage implementations.
+ *
+ * - StudioKV: Persists to Mesh/Studio's KV API (recommended for production)
+ * - JsonFileStorage: Persists to a local JSON file (for dev/simple deployments)
+ */
+
+import type { TriggerStorage } from "./triggers.ts";
+
+// ============================================================================
+// StudioKV — backed by Mesh's /api/kv endpoint
+// ============================================================================
+
+interface StudioKVOptions {
+  /** Mesh/Studio base URL (e.g., "https://studio.example.com") */
+  url: string;
+  /** API key created in the Studio org */
+  apiKey: string;
+  /** Key prefix to namespace trigger data (default: "triggers") */
+  prefix?: string;
+}
+
+/**
+ * TriggerStorage backed by Mesh/Studio's org-scoped KV API.
+ *
+ * @example
+ * ```typescript
+ * import { createTriggers } from "@decocms/runtime/triggers";
+ * import { StudioKV } from "@decocms/runtime/trigger-storage";
+ *
+ * const triggers = createTriggers({
+ *   definitions: [...],
+ *   storage: new StudioKV({
+ *     url: process.env.MESH_URL!,
+ *     apiKey: process.env.MESH_API_KEY!,
+ *   }),
+ * });
+ * ```
+ */
+export class StudioKV implements TriggerStorage {
+  private baseUrl: string;
+  private apiKey: string;
+  private prefix: string;
+
+  constructor(options: StudioKVOptions) {
+    this.baseUrl = options.url.replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+    this.prefix = options.prefix ?? "triggers";
+  }
+
+  private key(connectionId: string): string {
+    return `${this.prefix}:${connectionId}`;
+  }
+
+  async get(connectionId: string) {
+    const res = await fetch(
+      `${this.baseUrl}/api/kv/${encodeURIComponent(this.key(connectionId))}`,
+      {
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+      },
+    );
+
+    if (res.status === 404) return null;
+
+    if (!res.ok) {
+      console.error(`[StudioKV] GET failed: ${res.status} ${res.statusText}`);
+      return null;
+    }
+
+    const body = (await res.json()) as {
+      value?: {
+        credentials: { callbackUrl: string; callbackToken: string };
+        activeTriggerTypes: string[];
+      };
+    };
+    return body.value ?? null;
+  }
+
+  async set(
+    connectionId: string,
+    state: {
+      credentials: { callbackUrl: string; callbackToken: string };
+      activeTriggerTypes: string[];
+    },
+  ) {
+    const res = await fetch(
+      `${this.baseUrl}/api/kv/${encodeURIComponent(this.key(connectionId))}`,
+      {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(state),
+      },
+    );
+
+    if (!res.ok) {
+      console.error(`[StudioKV] PUT failed: ${res.status} ${res.statusText}`);
+    }
+  }
+
+  async delete(connectionId: string) {
+    const res = await fetch(
+      `${this.baseUrl}/api/kv/${encodeURIComponent(this.key(connectionId))}`,
+      {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+      },
+    );
+
+    if (!res.ok && res.status !== 404) {
+      console.error(
+        `[StudioKV] DELETE failed: ${res.status} ${res.statusText}`,
+      );
+    }
+  }
+}
+
+// ============================================================================
+// JsonFileStorage — backed by a local JSON file
+// ============================================================================
+
+interface JsonFileStorageOptions {
+  /** Path to the JSON file (will be created if it doesn't exist) */
+  path: string;
+}
+
+/**
+ * TriggerStorage backed by a local JSON file.
+ * Suitable for development and single-instance deployments.
+ *
+ * @example
+ * ```typescript
+ * import { createTriggers } from "@decocms/runtime/triggers";
+ * import { JsonFileStorage } from "@decocms/runtime/trigger-storage";
+ *
+ * const triggers = createTriggers({
+ *   definitions: [...],
+ *   storage: new JsonFileStorage({ path: "./trigger-state.json" }),
+ * });
+ * ```
+ */
+export class JsonFileStorage implements TriggerStorage {
+  private path: string;
+  private cache: Map<string, unknown> | null = null;
+
+  constructor(options: JsonFileStorageOptions) {
+    this.path = options.path;
+  }
+
+  private async load(): Promise<Map<string, unknown>> {
+    if (this.cache) return this.cache;
+    try {
+      const fs = await import("node:fs/promises");
+      const raw = await fs.readFile(this.path, "utf-8");
+      const data = JSON.parse(raw) as Record<string, unknown>;
+      this.cache = new Map(Object.entries(data));
+    } catch (err: unknown) {
+      if (
+        err instanceof Error &&
+        "code" in err &&
+        (err as NodeJS.ErrnoException).code === "ENOENT"
+      ) {
+        this.cache = new Map();
+      } else {
+        throw err;
+      }
+    }
+    return this.cache;
+  }
+
+  private async save(): Promise<void> {
+    const data = Object.fromEntries(this.cache ?? new Map());
+    const fs = await import("node:fs/promises");
+    await fs.writeFile(this.path, JSON.stringify(data, null, 2));
+  }
+
+  async get(connectionId: string) {
+    const map = await this.load();
+    return (map.get(connectionId) as any) ?? null;
+  }
+
+  async set(connectionId: string, state: unknown) {
+    const map = await this.load();
+    map.set(connectionId, state);
+    await this.save();
+  }
+
+  async delete(connectionId: string) {
+    const map = await this.load();
+    map.delete(connectionId);
+    await this.save();
+  }
+}

package/src/triggers.test.ts

@@ -0,0 +1,411 @@
+import { describe, expect, it, spyOn } from "bun:test";
+import { z } from "zod";
+import { createTriggers, type TriggerStorage } from "./triggers.ts";
+
+// biome-ignore lint: test mocks don't need full type compliance
+const mockCtx = (connectionId?: string) =>
+  ({
+    env: connectionId
+      ? { MESH_REQUEST_CONTEXT: { connectionId } }
+      : { MESH_REQUEST_CONTEXT: {} },
+    ctx: { waitUntil: () => {} },
+  }) as any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+const triggers = createTriggers([
+  {
+    type: "github.push",
+    description: "Triggered when code is pushed",
+    params: z.object({
+      repo: z.string().describe("Repository full name (owner/repo)"),
+    }),
+  },
+  {
+    type: "github.pull_request.opened",
+    description: "Triggered when a PR is opened",
+    params: z.object({
+      repo: z.string().describe("Repository full name"),
+    }),
+  },
+]);
+
+describe("createTriggers", () => {
+  it("tools() returns TRIGGER_LIST and TRIGGER_CONFIGURE", () => {
+    const tools = triggers.tools();
+    expect(tools).toHaveLength(2);
+    expect(tools[0].id).toBe("TRIGGER_LIST");
+    expect(tools[1].id).toBe("TRIGGER_CONFIGURE");
+  });
+
+  it("TRIGGER_LIST returns trigger definitions with paramsSchema", async () => {
+    const listTool = triggers.tools()[0];
+    const result = (await listTool.execute({
+      context: {},
+      runtimeContext: mockCtx(),
+    })) as {
+      triggers: Array<{ type: string; paramsSchema: Record<string, unknown> }>;
+    };
+
+    expect(result.triggers).toHaveLength(2);
+    expect(result.triggers[0].type).toBe("github.push");
+    expect(result.triggers[0].paramsSchema).toEqual({
+      repo: {
+        type: "string",
+        description: "Repository full name (owner/repo)",
+      },
+    });
+    expect(result.triggers[1].type).toBe("github.pull_request.opened");
+  });
+
+  it("TRIGGER_LIST includes enum values from z.enum params", async () => {
+    const enumTriggers = createTriggers([
+      {
+        type: "test.event",
+        description: "Test",
+        params: z.object({
+          action: z.enum(["opened", "closed", "merged"]).describe("PR action"),
+        }),
+      },
+    ]);
+    const listTool = enumTriggers.tools()[0];
+    const result = (await listTool.execute({
+      context: {},
+      runtimeContext: mockCtx(),
+    })) as {
+      triggers: Array<{ paramsSchema: Record<string, { enum?: string[] }> }>;
+    };
+    expect(result.triggers[0].paramsSchema.action.enum).toEqual([
+      "opened",
+      "closed",
+      "merged",
+    ]);
+  });
+
+  it("TRIGGER_CONFIGURE stores callback credentials and notify delivers", async () => {
+    const configureTool = triggers.tools()[1];
+
+    const mockResponse = new Response("ok", { status: 202 });
+    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(mockResponse);
+
+    // Configure a trigger with callback
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: { repo: "owner/repo" },
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "test-token-123",
+      },
+      runtimeContext: mockCtx("conn-1"),
+    });
+
+    // Notify should POST to the callback URL
+    triggers.notify("conn-1", "github.push", {
+      repository: { full_name: "owner/repo" },
+    });
+
+    // Wait for the fire-and-forget fetch
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://mesh.example.com/api/trigger-callback",
+      expect.objectContaining({
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: "Bearer test-token-123",
+        },
+      }),
+    );
+
+    const callBody = JSON.parse(
+      (fetchSpy.mock.calls[0][1] as RequestInit).body as string,
+    );
+    expect(callBody.type).toBe("github.push");
+    expect(callBody.data.repository.full_name).toBe("owner/repo");
+
+    fetchSpy.mockRestore();
+  });
+
+  it("disabling one trigger keeps credentials when another is still active", async () => {
+    const configureTool = triggers.tools()[1];
+
+    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("ok", { status: 202 }),
+    );
+
+    // Enable two trigger types
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "token-multi",
+      },
+      runtimeContext: mockCtx("conn-multi"),
+    });
+    await configureTool.execute({
+      context: {
+        type: "github.pull_request.opened",
+        params: {},
+        enabled: true,
+      },
+      runtimeContext: mockCtx("conn-multi"),
+    });
+
+    // Disable one — credentials should stay for the other
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: false,
+      },
+      runtimeContext: mockCtx("conn-multi"),
+    });
+
+    triggers.notify("conn-multi", "github.pull_request.opened", {});
+    await new Promise((r) => setTimeout(r, 50));
+    expect(fetchSpy).toHaveBeenCalled();
+
+    fetchSpy.mockRestore();
+  });
+
+  it("disabling the last trigger clears credentials", async () => {
+    const configureTool = triggers.tools()[1];
+
+    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("ok", { status: 202 }),
+    );
+    const consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+
+    // Enable a trigger
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "token-cleanup",
+      },
+      runtimeContext: mockCtx("conn-cleanup"),
+    });
+
+    // Disable it — last trigger, credentials should be cleared
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: false,
+      },
+      runtimeContext: mockCtx("conn-cleanup"),
+    });
+
+    triggers.notify("conn-cleanup", "github.push", {});
+    await new Promise((r) => setTimeout(r, 50));
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No callback credentials"),
+    );
+
+    fetchSpy.mockRestore();
+    consoleSpy.mockRestore();
+  });
+
+  it("notify is a no-op when no credentials exist", async () => {
+    const consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+    triggers.notify("unknown-conn", "github.push", {});
+    await new Promise((r) => setTimeout(r, 50));
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No callback credentials"),
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it("notify logs error on non-2xx response", async () => {
+    const configureTool = triggers.tools()[1];
+    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("Unauthorized", { status: 401, statusText: "Unauthorized" }),
+    );
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    // Ensure credentials exist (reuse from prior test state or set up fresh)
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "token-err",
+      },
+      runtimeContext: mockCtx("conn-err"),
+    });
+
+    fetchSpy.mockResolvedValue(
+      new Response("Unauthorized", { status: 401, statusText: "Unauthorized" }),
+    );
+
+    triggers.notify("conn-err", "github.push", {});
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Callback delivery failed"),
+    );
+
+    fetchSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  it("TRIGGER_CONFIGURE throws without connectionId", async () => {
+    const configureTool = triggers.tools()[1];
+    expect(
+      configureTool.execute({
+        context: { type: "github.push", params: {}, enabled: true },
+        runtimeContext: mockCtx(),
+      }),
+    ).rejects.toThrow("Connection ID not available");
+  });
+});
+
+describe("createTriggers with storage", () => {
+  function createMockStorage(): TriggerStorage & {
+    data: Map<string, unknown>;
+  } {
+    const data = new Map<string, unknown>();
+    return {
+      data,
+      get: async (id) => (data.get(id) as any) ?? null,
+      set: async (id, state) => {
+        data.set(id, state);
+      },
+      delete: async (id) => {
+        data.delete(id);
+      },
+    };
+  }
+
+  const defs = [
+    {
+      type: "github.push" as const,
+      description: "Push",
+      params: z.object({
+        repo: z.string().describe("Repo"),
+      }),
+    },
+  ];
+
+  it("persists trigger state to storage on configure", async () => {
+    const storage = createMockStorage();
+    const t = createTriggers({ definitions: defs, storage });
+    const configureTool = t.tools()[1];
+
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "persisted-token",
+      },
+      runtimeContext: mockCtx("conn-persist"),
+    });
+
+    expect(storage.data.has("conn-persist")).toBe(true);
+    const stored = storage.data.get("conn-persist") as any;
+    expect(stored.credentials.callbackToken).toBe("persisted-token");
+    expect(stored.activeTriggerTypes).toEqual(["github.push"]);
+  });
+
+  it("deletes from storage when last trigger is disabled", async () => {
+    const storage = createMockStorage();
+    const t = createTriggers({ definitions: defs, storage });
+    const configureTool = t.tools()[1];
+
+    await configureTool.execute({
+      context: {
+        type: "github.push",
+        params: {},
+        enabled: true,
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "to-delete",
+      },
+      runtimeContext: mockCtx("conn-del"),
+    });
+
+    expect(storage.data.has("conn-del")).toBe(true);
+
+    await configureTool.execute({
+      context: { type: "github.push", params: {}, enabled: false },
+      runtimeContext: mockCtx("conn-del"),
+    });
+
+    expect(storage.data.has("conn-del")).toBe(false);
+  });
+
+  it("restores credentials from storage on notify after restart", async () => {
+    const storage = createMockStorage();
+
+    // Simulate prior session: write state directly to storage
+    storage.data.set("conn-restart", {
+      credentials: {
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "restored-token",
+      },
+      activeTriggerTypes: ["github.push"],
+    });
+
+    // New instance (simulates restart) — in-memory cache is empty
+    const t = createTriggers({ definitions: defs, storage });
+
+    const fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("ok", { status: 202 }),
+    );
+
+    t.notify("conn-restart", "github.push", { test: true });
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "https://mesh.example.com/api/trigger-callback",
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: "Bearer restored-token",
+        }),
+      }),
+    );
+
+    fetchSpy.mockRestore();
+  });
+
+  it("disable after restart clears persisted credentials from storage", async () => {
+    const storage = createMockStorage();
+
+    // Simulate prior session
+    storage.data.set("conn-disable-restart", {
+      credentials: {
+        callbackUrl: "https://mesh.example.com/api/trigger-callback",
+        callbackToken: "stale-token",
+      },
+      activeTriggerTypes: ["github.push"],
+    });
+
+    // New instance (simulates restart)
+    const t = createTriggers({ definitions: defs, storage });
+    const configureTool = t.tools()[1];
+
+    // Disable the trigger — should load from storage, then clean up
+    await configureTool.execute({
+      context: { type: "github.push", params: {}, enabled: false },
+      runtimeContext: mockCtx("conn-disable-restart"),
+    });
+
+    expect(storage.data.has("conn-disable-restart")).toBe(false);
+
+    // notify should be a no-op
+    const consoleSpy = spyOn(console, "log").mockImplementation(() => {});
+    t.notify("conn-disable-restart", "github.push", {});
+    await new Promise((r) => setTimeout(r, 50));
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No callback credentials"),
+    );
+    consoleSpy.mockRestore();
+  });
+});

package/src/triggers.ts

@@ -0,0 +1,307 @@
+import {
+  TriggerConfigureInputSchema,
+  TriggerListOutputSchema,
+  type TriggerDefinition,
+} from "@decocms/bindings/trigger";
+import { z, type ZodObject, type ZodRawShape } from "zod";
+import type { DefaultEnv } from "./index.ts";
+import { createTool, type CreatedTool } from "./tools.ts";
+
+interface CallbackCredentials {
+  callbackUrl: string;
+  callbackToken: string;
+}
+
+interface TriggerState {
+  credentials: CallbackCredentials;
+  activeTriggerTypes: string[];
+}
+
+/**
+ * Storage interface for persisting trigger state across MCP restarts.
+ *
+ * Implement this with your storage backend (KV, DB, file system, etc.)
+ * and pass it to `createTriggers({ storage })`.
+ *
+ * Keys are connection IDs, values are serializable trigger state objects.
+ */
+export interface TriggerStorage {
+  get(connectionId: string): Promise<TriggerState | null>;
+  set(connectionId: string, state: TriggerState): Promise<void>;
+  delete(connectionId: string): Promise<void>;
+}
+
+interface TriggerDef<
+  TType extends string = string,
+  TParams extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>,
+> {
+  type: TType;
+  description: string;
+  params: TParams;
+}
+
+interface TriggersOptions<TDefs extends TriggerDef[]> {
+  definitions: TDefs;
+  storage?: TriggerStorage;
+}
+
+interface Triggers<TDefs extends TriggerDef[]> {
+  /**
+   * Returns TRIGGER_LIST and TRIGGER_CONFIGURE tools
+   * ready to be spread into your `withRuntime({ tools })` array.
+   */
+  tools(): CreatedTool[];
+
+  /**
+   * Notify Mesh that an event occurred.
+   * The SDK matches it to stored callback credentials and POSTs to Mesh.
+   * Fire-and-forget — errors are logged, not thrown.
+   */
+  notify<T extends TDefs[number]["type"]>(
+    connectionId: string,
+    type: T,
+    data: Record<string, unknown>,
+  ): void;
+}
+
+// In-memory cache backed by optional persistent storage
+class TriggerStateManager {
+  private credentials = new Map<string, CallbackCredentials>();
+  private activeTriggers = new Map<string, Set<string>>();
+  private storage: TriggerStorage | null;
+
+  constructor(storage?: TriggerStorage) {
+    this.storage = storage ?? null;
+  }
+
+  getCredentials(connectionId: string): CallbackCredentials | undefined {
+    return this.credentials.get(connectionId);
+  }
+
+  async loadFromStorage(connectionId: string): Promise<void> {
+    if (!this.storage || this.credentials.has(connectionId)) return;
+    const state = await this.storage.get(connectionId);
+    if (state) {
+      this.credentials.set(connectionId, state.credentials);
+      this.activeTriggers.set(connectionId, new Set(state.activeTriggerTypes));
+    }
+  }
+
+  async enable(
+    connectionId: string,
+    triggerType: string,
+    newCredentials?: CallbackCredentials,
+  ): Promise<void> {
+    if (newCredentials) {
+      this.credentials.set(connectionId, newCredentials);
+    }
+
+    const types = this.activeTriggers.get(connectionId) ?? new Set();
+    types.add(triggerType);
+    this.activeTriggers.set(connectionId, types);
+
+    await this.persist(connectionId);
+  }
+
+  async disable(connectionId: string, triggerType: string): Promise<void> {
+    // Ensure state is loaded (may be empty after restart)
+    await this.loadFromStorage(connectionId);
+    const types = this.activeTriggers.get(connectionId);
+    if (types) {
+      types.delete(triggerType);
+      if (types.size === 0) {
+        this.activeTriggers.delete(connectionId);
+        this.credentials.delete(connectionId);
+        await this.storage?.delete(connectionId);
+        return;
+      }
+    }
+
+    await this.persist(connectionId);
+  }
+
+  private async persist(connectionId: string): Promise<void> {
+    if (!this.storage) return;
+    const creds = this.credentials.get(connectionId);
+    const types = this.activeTriggers.get(connectionId);
+    if (!creds || !types || types.size === 0) return;
+    await this.storage.set(connectionId, {
+      credentials: creds,
+      activeTriggerTypes: [...types],
+    });
+  }
+}
+
+/**
+ * Create a trigger SDK for your MCP.
+ *
+ * @example
+ * ```typescript
+ * import { createTriggers } from "@decocms/runtime/triggers";
+ * import { z } from "zod";
+ *
+ * const triggers = createTriggers({
+ *   definitions: [
+ *     {
+ *       type: "github.push",
+ *       description: "Triggered when code is pushed to a repository",
+ *       params: z.object({
+ *         repo: z.string().describe("Repository full name (owner/repo)"),
+ *       }),
+ *     },
+ *   ],
+ *   // Optional: persist trigger state across restarts
+ *   storage: myKVStorage,
+ * });
+ *
+ * // In withRuntime:
+ * export default withRuntime({
+ *   tools: [() => triggers.tools()],
+ * });
+ *
+ * // In webhook handler:
+ * triggers.notify(connectionId, "github.push", payload);
+ * ```
+ */
+export function createTriggers<const TDefs extends TriggerDef[]>(
+  input: TDefs | TriggersOptions<TDefs>,
+): Triggers<TDefs> {
+  const { definitions, storage } = Array.isArray(input)
+    ? { definitions: input as TDefs, storage: undefined }
+    : input;
+
+  const state = new TriggerStateManager(storage);
+
+  const triggerDefinitions: TriggerDefinition[] = definitions.map((def) => {
+    const shape = def.params.shape;
+    const paramsSchema: Record<
+      string,
+      { type: "string"; description?: string; enum?: string[] }
+    > = {};
+
+    for (const [key, value] of Object.entries(shape)) {
+      const zodField = value as z.ZodTypeAny;
+      const entry: {
+        type: "string";
+        description?: string;
+        enum?: string[];
+      } = {
+        type: "string" as const,
+        description: zodField.description,
+      };
+
+      // Extract enum values from z.enum() schemas
+      if ("options" in zodField && Array.isArray(zodField.options)) {
+        entry.enum = zodField.options as string[];
+      }
+
+      paramsSchema[key] = entry;
+    }
+
+    return {
+      type: def.type,
+      description: def.description,
+      paramsSchema,
+    };
+  });
+
+  const TRIGGER_LIST = createTool({
+    id: "TRIGGER_LIST" as const,
+    description: "List available trigger definitions",
+    inputSchema: z.object({}),
+    outputSchema: TriggerListOutputSchema,
+    execute: async () => {
+      return { triggers: triggerDefinitions };
+    },
+  });
+
+  const TRIGGER_CONFIGURE = createTool({
+    id: "TRIGGER_CONFIGURE" as const,
+    description: "Configure a trigger with parameters",
+    inputSchema: TriggerConfigureInputSchema,
+    outputSchema: z.object({ success: z.boolean() }),
+    execute: async ({ context, runtimeContext }) => {
+      const connectionId = (runtimeContext?.env as unknown as DefaultEnv)
+        ?.MESH_REQUEST_CONTEXT?.connectionId;
+
+      if (!connectionId) {
+        throw new Error("Connection ID not available");
+      }
+
+      if (context.enabled) {
+        const creds =
+          context.callbackUrl && context.callbackToken
+            ? {
+                callbackUrl: context.callbackUrl,
+                callbackToken: context.callbackToken,
+              }
+            : undefined;
+        await state.enable(connectionId, context.type, creds);
+      } else {
+        await state.disable(connectionId, context.type);
+      }
+
+      return { success: true };
+    },
+  });
+
+  return {
+    tools() {
+      return [TRIGGER_LIST, TRIGGER_CONFIGURE] as CreatedTool[];
+    },
+
+    notify(connectionId, type, data) {
+      // Try in-memory first, fall back to storage load
+      const credentials = state.getCredentials(connectionId);
+      if (credentials) {
+        deliverCallback(credentials, type, data);
+        return;
+      }
+
+      // Attempt async load from storage (fire-and-forget)
+      state
+        .loadFromStorage(connectionId)
+        .then(() => {
+          const loaded = state.getCredentials(connectionId);
+          if (loaded) {
+            deliverCallback(loaded, type, data);
+          } else {
+            console.log(
+              `[Triggers] No callback credentials for connection=${connectionId}, skipping notify`,
+            );
+          }
+        })
+        .catch((err) => {
+          console.error(
+            `[Triggers] Failed to load credentials for ${connectionId}:`,
+            err,
+          );
+        });
+    },
+  };
+}
+
+function deliverCallback(
+  credentials: CallbackCredentials,
+  type: string,
+  data: Record<string, unknown>,
+): void {
+  fetch(credentials.callbackUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${credentials.callbackToken}`,
+    },
+    body: JSON.stringify({ type, data }),
+  })
+    .then((res) => {
+      if (!res.ok) {
+        console.error(
+          `[Triggers] Callback delivery failed for ${type}: ${res.status} ${res.statusText}`,
+        );
+      }
+    })
+    .catch((err) => {
+      console.error(`[Triggers] Failed to deliver callback for ${type}:`, err);
+    });
+}