@vauban-org/agent-sdk 0.16.0

package/src/skills/record-outcome.ts

@@ -0,0 +1,125 @@
+/**
+ * record_outcome — helper for outcomeMapping. INSERTs an `outcomes` row.
+ *
+ * Looks up `is_pending_backfill` from outcomes.yaml at OUTCOMES_YAML_PATH
+ * (defaults to false when path absent or outcome_type not declared).
+ *
+ * Distinct from `tracking/gen-ai.recordOutcome()` (OTel attribute helper).
+ * Lives in skills/ because it's invoked from OODA Act phase as a Skill.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { SkillExecutionError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    agent_id: z.string().min(1).max(64),
+    agent_run_id: z.string().uuid().nullable(),
+    outcome_type: z.string().min(1).max(64),
+    /** Signed integer cents. */
+    value_cents: z.number().int(),
+    currency: z.string().length(3).default("USD"),
+    occurred_at: z
+      .string()
+      .datetime({ offset: true })
+      .default(() => new Date().toISOString()),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+type RecordOutcomeInput = z.infer<typeof inputSchema>;
+
+export interface RecordOutcomeOutput {
+  id: string;
+  is_pending_backfill: boolean;
+}
+
+interface OutcomesYamlEntry {
+  type: string;
+  is_pending_backfill?: boolean;
+}
+
+let OUTCOMES_INDEX: Map<string, boolean> | null = null;
+
+async function loadOutcomesIndex(): Promise<Map<string, boolean>> {
+  if (OUTCOMES_INDEX) return OUTCOMES_INDEX;
+  const path = process.env.OUTCOMES_YAML_PATH;
+  if (!path) {
+    OUTCOMES_INDEX = new Map();
+    return OUTCOMES_INDEX;
+  }
+  try {
+    const [fs, yaml] = await Promise.all([
+      import("node:fs/promises"),
+      import("yaml"),
+    ]);
+    const raw = await fs.readFile(path, "utf-8");
+    const parsed = yaml.parse(raw) as
+      | { outcomes?: OutcomesYamlEntry[] }
+      | OutcomesYamlEntry[];
+    const entries = Array.isArray(parsed)
+      ? parsed
+      : (parsed.outcomes ?? []);
+    const m = new Map<string, boolean>();
+    for (const e of entries) {
+      m.set(e.type, e.is_pending_backfill === true);
+    }
+    OUTCOMES_INDEX = m;
+    return OUTCOMES_INDEX;
+  } catch (err) {
+    throw new SkillExecutionError("record_outcome", "could not load outcomes.yaml", {
+      cause: err,
+    });
+  }
+}
+
+/** Test helper. */
+export function _resetOutcomesIndex(): void {
+  OUTCOMES_INDEX = null;
+}
+
+export const recordOutcomeSkill: Skill<
+  RecordOutcomeInput,
+  RecordOutcomeOutput
+> = {
+  name: "record_outcome",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<RecordOutcomeOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["record_outcome"];
+      if (mock) return mock(input) as RecordOutcomeOutput;
+      return {
+        id: "00000000-0000-0000-0000-000000000000",
+        is_pending_backfill: false,
+      };
+    }
+    return withSkillSpan("record_outcome", async () => {
+      const idx = await loadOutcomesIndex();
+      const isPending = idx.get(input.outcome_type) ?? false;
+      const { rows } = await ctx.db.query<{ id: string }>(
+        `INSERT INTO outcomes
+          (agent_id, agent_run_id, outcome_type, value_cents, currency,
+           occurred_at, is_pending_backfill, metadata)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb)
+         RETURNING id`,
+        [
+          input.agent_id,
+          input.agent_run_id,
+          input.outcome_type,
+          input.value_cents,
+          input.currency,
+          input.occurred_at,
+          isPending,
+          JSON.stringify(input.metadata ?? {}),
+        ],
+      );
+      const id = rows[0]?.id;
+      if (!id) {
+        throw new Error("record_outcome: INSERT returned no id");
+      }
+      return { id, is_pending_backfill: isPending };
+    });
+  },
+};

package/src/skills/run-sql-query.ts

@@ -0,0 +1,87 @@
+/**
+ * run_sql_query — read-only SQL on the agent's scoped DB (cc:read scope).
+ *
+ * Pre-check: rejects any query that contains a write keyword
+ * (INSERT/UPDATE/DELETE/DROP/ALTER/TRUNCATE/GRANT/CREATE) outside of
+ * a string literal.
+ *
+ * NOTE: this is a defence-in-depth check; DB-level read-only role is
+ * still required at the host wiring layer.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { SqlReadOnlyViolation } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    sql: z.string().min(1).max(8_000),
+    params: z.array(z.unknown()).max(64).optional(),
+  })
+  .strict();
+type RunSqlQueryInput = z.infer<typeof inputSchema>;
+
+export interface RunSqlQueryOutput {
+  rows: object[];
+  rowCount: number;
+}
+
+const WRITE_KEYWORDS = [
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+  "DROP",
+  "ALTER",
+  "TRUNCATE",
+  "GRANT",
+  "REVOKE",
+  "CREATE",
+  "REPLACE",
+  "MERGE",
+  "CALL",
+  "VACUUM",
+  "REINDEX",
+  "COPY",
+];
+
+/** Strips PostgreSQL string literals + line/block comments before keyword scan. */
+function stripStringsAndComments(sql: string): string {
+  return sql
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/'(?:''|[^'])*'/g, " ")
+    .replace(/\$\$[\s\S]*?\$\$/g, " ");
+}
+
+export function isReadOnlySql(sql: string): boolean {
+  const stripped = stripStringsAndComments(sql).toUpperCase();
+  for (const kw of WRITE_KEYWORDS) {
+    const re = new RegExp(`(^|[^A-Z_])${kw}([^A-Z_]|$)`);
+    if (re.test(stripped)) return false;
+  }
+  return true;
+}
+
+export const runSqlQuery: Skill<RunSqlQueryInput, RunSqlQueryOutput> = {
+  name: "run_sql_query",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<RunSqlQueryOutput> {
+    if (!isReadOnlySql(input.sql)) {
+      throw new SqlReadOnlyViolation(input.sql);
+    }
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["run_sql_query"];
+      if (mock) return mock(input) as RunSqlQueryOutput;
+      return { rows: [], rowCount: 0 };
+    }
+    return withSkillSpan("run_sql_query", async () => {
+      const result = await ctx.db.query<object>(input.sql, input.params);
+      return {
+        rows: result.rows,
+        rowCount: result.rowCount ?? result.rows.length,
+      };
+    });
+  },
+};

package/src/skills/send-email.ts

@@ -0,0 +1,111 @@
+/**
+ * send_email — SMTP via SMTP_URL OR Resend API key (whichever set).
+ *
+ * SDK does NOT pull nodemailer. SMTP_URL takes precedence ONLY if a
+ * dynamically-imported `nodemailer` is available; else falls back to
+ * Resend HTTP API. Choose one path at deploy time.
+ *
+ * @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({
+    to: z.string().email(),
+    from: z.string().email().optional(),
+    subject: z.string().min(1).max(998),
+    text: z.string().min(1),
+    html: z.string().optional(),
+  })
+  .strict();
+type SendEmailInput = z.infer<typeof inputSchema>;
+
+export interface SendEmailOutput {
+  delivered: boolean;
+  provider: "smtp" | "resend" | "replay";
+  message_id: string | null;
+}
+
+export const sendEmail: Skill<SendEmailInput, SendEmailOutput> = {
+  name: "send_email",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<SendEmailOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["send_email"];
+      if (mock) return mock(input) as SendEmailOutput;
+      return { delivered: false, provider: "replay", message_id: null };
+    }
+    return withSkillSpan("send_email", async () => {
+      const resendKey = process.env.RESEND_API_KEY;
+      const smtpUrl = process.env.SMTP_URL;
+      const defaultFrom = process.env.EMAIL_FROM ?? input.from;
+      if (!resendKey && !smtpUrl) {
+        throw new SkillNotConfiguredError("send_email", [
+          "RESEND_API_KEY",
+          "SMTP_URL",
+        ]);
+      }
+      if (!defaultFrom) {
+        throw new SkillNotConfiguredError("send_email", [
+          "EMAIL_FROM (or input.from)",
+        ]);
+      }
+      // Prefer Resend (HTTP) — no native dep.
+      if (resendKey) {
+        const res = await fetch("https://api.resend.com/emails", {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${resendKey}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            from: defaultFrom,
+            to: [input.to],
+            subject: input.subject,
+            text: input.text,
+            html: input.html,
+          }),
+        });
+        if (!res.ok) {
+          throw new SkillExecutionError("send_email", `resend ${res.status}`, {
+            status: res.status,
+          });
+        }
+        const data = (await res.json()) as { id?: string };
+        return {
+          delivered: true,
+          provider: "resend",
+          message_id: data.id ?? null,
+        };
+      }
+      // SMTP via dynamic import — host must add nodemailer if used.
+      try {
+        const mod = (await import(/* @vite-ignore */ "nodemailer")) as {
+          createTransport: (url: string) => {
+            sendMail: (opts: object) => Promise<{ messageId?: string }>;
+          };
+        };
+        const transport = mod.createTransport(smtpUrl as string);
+        const info = await transport.sendMail({
+          from: defaultFrom,
+          to: input.to,
+          subject: input.subject,
+          text: input.text,
+          html: input.html,
+        });
+        return {
+          delivered: true,
+          provider: "smtp",
+          message_id: info.messageId ?? null,
+        };
+      } catch (err) {
+        throw new SkillExecutionError("send_email", "smtp transport error", {
+          cause: err,
+        });
+      }
+    });
+  },
+};

package/src/skills/skill-ledger.ts

@@ -0,0 +1,92 @@
+/**
+ * Skill Ledger — types + resolver for persisted winning strategies.
+ *
+ * SkillLedgerEntry mirrors the `skill_ledger` DB schema (migration 028).
+ * resolveSkillsForAgent implements LIFO scope-typed resolution:
+ *   1. Match by agent_id (exact) OR agent_id='*' (cross-agent wildcard)
+ *   2. Match outcome_type
+ *   3. lifecycle_state === 'active'
+ *   4. Sort descending by created_at (LIFO — most recent wins)
+ *
+ * @public
+ * Ref: command-center:sprint-530:quick-4
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type SkillLifecycleState = "active" | "archived" | "deprecated";
+
+export interface SkillLedgerEntry {
+  /** UUID primary key */
+  id: string;
+  /** Human-readable skill name (e.g. "kelly_cap_0.12_conviction_gt_0.8") */
+  skill_name: string;
+  /** SHA-256 of the skill payload — deduplication key */
+  skill_sha256: string;
+  /** Run IDs from which this skill was extracted */
+  source_run_ids: string[];
+  /**
+   * Agent that owns this skill.
+   * '*' means promoted cross-agent (available to all agents with matching outcome_type).
+   */
+  agent_id: string;
+  /** Outcome type this skill applies to (e.g. "trade_signal", "risk_report") */
+  outcome_type: string;
+  /** Brain entry ID where the skill rationale is archived */
+  brain_entry_id: string;
+  /** Arbitrary performance / quality metrics */
+  metrics: Record<string, unknown>;
+  lifecycle_state: SkillLifecycleState;
+  created_at: string; // ISO-8601
+}
+
+// ─── Resolver options ─────────────────────────────────────────────────────────
+
+export interface ResolveSkillsOptions {
+  /** Agent ID to resolve for (exact match OR '*' wildcard entries). */
+  agentId: string;
+  /** Outcome type filter (exact match). */
+  outcomeType: string;
+  /**
+   * Maximum number of skills to return.
+   * Defaults to all matching entries (LIFO ordered).
+   */
+  limit?: number;
+}
+
+// ─── Resolver ─────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve skills for a given agent + outcome type.
+ *
+ * LIFO scope-typed algorithm:
+ *   - Include entries where `agent_id === agentId` OR `agent_id === '*'`
+ *   - Include entries where `outcome_type === outcomeType`
+ *   - Include entries where `lifecycle_state === 'active'`
+ *   - Sort descending by `created_at` (most recent first)
+ *   - Apply optional `limit`
+ *
+ * Pure function — no side effects.
+ */
+export function resolveSkillsForAgent(
+  skills: readonly SkillLedgerEntry[],
+  opts: ResolveSkillsOptions,
+): SkillLedgerEntry[] {
+  const { agentId, outcomeType, limit } = opts;
+
+  const filtered = skills.filter(
+    (s) =>
+      (s.agent_id === agentId || s.agent_id === "*") &&
+      s.outcome_type === outcomeType &&
+      s.lifecycle_state === "active",
+  );
+
+  // LIFO: most recent created_at first
+  filtered.sort((a, b) => {
+    const ta = new Date(a.created_at).getTime();
+    const tb = new Date(b.created_at).getTime();
+    return tb - ta;
+  });
+
+  return limit !== undefined ? filtered.slice(0, limit) : filtered;
+}

package/src/skills/skill-registry-builder.ts

@@ -0,0 +1,264 @@
+/**
+ * SkillRegistryBuilder — generic skill assembly for OODA agent consumers.
+ *
+ * Promoted from `forge/src/agents/shared/skill-registry-builder.ts` (sprint-616:quick-3).
+ * Replaces 9 quasi-identical `buildXxxSkills()` functions in Forge with a single
+ * `buildSkills({ agentId, domain, extras })` factory.
+ *
+ * Pattern: base skills (universal) + domain extras (least privilege per agent).
+ *
+ * @public @since 0.18.0
+ */
+
+import { z } from "zod";
+import { brainStore } from "./brain-store.js";
+import { brainQuery } from "./brain-query.js";
+import { slackNotify } from "./slack-notify.js";
+import { httpFetch } from "./http-fetch.js";
+import type { Skill, SkillRegistry } from "../orchestration/ooda/skills.js";
+import type { BrainPort } from "../ports/brain.js";
+import type { LoggerPort } from "../ports/logger.js";
+import { BASE_SKILL_NAMES } from "./base-skills.js";
+import type { DomainSkillEntry } from "./base-skills.js";
+
+// ─── Public Types ──────────────────────────────────────────────────────────────
+
+/**
+ * Dependencies injected at skill construction time.
+ * Matches Forge's `SkillBuilderDeps` / `SkillDeps` — unified here.
+ */
+export interface SkillBuilderDeps {
+  /** Brain memory port for brain-query / brain-store skills. */
+  readonly brain?: BrainPort;
+  /** Logger for debug / audit trails inside skills. */
+  readonly logger: LoggerPort;
+  /** Slack webhook URL for slack-notify. Optional. */
+  readonly slackWebhookUrl?: string;
+  /** LiteLLM base URL for llm-complete. Optional. */
+  readonly litellmUrl?: string;
+  /** LiteLLM API key for llm-complete. Optional. */
+  readonly litellmApiKey?: string;
+}
+
+/**
+ * Options for `buildSkills`.
+ */
+export interface BuildSkillsOptions {
+  /** Agent identifier (used for debug traces and schema validation). */
+  readonly agentId: string;
+  /** Resolved dependencies at construction time. */
+  readonly deps: SkillBuilderDeps;
+  /**
+   * Domain name (e.g. "revenue", "ops", "product").
+   * Used for documentation + future audit trail.
+   */
+  readonly domain: string;
+  /**
+   * Extra skills to merge on top of the base registry.
+   * These must be domain-specific (e.g. prometheus-query, telegram-notify).
+   * Duplicates against base skills are rejected at validation time.
+   */
+  readonly extras?: DomainSkillEntry[];
+}
+
+/**
+ * Assembled skill registry, split for audit + introspection.
+ */
+export interface SkillRegistryBundle {
+  /** The merged SkillRegistry (base + extras), ready for OODA phase injection. */
+  registry: SkillRegistry;
+  /** Names of the base skills always included. */
+  baseNames: readonly string[];
+  /** Names of the domain extras merged in. */
+  extraNames: readonly string[];
+}
+
+// ─── Zod validation schema ────────────────────────────────────────────────────
+// NOTE: `deps` is intentionally excluded from this schema — it contains complex
+// runtime objects (BrainPort, LoggerPort) that are not Zod-serializable.
+// We validate only the primitive + serializable fields.
+
+const buildSkillsOptionsSchema = z.object({
+  agentId: z.string().min(1),
+  domain: z.string().min(1),
+  extras: z
+    .array(
+      z.object({
+        name: z.string().min(1),
+        skill: z.unknown(),
+      })
+    )
+    .optional(),
+});
+
+// ─── llm-complete factory ─────────────────────────────────────────────────────
+
+/**
+ * Build the `llm-complete` skill bound to the provided LiteLLM config.
+ * Produces a Skill that calls the LiteLLM `/v1/chat/completions` endpoint.
+ *
+ * Defined inline rather than a separate file to keep the bound config local.
+ */
+function buildLlmCompleteSkill(deps: SkillBuilderDeps): Skill {
+  type LlmInput = {
+    systemPrompt: string;
+    userPrompt: string;
+    model?: string;
+    maxTokens?: number;
+  };
+  type LlmOutput = { content: string; raw: unknown };
+
+  const inputSchema = z
+    .object({
+      systemPrompt: z.string(),
+      userPrompt: z.string(),
+      model: z.string().optional(),
+      maxTokens: z.number().int().positive().optional(),
+    })
+    .strict();
+
+  return {
+    name: "llm-complete",
+    inputSchema,
+    async execute(input: LlmInput, ctx): Promise<LlmOutput> {
+      if (ctx.isReplay) {
+        const mock = ctx.dryRunMocks["llm-complete"];
+        if (mock) return mock(input) as LlmOutput;
+        return { content: "", raw: { replay: true } };
+      }
+      const litellmUrl = deps.litellmUrl ?? process.env["LITELLM_URL"];
+      const apiKey =
+        deps.litellmApiKey ?? process.env["LITELLM_API_KEY"] ?? "sk-sdk";
+      if (!litellmUrl) {
+        deps.logger.warn?.(
+          { skill: "llm-complete" },
+          "LITELLM_URL not configured"
+        );
+        return { content: "", raw: { error: "LITELLM_URL not configured" } };
+      }
+      try {
+        const res = await fetch(`${litellmUrl}/v1/chat/completions`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            model: input.model ?? "forge-orient",
+            messages: [
+              { role: "system", content: input.systemPrompt },
+              { role: "user", content: input.userPrompt },
+            ],
+            max_tokens: input.maxTokens ?? 1024,
+            temperature: 0.3,
+          }),
+        });
+        const data = (await res.json()) as {
+          choices?: Array<{ message?: { content?: string } }>;
+        };
+        const content = data.choices?.[0]?.message?.content ?? "";
+        if (!content) {
+          deps.logger.error?.(
+            { skill: "llm-complete", data },
+            "empty response content"
+          );
+        }
+        return { content, raw: data };
+      } catch (err) {
+        deps.logger.error?.({ skill: "llm-complete", err }, "fetch failed");
+        return { content: "", raw: { error: String(err) } };
+      }
+    },
+  } satisfies Skill;
+}
+
+// ─── Main factory ─────────────────────────────────────────────────────────────
+
+/**
+ * Build a SkillRegistry for an agent.
+ *
+ * Base skills (always included): brain-store, brain-query, slack-notify, llm-complete.
+ * Domain extras are merged on top — Zod validation prevents duplicate IDs.
+ *
+ * @example
+ * ```ts
+ * const { registry } = buildSkills({
+ *   agentId: "forge-revenue",
+ *   deps,
+ *   domain: "revenue",
+ *   extras: [{ name: "http-fetch", skill: httpFetch }],
+ * });
+ * ```
+ *
+ * @throws {z.ZodError} if options fail validation
+ * @throws {Error} if extras contain a skill ID that collides with a base skill name
+ */
+export function buildSkills(opts: BuildSkillsOptions): SkillRegistryBundle {
+  // Validate serializable fields only (deps excluded — contains non-serializable ports)
+  buildSkillsOptionsSchema.parse({
+    agentId: opts.agentId,
+    domain: opts.domain,
+    extras: opts.extras,
+  });
+
+  const { deps, extras = [] } = opts;
+
+  // Check for duplicate IDs (extras must not shadow base skills)
+  const baseName = new Set<string>(BASE_SKILL_NAMES);
+  for (const { name } of extras) {
+    if (baseName.has(name)) {
+      throw new Error(
+        `buildSkills: extra skill "${name}" collides with a base skill name. ` +
+          `Base skills: ${[...baseName].join(", ")}. ` +
+          `To override a base skill, use a different name or extend the registry manually.`
+      );
+    }
+  }
+
+  // Check for duplicate extra names
+  const extraNames = extras.map((e) => e.name);
+  const uniqueExtras = new Set(extraNames);
+  if (uniqueExtras.size !== extraNames.length) {
+    const seen = new Set<string>();
+    const dupes: string[] = [];
+    for (const n of extraNames) {
+      if (seen.has(n)) dupes.push(n);
+      else seen.add(n);
+    }
+    throw new Error(
+      `buildSkills: duplicate extra skill IDs detected: ${dupes.join(", ")}`
+    );
+  }
+
+  // Assemble base registry
+  const base: SkillRegistry = {
+    "brain-store": brainStore,
+    "brain-query": brainQuery,
+    "slack-notify": slackNotify,
+    "llm-complete": buildLlmCompleteSkill(deps),
+  };
+
+  // Merge extras
+  const registry: SkillRegistry = { ...base };
+  for (const { name, skill } of extras) {
+    registry[name] = skill;
+  }
+
+  return {
+    registry,
+    baseNames: [...BASE_SKILL_NAMES],
+    extraNames,
+  };
+}
+
+/**
+ * Convenience: extract just the SkillRegistry from `buildSkills`.
+ * Identical to `buildSkills(opts).registry`.
+ */
+export function buildSkillRegistry(opts: BuildSkillsOptions): SkillRegistry {
+  return buildSkills(opts).registry;
+}
+
+// Re-export for convenience
+export { httpFetch };
+export type { DomainSkillEntry };