@vauban-org/agent-sdk 1.7.0 → 1.9.0

package/dist/quality/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * quality/index.ts — Outcome quality scoring (ADR-ECO-039).
+ *
+ * Promoted from forge consumer in SDK 1.8.0 — see Brief 2026-05-17.
+ *
+ * Companion to {@link OutcomeRecord.quality}. Each agent's
+ * `outcomeMapping(feedback)` returns a normalized quality score (0..1)
+ * computed from feedback signals. The Command Center backend reads this
+ * into the `agent_run.outcome_quality` column (NUMERIC(5,4)), which
+ * powers the EconomicObserver ROI weighting and the Quality Foreman
+ * regression checks.
+ *
+ * Design notes:
+ *  - Pure function (no I/O, no SDK imports beyond types) — safe to import
+ *    from any agent and cheap to unit-test.
+ *  - Signals are agent-agnostic — each agent maps its own feedback fields
+ *    into a shared {@link QualityInputs} shape.
+ *  - Default score is `0.5` ("neutral, no information"). Signals nudge it
+ *    up (positive outcomes) or down (errors). Final value is clamped to
+ *    `[0, 1]`.
+ *  - `customScore` lets an agent provide its own pre-computed score (e.g.
+ *    a model-based eval) and bypass the heuristic.
+ *  - Prod-validated on 33 forge agents (ADR-ECO-039 rollout 2026-05).
+ *
+ * @public
+ */
+/**
+ * Feedback signals consumed by {@link computeQuality}. All fields are
+ * optional — pass only the signals the calling agent emits.
+ *
+ * @public
+ */
+export interface QualityInputs {
+    /** Sentinel-style: number of threats blocked (e.g. paused contracts). */
+    readonly threatsBlocked?: number;
+    /** Sentinel/ops-style: alerts sent to operators. */
+    readonly alertsSent?: number;
+    /** Content-style: number of posts/articles successfully published. */
+    readonly postsPublished?: number;
+    /** Content-style: posts blocked by HITL or constitutional gate. */
+    readonly postsRejectedByHITL?: number;
+    /** Finance/treasury-style: invoices or proposals processed successfully. */
+    readonly invoicesProcessed?: number;
+    /** Generic: number of errors encountered during the cycle. */
+    readonly errorsEncountered?: number;
+    /** Lessons / retrospective bullets extracted (proxy for reflection depth). */
+    readonly lessons?: readonly unknown[];
+    /** Explicit override — bypasses the heuristic when defined. */
+    readonly customScore?: number;
+}
+/**
+ * Per-signal contribution to the final score. Returned by
+ * {@link computeQualityWithBreakdown}.
+ *
+ * @public
+ */
+export interface QualityContribution {
+    /** Source signal name (matches a {@link QualityInputs} field). */
+    readonly signal: string;
+    /** Signed delta applied to the running score (positive or negative). */
+    readonly delta: number;
+    /** Human-readable explanation, e.g. `"1 post published"`. */
+    readonly reason: string;
+}
+/**
+ * Breakdown view of {@link computeQuality} — score plus the ordered list of
+ * non-zero contributions. Powers debug-grade observability surfaces
+ * (e.g. `/agents/[id]` quality trend tooltip).
+ *
+ * @public
+ */
+export interface QualityBreakdown {
+    /** Final clamped score in `[0, 1]`. */
+    readonly score: number;
+    /** Contributions in evaluation order. Empty when no signal applies. */
+    readonly contributions: readonly QualityContribution[];
+}
+/**
+ * Compute a 0..1 quality score from agent feedback signals.
+ *
+ * Defaults to `0.5` when no signal is provided. Each positive signal nudges
+ * the score upward; errors and HITL rejections nudge it downward. The
+ * result is clamped to `[0, 1]`.
+ *
+ * @example
+ *   computeQuality({ postsPublished: 1 })          // → 0.7
+ *   computeQuality({ errorsEncountered: 1 })       // → 0.3
+ *   computeQuality({ customScore: 0.95 })          // → 0.95
+ *   computeQuality({})                             // → 0.5
+ *
+ * @public
+ */
+export declare function computeQuality(inputs: QualityInputs): number;
+/**
+ * Same heuristic as {@link computeQuality}, but also returns the ordered
+ * list of non-zero contributions for debug-grade observability.
+ *
+ * When `customScore` is provided, the breakdown contains a single entry
+ * tagged `"customScore"` and the heuristic is bypassed.
+ *
+ * @example
+ *   computeQualityWithBreakdown({ postsPublished: 1, lessons: ["a"] })
+ *   // → {
+ *   //     score: 0.75,
+ *   //     contributions: [
+ *   //       { signal: "postsPublished", delta:  0.2,  reason: "1 post published" },
+ *   //       { signal: "lessons",        delta:  0.05, reason: "1 lesson extracted" },
+ *   //     ],
+ *   //   }
+ *
+ * @public
+ */
+export declare function computeQualityWithBreakdown(inputs: QualityInputs): QualityBreakdown;
+//# sourceMappingURL=index.d.ts.map

package/dist/quality/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/quality/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACxD;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAiB5D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,aAAa,GACpB,gBAAgB,CAyFlB"}

package/dist/quality/index.js

@@ -0,0 +1,168 @@
+/**
+ * quality/index.ts — Outcome quality scoring (ADR-ECO-039).
+ *
+ * Promoted from forge consumer in SDK 1.8.0 — see Brief 2026-05-17.
+ *
+ * Companion to {@link OutcomeRecord.quality}. Each agent's
+ * `outcomeMapping(feedback)` returns a normalized quality score (0..1)
+ * computed from feedback signals. The Command Center backend reads this
+ * into the `agent_run.outcome_quality` column (NUMERIC(5,4)), which
+ * powers the EconomicObserver ROI weighting and the Quality Foreman
+ * regression checks.
+ *
+ * Design notes:
+ *  - Pure function (no I/O, no SDK imports beyond types) — safe to import
+ *    from any agent and cheap to unit-test.
+ *  - Signals are agent-agnostic — each agent maps its own feedback fields
+ *    into a shared {@link QualityInputs} shape.
+ *  - Default score is `0.5` ("neutral, no information"). Signals nudge it
+ *    up (positive outcomes) or down (errors). Final value is clamped to
+ *    `[0, 1]`.
+ *  - `customScore` lets an agent provide its own pre-computed score (e.g.
+ *    a model-based eval) and bypass the heuristic.
+ *  - Prod-validated on 33 forge agents (ADR-ECO-039 rollout 2026-05).
+ *
+ * @public
+ */
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0.5;
+    return Math.max(0, Math.min(1, n));
+}
+/**
+ * Compute a 0..1 quality score from agent feedback signals.
+ *
+ * Defaults to `0.5` when no signal is provided. Each positive signal nudges
+ * the score upward; errors and HITL rejections nudge it downward. The
+ * result is clamped to `[0, 1]`.
+ *
+ * @example
+ *   computeQuality({ postsPublished: 1 })          // → 0.7
+ *   computeQuality({ errorsEncountered: 1 })       // → 0.3
+ *   computeQuality({ customScore: 0.95 })          // → 0.95
+ *   computeQuality({})                             // → 0.5
+ *
+ * @public
+ */
+export function computeQuality(inputs) {
+    if (typeof inputs.customScore === "number") {
+        return clamp01(inputs.customScore);
+    }
+    let q = 0.5;
+    if ((inputs.errorsEncountered ?? 0) > 0)
+        q -= 0.2;
+    if ((inputs.postsRejectedByHITL ?? 0) > 0)
+        q -= 0.1;
+    if ((inputs.postsPublished ?? 0) > 0)
+        q += 0.2;
+    if ((inputs.threatsBlocked ?? 0) > 0)
+        q += 0.3;
+    if ((inputs.alertsSent ?? 0) > 0)
+        q += 0.1;
+    if ((inputs.invoicesProcessed ?? 0) > 0)
+        q += 0.2;
+    if ((inputs.lessons?.length ?? 0) > 0)
+        q += 0.05;
+    return clamp01(q);
+}
+/**
+ * Same heuristic as {@link computeQuality}, but also returns the ordered
+ * list of non-zero contributions for debug-grade observability.
+ *
+ * When `customScore` is provided, the breakdown contains a single entry
+ * tagged `"customScore"` and the heuristic is bypassed.
+ *
+ * @example
+ *   computeQualityWithBreakdown({ postsPublished: 1, lessons: ["a"] })
+ *   // → {
+ *   //     score: 0.75,
+ *   //     contributions: [
+ *   //       { signal: "postsPublished", delta:  0.2,  reason: "1 post published" },
+ *   //       { signal: "lessons",        delta:  0.05, reason: "1 lesson extracted" },
+ *   //     ],
+ *   //   }
+ *
+ * @public
+ */
+export function computeQualityWithBreakdown(inputs) {
+    if (typeof inputs.customScore === "number") {
+        const clamped = clamp01(inputs.customScore);
+        return {
+            score: clamped,
+            contributions: [
+                {
+                    signal: "customScore",
+                    delta: clamped - 0.5,
+                    reason: `customScore override = ${inputs.customScore}`,
+                },
+            ],
+        };
+    }
+    let q = 0.5;
+    const contributions = [];
+    const errors = inputs.errorsEncountered ?? 0;
+    if (errors > 0) {
+        q -= 0.2;
+        contributions.push({
+            signal: "errorsEncountered",
+            delta: -0.2,
+            reason: `${errors} error${errors === 1 ? "" : "s"} encountered`,
+        });
+    }
+    const rejects = inputs.postsRejectedByHITL ?? 0;
+    if (rejects > 0) {
+        q -= 0.1;
+        contributions.push({
+            signal: "postsRejectedByHITL",
+            delta: -0.1,
+            reason: `${rejects} post${rejects === 1 ? "" : "s"} rejected by HITL`,
+        });
+    }
+    const posts = inputs.postsPublished ?? 0;
+    if (posts > 0) {
+        q += 0.2;
+        contributions.push({
+            signal: "postsPublished",
+            delta: 0.2,
+            reason: `${posts} post${posts === 1 ? "" : "s"} published`,
+        });
+    }
+    const threats = inputs.threatsBlocked ?? 0;
+    if (threats > 0) {
+        q += 0.3;
+        contributions.push({
+            signal: "threatsBlocked",
+            delta: 0.3,
+            reason: `${threats} threat${threats === 1 ? "" : "s"} blocked`,
+        });
+    }
+    const alerts = inputs.alertsSent ?? 0;
+    if (alerts > 0) {
+        q += 0.1;
+        contributions.push({
+            signal: "alertsSent",
+            delta: 0.1,
+            reason: `${alerts} alert${alerts === 1 ? "" : "s"} sent`,
+        });
+    }
+    const invoices = inputs.invoicesProcessed ?? 0;
+    if (invoices > 0) {
+        q += 0.2;
+        contributions.push({
+            signal: "invoicesProcessed",
+            delta: 0.2,
+            reason: `${invoices} invoice${invoices === 1 ? "" : "s"} processed`,
+        });
+    }
+    const lessonCount = inputs.lessons?.length ?? 0;
+    if (lessonCount > 0) {
+        q += 0.05;
+        contributions.push({
+            signal: "lessons",
+            delta: 0.05,
+            reason: `${lessonCount} lesson${lessonCount === 1 ? "" : "s"} extracted`,
+        });
+    }
+    return { score: clamp01(q), contributions };
+}
+//# sourceMappingURL=index.js.map

package/dist/quality/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/quality/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vauban-org/agent-sdk",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Vauban agent primitives: loop, budget, routing, HITL, permissions, tracking, durable execution",
   "type": "module",
   "main": "dist/index.js",

package/src/alerts/digest.ts

@@ -0,0 +1,260 @@
+/**
+ * alerts/digest.ts — Adaptive notification batching (SDK 1.9.0).
+ *
+ * Promoted from forge's `src/agents/23-security-auditor/agent.ts`
+ * `buildEscalationMessages()` after a 47-alert Telegram flood during the
+ * first Dependabot-enabled cycle (2026-05-17). Generalized so any agent
+ * dispatching bulk operator alerts (devops, finance, devrel, inbox-monitor,
+ * security-auditor) can adopt it without re-implementing the
+ * threshold/sort/cap logic.
+ *
+ * Design notes:
+ *  - Pure function — no I/O, no transport dependency. Caller dispatches the
+ *    returned strings to Telegram/Slack/email/whatever channel.
+ *  - 0 items → no message at all (empty array).
+ *  - 1..threshold items → one full-detail message per item.
+ *  - More than threshold items → one digest message, sorted by severity
+ *    (configurable order), capped at `maxChars`, with truncation footer +
+ *    optional details pointer.
+ *  - Severities outside the configured order are appended last with a
+ *    default bullet emoji.
+ *
+ * @public
+ */
+
+/**
+ * A single alert item fed to {@link buildAlertDigest}. All fields except
+ * `severity` and `title` are optional — render skips empty lines.
+ *
+ * @public
+ */
+export interface AlertItem {
+  /**
+   * Severity bucket. Built-in semantics: `"critical" | "high" | "medium" |
+   * "low"`. Any other string is accepted and ranked according to
+   * {@link AlertDigestOptions.severityOrder} (or appended last with a
+   * default emoji when not listed).
+   */
+  readonly severity:
+    | "critical"
+    | "high"
+    | "medium"
+    | "low"
+    | (string & Record<never, never>);
+  /** Human-readable headline (rendered after the emoji). */
+  readonly title: string;
+  /** Affected component / repo / file (e.g. `"vauban-org/forge:axios"`). */
+  readonly component?: string;
+  /** External reference (e.g. `"CVE-2026-0001"`). */
+  readonly ref?: string;
+  /** Remediation hint shown in individual messages. */
+  readonly remediation?: string;
+  /** Direct URL for follow-up (shown in individual messages). */
+  readonly url?: string;
+}
+
+/**
+ * Options for {@link buildAlertDigest}. All fields optional with sensible
+ * defaults matching forge's prod-validated security-auditor behaviour.
+ *
+ * @public
+ */
+export interface AlertDigestOptions {
+  /**
+   * Header prefix label (e.g. `"SECURITY"`, `"DEVOPS"`). Default
+   * `"ALERT"`. Appears in the digest header — ignored in per-item mode.
+   */
+  readonly label?: string;
+  /**
+   * Cutoff between per-item and digest modes. `<=` threshold yields N
+   * messages, `>` threshold yields a single digest. Default `3`.
+   */
+  readonly threshold?: number;
+  /**
+   * Hard cap on the rendered digest length (chars). Default `4000`
+   * (Telegram-safe — Telegram limit is 4096).
+   */
+  readonly maxChars?: number;
+  /**
+   * Pointer to detailed source (e.g. `"query Brain category=forge_alert"`).
+   * Appended on a final line of every digest message when provided.
+   */
+  readonly detailsPointer?: string;
+  /**
+   * Severity sort order, highest priority first. Default
+   * `["critical", "high", "medium", "low"]`. Severities not listed go
+   * after listed ones, in input order.
+   */
+  readonly severityOrder?: readonly string[];
+  /**
+   * Per-severity emoji map. Default
+   * `{ critical: "🚨", high: "⚠️", medium: "ℹ️", low: "🔵" }`. Missing
+   * severities fall back to `"•"`.
+   */
+  readonly emojiMap?: Readonly<Record<string, string>>;
+}
+
+const DEFAULT_THRESHOLD = 3;
+const DEFAULT_MAX_CHARS = 4000;
+const DEFAULT_LABEL = "ALERT";
+const DEFAULT_SEVERITY_ORDER: readonly string[] = [
+  "critical",
+  "high",
+  "medium",
+  "low",
+];
+const DEFAULT_EMOJI_MAP: Readonly<Record<string, string>> = {
+  critical: "🚨",
+  high: "⚠️",
+  medium: "ℹ️",
+  low: "🔵",
+};
+const FALLBACK_EMOJI = "•";
+
+function emojiFor(
+  severity: string,
+  map: Readonly<Record<string, string>>
+): string {
+  return map[severity] ?? FALLBACK_EMOJI;
+}
+
+function severityRank(severity: string, order: readonly string[]): number {
+  const idx = order.indexOf(severity);
+  return idx === -1 ? order.length : idx;
+}
+
+function renderIndividual(
+  item: AlertItem,
+  emojiMap: Readonly<Record<string, string>>
+): string {
+  const emoji = emojiFor(item.severity, emojiMap);
+  const ref = item.ref ? ` [${item.ref}]` : "";
+  const lines: string[] = [`${emoji} ${item.title}${ref}`];
+  if (item.component) lines.push(`Component: ${item.component}`);
+  if (item.remediation) lines.push(`Remediation: ${item.remediation}`);
+  if (item.url) lines.push(item.url);
+  return lines.join("\n");
+}
+
+function buildHeader(
+  label: string,
+  total: number,
+  counts: ReadonlyMap<string, number>,
+  order: readonly string[],
+  emojiMap: Readonly<Record<string, string>>
+): string {
+  const breakdown: string[] = [];
+  for (const sev of order) {
+    const c = counts.get(sev) ?? 0;
+    if (c > 0) breakdown.push(`${c} ${sev}`);
+  }
+  const topSev = order.find((s) => (counts.get(s) ?? 0) > 0);
+  const headEmoji = topSev ? emojiFor(topSev, emojiMap) : FALLBACK_EMOJI;
+  const breakdownStr = breakdown.length > 0 ? ` (${breakdown.join(", ")})` : "";
+  return `${headEmoji} ${label} — ${total} items${breakdownStr}`;
+}
+
+/**
+ * Build an adaptive alert digest from a list of items.
+ *
+ * - 0 items → `[]` (no message at all).
+ * - 1..threshold items → one message per item (full detail preserved).
+ * - More than threshold → one digest message, severity-sorted, capped at
+ *   `maxChars`, with truncation footer `"… +K more"` when items overflow,
+ *   followed by `"Details: <detailsPointer>"` when a pointer is provided.
+ *
+ * Header counts only non-zero severities, in the configured order.
+ * Severities not in `severityOrder` are appended last with a default
+ * bullet emoji `"•"` (or a user-provided emoji from `emojiMap`).
+ *
+ * @example
+ *   buildAlertDigest([])                             // → []
+ *   buildAlertDigest([critical, high, low])          // → 3 messages
+ *   buildAlertDigest(arrayOf(50, "high"), {
+ *     label: "DEPENDABOT",
+ *     detailsPointer: "query Brain category=forge_alert tag=security",
+ *   })                                                // → 1 digest message
+ *
+ * @public
+ */
+export function buildAlertDigest(
+  items: readonly AlertItem[],
+  opts: AlertDigestOptions = {}
+): string[] {
+  if (items.length === 0) return [];
+
+  const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+  const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
+  const label = opts.label ?? DEFAULT_LABEL;
+  const severityOrder = opts.severityOrder ?? DEFAULT_SEVERITY_ORDER;
+  const emojiMap = opts.emojiMap ?? DEFAULT_EMOJI_MAP;
+  const detailsPointer = opts.detailsPointer;
+
+  if (items.length <= threshold) {
+    return items.map((it) => renderIndividual(it, emojiMap));
+  }
+
+  // Sort copy: by severityOrder rank, then preserve input order (stable).
+  const sorted = items
+    .map((it, idx) => ({ it, idx }))
+    .sort((a, b) => {
+      const ra = severityRank(a.it.severity, severityOrder);
+      const rb = severityRank(b.it.severity, severityOrder);
+      if (ra !== rb) return ra - rb;
+      return a.idx - b.idx;
+    })
+    .map((x) => x.it);
+
+  const counts = new Map<string, number>();
+  for (const it of sorted) {
+    counts.set(it.severity, (counts.get(it.severity) ?? 0) + 1);
+  }
+
+  const header = buildHeader(
+    label,
+    items.length,
+    counts,
+    severityOrder,
+    emojiMap
+  );
+  const footerLines: string[] = [];
+  if (detailsPointer) footerLines.push(`Details: ${detailsPointer}`);
+
+  // Compute fixed cost: header + body lines + footer.
+  // We need to leave room for an eventual "… +K more" line.
+  const truncationLineEstimate = 16; // "\n… +999 more"
+  const footerStr = footerLines.length > 0 ? "\n" + footerLines.join("\n") : "";
+
+  const bodyLines: string[] = [];
+  let renderedSoFar = header.length;
+  let truncated = 0;
+
+  for (let i = 0; i < sorted.length; i++) {
+    const it = sorted[i]!;
+    const emoji = emojiFor(it.severity, emojiMap);
+    const ref = it.ref ? ` [${it.ref}]` : "";
+    const line = `${emoji} ${it.title}${ref} — ${it.component ?? "?"}`;
+    // +1 for the leading "\n" before this line
+    const lineCost = 1 + line.length;
+    const remainingItems = sorted.length - i;
+    // If adding this line would prevent us from fitting truncation footer
+    // for the remaining items, stop here.
+    const projected =
+      renderedSoFar +
+      lineCost +
+      footerStr.length +
+      (remainingItems > 1 ? truncationLineEstimate : 0);
+    if (projected > maxChars) {
+      truncated = sorted.length - i;
+      break;
+    }
+    bodyLines.push(line);
+    renderedSoFar += lineCost;
+  }
+
+  const out: string[] = [header, ...bodyLines];
+  if (truncated > 0) out.push(`… +${truncated} more`);
+  if (footerLines.length > 0) out.push(...footerLines);
+
+  return [out.join("\n")];
+}

package/src/alerts/index.ts

@@ -0,0 +1,12 @@
+/**
+ * alerts/ — Adaptive notification batching (SDK 1.9.0).
+ *
+ * Promoted from forge's security-auditor `buildEscalationMessages()`
+ * after the 47-alert Telegram flood (2026-05-17). Pure, transport-agnostic
+ * helper; caller dispatches the returned strings.
+ *
+ * @public
+ */
+
+export { buildAlertDigest } from "./digest.js";
+export type { AlertItem, AlertDigestOptions } from "./digest.js";

package/src/index.ts

@@ -571,6 +571,21 @@ export type {
 // 13. Outcomes module (SDK v0.5.1 — Sprint-522)
 export * from "./outcomes/index.js";
 
+// 13b. Quality scoring helper (SDK 1.8.0 — promoted from forge 2026-05-17)
+export {
+  computeQuality,
+  computeQualityWithBreakdown,
+} from "./quality/index.js";
+export type {
+  QualityInputs,
+  QualityBreakdown,
+  QualityContribution,
+} from "./quality/index.js";
+
+// 13c. Alert digest helper (SDK 1.9.0 — promoted from forge 2026-05-17)
+export { buildAlertDigest } from "./alerts/index.js";
+export type { AlertItem, AlertDigestOptions } from "./alerts/index.js";
+
 // 14. Proof module (SDK v0.5.2 — Sprint-521 Bloc 1)
 // Note: proof/index.js re-exports from @vauban-org/proof-core (optional peerDep).
 // Import via subpath @vauban-org/agent-sdk/proof — do NOT wildcard here.

package/src/orchestration/ooda/types.ts

@@ -232,8 +232,9 @@ export interface OutcomeRecord {
    * the BUSINESS quality of the cycle output (publishedCount, threatsBlocked,
    * invoicesProcessed, etc.). Persisted to `agent_run.outcome_quality` by
    * the CC backend's telemetry-ingest finish handler (SDK 1.6 / ADR-ECO-039).
-   * Use `@vauban-org/forge`'s shared `computeQuality()` helper for consistent
-   * scoring across agents, or override with a custom score.
+   * Use the SDK's `computeQuality()` helper (or `computeQualityWithBreakdown()`
+   * for debug-grade observability) for consistent scoring across agents, or
+   * override with a custom score. See `@vauban-org/agent-sdk` quality module.
    */
   readonly quality?: number;
   readonly is_pending_backfill?: boolean;