@introspection-sdk/introspection-node 0.4.10 → 0.5.1

package/src/pagination.ts

@@ -0,0 +1,69 @@
+import { Paginated } from "@introspection-sdk/types";
+
+/**
+ * Adapts a wire pagination protocol for {@link Paginator}: how to fetch
+ * a page at a given cursor, pull the items out of it, and find the
+ * cursor for the next page (`undefined` once the list is exhausted).
+ */
+export interface PageSource<T, TPage> {
+  /** Fetch the page at `cursor` (`undefined` = the first page). */
+  fetch(cursor: string | undefined): Promise<TPage>;
+  /** Items contained in `page`, in iteration order. */
+  items(page: TPage): T[];
+  /** Cursor for the page after `page`, or `undefined` when exhausted. */
+  next(page: TPage): string | undefined;
+}
+
+/**
+ * A lazy, auto-paging collection.
+ *
+ * - `await listing` resolves to the FIRST page, preserving the wire
+ *   envelope's metadata (counts, `has_more`, …).
+ * - `for await (const item of listing)` streams every item across all
+ *   pages, fetching each page only as the iterator reaches it; stop
+ *   early to stop fetching.
+ */
+export class Paginator<T, TPage = Paginated<T>>
+  implements AsyncIterable<T>, PromiseLike<TPage>
+{
+  constructor(
+    private readonly source: PageSource<T, TPage>,
+    private readonly start?: string,
+  ) {}
+
+  /** Thenable: resolves to the first page (no further pages fetched). */
+  then<R1 = TPage, R2 = never>(
+    onfulfilled?: ((page: TPage) => R1 | PromiseLike<R1>) | null,
+    onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+  ): PromiseLike<R1 | R2> {
+    return this.source.fetch(this.start).then(onfulfilled, onrejected);
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    let cursor = this.start;
+    do {
+      const page = await this.source.fetch(cursor);
+      for (const item of this.source.items(page)) yield item;
+      cursor = this.source.next(page);
+    } while (cursor !== undefined);
+  }
+}
+
+/**
+ * Build a {@link Paginator} over the standard Introspection cursor
+ * envelope ({@link Paginated}): items live in `records` and the next
+ * page is reached via the opaque `next` token.
+ */
+export function cursorPaginate<T>(
+  fetch: (next: string | undefined) => Promise<Paginated<T>>,
+  start?: string,
+): Paginator<T, Paginated<T>> {
+  return new Paginator(
+    {
+      fetch,
+      items: (page) => page.records,
+      next: (page) => page.next ?? undefined,
+    },
+    start,
+  );
+}

package/src/resources/experiments.ts

@@ -11,6 +11,7 @@ import type {
 } from "@introspection-sdk/types";
 import type { HttpClient } from "../http.js";
 import type { IntrospectionClient } from "../client.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 import { Runner, type RunnerSource } from "../runner.js";
 
 interface ExperimentRunRequestBody {
@@ -36,21 +37,22 @@ export class ExperimentsApi {
     private readonly client: IntrospectionClient,
   ) {}
 
-  list(params: ExperimentListParams): Promise<Paginated<Experiment>> {
-    return this.http.request<Paginated<Experiment>>({
-      method: "GET",
-      path: "/v1/experiments",
-      query: params as unknown as Record<string, unknown>,
-    });
-  }
-
-  async *listAll(params: ExperimentListParams): AsyncIterable<Experiment> {
-    let next: string | undefined = params.next;
-    do {
-      const page = await this.list({ ...params, next });
-      for (const r of page.records) yield r;
-      next = page.next ?? undefined;
-    } while (next);
+  /**
+   * List experiments matching `params`. `await` the result for the first
+   * page, or `for await` it to stream every experiment across pages
+   * (fetched lazily — `limit` sets the page size, `next` the starting
+   * cursor; stop early to stop fetching).
+   */
+  list(params: ExperimentListParams): Paginator<Experiment> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<Experiment>>({
+          method: "GET",
+          path: "/v1/experiments",
+          query: { ...params, next } as unknown as Record<string, unknown>,
+        }),
+      params.next,
+    );
   }
 
   get(id: Uuid): Promise<Experiment> {
@@ -157,7 +159,6 @@ export function attachExperiments(
     new ExperimentHandle(api, id);
   const hybrid = factory as ExperimentsApi & ExperimentHandleFactory;
   hybrid.list = api.list.bind(api);
-  hybrid.listAll = api.listAll.bind(api);
   hybrid.get = api.get.bind(api);
   hybrid.create = api.create.bind(api);
   hybrid.update = api.update.bind(api);

package/src/resources/recipes.ts

@@ -7,6 +7,7 @@ import type {
   Uuid,
 } from "@introspection-sdk/types";
 import type { HttpClient } from "../http.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 
 /**
  * Programmatic CRUD for `/v1/recipes` on the CP.
@@ -18,22 +19,22 @@ import type { HttpClient } from "../http.js";
 export class RecipesApi {
   constructor(private readonly http: HttpClient) {}
 
-  list(params: RecipeListParams): Promise<Paginated<Recipe>> {
-    return this.http.request<Paginated<Recipe>>({
-      method: "GET",
-      path: "/v1/recipes",
-      query: params as unknown as Record<string, unknown>,
-    });
-  }
-
-  /** Async-iterate every page that matches `params`. */
-  async *listAll(params: RecipeListParams): AsyncIterable<Recipe> {
-    let next: string | undefined = params.next;
-    do {
-      const page = await this.list({ ...params, next });
-      for (const r of page.records) yield r;
-      next = page.next ?? undefined;
-    } while (next);
+  /**
+   * List recipes matching `params`. `await` the result for the first
+   * page, or `for await` it to stream every recipe across pages (fetched
+   * lazily — `limit` sets the page size, `next` the starting cursor; stop
+   * early to stop fetching).
+   */
+  list(params: RecipeListParams): Paginator<Recipe> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<Recipe>>({
+          method: "GET",
+          path: "/v1/recipes",
+          query: { ...params, next } as unknown as Record<string, unknown>,
+        }),
+      params.next,
+    );
   }
 
   get(id: Uuid): Promise<Recipe> {

package/src/resources/runtimes.ts

@@ -12,6 +12,7 @@ import type {
 import { NotFoundError } from "@introspection-sdk/types";
 import type { HttpClient } from "../http.js";
 import type { IntrospectionClient } from "../client.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 import { Runner, type RunnerSource } from "../runner.js";
 
 const UUID_RE =
@@ -50,21 +51,22 @@ export class RuntimesApi {
     private readonly client: IntrospectionClient,
   ) {}
 
-  list(params: RuntimeListParams): Promise<Paginated<Runtime>> {
-    return this.http.request<Paginated<Runtime>>({
-      method: "GET",
-      path: "/v1/runtimes",
-      query: params as unknown as Record<string, unknown>,
-    });
-  }
-
-  async *listAll(params: RuntimeListParams): AsyncIterable<Runtime> {
-    let next: string | undefined = params.next;
-    do {
-      const page = await this.list({ ...params, next });
-      for (const r of page.records) yield r;
-      next = page.next ?? undefined;
-    } while (next);
+  /**
+   * List runtimes matching `params`. `await` the result for the first
+   * page, or `for await` it to stream every runtime across pages (fetched
+   * lazily — `limit` sets the page size, `next` the starting cursor; stop
+   * early to stop fetching).
+   */
+  list(params: RuntimeListParams): Paginator<Runtime> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<Runtime>>({
+          method: "GET",
+          path: "/v1/runtimes",
+          query: { ...params, next } as unknown as Record<string, unknown>,
+        }),
+      params.next,
+    );
   }
 
   get(id: Uuid, params: { project_id?: Uuid }): Promise<Runtime> {
@@ -101,16 +103,18 @@ export class RuntimesApi {
 
   /** Resolve a name to a runtime by querying `/v1/runtimes?name=…`. */
   async resolveByName(name: string, projectId?: Uuid): Promise<Runtime> {
-    const page = await this.list({ project_id: projectId, name, limit: 2 });
-    const match = page.records.find((r) => r.name === name);
-    if (!match) {
-      throw new NotFoundError({
-        message: `Runtime '${name}' not found${projectId ? ` in project ${projectId}` : ""}`,
-        status: 404,
-        code: "not_found",
-      });
+    for await (const r of this.list({
+      project_id: projectId,
+      name,
+      limit: 2,
+    })) {
+      if (r.name === name) return r;
     }
-    return match;
+    throw new NotFoundError({
+      message: `Runtime '${name}' not found${projectId ? ` in project ${projectId}` : ""}`,
+      status: 404,
+      code: "not_found",
+    });
   }
 
   /** POST `/v1/runtimes/{id}/run` and wrap the result in a `Runner`. */
@@ -219,7 +223,6 @@ export function attachRuntimes(
   // the methods can be invoked off the proxy without losing `this`.
   const hybrid = factory as RuntimesApi & RuntimeHandleFactory;
   hybrid.list = api.list.bind(api);
-  hybrid.listAll = api.listAll.bind(api);
   hybrid.get = api.get.bind(api);
   hybrid.create = api.create.bind(api);
   hybrid.update = api.update.bind(api);

package/src/runner-resources/conversations.ts

@@ -0,0 +1,202 @@
+import type {
+  ConversationItem,
+  ConversationItemInclude,
+  ConversationItemList,
+  ConversationItemListParams,
+  ConversationListParams,
+  ConversationResponse,
+  ConversationSummary,
+  MessagePart,
+  Paginated,
+  ToolCallResponsePart,
+} from "@introspection-sdk/types";
+import { HttpClient } from "../http.js";
+import { Paginator, cursorPaginate } from "../pagination.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) {}
+
+  /**
+   * List items of a conversation. `await` the result for the first page
+   * (an OpenAI-style {@link ConversationItemList} envelope), or
+   * `for await` it to stream every item across pages (fetched lazily —
+   * `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.
+   */
+  list(
+    conversationId: string,
+    params?: ConversationItemListParams,
+  ): Paginator<ConversationItem, ConversationItemList> {
+    return new Paginator(
+      {
+        fetch: (after) =>
+          this.http.request<ConversationItemList>({
+            method: "GET",
+            path: `/v1/conversations/${encodeURIComponent(conversationId)}/items`,
+            query: { ...params, after } as Record<string, unknown>,
+          }),
+        items: (page) => page.data,
+        next: (page) =>
+          page.has_more && page.last_id !== null ? page.last_id : undefined,
+      },
+      params?.after,
+    );
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * List conversation summaries matching `params`. `await` the result for
+   * the first page, or `for await` it to stream every summary across
+   * pages (fetched lazily — `limit` sets the page size, `next` the
+   * starting cursor; stop early to stop fetching).
+   */
+  list(params?: ConversationListParams): Paginator<ConversationSummary> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<ConversationSummary>>({
+          method: "GET",
+          path: "/v1/conversations",
+          query: { ...params, next } as Record<string, unknown>,
+        }),
+      params?.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

@@ -1,5 +1,6 @@
 import type {
   File as FileResource,
+  FileCreateOptions,
   FileCreateTextParams,
   FileListParams,
   FileType,
@@ -8,6 +9,7 @@ import type {
   Paginated,
 } from "@introspection-sdk/types";
 import { HttpClient } from "../http.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 
 export type FileUploadBody =
   | { file: Blob; name?: string; file_type?: FileType }
@@ -21,24 +23,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(
-    fileId: string,
-    params?: ListParams,
-  ): AsyncIterable<FileResource> {
-    let next: string | undefined = params?.next;
-    do {
-      const page = await this.list(fileId, { ...params, next });
-      for (const f of page.records) yield f;
-      next = page.next ?? undefined;
-    } while (next);
+  /**
+   * List versions of a file. `await` the result for the first page, or
+   * `for await` it to stream every version across pages (fetched lazily;
+   * stop early to stop fetching).
+   */
+  list(fileId: string, params?: ListParams): Paginator<FileResource> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<FileResource>>({
+          method: "GET",
+          path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
+          query: { ...params, next } as Record<string, unknown>,
+        }),
+      params?.next,
+    );
   }
 
   get(fileId: string, versionId: string): Promise<FileResource> {
@@ -48,8 +47,12 @@ export class FileVersionsApi {
     });
   }
 
-  create(fileId: string, body: FileUploadBody): Promise<FileResource> {
-    const form = toFormData(body);
+  create(
+    fileId: string,
+    body: FileUploadBody,
+    options?: FileCreateOptions,
+  ): Promise<FileResource> {
+    const form = toFormData(body, options);
     return this.http.request<FileResource>({
       method: "POST",
       path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
@@ -65,25 +68,29 @@ 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,
-    });
+  /**
+   * List files matching `params`. `await` the result for the first page,
+   * or `for await` it to stream every file across pages (fetched lazily —
+   * `limit` sets the page size, `next` the starting cursor; stop early to
+   * stop fetching).
+   */
+  list(params?: FileListParams): Paginator<FileResource> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<FileResource>>({
+          method: "GET",
+          path: "/v1/files",
+          query: { ...params, next } as Record<string, unknown>,
+        }),
+      params?.next,
+    );
   }
 
-  async *listAll(params?: FileListParams): AsyncIterable<FileResource> {
-    let next: string | undefined = params?.next;
-    do {
-      const page = await this.list({ ...params, next });
-      for (const f of page.records) yield f;
-      next = page.next ?? undefined;
-    } while (next);
-  }
-
-  upload(body: FileUploadBody): Promise<FileResource> {
-    const form = toFormData(body);
+  upload(
+    body: FileUploadBody,
+    options?: FileCreateOptions,
+  ): Promise<FileResource> {
+    const form = toFormData(body, options);
     return this.http.request<FileResource>({
       method: "POST",
       path: "/v1/files",
@@ -91,11 +98,16 @@ export class FilesApi {
     });
   }
 
-  createText(body: FileCreateTextParams): Promise<FileResource> {
+  createText(
+    body: FileCreateTextParams,
+    options?: FileCreateOptions,
+  ): Promise<FileResource> {
     return this.http.request<FileResource>({
       method: "POST",
       path: "/v1/files",
-      body,
+      body: options?.visibility
+        ? { ...body, visibility: options.visibility }
+        : body,
     });
   }
 
@@ -139,7 +151,10 @@ export class FilesApi {
   }
 }
 
-function toFormData(body: FileUploadBody): FormData {
+function toFormData(
+  body: FileUploadBody,
+  options?: FileCreateOptions,
+): FormData {
   const fd = new FormData();
   if ("file" in body && body.file instanceof Blob) {
     fd.append("file", body.file, body.name);
@@ -159,5 +174,6 @@ function toFormData(body: FileUploadBody): FormData {
   }
   if (body.name) fd.append("name", body.name);
   if (body.file_type) fd.append("file_type", body.file_type);
+  if (options?.visibility) fd.append("visibility", options.visibility);
   return fd;
 }

package/src/runner-resources/tasks.ts

@@ -12,6 +12,7 @@ import type {
   TaskUpdateParams,
 } from "@introspection-sdk/types";
 import { HttpClient } from "../http.js";
+import { Paginator, cursorPaginate } from "../pagination.js";
 import { parseSse } from "../streaming.js";
 
 export interface StartParams extends TaskCreateParams {
@@ -84,21 +85,22 @@ 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> {
-    let next: string | undefined = params?.next;
-    do {
-      const page = await this.list({ ...params, next });
-      for (const t of page.records) yield t;
-      next = page.next ?? undefined;
-    } while (next);
+  /**
+   * List tasks matching `params`. `await` the result for the first page,
+   * or `for await` it to stream every task across pages (fetched lazily —
+   * `limit` sets the page size, `next` the starting cursor; stop early to
+   * stop fetching).
+   */
+  list(params?: TaskListParams): Paginator<Task> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<Task>>({
+          method: "GET",
+          path: "/v1/tasks",
+          query: { ...params, next } as Record<string, unknown>,
+        }),
+      params?.next,
+    );
   }
 
   create(body: TaskCreateParams): Promise<TaskCreateResponse> {