@introspection-sdk/introspection-node 0.4.1 → 0.4.3

package/src/client.ts

@@ -1,513 +1,118 @@
 /**
- * Introspection Client for Node.js
- * Provides an API for tracking events and feedback using OTLP Logs.
+ * Introspection REST Client for Node.js
  *
- * Identity and gen_ai context are automatically extracted from OpenTelemetry
- * baggage.
+ * Exposes the Control Plane REST surface for managing runtimes and
+ * experiments. Calling `client.runtimes(name).run()` or
+ * `client.experiments(id).run()` returns a {@link Runner} bound to a Data
+ * Plane sandbox.
+ *
+ * This class is **REST-only** and does not depend on the OpenTelemetry
+ * SDK. For event tracking, feedback, identify, and baggage context
+ * helpers, use {@link IntrospectionLogs} from
+ * `@introspection-sdk/introspection-node/otel`.
  */
 
-import { SeverityNumber, type LogAttributes } 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 type { AdvancedOptions } from "@introspection-sdk/types";
 import { logger as sdkLogger } from "./utils.js";
-import { VERSION } from "./version.js";
+import type { IntrospectionClientOptions } from "./types.js";
+import { HttpClient } from "./http.js";
+import {
+  attachRuntimes,
+  type RuntimeHandleFactory,
+  type RuntimesApi,
+} from "./resources/runtimes.js";
 import {
-  generateEventId,
-  type IntrospectionClientOptions,
-  type FeedbackOptions,
-  type UserTraits,
-  type GenAiContext,
-  type IdentityContext,
-} from "./types.js";
+  attachExperiments,
+  type ExperimentHandleFactory,
+  type ExperimentsApi,
+} from "./resources/experiments.js";
+import { attachRecipes, type RecipesApi } from "./resources/recipes.js";
 
 /**
- * Introspection client for tracking events and feedback using OTLP Logs.
+ * Introspection REST client.
  *
  * @example
  * ```typescript
  * const client = new IntrospectionClient({
  *   token: process.env.INTROSPECTION_TOKEN,
+ *   projectId: "proj_…",
  * });
  *
- * client.identify("user_123", { email: "user@example.com" });
- * client.feedback("thumbs_up", { comments: "Great response!" });
+ * // Open a runner from a runtime, then drive it.
+ * const runner = await client.runtimes("customer-agent").run({
+ *   identity: { user_id: "u_42" },
+ * });
+ * const run = await runner.tasks.create({ prompt: "Summarize this repo" });
+ * for await (const ev of run.stream()) console.log(ev);
  *
+ * await runner.close();
  * await client.shutdown();
  * ```
  */
 export class IntrospectionClient {
-  private loggerProvider: LoggerProvider;
-  private otelLogger: ReturnType<LoggerProvider["getLogger"]>;
-  private userId: string | undefined;
-  private anonymousId: string | undefined;
-  private traits: Record<string, unknown> = {};
-
-  constructor(options: IntrospectionClientOptions = {}) {
-    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: string;
-    if (baseUrl.endsWith("/v1/logs")) {
-      endpoint = baseUrl;
-    } else {
-      endpoint = `${baseUrl.replace(/\/$/, "")}/v1/logs`;
-    }
-
-    // Build headers
-    const headers: Record<string, string> = {
-      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 */
-  private getGenAiFromContext(): GenAiContext {
-    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 */
-  private getIdentityFromContext(): IdentityContext {
-    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,
-    };
-  }
+  /** @internal — HTTP client pointed at the CP API with the customer key. */
+  readonly cpHttp: HttpClient;
+  /** @internal — passed through to Runner so it can build its own DP HTTP client. */
+  readonly advancedOptions: AdvancedOptions;
+  readonly projectId: string | undefined;
 
   /**
-   * Get current timestamp as OpenTelemetry HrTime.
-   * Uses process.hrtime.bigint() for nanosecond precision in Node.js.
+   * CRUD on `/v1/runtimes` and the `(idOrName) => RuntimeHandle` factory.
+   * Call as `client.runtimes("customer-agent").run()` or
+   * `client.runtimes.list({ project_id })`.
    */
-  private getTimestamp(): [number, number] {
-    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];
-  }
+  readonly runtimes: RuntimesApi & RuntimeHandleFactory;
 
   /**
-   * Build log record attributes.
+   * CRUD on `/v1/experiments` and the `(id) => ExperimentHandle` factory.
    */
-  private buildAttributes(
-    eventName: string,
-    options: {
-      properties?: Record<string, unknown>;
-      traits?: Record<string, unknown>;
-      conversationId?: string;
-      previousResponseId?: string;
-      eventId?: string;
-    } = {},
-  ): LogAttributes {
-    const { properties, traits, conversationId, previousResponseId, eventId } =
-      options;
-
-    // Core fields
-    const attributes: LogAttributes = {
-      "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;
-  }
+  readonly experiments: ExperimentsApi & ExperimentHandleFactory;
 
   /**
-   * 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`.
+   * CRUD on `/v1/recipes`. Recipes are immutable build artefacts
+   * (repository + git ref + commit sha) referenced by runtimes and
+   * experiment arms.
    */
-  track(
-    eventName: string,
-    properties?: Record<string, unknown>,
-    options?: { eventId?: string },
-  ): void {
-    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: string, options: FeedbackOptions = {}): void {
-    const { comments, conversationId, previousResponseId, eventId, ...extra } =
-      options;
-
-    const properties: Record<string, unknown> = { name, ...extra };
-    if (comments) {
-      properties.comments = comments;
-    }
-
-    const attributes = this.buildAttributes("introspection.feedback", {
-      properties,
-      conversationId: conversationId as string | undefined,
-      previousResponseId: previousResponseId as string | undefined,
-      eventId: eventId as string | undefined,
-    });
-
-    this.otelLogger.emit({
-      timestamp: this.getTimestamp(),
-      context: context.active(),
-      severityNumber: SeverityNumber.INFO,
-      severityText: "INFO",
-      attributes,
-    });
+  readonly recipes: RecipesApi;
 
-    sdkLogger.debug(`Feedback: ${name}`);
-  }
+  constructor(options: IntrospectionClientOptions = {}) {
+    const token = options.token || process.env.INTROSPECTION_TOKEN || "";
+    const advanced = options.advanced || {};
+    this.advancedOptions = advanced;
+    this.projectId =
+      options.projectId || process.env.INTROSPECTION_PROJECT_ID || undefined;
+    const baseApiUrl =
+      advanced.baseApiUrl ||
+      process.env.INTROSPECTION_BASE_API_URL ||
+      "https://api.introspection.dev";
 
-  /**
-   * 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: string,
-    traits?: UserTraits,
-    anonymousId?: string,
-    eventId?: string,
-  ): void {
-    this.userId = userId;
-    if (anonymousId) {
-      this.anonymousId = anonymousId;
-    }
-    if (traits) {
-      this.traits = { ...this.traits, ...traits };
+    if (!token) {
+      sdkLogger.warn(
+        "IntrospectionClient: No token provided. REST calls will fail.",
+      );
     }
 
-    const attributes = this.buildAttributes("identify", { traits, eventId });
-
-    this.otelLogger.emit({
-      timestamp: this.getTimestamp(),
-      context: context.active(),
-      severityNumber: SeverityNumber.INFO,
-      severityText: "INFO",
-      attributes,
+    // CP HTTP client — talks to the customer-facing API with the customer
+    // API key. Runners get their own HttpClient instances pointed at the
+    // `deployment.endpoint` returned by `/v1/runtimes/{id}/run`.
+    this.cpHttp = new HttpClient({
+      apiUrl: baseApiUrl,
+      token,
+      additionalHeaders: advanced.additionalHeaders,
+      fetch: advanced.fetch,
     });
 
-    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: Record<string, string>) {
-    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<T>(
-    values: Record<string, string>,
-    callback: () => T | Promise<T>,
-  ): Promise<T> {
-    const ctx = this.createBaggageContext(values);
-    return await context.with(ctx, callback);
-  }
+    this.runtimes = attachRuntimes(this, this.cpHttp);
+    this.experiments = attachExperiments(this, this.cpHttp);
+    this.recipes = attachRecipes(this.cpHttp);
 
-  /**
-   * 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<T>(
-    agentName: string,
-    agentId: string | undefined,
-    callback: () => T | Promise<T>,
-  ): Promise<T> {
-    const values: Record<string, string> = { "gen_ai.agent.name": agentName };
-    if (agentId) {
-      values["gen_ai.agent.id"] = agentId;
-    }
-    return await context.with(this.createBaggageContext(values), callback);
+    sdkLogger.info(`IntrospectionClient initialized: api=${baseApiUrl}`);
   }
 
-  /**
-   * 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<T>(
-    conversationId: string | undefined,
-    previousResponseId: string | undefined,
-    callback: () => T | Promise<T>,
-  ): Promise<T> {
-    const values: Record<string, string> = {};
-    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: string): void {
-    this.userId = userId;
-  }
-
-  /**
-   * Set the anonymous ID on this client instance.
-   *
-   * @param anonymousId - Anonymous identifier used before authentication.
-   */
-  setAnonymousId(anonymousId: string): void {
-    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<T>(
-    userId: string,
-    callback: () => T | Promise<T>,
-  ): Promise<T> {
-    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<T>(
-    anonymousId: string,
-    callback: () => T | Promise<T>,
-  ): Promise<T> {
-    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(): string | undefined {
-    return this.anonymousId;
-  }
-
-  /**
-   * Reset all client-side state (user ID, anonymous ID, and traits).
-   */
-  reset(): void {
-    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(): Promise<void> {
-    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.
-   */
+  /** Close the underlying HTTP client. */
   async shutdown(): Promise<void> {
-    await this.loggerProvider.shutdown();
+    // HttpClient has no persistent connections to close, but reserved
+    // for future use (e.g. agent keep-alive pools).
     sdkLogger.debug("IntrospectionClient shutdown complete");
   }
 }

package/src/converters/claude.ts

@@ -228,6 +228,10 @@ export interface ClaudeSessionData {
   toolNames?: string[];
   /** System instructions / system prompt */
   systemInstructions?: string;
+  /** Tokens read from the LLM prompt cache */
+  cacheReadInputTokens?: number;
+  /** Tokens written to the LLM prompt cache */
+  cacheCreationInputTokens?: number;
 }
 
 /**
@@ -280,6 +284,12 @@ export function convertClaudeSessionToGenAI(
   if (data.outputTokens !== undefined) {
     result.outputTokens = data.outputTokens;
   }
+  if (data.cacheReadInputTokens !== undefined) {
+    result.cacheReadInputTokens = data.cacheReadInputTokens;
+  }
+  if (data.cacheCreationInputTokens !== undefined) {
+    result.cacheCreationInputTokens = data.cacheCreationInputTokens;
+  }
 
   // Set response ID
   if (data.responseId) {
@@ -318,7 +328,7 @@ export function convertClaudeSessionToGenAI(
  */
 export function convertClaudeSessionToOtelAttributes(
   data: ClaudeSessionData,
-): Record<string, string | number> {
+): Record<string, string | number | string[] | number[]> {
   const genaiAttrs = convertClaudeSessionToGenAI(data);
   const result = toAttributes(genaiAttrs);