@vauban-org/agent-sdk 0.16.0

package/src/skills/slack-notify.ts

@@ -0,0 +1,90 @@
+/**
+ * slack_notify — Slack chat.postMessage.
+ *
+ * Resolves channel from messaging_user_binding when binding_user_id provided.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { SkillExecutionError, SkillNotConfiguredError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    text: z.string().min(1).max(40_000),
+    channel: z.string().optional(),
+    binding_user_id: z.string().uuid().optional(),
+    blocks: z.array(z.record(z.string(), z.unknown())).optional(),
+  })
+  .strict()
+  .refine((v) => v.channel || v.binding_user_id, {
+    message: "channel or binding_user_id required",
+  });
+type SlackNotifyInput = z.infer<typeof inputSchema>;
+
+export interface SlackNotifyOutput {
+  delivered: boolean;
+  ts: string | null;
+}
+
+export const slackNotify: Skill<SlackNotifyInput, SlackNotifyOutput> = {
+  name: "slack_notify",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<SlackNotifyOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["slack_notify"];
+      if (mock) return mock(input) as SlackNotifyOutput;
+      return { delivered: false, ts: null };
+    }
+    return withSkillSpan("slack_notify", async () => {
+      const token = process.env.SLACK_BOT_TOKEN;
+      if (!token) {
+        throw new SkillNotConfiguredError("slack_notify", ["SLACK_BOT_TOKEN"]);
+      }
+      let channel = input.channel;
+      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],
+        );
+        channel = rows[0]?.chat_id;
+        if (!channel) {
+          throw new SkillExecutionError(
+            "slack_notify",
+            `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",
+        );
+      }
+      return { delivered: true, ts: data.ts ?? null };
+    });
+  },
+};

package/src/skills/starknet-balance.ts

@@ -0,0 +1,106 @@
+/**
+ * starknet_balance — read STRK / ETH / vault balance via starknet.js (peer dep).
+ *
+ * starknet.js stays peerDependency. We dynamic-import — if absent, throw
+ * SkillNotConfiguredError. RPC URL via STARKNET_RPC_URL env.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { SkillExecutionError, SkillNotConfiguredError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    address: z
+      .string()
+      .regex(/^0x[0-9a-fA-F]{1,64}$/),
+    token: z.enum(["STRK", "ETH", "VAULT"]).default("STRK"),
+    /** Override token contract for "VAULT" or custom tokens. */
+    contract: z
+      .string()
+      .regex(/^0x[0-9a-fA-F]{1,64}$/)
+      .optional(),
+  })
+  .strict();
+type StarknetBalanceInput = z.infer<typeof inputSchema>;
+
+export interface StarknetBalanceOutput {
+  address: string;
+  token: "STRK" | "ETH" | "VAULT";
+  /** Raw u256 as decimal string (avoid float64 — see core/security-boundaries). */
+  balance_wei: string;
+}
+
+const STRK = "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d";
+const ETH = "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
+
+export const starknetBalance: Skill<
+  StarknetBalanceInput,
+  StarknetBalanceOutput
+> = {
+  name: "starknet_balance",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<StarknetBalanceOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["starknet_balance"];
+      if (mock) return mock(input) as StarknetBalanceOutput;
+      return {
+        address: input.address,
+        token: input.token,
+        balance_wei: "0",
+      };
+    }
+    return withSkillSpan("starknet_balance", async () => {
+      const rpcUrl = process.env.STARKNET_RPC_URL;
+      if (!rpcUrl) {
+        throw new SkillNotConfiguredError("starknet_balance", [
+          "STARKNET_RPC_URL",
+        ]);
+      }
+      let starknet: typeof import("starknet");
+      try {
+        starknet = await import(/* @vite-ignore */ "starknet");
+      } catch (_err) {
+        throw new SkillNotConfiguredError("starknet_balance", [
+          "starknet (peer dependency)",
+        ]);
+      }
+      const provider = new starknet.RpcProvider({ nodeUrl: rpcUrl });
+      const tokenContract =
+        input.contract ??
+        (input.token === "STRK"
+          ? STRK
+          : input.token === "ETH"
+            ? ETH
+            : undefined);
+      if (!tokenContract) {
+        throw new SkillExecutionError(
+          "starknet_balance",
+          "VAULT requires explicit `contract` override",
+        );
+      }
+      try {
+        const result = await provider.callContract({
+          contractAddress: tokenContract,
+          entrypoint: "balanceOf",
+          calldata: [input.address],
+        });
+        // u256 returned as 2 felts (low, high). Combine.
+        const low = BigInt(result[0] ?? "0");
+        const high = BigInt(result[1] ?? "0");
+        const total = low + (high << 128n);
+        return {
+          address: input.address,
+          token: input.token,
+          balance_wei: total.toString(),
+        };
+      } catch (err) {
+        throw new SkillExecutionError("starknet_balance", "RPC error", {
+          cause: err,
+        });
+      }
+    });
+  },
+};

package/src/skills/telegram-notify.ts

@@ -0,0 +1,88 @@
+/**
+ * telegram_notify — POST Telegram bot sendMessage.
+ *
+ * Resolves chat_id from messaging_user_binding when `binding_user_id`
+ * is provided; else uses `chat_id` directly.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { SkillExecutionError, SkillNotConfiguredError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    text: z.string().min(1).max(4096),
+    chat_id: z.string().optional(),
+    binding_user_id: z.string().uuid().optional(),
+    parse_mode: z.enum(["MarkdownV2", "HTML"]).optional(),
+  })
+  .strict()
+  .refine((v) => v.chat_id || v.binding_user_id, {
+    message: "chat_id or binding_user_id required",
+  });
+type TelegramNotifyInput = z.infer<typeof inputSchema>;
+
+export interface TelegramNotifyOutput {
+  delivered: boolean;
+  message_id: number | null;
+}
+
+export const telegramNotify: Skill<TelegramNotifyInput, TelegramNotifyOutput> =
+  {
+    name: "telegram_notify",
+    inputSchema,
+    async execute(input, ctx: SkillContext): Promise<TelegramNotifyOutput> {
+      if (ctx.isReplay) {
+        const mock = ctx.dryRunMocks["telegram_notify"];
+        if (mock) return mock(input) as TelegramNotifyOutput;
+        return { delivered: false, message_id: null };
+      }
+      return withSkillSpan("telegram_notify", async () => {
+        const token = process.env.TELEGRAM_BOT_TOKEN;
+        if (!token) {
+          throw new SkillNotConfiguredError("telegram_notify", [
+            "TELEGRAM_BOT_TOKEN",
+          ]);
+        }
+        let chatId = input.chat_id;
+        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],
+          );
+          chatId = rows[0]?.chat_id;
+          if (!chatId) {
+            throw new SkillExecutionError(
+              "telegram_notify",
+              `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,
+          });
+        }
+        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

@@ -0,0 +1,108 @@
+/**
+ * web_search — Brave Search API + Tavily fallback.
+ *
+ * V8-2: isReplay short-circuits BEFORE any network I/O.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { SkillExecutionError, SkillNotConfiguredError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    query: z.string().min(1).max(512),
+    limit: z.number().int().min(1).max(20).default(5),
+  })
+  .strict();
+type WebSearchInput = z.infer<typeof inputSchema>;
+
+export interface WebSearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+export interface WebSearchOutput {
+  results: WebSearchResult[];
+  provider: "brave" | "tavily" | "replay";
+}
+
+export const webSearch: Skill<WebSearchInput, WebSearchOutput> = {
+  name: "web_search",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<WebSearchOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["web_search"];
+      if (mock) return mock(input) as WebSearchOutput;
+      return { results: [], provider: "replay" };
+    }
+    return withSkillSpan("web_search", async () => {
+      const braveKey = process.env.BRAVE_SEARCH_KEY;
+      const tavilyKey = process.env.TAVILY_API_KEY;
+      if (!braveKey && !tavilyKey) {
+        throw new SkillNotConfiguredError("web_search", [
+          "BRAVE_SEARCH_KEY",
+          "TAVILY_API_KEY",
+        ]);
+      }
+      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?: {
+              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" };
+        }
+        if (!tavilyKey) {
+          throw new SkillExecutionError("web_search", `brave ${res.status}`, {
+            status: res.status,
+          });
+        }
+      }
+      // 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" };
+    });
+  },
+};

package/src/templates/complex-agent.ts

@@ -0,0 +1,187 @@
+/**
+ * ComplexAgent Template — Tier 3 (Supervisor-Worker + Plan-and-Execute + Debate).
+ *
+ * Promoted from forge/src/agents/shared/templates/complex-agent.ts (Vague 1.B.7).
+ *
+ * For agents that need multi-agent coordination, step-by-step planning,
+ * and adversarial debate:
+ *   - Orchestrateur Central, Treasury Agent, DevOps Agent, Security Auditor,
+ *     Contract Reviewer.
+ *
+ * Pattern: observe → orient (LLM + Debate) → decide (Plan decomposition) →
+ *          act (execute steps) → reflect (self-critique, optional) → feedback.
+ *
+ * Differences from Forge template:
+ * - AgentDependencies removed — uses AgentFactoryDeps (SDK-native)
+ * - buildSkills / createForgeAgent replaced by createAgentFromConfig (SDK)
+ * - Forge-specific couplings (slackWebhookUrl, litellmUrl) removed
+ * - hitlEscalationLevel wired to AgentFactoryConfig (not Forge-specific gate)
+ *
+ * @public @since 0.20.0
+ */
+
+import { createAgentFromConfig } from "../factory/agent-factory.js";
+import type { AgentFactoryDeps } from "../factory/agent-factory.js";
+import type { OODAAgent, OODAContext } from "../orchestration/ooda/types.js";
+import type {
+  SessionGuard,
+  RiskGuard,
+  OutcomeRecord,
+} from "../orchestration/ooda/types.js";
+
+// ─── Options ──────────────────────────────────────────────────────────────────
+
+/**
+ * ComplexAgentOptions — typed configuration for Tier 3 agents.
+ *
+ * Type parameters chain OODA phase I/O:
+ * - `TObs`      — observation output
+ * - `TOrient`   — orientation output (after LLM + Debate)
+ * - `TDecision` — decision output (plan decomposition)
+ * - `TAction`   — action output (step execution result)
+ * - `TFeedback` — feedback output
+ *
+ * @public
+ */
+export interface ComplexAgentOptions<
+  TObs,
+  TOrient,
+  TDecision,
+  TAction,
+  TFeedback
+> {
+  /** Agent identifier (e.g. "treasury-agent"). */
+  agentId: string;
+  /** Agent semver string. */
+  agentVersion?: string;
+  /** Cycle interval in milliseconds. */
+  intervalMs: number;
+  /** Observe phase: read data from Brain/APIs (readOnly). */
+  observe: (_: void, ctx: OODAContext) => Promise<TObs>;
+  /** Orient phase: LLM analysis + optional Multi-Agent Debate (readOnly). */
+  orient: (obs: TObs, ctx: OODAContext) => Promise<TOrient>;
+  /** Decide phase: plan decomposition + LLM routing. */
+  decide: (orient: TOrient, ctx: OODAContext) => Promise<TDecision>;
+  /**
+   * Act phase: executeSteps with optional ReactLoop for tool-calling.
+   * Set `hitlEscalationLevel` to gate this phase on HITL approval.
+   */
+  act: (decision: TDecision, ctx: OODAContext) => Promise<TAction>;
+  /**
+   * Optional reflect phase: self-critique with Reflexion memory.
+   * When provided, runs between act and feedback.
+   */
+  reflect?: (
+    input: TAction & { decision: TDecision },
+    ctx: OODAContext
+  ) => Promise<TFeedback>;
+  /** Feedback phase: log outcome, archive to Brain. */
+  feedback: (
+    input: TAction & { decision?: TDecision },
+    ctx: OODAContext
+  ) => Promise<TFeedback>;
+  /**
+   * HITL escalation level for the act phase.
+   * - "L2": async review before irreversible effects.
+   * - "L3": synchronous HITL approval required (default).
+   */
+  hitlEscalationLevel?: "L2" | "L3";
+  /** Optional session guards (e.g. market hours). Defaults to alwaysOn. */
+  sessionGuards?: SessionGuard[];
+  /** Optional risk guards (e.g. circuit breaker, budget). */
+  riskGuards?: RiskGuard[];
+  /** Optional outcome mapping for Economic Observer. */
+  outcomeMapping?: (feedback: TFeedback) => OutcomeRecord | null;
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+/**
+ * Create a Tier 3 (complex, supervisor-worker, debate-capable) OODA agent.
+ *
+ * Boilerplate reduction vs. raw `createAgentFromConfig`:
+ * - HITL wiring handled automatically when `hitlEscalationLevel` is set
+ * - Optional `reflect` phase wired correctly between act and feedback
+ * - Phase `type` codes and `readOnly` flags set automatically
+ *
+ * @example
+ * ```ts
+ * const agent = await createComplexAgent<Obs, Orient, Plan, ExecResult, Feedback>(deps, {
+ *   agentId: "treasury-agent",
+ *   intervalMs: 3_600_000,
+ *   observe: async () => ({ balance: 1000, pendingTx: [] }),
+ *   orient: async (obs) => ({ recommendation: "hold", risk: "low" }),
+ *   decide: async (orient) => ({ steps: [{ action: "record", data: orient }] }),
+ *   act: async (plan) => ({ stepsExecuted: plan.steps.length }),
+ *   feedback: async (result) => ({ success: result.stepsExecuted > 0 }),
+ *   hitlEscalationLevel: "L3",
+ * });
+ * await agent.start();
+ * ```
+ *
+ * @public
+ */
+export async function createComplexAgent<
+  TObs,
+  TOrient,
+  TDecision,
+  TAction,
+  TFeedback
+>(
+  deps: AgentFactoryDeps,
+  opts: ComplexAgentOptions<TObs, TOrient, TDecision, TAction, TFeedback>
+): Promise<OODAAgent> {
+  return createAgentFromConfig<
+    unknown,
+    TObs,
+    TOrient,
+    TDecision,
+    TAction,
+    TFeedback
+  >(deps, {
+    agentId: opts.agentId,
+    agentVersion: opts.agentVersion ?? "0.1.0",
+    intervalMs: opts.intervalMs,
+    hitlEscalationLevel: opts.hitlEscalationLevel ?? "L3",
+    sessionGuards: opts.sessionGuards,
+    riskGuards: opts.riskGuards,
+    outcomeMapping: opts.outcomeMapping,
+    phases: {
+      observe: {
+        type: "observation",
+        readOnly: true,
+        fn: opts.observe,
+      },
+      orient: {
+        type: "retrieval",
+        readOnly: true,
+        fn: opts.orient,
+      },
+      decide: {
+        type: "decision",
+        fn: opts.decide,
+      },
+      act: {
+        type: "execution",
+        hitlGate: opts.hitlEscalationLevel !== undefined,
+        fn: opts.act,
+      },
+      ...(opts.reflect !== undefined
+        ? {
+            reflect: {
+              type: "feedback" as const,
+              readOnly: true,
+              fn: opts.reflect,
+            },
+          }
+        : {}),
+      feedback: {
+        type: "feedback",
+        fn: opts.feedback as (
+          input: TAction,
+          ctx: OODAContext
+        ) => Promise<TFeedback>,
+      },
+    },
+  });
+}

package/src/templates/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent tier templates — SDK-distributable factory helpers.
+ *
+ * Three tiers promoted from Forge (Vague 1.B.7):
+ * - Tier 1 — SimpleAgent: rule-based, no LLM debate
+ * - Tier 2 — ReasoningAgent: LLM + Reflexion + Inner Monologue
+ * - Tier 3 — ComplexAgent: Supervisor-Worker + Debate + HITL gate
+ *
+ * @public @since 0.20.0
+ */
+
+export { createSimpleAgent } from "./simple-agent.js";
+export type {
+  SimpleAgentOptions,
+  SimpleAction,
+  SimpleDecision,
+  SimpleExecutionResult,
+} from "./simple-agent.js";
+
+export { createComplexAgent } from "./complex-agent.js";
+export type { ComplexAgentOptions } from "./complex-agent.js";
+
+export { createReasoningAgent } from "./reasoning-agent.js";
+export type {
+  ReasoningAgentOptions,
+  ReasoningAgentConfig,
+} from "./reasoning-agent.js";