@introspection-sdk/introspection-node 0.19.1 → 0.21.0

package/src/converters/vercel.ts

@@ -1,302 +0,0 @@
-/**
- * Converter for Vercel AI SDK telemetry spans → Gen AI semantic conventions.
- *
- * The Vercel AI SDK emits spans with `ai.*` attributes when
- * `experimental_telemetry: { isEnabled: true }` is set on streamText/generateText.
- * This converter translates those to `gen_ai.*` so the Introspection frontend
- * can render them in the conversation view.
- */
-
-import type { Attributes } from "@opentelemetry/api";
-
-interface VercelMessage {
-  role: string;
-  content?: string | VercelContentPart[];
-}
-
-interface VercelContentPart {
-  type: string;
-  text?: string;
-  content?: string;
-  toolName?: string;
-  name?: string;
-  toolCallId?: string;
-  id?: string;
-  // AI SDK v6 uses `input` for tool-call args; older versions used `args`.
-  args?: string | Record<string, unknown>;
-  input?: string | Record<string, unknown>;
-  // tool-result payload. AI SDK v6 emits `{ output: { type: "text", value } }`
-  // for text results; older shapes used `result`.
-  output?: { type?: string; value?: unknown } | unknown;
-  result?: unknown;
-}
-
-interface VercelTool {
-  type?: string;
-  name?: string;
-  description?: string;
-  inputSchema?: Record<string, unknown>;
-  parameters?: Record<string, unknown>;
-}
-
-interface GenAIPart {
-  type: string;
-  content?: string;
-  name?: string;
-  id?: string;
-  arguments?: string;
-  // tool_call_response payload — kept separate from `content` so downstream
-  // consumers (and brightstaff signal detectors) can distinguish tool
-  // results from plain text.
-  response?: string;
-}
-
-interface GenAIMessage {
-  role: string;
-  parts: GenAIPart[];
-}
-
-/** Check if a span is a Vercel AI SDK span worth converting.
- * Only converts child "do*" spans (doStream, doGenerate) which have
- * the actual prompt/response data with proper message windows.
- * Parent wrapper spans (ai.streamText, ai.generateText) are skipped
- * to avoid duplicate conversation steps without user messages. */
-export function isVercelAISpan(attrs: Attributes): boolean {
-  const operationId = attrs["ai.operationId"];
-  return typeof operationId === "string" && operationId.includes(".do");
-}
-
-/**
- * Convert Vercel AI SDK `ai.*` attributes to `gen_ai.*` semconv attributes.
- * Returns only the gen_ai attributes to merge — does NOT remove originals.
- */
-export function convertVercelAIToGenAI(
-  attrs: Attributes,
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-
-  // gen_ai.operation.name
-  result["gen_ai.operation.name"] = "chat";
-
-  // gen_ai.usage.cache_read.input_tokens from ai.usage.cachedInputTokens
-  const cachedInput = attrs["ai.usage.cachedInputTokens"];
-  if (typeof cachedInput === "number") {
-    result["gen_ai.usage.cache_read.input_tokens"] = cachedInput;
-  }
-
-  // gen_ai.conversation.id from telemetry metadata (set by app)
-  const metadataConvId = attrs["ai.telemetry.metadata.gen_ai.conversation.id"];
-  if (typeof metadataConvId === "string") {
-    result["gen_ai.conversation.id"] = metadataConvId;
-  }
-
-  // gen_ai.request.model and gen_ai.provider.name from ai.model.*
-  const modelId = attrs["ai.model.id"];
-  if (typeof modelId === "string" && !attrs["gen_ai.request.model"]) {
-    result["gen_ai.request.model"] = modelId;
-  }
-  const modelProvider = attrs["ai.model.provider"];
-  if (typeof modelProvider === "string" && !attrs["gen_ai.provider.name"]) {
-    result["gen_ai.provider.name"] = modelProvider;
-  }
-
-  // Vercel AI SDK stores prompt data in two formats:
-  // - Child spans (doStream): flat keys like ai.prompt.messages, ai.prompt.toolChoice
-  // - Parent spans (streamText): single JSON string in ai.prompt
-  const promptMessages = attrs["ai.prompt.messages"];
-  const promptRaw = attrs["ai.prompt"];
-  let parsedMessages: VercelMessage[] | null = null;
-  let parsedSystem: string | null = null;
-
-  if (typeof promptMessages === "string") {
-    try {
-      const parsed: unknown = JSON.parse(promptMessages);
-      if (Array.isArray(parsed)) parsedMessages = parsed as VercelMessage[];
-    } catch {
-      /* ignore */
-    }
-  } else if (typeof promptRaw === "string") {
-    try {
-      const parsed = JSON.parse(promptRaw) as Record<string, unknown>;
-      if (Array.isArray(parsed?.messages))
-        parsedMessages = parsed.messages as VercelMessage[];
-      if (typeof parsed?.system === "string") parsedSystem = parsed.system;
-    } catch {
-      /* ignore */
-    }
-  }
-
-  // gen_ai.input.messages — excluding system messages
-  const nonSystemMessages = parsedMessages
-    ? parsedMessages.filter((m) => m.role !== "system")
-    : null;
-  if (nonSystemMessages && nonSystemMessages.length > 0) {
-    const converted = nonSystemMessages.map(convertVercelMessageToGenAI);
-    result["gen_ai.input.messages"] = JSON.stringify(converted);
-  }
-
-  // gen_ai.output.messages — build from ai.response.text + ai.response.reasoning
-  const responseText = attrs["ai.response.text"];
-  const responseReasoning = attrs["ai.response.reasoning"];
-  if (typeof responseText === "string" && responseText) {
-    const parts: GenAIPart[] = [];
-    if (typeof responseReasoning === "string" && responseReasoning) {
-      parts.push({ type: "reasoning", content: responseReasoning });
-    }
-    parts.push({ type: "text", content: responseText });
-    result["gen_ai.output.messages"] = JSON.stringify([
-      { role: "assistant", parts },
-    ]);
-  }
-
-  // gen_ai.tool.definitions — parse ai.prompt.tools JSON strings
-  const promptTools = attrs["ai.prompt.tools"];
-  if (typeof promptTools === "string") {
-    try {
-      const parsed: unknown = JSON.parse(promptTools);
-      if (Array.isArray(parsed)) {
-        result["gen_ai.tool.definitions"] = JSON.stringify(
-          (parsed as (string | VercelTool)[])
-            .map((t) => {
-              if (typeof t === "string") {
-                try {
-                  return JSON.parse(t) as VercelTool;
-                } catch {
-                  return { name: t } as VercelTool;
-                }
-              }
-              return t;
-            })
-            .map((t) => ({
-              type: t.type || "function",
-              name: t.name || "",
-              description: t.description || "",
-              parameters: t.inputSchema || t.parameters || undefined,
-            })),
-        );
-      }
-    } catch {
-      // ignore
-    }
-  } else if (Array.isArray(promptTools)) {
-    const tools = (promptTools as string[]).map((t) => {
-      const parsed = (typeof t === "string" ? JSON.parse(t) : t) as VercelTool;
-      return {
-        type: parsed.type || "function",
-        name: parsed.name || "",
-        description: parsed.description || "",
-        parameters: parsed.inputSchema || parsed.parameters || undefined,
-      };
-    });
-    result["gen_ai.tool.definitions"] = JSON.stringify(tools);
-  }
-
-  // gen_ai.agent.name — from telemetry functionId or operation
-  const functionId = attrs["ai.telemetry.functionId"];
-  if (typeof functionId === "string" && functionId) {
-    result["gen_ai.agent.name"] = functionId;
-  }
-
-  // gen_ai.system_instructions — from parsed system prompt or system role messages
-  if (parsedSystem) {
-    result["gen_ai.system_instructions"] = JSON.stringify([
-      { type: "text", content: parsedSystem },
-    ]);
-  } else if (parsedMessages) {
-    const systemMsgs = parsedMessages.filter((m) => m.role === "system");
-    if (systemMsgs.length > 0) {
-      result["gen_ai.system_instructions"] = JSON.stringify(
-        systemMsgs.map((m) => ({
-          type: "text",
-          content:
-            typeof m.content === "string"
-              ? m.content
-              : JSON.stringify(m.content),
-        })),
-      );
-    }
-  }
-
-  return result;
-}
-
-function convertVercelMessageToGenAI(msg: VercelMessage): GenAIMessage {
-  const role = msg.role || "user";
-
-  if (role === "system") {
-    return {
-      role,
-      parts: [{ type: "text", content: extractTextContent(msg.content) }],
-    };
-  }
-
-  return {
-    role,
-    parts: extractParts(msg.content),
-  };
-}
-
-function extractTextContent(content: VercelMessage["content"]): string {
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) {
-    return content
-      .filter((p) => p.type === "text")
-      .map((p) => p.text || p.content || "")
-      .join("");
-  }
-  return String(content || "");
-}
-
-function extractParts(content: VercelMessage["content"]): GenAIPart[] {
-  if (typeof content === "string") {
-    return [{ type: "text", content }];
-  }
-  if (Array.isArray(content)) {
-    return content.map((part) => {
-      if (part.type === "text") {
-        return { type: "text", content: part.text || part.content || "" };
-      }
-      if (part.type === "tool-call" || part.type === "tool_call") {
-        // AI SDK v6 emits `input`; older versions emitted `args`.
-        const rawArgs = part.input ?? part.args;
-        return {
-          type: "tool_call",
-          name: part.toolName || part.name || "",
-          id: part.toolCallId || part.id || "",
-          arguments:
-            typeof rawArgs === "string" ? rawArgs : JSON.stringify(rawArgs),
-        };
-      }
-      if (part.type === "tool-result" || part.type === "tool_result") {
-        // AI SDK v6 wraps text outputs in `{ output: { type: "text", value } }`.
-        // Older shapes used `result`. Unwrap to the raw string when we can so
-        // brightstaff's execution.failure.* / environment.exhaustion.* regex
-        // detectors see the error text directly — otherwise downstream
-        // consumers get a JSON-stringified blob and the canonical
-        // `tool_call_response` shape is lost.
-        const rawOutput =
-          part.result !== undefined ? part.result : (part.output as unknown);
-        let response: string;
-        if (typeof rawOutput === "string") {
-          response = rawOutput;
-        } else if (
-          rawOutput &&
-          typeof rawOutput === "object" &&
-          "value" in (rawOutput as Record<string, unknown>)
-        ) {
-          const value = (rawOutput as Record<string, unknown>).value;
-          response = typeof value === "string" ? value : JSON.stringify(value);
-        } else {
-          response = JSON.stringify(rawOutput);
-        }
-        return {
-          type: "tool_call_response",
-          id: part.toolCallId || part.id || "",
-          response,
-        };
-      }
-      return { type: "text", content: JSON.stringify(part) };
-    });
-  }
-  return [{ type: "text", content: String(content || "") }];
-}

package/src/dev-target.ts

@@ -1,79 +0,0 @@
-/**
- * Development-target resolution — which `introspection dev` server this
- * process's tasks should reach.
- *
- * Two developers can run `introspection dev` against one shared Runtime. A
- * task created by a shared application credential carries no developer, so the
- * platform cannot tell their machines apart; the caller names one instead.
- * `introspection dev` prints the value to set:
- *
- * ```
- * serving as: roland
- * for your app: INTROSPECTION_DEV_TARGET=roland
- * ```
- *
- * Carried as a header rather than on the runner's `caller` payload: `caller`
- * is descriptive metadata the platform never acts on, and a target is a
- * per-request selector the platform does act on. Keeping them apart is what
- * lets `caller` stay a free-form bag, and it is the only transport that
- * reaches a bare `POST /v1/tasks` with a dev API key, whose JWT is minted from
- * the key row with no per-request input path.
- *
- * Deliberately env-only, with no `os.userInfo()` fallback. Defaulting to the
- * local username would be zero-config on a laptop and wrong everywhere else: a
- * process running in a shared development deployment under an account like
- * `node` would silently name a machine nobody is serving and fail closed,
- * where today it reaches the one connected dev server. The CLI defaults to the
- * username because it is naming *itself* and always runs on the developer's
- * machine; this names *someone else's* machine and can run anywhere.
- *
- * Inert outside development: the Data Plane consults a target only on the
- * development pin path, so a stray value in staging or production is ignored.
- */
-
-/** Header carrying the target on requests that have no runner to ride. */
-export const DEV_TARGET_HEADER = "x-introspection-dev-target";
-
-/** The env var `introspection dev` prints and both the CLI and SDK read. */
-export const DEV_TARGET_ENV = "INTROSPECTION_DEV_TARGET";
-
-/**
- * Percent-encode to RFC 3986, so the three SDKs put identical bytes on the
- * wire for the same target.
- *
- * `encodeURIComponent` leaves `!'()*` alone where Python's `quote(safe="")`
- * and the Rust client encode them. The Data Plane decodes before it
- * normalizes, so either form routes — but a header that differs by which
- * client sent it is a debugging trap for no benefit.
- */
-function encodeTarget(value: string): string {
-  return encodeURIComponent(value).replace(
-    /[!'()*]/g,
-    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
-  );
-}
-
-/**
- * The development target for this process, or `undefined` when unset.
- *
- * Percent-encoded, because the value becomes an HTTP header and a header is
- * bytes: a login name like `andré` is not transmissible as-is, and a runtime
- * that lets it through sends latin-1 bytes the server would read back as a
- * different string. Encoding here is lossless and costs nothing for the
- * ordinary ASCII name, which encodes to itself.
- *
- * Safe to send encoded because the Data Plane decodes before it normalizes,
- * so `andré` and `andr%C3%A9` land on the same target as the `--as andré`
- * the CLI advertises over protobuf, where no encoding is needed.
- *
- * Read through `globalThis.process` so the module stays importable from
- * non-Node runtimes that share this package's build.
- */
-export function resolveDevTarget(): string | undefined {
-  const env = (
-    globalThis as { process?: { env?: Record<string, string | undefined> } }
-  ).process?.env;
-  const raw = env?.[DEV_TARGET_ENV];
-  const trimmed = raw?.trim();
-  return trimmed ? encodeTarget(trimmed) : undefined;
-}

package/src/http.ts

@@ -1,43 +0,0 @@
-import { BaseHttpClient } from "@introspection-sdk/http";
-
-export interface ResolvedApiConfig {
-  /**
-   * Base URL the client will prepend to every request path. For the
-   * IntrospectionClient this is the CP API host; for a Runner it is the
-   * `deployment.endpoint` returned by CP.
-   */
-  apiUrl: string;
-  /** Bearer token. Customer API key for CP, runner JWT for DP. */
-  token: string;
-  additionalHeaders?: Record<string, string>;
-  fetch?: typeof fetch;
-  /**
-   * Automatic retries on a `429 Too Many Requests` for unary requests
-   * (honouring `Retry-After`). `0` disables. Defaults to the shared client
-   * default. Streaming has its own resume budget.
-   */
-  maxRetries?: number;
-  /** Base step (ms) of the capped-exponential `429` retry backoff. */
-  retryBaseMs?: number;
-}
-
-/**
- * Bearer-token HTTP client used by both the CP-bound IntrospectionClient
- * and each DP-bound Runner. The request/response machinery lives in the
- * shared {@link BaseHttpClient}; this only pins the auth strategy —
- * `Authorization: Bearer <token>` on every request, no cookie credentials.
- */
-export class HttpClient extends BaseHttpClient {
-  constructor(cfg: ResolvedApiConfig) {
-    super({
-      apiUrl: cfg.apiUrl,
-      additionalHeaders: cfg.additionalHeaders,
-      fetch: cfg.fetch,
-      maxRetries: cfg.maxRetries,
-      retryBaseMs: cfg.retryBaseMs,
-      transport: {
-        authHeaders: () => ({ Authorization: `Bearer ${cfg.token}` }),
-      },
-    });
-  }
-}

package/src/index.ts

@@ -1,266 +0,0 @@
-/**
- * Root entry point — REST-only surface.
- *
- * Exports `IntrospectionClient` (REST), Runner / RuntimeHandle /
- * ExperimentHandle, REST wire types, and HTTP helpers. None of these
- * touch the OpenTelemetry SDK.
- *
- * For the OTel surface (logs, span processors, instrumentors) import
- * from `@introspection-sdk/introspection-node/otel`.
- */
-
-// REST client.
-export { IntrospectionClient } from "./client.js";
-
-// Machine / federated / hosted-login OAuth token helpers.
-export {
-  serviceAccountToken,
-  tokenExchange,
-  authorizationCodeToken,
-} from "./auth.js";
-export type {
-  ServiceAccountTokenParams,
-  ServiceAccountToken,
-  TokenExchangeParams,
-  AuthorizationCodeParams,
-  OAuthToken,
-} from "./auth.js";
-
-// Configuration / event types shared with the OTel surface.
-export type {
-  AdvancedOptions,
-  IntrospectionClientOptions,
-  FeedbackOptions,
-  UserTraits,
-} from "./types.js";
-
-// Runner-bound REST namespaces (runner.tasks, runner.files,
-// runner.conversations) + HTTP.
-export {
-  ConversationItemsApi,
-  ConversationsApi,
-  EventsApi,
-  FileVersionsApi,
-  FilesApi,
-  MetricsApi,
-  RunHandle,
-  SharesApi,
-  TaskRunsApi,
-  TasksApi,
-} from "@introspection-sdk/http";
-export { streamResumable } from "@introspection-sdk/http";
-export { ArrowPages } from "@introspection-sdk/http";
-export type {
-  EventArrowParams,
-  FileUploadBody,
-  ListReadParams,
-  StartParams,
-  StreamOptions,
-} from "@introspection-sdk/http";
-export { HttpClient } from "./http.js";
-export type { ResolvedApiConfig } from "./http.js";
-export { EventType } from "@introspection-sdk/types";
-
-// Runner + CP resources.
-export { Runner } from "./runner.js";
-export type { RunnerSource } from "./runner.js";
-export {
-  RuntimesApi,
-  RuntimeHandle,
-  attachRuntimes,
-  isUuid,
-} from "./resources/runtimes.js";
-export type { RuntimeHandleFactory } from "./resources/runtimes.js";
-export {
-  ExperimentsApi,
-  ExperimentHandle,
-  attachExperiments,
-} from "./resources/experiments.js";
-export type { ExperimentHandleFactory } from "./resources/experiments.js";
-export { RecipesApi, attachRecipes } from "./resources/recipes.js";
-
-// REST API wire types
-export type {
-  AGUIEvent,
-  BaseEvent,
-  Interrupt,
-  Message,
-  ResumeEntry,
-  RunAgentInput,
-  Paginated,
-  ListParams,
-  Task,
-  TaskCreateParams,
-  TaskUpdateParams,
-  TaskListParams,
-  TaskMode,
-  TaskStatus,
-  TaskRunKind,
-  TaskPrompt,
-  TaskRun,
-  TaskRunCreateParams,
-  TaskRunResumeParams,
-  TaskRunResponse,
-  TaskCreateResponse,
-  TaskFileRef,
-  TaskCancelResponse,
-  TaskCancelOptions,
-  AgentInfo,
-  File,
-  FileType,
-  FileListParams,
-  FileUpdateParams,
-  FileCreateTextParams,
-  Runtime,
-  RuntimeListParams,
-  Experiment,
-  ExperimentCreate,
-  ExperimentUpdate,
-  ExperimentListParams,
-  ExperimentStatus,
-  ExperimentGoal,
-  ExperimentGoalComponent,
-  ExperimentGoalDirection,
-  ExperimentGoalGuard,
-  JudgeGoalComponent,
-  TelemetryGoalComponent,
-  ExperimentArm,
-  Recipe,
-  RecipeCreate,
-  RecipeUpdate,
-  RecipeListParams,
-  RunnerSpec,
-  RunnerDeployment,
-  RunnerContext,
-  RunnerRecipeSummary,
-  RunnerIdentity,
-  RunRequest,
-  RunCaller,
-  RunCallerLibrary,
-  RunCallerPage,
-  RunIdentityInput,
-  GenAiSpan,
-  GenAiSpanList,
-  GenAiSpanAttributes,
-  GenAiSpanStatus,
-  IntrospectionSpanAttributes,
-  IntrospectionConversation,
-  SpanAttributes,
-  SpanResource,
-  ConversationItemInclude,
-  ConversationSortField,
-  ConversationListParams,
-  ConversationItemListParams,
-  ConversationsMethod,
-  SpanEvent,
-  SpanKind,
-  SpanStatus,
-  ReadFormat,
-  ReadWindowParams,
-  IntrospectionEventName,
-  IntrospectionEventEnvelope,
-  ObservationPayload,
-  PatternPayload,
-  PatternAssignmentPayload,
-  ClusteringRunPayload,
-  FeedbackPayload,
-  JudgementPayload,
-  ObservationEvent,
-  PatternEvent,
-  PatternAssignmentEvent,
-  ClusteringRunEvent,
-  FeedbackEvent,
-  JudgementEvent,
-  Event,
-  UnknownEvent,
-  EventForName,
-  EventSortField,
-  EventListParams,
-  MetricView,
-  MetricAggregation,
-  MetricFilterOperator,
-  MetricInterval,
-  MetricSpec,
-  MetricDimension,
-  MetricFilter,
-  MetricTimeDimension,
-  MetricOrderBy,
-  MetricHaving,
-  MetricQueryConfig,
-  MetricQueryRequest,
-  MetricDimensionValue,
-  MetricResultValue,
-  MetricResultRow,
-  MetricEffectiveWindow,
-  MetricQueryMeta,
-  MetricQueryResponse,
-} from "@introspection-sdk/types";
-export {
-  ConversationsMethods,
-  IntrospectionEventNames,
-  genAiConversationId,
-  genAiInputMessages,
-  genAiOutputMessages,
-  isKnownEvent,
-} from "@introspection-sdk/types";
-export {
-  IntrospectionAPIError,
-  AuthenticationError,
-  InsufficientScopeError,
-  RunnerExpiredError,
-  NotFoundError,
-  ConflictError,
-  ValidationError,
-  RateLimitError,
-  SandboxUnavailableError,
-  StreamError,
-  NetworkError,
-  apiErrorFromResponse,
-} from "@introspection-sdk/types";
-
-// GenAI types (shared, no OTel SDK imports).
-export type {
-  GenAiAttributes,
-  InputMessage,
-  OutputMessage,
-  SystemInstruction,
-  ToolDefinition,
-  TextPart,
-  ToolCallRequestPart,
-  ToolCallResponsePart,
-  CompactionPart,
-  MediaUrlPart,
-  BinaryDataPart,
-  MessagePart,
-} from "@introspection-sdk/types";
-export { toAttributes } from "@introspection-sdk/types";
-
-// OpenAI converter exports (pure functions, no OTel SDK imports).
-export {
-  convertResponsesInputsToSemconv,
-  convertResponsesOutputsToSemconv,
-  convertResponsesToolsToSemconv,
-  convertResponsesInstructionsToSemconv,
-} from "./converters/openai.js";
-export type {
-  ResponseInputItem,
-  ResponseOutputItem,
-  ResponseTool,
-  ResponseUsage,
-  Response as OpenAIResponse,
-} from "./converters/openai.js";
-
-// Gemini converters (pure functions, no OTel SDK imports).
-export {
-  convertGeminiContentsToInputMessages,
-  convertGeminiCandidatesToOutputMessages,
-  convertGeminiSystemInstructionToSemconv,
-  convertGeminiToolsToToolDefinitions,
-} from "./converters/gemini.js";
-export type {
-  GeminiCandidate,
-  GeminiContent,
-  GeminiFunctionDeclaration,
-  GeminiPart,
-  GeminiTool,
-} from "./converters/gemini.js";