@vauban-org/agent-sdk 1.2.0 → 1.3.0

package/src/index.ts

@@ -105,10 +105,39 @@ export { createAgentRunTracker } from "./tracking/agent-run-tracker.js";
 export type {
   AgentRunTracker,
   AgentRunStartInput,
-  AgentRunStepDelta,
   AgentRunFinish,
   DbClient,
 } from "./tracking/agent-run-tracker.js";
+
+// ─── Telemetry — sovereign multi-sink observability (ADR-ECO-039) ────────────
+export {
+  NOOP_TELEMETRY_SINK,
+  TelemetrySinkError,
+  createTelemetryBus,
+  stdoutTelemetrySink,
+  localSqliteTelemetrySink,
+  otlpTelemetrySink,
+} from "./telemetry/index.js";
+export type {
+  TelemetrySink,
+  TelemetryRunStart,
+  TelemetryRunStep,
+  TelemetryRunFinish,
+  TelemetryRunStatus,
+  TelemetryBusOptions,
+  TelemetryCounters,
+  TelemetryLogger,
+  StdoutTelemetrySinkOptions,
+  LocalSqliteTelemetrySinkOptions,
+  OtlpTelemetrySinkOptions,
+} from "./telemetry/index.js";
+
+// Re-export legacy AgentRunStepDelta + AgentRunFinalStatus (kept for backward
+// compat with `AgentRunTracker` consumers, e.g. command-center/src/tracking).
+export type {
+  AgentRunStepDelta,
+  AgentRunFinalStatus,
+} from "./tracking/agent-run-tracker.js";
 export { createBullMQRunner, BullMQRunner } from "./durable/bullmq-runner.js";
 export type {
   BullMQRunnerConfig,

package/src/orchestration/ooda/agent.ts

@@ -295,6 +295,51 @@ export class OODAAgentImpl<
     const executionMode = overrideMode ?? this._config.executionMode;
     const isReplay = false;
     const logger = this._config.logger ?? NOOP_LOGGER;
+    const startedAt = new Date().toISOString();
+
+    // ── Telemetry (ADR-ECO-039) ─────────────────────────────────────────────
+    // Failures isolated by sink/bus — never block agent. Fire-and-forget on
+    // exit paths so cycle latency is unaffected.
+    const telemetry = this._config.telemetry;
+    const telemetryStartFired = telemetry
+      ? telemetry
+          .start({
+            runId,
+            agentId: this._config.agentId,
+            agentVersion: this._config.agentVersion ?? "0.0.0",
+            model: "unknown",
+            provider: "unknown",
+            startedAt,
+          })
+          .catch((err: unknown) => {
+            logger.warn(
+              { err: (err as Error)?.message ?? String(err) },
+              "telemetry.start.failed"
+            );
+          })
+      : Promise.resolve();
+    const finishTelemetry = (
+      status: "success" | "failed" | "skipped",
+      stopReason?: string,
+      errorMessage?: string
+    ): void => {
+      if (!telemetry) return;
+      void telemetryStartFired.then(() =>
+        telemetry
+          .finish(runId, {
+            status,
+            stopReason,
+            errorMessage,
+            finishedAt: new Date().toISOString(),
+          })
+          .catch((err: unknown) =>
+            logger.warn(
+              { err: (err as Error)?.message ?? String(err) },
+              "telemetry.finish.failed"
+            )
+          )
+      );
+    };
 
     // ── OTel: agent-level span for the full cycle ───────────────────────────
     const tracer = getTracer("vauban-agent-sdk.ooda");
@@ -369,6 +414,7 @@ export class OODAAgentImpl<
       rootSpan.end();
       this._cyclesCompleted += 1;
       this._lastCycleAt = new Date().toISOString();
+      finishTelemetry("skipped", sessionResult.reason ?? "session_guard");
       return { runId, status: "skipped" };
     }
 
@@ -391,6 +437,7 @@ export class OODAAgentImpl<
       rootSpan.end();
       this._cyclesCompleted += 1;
       this._lastCycleAt = new Date().toISOString();
+      finishTelemetry("skipped", riskResult.reason ?? "risk_guard");
       return { runId, status: "skipped" };
     }
 
@@ -410,6 +457,7 @@ export class OODAAgentImpl<
       rootSpan.end();
       this._cyclesCompleted += 1;
       this._lastCycleAt = new Date().toISOString();
+      finishTelemetry("skipped", `heap_exceeded:${heapMb.toFixed(1)}mb`);
       return { runId, status: "skipped" };
     }
 
@@ -489,6 +537,7 @@ export class OODAAgentImpl<
       rootSpan.end();
       this._cyclesCompleted += 1;
       this._lastCycleAt = new Date().toISOString();
+      finishTelemetry("success");
       return { runId, status: "succeeded" };
     } catch (err) {
       logger.error(
@@ -509,6 +558,7 @@ export class OODAAgentImpl<
       rootSpan.end();
       this._cyclesCompleted += 1;
       this._lastCycleAt = new Date().toISOString();
+      finishTelemetry("failed", undefined, (err as Error).message);
       return { runId, status: "failed" };
     }
   }

package/src/orchestration/ooda/types.ts

@@ -282,6 +282,18 @@ export interface OODAAgentConfig<
   readonly errorStepImpl?: OODAContext["errorStep"];
   readonly notifySlackImpl?: OODAContext["notifySlack"];
 
+  /**
+   * Optional telemetry sink (or a {@link createTelemetryBus} for multi-sink).
+   *
+   * Per ADR-ECO-039. Receives one `start`, 0..N `step`, and one `finish` event
+   * per OODA cycle. Failures are isolated by the bus — never block the agent.
+   * When absent, telemetry is silently skipped.
+   *
+   * @experimental — public-experimental contract (interface stable as of 1.3.0,
+   * additional event fields may be added before 2.0).
+   */
+  readonly telemetry?: import("../../telemetry/port.js").TelemetrySink;
+
   /**
    * Optional HITL gate awaiter. Called when `act` phase has
    * `hitlGate: true`. Resolves when human approves; rejects to abort.

package/src/skills/_secrets.ts

@@ -0,0 +1,25 @@
+/**
+ * Internal helper for skills that read configuration secrets.
+ *
+ * Prefers `ctx.secrets` (audit-trail-bearing per ADR-ECO-036) over
+ * `process.env` when a {@link SecretsAccessor} is configured on the
+ * {@link SkillContext}. Falls back to env when no accessor is wired so
+ * legacy callers see no behavior change.
+ *
+ * Returns `undefined` when the secret is configured nowhere — callers
+ * decide whether that's a SkillNotConfiguredError or a soft default.
+ *
+ * @internal
+ */
+
+import type { SkillContext } from "../orchestration/ooda/skills.js";
+
+export function readSecret(
+  ctx: SkillContext,
+  name: string
+): string | undefined {
+  if (ctx.secrets && ctx.secrets.has(name)) {
+    return ctx.secrets.get(name);
+  }
+  return process.env[name];
+}

package/src/skills/alpaca-quote.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 ALPACA_RETRY: RetryConfig = {
+  ...RETRY_TRANSIENT,
+  retryIf: (err) =>
+    err instanceof RetryableHttpError || err instanceof TypeError,
+};
 
 const inputSchema = z
   .object({
@@ -46,8 +68,8 @@ export const alpacaQuote: Skill<AlpacaQuoteInput, AlpacaQuoteOutput> = {
       };
     }
     return withSkillSpan("alpaca_quote", async () => {
-      const apiKey = process.env.ALPACA_API_KEY;
-      const apiSecret = process.env.ALPACA_API_SECRET;
+      const apiKey = readSecret(ctx, "ALPACA_API_KEY");
+      const apiSecret = readSecret(ctx, "ALPACA_API_SECRET");
       if (!apiKey || !apiSecret) {
         throw new SkillNotConfiguredError("alpaca_quote", [
           "ALPACA_API_KEY",
@@ -55,28 +77,51 @@ export const alpacaQuote: Skill<AlpacaQuoteInput, AlpacaQuoteOutput> = {
         ]);
       }
       const dataHost = "https://data.alpaca.markets";
-      const url = `${dataHost}/v2/stocks/${encodeURIComponent(input.symbol)}/quotes/latest`;
-      const res = await fetch(url, {
-        headers: {
-          "APCA-API-KEY-ID": apiKey,
-          "APCA-API-SECRET-KEY": apiSecret,
-        },
-      });
-      if (!res.ok) {
-        throw new SkillExecutionError("alpaca_quote", `${res.status}`, {
-          status: res.status,
-        });
+      const url = `${dataHost}/v2/stocks/${encodeURIComponent(
+        input.symbol
+      )}/quotes/latest`;
+      try {
+        return await retry(
+          async () => {
+            const res = await fetch(url, {
+              headers: {
+                "APCA-API-KEY-ID": apiKey,
+                "APCA-API-SECRET-KEY": apiSecret,
+              },
+            });
+            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("alpaca_quote", `${res.status}`, {
+                status: res.status,
+              });
+            }
+            const data = (await res.json()) as {
+              quote?: { bp?: number; ap?: number; t?: string };
+            };
+            return {
+              symbol: input.symbol,
+              bid: data.quote?.bp ?? 0,
+              ask: data.quote?.ap ?? 0,
+              timestamp: data.quote?.t ?? new Date().toISOString(),
+              mode: input.mode,
+            };
+          },
+          { config: ALPACA_RETRY }
+        );
+      } catch (err) {
+        const cause = err instanceof RetryExhaustedError ? err.lastError : err;
+        if (cause instanceof RetryableHttpError) {
+          throw new SkillExecutionError(
+            "alpaca_quote",
+            `${cause.status} after retries`,
+            { status: cause.status }
+          );
+        }
+        throw cause;
       }
-      const data = (await res.json()) as {
-        quote?: { bp?: number; ap?: number; t?: string };
-      };
-      return {
-        symbol: input.symbol,
-        bid: data.quote?.bp ?? 0,
-        ask: data.quote?.ap ?? 0,
-        timestamp: data.quote?.t ?? new Date().toISOString(),
-        mode: input.mode,
-      };
     });
   },
 };

package/src/skills/send-email.ts

@@ -11,6 +11,7 @@ import { z } from "zod";
 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";
 
 const inputSchema = z
   .object({
@@ -29,18 +30,6 @@ export interface SendEmailOutput {
   message_id: string | null;
 }
 
-/**
- * Prefer ctx.secrets (audit-trail-bearing) over process.env. When no secrets
- * accessor is configured, falls back to env so legacy callers see no behavior
- * change. When the secret is absent in both, returns undefined.
- */
-function readSecret(ctx: SkillContext, name: string): string | undefined {
-  if (ctx.secrets) {
-    if (ctx.secrets.has(name)) return ctx.secrets.get(name);
-  }
-  return process.env[name];
-}
-
 export const sendEmail: Skill<SendEmailInput, SendEmailOutput> = {
   name: "send_email",
   inputSchema,

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,
-        };
       });
     },
   };