@introspection-sdk/introspection-node 0.4.9 → 0.5.0

package/src/runner-resources/conversations.ts

@@ -0,0 +1,198 @@
+import type {
+  ConversationItem,
+  ConversationItemInclude,
+  ConversationItemList,
+  ConversationItemListParams,
+  ConversationListParams,
+  ConversationResponse,
+  ConversationSummary,
+  MessagePart,
+  Paginated,
+  ToolCallResponsePart,
+} from "@introspection-sdk/types";
+import { HttpClient } from "../http.js";
+
+/** Includes requested when building a {@link ConversationResponse}. */
+const RESPONSE_INCLUDES: ConversationItemInclude[] = [
+  "gen_ai.input.messages",
+  "gen_ai.system_instructions",
+  "gen_ai.tool.definitions",
+];
+
+/**
+ * Items of a conversation (`/v1/conversations/{id}/items`). Read-only.
+ *
+ * Paging is OpenAI-style underneath: the envelope has NO `next` token —
+ * `list()` drives `after` = the previous page's `last_id` while
+ * `has_more` is true.
+ */
+export class ConversationItemsApi {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Iterate items of a conversation. Pages are fetched lazily as the
+   * iterator is consumed (`limit` sets the page size, `after` the
+   * starting cursor); stop early to stop fetching. Pass
+   * `order: "asc"` to walk the transcript from the start.
+   *
+   * Items carry the turn-local delta in `input_messages` — only the
+   * messages new to that turn. Use `get()` for the full input history.
+   */
+  async *list(
+    conversationId: string,
+    params?: ConversationItemListParams,
+  ): AsyncIterable<ConversationItem> {
+    let after: string | undefined = params?.after;
+    for (;;) {
+      const page = await this.http.request<ConversationItemList>({
+        method: "GET",
+        path: `/v1/conversations/${encodeURIComponent(conversationId)}/items`,
+        query: { ...params, after } as Record<string, unknown>,
+      });
+      for (const item of page.data) yield item;
+      if (!page.has_more || page.last_id === null) return;
+      after = page.last_id;
+    }
+  }
+
+  /**
+   * Fetch a single conversation item. Unlike the list route, the
+   * detail's `input_messages` is the FULL input history for that span.
+   */
+  get(
+    conversationId: string,
+    itemId: string,
+    params?: { include?: ConversationItemInclude[] },
+  ): Promise<ConversationItem> {
+    return this.http.request<ConversationItem>({
+      method: "GET",
+      path: `/v1/conversations/${encodeURIComponent(conversationId)}/items/${encodeURIComponent(itemId)}`,
+      query: params as Record<string, unknown> | undefined,
+    });
+  }
+}
+
+/**
+ * Read-only Conversations API (`/v1/conversations`).
+ *
+ * Both `list()` and `items.list()` are auto-paging async generators,
+ * but they drive different wire protocols underneath: `list()` walks
+ * the standard Introspection cursor envelope's opaque `next` token,
+ * while `items.list()` walks an OpenAI-style envelope via `after` =
+ * the previous page's `last_id` while `has_more` is true.
+ */
+export class ConversationsApi {
+  /** Items of a conversation — `conversations.items.list(...)` etc. */
+  readonly items: ConversationItemsApi;
+
+  constructor(private readonly http: HttpClient) {
+    this.items = new ConversationItemsApi(http);
+  }
+
+  /**
+   * Iterate conversation summaries matching `params`. Pages are fetched
+   * lazily as the iterator is consumed (`limit` sets the page size,
+   * `next` the starting cursor); stop early to stop fetching.
+   */
+  async *list(
+    params?: ConversationListParams,
+  ): AsyncIterable<ConversationSummary> {
+    let next: string | undefined = params?.next;
+    do {
+      const page = await this.http.request<Paginated<ConversationSummary>>({
+        method: "GET",
+        path: "/v1/conversations",
+        query: { ...params, next } as Record<string, unknown>,
+      });
+      for (const c of page.records) yield c;
+      next = page.next ?? undefined;
+    } while (next);
+  }
+
+  /**
+   * Responses-API-style retrieve: load the state of a conversation as of
+   * one item — the full input history, output, system instructions, and
+   * tool definitions of that turn.
+   *
+   * When `itemId` is omitted, the latest LLM turn is used: the first
+   * item (in descending order) whose `node_type` is `"assistant"` or
+   * whose `operation_name` is `"chat"`, falling back to the first item
+   * with a non-null `output_message`. Returns `null` when the
+   * conversation has no items.
+   *
+   * For the full per-turn transcript instead, iterate
+   * `items.list(conversationId, { order: "asc" })`.
+   */
+  async retrieve(
+    conversationId: string,
+    itemId?: string,
+  ): Promise<ConversationResponse | null> {
+    const targetId = itemId ?? (await this.findLatestTurnId(conversationId));
+    if (targetId === null) return null;
+
+    const detail = await this.items.get(conversationId, targetId, {
+      include: RESPONSE_INCLUDES,
+    });
+    const outputMessages =
+      detail.gen_ai_output_messages ??
+      (detail.output_message ? [detail.output_message] : []);
+    return {
+      conversation_id: conversationId,
+      response_id: detail.response_id ?? null,
+      item_id: detail.id,
+      created_at: detail.created_at,
+      model:
+        detail.model_name ??
+        detail.response_model ??
+        detail.request_model ??
+        null,
+      provider_name: detail.provider_name ?? null,
+      // The single-item route returns the FULL input history here.
+      input_messages: normalizeMessages(detail.input_messages),
+      output_messages: normalizeMessages(outputMessages),
+      system_instructions: detail.system_instructions ?? null,
+      tool_definitions: detail.tool_definitions ?? null,
+    };
+  }
+
+  /** Scan items in descending order for the most recent LLM turn. */
+  private async findLatestTurnId(
+    conversationId: string,
+  ): Promise<string | null> {
+    let fallback: ConversationItem | null = null;
+    for await (const item of this.items.list(conversationId, {
+      order: "desc",
+    })) {
+      if (item.node_type === "assistant" || item.operation_name === "chat") {
+        return item.id;
+      }
+      if (fallback === null && item.output_message != null) fallback = item;
+    }
+    return fallback?.id ?? null;
+  }
+}
+
+/**
+ * Defensive normalization for {@link ConversationsApi.retrieve} only:
+ * older DP deployments emitted `tool_call_response` parts with a legacy
+ * `result` key instead of the semconv `response` key. Map it across so
+ * replayed history is always semconv-shaped.
+ */
+function normalizeMessages<T extends { parts: MessagePart[] }>(
+  messages: T[],
+): T[] {
+  return messages.map((message) => ({
+    ...message,
+    parts: message.parts.map(normalizePart),
+  }));
+}
+
+function normalizePart(part: MessagePart): MessagePart {
+  if (part.type !== "tool_call_response") return part;
+  const legacy = part as ToolCallResponsePart & { result?: unknown };
+  if (legacy.response !== undefined || legacy.result === undefined) {
+    return part;
+  }
+  const { result, ...rest } = legacy;
+  return { ...rest, response: result };
+}

package/src/runner-resources/files.ts

@@ -21,21 +21,21 @@ export type FileUploadBody =
 export class FileVersionsApi {
   constructor(private readonly http: HttpClient) {}
 
-  list(fileId: string, params?: ListParams): Promise<Paginated<FileResource>> {
-    return this.http.request<Paginated<FileResource>>({
-      method: "GET",
-      path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
-      query: params as Record<string, unknown> | undefined,
-    });
-  }
-
-  async *listAll(
+  /**
+   * Iterate versions of a file. Pages are fetched lazily as the
+   * iterator is consumed; stop early to stop fetching.
+   */
+  async *list(
     fileId: string,
     params?: ListParams,
   ): AsyncIterable<FileResource> {
     let next: string | undefined = params?.next;
     do {
-      const page = await this.list(fileId, { ...params, next });
+      const page = await this.http.request<Paginated<FileResource>>({
+        method: "GET",
+        path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
+        query: { ...params, next } as Record<string, unknown>,
+      });
       for (const f of page.records) yield f;
       next = page.next ?? undefined;
     } while (next);
@@ -65,18 +65,19 @@ export class FilesApi {
     this.versions = new FileVersionsApi(http);
   }
 
-  list(params?: FileListParams): Promise<Paginated<FileResource>> {
-    return this.http.request<Paginated<FileResource>>({
-      method: "GET",
-      path: "/v1/files",
-      query: params as Record<string, unknown> | undefined,
-    });
-  }
-
-  async *listAll(params?: FileListParams): AsyncIterable<FileResource> {
+  /**
+   * Iterate files matching `params`. Pages are fetched lazily as the
+   * iterator is consumed (`limit` sets the page size, `next` the
+   * starting cursor); stop early to stop fetching.
+   */
+  async *list(params?: FileListParams): AsyncIterable<FileResource> {
     let next: string | undefined = params?.next;
     do {
-      const page = await this.list({ ...params, next });
+      const page = await this.http.request<Paginated<FileResource>>({
+        method: "GET",
+        path: "/v1/files",
+        query: { ...params, next } as Record<string, unknown>,
+      });
       for (const f of page.records) yield f;
       next = page.next ?? undefined;
     } while (next);

package/src/runner-resources/tasks.ts

@@ -84,18 +84,19 @@ export class TasksApi {
     this.runs = new TaskRunsApi(http);
   }
 
-  list(params?: TaskListParams): Promise<Paginated<Task>> {
-    return this.http.request<Paginated<Task>>({
-      method: "GET",
-      path: "/v1/tasks",
-      query: params as Record<string, unknown> | undefined,
-    });
-  }
-
-  async *listAll(params?: TaskListParams): AsyncIterable<Task> {
+  /**
+   * Iterate tasks matching `params`. Pages are fetched lazily as the
+   * iterator is consumed (`limit` sets the page size, `next` the
+   * starting cursor); stop early to stop fetching.
+   */
+  async *list(params?: TaskListParams): AsyncIterable<Task> {
     let next: string | undefined = params?.next;
     do {
-      const page = await this.list({ ...params, next });
+      const page = await this.http.request<Paginated<Task>>({
+        method: "GET",
+        path: "/v1/tasks",
+        query: { ...params, next } as Record<string, unknown>,
+      });
       for (const t of page.records) yield t;
       next = page.next ?? undefined;
     } while (next);

package/src/runner.ts

@@ -9,6 +9,7 @@ import {
 import { HttpClient } from "./http.js";
 import { TasksApi } from "./runner-resources/tasks.js";
 import { FilesApi } from "./runner-resources/files.js";
+import { ConversationsApi } from "./runner-resources/conversations.js";
 import type { IntrospectionClient } from "./client.js";
 
 /**
@@ -23,7 +24,7 @@ export type RunnerSource =
 /**
  * Live handle to a Data Plane sandbox. Holds the bearer JWT, the DP
  * endpoint URL, and the runtime/experiment context, and exposes the
- * runner-bound `tasks` and `files` namespaces.
+ * runner-bound `tasks`, `files`, and `conversations` namespaces.
  *
  * In v1 of the agent-session-based design, token refresh is handled
  * server-side by the DP materializer attached to the agent session — the
@@ -39,6 +40,7 @@ export class Runner {
   // Public API surfaces.
   readonly tasks: TasksApi;
   readonly files: FilesApi;
+  readonly conversations: ConversationsApi;
 
   constructor(
     private readonly client: IntrospectionClient,
@@ -49,6 +51,7 @@ export class Runner {
     this.http = this.buildHttp();
     this.tasks = new TasksApi(this.guardedHttp(this.http));
     this.files = new FilesApi(this.guardedHttp(this.http));
+    this.conversations = new ConversationsApi(this.guardedHttp(this.http));
   }
 
   // --- public accessors ---
@@ -113,7 +116,8 @@ export class Runner {
 
   /**
    * Best-effort close — flips a local `isClosed` flag so subsequent
-   * `runner.tasks` / `runner.files` calls throw a friendly error. No
+   * `runner.tasks` / `runner.files` / `runner.conversations` calls
+   * throw a friendly error. No
    * server-side revoke is performed; future work will route a revoke via
    * the CP locator-token path.
    */

package/src/utils.ts

@@ -1,19 +1,23 @@
 import { DiagLogLevel, DiagLogger } from "@opentelemetry/api";
 import { HttpsProxyAgent } from "https-proxy-agent";
-import { resolveForwardProxyUrl } from "@introspection-sdk/introspection-proxy";
+import { getProxyForUrl } from "proxy-from-env";
 
 /**
  * Attach a forward-proxy agent to OTLP exporter options when a proxy is
- * configured in the environment.
+ * configured for the exporter's endpoint.
  *
- * Note: the OTLP proto exporters use Node's `http`/`https` stack, so this uses
+ * The OTLP proto exporters use Node's `http`/`https` stack, so this uses
  * `HttpsProxyAgent` (an `http.Agent`) rather than the undici dispatcher from
- * `./proxy.js` — a dispatcher only applies to `fetch`. The proxy *URL* is
- * resolved by the shared {@link resolveForwardProxyUrl} so fetch and OTLP
- * traffic agree on which proxy to use.
+ * `@introspection-sdk/introspection-proxy` — a dispatcher only applies to
+ * `fetch`. Unlike undici's `EnvHttpProxyAgent`, `HttpsProxyAgent` ignores
+ * `NO_PROXY`, so we resolve the proxy per-endpoint with `proxy-from-env`'s
+ * {@link getProxyForUrl}, which returns `""` when the host matches `NO_PROXY`.
+ * This keeps in-cluster endpoints (e.g. `*.svc.cluster.local`) on a direct
+ * connection instead of tunnelling them through the egress proxy, which has no
+ * route for them.
  */
-export function withOtlpHttpsProxy<T extends object>(options: T): T {
-  const proxyUrl = resolveForwardProxyUrl();
+export function withOtlpHttpsProxy<T extends { url?: string }>(options: T): T {
+  const proxyUrl = options.url ? getProxyForUrl(options.url) : "";
   if (!proxyUrl) return options;
 
   return {