feat!: consolidate graph metric summary into LDAIGraphMetricSummary

The managed-layer `AIGraphMetricSummary` and the tracker-layer
`LDAIGraphMetricSummary` were duplicate interfaces describing the same
spec concept (`AIGraphMetricSummary` in AIRUNNER §2.5). Consolidate to
the single `LDAIGraphMetricSummary` (JS LD-prefix convention) and add
`nodeMetrics` so it can carry per-node summaries from
`ManagedAgentGraph.run()`.

Required vs. optional matches the runtime contract:

- `success`, `path`, `nodeMetrics` are required — the managed layer
  sources these from `LDAIGraphMetrics` where they are required, so the
  type now reflects the actual guarantee.
- `durationMs`, `tokens`, `resumptionToken` remain optional — these
  may not be tracked depending on runner.

For `LDGraphTracker.getSummary()`, which populates incrementally as
tracking calls arrive, the return type is now
`Partial<LDAIGraphMetricSummary>` to express the per-call partial state
explicitly. `LDGraphTrackerImpl._summary` is similarly typed.

`AIGraphMetricSummary` is removed; `ManagedGraphResult.metrics` and
`ManagedAgentGraph` now use `LDAIGraphMetricSummary`.

BREAKING CHANGE: `AIGraphMetricSummary` is removed in favour of
`LDAIGraphMetricSummary`. `LDGraphTracker.getSummary()` now returns
`Partial<LDAIGraphMetricSummary>` instead of `LDAIGraphMetricSummary`
to reflect that the tracker accumulates the summary incrementally;
consumers must check optional fields.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jsonbailey

packages/sdk/server-ai/src/LDGraphTrackerImpl.ts

@@ -12,7 +12,7 @@ import type { LDClientMin } from './LDClientMin';
  * {@link LDGraphTrackerImpl.fromResumptionToken}.
  */
 export class LDGraphTrackerImpl implements LDGraphTracker {
-  private _summary: LDAIGraphMetricSummary = {};
+  private _summary: Partial<LDAIGraphMetricSummary> = {};
 
   constructor(
     private readonly _ldClient: LDClientMin,
@@ -67,7 +67,7 @@ export class LDGraphTrackerImpl implements LDGraphTracker {
     };
   }
 
-  getSummary(): LDAIGraphMetricSummary {
+  getSummary(): Partial<LDAIGraphMetricSummary> {
     return { ...this._summary };
   }
 

packages/sdk/server-ai/src/api/graph/LDGraphTracker.ts

@@ -33,9 +33,13 @@ export interface LDGraphTracker {
   };
 
   /**
-   * Returns a snapshot of all graph-level metrics tracked so far.
+   * Returns a snapshot of all graph-level metrics tracked so far. Fields
+   * populate incrementally as `track*` methods are called, so the result is
+   * a `Partial<LDAIGraphMetricSummary>`. Once the graph invocation has
+   * completed via `ManagedAgentGraph.run()`, prefer `ManagedGraphResult.metrics`
+   * which is fully populated.
    */
-  getSummary(): LDAIGraphMetricSummary;
+  getSummary(): Partial<LDAIGraphMetricSummary>;
 
   /**
    * A URL-safe Base64-encoded (RFC 4648, no padding) token encoding the tracker's

packages/sdk/server-ai/src/api/graph/ManagedAgentGraph.ts

@@ -5,15 +5,15 @@ import { LDAIMetricSummary } from '../model/types';
 import { LDJudgeResult } from '../judge/types';
 import { AgentGraphDefinition } from './AgentGraphDefinition';
 import { LDGraphTracker } from './LDGraphTracker';
-import { AgentGraphRunnerResult, GraphMetricSummary, ManagedGraphResult } from './types';
+import { AgentGraphRunnerResult, LDAIGraphMetricSummary, ManagedGraphResult } from './types';
 
 /**
  * ManagedAgentGraph wraps an AgentGraphDefinition and provides a managed run()
  * method that returns ManagedGraphResult with async judge evaluations.
  *
  * The runner function is responsible for executing the graph and returning
  * an AgentGraphRunnerResult. ManagedAgentGraph builds the managed result from
- * the runner result, including GraphMetricSummary with the graphTracker's
+ * the runner result, including LDAIGraphMetricSummary with the graphTracker's
  * resumptionToken.
  */
 export class ManagedAgentGraph {
@@ -31,7 +31,7 @@ export class ManagedAgentGraph {
    * run() returns before ManagedGraphResult.evaluations resolves.
    *
    * @param runner Async function that executes the graph and returns AgentGraphRunnerResult.
-   * @returns ManagedGraphResult with GraphMetricSummary and evaluations promise.
+   * @returns ManagedGraphResult with LDAIGraphMetricSummary and evaluations promise.
    */
   async run(
     runner: (
@@ -43,7 +43,7 @@ export class ManagedAgentGraph {
 
     const runnerResult = await runner(this._graphDefinition, graphTracker);
 
-    const metrics: GraphMetricSummary = {
+    const metrics: LDAIGraphMetricSummary = {
       success: runnerResult.metrics.success,
       path: runnerResult.metrics.path,
       durationMs: runnerResult.metrics.durationMs,

packages/sdk/server-ai/src/api/graph/types.ts

@@ -40,28 +40,38 @@ export interface LDAgentGraphFlagValue {
 }
 
 /**
- * Accumulated graph-level metrics collected by an LDGraphTracker.
+ * Summarized graph-level metrics for a completed graph invocation, as
+ * returned by {@link ManagedAgentGraph.run} via {@link ManagedGraphResult.metrics}.
+ *
+ * For the tracker-layer incremental view (where fields populate as tracking
+ * calls arrive), see {@link LDGraphTracker.getSummary}, which returns a
+ * `Partial<LDAIGraphMetricSummary>`.
  */
 export interface LDAIGraphMetricSummary {
   /**
-   * Whether the graph invocation succeeded. Absent if not yet tracked.
+   * Whether the graph invocation succeeded.
    */
-  success?: boolean;
+  success: boolean;
 
   /**
-   * Total graph execution duration in milliseconds. Absent if not yet tracked.
+   * Execution path through the graph as an ordered array of config keys.
    */
-  durationMs?: number;
+  path: string[];
+
+  /**
+   * Per-node metric summaries keyed by agent config key.
+   */
+  nodeMetrics: Record<string, LDAIMetricSummary>;
 
   /**
-   * Aggregate token usage across the entire graph invocation. Absent if not yet tracked.
+   * Total graph execution duration in milliseconds, if tracked.
    */
-  tokens?: LDTokenUsage;
+  durationMs?: number;
 
   /**
-   * Execution path through the graph as an array of config keys. Absent if not yet tracked.
+   * Aggregate token usage across the entire graph invocation, if available.
    */
-  path?: string[];
+  tokens?: LDTokenUsage;
 
   /**
    * Resumption token for deferred feedback association.
@@ -125,42 +135,6 @@ export interface AgentGraphRunnerResult {
 // Managed-Layer Graph Types
 // ============================================================================
 
-/**
- * Graph metric summary returned in ManagedGraphResult.
- * Includes per-node metrics and a resumption token.
- */
-export interface GraphMetricSummary {
-  /**
-   * Whether the graph invocation succeeded.
-   */
-  success: boolean;
-
-  /**
-   * Execution path through the graph as an ordered array of config keys.
-   */
-  path: string[];
-
-  /**
-   * Total graph execution duration in milliseconds, if tracked.
-   */
-  durationMs?: number;
-
-  /**
-   * Aggregate token usage across the entire graph invocation, if available.
-   */
-  tokens?: LDTokenUsage;
-
-  /**
-   * Per-node metric summaries keyed by agent config key.
-   */
-  nodeMetrics: Record<string, LDAIMetricSummary>;
-
-  /**
-   * Resumption token for deferred feedback association.
-   */
-  resumptionToken?: string;
-}
-
 /**
  * The result returned by a managed graph invocation (ManagedAgentGraph.run()).
  */
@@ -173,7 +147,7 @@ export interface ManagedGraphResult {
   /**
    * Summarized metrics for this graph invocation.
    */
-  metrics: GraphMetricSummary;
+  metrics: LDAIGraphMetricSummary;
 
   /**
    * The raw response object from the provider, if available.