feat(ai): add telemetry interface and registry

[aayush-kapoor]

Background

we needed an interface that could be implemented by telemetry providers for capturing all the data that will be propagated via the callbacks

Summary

• TelemetryHandler : interface to create custom telemetry integrations
• expand-handlers.ts : file turns handlers: [handlerA, handlerB, handlerC] into a single object with one callback per lifecycle event, where each callback fans out to every handler that needs info about that event
• added new option handlers to the telemetry-settings for handlers that receive lifecycle events during generation

Future Work

make the integrations option work behind the scenes, ie without a need for it to be in experimental_telemetry

Checklist

• Tests have been added / updated (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)
• A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
• I have reviewed this pull request (self-review)

[aayush-kapoor]

the dx for the providers using this will be

import type { TelemetryHandler } from 'ai';
import { bindTelemetryHandler } from 'ai';

class DevToolsTelemetryHandler implements TelemetryHandler {
  private runId: string | undefined;
  private stepCounter = 0;
  private stepTimers = new Map<number, number>();

  async onStart(event) {
    ...
  }

  async onStepStart(event) {
    ...
  }

  async onToolCallStart(event) {
    // Log tool invocation to devtools UI
  }

  async onToolCallFinish(event) {
    // Log tool result (or error) with duration
  }

  async onStepFinish(event) {
    ...
  }

  async onFinish(event) {
    // Final summary: total usage, all steps, etc.
  }
}

// the public API - what end users import and pass to `handlers`
export function devToolsHandler(): TelemetryHandler {
  return bindTelemetryHandler(new DevToolsTelemetryHandler());
}

[lgrammel]

wonder if we can use / extract types such as OnStartListener - maybe in follow up prs

[lgrammel]

the global listener would need to be called from generateText and streamText