@introspection-sdk/introspection-browser 0.5.0 → 0.5.2

package/.turbo/turbo-build.log

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

package/README.md

@@ -30,3 +30,62 @@ 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.
+
+> **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.

package/dist/api/client.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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";
+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;
+    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;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"}

package/dist/api/client.js

@@ -0,0 +1,74 @@
+/**
+ * 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";
+export class IntrospectionApiClient {
+    opts;
+    /** `/v1/tasks` operations bound to the DP session cookie. */
+    tasks;
+    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);
+    }
+    /**
+     * 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;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"}

package/dist/api/http.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Browser HTTP transport for the Introspection Data Plane `/v1` surface.
+ *
+ * The request/response machinery — URL joining, query building, body
+ * serialization, error mapping, SSE — 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 the HttpOnly
+ * `intro_dp_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.
+ */
+import { BaseHttpClient, stripTrailingSlash, toApiError } from "@introspection-sdk/http";
+export { stripTrailingSlash, toApiError };
+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>;
+}
+/**
+ * Cookie-authenticated HTTP wrapper bound to one DP endpoint. Has no
+ * opinion about which resource it serves — the caller picks the path.
+ */
+export declare class BrowserHttpClient extends BaseHttpClient {
+    constructor(cfg: BrowserHttpConfig);
+}
+//# sourceMappingURL=http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/api/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,UAAU,EACX,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC;AAE1C,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACzC;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;gBACvC,GAAG,EAAE,iBAAiB;CAYnC"}

package/dist/api/http.js

@@ -0,0 +1,34 @@
+/**
+ * Browser HTTP transport for the Introspection Data Plane `/v1` surface.
+ *
+ * The request/response machinery — URL joining, query building, body
+ * serialization, error mapping, SSE — 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 the HttpOnly
+ * `intro_dp_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.
+ */
+import { BaseHttpClient, stripTrailingSlash, toApiError, } from "@introspection-sdk/http";
+// Re-exported for `client.ts`, which redeems the DP session on `connect()`.
+export { stripTrailingSlash, toApiError };
+/**
+ * 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) {
+        super({
+            apiUrl: cfg.apiUrl,
+            additionalHeaders: cfg.additionalHeaders,
+            fetch: cfg.fetch,
+            transport: {
+                authHeaders: () => ({}),
+                credentials: "include",
+                onUnauthorized: cfg.onUnauthorized,
+            },
+        });
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/api/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/api/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,UAAU,GACX,MAAM,yBAAyB,CAAC;AAEjC,4EAA4E;AAC5E,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC;AAiB1C;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IACnD,YAAY,GAAsB;QAChC,KAAK,CAAC;YACJ,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,SAAS,EAAE;gBACT,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;gBACvB,WAAW,EAAE,SAAS;gBACtB,cAAc,EAAE,GAAG,CAAC,cAAc;aACnC;SACF,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/api/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * import { IntrospectionApiClient } from "@introspection-sdk/introspection-browser/api";
+ *
+ * const client = new IntrospectionApiClient({
+ *   dpUrl: "https://dp.us.introspection.dev",
+ *   projectId: "proj_…",
+ *   // your backend mints the 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",
+ *   identity: { user_id: "u_42" },
+ * });
+ * for await (const ev of run.stream()) console.log(ev.event, ev.data);
+ * ```
+ */
+export { IntrospectionApiClient, type IntrospectionApiClientOptions, } from "./client.js";
+export { TasksClient, TaskRunsClient, RunHandle, type CreateTaskParams, type StartTaskParams, } from "./tasks.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 { IntrospectionAPIError, AuthenticationError, InsufficientScopeError, NotFoundError, NetworkError, } from "@introspection-sdk/types";
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/api/index.js

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * import { IntrospectionApiClient } from "@introspection-sdk/introspection-browser/api";
+ *
+ * const client = new IntrospectionApiClient({
+ *   dpUrl: "https://dp.us.introspection.dev",
+ *   projectId: "proj_…",
+ *   // your backend mints the 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",
+ *   identity: { user_id: "u_42" },
+ * });
+ * for await (const ev of run.stream()) console.log(ev.event, ev.data);
+ * ```
+ */
+export { IntrospectionApiClient, } from "./client.js";
+export { TasksClient, TaskRunsClient, RunHandle, } from "./tasks.js";
+export { BrowserHttpClient } from "./http.js";
+export { parseSse } from "./sse.js";
+export { Paginator, cursorPaginate, } from "@introspection-sdk/http";
+export { IntrospectionAPIError, AuthenticationError, InsufficientScopeError, NotFoundError, NetworkError, } from "@introspection-sdk/types";
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

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

package/dist/api/sse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * SSE parsing now lives in the shared `@introspection-sdk/http` core so
+ * the browser and Node SDKs stay byte-for-byte identical. Re-exported
+ * here to keep the existing `./sse.js` import path stable.
+ */
+export { parseSse } from "@introspection-sdk/http";
+//# sourceMappingURL=sse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/api/sse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/api/sse.js

@@ -0,0 +1,7 @@
+/**
+ * SSE parsing now lives in the shared `@introspection-sdk/http` core so
+ * the browser and Node SDKs stay byte-for-byte identical. Re-exported
+ * here to keep the existing `./sse.js` import path stable.
+ */
+export { parseSse } from "@introspection-sdk/http";
+//# sourceMappingURL=sse.js.map

package/dist/api/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/api/sse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/api/tasks.d.ts

@@ -0,0 +1,83 @@
+import type { RunIdentityInput, SseEvent, Task, TaskCancelResponse, TaskCreateResponse, TaskListParams, TaskRun, TaskRunCreateParams, TaskUpdateParams, TaskVisibility } from "@introspection-sdk/types";
+import { Paginator } from "@introspection-sdk/http";
+import { BrowserHttpClient } from "./http.js";
+/**
+ * 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?: string;
+    /** Named recipe agent, when no `runtime_id` is pinned. */
+    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
+     * deployment default. Clamped to the task timeout.
+     */
+    idle_timeout_seconds?: number;
+    /** Caller identity for attribution; merged into `metadata.identity`. */
+    identity?: RunIdentityInput;
+}
+export interface StartTaskParams extends CreateTaskParams {
+    /** Required for the `start()` sugar that returns a run handle. */
+    prompt: string;
+}
+/** Live handle on a task's run: stream its events, collect text, cancel. */
+export declare class RunHandle {
+    readonly task: Task | null;
+    readonly run: TaskRun;
+    private readonly runs;
+    constructor(task: Task | null, run: TaskRun, runs: TaskRunsClient);
+    stream(): AsyncIterable<SseEvent>;
+    cancel(): Promise<TaskCancelResponse>;
+    /** Convenience: concatenate `data` from `text`/`message` SSE frames. */
+    text(): Promise<string>;
+}
+export declare class TaskRunsClient {
+    private readonly http;
+    constructor(http: BrowserHttpClient);
+    create(taskId: string, body: TaskRunCreateParams): Promise<RunHandle>;
+    get(taskId: string, runId: string): Promise<TaskRun>;
+    cancel(taskId: string, runId: string): Promise<TaskCancelResponse>;
+    stream(taskId: string, runId: string): AsyncIterable<SseEvent>;
+}
+/**
+ * Cookie-authenticated `/v1/tasks` client. Mirrors the Node SDK's
+ * `TasksApi` shape but is bound to a DP session cookie rather than a
+ * bearer token, and lets the caller select the agent on create.
+ */
+export declare class TasksClient {
+    private readonly http;
+    readonly runs: TaskRunsClient;
+    constructor(http: BrowserHttpClient);
+    /**
+     * Tasks matching `params`. `await` it for the first page (preserving
+     * the wire envelope's counts + `next` cursor), or `for await` it to
+     * stream every task across pages (fetched lazily — `limit` sets the
+     * page size, `next` the starting cursor; stop early to stop fetching).
+     *
+     * Mirrors the Node SDK's `TasksApi.list`, which is the source of truth
+     * for the `/v1/tasks` shape.
+     */
+    list(params?: TaskListParams): Paginator<Task>;
+    create(body: CreateTaskParams): Promise<TaskCreateResponse>;
+    get(taskId: string): Promise<Task>;
+    update(taskId: string, body: TaskUpdateParams): Promise<Task>;
+    delete(taskId: string): Promise<void>;
+    archive(taskId: string): Promise<void>;
+    unarchive(taskId: string): Promise<void>;
+    /** Sugar: create a task + return a handle on its initial run. */
+    start(params: StartTaskParams): Promise<RunHandle>;
+}
+//# sourceMappingURL=tasks.d.ts.map

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

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

package/dist/api/tasks.js

@@ -0,0 +1,146 @@
+import { cursorPaginate } from "@introspection-sdk/http";
+import { parseSse } from "./sse.js";
+function toTaskBody(params) {
+    const { identity, metadata, ...rest } = params;
+    const body = { ...rest };
+    const mergedMetadata = identity
+        ? { ...(metadata ?? {}), identity }
+        : metadata;
+    if (mergedMetadata !== undefined)
+        body.metadata = mergedMetadata;
+    return body;
+}
+/** Live handle on a task's run: stream its events, collect text, cancel. */
+export class RunHandle {
+    task;
+    run;
+    runs;
+    constructor(task, run, runs) {
+        this.task = task;
+        this.run = run;
+        this.runs = runs;
+    }
+    stream() {
+        return this.runs.stream(this.run.task_id, this.run.id);
+    }
+    cancel() {
+        return this.runs.cancel(this.run.task_id, this.run.id);
+    }
+    /** Convenience: concatenate `data` from `text`/`message` SSE frames. */
+    async text() {
+        let out = "";
+        for await (const ev of this.stream()) {
+            if (ev.event === "text" || ev.event === "message")
+                out += ev.data;
+        }
+        return out;
+    }
+}
+export class TaskRunsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async create(taskId, body) {
+        const res = await this.http.request({
+            method: "POST",
+            path: `/v1/tasks/${encodeURIComponent(taskId)}/runs`,
+            body,
+        });
+        return new RunHandle(null, res.run, this);
+    }
+    get(taskId, runId) {
+        return this.http.request({
+            method: "GET",
+            path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}`,
+        });
+    }
+    cancel(taskId, runId) {
+        return this.http.request({
+            method: "POST",
+            path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}/cancel`,
+        });
+    }
+    async *stream(taskId, runId) {
+        const res = await this.http.stream({
+            path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}/stream`,
+        });
+        yield* parseSse(res);
+    }
+}
+/**
+ * Cookie-authenticated `/v1/tasks` client. Mirrors the Node SDK's
+ * `TasksApi` shape but is bound to a DP session cookie rather than a
+ * bearer token, and lets the caller select the agent on create.
+ */
+export class TasksClient {
+    http;
+    runs;
+    constructor(http) {
+        this.http = http;
+        this.runs = new TaskRunsClient(http);
+    }
+    /**
+     * Tasks matching `params`. `await` it for the first page (preserving
+     * the wire envelope's counts + `next` cursor), or `for await` it to
+     * stream every task across pages (fetched lazily — `limit` sets the
+     * page size, `next` the starting cursor; stop early to stop fetching).
+     *
+     * Mirrors the Node SDK's `TasksApi.list`, which is the source of truth
+     * for the `/v1/tasks` shape.
+     */
+    list(params) {
+        return cursorPaginate((next) => this.http.request({
+            method: "GET",
+            path: "/v1/tasks",
+            query: { ...params, next },
+        }), params?.next);
+    }
+    create(body) {
+        return this.http.request({
+            method: "POST",
+            path: "/v1/tasks",
+            body: toTaskBody(body),
+        });
+    }
+    get(taskId) {
+        return this.http.request({
+            method: "GET",
+            path: `/v1/tasks/${encodeURIComponent(taskId)}`,
+        });
+    }
+    update(taskId, body) {
+        return this.http.request({
+            method: "PATCH",
+            path: `/v1/tasks/${encodeURIComponent(taskId)}`,
+            body,
+        });
+    }
+    delete(taskId) {
+        return this.http.request({
+            method: "DELETE",
+            path: `/v1/tasks/${encodeURIComponent(taskId)}`,
+            expect: "empty",
+        });
+    }
+    archive(taskId) {
+        return this.http.request({
+            method: "POST",
+            path: `/v1/tasks/${encodeURIComponent(taskId)}/archive`,
+            expect: "empty",
+        });
+    }
+    unarchive(taskId) {
+        return this.http.request({
+            method: "POST",
+            path: `/v1/tasks/${encodeURIComponent(taskId)}/unarchive`,
+            expect: "empty",
+        });
+    }
+    /** Sugar: create a task + return a handle on its initial run. */
+    async start(params) {
+        const res = await this.create(params);
+        return new RunHandle(res.task, res.run, this.runs);
+    }
+}
+//# sourceMappingURL=tasks.js.map

package/dist/api/tasks.js.map

@@ -0,0 +1 @@
+{"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.0",
+  "version": "0.5.2",
   "license": "Apache-2.0",
   "description": "Introspection observability SDK for the browser",
   "engines": {
@@ -13,21 +13,26 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "default": "./dist/api/index.js"
     }
   },
   "devDependencies": {
     "@types/node": "^22.19.20",
     "eslint": "^9.39.4",
     "typescript": "5.9.3",
-    "@repo/typescript-config": "0.0.0",
-    "@repo/eslint-config": "0.0.0"
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/api-logs": "^0.218.0",
-    "@opentelemetry/sdk-logs": "^0.218.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.218.0",
-    "@introspection-sdk/types": "0.5.0"
+    "@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"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",

package/src/api/client.ts

@@ -0,0 +1,98 @@
+/**
+ * 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";
+
+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 class IntrospectionApiClient {
+  /** `/v1/tasks` operations bound to the DP session cookie. */
+  readonly tasks: TasksClient;
+
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(private readonly opts: IntrospectionApiClientOptions) {
+    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);
+  }
+
+  /**
+   * 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(): 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, 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. */
+  private async reexchange(): Promise<boolean> {
+    try {
+      await this.exchange();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/api/http.ts

@@ -0,0 +1,55 @@
+/**
+ * Browser HTTP transport for the Introspection Data Plane `/v1` surface.
+ *
+ * The request/response machinery — URL joining, query building, body
+ * serialization, error mapping, SSE — 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 the HttpOnly
+ * `intro_dp_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.
+ */
+
+import {
+  BaseHttpClient,
+  stripTrailingSlash,
+  toApiError,
+} from "@introspection-sdk/http";
+
+// Re-exported for `client.ts`, which redeems the DP session on `connect()`.
+export { stripTrailingSlash, toApiError };
+
+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>;
+}
+
+/**
+ * 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,
+      additionalHeaders: cfg.additionalHeaders,
+      fetch: cfg.fetch,
+      transport: {
+        authHeaders: () => ({}),
+        credentials: "include",
+        onUnauthorized: cfg.onUnauthorized,
+      },
+    });
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * import { IntrospectionApiClient } from "@introspection-sdk/introspection-browser/api";
+ *
+ * const client = new IntrospectionApiClient({
+ *   dpUrl: "https://dp.us.introspection.dev",
+ *   projectId: "proj_…",
+ *   // your backend mints the 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",
+ *   identity: { user_id: "u_42" },
+ * });
+ * for await (const ev of run.stream()) console.log(ev.event, ev.data);
+ * ```
+ */
+
+export {
+  IntrospectionApiClient,
+  type IntrospectionApiClientOptions,
+} from "./client.js";
+export {
+  TasksClient,
+  TaskRunsClient,
+  RunHandle,
+  type CreateTaskParams,
+  type StartTaskParams,
+} from "./tasks.js";
+export { BrowserHttpClient, type BrowserHttpConfig } from "./http.js";
+export { parseSse } from "./sse.js";
+export {
+  Paginator,
+  cursorPaginate,
+  type PageSource,
+} from "@introspection-sdk/http";
+
+// Re-exported wire types for convenience.
+export type {
+  Task,
+  TaskRun,
+  TaskStatus,
+  TaskVisibility,
+  TaskCreateResponse,
+  TaskListParams,
+  TaskUpdateParams,
+  TaskRunCreateParams,
+  TaskCancelResponse,
+  RunIdentityInput,
+  Paginated,
+  SseEvent,
+} from "@introspection-sdk/types";
+export {
+  IntrospectionAPIError,
+  AuthenticationError,
+  InsufficientScopeError,
+  NotFoundError,
+  NetworkError,
+} from "@introspection-sdk/types";

package/src/api/sse.ts

@@ -0,0 +1,6 @@
+/**
+ * SSE parsing now lives in the shared `@introspection-sdk/http` core so
+ * the browser and Node SDKs stay byte-for-byte identical. Re-exported
+ * here to keep the existing `./sse.js` import path stable.
+ */
+export { parseSse } from "@introspection-sdk/http";

package/src/api/tasks.ts

@@ -0,0 +1,208 @@
+import type {
+  Paginated,
+  RunIdentityInput,
+  SseEvent,
+  Task,
+  TaskCancelResponse,
+  TaskCreateResponse,
+  TaskListParams,
+  TaskRun,
+  TaskRunCreateParams,
+  TaskRunResponse,
+  TaskUpdateParams,
+  TaskVisibility,
+} from "@introspection-sdk/types";
+import { Paginator, cursorPaginate } from "@introspection-sdk/http";
+import { BrowserHttpClient } from "./http.js";
+import { parseSse } from "./sse.js";
+
+/**
+ * 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?: string;
+  /** Named recipe agent, when no `runtime_id` is pinned. */
+  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
+   * deployment default. Clamped to the task timeout.
+   */
+  idle_timeout_seconds?: number;
+  /** Caller identity for attribution; merged into `metadata.identity`. */
+  identity?: RunIdentityInput;
+}
+
+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;
+}
+
+/** Live handle on a task's run: stream its events, collect text, cancel. */
+export class RunHandle {
+  constructor(
+    public readonly task: Task | null,
+    public readonly run: TaskRun,
+    private readonly runs: TaskRunsClient,
+  ) {}
+
+  stream(): AsyncIterable<SseEvent> {
+    return this.runs.stream(this.run.task_id, this.run.id);
+  }
+
+  cancel(): Promise<TaskCancelResponse> {
+    return this.runs.cancel(this.run.task_id, this.run.id);
+  }
+
+  /** Convenience: concatenate `data` from `text`/`message` SSE frames. */
+  async text(): Promise<string> {
+    let out = "";
+    for await (const ev of this.stream()) {
+      if (ev.event === "text" || ev.event === "message") out += ev.data;
+    }
+    return out;
+  }
+}
+
+export class TaskRunsClient {
+  constructor(private readonly http: BrowserHttpClient) {}
+
+  async create(taskId: string, body: TaskRunCreateParams): Promise<RunHandle> {
+    const res = await this.http.request<TaskRunResponse>({
+      method: "POST",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs`,
+      body,
+    });
+    return new RunHandle(null, res.run, this);
+  }
+
+  get(taskId: string, runId: string): Promise<TaskRun> {
+    return this.http.request<TaskRun>({
+      method: "GET",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}`,
+    });
+  }
+
+  cancel(taskId: string, runId: string): Promise<TaskCancelResponse> {
+    return this.http.request<TaskCancelResponse>({
+      method: "POST",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}/cancel`,
+    });
+  }
+
+  async *stream(taskId: string, runId: string): AsyncIterable<SseEvent> {
+    const res = await this.http.stream({
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}/stream`,
+    });
+    yield* parseSse(res);
+  }
+}
+
+/**
+ * Cookie-authenticated `/v1/tasks` client. Mirrors the Node SDK's
+ * `TasksApi` shape but is bound to a DP session cookie rather than a
+ * bearer token, and lets the caller select the agent on create.
+ */
+export class TasksClient {
+  readonly runs: TaskRunsClient;
+
+  constructor(private readonly http: BrowserHttpClient) {
+    this.runs = new TaskRunsClient(http);
+  }
+
+  /**
+   * Tasks matching `params`. `await` it for the first page (preserving
+   * the wire envelope's counts + `next` cursor), or `for await` it to
+   * stream every task across pages (fetched lazily — `limit` sets the
+   * page size, `next` the starting cursor; stop early to stop fetching).
+   *
+   * Mirrors the Node SDK's `TasksApi.list`, which is the source of truth
+   * for the `/v1/tasks` shape.
+   */
+  list(params?: TaskListParams): Paginator<Task> {
+    return cursorPaginate(
+      (next) =>
+        this.http.request<Paginated<Task>>({
+          method: "GET",
+          path: "/v1/tasks",
+          query: { ...params, next } as Record<string, unknown>,
+        }),
+      params?.next,
+    );
+  }
+
+  create(body: CreateTaskParams): Promise<TaskCreateResponse> {
+    return this.http.request<TaskCreateResponse>({
+      method: "POST",
+      path: "/v1/tasks",
+      body: toTaskBody(body),
+    });
+  }
+
+  get(taskId: string): Promise<Task> {
+    return this.http.request<Task>({
+      method: "GET",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}`,
+    });
+  }
+
+  update(taskId: string, body: TaskUpdateParams): Promise<Task> {
+    return this.http.request<Task>({
+      method: "PATCH",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}`,
+      body,
+    });
+  }
+
+  delete(taskId: string): Promise<void> {
+    return this.http.request<void>({
+      method: "DELETE",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}`,
+      expect: "empty",
+    });
+  }
+
+  archive(taskId: string): Promise<void> {
+    return this.http.request<void>({
+      method: "POST",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/archive`,
+      expect: "empty",
+    });
+  }
+
+  unarchive(taskId: string): Promise<void> {
+    return this.http.request<void>({
+      method: "POST",
+      path: `/v1/tasks/${encodeURIComponent(taskId)}/unarchive`,
+      expect: "empty",
+    });
+  }
+
+  /** Sugar: create a task + return a handle on its initial run. */
+  async start(params: StartTaskParams): Promise<RunHandle> {
+    const res = await this.create(params);
+    return new RunHandle(res.task, res.run, this.runs);
+  }
+}