@introspection-sdk/introspection-browser 0.5.2 → 0.5.4

package/dist/api/index.js

@@ -12,8 +12,8 @@
  *
  * const client = new IntrospectionApiClient({
  *   dpUrl: "https://dp.us.introspection.dev",
- *   projectId: "proj_…",
- *   // your backend mints the Introspection access token
+ *   // your backend mints the Introspection access token (the session's
+ *   // project is derived from its claims — no projectId option needed)
  *   getToken: () => fetch("/api/introspection/token").then((r) => r.text()),
  * });
  *
@@ -28,6 +28,9 @@
  */
 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 { SharesClient } from "./shares.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,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,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;AAiCjC,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,aAAa,EACb,YAAY,GACb,MAAM,0BAA0B,CAAC"}

package/dist/api/shares.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Cookie-authenticated Resource Shares client for the browser (`/v1/shares`).
+ *
+ * Read-sharing grants for files and conversations: `create` / `list` / `get` /
+ * `delete` (revoke). A grant carries a `url` (with the `?share_id` capability) —
+ * read the shared resource via `client.files.get(id, { shareId })` or
+ * `client.conversations.items(id, { shareId })`. To fork a new task from a
+ * shared conversation, pass `fork_share_id` to `client.tasks.create(...)`.
+ */
+import type { ResourceShare, ShareCreateParams, ShareListParams } from "@introspection-sdk/types";
+import { Paginator } from "@introspection-sdk/http";
+import { BrowserHttpClient } from "./http.js";
+/** Cookie-authenticated `/v1/shares` client. */
+export declare class SharesClient {
+    private readonly http;
+    constructor(http: BrowserHttpClient);
+    /**
+     * List grants the caller created or that target them. `await` for the first
+     * page, or `for await` to stream every grant across pages.
+     */
+    list(params?: ShareListParams): Paginator<ResourceShare>;
+    /** Create a read-sharing grant. The caller must own the target resource. */
+    create(body: ShareCreateParams): Promise<ResourceShare>;
+    /** Read a single grant (carries the `url` to the shared resource). */
+    get(shareId: string): Promise<ResourceShare>;
+    /** Revoke a grant. Only the grantor (or an admin/owner) may revoke. */
+    delete(shareId: string): Promise<void>;
+}
+//# sourceMappingURL=shares.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shares.d.ts","sourceRoot":"","sources":["../../src/api/shares.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAEV,aAAa,EACb,iBAAiB,EACjB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,gDAAgD;AAChD,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,iBAAiB;IAEpD;;;OAGG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,aAAa,CAAC;IAYxD,4EAA4E;IAC5E,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAQvD,sEAAsE;IACtE,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAO5C,uEAAuE;IACvE,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOvC"}

package/dist/api/shares.js

@@ -0,0 +1,52 @@
+/**
+ * Cookie-authenticated Resource Shares client for the browser (`/v1/shares`).
+ *
+ * Read-sharing grants for files and conversations: `create` / `list` / `get` /
+ * `delete` (revoke). A grant carries a `url` (with the `?share_id` capability) —
+ * read the shared resource via `client.files.get(id, { shareId })` or
+ * `client.conversations.items(id, { shareId })`. To fork a new task from a
+ * shared conversation, pass `fork_share_id` to `client.tasks.create(...)`.
+ */
+import { cursorPaginate } from "@introspection-sdk/http";
+/** Cookie-authenticated `/v1/shares` client. */
+export class SharesClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * List grants the caller created or that target them. `await` for the first
+     * page, or `for await` to stream every grant across pages.
+     */
+    list(params) {
+        return cursorPaginate((next) => this.http.request({
+            method: "GET",
+            path: "/v1/shares",
+            query: { ...params, next },
+        }), params?.next);
+    }
+    /** Create a read-sharing grant. The caller must own the target resource. */
+    create(body) {
+        return this.http.request({
+            method: "POST",
+            path: "/v1/shares",
+            body,
+        });
+    }
+    /** Read a single grant (carries the `url` to the shared resource). */
+    get(shareId) {
+        return this.http.request({
+            method: "GET",
+            path: `/v1/shares/${encodeURIComponent(shareId)}`,
+        });
+    }
+    /** Revoke a grant. Only the grantor (or an admin/owner) may revoke. */
+    delete(shareId) {
+        return this.http.request({
+            method: "DELETE",
+            path: `/v1/shares/${encodeURIComponent(shareId)}`,
+            expect: "empty",
+        });
+    }
+}
+//# sourceMappingURL=shares.js.map

package/dist/api/shares.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shares.js","sourceRoot":"","sources":["../../src/api/shares.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAa,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAGpE,gDAAgD;AAChD,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,IAAuB;QAAvB,SAAI,GAAJ,IAAI,CAAmB;IAAG,CAAC;IAExD;;;OAGG;IACH,IAAI,CAAC,MAAwB;QAC3B,OAAO,cAAc,CACnB,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAC,IAAI,CAAC,OAAO,CAA2B;YAC1C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,IAAI,EAA6B;SACtD,CAAC,EACJ,MAAM,EAAE,IAAI,CACb,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,MAAM,CAAC,IAAuB;QAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAgB;YACtC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,YAAY;YAClB,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IAED,sEAAsE;IACtE,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAgB;YACtC,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,cAAc,kBAAkB,CAAC,OAAO,CAAC,EAAE;SAClD,CAAC,CAAC;IACL,CAAC;IAED,uEAAuE;IACvE,MAAM,CAAC,OAAe;QACpB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAO;YAC7B,MAAM,EAAE,QAAQ;YAChB,IAAI,EAAE,cAAc,kBAAkB,CAAC,OAAO,CAAC,EAAE;YACjD,MAAM,EAAE,OAAO;SAChB,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/api/tasks.d.ts

@@ -1,4 +1,4 @@
-import type { RunIdentityInput, SseEvent, Task, TaskCancelResponse, TaskCreateResponse, TaskListParams, TaskRun, TaskRunCreateParams, TaskUpdateParams, TaskVisibility } from "@introspection-sdk/types";
+import type { RunIdentityInput, SseEvent, Task, TaskCancelResponse, TaskCreateResponse, TaskListParams, TaskRun, TaskRunCreateParams, TaskUpdateParams } from "@introspection-sdk/types";
 import { Paginator } from "@introspection-sdk/http";
 import { BrowserHttpClient } from "./http.js";
 /**
@@ -19,7 +19,6 @@ export interface CreateTaskParams {
     agent_name?: string;
     title?: string;
     metadata?: Record<string, unknown>;
-    visibility?: TaskVisibility;
     /**
      * Override the interactive idle window (seconds) before the sandbox is
      * torn down. `0` tears down as soon as it's provisioned; omit to use the
@@ -28,6 +27,13 @@ export interface CreateTaskParams {
     idle_timeout_seconds?: number;
     /** Caller identity for attribution; merged into `metadata.identity`. */
     identity?: RunIdentityInput;
+    /**
+     * Fork from a shared conversation: the `/v1/shares` grant id for the source
+     * conversation. Its presence makes this create a fork — the server seeds the
+     * new task with that conversation's history, read via the share (the
+     * permissions boundary).
+     */
+    fork_share_id?: string;
 }
 export interface StartTaskParams extends CreateTaskParams {
     /** Required for the `start()` sugar that returns a run handle. */

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

@@ -1 +1 @@
-{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/api/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,gBAAgB,EAChB,QAAQ,EACR,IAAI,EACJ,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,mBAAmB,EAEnB,gBAAgB,EAChB,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAG9C;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB;AAYD,4EAA4E;AAC5E,qBAAa,SAAS;aAEF,IAAI,EAAE,IAAI,GAAG,IAAI;aACjB,GAAG,EAAE,OAAO;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAFL,IAAI,EAAE,IAAI,GAAG,IAAI,EACjB,GAAG,EAAE,OAAO,EACX,IAAI,EAAE,cAAc;IAGvC,MAAM,IAAI,aAAa,CAAC,QAAQ,CAAC;IAIjC,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAIrC,wEAAwE;IAClE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAO9B;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,iBAAiB;IAE9C,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IAS3E,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOpD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAO3D,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC;CAMtE;AAED;;;;GAIG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;gBAED,IAAI,EAAE,iBAAiB;IAIpD;;;;;;;;OAQG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC,IAAI,CAAC;IAY9C,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAQ3D,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxC,iEAAiE;IAC3D,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC;CAIzD"}
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/api/tasks.ts"],"names":[],"mappings":"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"}

package/dist/api/tasks.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-sdk/introspection-browser",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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/http": "0.5.4",
+    "@introspection-sdk/types": "0.5.4"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",

package/src/api/client.ts

@@ -21,16 +21,19 @@
 
 import { BrowserHttpClient, stripTrailingSlash, toApiError } from "./http.js";
 import { TasksClient } from "./tasks.js";
+import { FilesClient } from "./files.js";
+import { ConversationsClient } from "./conversations.js";
+import { SharesClient } from "./shares.js";
 
 export interface IntrospectionApiClientOptions {
   /** Data Plane REST base URL (e.g. `https://dp.us.introspection.dev`). */
   dpUrl: string;
-  /** Project the session is scoped to. */
-  projectId: string;
   /**
    * Returns a fresh Introspection access token from the app's broker
    * (its own backend). Called on `connect()` and again whenever the DP
-   * session cookie needs re-minting after a 401.
+   * session cookie needs re-minting after a 401. The session's project is
+   * derived from this token's claims server-side — there is no separate
+   * project option.
    */
   getToken: () => string | Promise<string>;
   /** Custom `fetch` (for tests or non-standard runtimes). */
@@ -42,6 +45,12 @@ 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;
+  /** `/v1/shares` read-sharing grants bound to the session cookie. */
+  readonly shares: SharesClient;
 
   private readonly fetchImpl: typeof fetch;
 
@@ -59,6 +68,9 @@ export class IntrospectionApiClient {
       onUnauthorized: () => this.reexchange(),
     });
     this.tasks = new TasksClient(http);
+    this.files = new FilesClient(http);
+    this.conversations = new ConversationsClient(http);
+    this.shares = new SharesClient(http);
   }
 
   /**
@@ -79,7 +91,7 @@ export class IntrospectionApiClient {
           "Content-Type": "application/json",
           ...(this.opts.additionalHeaders ?? {}),
         },
-        body: JSON.stringify({ token, project_id: this.opts.projectId }),
+        body: JSON.stringify({ token }),
         credentials: "include",
       },
     );

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,179 @@
+/**
+ * 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 ownership and access are enforced server-side.
+ */
+
+import type {
+  File as FileResource,
+  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): Promise<FileResource> {
+    const form = toFormData(body);
+    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): Promise<FileResource> {
+    const form = toFormData(body);
+    return this.http.request<FileResource>({
+      method: "POST",
+      path: "/v1/files",
+      body: form,
+    });
+  }
+
+  createText(body: FileCreateTextParams): Promise<FileResource> {
+    return this.http.request<FileResource>({
+      method: "POST",
+      path: "/v1/files",
+      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): 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);
+  return fd;
+}