@oomol-lab/open-connector 1.6.5 → 1.8.0

package/src/server/api/oauth-completion-page.d.ts

@@ -1 +1,125 @@
+export declare const oauthCompletionStrings: {
+    en: {
+        badge: string;
+        title: string;
+        body: string;
+        closeButton: string;
+        autoClose: string;
+        manualClose: string;
+        checkingTitle: string;
+        checking: string;
+        signIn: string;
+        login: string;
+        retry: string;
+        missing: string;
+        retrying: string;
+        waiting: string;
+        failed: string;
+        network: string;
+        notFound: string;
+        forbidden: string;
+    };
+    "zh-CN": {
+        badge: string;
+        title: string;
+        body: string;
+        closeButton: string;
+        autoClose: string;
+        manualClose: string;
+        checkingTitle: string;
+        checking: string;
+        signIn: string;
+        login: string;
+        retry: string;
+        missing: string;
+        retrying: string;
+        waiting: string;
+        failed: string;
+        network: string;
+        notFound: string;
+        forbidden: string;
+    };
+    "zh-TW": {
+        badge: string;
+        title: string;
+        body: string;
+        closeButton: string;
+        autoClose: string;
+        manualClose: string;
+        checkingTitle: string;
+        checking: string;
+        signIn: string;
+        login: string;
+        retry: string;
+        missing: string;
+        retrying: string;
+        waiting: string;
+        failed: string;
+        network: string;
+        notFound: string;
+        forbidden: string;
+    };
+    ja: {
+        badge: string;
+        title: string;
+        body: string;
+        closeButton: string;
+        autoClose: string;
+        manualClose: string;
+        checkingTitle: string;
+        checking: string;
+        signIn: string;
+        login: string;
+        retry: string;
+        missing: string;
+        retrying: string;
+        waiting: string;
+        failed: string;
+        network: string;
+        notFound: string;
+        forbidden: string;
+    };
+    fr: {
+        badge: string;
+        title: string;
+        body: string;
+        closeButton: string;
+        autoClose: string;
+        manualClose: string;
+        checkingTitle: string;
+        checking: string;
+        signIn: string;
+        login: string;
+        retry: string;
+        missing: string;
+        retrying: string;
+        waiting: string;
+        failed: string;
+        network: string;
+        notFound: string;
+        forbidden: string;
+    };
+    ru: {
+        badge: string;
+        title: string;
+        body: string;
+        closeButton: string;
+        autoClose: string;
+        manualClose: string;
+        checkingTitle: string;
+        checking: string;
+        signIn: string;
+        login: string;
+        retry: string;
+        missing: string;
+        retrying: string;
+        waiting: string;
+        failed: string;
+        network: string;
+        notFound: string;
+        forbidden: string;
+    };
+};
+export declare const oauthCompletionStyles = "\n:root {\n  --background: hsl(0 0% 100%);\n  --foreground: hsl(222.2 84% 4.9%);\n  --card: hsl(0 0% 100%);\n  --card-foreground: hsl(222.2 84% 4.9%);\n  --muted: hsl(210 40% 96.1%);\n  --muted-foreground: hsl(215.4 16.3% 46.9%);\n  --border: hsl(214.3 31.8% 91.4%);\n  --primary: hsl(222.2 47.4% 11.2%);\n  --primary-foreground: hsl(210 40% 98%);\n  --ring: hsl(222.2 84% 4.9%);\n}\n* {\n  box-sizing: border-box;\n}\nbody {\n  min-height: 100vh;\n  margin: 0;\n  display: grid;\n  place-items: center;\n  padding: 24px;\n  background: var(--background);\n  color: var(--foreground);\n  font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif;\n}\n.card {\n  width: min(100%, 420px);\n  padding: 24px;\n  border: 1px solid var(--border);\n  border-radius: 12px;\n  background: var(--card);\n  color: var(--card-foreground);\n  box-shadow: 0 1px 2px hsl(222.2 84% 4.9% / 0.04), 0 12px 32px hsl(222.2 84% 4.9% / 0.08);\n}\n.header {\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n}\n.badge {\n  width: fit-content;\n  display: inline-flex;\n  align-items: center;\n  border: 1px solid transparent;\n  border-radius: 999px;\n  padding: 2px 10px;\n  background: var(--primary);\n  color: var(--primary-foreground);\n  font-size: 12px;\n  font-weight: 600;\n  line-height: 20px;\n}\nh1 {\n  margin: 0;\n  font-size: 20px;\n  line-height: 28px;\n  font-weight: 600;\n}\np {\n  margin: 0;\n  color: var(--muted-foreground);\n  font-size: 14px;\n  line-height: 22px;\n}\ncode {\n  border-radius: 6px;\n  background: var(--muted);\n  padding: 2px 6px;\n  color: var(--foreground);\n  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", monospace;\n  font-size: 13px;\n}\n.actions {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: 12px;\n  flex-wrap: wrap;\n  margin-top: 24px;\n}\n.button {\n  appearance: none;\n  border: 1px solid var(--border);\n  border-radius: 8px;\n  background: var(--card);\n  color: var(--foreground);\n  padding: 8px 14px;\n  font: inherit;\n  font-size: 14px;\n  font-weight: 500;\n  line-height: 20px;\n  cursor: pointer;\n}\n.button:focus-visible {\n  outline: 2px solid var(--ring);\n  outline-offset: 2px;\n}\n.button:hover {\n  background: var(--muted);\n}\n.close-note {\n  font-size: 12px;\n  line-height: 18px;\n}\n\n[hidden]{display:none!important}\n.button:disabled{opacity:.5;cursor:wait}\na.button{text-decoration:none}\n.actions{justify-content:flex-start}\n";
+export declare const oauthCompletionLocaleScript = "const pick=()=>{try{const stored=localStorage.getItem(\"oomol-connect.lang\");if(Object.hasOwn(STR,stored))return stored;}catch{}const langs=navigator.languages&&navigator.languages.length?navigator.languages:[navigator.language||\"en\"];for(const raw of langs){const l=String(raw).toLowerCase();if(l.startsWith(\"zh\"))return (!l.includes(\"hans\")&&(l.includes(\"tw\")||l.includes(\"hk\")||l.includes(\"mo\")||l.includes(\"hant\")))?\"zh-TW\":\"zh-CN\";const primary=l.split(\"-\")[0];if(STR[raw])return raw;if(STR[primary])return primary;}return \"en\";};";
 export declare function renderOAuthCompletionPage(service: string): string;

package/src/server/api/oauth-completion-page.js

@@ -3,7 +3,7 @@ const oauthCompletedType = "oauth.completed";
 // Client-side translations. English is also the server-rendered default in the
 // markup below, so the page stays meaningful without JavaScript. The copy stays
 // host-neutral because this runtime can be embedded by more than one product.
-const oauthCompletionStrings = {
+export const oauthCompletionStrings = {
     en: {
         badge: "Connected",
         title: "Connection complete",
@@ -11,44 +11,121 @@ const oauthCompletionStrings = {
         closeButton: "Close window",
         autoClose: "Automatically closing in %N% seconds.",
         manualClose: "You can now close this window.",
+        checkingTitle: "Completing connection",
+        checking: "Checking your Console session…",
+        signIn: "Open Console to sign in",
+        login: "Sign in to Console, then check again. Use the same browser and Console address where you started authorization.",
+        retry: "Check again",
+        missing: "The authorization request is missing. Return to the initiating client.",
+        retrying: "The connection could not be checked yet. Retrying…",
+        waiting: "Waiting for authorization to be confirmed…",
+        failed: "Authorization could not be completed. Return to the initiating client.",
+        network: "Could not reach Connect. Check your connection and try again.",
+        notFound: "This request was not found or has expired. Return to the initiating client.",
+        forbidden: "Synchronization was rejected. Check that OOMOL_CONNECT_ORIGIN matches your Console address.",
     },
     "zh-CN": {
         badge: "已连接",
         title: "连接完成",
-        body: "关闭此窗口，然后回到刚才的应用继续。",
+        body: "连接已就绪，可以返回刚才的应用继续使用。",
         closeButton: "关闭窗口",
         autoClose: "%N% 秒后自动关闭。",
         manualClose: "现在可以手动关闭此窗口。",
+        checkingTitle: "正在完成连接",
+        checking: "正在检查控制台登录状态…",
+        signIn: "打开控制台登录",
+        login: "请登录控制台后重新检查，使用发起授权时的浏览器和控制台地址。",
+        retry: "重新检查",
+        missing: "缺少授权请求信息，请返回发起授权的应用。",
+        retrying: "暂时无法确认连接，正在重试…",
+        waiting: "正在等待授权结果确认…",
+        failed: "授权未能完成，请返回发起授权的应用查看。",
+        network: "无法连接到 Connect，请检查网络后重试。",
+        notFound: "授权请求不存在或已过期，请返回发起授权的应用。",
+        forbidden: "同步请求被拒绝，请检查 OOMOL_CONNECT_ORIGIN 是否与控制台地址一致。",
     },
     "zh-TW": {
         badge: "已連線",
         title: "連線完成",
-        body: "關閉此視窗，然後回到剛才的應用繼續。",
+        body: "連線已就緒，可以返回剛才的應用繼續使用。",
         closeButton: "關閉視窗",
         autoClose: "%N% 秒後自動關閉。",
         manualClose: "現在可以手動關閉此視窗。",
+        checkingTitle: "正在完成連線",
+        checking: "正在檢查控制台登入狀態…",
+        signIn: "開啟控制台登入",
+        login: "請登入控制台後重新檢查，使用發起授權時的瀏覽器和控制台位址。",
+        retry: "重新檢查",
+        missing: "缺少授權請求資訊，請返回發起授權的應用。",
+        retrying: "暫時無法確認連線，正在重試…",
+        waiting: "正在等待授權結果確認…",
+        failed: "授權未能完成，請返回發起授權的應用查看。",
+        network: "無法連線至 Connect，請檢查網路後重試。",
+        notFound: "授權請求不存在或已過期，請返回發起授權的應用。",
+        forbidden: "同步請求遭拒，請檢查 OOMOL_CONNECT_ORIGIN 是否與控制台位址一致。",
     },
     ja: {
         badge: "接続済み",
         title: "接続が完了しました",
-        body: "このウィンドウを閉じて、元のアプリに戻って続行してください。",
+        body: "元のアプリに戻って続行できます。",
         closeButton: "ウィンドウを閉じる",
         autoClose: "%N% 秒後に自動的に閉じます。",
         manualClose: "このウィンドウを閉じても問題ありません。",
+        checkingTitle: "接続を完了しています",
+        checking: "コンソールのログイン状態を確認しています…",
+        signIn: "コンソールにログイン",
+        login: "認可を開始したブラウザーとコンソールのアドレスでログインし、再確認してください。",
+        retry: "再確認",
+        missing: "認可リクエストがありません。元のアプリに戻ってください。",
+        retrying: "接続を確認できません。再試行しています…",
+        waiting: "認可結果を確認しています…",
+        failed: "認可を完了できませんでした。元のアプリで確認してください。",
+        network: "Connect に接続できません。ネットワークを確認して再試行してください。",
+        notFound: "リクエストが見つからないか期限切れです。元のアプリに戻ってください。",
+        forbidden: "同期が拒否されました。OOMOL_CONNECT_ORIGIN とコンソールのアドレスを確認してください。",
+    },
+    fr: {
+        badge: "Connecté",
+        title: "Connexion terminée",
+        body: "Vous pouvez revenir à l’application de départ.",
+        closeButton: "Fermer la fenêtre",
+        autoClose: "Fermeture automatique dans %N% secondes.",
+        manualClose: "Vous pouvez fermer cette fenêtre.",
+        checkingTitle: "Finalisation de la connexion",
+        checking: "Vérification de la session Console…",
+        signIn: "Se connecter à la Console",
+        login: "Connectez-vous à la Console avec le navigateur et l’adresse utilisés au départ, puis réessayez.",
+        retry: "Vérifier à nouveau",
+        missing: "La demande d’autorisation est absente. Revenez à l’application de départ.",
+        retrying: "Vérification impossible pour le moment. Nouvelle tentative…",
+        waiting: "En attente de confirmation de l’autorisation…",
+        failed: "L’autorisation a échoué. Consultez l’application de départ.",
+        network: "Connect est inaccessible. Vérifiez votre connexion et réessayez.",
+        notFound: "Cette demande est introuvable ou expirée. Revenez à l’application de départ.",
+        forbidden: "Synchronisation refusée. Vérifiez que OOMOL_CONNECT_ORIGIN correspond à l’adresse de la Console.",
+    },
+    ru: {
+        badge: "Подключено",
+        title: "Подключение завершено",
+        body: "Можно вернуться в исходное приложение.",
+        closeButton: "Закрыть окно",
+        autoClose: "Автоматическое закрытие через %N% сек.",
+        manualClose: "Теперь можно закрыть это окно.",
+        checkingTitle: "Завершение подключения",
+        checking: "Проверка сеанса консоли…",
+        signIn: "Войти в консоль",
+        login: "Войдите в консоль в том же браузере и по тому же адресу, где началась авторизация, затем повторите проверку.",
+        retry: "Проверить снова",
+        missing: "Запрос авторизации отсутствует. Вернитесь в исходное приложение.",
+        retrying: "Пока не удалось проверить подключение. Повторяем…",
+        waiting: "Ожидание подтверждения авторизации…",
+        failed: "Не удалось завершить авторизацию. Проверьте исходное приложение.",
+        network: "Нет связи с Connect. Проверьте сеть и повторите попытку.",
+        notFound: "Запрос не найден или истёк. Вернитесь в исходное приложение.",
+        forbidden: "Синхронизация отклонена. Проверьте соответствие OOMOL_CONNECT_ORIGIN адресу консоли.",
     },
 };
-export function renderOAuthCompletionPage(service) {
-    const payload = scriptJson({
-        type: oauthCompletedType,
-        service,
-    });
-    return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Connection complete</title>
-<style>
+export const oauthCompletionStyles = `
 :root {
   --background: hsl(0 0% 100%);
   --foreground: hsl(222.2 84% 4.9%);
@@ -153,7 +230,25 @@ code {
   font-size: 12px;
   line-height: 18px;
 }
-</style>
+
+[hidden]{display:none!important}
+.button:disabled{opacity:.5;cursor:wait}
+a.button{text-decoration:none}
+.actions{justify-content:flex-start}
+`;
+export const oauthCompletionLocaleScript = `const pick=()=>{try{const stored=localStorage.getItem("oomol-connect.lang");if(Object.hasOwn(STR,stored))return stored;}catch{}const langs=navigator.languages&&navigator.languages.length?navigator.languages:[navigator.language||"en"];for(const raw of langs){const l=String(raw).toLowerCase();if(l.startsWith("zh"))return (!l.includes("hans")&&(l.includes("tw")||l.includes("hk")||l.includes("mo")||l.includes("hant")))?"zh-TW":"zh-CN";const primary=l.split("-")[0];if(STR[raw])return raw;if(STR[primary])return primary;}return "en";};`;
+export function renderOAuthCompletionPage(service) {
+    const payload = scriptJson({
+        type: oauthCompletedType,
+        service,
+    });
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Connection complete</title>
+<style>${oauthCompletionStyles}</style>
 </head>
 <body>
 <main class="card" role="status" aria-live="polite">
@@ -170,7 +265,7 @@ code {
 <script>(()=>{
 const STR=${scriptJson(oauthCompletionStrings)};
 if("BroadcastChannel" in window){const channel=new BroadcastChannel(${scriptJson(oauthCompletionChannelName)});channel.postMessage(${payload});channel.close();}
-const pick=()=>{const langs=navigator.languages&&navigator.languages.length?navigator.languages:[navigator.language||"en"];for(const raw of langs){const l=String(raw).toLowerCase();if(l.startsWith("zh"))return (!l.includes("hans")&&(l.includes("tw")||l.includes("hk")||l.includes("mo")||l.includes("hant")))?"zh-TW":"zh-CN";const primary=l.split("-")[0];if(STR[raw])return raw;if(STR[primary])return primary;}return "en";};
+${oauthCompletionLocaleScript}
 const t=STR[pick()]||STR.en;
 document.documentElement.lang=pick();
 for(const el of document.querySelectorAll("[data-t]")){const key=el.getAttribute("data-t");if(t[key]!=null)el.textContent=t[key];}

package/src/server/api/openapi.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { jsonSchema } from "../../core/json-schema.js";
+import { triggerOperationSchema } from "../../triggers/request.js";
 import { actionInputMaxDepth, idempotencyKeyMaxBytes, idempotencyRetentionHours, } from "../actions/action-idempotency.js";
 import { oauthConnectionInput, apiKeyConnectionInput, customConnectionInput } from "./connection-input.js";
 import { policyRequestMaxBytes, policyRuleListMaxItems, policyRuleMaxBytes } from "./policy-input.js";
@@ -18,7 +19,10 @@ const errorResponseSchema = jsonSchema.object({
     description: "Standard error response.",
 });
 const actionResultMetaSchema = jsonSchema.object({
-    executionId: jsonSchema.string({ description: "Action execution identifier." }),
+    executionId: jsonSchema.string({ description: "Local action execution identifier." }),
+    remoteExecutionId: jsonSchema.string({
+        description: "SaaS execution identifier when available; distinct from the local executionId.",
+    }),
     actionId: jsonSchema.string({ description: "Executed action identifier." }),
     auditPersisted: jsonSchema.boolean({ description: "Whether the run audit record was stored." }),
 }, {
@@ -27,6 +31,9 @@ const actionResultMetaSchema = jsonSchema.object({
 });
 const actionFailureMetaSchema = jsonSchema.object({
     executionId: jsonSchema.string({ description: "Execution identifier when action execution began." }),
+    remoteExecutionId: jsonSchema.string({
+        description: "SaaS execution identifier when the remote failure supplies one.",
+    }),
     actionId: jsonSchema.string({ description: "Requested action identifier." }),
     auditPersisted: jsonSchema.boolean({ description: "Whether the run audit record was stored." }),
 }, {
@@ -42,6 +49,9 @@ const oauthClientConfigRequestSchema = jsonSchema.object({
         minItems: 1,
         description: "Non-empty provider-declared scope subset to request. Omit to use every provider default.",
     }),
+    redirectUri: jsonSchema.string({
+        description: "Absolute redirect URI registered with the provider instead of the runtime callback, such as a native app's custom scheme. Must not carry user info or a fragment; javascript, vbscript, data, file, blob, and about schemes are rejected. Omit or send an empty string to use the runtime callback.",
+    }),
     extra: {
         type: "object",
         additionalProperties: { type: "string" },
@@ -56,6 +66,7 @@ const oauthClientConfigRequestSchema = jsonSchema.object({
     required: ["clientId"],
     description: "User-provided OAuth app client configuration.",
 });
+const saasExecutionDescription = "SaaS connections execute remotely after local policy and input validation, using the selected account without local credentials or fallback. SaaS execution POSTs have a 300-second budget and a 64 MiB decoded JSON envelope limit. Responses retain the local executionId and add remoteExecutionId when available. Cancellation or a failed response does not guarantee that remote side effects were undone. ";
 const actionIdempotencyDescription = `Requests with the same Idempotency-Key, action, input, effective connection, and stored runtime token identity replay the original HTTP status and body of completed successes and failures during the ${idempotencyRetentionHours}-hour replay window. ` +
     "Requests that are still in progress, or whose outcome is uncertain, are not automatically dispatched again. " +
     "Duplicate suppression does not guarantee exactly-once execution by the provider.";
@@ -67,6 +78,13 @@ const actionIdParameter = {
 };
 const namedConnectionDescription = "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default.";
 const namedConnectionParameters = [
+    {
+        name: "x-oo-connector-app-id",
+        in: "header",
+        required: false,
+        schema: jsonSchema.string(),
+        description: "Stable connection ID. If an alias is also supplied it must identify the same connection. Unknown IDs never select the default account.",
+    },
     {
         name: "x-oo-connector-alias",
         in: "header",
@@ -103,6 +121,9 @@ const idempotencyKeyParameter = {
 const idempotencyConflictDescription = "For idempotency, idempotency_request_in_progress means the original request is still running or its outcome is uncertain, while idempotency_key_conflict means the key was reused for a different action, input, effective connection, or stored runtime token. Other runtime conflicts may return their own error code with the same status.";
 const runtimeConnectionProperties = {
     id: jsonSchema.string({ description: "Stable local connection identifier." }),
+    providerAccountId: jsonSchema.string({
+        description: "Provider account identity from the stored credential profile.",
+    }),
     service: jsonSchema.string({ description: "Provider service identifier." }),
     status: { type: "string", enum: ["active", "disconnected"] },
     alias: jsonSchema.string({ description: namedConnectionDescription }),
@@ -259,6 +280,61 @@ export function createOpenApiDocument(providers, options = {}) {
         "/api/files/{fileId}": createTransitFilePath(),
         "/v1/actions/{actionId}": runPath,
         "/v1/proxy/{service}": createProxyPath(),
+        "/v1/providers/{service}/trigger-permissions": runtimeGetOperation("Triggers", "Read provider-native Trigger permission guidance.", {
+            data: { type: "array", items: { type: "object", additionalProperties: true } },
+            parameters: [{ name: "service", in: "path", required: true, schema: jsonSchema.string() }],
+            errorStatuses: [401, 404],
+        }),
+        "/v1/providers/{service}/triggers/{triggerId}/execute": {
+            post: {
+                tags: ["Triggers"],
+                summary: "Execute a registered Provider Trigger operation.",
+                description: "Requires independent Trigger grants. Stateful operations require a persistent runtime token and native local connection; remote state and credentials stay server-owned.",
+                parameters: [
+                    { name: "service", in: "path", required: true, schema: jsonSchema.string() },
+                    { name: "triggerId", in: "path", required: true, schema: jsonSchema.string() },
+                    ...namedConnectionParameters,
+                ],
+                requestBody: { required: true, content: { "application/json": { schema: triggerOperationSchema() } } },
+                responses: {
+                    200: jsonResponse(runtimeSuccessSchema({})),
+                    400: jsonResponse(runtimeFailureSchema()),
+                    401: jsonResponse(runtimeFailureSchema()),
+                    403: jsonResponse(runtimeFailureSchema()),
+                    404: jsonResponse(runtimeFailureSchema()),
+                    409: jsonResponse(runtimeFailureSchema()),
+                    413: jsonResponse(runtimeFailureSchema()),
+                    501: jsonResponse(runtimeFailureSchema()),
+                    503: jsonResponse(runtimeFailureSchema()),
+                },
+            },
+        },
+        "/api/trigger-subscriptions": getOperation("Triggers", "List owned subscriptions and cleanup status without secrets.", { type: "array", items: { type: "object", additionalProperties: true } }),
+        "/api/trigger-subscriptions/{id}/cancel": {
+            post: {
+                tags: ["Triggers"],
+                summary: "Cancel a subscription with retained original credentials.",
+                parameters: [{ name: "id", in: "path", required: true, schema: jsonSchema.string() }],
+                responses: {
+                    200: jsonResponse(jsonSchema.object({ ok: jsonSchema.boolean() })),
+                    404: jsonResponse(errorResponseSchema),
+                    409: jsonResponse(errorResponseSchema),
+                    503: jsonResponse(errorResponseSchema),
+                },
+            },
+        },
+        "/api/trigger-subscriptions/{id}/abandon": {
+            post: {
+                tags: ["Triggers"],
+                summary: "Explicitly abandon automatic cleanup; retain the uncleaned remote-resource record.",
+                parameters: [{ name: "id", in: "path", required: true, schema: jsonSchema.string() }],
+                responses: {
+                    200: jsonResponse(jsonSchema.object({ ok: jsonSchema.boolean() })),
+                    404: jsonResponse(errorResponseSchema),
+                    409: jsonResponse(errorResponseSchema),
+                },
+            },
+        },
         "/api/runs": createRunsPath(),
         "/api/runs/{id}": createRunDetailPath(),
         "/mcp": createMcpPath(),
@@ -284,7 +360,11 @@ export function createOpenApiDocument(providers, options = {}) {
             { name: "Access", description: "Runtime execution policy and bearer tokens for /v1 and MCP clients." },
             { name: "Files", description: "Local temporary file transit for provider actions." },
             { name: "Runs", description: "Local action execution and recent run history." },
-            { name: "Proxy", description: "Provider API proxy requests through local credentials." },
+            {
+                name: "Triggers",
+                description: "Registered provider Trigger operations and owned remote subscription cleanup.",
+            },
+            { name: "Proxy", description: "Provider API proxy requests using the selected local or SaaS connection." },
             { name: "MCP", description: "Stateless MCP POST endpoint and tool metadata." },
         ],
         paths,
@@ -416,6 +496,9 @@ export function createOpenApiDocument(providers, options = {}) {
                 }),
                 ConnectionSummary: jsonSchema.object({
                     id: jsonSchema.string({ description: "Stable local connection identifier." }),
+                    providerAccountId: jsonSchema.string({
+                        description: "Provider account identity from the stored credential profile.",
+                    }),
                     service: jsonSchema.string({ description: "Provider service identifier." }),
                     authType: jsonSchema.string({ description: "Connection authentication type." }),
                     configured: jsonSchema.boolean({ description: "Whether the provider is connected." }),
@@ -457,8 +540,11 @@ export function createOpenApiDocument(providers, options = {}) {
                     }),
                     clientId: jsonSchema.nullable(jsonSchema.string({ description: "Configured OAuth client id." })),
                     expectedRedirectUri: jsonSchema.string({
-                        description: "Callback URL to configure in the provider OAuth app.",
+                        description: "Callback URL to configure in the provider OAuth app: the configured override, else the runtime callback.",
                     }),
+                    redirectUri: jsonSchema.nullable(jsonSchema.string({
+                        description: "Configured redirect URI override, or null when the runtime callback is used.",
+                    })),
                     auth: jsonSchema.unknownObject("Provider OAuth capability metadata."),
                     requestedScopes: jsonSchema.nullable(jsonSchema.array(jsonSchema.string(), {
                         description: "Configured scope subset, or null when provider defaults are used.",
@@ -473,6 +559,7 @@ export function createOpenApiDocument(providers, options = {}) {
                         "customClientAvailable",
                         "clientId",
                         "expectedRedirectUri",
+                        "redirectUri",
                         "auth",
                         "requestedScopes",
                         "effectiveScopes",
@@ -486,6 +573,7 @@ export function createOpenApiDocument(providers, options = {}) {
                     allowedActions: policyRuleArraySchema("Action allow rules applied to this stored runtime token."),
                     blockedActions: policyRuleArraySchema("Action block rules applied to this stored runtime token."),
                     allowedProxies: policyRuleArraySchema("Provider proxies explicitly granted to this token. An empty list grants no proxy access."),
+                    allowedTriggers: policyRuleArraySchema("Trigger IDs explicitly granted to this token. Omit or leave empty to deny all Trigger operations."),
                     allowedConnections: connectionIdArraySchema("Stable connection IDs granted to this stored runtime token. An empty list is unrestricted connection access. IDs are opaque values returned by the connection APIs. Virtual no_auth connections do not require grants."),
                     createdAt: jsonSchema.string({ description: "Creation timestamp." }),
                     lastUsedAt: jsonSchema.string({ description: "Last successful use timestamp." }),
@@ -497,6 +585,7 @@ export function createOpenApiDocument(providers, options = {}) {
                         "blockedActions",
                         "allowedProxies",
                         "allowedConnections",
+                        "allowedTriggers",
                         "createdAt",
                     ],
                     description: "Runtime API token summary. Plaintext tokens and token hashes are not returned.",
@@ -506,6 +595,7 @@ export function createOpenApiDocument(providers, options = {}) {
                     allowedActions: policyRuleArraySchema("Optional action allow rules for the new token."),
                     blockedActions: policyRuleArraySchema("Optional action block rules for the new token."),
                     allowedProxies: policyRuleArraySchema("Optional provider proxy grants for the new token. Omit or leave empty to deny proxy access."),
+                    allowedTriggers: policyRuleArraySchema("Trigger IDs explicitly granted to this token. Omit or leave empty to deny all Trigger operations."),
                     allowedConnections: connectionIdArraySchema("Optional stable connection IDs granted to the new token. Omit or leave empty for unrestricted connection access. A non-empty list matches exact opaque IDs returned by the connection APIs. Virtual no_auth connections do not require grants."),
                 }, {
                     required: ["name"],
@@ -515,10 +605,11 @@ export function createOpenApiDocument(providers, options = {}) {
                     allowedActions: policyRuleArraySchema("Action allow rules for this token."),
                     blockedActions: policyRuleArraySchema("Action block rules for this token."),
                     allowedProxies: policyRuleArraySchema("Provider proxies explicitly granted to this token. An empty list grants no proxy access."),
+                    allowedTriggers: policyRuleArraySchema("Trigger IDs explicitly granted to this token. Omit or leave empty to deny all Trigger operations."),
                     allowedConnections: connectionIdArraySchema("Stable connection IDs granted to this stored token. An empty list is unrestricted connection access. A non-empty list matches exact opaque IDs returned by the connection APIs. Virtual no_auth connections do not require grants."),
                 }, {
                     required: ["allowedActions", "blockedActions", "allowedProxies", "allowedConnections"],
-                    description: "Complete replacement of one stored runtime token's action, proxy, and connection permissions.",
+                    description: "Complete replacement of one stored runtime token's Action, Trigger, proxy, and connection permissions.",
                 }),
                 PolicyRules: policyRulesSchema(),
                 RuntimePolicyState: jsonSchema.object({
@@ -775,7 +866,7 @@ function createRuntimePolicyPath() {
         },
         put: {
             tags: ["Access"],
-            summary: "Replace the persisted Runtime action and proxy policy.",
+            summary: "Replace the persisted Runtime Action, Trigger, and proxy policy.",
             description: `Deployment policy remains read-only. Block rules take precedence and non-empty allowlists intersect. Policy request bodies must not exceed ${policyRequestMaxBytes} bytes.`,
             requestBody: {
                 required: true,
@@ -799,6 +890,8 @@ function policyRulesSchema() {
         allowedActions: policyRuleArraySchema("Action allow rules."),
         blockedActions: policyRuleArraySchema("Action block rules."),
         allowedProxies: policyRuleArraySchema("Proxy service allow rules."),
+        allowedTriggers: policyRuleArraySchema("Trigger allow rules. Non-empty allowlists intersect across policy layers."),
+        blockedTriggers: policyRuleArraySchema("Trigger block rules override all grants."),
         blockedProxies: policyRuleArraySchema("Proxy service block rules."),
     }, {
         required: ["allowedActions", "blockedActions", "allowedProxies", "blockedProxies"],
@@ -939,6 +1032,7 @@ function createRunPath() {
             tags: ["Runs"],
             summary: "Execute a runtime action.",
             description: "Use the action catalog to discover provider-specific input and output schemas. For a compact strongly typed OpenAPI document for one action, request /openapi.json?actionId=<actionId>. " +
+                saasExecutionDescription +
                 actionIdempotencyDescription,
             parameters: [actionIdParameter, idempotencyKeyParameter, ...namedConnectionParameters],
             requestBody: actionRunBody(jsonSchema.unknownObject("Action input matching the catalog schema. Omitted input is treated as {}."), "Generic action run creation request."),
@@ -951,7 +1045,7 @@ function createProxyPath() {
         post: {
             tags: ["Proxy"],
             summary: "Proxy one provider API request.",
-            description: "For providers with a local proxy executor, forwards a provider-relative HTTP request and applies stored provider credentials locally.",
+            description: "Executes through the selected connection. Local connections use the local provider proxy; SaaS connections use the project proxy without loading local credentials. SaaS accepts GET/POST/PUT/PATCH/DELETE, primitive query values, string non-authentication headers and JSON/text bodies only; accessGrant and unknown fields are rejected. SaaS execution has a 300-second POST budget and a 64 MiB decoded JSON envelope limit, preserves the upstream status inside data.status, and supplies distinct local executionId and remoteExecutionId in meta. Failed or cancelled calls are never automatically replayed; remote side effects may have completed.",
             parameters: [
                 {
                     name: "service",
@@ -968,7 +1062,7 @@ function createProxyPath() {
                         schema: jsonSchema.object({
                             endpoint: jsonSchema.string({ description: "Provider-relative path beginning with /." }),
                             method: jsonSchema.string({
-                                description: "HTTP method: DELETE, GET, HEAD, PATCH, POST, or PUT.",
+                                description: "HTTP method: DELETE, GET, HEAD, PATCH, POST, or PUT. SaaS connections reject HEAD.",
                             }),
                             query: {
                                 type: "object",
@@ -998,7 +1092,7 @@ function createProxyPath() {
                         description: "Provider response headers.",
                     },
                     bodyEncoding: jsonSchema.string({
-                        description: "Present as base64 when the provider response is binary.",
+                        description: "Present as base64 when a local provider response is binary. SaaS proxy supports JSON/text responses and omits this field.",
                     }),
                     data: jsonSchema.unknown("Provider response payload."),
                 }, {
@@ -1014,6 +1108,9 @@ function createProxyPath() {
                 429: jsonResponse(runtimeFailureSchema()),
                 500: jsonResponse(runtimeFailureSchema()),
                 501: jsonResponse(runtimeFailureSchema()),
+                502: jsonResponse(runtimeFailureSchema()),
+                503: jsonResponse(runtimeFailureSchema()),
+                504: jsonResponse(runtimeFailureSchema()),
             },
         },
     };
@@ -1082,6 +1179,9 @@ function createOAuthAuthorizationPath() {
                                 minItems: 1,
                                 description: "Optional non-empty provider-declared scope subset to request.",
                             }),
+                            redirectUri: jsonSchema.string({
+                                description: "Optional redirect URI registered with the connection-scoped OAuth app instead of the runtime callback. Same rules as OAuthClientConfigRequest.redirectUri.",
+                            }),
                             authorizationOptionIds: jsonSchema.array(jsonSchema.string(), {
                                 description: "Optional provider authorization option ids selected for this connection.",
                             }),
@@ -1216,6 +1316,10 @@ function actionRunResponses(output) {
         413: jsonResponse(failure, "The provider response exceeded the runtime size limit, or the upstream answered 413."),
         429: jsonResponse(failure),
         500: jsonResponse(failure),
+        501: jsonResponse(failure),
+        502: jsonResponse(failure, "SaaS upstream, protocol or response size failure; execution may have completed."),
+        503: jsonResponse(failure, "SaaS project credentials or execution are unavailable."),
+        504: jsonResponse(failure, "SaaS execution timed out; execution may have completed."),
     };
 }
 function createConnectionUpsertRequestSchema() {
@@ -1240,7 +1344,7 @@ function createConcreteRunOperation(action) {
     return {
         tags: ["Runs"],
         summary: `Execute ${action.id}.`,
-        description: `${action.description} ${actionIdempotencyDescription}`,
+        description: `${action.description} ${saasExecutionDescription}${actionIdempotencyDescription}`,
         parameters: [actionIdParameter, idempotencyKeyParameter, ...namedConnectionParameters],
         requestBody: actionRunBody(action.inputSchema, `Run creation request for ${action.id}. Omitted input is treated as {}.`),
         responses: actionRunResponses(action.outputSchema),
@@ -1339,11 +1443,11 @@ function connectionManagementPaths() {
             scopes: jsonSchema.optional(jsonSchema.stringArray("Provider scopes the connector requests.")),
             authorizationOptions: jsonSchema.optional(jsonSchema.array(authorizationOption)),
         })),
-        oauthClient: jsonSchema.optional(jsonSchema.object("OAuth client configuration state; present when the provider supports OAuth.", {
+        oauthClient: jsonSchema.optional(jsonSchema.object("Default OAuth source configuration; present when the provider supports OAuth.", {
             configured: jsonSchema.boolean(),
-            customClientAvailable: jsonSchema.boolean("Whether connections may carry their own OAuth client."),
-            expectedRedirectUri: jsonSchema.string("Callback URL to register with the provider."),
-            missingFields: jsonSchema.stringArray("Required client inputs absent from the stored configuration."),
+            customClientAvailable: jsonSchema.boolean("Whether connections may carry their own OAuth client; false for a SaaS default source."),
+            expectedRedirectUri: jsonSchema.string("Callback URL: the SaaS provider config callback for a SaaS source; otherwise the local override or runtime callback."),
+            missingFields: jsonSchema.stringArray("Required local client inputs absent from storage; empty for a SaaS source."),
         })),
     });
     const parameter = (name) => ({ name, in: "path", required: true, schema: { type: "string" } });
@@ -1369,8 +1473,8 @@ function connectionManagementPaths() {
         "/v1/connection-requests/{connectionRequestId}": runtimeGetOperation("Connections", "Get an OAuth authorization result.", {
             data: request,
             parameters: [parameter("connectionRequestId")],
-            errorStatuses: [401, 403, 404],
-            description: "Requires the initiating management principal. A consumed callback does not remove the result. Responses use Cache-Control: private, no-store.",
+            errorStatuses: [401, 403, 404, 409, 429, 502, 503, 504],
+            description: "Requires the initiating management principal. An explicit valid administrator Bearer token advances SaaS authorization; cookie-only and unauthenticated local GET requests only read stored results. Console uses same-origin POST /api/oauth/connection-requests/{id}/sync with X-OpenConnector-Request: sync. A consumed callback does not remove the result. Responses use Cache-Control: private, no-store.",
         }),
     };
     for (const reconnect of [false, true]) {
@@ -1397,6 +1501,10 @@ function connectionManagementPaths() {
                         403: jsonResponse(runtimeFailureSchema()),
                         404: jsonResponse(runtimeFailureSchema()),
                         409: jsonResponse(runtimeFailureSchema()),
+                        429: jsonResponse(runtimeFailureSchema()),
+                        502: jsonResponse(runtimeFailureSchema()),
+                        503: jsonResponse(runtimeFailureSchema()),
+                        504: jsonResponse(runtimeFailureSchema()),
                     },
                 },
             };