@introspection-sdk/introspection-browser 0.5.1 → 0.5.3

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @introspection-sdk/introspection-browser@0.5.1 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

@@ -30,3 +30,90 @@ client.feedback("thumbs_down", {
   comments: "Off topic",
 });
 ```
+
+## Client-side API (`/api`)
+
+The `@introspection-sdk/introspection-browser/api` entry point lets a
+single-page app **create and stream Introspection tasks directly from the
+browser, with no API key in JavaScript**. Authentication is the standard B2B2C
+flow (see the [`sample-auth`](../../examples/apps/sample-auth) example):
+
+1. The app's **own backend ("broker")** mints an Introspection access token —
+   via RFC 8693 token-exchange of the partner IdP token, a PKCE
+   `authorization_code`, or `client_credentials`. The IdP secret never leaves
+   the backend.
+2. `connect()` redeems that token at the Data Plane
+   (`POST /v1/oauth/exchange`) for the HttpOnly `intro_dp_session` cookie.
+3. Every subsequent call rides that cookie (`credentials: "include"`). When the
+   session expires, the client transparently re-mints it once on a `401`.
+
+```typescript
+import { IntrospectionApiClient } from "@introspection-sdk/introspection-browser/api";
+
+const client = new IntrospectionApiClient({
+  dpUrl: "https://dp.us.introspection.dev",
+  projectId: "proj_…",
+  // your backend returns a fresh Introspection access token
+  getToken: () => fetch("/api/introspection/token").then((r) => r.text()),
+});
+
+await client.connect(); // → intro_dp_session cookie
+
+const run = await client.tasks.start({
+  prompt: "Summarize my latest order",
+  agent_name: "support-agent", // or runtime_id: "rt_…"
+  identity: { user_id: "u_42" }, // folded into metadata.identity
+  visibility: "identity", // sharing scope; defaults by credential
+  idle_timeout_seconds: 120, // idle window before the sandbox is torn down
+});
+
+for await (const ev of run.stream()) {
+  console.log(ev.event, ev.data);
+}
+```
+
+`client.tasks` exposes the full CRUD surface (`create` / `start` / `get` /
+`list` / `update` / `delete` / `archive` / `unarchive`) plus per-run streaming
+(`run.stream()`, `run.text()`, `run.cancel()`).
+
+Both `create` and `start` accept two optional task controls:
+
+- **`visibility`** (`"identity" | "member" | "project"`) — the task's minimum
+  sharing scope. Defaults to `"identity"` when the credential carries an
+  identity claim, else `"project"`. The owning `identity_key` is always derived
+  from the session JWT, never the request body.
+- **`idle_timeout_seconds`** (`number`) — overrides the interactive idle window
+  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/file/conversation calls to succeed.

package/dist/api/client.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Browser-side Introspection API client.
+ *
+ * Lets a single-page app create and stream Introspection tasks directly
+ * from the browser, with no API key in JavaScript. The auth boundary:
+ *
+ *   1. The SPA's own backend ("broker") mints an Introspection access
+ *      token — via RFC 8693 token-exchange of the partner IdP token, a
+ *      PKCE `authorization_code`, or `client_credentials`. The IdP
+ *      secret never leaves the backend. The SPA fetches that token
+ *      through the `getToken` callback.
+ *   2. `connect()` redeems the token at the DP `POST /v1/oauth/exchange`
+ *      for the HttpOnly `intro_dp_session` cookie.
+ *   3. Every subsequent call rides that cookie (`credentials: "include"`)
+ *      — `client.tasks.start(...)`, `.get(...)`, run streaming, etc.
+ *
+ * When the session cookie expires, an in-flight request gets a 401, and
+ * the client transparently re-runs `getToken` + the DP exchange once
+ * 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;
+    /** 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.
+     */
+    getToken: () => string | Promise<string>;
+    /** Custom `fetch` (for tests or non-standard runtimes). */
+    fetch?: typeof fetch;
+    /** Extra headers merged into every DP request. */
+    additionalHeaders?: Record<string, string>;
+}
+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);
+    /**
+     * Mint a token via `getToken` and redeem it at the DP for the
+     * `intro_dp_session` cookie. Call once before issuing task requests.
+     */
+    connect(): Promise<void>;
+    private exchange;
+    /** 401 recovery: re-exchange, reporting success so the call can retry. */
+    private reexchange;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +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;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

@@ -0,0 +1,82 @@
+/**
+ * Browser-side Introspection API client.
+ *
+ * Lets a single-page app create and stream Introspection tasks directly
+ * from the browser, with no API key in JavaScript. The auth boundary:
+ *
+ *   1. The SPA's own backend ("broker") mints an Introspection access
+ *      token — via RFC 8693 token-exchange of the partner IdP token, a
+ *      PKCE `authorization_code`, or `client_credentials`. The IdP
+ *      secret never leaves the backend. The SPA fetches that token
+ *      through the `getToken` callback.
+ *   2. `connect()` redeems the token at the DP `POST /v1/oauth/exchange`
+ *      for the HttpOnly `intro_dp_session` cookie.
+ *   3. Every subsequent call rides that cookie (`credentials: "include"`)
+ *      — `client.tasks.start(...)`, `.get(...)`, run streaming, etc.
+ *
+ * When the session cookie expires, an in-flight request gets a 401, and
+ * the client transparently re-runs `getToken` + the DP exchange once
+ * before retrying.
+ */
+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;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new Error("global fetch is unavailable; pass `fetch` or run in a modern browser");
+        }
+        const http = new BrowserHttpClient({
+            apiUrl: opts.dpUrl,
+            additionalHeaders: opts.additionalHeaders,
+            fetch: opts.fetch,
+            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
+     * `intro_dp_session` cookie. Call once before issuing task requests.
+     */
+    async connect() {
+        await this.exchange();
+    }
+    async exchange() {
+        const token = await this.opts.getToken();
+        const res = await this.fetchImpl(`${stripTrailingSlash(this.opts.dpUrl)}/v1/oauth/exchange`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(this.opts.additionalHeaders ?? {}),
+            },
+            body: JSON.stringify({ token, project_id: this.opts.projectId }),
+            credentials: "include",
+        });
+        if (!res.ok)
+            throw await toApiError(res);
+    }
+    /** 401 recovery: re-exchange, reporting success so the call can retry. */
+    async reexchange() {
+        try {
+            await this.exchange();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -0,0 +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;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"}