@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/src/skills/slack-notify.ts

@@ -6,9 +6,31 @@
  * @public
  */
 import { z } from "zod";
+
+import {
+  retry,
+  RETRY_TRANSIENT,
+  RetryExhaustedError,
+  type RetryConfig,
+} from "../retry/index.js";
 import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+
 import { SkillExecutionError, SkillNotConfiguredError } from "./errors.js";
 import { withSkillSpan } from "./_otel.js";
+import { readSecret } from "./_secrets.js";
+
+class RetryableHttpError extends Error {
+  constructor(public readonly status: number, public readonly body: string) {
+    super(`HTTP ${status}: ${body.slice(0, 200)}`);
+    this.name = "RetryableHttpError";
+  }
+}
+
+const SLACK_RETRY: RetryConfig = {
+  ...RETRY_TRANSIENT,
+  retryIf: (err) =>
+    err instanceof RetryableHttpError || err instanceof TypeError,
+};
 
 const inputSchema = z
   .object({
@@ -38,7 +60,7 @@ export const slackNotify: Skill<SlackNotifyInput, SlackNotifyOutput> = {
       return { delivered: false, ts: null };
     }
     return withSkillSpan("slack_notify", async () => {
-      const token = process.env.SLACK_BOT_TOKEN;
+      const token = readSecret(ctx, "SLACK_BOT_TOKEN");
       if (!token) {
         throw new SkillNotConfiguredError("slack_notify", ["SLACK_BOT_TOKEN"]);
       }
@@ -46,45 +68,66 @@ export const slackNotify: Skill<SlackNotifyInput, SlackNotifyOutput> = {
       if (!channel && input.binding_user_id) {
         const { rows } = await ctx.db.query<{ chat_id: string }>(
           "SELECT chat_id FROM messaging_user_binding WHERE user_id = $1 AND channel = 'slack' LIMIT 1",
-          [input.binding_user_id],
+          [input.binding_user_id]
         );
         channel = rows[0]?.chat_id;
         if (!channel) {
           throw new SkillExecutionError(
             "slack_notify",
-            `no slack binding for user ${input.binding_user_id}`,
+            `no slack binding for user ${input.binding_user_id}`
           );
         }
       }
-      const res = await fetch("https://slack.com/api/chat.postMessage", {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json; charset=utf-8",
-          Authorization: `Bearer ${token}`,
-        },
-        body: JSON.stringify({
-          channel,
-          text: input.text,
-          blocks: input.blocks,
-        }),
-      });
-      if (!res.ok) {
-        throw new SkillExecutionError("slack_notify", `${res.status}`, {
-          status: res.status,
-        });
-      }
-      const data = (await res.json()) as {
-        ok?: boolean;
-        ts?: string;
-        error?: string;
-      };
-      if (!data.ok) {
-        throw new SkillExecutionError(
-          "slack_notify",
-          data.error ?? "unknown slack error",
+      try {
+        return await retry(
+          async () => {
+            const res = await fetch("https://slack.com/api/chat.postMessage", {
+              method: "POST",
+              headers: {
+                "Content-Type": "application/json; charset=utf-8",
+                Authorization: `Bearer ${token}`,
+              },
+              body: JSON.stringify({
+                channel,
+                text: input.text,
+                blocks: input.blocks,
+              }),
+            });
+            if (!res.ok) {
+              const body = await res.text().catch(() => "");
+              if (res.status >= 500 || res.status === 429) {
+                throw new RetryableHttpError(res.status, body);
+              }
+              throw new SkillExecutionError("slack_notify", `${res.status}`, {
+                status: res.status,
+              });
+            }
+            const data = (await res.json()) as {
+              ok?: boolean;
+              ts?: string;
+              error?: string;
+            };
+            if (!data.ok) {
+              throw new SkillExecutionError(
+                "slack_notify",
+                data.error ?? "unknown slack error"
+              );
+            }
+            return { delivered: true, ts: data.ts ?? null };
+          },
+          { config: SLACK_RETRY }
         );
+      } catch (err) {
+        const cause = err instanceof RetryExhaustedError ? err.lastError : err;
+        if (cause instanceof RetryableHttpError) {
+          throw new SkillExecutionError(
+            "slack_notify",
+            `${cause.status} after retries`,
+            { status: cause.status }
+          );
+        }
+        throw cause;
       }
-      return { delivered: true, ts: data.ts ?? null };
     });
   },
 };

package/src/skills/telegram-notify.ts

@@ -7,9 +7,31 @@
  * @public
  */
 import { z } from "zod";
+
+import {
+  retry,
+  RETRY_TRANSIENT,
+  RetryExhaustedError,
+  type RetryConfig,
+} from "../retry/index.js";
 import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+
 import { SkillExecutionError, SkillNotConfiguredError } from "./errors.js";
 import { withSkillSpan } from "./_otel.js";
+import { readSecret } from "./_secrets.js";
+
+class RetryableHttpError extends Error {
+  constructor(public readonly status: number, public readonly body: string) {
+    super(`HTTP ${status}: ${body.slice(0, 200)}`);
+    this.name = "RetryableHttpError";
+  }
+}
+
+const TELEGRAM_RETRY: RetryConfig = {
+  ...RETRY_TRANSIENT,
+  retryIf: (err) =>
+    err instanceof RetryableHttpError || err instanceof TypeError,
+};
 
 const inputSchema = z
   .object({
@@ -40,7 +62,7 @@ export const telegramNotify: Skill<TelegramNotifyInput, TelegramNotifyOutput> =
         return { delivered: false, message_id: null };
       }
       return withSkillSpan("telegram_notify", async () => {
-        const token = process.env.TELEGRAM_BOT_TOKEN;
+        const token = readSecret(ctx, "TELEGRAM_BOT_TOKEN");
         if (!token) {
           throw new SkillNotConfiguredError("telegram_notify", [
             "TELEGRAM_BOT_TOKEN",
@@ -50,39 +72,63 @@ export const telegramNotify: Skill<TelegramNotifyInput, TelegramNotifyOutput> =
         if (!chatId && input.binding_user_id) {
           const { rows } = await ctx.db.query<{ chat_id: string }>(
             "SELECT chat_id FROM messaging_user_binding WHERE user_id = $1 AND channel = 'telegram' LIMIT 1",
-            [input.binding_user_id],
+            [input.binding_user_id]
           );
           chatId = rows[0]?.chat_id;
           if (!chatId) {
             throw new SkillExecutionError(
               "telegram_notify",
-              `no telegram binding for user ${input.binding_user_id}`,
+              `no telegram binding for user ${input.binding_user_id}`
             );
           }
         }
         const url = `https://api.telegram.org/bot${token}/sendMessage`;
-        const res = await fetch(url, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            chat_id: chatId,
-            text: input.text,
-            parse_mode: input.parse_mode,
-          }),
-        });
-        if (!res.ok) {
-          throw new SkillExecutionError("telegram_notify", `${res.status}`, {
-            status: res.status,
-          });
+        try {
+          return await retry(
+            async () => {
+              const res = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                  chat_id: chatId,
+                  text: input.text,
+                  parse_mode: input.parse_mode,
+                }),
+              });
+              if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                if (res.status >= 500 || res.status === 429) {
+                  throw new RetryableHttpError(res.status, body);
+                }
+                throw new SkillExecutionError(
+                  "telegram_notify",
+                  `${res.status}`,
+                  { status: res.status }
+                );
+              }
+              const data = (await res.json()) as {
+                ok?: boolean;
+                result?: { message_id?: number };
+              };
+              return {
+                delivered: data.ok === true,
+                message_id: data.result?.message_id ?? null,
+              };
+            },
+            { config: TELEGRAM_RETRY }
+          );
+        } catch (err) {
+          const cause =
+            err instanceof RetryExhaustedError ? err.lastError : err;
+          if (cause instanceof RetryableHttpError) {
+            throw new SkillExecutionError(
+              "telegram_notify",
+              `${cause.status} after retries`,
+              { status: cause.status }
+            );
+          }
+          throw cause;
         }
-        const data = (await res.json()) as {
-          ok?: boolean;
-          result?: { message_id?: number };
-        };
-        return {
-          delivered: data.ok === true,
-          message_id: data.result?.message_id ?? null,
-        };
       });
     },
   };

package/src/skills/web-search.ts

@@ -6,9 +6,31 @@
  * @public
  */
 import { z } from "zod";
+
+import {
+  retry,
+  RETRY_TRANSIENT,
+  RetryExhaustedError,
+  type RetryConfig,
+} from "../retry/index.js";
 import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+
 import { SkillExecutionError, SkillNotConfiguredError } from "./errors.js";
 import { withSkillSpan } from "./_otel.js";
+import { readSecret } from "./_secrets.js";
+
+class RetryableHttpError extends Error {
+  constructor(public readonly status: number, public readonly body: string) {
+    super(`HTTP ${status}: ${body.slice(0, 200)}`);
+    this.name = "RetryableHttpError";
+  }
+}
+
+const SEARCH_RETRY: RetryConfig = {
+  ...RETRY_TRANSIENT,
+  retryIf: (err) =>
+    err instanceof RetryableHttpError || err instanceof TypeError,
+};
 
 const inputSchema = z
   .object({
@@ -38,71 +60,131 @@ export const webSearch: Skill<WebSearchInput, WebSearchOutput> = {
       return { results: [], provider: "replay" };
     }
     return withSkillSpan("web_search", async () => {
-      const braveKey = process.env.BRAVE_SEARCH_KEY;
-      const tavilyKey = process.env.TAVILY_API_KEY;
+      const braveKey = readSecret(ctx, "BRAVE_SEARCH_KEY");
+      const tavilyKey = readSecret(ctx, "TAVILY_API_KEY");
       if (!braveKey && !tavilyKey) {
         throw new SkillNotConfiguredError("web_search", [
           "BRAVE_SEARCH_KEY",
           "TAVILY_API_KEY",
         ]);
       }
+
+      // Try Brave first when configured. Retry on 5xx/429. Fall back to
+      // Tavily on any final non-OK (4xx other than 429 short-circuits).
       if (braveKey) {
-        const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(input.query)}&count=${input.limit}`;
-        const res = await fetch(url, {
-          headers: {
-            Accept: "application/json",
-            "X-Subscription-Token": braveKey,
-          },
-        });
-        if (res.ok) {
-          const data = (await res.json()) as {
-            web?: {
+        try {
+          return await retry(
+            async () => {
+              const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(
+                input.query
+              )}&count=${input.limit}`;
+              const res = await fetch(url, {
+                headers: {
+                  Accept: "application/json",
+                  "X-Subscription-Token": braveKey,
+                },
+              });
+              if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                if (res.status >= 500 || res.status === 429) {
+                  throw new RetryableHttpError(res.status, body);
+                }
+                throw new SkillExecutionError(
+                  "web_search",
+                  `brave ${res.status}`,
+                  { status: res.status }
+                );
+              }
+              const data = (await res.json()) as {
+                web?: {
+                  results?: Array<{
+                    title?: string;
+                    url?: string;
+                    description?: string;
+                  }>;
+                };
+              };
+              const results: WebSearchResult[] = (data.web?.results ?? []).map(
+                (r) => ({
+                  title: r.title ?? "",
+                  url: r.url ?? "",
+                  snippet: r.description ?? "",
+                })
+              );
+              return { results, provider: "brave" as const };
+            },
+            { config: SEARCH_RETRY }
+          );
+        } catch (err) {
+          if (!tavilyKey) {
+            const cause =
+              err instanceof RetryExhaustedError ? err.lastError : err;
+            if (cause instanceof RetryableHttpError) {
+              throw new SkillExecutionError(
+                "web_search",
+                `brave ${cause.status} after retries`,
+                { status: cause.status }
+              );
+            }
+            throw cause;
+          }
+          // Brave failed — fall through to Tavily.
+        }
+      }
+
+      // Tavily (primary if no Brave key, else fallback)
+      try {
+        return await retry(
+          async () => {
+            const res = await fetch("https://api.tavily.com/search", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({
+                api_key: tavilyKey,
+                query: input.query,
+                max_results: input.limit,
+              }),
+            });
+            if (!res.ok) {
+              const body = await res.text().catch(() => "");
+              if (res.status >= 500 || res.status === 429) {
+                throw new RetryableHttpError(res.status, body);
+              }
+              throw new SkillExecutionError(
+                "web_search",
+                `tavily ${res.status}`,
+                { status: res.status }
+              );
+            }
+            const data = (await res.json()) as {
               results?: Array<{
                 title?: string;
                 url?: string;
-                description?: string;
+                content?: string;
               }>;
             };
-          };
-          const results: WebSearchResult[] = (data.web?.results ?? []).map(
-            (r) => ({
-              title: r.title ?? "",
-              url: r.url ?? "",
-              snippet: r.description ?? "",
-            }),
+            const results: WebSearchResult[] = (data.results ?? []).map(
+              (r) => ({
+                title: r.title ?? "",
+                url: r.url ?? "",
+                snippet: r.content ?? "",
+              })
+            );
+            return { results, provider: "tavily" as const };
+          },
+          { config: SEARCH_RETRY }
+        );
+      } catch (err) {
+        const cause = err instanceof RetryExhaustedError ? err.lastError : err;
+        if (cause instanceof RetryableHttpError) {
+          throw new SkillExecutionError(
+            "web_search",
+            `tavily ${cause.status} after retries`,
+            { status: cause.status }
           );
-          return { results, provider: "brave" };
-        }
-        if (!tavilyKey) {
-          throw new SkillExecutionError("web_search", `brave ${res.status}`, {
-            status: res.status,
-          });
         }
+        throw cause;
       }
-      // Tavily fallback
-      const res = await fetch("https://api.tavily.com/search", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          api_key: tavilyKey,
-          query: input.query,
-          max_results: input.limit,
-        }),
-      });
-      if (!res.ok) {
-        throw new SkillExecutionError("web_search", `tavily ${res.status}`, {
-          status: res.status,
-        });
-      }
-      const data = (await res.json()) as {
-        results?: Array<{ title?: string; url?: string; content?: string }>;
-      };
-      const results: WebSearchResult[] = (data.results ?? []).map((r) => ({
-        title: r.title ?? "",
-        url: r.url ?? "",
-        snippet: r.content ?? "",
-      }));
-      return { results, provider: "tavily" };
     });
   },
 };