@lunora/agent 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/telemetry/index.d.mts

@@ -1,36 +1,41 @@
 import { Telemetry } from 'ai';
 /**
-* Privacy options shared by every telemetry integration in this package.
-*
-* Both flags default to **FALSE**. Without an explicit opt-in, no prompt,
-* message, tool input, generated model text, or tool output is ever forwarded
-* to a downstream tracer — only structural metadata (model id, finish reason,
-* token counts, tool name, timing, success/failure) is recorded. This is the
-* privacy-safe default: turn recording on deliberately, per integration.
-*/
+ * Privacy options shared by every telemetry integration in this package.
+ *
+ * Both flags default to **FALSE**. Without an explicit opt-in, no prompt,
+ * message, tool input, generated model text, or tool output is ever forwarded
+ * to a downstream tracer — only structural metadata (model id, finish reason,
+ * token counts, tool name, timing, success/failure) is recorded. This is the
+ * privacy-safe default: turn recording on deliberately, per integration.
+ * @experimental
+ */
 interface CommonOptions {
   /**
-  * When `true`, record model/tool **input** — prompts, messages, and tool
-  * call arguments. Default `false`.
-  */
+   * When `true`, record model/tool **input** — prompts, messages, and tool
+   * call arguments. Default `false`.
+   */
   recordInputs?: boolean;
   /**
-  * When `true`, record model/tool **output** — generated text and tool
-  * results. Default `false`.
-  */
+   * When `true`, record model/tool **output** — generated text and tool
+   * results. Default `false`.
+   */
   recordOutputs?: boolean;
 }
-/** The span handle a {@link BraintrustLike.traced} callback receives. */
+/**
+ * The span handle a {@link BraintrustLike.traced} callback receives.
+ * @experimental
+ */
 interface BraintrustSpan {
   /** Attach structured fields to the current span. */
   log: (event: Record<string, unknown>) => void;
 }
 /**
-* The minimal, **structural** slice of the `braintrust` SDK this bridge needs.
-* `braintrust` is intentionally **not** a dependency — the app passes its own
-* initialized logger, so this package stays dependency-free and works with any
-* compatible Braintrust SDK version.
-*/
+ * The minimal, **structural** slice of the `braintrust` SDK this bridge needs.
+ * `braintrust` is intentionally **not** a dependency — the app passes its own
+ * initialized logger, so this package stays dependency-free and works with any
+ * compatible Braintrust SDK version.
+ * @experimental
+ */
 interface BraintrustLike {
   /** Run `callback` inside a new traced span and return its result. */
   traced: <T>(callback: (span: BraintrustSpan) => T, args?: {
@@ -38,79 +43,174 @@ interface BraintrustLike {
     type?: string;
   }) => T;
 }
-/** Options for {@link braintrustTelemetry}. */
+/**
+ * Options for {@link braintrustTelemetry}.
+ * @experimental
+ */
 interface BraintrustTelemetryOptions extends CommonOptions {
   /** Span-name prefix for the language-model call (e.g. the agent name). */
   functionId?: string;
   /**
-  * The caller's initialized Braintrust logger (dependency-injected). Import
-  * and initialize `braintrust` in your app and pass it as `logger`.
-  */
+   * The caller's initialized Braintrust logger (dependency-injected). Import
+   * and initialize `braintrust` in your app and pass it as `logger`.
+   */
   logger: BraintrustLike;
 }
 /**
-* A dependency-injected Braintrust bridge for the ai@7 telemetry surface.
-*
-* It wraps model calls (`type: "llm"`) and tool executions (`type: "tool"`) in
-* `logger.traced` spans and logs structural metadata. Prompts / tool arguments
-* are logged only when `recordInputs` is set; generated text / tool results
-* only when `recordOutputs` is set. `onError` opens a span and logs the error.
-*
-* The app owns Braintrust initialization; pass the logger in as `logger`.
-*/
+ * A dependency-injected Braintrust bridge for the ai@7 telemetry surface.
+ *
+ * It wraps model calls (`type: "llm"`) and tool executions (`type: "tool"`) in
+ * `logger.traced` spans and logs structural metadata. Prompts / tool arguments
+ * are logged only when `recordInputs` is set; generated text / tool results
+ * only when `recordOutputs` is set. `onError` opens a span and logs the error.
+ *
+ * The app owns Braintrust initialization; pass the logger in as `logger`.
+ * @experimental
+ */
 declare const braintrustTelemetry: (options: BraintrustTelemetryOptions) => Telemetry;
 /**
-* Combine several {@link Telemetry} integrations into a single one that fans
-* every lifecycle callback out to all of them and nests the two execution
-* wrappers so multiple span-context wrappers compose correctly.
-*
-* Value callbacks (`onStart`, `onStepEnd`, `onToolExecutionEnd`, …) invoke each
-* integration's matching callback (guarding `undefined`) and await them all in
-* parallel. The wrappers (`executeLanguageModelCall`, `executeTool`) are
-* composed by nesting right-to-left; integrations without a wrapper are skipped,
-* and with none defined the plain `execute` still runs.
-*/
+ * Combine several {@link Telemetry} integrations into a single one that fans
+ * every lifecycle callback out to all of them and nests the two execution
+ * wrappers so multiple span-context wrappers compose correctly.
+ *
+ * Value callbacks (`onStart`, `onStepEnd`, `onToolExecutionEnd`, …) invoke each
+ * integration's matching callback (guarding `undefined`) and await them all in
+ * parallel. The wrappers (`executeLanguageModelCall`, `executeTool`) are
+ * composed by nesting right-to-left; integrations without a wrapper are skipped,
+ * and with none defined the plain `execute` still runs.
+ * @experimental
+ */
 declare const combineTelemetry: (...integrations: Telemetry[]) => Telemetry;
-/** Severity level passed to a {@link ConsoleLogger}. */
+/**
+ * Severity level passed to a {@link ConsoleLogger}.
+ * @experimental
+ */
 type ConsoleLogLevel = "error" | "info" | "warn";
 /**
-* Structured log sink. Receives a level, a static human message, and a bag of
-* structured fields (never interpolated into the message, so log processors can
-* index them). The default sink writes to `globalThis.console`.
-*/
+ * Structured log sink. Receives a level, a static human message, and a bag of
+ * structured fields (never interpolated into the message, so log processors can
+ * index them). The default sink writes to `globalThis.console`.
+ * @experimental
+ */
 type ConsoleLogger = (level: ConsoleLogLevel, message: string, fields: Record<string, unknown>) => void;
-/** Options for {@link consoleTelemetry}. */
+/**
+ * Options for {@link consoleTelemetry}.
+ * @experimental
+ */
 interface ConsoleTelemetryOptions extends CommonOptions {
   /**
-  * Identifier prefixed into every log message (e.g. the agent name). Helps
-  * correlate lines when several agents share one process. Optional.
-  */
+   * Identifier prefixed into every log message (e.g. the agent name). Helps
+   * correlate lines when several agents share one process. Optional.
+   */
   functionId?: string;
   /**
-  * Sink for structured log lines. Defaults to a `globalThis.console`-backed
-  * writer that routes `info`/`warn`/`error` to the matching console method.
-  */
+   * Sink for structured log lines. Defaults to a `globalThis.console`-backed
+   * writer that routes `info`/`warn`/`error` to the matching console method.
+   */
   logger?: ConsoleLogger;
 }
 /**
-* A zero-dependency structured tracer for the ai@7 telemetry surface.
-*
-* It maps the generation lifecycle onto {@link ConsoleLogger} calls: operation
-* start/end, per-step start/end, model-call end (model + finish reason +
-* usage), and tool start/end (name, success, timing). By default it records
-* **only structural metadata** — set `recordInputs` to also log prompts / tool
-* arguments, and `recordOutputs` to log generated text / tool results.
-*
-* Every callback is defensive (event fields may be absent) and synchronous.
-*/
+ * A zero-dependency structured tracer for the ai@7 telemetry surface.
+ *
+ * It maps the generation lifecycle onto {@link ConsoleLogger} calls: operation
+ * start/end, per-step start/end, model-call end (model + finish reason +
+ * usage), and tool start/end (name, success, timing). By default it records
+ * **only structural metadata** — set `recordInputs` to also log prompts / tool
+ * arguments, and `recordOutputs` to log generated text / tool results.
+ *
+ * Every callback is defensive (event fields may be absent) and synchronous.
+ * @experimental
+ */
 declare const consoleTelemetry: (options?: ConsoleTelemetryOptions) => Telemetry;
 /**
-* The minimal, **structural** slice of `@sentry/cloudflare` (equivalently
-* `@sentry/node`/`@sentry/browser`) this bridge needs. `@sentry/cloudflare` is
-* intentionally **not** a dependency — the app passes its own already-initialized
-* Sentry namespace, so this package stays dependency-free and works with any
-* compatible Sentry SDK version.
-*/
+ * Options for {@link otlpTelemetry}.
+ * @experimental
+ */
+interface OtlpTelemetryOptions extends CommonOptions {
+  /**
+   * Conversation / session id to tag each generation span with, emitted as the
+   * `gen_ai.conversation.id` semantic-convention attribute so a multi-turn
+   * conversation's model turns group in the trace store. On a deployed agent the
+   * platform wiring passes the run's `threadKey` here automatically (one thread =
+   * one conversation). Omitted → the attribute is absent (backward-compatible),
+   * and each turn's span is ungrouped.
+   */
+  conversationId?: string;
+  /**
+   * The OTLP-over-HTTP collector base endpoint (e.g. the Lunora Cloud's `/v1`
+   * base). Spans are POSTed to `${endpoint}/v1/traces`; a trailing slash is
+   * tolerated. On the platform this is the injected `LUNORA_OTLP_ENDPOINT`.
+   */
+  endpoint: string;
+  /**
+   * Extra headers merged onto every POST — typically the correlation headers
+   * the platform injects. `Content-Type: application/json` is set by default.
+   */
+  headers?: Record<string, string>;
+  /** `service.name` resource attribute on every span. Defaults to `lunora`. */
+  serviceName?: string;
+  /**
+   * Bearer token added as `Authorization: Bearer` (wins over any authorization
+   * in `headers`) — the injected `LUNORA_OTLP_TOKEN`. Omit for an
+   * unauthenticated collector.
+   */
+  token?: string;
+  /**
+   * Trace id (32-hex) to hang every span of this run under, so one agent run
+   * reads as one trace. Pass a stable id derived from the run (e.g. the
+   * workflow run id). Omitted → each span mints its own trace id (still valid,
+   * just ungrouped).
+   */
+  traceId?: string;
+  /**
+   * The Worker request's `waitUntil`, so a fire-and-forget export survives
+   * isolate teardown after the turn returns. Omit and the send degrades to
+   * best-effort.
+   */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * An OTLP-over-HTTP telemetry integration for `@lunora/agent`.
+ *
+ * The OTLP counterpart to the `sentryTelemetry` / `braintrustTelemetry` bridges:
+ * it wraps each language-model call and tool execution in an OTLP **span**
+ * (`gen_ai.*` semantic-convention attributes — model, provider, token usage,
+ * tool name) and ships it to a collector, so agent generations land in the same
+ * trace store as the rest of an app's telemetry (the Lunora Cloud, or any OTel
+ * collector). Plug it into `defineAgent({ telemetry: { isEnabled: true,
+ * integrations: [otlpTelemetry({ endpoint, token })] } })`.
+ *
+ * Emitting inside the turn's execution wrapper means one span per **real** turn:
+ * the agent loop memoizes each `step.do('llm:turn:N')`, so a Workflow replay
+ * returns the cached result without re-invoking `execute`, and no duplicate span
+ * is emitted. Privacy-safe by default — `recordInputs`/`recordOutputs` both
+ * default `false`, so no prompt or generated text leaves the worker without an
+ * explicit opt-in; only structural metadata + token counts are recorded.
+ *
+ * Each export is fire-and-forget (registered with `waitUntil` when supplied);
+ * every rejection is swallowed so a flaky collector never surfaces to the run.
+ *
+ * Two deliberate differences from the SDK-backed bridges, which delegate to a
+ * host tracer. First, no `onError`: a failed call already emits a span with
+ * `status.code === 2`, so the failure is on the trace and there is no host client
+ * to also notify. Second, flat not nested: every span gets `traceId` (shared when
+ * `traceId` is set) but no `parentSpanId`, so model-call and tool spans are
+ * siblings under the run rather than a tree — OTLP has no ambient span context to
+ * parent to here.
+ * @param options `endpoint` (+ optional `token`/`headers`/`serviceName`),
+ * `traceId` to group a run's spans, `waitUntil`, and the `recordInputs`/
+ * `recordOutputs` privacy flags.
+ * @experimental
+ */
+declare const otlpTelemetry: (options: OtlpTelemetryOptions) => Telemetry;
+/**
+ * The minimal, **structural** slice of `@sentry/cloudflare` (equivalently
+ * `@sentry/node`/`@sentry/browser`) this bridge needs. `@sentry/cloudflare` is
+ * intentionally **not** a dependency — the app passes its own already-initialized
+ * Sentry namespace, so this package stays dependency-free and works with any
+ * compatible Sentry SDK version.
+ * @experimental
+ */
 interface SentryLike {
   /** Capture a thrown value / exception. */
   captureException: (exception: unknown) => unknown;
@@ -125,26 +225,30 @@ interface SentryLike {
     } | string) => void;
   }) => T) => T;
 }
-/** Options for {@link sentryTelemetry}. */
+/**
+ * Options for {@link sentryTelemetry}.
+ * @experimental
+ */
 interface SentryTelemetryOptions extends CommonOptions {
   /** Span-name prefix for the language-model call (e.g. the agent name). */
   functionId?: string;
   /**
-  * The caller's already-initialized Sentry namespace (dependency-injected).
-  * `import * as Sentry from "@sentry/cloudflare"` and pass it as `Sentry`.
-  */
+   * The caller's already-initialized Sentry namespace (dependency-injected).
+   * `import * as Sentry from "@sentry/cloudflare"` and pass it as `Sentry`.
+   */
   Sentry: SentryLike;
 }
 /**
-* A dependency-injected Sentry bridge for the ai@7 telemetry surface.
-*
-* It wraps model calls and tool executions in Sentry spans (via
-* `Sentry.startSpan`) so nested provider/tool work is correctly parented, and
-* routes `onError` to `Sentry.captureException`. Span attributes carry only
-* structural metadata (model, provider, tool name) unless `recordInputs` is
-* set, in which case prompts / tool arguments are attached too.
-*
-* The app owns Sentry initialization; pass the namespace in as `Sentry`.
-*/
+ * A dependency-injected Sentry bridge for the ai@7 telemetry surface.
+ *
+ * It wraps model calls and tool executions in Sentry spans (via
+ * `Sentry.startSpan`) so nested provider/tool work is correctly parented, and
+ * routes `onError` to `Sentry.captureException`. Span attributes carry only
+ * structural metadata (model, provider, tool name) unless `recordInputs` is
+ * set, in which case prompts / tool arguments are attached too.
+ *
+ * The app owns Sentry initialization; pass the namespace in as `Sentry`.
+ * @experimental
+ */
 declare const sentryTelemetry: (options: SentryTelemetryOptions) => Telemetry;
-export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, sentryTelemetry };
+export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type OtlpTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, otlpTelemetry, sentryTelemetry };