@introspection-sdk/introspection-node 0.4.0

package/dist/client.js

@@ -0,0 +1,394 @@
+/**
+ * Introspection Client for Node.js
+ * Provides an API for tracking events and feedback using OTLP Logs.
+ *
+ * Identity and gen_ai context are automatically extracted from OpenTelemetry
+ * baggage.
+ */
+import { SeverityNumber } from "@opentelemetry/api-logs";
+import { LoggerProvider, BatchLogRecordProcessor, } from "@opentelemetry/sdk-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
+import { resourceFromAttributes, defaultResource, } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { propagation, context } from "@opentelemetry/api";
+import { logger as sdkLogger } from "./utils.js";
+import { VERSION } from "./version.js";
+import { generateEventId, } from "./types.js";
+/**
+ * Introspection client for tracking events and feedback using OTLP Logs.
+ *
+ * @example
+ * ```typescript
+ * const client = new IntrospectionClient({
+ *   token: process.env.INTROSPECTION_TOKEN,
+ * });
+ *
+ * client.identify("user_123", { email: "user@example.com" });
+ * client.feedback("thumbs_up", { comments: "Great response!" });
+ *
+ * await client.shutdown();
+ * ```
+ */
+export class IntrospectionClient {
+    loggerProvider;
+    otelLogger;
+    userId;
+    anonymousId;
+    traits = {};
+    constructor(options = {}) {
+        const token = options.token || process.env.INTROSPECTION_TOKEN || "";
+        const serviceName = options.serviceName ||
+            process.env.INTROSPECTION_SERVICE_NAME ||
+            "introspection-client";
+        const advanced = options.advanced || {};
+        const baseUrl = advanced.baseUrl ||
+            process.env.INTROSPECTION_BASE_URL ||
+            "https://otel.introspection.dev";
+        if (!token) {
+            sdkLogger.warn("IntrospectionClient: No token provided. Events will not be sent.");
+        }
+        // Construct endpoint URL for logs
+        let endpoint;
+        if (baseUrl.endsWith("/v1/logs")) {
+            endpoint = baseUrl;
+        }
+        else {
+            endpoint = `${baseUrl.replace(/\/$/, "")}/v1/logs`;
+        }
+        // Build headers
+        const headers = {
+            Authorization: `Bearer ${token}`,
+        };
+        if (advanced.additionalHeaders) {
+            Object.assign(headers, advanced.additionalHeaders);
+        }
+        // Create OTLP log exporter
+        const exporter = new OTLPLogExporter({
+            url: endpoint,
+            headers,
+        });
+        // Create batch processor
+        const processor = new BatchLogRecordProcessor(exporter, {
+            maxQueueSize: advanced.maxBatchSize ?? 100,
+            scheduledDelayMillis: advanced.flushInterval ?? 5000,
+        });
+        // Get default resource and merge with our service name
+        const baseResource = defaultResource();
+        const introspectionResource = resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: serviceName,
+        });
+        const resource = baseResource.merge(introspectionResource);
+        // Create logger provider
+        this.loggerProvider = new LoggerProvider({
+            resource,
+            processors: [processor],
+        });
+        this.otelLogger = this.loggerProvider.getLogger("@introspection-sdk/introspection-node", VERSION);
+        sdkLogger.info(`IntrospectionClient initialized: service=${serviceName}, endpoint=${endpoint}`);
+    }
+    /** Get gen_ai context from baggage */
+    getGenAiFromContext() {
+        const baggage = propagation.getBaggage(context.active());
+        return {
+            conversationId: baggage?.getEntry("gen_ai.conversation.id")?.value,
+            previousResponseId: baggage?.getEntry("gen_ai.request.previous_response_id")?.value,
+            agentName: baggage?.getEntry("gen_ai.agent.name")?.value,
+            agentId: baggage?.getEntry("gen_ai.agent.id")?.value,
+        };
+    }
+    /** Get identity from baggage or client instance */
+    getIdentityFromContext() {
+        const baggage = propagation.getBaggage(context.active());
+        return {
+            userId: baggage?.getEntry("identity.user_id")?.value || this.userId,
+            anonymousId: baggage?.getEntry("identity.anonymous_id")?.value || this.anonymousId,
+        };
+    }
+    /**
+     * Get current timestamp as OpenTelemetry HrTime.
+     * Uses process.hrtime.bigint() for nanosecond precision in Node.js.
+     */
+    getTimestamp() {
+        const hrTimeNs = process.hrtime.bigint();
+        const epochNs = BigInt(Date.now()) * BigInt(1_000_000);
+        const offsetNs = hrTimeNs - process.hrtime.bigint() + epochNs;
+        const seconds = Number(offsetNs / BigInt(1_000_000_000));
+        const nanos = Number(offsetNs % BigInt(1_000_000_000));
+        return [seconds, nanos];
+    }
+    /**
+     * Build log record attributes.
+     */
+    buildAttributes(eventName, options = {}) {
+        const { properties, traits, conversationId, previousResponseId, eventId } = options;
+        // Core fields
+        const attributes = {
+            "event.name": eventName,
+            "event.id": eventId || generateEventId(),
+        };
+        // Identity
+        const identity = this.getIdentityFromContext();
+        if (identity.userId) {
+            attributes["identity.user.id"] = identity.userId;
+        }
+        if (identity.anonymousId) {
+            attributes["identity.anonymous.id"] = identity.anonymousId;
+        }
+        // Gen AI context (explicit params override baggage)
+        const genAi = this.getGenAiFromContext();
+        const finalConversationId = conversationId || genAi.conversationId;
+        const finalPreviousResponseId = previousResponseId || genAi.previousResponseId;
+        if (finalConversationId) {
+            attributes["gen_ai.conversation.id"] = finalConversationId;
+        }
+        if (finalPreviousResponseId) {
+            attributes["gen_ai.request.previous_response_id"] =
+                finalPreviousResponseId;
+        }
+        if (genAi.agentName) {
+            attributes["gen_ai.agent.name"] = genAi.agentName;
+        }
+        if (genAi.agentId) {
+            attributes["gen_ai.agent.id"] = genAi.agentId;
+        }
+        // Flatten properties with "properties." prefix
+        if (properties) {
+            for (const [key, value] of Object.entries(properties)) {
+                if (value != null) {
+                    const attrKey = `properties.${key}`;
+                    if (typeof value === "object") {
+                        attributes[attrKey] = JSON.stringify(value);
+                    }
+                    else if (typeof value === "string" ||
+                        typeof value === "number" ||
+                        typeof value === "boolean") {
+                        attributes[attrKey] = value;
+                    }
+                }
+            }
+        }
+        // Flatten traits with "context.traits." prefix
+        if (traits) {
+            for (const [key, value] of Object.entries(traits)) {
+                if (value != null) {
+                    const attrKey = `context.traits.${key}`;
+                    if (typeof value === "object") {
+                        attributes[attrKey] = JSON.stringify(value);
+                    }
+                    else if (typeof value === "string" ||
+                        typeof value === "number" ||
+                        typeof value === "boolean") {
+                        attributes[attrKey] = value;
+                    }
+                }
+            }
+        }
+        return attributes;
+    }
+    /**
+     * Track a custom event.
+     *
+     * @param eventName - A descriptive name for the event (e.g. `"page_view"`).
+     * @param properties - Arbitrary key/value pairs attached to the event.
+     * @param options - Optional overrides such as a custom `eventId`.
+     */
+    track(eventName, properties, options) {
+        const attributes = this.buildAttributes(eventName, {
+            properties,
+            eventId: options?.eventId,
+        });
+        this.otelLogger.emit({
+            timestamp: this.getTimestamp(),
+            context: context.active(),
+            severityNumber: SeverityNumber.INFO,
+            severityText: "INFO",
+            attributes,
+        });
+        sdkLogger.debug(`Tracked: ${eventName}`);
+    }
+    /**
+     * Track feedback on a message or response.
+     *
+     * @param name - Feedback type (e.g. `"thumbs_up"`, `"thumbs_down"`).
+     * @param options - Additional feedback context such as comments or conversation ID.
+     */
+    feedback(name, options = {}) {
+        const { comments, conversationId, previousResponseId, eventId, ...extra } = options;
+        const properties = { name, ...extra };
+        if (comments) {
+            properties.comments = comments;
+        }
+        const attributes = this.buildAttributes("introspection.feedback", {
+            properties,
+            conversationId: conversationId,
+            previousResponseId: previousResponseId,
+            eventId: eventId,
+        });
+        this.otelLogger.emit({
+            timestamp: this.getTimestamp(),
+            context: context.active(),
+            severityNumber: SeverityNumber.INFO,
+            severityText: "INFO",
+            attributes,
+        });
+        sdkLogger.debug(`Feedback: ${name}`);
+    }
+    /**
+     * Identify a user and associate traits with them.
+     *
+     * @param userId - Unique identifier for the user.
+     * @param traits - Key/value user properties (e.g. `{ email: "…" }`).
+     * @param anonymousId - Optional anonymous identifier to link pre-auth sessions.
+     * @param eventId - Optional custom event ID override.
+     */
+    identify(userId, traits, anonymousId, eventId) {
+        this.userId = userId;
+        if (anonymousId) {
+            this.anonymousId = anonymousId;
+        }
+        if (traits) {
+            this.traits = { ...this.traits, ...traits };
+        }
+        const attributes = this.buildAttributes("identify", { traits, eventId });
+        this.otelLogger.emit({
+            timestamp: this.getTimestamp(),
+            context: context.active(),
+            severityNumber: SeverityNumber.INFO,
+            severityText: "INFO",
+            attributes,
+        });
+        sdkLogger.debug(`Identified: ${userId}`);
+    }
+    /**
+     * Create an OTel context with the given baggage values set.
+     *
+     * @param values - Key/value pairs to store in OTel baggage.
+     * @returns A new context containing the baggage entries.
+     */
+    createBaggageContext(values) {
+        const ctx = context.active();
+        let bag = propagation.getBaggage(ctx) || propagation.createBaggage();
+        for (const [key, value] of Object.entries(values)) {
+            bag = bag.setEntry(key, { value });
+        }
+        return propagation.setBaggage(ctx, bag);
+    }
+    /**
+     * Set multiple baggage values and run a callback within that context.
+     *
+     * @param values - Key/value pairs to store in OTel baggage.
+     * @param callback - Function to execute with the baggage context active.
+     * @returns The value returned by `callback`.
+     */
+    async withBaggage(values, callback) {
+        const ctx = this.createBaggageContext(values);
+        return await context.with(ctx, callback);
+    }
+    /**
+     * Set `gen_ai.agent.name` (and optionally `gen_ai.agent.id`) baggage and run
+     * a callback within that context.
+     *
+     * @param agentName - The agent name to propagate.
+     * @param agentId - Optional agent identifier.
+     * @param callback - Function to execute with the agent baggage active.
+     * @returns The value returned by `callback`.
+     */
+    async withAgent(agentName, agentId, callback) {
+        const values = { "gen_ai.agent.name": agentName };
+        if (agentId) {
+            values["gen_ai.agent.id"] = agentId;
+        }
+        return await context.with(this.createBaggageContext(values), callback);
+    }
+    /**
+     * Set conversation-related baggage (`gen_ai.conversation.id`,
+     * `gen_ai.request.previous_response_id`) and run a callback within that
+     * context.
+     *
+     * @param conversationId - The conversation identifier.
+     * @param previousResponseId - The ID of the previous response in the conversation.
+     * @param callback - Function to execute with the conversation baggage active.
+     * @returns The value returned by `callback`.
+     */
+    async withConversation(conversationId, previousResponseId, callback) {
+        const values = {};
+        if (conversationId) {
+            values["gen_ai.conversation.id"] = conversationId;
+        }
+        if (previousResponseId) {
+            values["gen_ai.request.previous_response_id"] = previousResponseId;
+        }
+        return await context.with(this.createBaggageContext(values), callback);
+    }
+    /**
+     * Set the user ID on this client instance.
+     *
+     * @param userId - Unique identifier for the user.
+     */
+    setUserId(userId) {
+        this.userId = userId;
+    }
+    /**
+     * Set the anonymous ID on this client instance.
+     *
+     * @param anonymousId - Anonymous identifier used before authentication.
+     */
+    setAnonymousId(anonymousId) {
+        this.anonymousId = anonymousId;
+    }
+    /**
+     * Set `identity.user_id` baggage and run a callback within that context.
+     *
+     * @param userId - The user identifier to propagate.
+     * @param callback - Function to execute with the user-ID baggage active.
+     * @returns The value returned by `callback`.
+     */
+    async withUserId(userId, callback) {
+        return await context.with(this.createBaggageContext({ "identity.user_id": userId }), callback);
+    }
+    /**
+     * Set `identity.anonymous_id` baggage and run a callback within that context.
+     *
+     * @param anonymousId - The anonymous identifier to propagate.
+     * @param callback - Function to execute with the anonymous-ID baggage active.
+     * @returns The value returned by `callback`.
+     */
+    async withAnonymousId(anonymousId, callback) {
+        return await context.with(this.createBaggageContext({ "identity.anonymous_id": anonymousId }), callback);
+    }
+    /**
+     * Get the current anonymous ID stored on this client instance.
+     *
+     * @returns The anonymous ID, or `undefined` if not set.
+     */
+    getAnonymousId() {
+        return this.anonymousId;
+    }
+    /**
+     * Reset all client-side state (user ID, anonymous ID, and traits).
+     */
+    reset() {
+        this.userId = undefined;
+        this.anonymousId = undefined;
+        this.traits = {};
+        sdkLogger.debug("Client state reset");
+    }
+    /**
+     * Flush all queued log records to the backend.
+     *
+     * @returns A promise that resolves once the flush completes.
+     */
+    async flush() {
+        await this.loggerProvider.forceFlush();
+        sdkLogger.debug("Flushed pending log records");
+    }
+    /**
+     * Shut down the client, flushing all pending log records.
+     *
+     * @returns A promise that resolves once shutdown is complete.
+     */
+    async shutdown() {
+        await this.loggerProvider.shutdown();
+        sdkLogger.debug("IntrospectionClient shutdown complete");
+    }
+}

package/dist/converters/ai-sdk.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Converter for AI SDK event data → Gen AI semantic conventions.
+ *
+ * Converts typed event objects (messages, tool definitions, step results)
+ * from the AI SDK's TelemetryIntegration callbacks into the standardized
+ * gen_ai format used by the Introspection backend.
+ *
+ * Used by {@link IntrospectionAISDKIntegration}.
+ */
+import type { InputMessage, OutputMessage, SystemInstruction, ToolDefinition } from "../types/genai.js";
+/**
+ * Convert AI SDK messages (ModelMessage[]) to gen_ai InputMessage[].
+ * System messages are excluded — they're handled separately via
+ * {@link extractSystemInstructions}.
+ *
+ * @param messages - Array of AI SDK ModelMessage objects.
+ * @returns Array of gen_ai InputMessage objects (without system messages).
+ */
+export declare function convertMessagesToInputMessages(messages: readonly unknown[]): InputMessage[];
+/**
+ * Extract gen_ai system instructions from AI SDK's system field and messages.
+ *
+ * The AI SDK provides system prompts in two places:
+ * - The `system` parameter (string, SystemModelMessage, or array)
+ * - Messages with role "system"
+ *
+ * @param system - The AI SDK `system` field.
+ * @param messages - The messages array (may contain system-role messages).
+ * @returns System instructions in gen_ai format, or undefined if none.
+ */
+export declare function extractSystemInstructions(system: unknown, messages: readonly unknown[]): SystemInstruction[] | undefined;
+/**
+ * Build gen_ai output messages from AI SDK step result data.
+ *
+ * Combines text, reasoning, and tool call outputs into a single assistant
+ * OutputMessage, mirroring the order used by vercel.ts (reasoning → text → tool calls).
+ *
+ * @param options - Step result fields.
+ * @returns Array of gen_ai OutputMessage objects.
+ */
+export declare function buildOutputMessages(options: {
+    text?: string;
+    reasoningText?: string;
+    reasoning?: readonly {
+        text?: string;
+    }[];
+    toolCalls?: readonly {
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    }[];
+    finishReason?: string;
+}): OutputMessage[];
+/**
+ * Convert AI SDK ToolSet to gen_ai ToolDefinition[].
+ *
+ * The AI SDK represents tools as `Record<string, Tool>` where each Tool has
+ * description and parameters (usually a Zod schema). We extract what we can
+ * without importing Zod.
+ *
+ * @param tools - AI SDK ToolSet (Record<string, Tool>).
+ * @returns Array of gen_ai ToolDefinition objects, or undefined if no tools.
+ */
+export declare function convertToolsToToolDefinitions(tools: unknown): ToolDefinition[] | undefined;
+//# sourceMappingURL=ai-sdk.d.ts.map

package/dist/converters/ai-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.d.ts","sourceRoot":"","sources":["../../src/converters/ai-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAuB3B;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,YAAY,EAAE,CAQhB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,iBAAiB,EAAE,GAAG,SAAS,CAoCjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,SAAS;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzC,SAAS,CAAC,EAAE,SAAS;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,OAAO,CAAC;KAChB,EAAE,CAAC;IACJ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,aAAa,EAAE,CAuClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,GACb,cAAc,EAAE,GAAG,SAAS,CAgB9B"}

package/dist/converters/ai-sdk.js

@@ -0,0 +1,238 @@
+/**
+ * Converter for AI SDK event data → Gen AI semantic conventions.
+ *
+ * Converts typed event objects (messages, tool definitions, step results)
+ * from the AI SDK's TelemetryIntegration callbacks into the standardized
+ * gen_ai format used by the Introspection backend.
+ *
+ * Used by {@link IntrospectionAISDKIntegration}.
+ */
+// ---------------------------------------------------------------------------
+// Public conversion functions
+// ---------------------------------------------------------------------------
+/**
+ * Convert AI SDK messages (ModelMessage[]) to gen_ai InputMessage[].
+ * System messages are excluded — they're handled separately via
+ * {@link extractSystemInstructions}.
+ *
+ * @param messages - Array of AI SDK ModelMessage objects.
+ * @returns Array of gen_ai InputMessage objects (without system messages).
+ */
+export function convertMessagesToInputMessages(messages) {
+    const result = [];
+    for (const msg of messages) {
+        const m = msg;
+        if (!m || !m.role || m.role === "system")
+            continue;
+        result.push(convertOneMessage(m));
+    }
+    return result;
+}
+/**
+ * Extract gen_ai system instructions from AI SDK's system field and messages.
+ *
+ * The AI SDK provides system prompts in two places:
+ * - The `system` parameter (string, SystemModelMessage, or array)
+ * - Messages with role "system"
+ *
+ * @param system - The AI SDK `system` field.
+ * @param messages - The messages array (may contain system-role messages).
+ * @returns System instructions in gen_ai format, or undefined if none.
+ */
+export function extractSystemInstructions(system, messages) {
+    const instructions = [];
+    // From the `system` field
+    if (typeof system === "string" && system) {
+        instructions.push({ type: "text", content: system });
+    }
+    else if (system && typeof system === "object") {
+        if (Array.isArray(system)) {
+            for (const s of system) {
+                const text = extractTextFromSystemMessage(s);
+                if (text)
+                    instructions.push({ type: "text", content: text });
+            }
+        }
+        else {
+            const text = extractTextFromSystemMessage(system);
+            if (text)
+                instructions.push({ type: "text", content: text });
+        }
+    }
+    // From system-role messages
+    for (const msg of messages) {
+        const m = msg;
+        if (m?.role === "system") {
+            const content = m.content;
+            if (typeof content === "string") {
+                instructions.push({ type: "text", content });
+            }
+            else if (Array.isArray(content)) {
+                const text = content
+                    .filter((p) => p.type === "text")
+                    .map((p) => p.text || "")
+                    .join("");
+                if (text)
+                    instructions.push({ type: "text", content: text });
+            }
+        }
+    }
+    return instructions.length > 0 ? instructions : undefined;
+}
+/**
+ * Build gen_ai output messages from AI SDK step result data.
+ *
+ * Combines text, reasoning, and tool call outputs into a single assistant
+ * OutputMessage, mirroring the order used by vercel.ts (reasoning → text → tool calls).
+ *
+ * @param options - Step result fields.
+ * @returns Array of gen_ai OutputMessage objects.
+ */
+export function buildOutputMessages(options) {
+    const parts = [];
+    // Reasoning first (mirrors vercel.ts order)
+    if (options.reasoningText) {
+        parts.push({ type: "thinking", content: options.reasoningText });
+    }
+    else if (options.reasoning?.length) {
+        for (const r of options.reasoning) {
+            if (r.text)
+                parts.push({ type: "thinking", content: r.text });
+        }
+    }
+    // Text content
+    if (options.text) {
+        parts.push({ type: "text", content: options.text });
+    }
+    // Tool calls
+    if (options.toolCalls?.length) {
+        for (const tc of options.toolCalls) {
+            parts.push({
+                type: "tool_call",
+                name: tc.toolName,
+                id: tc.toolCallId,
+                arguments: typeof tc.input === "string" ? tc.input : JSON.stringify(tc.input),
+            });
+        }
+    }
+    if (parts.length === 0)
+        return [];
+    return [
+        {
+            role: "assistant",
+            parts,
+            finish_reason: options.finishReason,
+        },
+    ];
+}
+/**
+ * Convert AI SDK ToolSet to gen_ai ToolDefinition[].
+ *
+ * The AI SDK represents tools as `Record<string, Tool>` where each Tool has
+ * description and parameters (usually a Zod schema). We extract what we can
+ * without importing Zod.
+ *
+ * @param tools - AI SDK ToolSet (Record<string, Tool>).
+ * @returns Array of gen_ai ToolDefinition objects, or undefined if no tools.
+ */
+export function convertToolsToToolDefinitions(tools) {
+    if (!tools || typeof tools !== "object")
+        return undefined;
+    const defs = [];
+    for (const [name, tool] of Object.entries(tools)) {
+        if (!tool || typeof tool !== "object")
+            continue;
+        const t = tool;
+        defs.push({
+            name,
+            description: typeof t.description === "string" ? t.description : undefined,
+            parameters: extractToolParameters(t.parameters),
+        });
+    }
+    return defs.length > 0 ? defs : undefined;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function convertOneMessage(msg) {
+    const role = (msg.role || "user");
+    const content = msg.content;
+    const parts = [];
+    if (typeof content === "string") {
+        parts.push({ type: "text", content });
+    }
+    else if (Array.isArray(content)) {
+        for (const part of content) {
+            const converted = convertContentPart(part);
+            if (converted)
+                parts.push(converted);
+        }
+    }
+    return { role, parts };
+}
+function convertContentPart(part) {
+    switch (part.type) {
+        case "text":
+            return { type: "text", content: part.text || "" };
+        case "tool-call": {
+            const args = part.args ?? part.input;
+            return {
+                type: "tool_call",
+                name: part.toolName || "",
+                id: part.toolCallId || "",
+                arguments: typeof args === "string" ? args : JSON.stringify(args ?? {}),
+            };
+        }
+        case "tool-result": {
+            const rawResult = part.result ?? part.output;
+            let response;
+            if (typeof rawResult === "string") {
+                response = rawResult;
+            }
+            else if (rawResult &&
+                typeof rawResult === "object" &&
+                "value" in rawResult) {
+                response = JSON.stringify(rawResult.value);
+            }
+            else {
+                response = JSON.stringify(rawResult);
+            }
+            return {
+                type: "tool_call_response",
+                id: part.toolCallId || "",
+                response,
+            };
+        }
+        case "reasoning":
+            return { type: "thinking", content: part.text || "" };
+        default:
+            // Unknown part type — serialize as text fallback
+            return { type: "text", content: JSON.stringify(part) };
+    }
+}
+function extractTextFromSystemMessage(msg) {
+    if (typeof msg === "string")
+        return msg;
+    if (msg && typeof msg === "object") {
+        const m = msg;
+        if (typeof m.content === "string")
+            return m.content;
+        if (typeof m.text === "string")
+            return m.text;
+    }
+    return null;
+}
+function extractToolParameters(parameters) {
+    if (!parameters || typeof parameters !== "object")
+        return undefined;
+    const p = parameters;
+    // jsonSchema() wrapper — has a jsonSchema property
+    if (p.jsonSchema && typeof p.jsonSchema === "object") {
+        return p.jsonSchema;
+    }
+    // Plain JSON Schema object (has 'type' and 'properties')
+    if (p.type === "object" && p.properties) {
+        return p;
+    }
+    return undefined;
+}