@introspection-sdk/introspection-browser 0.5.2 → 0.5.3

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @introspection-sdk/introspection-browser@0.5.2 build /home/runner/work/introspection-js-sdk/introspection-js-sdk/packages/introspection-browser
+> @introspection-sdk/introspection-browser@0.5.3 build /home/runner/work/introspection-js-sdk/introspection-js-sdk/packages/introspection-browser
 > tsc
 

package/README.md

@@ -86,6 +86,34 @@ Both `create` and `start` accept two optional task controls:
   before the sandbox is torn down. `0` tears it down as soon as it's
   provisioned; omit to use the deployment default. Clamped to the task timeout.
 
+## Files and conversations
+
+The same identity session also reaches `/v1/files` and (read-only)
+`/v1/conversations` — no extra credential, just the cookie minted by
+`connect()`:
+
+```typescript
+// Files — CRUD + upload/download, all identity-scoped
+await client.files.upload({ file: new Blob(["hi"]), name: "hi.txt" });
+const page = await client.files.list({ visibility: "identity" });
+const bytes = await client.files.download(page.records[0].id);
+
+// Conversations — read-only projection over the telemetry store
+for await (const summary of client.conversations.list()) {
+  console.log(summary.conversation_id);
+}
+// Resolve the latest turn of a conversation (Responses-API shape)
+const turn = await client.conversations.retrieve(conversationId);
+console.log(turn?.output_messages);
+```
+
+`client.files` mirrors the Node SDK's `FilesApi` (`list` / `upload` /
+`createText` / `get` / `update` / `delete` / `download` / `downloadStream`,
+plus `files.versions`). `client.conversations` mirrors `ConversationsApi`
+(`list`, `retrieve`, and `conversations.items.list()` / `.get()`). Both `list`
+helpers return a `Paginator` — `await` it for the first page or `for await` it
+to auto-page.
+
 > **CORS:** the Data Plane authorizes browser origins against its configured
 > allowlist (`CORS_ORIGINS`). A new SPA origin must be present there for the
-> cross-origin cookie exchange and task calls to succeed.
+> cross-origin cookie exchange and task/file/conversation calls to succeed.

package/dist/api/client.d.ts

@@ -19,6 +19,8 @@
  * before retrying.
  */
 import { TasksClient } from "./tasks.js";
+import { FilesClient } from "./files.js";
+import { ConversationsClient } from "./conversations.js";
 export interface IntrospectionApiClientOptions {
     /** Data Plane REST base URL (e.g. `https://dp.us.introspection.dev`). */
     dpUrl: string;
@@ -39,6 +41,10 @@ export declare class IntrospectionApiClient {
     private readonly opts;
     /** `/v1/tasks` operations bound to the DP session cookie. */
     readonly tasks: TasksClient;
+    /** `/v1/files` operations bound to the DP session cookie. */
+    readonly files: FilesClient;
+    /** Read-only `/v1/conversations` projection bound to the session cookie. */
+    readonly conversations: ConversationsClient;
     private readonly fetchImpl;
     constructor(opts: IntrospectionApiClientOptions);
     /**

package/dist/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,WAAW,6BAA6B;IAC5C,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,qBAAa,sBAAsB;IAMrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAEZ,IAAI,EAAE,6BAA6B;IAgBhE;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAIhB,QAAQ;IAiBtB,0EAA0E;YAC5D,UAAU;CAQzB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,WAAW,6BAA6B;IAC5C,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,qBAAa,sBAAsB;IAUrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IATjC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAC;IAE5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAEZ,IAAI,EAAE,6BAA6B;IAkBhE;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAIhB,QAAQ;IAiBtB,0EAA0E;YAC5D,UAAU;CAQzB"}

package/dist/api/client.js

@@ -20,10 +20,16 @@
  */
 import { BrowserHttpClient, stripTrailingSlash, toApiError } from "./http.js";
 import { TasksClient } from "./tasks.js";
+import { FilesClient } from "./files.js";
+import { ConversationsClient } from "./conversations.js";
 export class IntrospectionApiClient {
     opts;
     /** `/v1/tasks` operations bound to the DP session cookie. */
     tasks;
+    /** `/v1/files` operations bound to the DP session cookie. */
+    files;
+    /** Read-only `/v1/conversations` projection bound to the session cookie. */
+    conversations;
     fetchImpl;
     constructor(opts) {
         this.opts = opts;
@@ -38,6 +44,8 @@ export class IntrospectionApiClient {
             onUnauthorized: () => this.reexchange(),
         });
         this.tasks = new TasksClient(http);
+        this.files = new FilesClient(http);
+        this.conversations = new ConversationsClient(http);
     }
     /**
      * Mint a token via `getToken` and redeem it at the DP for the

package/dist/api/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAmBzC,MAAM,OAAO,sBAAsB;IAMJ;IAL7B,6DAA6D;IACpD,KAAK,CAAc;IAEX,SAAS,CAAe;IAEzC,YAA6B,IAAmC;QAAnC,SAAI,GAAJ,IAAI,CAA+B;QAC9D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;QAChD,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,sEAAsE,CACvE,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,iBAAiB,CAAC;YACjC,MAAM,EAAE,IAAI,CAAC,KAAK;YAClB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE;SACxC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAC9B,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,oBAAoB,EAC1D;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,IAAI,EAAE,CAAC;aACvC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YAChE,WAAW,EAAE,SAAS;SACvB,CACF,CAAC;QACF,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAED,0EAA0E;IAClE,KAAK,CAAC,UAAU;QACtB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAmBzD,MAAM,OAAO,sBAAsB;IAUJ;IAT7B,6DAA6D;IACpD,KAAK,CAAc;IAC5B,6DAA6D;IACpD,KAAK,CAAc;IAC5B,4EAA4E;IACnE,aAAa,CAAsB;IAE3B,SAAS,CAAe;IAEzC,YAA6B,IAAmC;QAAnC,SAAI,GAAJ,IAAI,CAA+B;QAC9D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;QAChD,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,sEAAsE,CACvE,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,iBAAiB,CAAC;YACjC,MAAM,EAAE,IAAI,CAAC,KAAK;YAClB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE;SACxC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,aAAa,GAAG,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAEO,KAAK,CAAC,QAAQ;QACpB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAC9B,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,oBAAoB,EAC1D;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,IAAI,EAAE,CAAC;aACvC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YAChE,WAAW,EAAE,SAAS;SACvB,CACF,CAAC;QACF,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAED,0EAA0E;IAClE,KAAK,CAAC,UAAU;QACtB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/api/conversations.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Cookie-authenticated, read-only Conversations client for the browser
+ * (`/v1/conversations`).
+ *
+ * Mirrors the Node SDK's runner-bound `ConversationsApi`, but rides the
+ * DP `intro_dp_session` cookie via {@link BrowserHttpClient} instead of a
+ * bearer token — so a single-page app reads conversation history with the
+ * same identity session it uses for tasks and files. Conversations are a
+ * projection over the immutable telemetry store: list summaries, walk a
+ * conversation's items, or `retrieve()` the resolved state of one turn.
+ */
+import type { ConversationItem, ConversationItemInclude, ConversationItemList, ConversationItemListParams, ConversationListParams, ConversationResponse, ConversationSummary } from "@introspection-sdk/types";
+import { Paginator } from "@introspection-sdk/http";
+import { BrowserHttpClient } from "./http.js";
+/**
+ * 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 declare class ConversationItemsClient {
+    private readonly http;
+    constructor(http: BrowserHttpClient);
+    /**
+     * 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>;
+    /**
+     * 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>;
+}
+/**
+ * Read-only Conversations client (`/v1/conversations`).
+ *
+ * Both `list()` and `items.list()` are auto-paging, 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 declare class ConversationsClient {
+    private readonly http;
+    /** Items of a conversation — `conversations.items.list(...)` etc. */
+    readonly items: ConversationItemsClient;
+    constructor(http: BrowserHttpClient);
+    /**
+     * 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>;
+    /**
+     * 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" })`.
+     */
+    retrieve(conversationId: string, itemId?: string): Promise<ConversationResponse | null>;
+    /** Scan items in descending order for the most recent LLM turn. */
+    private findLatestTurnId;
+}
+//# sourceMappingURL=conversations.d.ts.map

package/dist/api/conversations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversations.d.ts","sourceRoot":"","sources":["../../src/api/conversations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EAIpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAS9C;;;;;;GAMG;AACH,qBAAa,uBAAuB;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,iBAAiB;IAEpD;;;;;;;;;;OAUG;IACH,IAAI,CACF,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,0BAA0B,GAClC,SAAS,CAAC,gBAAgB,EAAE,oBAAoB,CAAC;IAiBpD;;;OAGG;IACH,GAAG,CACD,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,uBAAuB,EAAE,CAAA;KAAE,GAC/C,OAAO,CAAC,gBAAgB,CAAC;CAO7B;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAmB;IAIlB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAC;gBAEX,IAAI,EAAE,iBAAiB;IAIpD;;;;;OAKG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC,mBAAmB,CAAC;IAYrE;;;;;;;;;;;;;OAaG;IACG,QAAQ,CACZ,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA6BvC,mEAAmE;YACrD,gBAAgB;CAc/B"}

package/dist/api/conversations.js

@@ -0,0 +1,172 @@
+/**
+ * Cookie-authenticated, read-only Conversations client for the browser
+ * (`/v1/conversations`).
+ *
+ * Mirrors the Node SDK's runner-bound `ConversationsApi`, but rides the
+ * DP `intro_dp_session` cookie via {@link BrowserHttpClient} instead of a
+ * bearer token — so a single-page app reads conversation history with the
+ * same identity session it uses for tasks and files. Conversations are a
+ * projection over the immutable telemetry store: list summaries, walk a
+ * conversation's items, or `retrieve()` the resolved state of one turn.
+ */
+import { Paginator, cursorPaginate } from "@introspection-sdk/http";
+/** Includes requested when building a {@link ConversationResponse}. */
+const RESPONSE_INCLUDES = [
+    "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 ConversationItemsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * 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, params) {
+        return new Paginator({
+            fetch: (after) => this.http.request({
+                method: "GET",
+                path: `/v1/conversations/${encodeURIComponent(conversationId)}/items`,
+                query: { ...params, after },
+            }),
+            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, itemId, params) {
+        return this.http.request({
+            method: "GET",
+            path: `/v1/conversations/${encodeURIComponent(conversationId)}/items/${encodeURIComponent(itemId)}`,
+            query: params,
+        });
+    }
+}
+/**
+ * Read-only Conversations client (`/v1/conversations`).
+ *
+ * Both `list()` and `items.list()` are auto-paging, 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 ConversationsClient {
+    http;
+    /** Items of a conversation — `conversations.items.list(...)` etc. */
+    items;
+    constructor(http) {
+        this.http = http;
+        this.items = new ConversationItemsClient(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) {
+        return cursorPaginate((next) => this.http.request({
+            method: "GET",
+            path: "/v1/conversations",
+            query: { ...params, next },
+        }), 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, itemId) {
+        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. */
+    async findLatestTurnId(conversationId) {
+        let fallback = 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 ConversationsClient.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(messages) {
+    return messages.map((message) => ({
+        ...message,
+        parts: message.parts.map(normalizePart),
+    }));
+}
+function normalizePart(part) {
+    if (part.type !== "tool_call_response")
+        return part;
+    const legacy = part;
+    if (legacy.response !== undefined || legacy.result === undefined) {
+        return part;
+    }
+    const { result, ...rest } = legacy;
+    return { ...rest, response: result };
+}
+//# sourceMappingURL=conversations.js.map

package/dist/api/conversations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversations.js","sourceRoot":"","sources":["../../src/api/conversations.ts"],"names":[],"mappings":"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"}

package/dist/api/files.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Cookie-authenticated Files client for the browser (`/v1/files`).
+ *
+ * Mirrors the Node SDK's runner-bound `FilesApi`, but rides the DP
+ * `intro_dp_session` cookie via {@link BrowserHttpClient} instead of a
+ * bearer token — so a single-page app reads and writes files with the
+ * same identity session it uses for tasks and conversations. The DP
+ * derives the owning `identity_key` from the session JWT; per-identity
+ * file visibility is enforced server-side.
+ */
+import type { File as FileResource, FileCreateOptions, FileCreateTextParams, FileListParams, FileType, FileUpdateParams, ListParams } from "@introspection-sdk/types";
+import { Paginator } from "@introspection-sdk/http";
+import { BrowserHttpClient } from "./http.js";
+export type FileUploadBody = {
+    file: Blob;
+    name?: string;
+    file_type?: FileType;
+} | {
+    file: Uint8Array;
+    name: string;
+    file_type?: FileType;
+    contentType?: string;
+};
+/** Versions of a file (`/v1/files/{id}/versions`). */
+export declare class FileVersionsClient {
+    private readonly http;
+    constructor(http: BrowserHttpClient);
+    /**
+     * 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>;
+    get(fileId: string, versionId: string): Promise<FileResource>;
+    create(fileId: string, body: FileUploadBody, options?: FileCreateOptions): Promise<FileResource>;
+}
+/**
+ * Cookie-authenticated `/v1/files` client. Mirrors the Node SDK's
+ * `FilesApi` shape but is bound to a DP session cookie rather than a
+ * bearer token.
+ */
+export declare class FilesClient {
+    private readonly http;
+    readonly versions: FileVersionsClient;
+    constructor(http: BrowserHttpClient);
+    /**
+     * 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>;
+    upload(body: FileUploadBody, options?: FileCreateOptions): Promise<FileResource>;
+    createText(body: FileCreateTextParams, options?: FileCreateOptions): Promise<FileResource>;
+    get(fileId: string): Promise<FileResource>;
+    update(fileId: string, body: FileUpdateParams): Promise<FileResource>;
+    delete(fileId: string): Promise<void>;
+    download(fileId: string): Promise<Uint8Array>;
+    downloadStream(fileId: string): Promise<ReadableStream<Uint8Array>>;
+}
+//# sourceMappingURL=files.d.ts.map

package/dist/api/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/api/files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,IAAI,IAAI,YAAY,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,QAAQ,CAAA;CAAE,GACnD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN,sDAAsD;AACtD,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,iBAAiB;IAEpD;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,YAAY,CAAC;IAYlE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAO7D,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,cAAc,EACpB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,YAAY,CAAC;CAQzB;AAED;;;;GAIG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;gBAET,IAAI,EAAE,iBAAiB;IAIpD;;;;;OAKG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC,YAAY,CAAC;IAYtD,MAAM,CACJ,IAAI,EAAE,cAAc,EACpB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,YAAY,CAAC;IASxB,UAAU,CACR,IAAI,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,YAAY,CAAC;IAUxB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAO1C,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAQrE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ7C,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;CAOpE"}

package/dist/api/files.js

@@ -0,0 +1,145 @@
+/**
+ * Cookie-authenticated Files client for the browser (`/v1/files`).
+ *
+ * Mirrors the Node SDK's runner-bound `FilesApi`, but rides the DP
+ * `intro_dp_session` cookie via {@link BrowserHttpClient} instead of a
+ * bearer token — so a single-page app reads and writes files with the
+ * same identity session it uses for tasks and conversations. The DP
+ * derives the owning `identity_key` from the session JWT; per-identity
+ * file visibility is enforced server-side.
+ */
+import { cursorPaginate } from "@introspection-sdk/http";
+/** Versions of a file (`/v1/files/{id}/versions`). */
+export class FileVersionsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * 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, params) {
+        return cursorPaginate((next) => this.http.request({
+            method: "GET",
+            path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
+            query: { ...params, next },
+        }), params?.next);
+    }
+    get(fileId, versionId) {
+        return this.http.request({
+            method: "GET",
+            path: `/v1/files/${encodeURIComponent(fileId)}/versions/${encodeURIComponent(versionId)}`,
+        });
+    }
+    create(fileId, body, options) {
+        const form = toFormData(body, options);
+        return this.http.request({
+            method: "POST",
+            path: `/v1/files/${encodeURIComponent(fileId)}/versions`,
+            body: form,
+        });
+    }
+}
+/**
+ * Cookie-authenticated `/v1/files` client. Mirrors the Node SDK's
+ * `FilesApi` shape but is bound to a DP session cookie rather than a
+ * bearer token.
+ */
+export class FilesClient {
+    http;
+    versions;
+    constructor(http) {
+        this.http = http;
+        this.versions = new FileVersionsClient(http);
+    }
+    /**
+     * 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) {
+        return cursorPaginate((next) => this.http.request({
+            method: "GET",
+            path: "/v1/files",
+            query: { ...params, next },
+        }), params?.next);
+    }
+    upload(body, options) {
+        const form = toFormData(body, options);
+        return this.http.request({
+            method: "POST",
+            path: "/v1/files",
+            body: form,
+        });
+    }
+    createText(body, options) {
+        return this.http.request({
+            method: "POST",
+            path: "/v1/files",
+            body: options?.visibility
+                ? { ...body, visibility: options.visibility }
+                : body,
+        });
+    }
+    get(fileId) {
+        return this.http.request({
+            method: "GET",
+            path: `/v1/files/${encodeURIComponent(fileId)}`,
+        });
+    }
+    update(fileId, body) {
+        return this.http.request({
+            method: "PATCH",
+            path: `/v1/files/${encodeURIComponent(fileId)}`,
+            body,
+        });
+    }
+    delete(fileId) {
+        return this.http.request({
+            method: "DELETE",
+            path: `/v1/files/${encodeURIComponent(fileId)}`,
+            expect: "empty",
+        });
+    }
+    download(fileId) {
+        return this.http.request({
+            method: "GET",
+            path: `/v1/files/${encodeURIComponent(fileId)}/content`,
+            expect: "bytes",
+        });
+    }
+    downloadStream(fileId) {
+        return this.http.request({
+            method: "GET",
+            path: `/v1/files/${encodeURIComponent(fileId)}/content`,
+            expect: "stream",
+        });
+    }
+}
+function toFormData(body, options) {
+    const fd = new FormData();
+    if ("file" in body && body.file instanceof Blob) {
+        fd.append("file", body.file, body.name);
+    }
+    else {
+        // Uint8Array branch — copy into a fresh ArrayBuffer so the Blob
+        // constructor sees a concrete ArrayBuffer (not ArrayBufferLike,
+        // which TS rejects under nodenext lib).
+        const u8 = body.file;
+        const ct = body.contentType ??
+            "application/octet-stream";
+        const ab = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength);
+        fd.append("file", new Blob([ab], { type: ct }), body.name);
+    }
+    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;
+}
+//# sourceMappingURL=files.js.map

package/dist/api/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/api/files.ts"],"names":[],"mappings":"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"}

package/dist/api/index.d.ts

@@ -28,9 +28,11 @@
  */
 export { IntrospectionApiClient, type IntrospectionApiClientOptions, } from "./client.js";
 export { TasksClient, TaskRunsClient, RunHandle, type CreateTaskParams, type StartTaskParams, } from "./tasks.js";
+export { FilesClient, FileVersionsClient, type FileUploadBody, } from "./files.js";
+export { ConversationsClient, ConversationItemsClient, } from "./conversations.js";
 export { BrowserHttpClient, type BrowserHttpConfig } from "./http.js";
 export { parseSse } from "./sse.js";
 export { Paginator, cursorPaginate, type PageSource, } from "@introspection-sdk/http";
-export type { Task, TaskRun, TaskStatus, TaskVisibility, TaskCreateResponse, TaskListParams, TaskUpdateParams, TaskRunCreateParams, TaskCancelResponse, RunIdentityInput, Paginated, SseEvent, } from "@introspection-sdk/types";
+export type { Task, TaskRun, TaskStatus, TaskVisibility, TaskCreateResponse, TaskListParams, TaskUpdateParams, TaskRunCreateParams, TaskCancelResponse, RunIdentityInput, Paginated, SseEvent, File, FileType, FileListParams, FileUpdateParams, FileCreateTextParams, FileCreateOptions, ListParams, ConversationSummary, ConversationItem, ConversationItemList, ConversationListParams, ConversationItemListParams, ConversationItemInclude, ConversationResponse, } from "@introspection-sdk/types";
 export { IntrospectionAPIError, AuthenticationError, InsufficientScopeError, NotFoundError, NetworkError, } from "@introspection-sdk/types";
 //# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EACL,SAAS,EACT,cAAc,EACd,KAAK,UAAU,GAChB,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EACV,IAAI,EACJ,OAAO,EACP,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,QAAQ,GACT,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,aAAa,EACb,YAAY,GACb,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EACL,SAAS,EACT,cAAc,EACd,KAAK,UAAU,GAChB,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EACV,IAAI,EACJ,OAAO,EACP,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,aAAa,EACb,YAAY,GACb,MAAM,0BAA0B,CAAC"}

package/dist/api/index.js

@@ -28,6 +28,8 @@
  */
 export { IntrospectionApiClient, } from "./client.js";
 export { TasksClient, TaskRunsClient, RunHandle, } from "./tasks.js";
+export { FilesClient, FileVersionsClient, } from "./files.js";
+export { ConversationsClient, ConversationItemsClient, } from "./conversations.js";
 export { BrowserHttpClient } from "./http.js";
 export { parseSse } from "./sse.js";
 export { Paginator, cursorPaginate, } from "@introspection-sdk/http";

package/dist/api/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,sBAAsB,GAEvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,GAGV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAA0B,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EACL,SAAS,EACT,cAAc,GAEf,MAAM,yBAAyB,CAAC;AAiBjC,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,aAAa,EACb,YAAY,GACb,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,sBAAsB,GAEvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,GAGV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EACX,kBAAkB,GAEnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAA0B,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EACL,SAAS,EACT,cAAc,GAEf,MAAM,yBAAyB,CAAC;AA+BjC,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,aAAa,EACb,YAAY,GACb,MAAM,0BAA0B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-sdk/introspection-browser",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "license": "Apache-2.0",
   "description": "Introspection observability SDK for the browser",
   "engines": {
@@ -20,7 +20,7 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^22.19.20",
+    "@types/node": "^22.19.21",
     "eslint": "^9.39.4",
     "typescript": "5.9.3",
     "@repo/eslint-config": "0.0.0",
@@ -31,8 +31,8 @@
     "@opentelemetry/api-logs": "^0.219.0",
     "@opentelemetry/sdk-logs": "^0.219.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.219.0",
-    "@introspection-sdk/http": "0.5.2",
-    "@introspection-sdk/types": "0.5.2"
+    "@introspection-sdk/types": "0.5.3",
+    "@introspection-sdk/http": "0.5.3"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",

package/src/api/client.ts

@@ -21,6 +21,8 @@
 
 import { BrowserHttpClient, stripTrailingSlash, toApiError } from "./http.js";
 import { TasksClient } from "./tasks.js";
+import { FilesClient } from "./files.js";
+import { ConversationsClient } from "./conversations.js";
 
 export interface IntrospectionApiClientOptions {
   /** Data Plane REST base URL (e.g. `https://dp.us.introspection.dev`). */
@@ -42,6 +44,10 @@ export interface IntrospectionApiClientOptions {
 export class IntrospectionApiClient {
   /** `/v1/tasks` operations bound to the DP session cookie. */
   readonly tasks: TasksClient;
+  /** `/v1/files` operations bound to the DP session cookie. */
+  readonly files: FilesClient;
+  /** Read-only `/v1/conversations` projection bound to the session cookie. */
+  readonly conversations: ConversationsClient;
 
   private readonly fetchImpl: typeof fetch;
 
@@ -59,6 +65,8 @@ export class IntrospectionApiClient {
       onUnauthorized: () => this.reexchange(),
     });
     this.tasks = new TasksClient(http);
+    this.files = new FilesClient(http);
+    this.conversations = new ConversationsClient(http);
   }
 
   /**

package/src/api/conversations.ts

@@ -0,0 +1,214 @@
+/**
+ * Cookie-authenticated, read-only Conversations client for the browser
+ * (`/v1/conversations`).
+ *
+ * Mirrors the Node SDK's runner-bound `ConversationsApi`, but rides the
+ * DP `intro_dp_session` cookie via {@link BrowserHttpClient} instead of a
+ * bearer token — so a single-page app reads conversation history with the
+ * same identity session it uses for tasks and files. Conversations are a
+ * projection over the immutable telemetry store: list summaries, walk a
+ * conversation's items, or `retrieve()` the resolved state of one turn.
+ */
+
+import type {
+  ConversationItem,
+  ConversationItemInclude,
+  ConversationItemList,
+  ConversationItemListParams,
+  ConversationListParams,
+  ConversationResponse,
+  ConversationSummary,
+  MessagePart,
+  Paginated,
+  ToolCallResponsePart,
+} from "@introspection-sdk/types";
+import { Paginator, cursorPaginate } from "@introspection-sdk/http";
+import { BrowserHttpClient } 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 ConversationItemsClient {
+  constructor(private readonly http: BrowserHttpClient) {}
+
+  /**
+   * 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 client (`/v1/conversations`).
+ *
+ * Both `list()` and `items.list()` are auto-paging, 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 ConversationsClient {
+  /** Items of a conversation — `conversations.items.list(...)` etc. */
+  readonly items: ConversationItemsClient;
+
+  constructor(private readonly http: BrowserHttpClient) {
+    this.items = new ConversationItemsClient(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 ConversationsClient.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/api/files.ts

@@ -0,0 +1,196 @@
+/**
+ * Cookie-authenticated Files client for the browser (`/v1/files`).
+ *
+ * Mirrors the Node SDK's runner-bound `FilesApi`, but rides the DP
+ * `intro_dp_session` cookie via {@link BrowserHttpClient} instead of a
+ * bearer token — so a single-page app reads and writes files with the
+ * same identity session it uses for tasks and conversations. The DP
+ * derives the owning `identity_key` from the session JWT; per-identity
+ * file visibility is enforced server-side.
+ */
+
+import type {
+  File as FileResource,
+  FileCreateOptions,
+  FileCreateTextParams,
+  FileListParams,
+  FileType,
+  FileUpdateParams,
+  ListParams,
+  Paginated,
+} from "@introspection-sdk/types";
+import { Paginator, cursorPaginate } from "@introspection-sdk/http";
+import { BrowserHttpClient } from "./http.js";
+
+export type FileUploadBody =
+  | { file: Blob; name?: string; file_type?: FileType }
+  | {
+      file: Uint8Array;
+      name: string;
+      file_type?: FileType;
+      contentType?: string;
+    };
+
+/** Versions of a file (`/v1/files/{id}/versions`). */
+export class FileVersionsClient {
+  constructor(private readonly http: BrowserHttpClient) {}
+
+  /**
+   * 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> {
+    return this.http.request<FileResource>({
+      method: "GET",
+      path: `/v1/files/${encodeURIComponent(fileId)}/versions/${encodeURIComponent(versionId)}`,
+    });
+  }
+
+  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`,
+      body: form,
+    });
+  }
+}
+
+/**
+ * Cookie-authenticated `/v1/files` client. Mirrors the Node SDK's
+ * `FilesApi` shape but is bound to a DP session cookie rather than a
+ * bearer token.
+ */
+export class FilesClient {
+  readonly versions: FileVersionsClient;
+
+  constructor(private readonly http: BrowserHttpClient) {
+    this.versions = new FileVersionsClient(http);
+  }
+
+  /**
+   * 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,
+    );
+  }
+
+  upload(
+    body: FileUploadBody,
+    options?: FileCreateOptions,
+  ): Promise<FileResource> {
+    const form = toFormData(body, options);
+    return this.http.request<FileResource>({
+      method: "POST",
+      path: "/v1/files",
+      body: form,
+    });
+  }
+
+  createText(
+    body: FileCreateTextParams,
+    options?: FileCreateOptions,
+  ): Promise<FileResource> {
+    return this.http.request<FileResource>({
+      method: "POST",
+      path: "/v1/files",
+      body: options?.visibility
+        ? { ...body, visibility: options.visibility }
+        : body,
+    });
+  }
+
+  get(fileId: string): Promise<FileResource> {
+    return this.http.request<FileResource>({
+      method: "GET",
+      path: `/v1/files/${encodeURIComponent(fileId)}`,
+    });
+  }
+
+  update(fileId: string, body: FileUpdateParams): Promise<FileResource> {
+    return this.http.request<FileResource>({
+      method: "PATCH",
+      path: `/v1/files/${encodeURIComponent(fileId)}`,
+      body,
+    });
+  }
+
+  delete(fileId: string): Promise<void> {
+    return this.http.request<void>({
+      method: "DELETE",
+      path: `/v1/files/${encodeURIComponent(fileId)}`,
+      expect: "empty",
+    });
+  }
+
+  download(fileId: string): Promise<Uint8Array> {
+    return this.http.request<Uint8Array>({
+      method: "GET",
+      path: `/v1/files/${encodeURIComponent(fileId)}/content`,
+      expect: "bytes",
+    });
+  }
+
+  downloadStream(fileId: string): Promise<ReadableStream<Uint8Array>> {
+    return this.http.request<ReadableStream<Uint8Array>>({
+      method: "GET",
+      path: `/v1/files/${encodeURIComponent(fileId)}/content`,
+      expect: "stream",
+    });
+  }
+}
+
+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);
+  } else {
+    // Uint8Array branch — copy into a fresh ArrayBuffer so the Blob
+    // constructor sees a concrete ArrayBuffer (not ArrayBufferLike,
+    // which TS rejects under nodenext lib).
+    const u8 = (body as { file: Uint8Array }).file;
+    const ct =
+      (body as { contentType?: string }).contentType ??
+      "application/octet-stream";
+    const ab = u8.buffer.slice(
+      u8.byteOffset,
+      u8.byteOffset + u8.byteLength,
+    ) as ArrayBuffer;
+    fd.append("file", new Blob([ab], { type: ct }), body.name);
+  }
+  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/api/index.ts

@@ -38,6 +38,15 @@ export {
   type CreateTaskParams,
   type StartTaskParams,
 } from "./tasks.js";
+export {
+  FilesClient,
+  FileVersionsClient,
+  type FileUploadBody,
+} from "./files.js";
+export {
+  ConversationsClient,
+  ConversationItemsClient,
+} from "./conversations.js";
 export { BrowserHttpClient, type BrowserHttpConfig } from "./http.js";
 export { parseSse } from "./sse.js";
 export {
@@ -60,6 +69,20 @@ export type {
   RunIdentityInput,
   Paginated,
   SseEvent,
+  File,
+  FileType,
+  FileListParams,
+  FileUpdateParams,
+  FileCreateTextParams,
+  FileCreateOptions,
+  ListParams,
+  ConversationSummary,
+  ConversationItem,
+  ConversationItemList,
+  ConversationListParams,
+  ConversationItemListParams,
+  ConversationItemInclude,
+  ConversationResponse,
 } from "@introspection-sdk/types";
 export {
   IntrospectionAPIError,