@introspection-sdk/introspection-browser 0.20.0 → 0.21.1

package/src/api/client.ts

@@ -1,196 +0,0 @@
-/**
- * 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 browser talks only
- * to the Data Plane — runtime resolution and any other Control Plane work
- * stays on the app's backend, so the CP never needs to serve CORS to
- * customer web origins. The auth boundary:
- *
- *   1. The SPA's own backend ("broker") mints a short-lived 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) — and, when a specific runtime
- *      is needed, resolves its `runtime_id` server-side. The SPA fetches
- *      the token through the `getToken` callback.
- *   2. `connect()` redeems the token at the DP `POST /v1/oauth/exchange`
- *      for an HttpOnly session cookie, named for the token's environment lane
- *      (`intro_dp_development` / `intro_dp_staging` / `intro_dp_production`).
- *      Distinct names mean an app running several lanes holds a live session
- *      for each in one browser instead of the newest evicting the last.
- *   3. Every subsequent call rides that cookie (`credentials: "include"`)
- *      — `client.tasks.start({ runtime_id })`, `.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 { resolveBrowserFetch } from "./fetch.js";
-import {
-  ConversationsClient,
-  FilesClient,
-  SharesClient,
-} from "@introspection-sdk/http";
-import type { Environment } from "@introspection-sdk/types";
-import { TasksClient } from "./tasks.js";
-
-type CookieClients = {
-  tasks: TasksClient;
-  files: FilesClient;
-  conversations: ConversationsClient;
-  shares: SharesClient;
-};
-
-export interface IntrospectionApiClientOptions {
-  /**
-   * Data Plane REST base URL for the cookie-session APIs (`connect()` and
-   * `client.tasks` / `client.files` / `client.conversations` /
-   * `client.shares`). Required — the browser only talks to the DP.
-   */
-  dpUrl: 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. 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). */
-  fetch?: typeof fetch;
-  /** Extra headers merged into every DP request. */
-  additionalHeaders?: Record<string, string>;
-  /**
-   * Environment lane this client talks to.
-   *
-   * Normally omit it. `connect()` learns the lane from the exchange response,
-   * which the DP derives from the token's own `environment` claim — that is the
-   * authoritative source, and it is why a client cannot simply declare a lane
-   * it has no token for.
-   *
-   * Set it only to send the lane header before the first `connect()` resolves.
-   * If it disagrees with the token, `connect()` throws rather than silently
-   * preferring one.
-   */
-  environment?: Environment;
-}
-
-export class IntrospectionApiClient {
-  private readonly fetchImpl: typeof fetch;
-  private readonly cookieClients: CookieClients;
-  /**
-   * Lane established by the most recent exchange. Per instance, never module
-   * scope — two clients on one page holding different lanes is the point.
-   */
-  private resolvedEnvironment?: Environment;
-
-  constructor(private readonly opts: IntrospectionApiClientOptions) {
-    // Native browser `fetch` throws "Illegal invocation" when called as a
-    // method of this client (`this.fetchImpl(...)`); resolveBrowserFetch
-    // returns a global-safe wrapper. The same impl backs the connect()
-    // exchange here and the cookie-session resource calls via BrowserHttpClient.
-    this.fetchImpl = resolveBrowserFetch(opts.fetch);
-    if (!opts.dpUrl) {
-      throw new Error("IntrospectionApiClient requires a dpUrl");
-    }
-    this.resolvedEnvironment = opts.environment;
-    const http = new BrowserHttpClient({
-      apiUrl: opts.dpUrl,
-      additionalHeaders: opts.additionalHeaders,
-      fetch: this.fetchImpl,
-      onUnauthorized: () => this.reexchange(),
-      environment: () => this.resolvedEnvironment,
-    });
-    this.cookieClients = {
-      tasks: new TasksClient(http),
-      files: new FilesClient(http),
-      conversations: new ConversationsClient(http),
-      shares: new SharesClient(http),
-    };
-  }
-
-  /** `/v1/tasks` operations bound to the DP session cookie. */
-  get tasks(): TasksClient {
-    return this.cookieClients.tasks;
-  }
-
-  /** `/v1/files` operations bound to the DP session cookie. */
-  get files(): FilesClient {
-    return this.cookieClients.files;
-  }
-
-  /** Read-only `/v1/conversations` projection bound to the session cookie. */
-  get conversations(): ConversationsClient {
-    return this.cookieClients.conversations;
-  }
-
-  /** `/v1/shares` read-sharing grants bound to the session cookie. */
-  get shares(): SharesClient {
-    return this.cookieClients.shares;
-  }
-
-  /**
-   * Environment lane this client is connected to, once `connect()` has
-   * resolved. `undefined` before the first exchange, unless the constructor
-   * was given one.
-   */
-  get environment(): Environment | undefined {
-    return this.resolvedEnvironment;
-  }
-
-  /**
-   * Mint a token via `getToken` and redeem it at the DP for the session
-   * cookie. Call once before issuing task requests.
-   */
-  async connect(): Promise<void> {
-    await this.exchange();
-  }
-
-  private async exchange(): Promise<void> {
-    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 }),
-        credentials: "include",
-      },
-    );
-    if (!res.ok) throw await toApiError(res);
-
-    // The DP echoes the lane it resolved from the token's claim, so the client
-    // learns which cookie it just established without being told. Re-read on
-    // every exchange, including the 401 recovery path: if the broker has since
-    // switched lanes, a stale value would name a cookie we no longer hold.
-    const body = (await res.json().catch(() => ({}))) as {
-      environment?: Environment;
-    };
-    if (body.environment) {
-      if (this.opts.environment && this.opts.environment !== body.environment) {
-        throw new Error(
-          `IntrospectionApiClient is configured for environment ` +
-            `"${this.opts.environment}" but getToken() returned a token for ` +
-            `"${body.environment}".`,
-        );
-      }
-      this.resolvedEnvironment = body.environment;
-    }
-  }
-
-  /** 401 recovery: re-exchange, reporting success so the call can retry. */
-  private async reexchange(): Promise<boolean> {
-    try {
-      await this.exchange();
-      return true;
-    } catch {
-      return false;
-    }
-  }
-}

package/src/api/fetch.ts

@@ -1,31 +0,0 @@
-/**
- * Resolve the `fetch` implementation for browser Data Plane calls.
- *
- * The native browser `fetch` brand-checks its `this`: it must be the global
- * (`window` / `WorkerGlobalScope`). Storing `globalThis.fetch` on an instance
- * field and later calling it as a method — `this.fetchImpl(url, init)` — rebinds
- * `this` to the client instance, so the browser throws
- * `Failed to execute 'fetch' on 'Window': Illegal invocation`.
- *
- * When no custom `fetch` is supplied we therefore return a thin wrapper that
- * invokes `globalThis.fetch(...)` **as a method of the global** (correct `this`)
- * and resolves it **per call**. The per-call lookup is deliberate: the only
- * reason to go through `globalThis.fetch` rather than the lexical `fetch` is so
- * a swapped-in implementation is honored — that is the server-side proxy
- * (`@introspection-sdk/introspection-proxy` monkeypatches `globalThis.fetch`),
- * never a browser concern. A caller-supplied `fetch` is returned untouched.
- *
- * This lives in the browser package on purpose: Node's `fetch` (undici) has no
- * such brand check, so the shared {@link BaseHttpClient} / Node client keep
- * resolving `globalThis.fetch` directly (so the proxy override still applies).
- */
-export function resolveBrowserFetch(custom?: typeof fetch): typeof fetch {
-  if (custom) return custom;
-  if (!globalThis.fetch) {
-    throw new Error(
-      "global fetch is unavailable; pass `fetch` or run in a modern browser",
-    );
-  }
-  return (input: RequestInfo | URL, init?: RequestInit) =>
-    globalThis.fetch(input, init);
-}

package/src/api/http.ts

@@ -1,88 +0,0 @@
-/**
- * Browser HTTP transport for the Introspection Data Plane `/v1` surface.
- *
- * The request/response machinery — URL joining, query building, body
- * serialization, error mapping, AG-UI stream parsing — lives in the shared
- * `@introspection-sdk/http` {@link BaseHttpClient}. This module pins the
- * browser auth strategy on top of it: the DP is reached with an HttpOnly
- * session cookie minted by `POST /v1/oauth/exchange`, so every request opts
- * into `credentials: "include"` and sends NO bearer token — no Introspection
- * credential ever lives in JavaScript. A 401 (expired session cookie)
- * triggers a single `onUnauthorized` refresh + retry.
- *
- * The session cookie is named for its environment lane
- * (`intro_dp_development` / `intro_dp_staging` / `intro_dp_production`), so an
- * app running several lanes holds a live session for each in one browser. When
- * more than one is present the DP cannot tell which a request means, so we name
- * it in {@link ENVIRONMENT_HEADER}.
- */
-
-import {
-  BaseHttpClient,
-  stripTrailingSlash,
-  toApiError,
-} from "@introspection-sdk/http";
-
-import type { Environment } from "@introspection-sdk/types";
-
-import { resolveBrowserFetch } from "./fetch.js";
-
-// Re-exported for `client.ts`, which redeems the DP session on `connect()`.
-export { stripTrailingSlash, toApiError };
-
-/**
- * Names which environment lane's session cookie the DP should resolve.
- *
- * A selector, not a credential: the cookie it names is still validated
- * server-side, so naming a lane this browser holds no cookie for resolves to
- * nothing rather than granting anything.
- */
-export const ENVIRONMENT_HEADER = "x-introspection-environment";
-
-export interface BrowserHttpConfig {
-  /** DP REST base URL every request is prefixed with. */
-  apiUrl: string;
-  /** Extra headers merged into every request. */
-  additionalHeaders?: Record<string, string>;
-  /** Custom `fetch` (for tests or non-standard runtimes). */
-  fetch?: typeof fetch;
-  /**
-   * Invoked when a request comes back `401`. Return `true` if the DP
-   * session was refreshed and the request should be retried once;
-   * `false` to surface the original error.
-   */
-  onUnauthorized?: () => Promise<boolean>;
-  /**
-   * Reads the lane established by the most recent exchange.
-   *
-   * Called per request rather than captured at construction, because the lane
-   * is not known until `connect()` resolves — and it can change under a
-   * re-exchange.
-   */
-  environment?: () => Environment | undefined;
-}
-
-/**
- * Cookie-authenticated HTTP wrapper bound to one DP endpoint. Has no
- * opinion about which resource it serves — the caller picks the path.
- */
-export class BrowserHttpClient extends BaseHttpClient {
-  constructor(cfg: BrowserHttpConfig) {
-    super({
-      apiUrl: cfg.apiUrl,
-      // Resolve a browser-safe `fetch` (native `fetch` brand-checks `this`).
-      fetch: resolveBrowserFetch(cfg.fetch),
-      additionalHeaders: cfg.additionalHeaders,
-      transport: {
-        // Still no bearer token — the HttpOnly cookie is the credential. The
-        // only per-request contribution is which lane's cookie to resolve.
-        authHeaders: (): Record<string, string> => {
-          const environment = cfg.environment?.();
-          return environment ? { [ENVIRONMENT_HEADER]: environment } : {};
-        },
-        credentials: "include",
-        onUnauthorized: cfg.onUnauthorized,
-      },
-    });
-  }
-}

package/src/api/index.ts

@@ -1,133 +0,0 @@
-/**
- * Introspection Browser API surface — `@introspection-sdk/introspection-browser/api`.
- *
- * A cookie-authenticated client for creating and streaming Introspection
- * tasks directly from a single-page app, with no API key in the browser.
- * Separate from the package's default telemetry export so apps only pull
- * in what they use.
- *
- * The browser talks only to the Data Plane. Resolving a runtime by slug
- * (a Control Plane call) stays on your backend, which hands the browser a
- * short-lived access token plus the resolved `runtime_id`.
- *
- * @example
- * ```typescript
- * import { IntrospectionApiClient } from "@introspection-sdk/introspection-browser/api";
- *
- * // Your backend returns { token, runtimeId, dpUrl } — it mints the access
- * // token, resolves the runtime id, and surfaces the DP URL (e.g. from the
- * // Node SDK's serviceAccountToken response), so the browser never calls the CP.
- * const { token, runtimeId, dpUrl } = await fetch(
- *   "/api/introspection/session",
- * ).then((r) => r.json());
- *
- * const client = new IntrospectionApiClient({
- *   dpUrl,
- *   getToken: () => token,
- * });
- *
- * await client.connect(); // -> intro_dp_<environment> session cookie
- * const run = await client.tasks.start({
- *   prompt: "Summarize my latest order",
- *   runtime_id: runtimeId,
- * });
- * for await (const ev of run.stream()) console.log(ev.type);
- * ```
- */
-
-export {
-  IntrospectionApiClient,
-  type IntrospectionApiClientOptions,
-} from "./client.js";
-export {
-  TasksClient,
-  TaskRunsClient,
-  RunHandle,
-  type CreateTaskParams,
-  type StartTaskParams,
-} from "./tasks.js";
-export {
-  ConversationItemsClient,
-  ConversationsClient,
-  FileVersionsClient,
-  FilesClient,
-  SharesClient,
-  type FileUploadBody,
-} from "@introspection-sdk/http";
-export {
-  BrowserHttpClient,
-  ENVIRONMENT_HEADER,
-  type BrowserHttpConfig,
-} from "./http.js";
-export {
-  Paginator,
-  cursorPaginate,
-  type PageSource,
-} from "@introspection-sdk/http";
-export {
-  TranscriptAccumulator,
-  foldAgui,
-  foldSpans,
-  mergeTranscripts,
-} from "@introspection-sdk/http";
-export { EventType } from "@introspection-sdk/types";
-export {
-  genAiConversationId,
-  genAiInputMessages,
-  genAiOutputMessages,
-} from "@introspection-sdk/types";
-
-// Re-exported wire types for convenience.
-export type {
-  AGUIEvent,
-  BaseEvent,
-  Environment,
-  Interrupt,
-  Message,
-  ResumeEntry,
-  RunAgentInput,
-  Task,
-  TaskRun,
-  TaskStatus,
-  TaskRunKind,
-  TaskCreateResponse,
-  TaskListParams,
-  TaskUpdateParams,
-  TaskRunCreateParams,
-  TaskRunResumeParams,
-  TaskFileRef,
-  TaskCancelResponse,
-  TaskCancelOptions,
-  RunIdentityInput,
-  Paginated,
-  File,
-  FileType,
-  FileListParams,
-  FileUpdateParams,
-  FileCreateTextParams,
-  ListParams,
-  GenAiSpan,
-  GenAiSpanList,
-  Conversation,
-  ConversationAgent,
-  ConversationUsage,
-  ConversationCost,
-  ConversationMetrics,
-  SpanAttributes,
-  ConversationSortField,
-  ConversationListParams,
-  ConversationItemListParams,
-  ConversationItemInclude,
-  ResourceShare,
-  ShareResourceType,
-  ShareCreateParams,
-  ShareListParams,
-} from "@introspection-sdk/types";
-export {
-  IntrospectionAPIError,
-  AuthenticationError,
-  InsufficientScopeError,
-  NotFoundError,
-  NetworkError,
-  RunnerExpiredError,
-} from "@introspection-sdk/types";

package/src/api/tasks.ts

@@ -1,87 +0,0 @@
-import type {
-  RunIdentityInput,
-  TaskFileRef,
-  Uuid,
-} from "@introspection-sdk/types";
-import {
-  RunHandle,
-  TaskRunsClient,
-  TasksClient as SharedTasksClient,
-  type ResourceHttpClient,
-} from "@introspection-sdk/http";
-
-/**
- * Body for creating a task directly against the DP from the browser.
- *
- * A browser caller has no pre-pinned `Runner`, so — unlike the Node
- * SDK's runner-bound create — it selects the agent itself: pass
- * `runtime_id` to pin a recipe runtime, or `agent_name` to fall back to
- * a named recipe agent. `identity` is a convenience that is folded into
- * `metadata.identity` for attribution (the DP derives the owning
- * `identity_key` from the session's JWT claims, never from this body).
- */
-export interface CreateTaskParams {
-  prompt?: string;
-  /** Pin the task to a specific recipe runtime. */
-  runtime_id?: Uuid;
-  /** Named recipe agent, when no `runtime_id` is pinned. */
-  agent_name?: string;
-  title?: string;
-  metadata?: Record<string, unknown>;
-  /**
-   * 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
-   * deployment default. Clamped to the task timeout.
-   */
-  idle_timeout_seconds?: number;
-  /** Caller identity for attribution; merged into `metadata.identity`. */
-  identity?: RunIdentityInput;
-  /**
-   * Files to attach to this task, uploaded first via `client.files`.
-   *
-   * Only for files the user picked before the first turn. To attach one
-   * mid-conversation, put `files` on the run instead
-   * (`client.tasks.runs.create(taskId, { prompt, files })`) — the task's
-   * workspace is built when its sandbox starts, so a later attachment has to
-   * ride the turn that references it.
-   */
-  files?: TaskFileRef[];
-  /**
-   * 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. */
-  prompt: string;
-}
-
-function toTaskBody(params: CreateTaskParams): Record<string, unknown> {
-  const { identity, metadata, ...rest } = params;
-  const body: Record<string, unknown> = { ...rest };
-  const mergedMetadata = identity
-    ? { ...(metadata ?? {}), identity }
-    : metadata;
-  if (mergedMetadata !== undefined) body.metadata = mergedMetadata;
-  return body;
-}
-
-/**
- * Cookie-authenticated `/v1/tasks` client. The implementation is shared with
- * Node's runner-bound task client; this browser subclass only adds the
- * `identity -> metadata.identity` body mapping used by cookie-session calls.
- */
-export class TasksClient extends SharedTasksClient<
-  CreateTaskParams,
-  StartTaskParams
-> {
-  constructor(http: ResourceHttpClient) {
-    super(http, toTaskBody);
-  }
-}
-
-export { RunHandle, TaskRunsClient };