@dbx-tools/appkit-mastra 0.1.67 → 0.1.68

package/src/memory.ts

@@ -1,293 +0,0 @@
-/**
- * Lakebase-backed Mastra memory wiring.
- *
- * Provides a {@link MemoryBuilder} that mints one `Memory` per agent
- * with two independent knobs:
- *
- * - **Storage** (threads / messages via `PostgresStore`): defaults to
- *   **per-agent** namespacing via `schemaName: "mastra_<agentId>"` so
- *   conversation history stays isolated between agents in the same
- *   database. `PostgresStore` auto-creates the schema with
- *   `CREATE SCHEMA IF NOT EXISTS` on init.
- * - **Memory** (semantic recall via `PgVector`): defaults to a single
- *   **shared** instance across every agent. Cross-agent recall on one
- *   index is almost always what users want; opt into per-agent recall
- *   by passing a {@link MastraMemoryConfigOverride} on the agent.
- *
- * Additionally, {@link MemoryBuilder.instanceStorage} returns a
- * **Mastra-instance-level** `PostgresStore` (schema `mastra_instance`)
- * used for workflow snapshots - the persistence layer
- * `agent.resumeStream()` reads from when waking a suspended
- * `requireApproval` tool call. Per-agent stores are not enough for
- * this: workflow runs are scoped to the Mastra instance, not an
- * individual agent's `Memory`.
- *
- * Plugin-level `config.storage` / `config.memory` act as the baseline
- * (auto-defaulted to `true` in `plugin.ts` when the `lakebase` plugin
- * is registered); per-agent settings cascade on top of that.
- */
-
-import { getUsernameWithApiLookup } from "@databricks/appkit";
-import { logUtils } from "@dbx-tools/shared";
-import { fastembed } from "@mastra/fastembed";
-import { Memory } from "@mastra/memory";
-import { PgVector, PostgresStore } from "@mastra/pg";
-import { randomUUID } from "node:crypto";
-import { Pool, type PoolConfig } from "pg";
-
-import type { MastraAgentDefinition, MastraMemoryConfigOverride } from "./agents.js";
-import type { MastraPluginConfig } from "./config.js";
-
-const log = logUtils.logger("mastra/memory");
-
-/**
- * Build a dedicated **service-principal** Lakebase pool for Mastra
- * memory from the lakebase plugin's resolved SP pg config.
- *
- * The plugin's `exports().pool` is a `RoutingPool` that switches to
- * the per-user (OBO) pool whenever a query runs inside an `asUser`
- * scope - exactly the context the mastra plugin establishes around
- * every chat turn. Memory (threads / messages + semantic recall) must
- * instead always act as the app service principal: it owns the
- * auto-created `mastra_*` schemas (a per-user role usually can't
- * `CREATE SCHEMA`) and is shared across users, so it cannot inherit a
- * request's OBO identity.
- *
- * `pgConfig` must be the plugin's `exports().getPgConfig()` evaluated
- * **outside** any `asUser` scope (i.e. during setup), so it carries
- * the SP connection target, OAuth token-refresh `password` callback,
- * and any `lakebase({ pool })` tuning overrides - all of which this
- * pool inherits. See the call site in `plugin.ts`.
- */
-export async function createServicePrincipalPool(pgConfig: PoolConfig): Promise<Pool> {
-  // `getPgConfig()` resolves the SP username synchronously from
-  // `PGUSER` / `DATABRICKS_CLIENT_ID`; fall back to the async API
-  // lookup (e.g. local dev authenticating via PAT) so the pool always
-  // has an identity to connect with.
-  const user = pgConfig.user ?? (await getUsernameWithApiLookup());
-  return new Pool({ ...pgConfig, user });
-}
-
-/** Effective per-knob setting after the plugin/agent cascade. */
-type StorageSetting = MastraAgentDefinition["storage"];
-type MemorySetting = MastraAgentDefinition["memory"];
-
-/**
- * True when any plugin-level or per-agent setting could need the
- * Lakebase pool. Used by `plugin.ts` to gate creation of the
- * service-principal pool and the {@link MemoryBuilder} that consumes
- * it; when false neither is built.
- */
-export function needsLakebase(config: MastraPluginConfig): boolean {
-  if (settingNeedsSharedPool(config.storage)) return true;
-  if (settingNeedsSharedPool(config.memory)) return true;
-  const defs = collectAgentDefinitions(config);
-  return defs.some(
-    (d) => settingNeedsSharedPool(d.storage) || settingNeedsSharedPool(d.memory),
-  );
-}
-
-/**
- * Construct a per-agent {@link Memory} factory bound to the supplied
- * service-principal pool (see {@link createServicePrincipalPool}).
- * Caches the shared `PgVector` singleton (built on first need) so each
- * agent build is O(1) after the first.
- */
-export function createMemoryBuilder(
-  config: MastraPluginConfig,
-  servicePrincipalPool: Pool,
-): MemoryBuilder {
-  return new MemoryBuilder(config, servicePrincipalPool);
-}
-
-/**
- * Builds one `Memory` per agent against a shared service-principal
- * Lakebase pool. Per-instance state keeps the shared `PgVector` alive
- * across calls so registering N agents stays cheap.
- */
-export class MemoryBuilder {
-  private sharedVector: PgVector | undefined;
-
-  constructor(
-    private readonly config: MastraPluginConfig,
-    private readonly servicePrincipalPool: Pool,
-  ) {}
-
-  /**
-   * Build a `Memory` for `agentId` after the plugin/agent cascade.
-   * Returns `undefined` when the agent has neither storage nor a
-   * vector store enabled - Mastra accepts a missing `memory` field
-   * and treats the agent as stateless.
-   */
-  /**
-   * Build the Mastra-instance-level storage used for workflow
-   * snapshots. Returns `undefined` when plugin-level `storage` is
-   * disabled, in which case `agent.resumeStream()` (and therefore
-   * the `requireApproval` flow) will not be available.
-   *
-   * The store lives in a dedicated `mastra_instance` schema so it
-   * never collides with per-agent `mastra_<agentId>` namespaces.
-   * Workflow snapshots are not per-agent state; they belong to the
-   * `Mastra` instance that owns the workflow execution.
-   */
-  instanceStorage(): PostgresStore | undefined {
-    const setting = this.config.storage;
-    if (!setting) return undefined;
-    if (typeof setting === "object") {
-      return new PostgresStore(
-        withId(setting, "mastra-store__instance") as ConstructorParameters<
-          typeof PostgresStore
-        >[0],
-      );
-    }
-    return new PostgresStore({
-      id: "mastra-store__instance",
-      schemaName: "mastra_instance",
-      pool: this.servicePrincipalPool,
-    });
-  }
-
-  forAgent(agentId: string, def: MastraAgentDefinition): Memory | undefined {
-    const storageSetting = def.storage ?? this.config.storage;
-    const memorySetting = def.memory ?? this.config.memory;
-
-    const storage = this.buildStorage(agentId, storageSetting);
-    const vector = this.buildVector(memorySetting);
-    if (!storage && !vector) {
-      log.debug("agent:stateless", { agentId });
-      return undefined;
-    }
-
-    log.debug("agent:configured", {
-      agentId,
-      storage: storage !== undefined,
-      vector: vector !== undefined,
-      vectorMode:
-        vector === undefined
-          ? "off"
-          : typeof memorySetting === "object"
-            ? "dedicated"
-            : "shared",
-    });
-
-    return new Memory({
-      ...(storage ? { storage } : {}),
-      ...(vector ? { vector, embedder: fastembed } : {}),
-      options: {
-        lastMessages: 10,
-        ...(vector ? { semanticRecall: { topK: 3, messageRange: 2 } } : {}),
-      },
-    });
-  }
-
-  private buildStorage(
-    agentId: string,
-    setting: StorageSetting,
-  ): PostgresStore | undefined {
-    if (!setting) return undefined;
-    if (typeof setting === "boolean") {
-      return new PostgresStore({
-        id: `mastra-store__${agentId}`,
-        schemaName: `mastra_${agentId}`,
-        pool: this.servicePrincipalPool,
-      });
-    }
-    // Cast: `withId` guarantees `id` is set, but the distributive
-    // Omit + `id?: string` shape doesn't structurally narrow to the
-    // discriminated union members. Runtime shape is identical.
-    return new PostgresStore(
-      withId(setting, `mastra-store__${agentId}`) as ConstructorParameters<
-        typeof PostgresStore
-      >[0],
-    );
-  }
-
-  /**
-   * Resolve the agent's vector store. Cascade:
-   *
-   * - falsy: no vector.
-   * - `boolean` / `undefined-inheriting-true`: return the shared
-   *   singleton (built lazily on first call). All agents that
-   *   default-enable memory write into and recall from one index.
-   * - object: build a dedicated `PgVector` for this agent.
-   */
-  private buildVector(setting: MemorySetting): PgVector | undefined {
-    if (!setting) return undefined;
-    if (typeof setting === "boolean") return this.getSharedVector();
-    return buildPgVector(setting);
-  }
-
-  private getSharedVector(): PgVector {
-    if (!this.sharedVector) {
-      this.sharedVector = buildSharedPgVector(this.servicePrincipalPool);
-    }
-    return this.sharedVector;
-  }
-}
-
-/**
- * Build the shared `PgVector` that backs the default
- * `def.memory === true` case across every agent.
- *
- * `PgVector`'s constructor accepts only connection-style configs
- * (`HostConfig` / `ConnectionStringConfig` / `ClientConfig`); there is
- * no `{ pool }` shorthand the way `PostgresStore` has one. Worse, the
- * constructor synchronously kicks off a `cacheWarmupPromise` IIFE that
- * calls `this.pool.connect()` before returning, so we can't cleanly
- * hand it an inert config and patch the pool afterwards.
- *
- * The trick: pass illegal-but-validation-passing placeholders so the
- * warmup's `net.connect()` rejects synchronously with `RangeError`
- * (Node validates `0 <= port < 65536`). The IIFE's `catch {}` swallows
- * it, no DNS lookup or TCP attempt happens, and we then swap
- * `pgVector.pool` to the lakebase pool. Every subsequent `PgVector`
- * method reads `this.pool` at call time, so all real I/O goes through
- * the lakebase pool from then on. The placeholder pool is `.end()`'d
- * so its socket book-keeping is released.
- */
-function buildSharedPgVector(pool: Pool): PgVector {
-  const vector = new PgVector({
-    id: `pg${randomUUID()}`,
-    host: "-1",
-    port: -1,
-    database: "_",
-    user: "_",
-    password: "_",
-  });
-  const placeholder = vector.pool;
-  vector.pool = pool;
-  void placeholder.end().catch(() => undefined);
-  return vector;
-}
-
-/** Per-agent dedicated `PgVector` (rare; opt-in via object override). */
-function buildPgVector(setting: MastraMemoryConfigOverride): PgVector {
-  return new PgVector(
-    withId(setting, `pg-vector__${randomUUID()}`) as ConstructorParameters<
-      typeof PgVector
-    >[0],
-  );
-}
-
-/** True when this setting requires the shared Lakebase pool. */
-function settingNeedsSharedPool(
-  setting: StorageSetting | MemorySetting | undefined,
-): boolean {
-  return setting === true;
-}
-
-/** Walk the three shapes of `config.agents` into a flat list. */
-function collectAgentDefinitions(config: MastraPluginConfig): MastraAgentDefinition[] {
-  const agents = config.agents;
-  if (!agents) return [];
-  if (Array.isArray(agents)) return agents;
-  if (typeof (agents as MastraAgentDefinition).instructions === "string") {
-    return [agents as MastraAgentDefinition];
-  }
-  return Object.values(agents as Record<string, MastraAgentDefinition>);
-}
-
-/** Fill in a default `id` when the caller didn't supply one. */
-function withId<T extends { id?: string }>(value: T, fallback: string): T {
-  return value.id ? value : { ...value, id: fallback };
-}

package/src/model.ts

@@ -1,263 +0,0 @@
-/**
- * Databricks Model Serving resolver for Mastra agents.
- *
- * Each agent step calls {@link buildModel} with the active
- * `RequestContext`. The user stamped by `MastraServer` carries an
- * AppKit `WorkspaceClient`; we ask it for the workspace host and a
- * fresh bearer header, then point Mastra's OpenAI-compatible provider
- * at `/serving-endpoints` on that host.
- *
- * This module only adds the Mastra-specific glue. The actual model
- * selection - listing the workspace catalogue and resolving an
- * explicit name / class / fallback chain to a real endpoint id - lives
- * in `@dbx-tools/model` ({@link selectModel}) so non-Mastra consumers
- * (e.g. a job that just needs a model name) can reuse it. Here we
- * assemble the explicit ask from Mastra's request context (the
- * per-request override under {@link MASTRA_MODEL_OVERRIDE_KEY}, the
- * agent / plugin `modelId`, or `DATABRICKS_SERVING_ENDPOINT_NAME`),
- * pass the plugin's fuzzy / class / fallback knobs through, and wrap
- * the resolved id in the OpenAI-compatible provider config Mastra
- * expects. Catalogue fetches fail loud: network / auth errors
- * propagate so callers see the real SDK message.
- */
-
-import { getExecutionContext } from "@databricks/appkit";
-import { type ModelClass, parseModelClass, selectModel } from "@dbx-tools/model";
-import { commonUtils, logUtils, netUtils, stringUtils } from "@dbx-tools/shared";
-import type { MastraModelConfig } from "@mastra/core/llm";
-import type { RequestContext } from "@mastra/core/request-context";
-
-import { MASTRA_USER_KEY, type MastraPluginConfig, type User } from "./config.js";
-import { MASTRA_MODEL_OVERRIDE_KEY, resolveServingConfig } from "./serving.js";
-
-export {
-  classifyEndpoints,
-  FALLBACK_MODEL_IDS,
-  ModelClass,
-  modelForClass,
-  modelsForClass,
-} from "@dbx-tools/model";
-
-/** Optional overrides accepted by {@link buildModel}. */
-export interface BuildModelOverrides {
-  /**
-   * Static model id from the agent / plugin config (string sugar on
-   * `def.model` or `config.defaultModel`). Loses to the per-request
-   * override but wins over env / class / fallback.
-   */
-  modelId?: string;
-  /**
-   * Chat capability class to resolve when no explicit model id is
-   * supplied. Used by internal agents (e.g. the chart planner asks for
-   * {@link ModelClass.ChatFast}) to express intent without pinning an
-   * endpoint name; the live catalogue is classified and the top
-   * available model in the class is chosen, falling back to the
-   * class's static list when the workspace has none.
-   */
-  modelClass?: ModelClass;
-}
-
-/**
- * Resolve a `MastraModelConfig` for the current agent step. Runs
- * while `agent.stream` is inside the `asUser(req)` scope so tokens
- * are user-scoped; outside an active user context the workspace
- * client falls back to the service principal.
- */
-export async function buildModel(
-  config: MastraPluginConfig,
-  requestContext: RequestContext,
-  overrides: BuildModelOverrides = {},
-): Promise<MastraModelConfig> {
-  void setupFetchInterceptor();
-  // The chat path stamps the AppKit user on the request context via
-  // `MastraServer`. The MCP transport routes don't thread that context
-  // into tool execution, so fall back to the ambient execution context
-  // (the active OBO scope, or the service principal) when it's absent.
-  const user = requestContext.get(MASTRA_USER_KEY) as User | undefined;
-  const executionContext = user?.executionContext ?? getExecutionContext();
-  const clientConfig = executionContext.client.config;
-  const host = (await clientConfig.getHost()).toString();
-  const headers = new Headers();
-  await clientConfig.authenticate(headers);
-  // The OpenAI Node SDK appends paths like `/chat/completions` to whatever
-  // URL we hand it. Drop the trailing slash so the resulting URL stays
-  // well-formed (`/serving-endpoints/chat/completions`).
-  const url = new URL("/serving-endpoints", host).toString().replace(/\/$/, "");
-
-  const log = logUtils.logger(config);
-  const serving = resolveServingConfig(config);
-  const override = serving.allowOverride
-    ? (requestContext.get(MASTRA_MODEL_OVERRIDE_KEY) as string | undefined)
-    : undefined;
-
-  // The override / agent default / env value can be either a concrete
-  // endpoint name or a model class slug ("chat-thinking" /
-  // "chat-balanced" / "chat-fast"). A class slug becomes a class intent
-  // (let the live catalogue pick the best model in that band); anything
-  // else is an explicit name fuzzy-matched against the catalogue. An
-  // internal `overrides.modelClass` (e.g. the chart planner) is the
-  // floor when nothing was requested.
-  const requested =
-    override ?? overrides.modelId ?? process.env.DATABRICKS_SERVING_ENDPOINT_NAME;
-  const requestedClass = requested !== undefined ? parseModelClass(requested) : null;
-  const explicit = requestedClass === null ? requested : undefined;
-  const modelClass = requestedClass ?? overrides.modelClass;
-
-  const { modelId, source } = await selectModel(executionContext.client, host, {
-    ...(explicit !== undefined ? { explicit } : {}),
-    fuzzy: serving.fuzzy,
-    threshold: serving.threshold,
-    ...(modelClass !== undefined ? { modelClass } : {}),
-    fallbacks: serving.fallbacks,
-    ttlMs: serving.ttlMs,
-  });
-  log.debug("model selected", { modelId, source, requested });
-
-  return {
-    providerId: config.providerId ?? "databricks",
-    modelId,
-    url,
-    headers: Object.fromEntries(headers.entries()),
-  };
-}
-
-/** Path prefix that identifies a Databricks Model Serving REST call. */
-const SERVING_ENDPOINTS_PATH_PREFIX = "/serving-endpoints/";
-
-/**
- * OpenAI-flavoured chat message shape we need to mutate. We do not
- * import the OpenAI / AI SDK types because both packages keep these
- * fields under internal namespaces; the wire payload is the contract
- * here and it's stable enough to inline.
- */
-interface ChatMessage {
-  role: "system" | "user" | "assistant" | "tool";
-  content?: string;
-  tool_calls?: Array<{ id: string; type: string; function: unknown }>;
-  tool_call_id?: string;
-}
-
-/**
- * Install a single shared `globalThis.fetch` wrapper for every POST to
- * `/serving-endpoints/...`. The wrapper does two things:
- *
- *   1. Rewrites the outgoing `messages` array to repair Mastra/AI SDK
- *      stream-replay quirks that Databricks-hosted Claude rejects (see
- *      {@link sanitizeServingMessages}).
- *   2. At `LOG_LEVEL=debug`, dumps the (post-sanitize) JSON body so
- *      4xx debugging doesn't have to fight AI SDK's `[Array]`
- *      formatter.
- *
- * Safe to call from any hot path: {@link commonUtils.memoize} ensures
- * the wrapper is installed at most once per process, so subsequent
- * calls collapse to a single cached promise even when
- * {@link buildModel} fires on every agent step.
- */
-const setupFetchInterceptor = commonUtils.memoize((): void => {
-  const log = logUtils.logger("mastra/llm");
-  const original = globalThis.fetch.bind(globalThis);
-  globalThis.fetch = (async (input, init) => {
-    const url = netUtils.urlBuilder(input);
-    if (
-      !url ||
-      !url.pathname.startsWith(SERVING_ENDPOINTS_PATH_PREFIX) ||
-      typeof init?.body !== "string"
-    ) {
-      return original(input, init);
-    }
-    const rewritten = rewriteServingBody(init.body);
-    if (rewritten !== init.body) {
-      init = { ...init, body: rewritten };
-    }
-    try {
-      log.debug("POST", { url: url.toString(), body: JSON.parse(rewritten) });
-    } catch {
-      log.debug("POST", { url: url.toString(), bodyType: "non-JSON" });
-    }
-    return original(input, init);
-  }) as typeof globalThis.fetch;
-});
-
-/**
- * Parse, sanitize, and re-serialize a `/serving-endpoints/...` POST
- * body. Returns the original string verbatim when the body is not
- * JSON, has no `messages`, or no rewrite was needed; this lets the
- * caller skip the allocation of a new `init` object in the common
- * pass-through case.
- */
-function rewriteServingBody(body: string): string {
-  let parsed: { messages?: unknown };
-  try {
-    parsed = JSON.parse(body);
-  } catch {
-    return body;
-  }
-  if (!Array.isArray(parsed.messages)) return body;
-  const changed = sanitizeServingMessages(parsed.messages as ChatMessage[]);
-  return changed ? JSON.stringify(parsed) : body;
-}
-
-/**
- * Repair a Mastra/AI SDK message replay that Databricks-hosted Claude
- * rejects with `"This model does not support assistant message
- * prefill. The conversation must end with a user message."`.
- *
- * The bug pattern: when an assistant turn streams text *and* a
- * `tool_call`, the AI SDK persists them as two separate assistant
- * entries (text-only and tool-call-only). On the next agent step the
- * tool-call entry is replayed *before* the tool result and the
- * text entry is replayed *after* it, so the conversation ends with a
- * trailing assistant text message. Anthropic interprets that as a
- * prefill request and rejects it on Databricks (the upstream Bedrock
- * route disallows prefill).
- *
- * Fix: when the last message is an assistant text with no `tool_calls`
- * and the chain immediately before it is `assistant(tool_calls=...)`
- * followed only by `tool(...)` results, fold the trailing text back
- * into the `content` of that opening assistant and drop the duplicate.
- * The result is the canonical OpenAI shape
- * `[..., user, assistant(text + tool_calls), tool(...)]` which both
- * Databricks Claude and every other endpoint accept.
- *
- * Mutates `messages` in place; returns `true` when something changed
- * so the caller knows whether to re-serialize.
- */
-function sanitizeServingMessages(messages: ChatMessage[]): boolean {
-  if (messages.length < 2) return false;
-  const last = messages[messages.length - 1];
-  if (
-    !last ||
-    last.role !== "assistant" ||
-    (last.tool_calls && last.tool_calls.length > 0)
-  ) {
-    return false;
-  }
-
-  // Walk back through any contiguous tool-result messages to find the
-  // assistant turn that opened this tool sequence.
-  let i = messages.length - 2;
-  while (i >= 0 && messages[i]?.role === "tool") i--;
-  if (i < 0) return false;
-  const opener = messages[i];
-  if (
-    !opener ||
-    opener.role !== "assistant" ||
-    !opener.tool_calls ||
-    opener.tool_calls.length === 0
-  ) {
-    return false;
-  }
-
-  // `trimToNull` collapses the `typeof string && trimmed` dance and
-  // drops blank fragments before the `\n\n` join below, so the merge
-  // never introduces stray leading / trailing whitespace.
-  const merged = [
-    stringUtils.trimToNull(opener.content),
-    stringUtils.trimToNull(last.content),
-  ]
-    .filter((s): s is string => s !== null)
-    .join("\n\n");
-  opener.content = merged;
-  messages.pop();
-  return true;
-}

package/src/observability.ts

@@ -1,114 +0,0 @@
-/**
- * Mastra observability wired through the same OTel pipeline AppKit's
- * built-in plugins (e.g. `agents`) use, via `@mastra/otel-bridge`.
- *
- * How traces flow:
- *
- * 1. `@databricks/appkit` boots a global `NodeSDK` in
- *    `TelemetryManager.initialize()` (during `createApp`) when
- *    `OTEL_EXPORTER_OTLP_ENDPOINT` is set in the process env.
- * 2. Every AppKit plugin span (e.g. the `agents` plugin's
- *    `executeStream`) is created via the global OTel tracer
- *    (`trace.getTracer(<plugin>)`), so it lands on that NodeSDK and
- *    is shipped through its OTLP exporter.
- * 3. The Mastra `OtelBridge` ALSO creates real OTel spans on the same
- *    global tracer for every Mastra operation (agent runs, model
- *    calls, tool invocations, workflow steps). They inherit the
- *    ambient OTel context, so when Mastra is invoked from inside an
- *    AppKit HTTP span the trace stays connected.
- *
- * Net effect: Mastra spans get exactly the treatment AppKit's
- * `agents` plugin gets. No custom OTLP pipeline lives in this
- * package; the OTLP endpoint, headers, and resource attributes are
- * driven by the standard OTel env vars
- * (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`,
- * `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, ...) and consumed
- * by AppKit's `TelemetryManager`. Set those once and both AppKit and
- * Mastra spans end up at the same backend.
- *
- * When `OTEL_EXPORTER_OTLP_ENDPOINT` is unset the bridge's spans go
- * to the global noop tracer, mirroring how the `agents` plugin
- * silently no-ops in the same situation.
- */
-
-import { logUtils, projectUtils } from "@dbx-tools/shared";
-import { Observability } from "@mastra/observability";
-import { OtelBridge } from "@mastra/otel-bridge";
-
-import { TRACE_REQUEST_CONTEXT_KEYS } from "./config.js";
-
-const log = logUtils.logger("mastra/observability");
-
-const DEFAULT_SERVICE_NAME = "mastra";
-
-export interface BuildObservabilityOptions {
-  /**
-   * Service name attached to the Mastra `Observability` config. Used
-   * as the tracer scope name on bridged OTel spans (the `service.name`
-   * resource attribute is owned by AppKit's `TelemetryManager` instead
-   * - it reads `OTEL_SERVICE_NAME` / `DATABRICKS_APP_NAME` at
-   * `createApp` time).
-   *
-   * Defaults to project name then `"mastra"`.
-   */
-  serviceName?: string;
-  /**
-   * `RequestContext` keys to extract as span metadata on every Mastra
-   * trace. Defaults to {@link TRACE_REQUEST_CONTEXT_KEYS} (user id,
-   * thread id, request id, environment, model override, ...).
-   *
-   * Supports dot notation for nested values per the Mastra docs.
-   */
-  requestContextKeys?: readonly string[];
-}
-
-/**
- * Build a Mastra `Observability` whose spans ride AppKit's global
- * OTel pipeline via `@mastra/otel-bridge`.
- *
- * Returns `undefined` only if someone explicitly opts out in the
- * future; today it always returns an `Observability` because the
- * bridge degrades gracefully (no-op tracer) when no global OTel SDK
- * is registered. Callers can spread `...(observability ? { observability } : {})`
- * either way to stay forward-compatible.
- */
-export async function buildObservability(
-  options?: BuildObservabilityOptions,
-): Promise<Observability | undefined> {
-  const serviceName =
-    options?.serviceName ?? (await projectUtils.name()) ?? DEFAULT_SERVICE_NAME;
-  const requestContextKeys = [
-    ...(options?.requestContextKeys ?? TRACE_REQUEST_CONTEXT_KEYS),
-  ];
-
-  // The OTel HTTP exporter treats `OTEL_EXPORTER_OTLP_ENDPOINT` as a
-  // *base* URL and appends the signal path itself (e.g.
-  // `http://localhost:6006` -> `http://localhost:6006/v1/traces`). Log
-  // the resolved POST URL so misconfigurations (e.g. accidentally
-  // setting the base var to a `/v1/traces`-suffixed URL, which makes
-  // the SDK POST to `.../v1/traces/v1/traces` and Phoenix 404s) are
-  // obvious in startup output.
-  const otelBase = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
-  const otelTracesOverride = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
-  const resolvedTracesUrl = otelTracesOverride
-    ? otelTracesOverride
-    : otelBase
-      ? `${otelBase.replace(/\/+$/, "")}/v1/traces`
-      : undefined;
-  log.info("Mastra observability wired through OTel bridge", {
-    serviceName,
-    requestContextKeys,
-    otelBase: otelBase ?? "<unset>",
-    resolvedTracesUrl: resolvedTracesUrl ?? "<noop; OTLP endpoint unset>",
-  });
-
-  return new Observability({
-    configs: {
-      serviceName: {
-        serviceName,
-        bridge: new OtelBridge(),
-        requestContextKeys,
-      },
-    },
-  });
-}