@introspection-sdk/introspection-node 0.4.1 → 0.4.3

package/src/converters/gemini.ts

@@ -0,0 +1,243 @@
+/**
+ * Google Gemini (`@google/genai`) format conversion functions for OTel Gen AI
+ * Semantic Conventions.
+ *
+ * Gemini 3.x / Gemini 3.5+ models emit per-part `thoughtSignature` payloads
+ * that carry encrypted reasoning context which MUST be passed back on
+ * subsequent turns (especially around tool calls) for the model to maintain
+ * its chain of thought.
+ *
+ * @see https://ai.google.dev/gemini-api/docs/thought-signatures
+ *
+ * Whenever a Gemini part carries a `thoughtSignature`, this converter emits a
+ * `thinking` gen_ai part preceding the visible content. If the part is itself a
+ * thought summary (`thought: true`), the visible thought text is used as the
+ * thinking content; otherwise the signed-but-redacted sentinel
+ * `REDACTED_THINKING_CONTENT` (`"[redacted]"`) is used — mirroring the way the
+ * Anthropic instrumentor handles `redacted_thinking` blocks.
+ */
+
+import type {
+  InputMessage,
+  OutputMessage,
+  MessagePart,
+  ReasoningPart,
+  SystemInstruction,
+  ToolDefinition,
+} from "@introspection-sdk/types";
+
+/** Sentinel for parts that carry a thought signature but no visible thought content. */
+const REDACTED_THINKING_CONTENT = "[redacted]";
+
+/** Provider name reported on Gemini-produced thinking parts. */
+export const GEMINI_PROVIDER_NAME = "gemini";
+
+/** A single content part as returned by the `@google/genai` SDK. */
+export interface GeminiPart {
+  text?: string;
+  thought?: boolean;
+  thoughtSignature?: string;
+  functionCall?: {
+    id?: string;
+    name?: string;
+    args?: unknown;
+  };
+  functionResponse?: {
+    id?: string;
+    name?: string;
+    response?: unknown;
+  };
+  [key: string]: unknown;
+}
+
+/** A Content envelope as used in Gemini `contents` requests and candidate outputs. */
+export interface GeminiContent {
+  role?: string;
+  parts?: GeminiPart[];
+}
+
+/** A single candidate from a `generateContent` response. */
+export interface GeminiCandidate {
+  content?: GeminiContent;
+  finishReason?: string;
+  index?: number;
+}
+
+/** A Gemini tool function declaration. */
+export interface GeminiFunctionDeclaration {
+  name?: string;
+  description?: string;
+  parameters?: unknown;
+  parametersJsonSchema?: unknown;
+}
+
+/** A Gemini tool entry — `{ functionDeclarations: [...] }`. */
+export interface GeminiTool {
+  functionDeclarations?: GeminiFunctionDeclaration[];
+}
+
+/** Normalize roles from Gemini to gen_ai. Gemini uses `model` for assistant turns. */
+function normalizeRole(role: string | undefined): InputMessage["role"] {
+  if (role === "model") return "assistant";
+  if (role === "user" || role === "system" || role === "tool") return role;
+  return "user";
+}
+
+/**
+ * Convert a single Gemini part into zero-or-more gen_ai message parts.
+ *
+ * A part carrying a `thoughtSignature` always produces a leading `thinking`
+ * part so the signed reasoning payload is preserved alongside whatever visible
+ * content the part contains.
+ */
+function partToGenAiParts(part: GeminiPart): MessagePart[] {
+  const out: MessagePart[] = [];
+  const signature = part.thoughtSignature || undefined;
+  const isThought = part.thought === true;
+
+  if (isThought) {
+    // Visible thought summary (Gemini emits these when `includeThoughts: true`).
+    const reasoning: ReasoningPart = {
+      type: "thinking",
+      content: part.text || REDACTED_THINKING_CONTENT,
+      signature,
+      provider_name: GEMINI_PROVIDER_NAME,
+    };
+    out.push(reasoning);
+    return out;
+  }
+
+  if (signature) {
+    // Signed but non-thought part — emit a redacted thinking prefix carrying the signature.
+    const reasoning: ReasoningPart = {
+      type: "thinking",
+      content: REDACTED_THINKING_CONTENT,
+      signature,
+      provider_name: GEMINI_PROVIDER_NAME,
+    };
+    out.push(reasoning);
+  }
+
+  if (typeof part.text === "string" && part.text.length > 0) {
+    out.push({ type: "text", content: part.text });
+  }
+
+  if (part.functionCall) {
+    out.push({
+      type: "tool_call",
+      id: part.functionCall.id,
+      name: part.functionCall.name || "",
+      arguments: part.functionCall.args,
+    });
+  }
+
+  if (part.functionResponse) {
+    out.push({
+      type: "tool_call_response",
+      id: part.functionResponse.id,
+      name: part.functionResponse.name,
+      response: part.functionResponse.response,
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Convert a `contents` array from a Gemini request to gen_ai input messages.
+ *
+ * Accepts a plain string (the convenience form `generateContent({ contents: "hi" })`)
+ * or an array of {@link GeminiContent} objects. Roles are normalized: Gemini's
+ * `model` becomes `assistant`.
+ *
+ * @param contents - The Gemini request's `contents` field.
+ * @returns Array of {@link InputMessage} objects.
+ */
+export function convertGeminiContentsToInputMessages(
+  contents: string | GeminiContent[] | GeminiContent | undefined,
+): InputMessage[] {
+  if (!contents) return [];
+
+  if (typeof contents === "string") {
+    return [{ role: "user", parts: [{ type: "text", content: contents }] }];
+  }
+
+  const list: GeminiContent[] = Array.isArray(contents) ? contents : [contents];
+
+  const result: InputMessage[] = [];
+  for (const c of list) {
+    const parts = (c.parts || []).flatMap(partToGenAiParts);
+    if (parts.length === 0) continue;
+    result.push({ role: normalizeRole(c.role), parts });
+  }
+  return result;
+}
+
+/**
+ * Convert Gemini response candidates to gen_ai output messages.
+ *
+ * @param candidates - The `candidates` array from a `generateContent` response.
+ * @returns Array of {@link OutputMessage} objects (one per candidate that has content).
+ */
+export function convertGeminiCandidatesToOutputMessages(
+  candidates: GeminiCandidate[] | undefined,
+): OutputMessage[] {
+  if (!candidates || candidates.length === 0) return [];
+
+  const result: OutputMessage[] = [];
+  for (const cand of candidates) {
+    const role = normalizeRole(cand.content?.role || "model");
+    const parts = (cand.content?.parts || []).flatMap(partToGenAiParts);
+    if (parts.length === 0 && !cand.finishReason) continue;
+    const msg: OutputMessage = { role, parts };
+    if (cand.finishReason) msg.finish_reason = cand.finishReason;
+    result.push(msg);
+  }
+  return result;
+}
+
+/**
+ * Convert a Gemini `systemInstruction` field to gen_ai SystemInstruction[].
+ *
+ * Gemini accepts either a plain string or a {@link GeminiContent} object.
+ */
+export function convertGeminiSystemInstructionToSemconv(
+  systemInstruction: string | GeminiContent | undefined,
+): SystemInstruction[] | undefined {
+  if (!systemInstruction) return undefined;
+
+  if (typeof systemInstruction === "string") {
+    return [{ type: "text", content: systemInstruction }];
+  }
+
+  const result = (systemInstruction.parts || []).flatMap(
+    (p): SystemInstruction[] =>
+      typeof p.text === "string" && p.text.length > 0
+        ? [{ type: "text", content: p.text }]
+        : [],
+  );
+  return result.length > 0 ? result : undefined;
+}
+
+/**
+ * Convert Gemini `tools` (array of `{functionDeclarations}` entries) to gen_ai
+ * ToolDefinition[].
+ */
+export function convertGeminiToolsToToolDefinitions(
+  tools: GeminiTool[] | undefined,
+): ToolDefinition[] | undefined {
+  if (!tools || tools.length === 0) return undefined;
+
+  const defs: ToolDefinition[] = [];
+  for (const tool of tools) {
+    for (const fn of tool.functionDeclarations || []) {
+      if (!fn.name) continue;
+      const def: ToolDefinition = { name: fn.name };
+      if (fn.description) def.description = fn.description;
+      const params = fn.parametersJsonSchema ?? fn.parameters;
+      if (params) def.parameters = params;
+      defs.push(def);
+    }
+  }
+  return defs.length > 0 ? defs : undefined;
+}

package/src/converters/index.ts

@@ -24,13 +24,6 @@ export {
 
 export { isVercelAISpan, convertVercelAIToGenAI } from "./vercel.js";
 
-export {
-  convertMessagesToInputMessages as convertAISDKMessagesToInputMessages,
-  extractSystemInstructions as extractAISDKSystemInstructions,
-  buildOutputMessages as buildAISDKOutputMessages,
-  convertToolsToToolDefinitions as convertAISDKToolsToToolDefinitions,
-} from "./ai-sdk.js";
-
 export {
   convertClaudePromptToInputMessages,
   convertClaudeResponseToOutputMessages,
@@ -42,3 +35,16 @@ export {
   type ClaudeResponse,
   type ClaudeSessionData,
 } from "./claude.js";
+
+export {
+  convertGeminiContentsToInputMessages,
+  convertGeminiCandidatesToOutputMessages,
+  convertGeminiSystemInstructionToSemconv,
+  convertGeminiToolsToToolDefinitions,
+  GEMINI_PROVIDER_NAME,
+  type GeminiCandidate,
+  type GeminiContent,
+  type GeminiFunctionDeclaration,
+  type GeminiPart,
+  type GeminiTool,
+} from "./gemini.js";

package/src/converters/vercel.ts

@@ -22,7 +22,13 @@ interface VercelContentPart {
   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 {
@@ -39,6 +45,10 @@ interface GenAIPart {
   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 {
@@ -247,14 +257,42 @@ function extractParts(content: VercelMessage["content"]): GenAIPart[] {
         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 part.args === "string"
-              ? part.args
-              : JSON.stringify(part.args),
+            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) };

package/src/http.ts

@@ -0,0 +1,163 @@
+import {
+  IntrospectionAPIError,
+  NetworkError,
+  apiErrorFromResponse,
+} from "@introspection-sdk/types";
+
+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;
+}
+
+function joinUrl(base: string, path: string): string {
+  const b = base.replace(/\/+$/, "");
+  const p = path.startsWith("/") ? path : `/${path}`;
+  return `${b}${p}`;
+}
+
+function buildQuery(params?: Record<string, unknown>): string {
+  if (!params) return "";
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v === undefined || v === null) continue;
+    if (Array.isArray(v)) {
+      for (const item of v) sp.append(k, String(item));
+    } else {
+      sp.set(k, String(v));
+    }
+  }
+  const q = sp.toString();
+  return q ? `?${q}` : "";
+}
+
+/**
+ * Thin HTTP wrapper used by both the CP-bound IntrospectionClient and
+ * each DP-bound Runner. Has no opinion on which one it is — the caller
+ * picks the base URL and the token.
+ */
+export class HttpClient {
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(private readonly cfg: ResolvedApiConfig) {
+    this.fetchImpl = cfg.fetch ?? globalThis.fetch;
+    if (!this.fetchImpl) {
+      throw new Error(
+        "global fetch is unavailable; pass `advanced.fetch` or run on Node 18+",
+      );
+    }
+  }
+
+  private headers(extra?: Record<string, string>): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.cfg.token}`,
+      ...(this.cfg.additionalHeaders ?? {}),
+      ...(extra ?? {}),
+    };
+  }
+
+  async request<T>(opts: {
+    method: string;
+    path: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    expect?: "json" | "empty" | "bytes" | "stream";
+  }): Promise<T> {
+    const url = joinUrl(this.cfg.apiUrl, opts.path) + buildQuery(opts.query);
+    let body: BodyInit | undefined;
+    const headers = this.headers(opts.headers);
+    if (opts.body instanceof FormData) {
+      body = opts.body;
+      // let fetch set the multipart boundary
+    } else if (opts.body !== undefined) {
+      headers["Content-Type"] = headers["Content-Type"] ?? "application/json";
+      body = JSON.stringify(opts.body);
+    }
+    let res: Response;
+    try {
+      res = await this.fetchImpl(url, {
+        method: opts.method,
+        headers,
+        body,
+      });
+    } catch (err) {
+      throw new NetworkError({
+        message: err instanceof Error ? err.message : "network request failed",
+        code: null,
+        requestId: null,
+        body: err,
+      });
+    }
+    if (!res.ok) throw await toApiError(res);
+    const expect = opts.expect ?? "json";
+    if (expect === "empty") return undefined as T;
+    if (expect === "bytes") return new Uint8Array(await res.arrayBuffer()) as T;
+    if (expect === "stream") return res.body as T;
+    return (await res.json()) as T;
+  }
+
+  async stream(opts: {
+    path: string;
+    query?: Record<string, unknown>;
+  }): Promise<Response> {
+    const url = joinUrl(this.cfg.apiUrl, opts.path) + buildQuery(opts.query);
+    let res: Response;
+    try {
+      res = await this.fetchImpl(url, {
+        method: "GET",
+        headers: this.headers({ Accept: "text/event-stream" }),
+      });
+    } catch (err) {
+      throw new NetworkError({
+        message: err instanceof Error ? err.message : "network request failed",
+        code: null,
+        requestId: null,
+        body: err,
+      });
+    }
+    if (!res.ok) throw await toApiError(res);
+    return res;
+  }
+}
+
+async function toApiError(res: Response): Promise<IntrospectionAPIError> {
+  let body: unknown = undefined;
+  let message = `HTTP ${res.status}`;
+  let code: string | null = null;
+  const ct = res.headers.get("content-type") ?? "";
+  if (ct.includes("json")) {
+    body = await res.json().catch(() => undefined);
+    if (body && typeof body === "object") {
+      const obj = body as Record<string, unknown>;
+      if (typeof obj.detail === "string") message = obj.detail;
+      if (typeof obj.code === "string") code = obj.code;
+      if (typeof obj.message === "string" && message === `HTTP ${res.status}`) {
+        message = obj.message;
+      }
+    }
+  } else {
+    body = await res.text().catch(() => undefined);
+  }
+  const retryAfterHeader = res.headers.get("retry-after");
+  let retryAfter: number | null = null;
+  if (retryAfterHeader) {
+    const n = Number(retryAfterHeader);
+    if (Number.isFinite(n)) retryAfter = n;
+  }
+  return apiErrorFromResponse({
+    status: res.status,
+    message,
+    code,
+    requestId: res.headers.get("x-request-id"),
+    body,
+    retryAfter,
+  });
+}