@introspection-sdk/introspection-browser 0.14.0 → 0.16.0

package/.turbo/turbo-build.log

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

package/README.md

@@ -50,7 +50,8 @@ customer web origins.
    `client.runtimes.resolve("support-agent")`) and supplies the Data
    Plane URL, so the SPA needs no Introspection config of its own.
 2. `client.connect()` redeems the token at the **Data Plane**
-   `POST /v1/oauth/exchange` for the HttpOnly `intro_dp_session` cookie.
+   `POST /v1/oauth/exchange` for an HttpOnly session cookie, named for the
+   token's environment lane (see [Environments](#environments)).
 3. `client.tasks.start({ runtime_id })` and friends ride that cookie against
    the Data Plane for tasks, files, conversations, and shares.
 
@@ -69,7 +70,7 @@ const client = new IntrospectionApiClient({
   getToken: () => token,
 });
 
-await client.connect(); // -> intro_dp_session cookie
+await client.connect(); // -> intro_dp_<environment> session cookie
 
 const run = await client.tasks.start({
   prompt: "Summarize my latest order",
@@ -94,6 +95,48 @@ as soon as it's provisioned; omit to use the deployment default. Clamped to the
 task timeout. When no `runtime_id` is supplied, pass `agent_name` to select a
 named recipe agent instead.
 
+### Environments
+
+The session cookie is named for its environment lane —
+`intro_dp_development`, `intro_dp_staging`, `intro_dp_production` — so an app
+running more than one lane holds a live session for **each** in one browser. A
+single shared name gave the browser one slot, so a second `connect()` evicted
+the first.
+
+**You never pass the environment in.** Your backend picks the lane when it
+mints the token; the Data Plane reads it off the token's claim and returns it,
+and the client sends it back as `x-introspection-environment` so the right
+cookie is resolved:
+
+```typescript
+const dev = new IntrospectionApiClient({
+  dpUrl,
+  getToken: () => mintToken({ environment: "development" }),
+});
+const prod = new IntrospectionApiClient({
+  dpUrl,
+  getToken: () => mintToken({ environment: "production" }),
+});
+
+await Promise.all([dev.connect(), prod.connect()]);
+
+dev.environment; // "development" -> cookie intro_dp_development
+prod.environment; // "production"  -> cookie intro_dp_production
+
+await dev.tasks.list(); // x-introspection-environment: development
+await prod.tasks.list(); // x-introspection-environment: production
+```
+
+`client.environment` is `undefined` until `connect()` resolves. The optional
+`environment` constructor option sends the header before that first exchange;
+if it disagrees with the token, `connect()` throws rather than silently
+preferring one — the token is the authority.
+
+> **Requires a Data Plane that returns `environment` from
+> `/v1/oauth/exchange`.** Against an older deployment `client.environment`
+> stays `undefined`, no header is sent, and a single-lane app keeps working
+> unchanged.
+
 ## Files and conversations
 
 The same cookie session also reaches `/v1/files` and (read-only)

package/dist/api/client.d.ts

@@ -14,7 +14,10 @@
  *      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 the HttpOnly `intro_dp_session` cookie.
+ *      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.
@@ -24,6 +27,7 @@
  * before retrying.
  */
 import { ConversationsClient, FilesClient, SharesClient } from "@introspection-sdk/http";
+import type { Environment } from "@introspection-sdk/types";
 import { TasksClient } from "./tasks.js";
 export interface IntrospectionApiClientOptions {
     /**
@@ -44,11 +48,29 @@ export interface IntrospectionApiClientOptions {
     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 declare class IntrospectionApiClient {
     private readonly opts;
     private readonly fetchImpl;
     private readonly 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?;
     constructor(opts: IntrospectionApiClientOptions);
     /** `/v1/tasks` operations bound to the DP session cookie. */
     get tasks(): TasksClient;
@@ -59,8 +81,14 @@ export declare class IntrospectionApiClient {
     /** `/v1/shares` read-sharing grants bound to the session cookie. */
     get shares(): SharesClient;
     /**
-     * Mint a token via `getToken` and redeem it at the DP for the
-     * `intro_dp_session` cookie. Call once before issuing task requests.
+     * 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;
+    /**
+     * Mint a token via `getToken` and redeem it at the DP for the session
+     * cookie. Call once before issuing task requests.
      */
     connect(): Promise<void>;
     private exchange;

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,YAAY,EACb,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AASzC,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;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;IAIrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;gBAEjB,IAAI,EAAE,6BAA6B;IAuBhE,6DAA6D;IAC7D,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,6DAA6D;IAC7D,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,4EAA4E;IAC5E,IAAI,aAAa,IAAI,mBAAmB,CAEvC;IAED,oEAAoE;IACpE,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAIhB,QAAQ;IAiBtB,0EAA0E;YAC5D,UAAU;CAQzB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,YAAY,EACb,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AASzC,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;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;IAC3C;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,sBAAsB;IASrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IARjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAAC,CAAc;gBAEb,IAAI,EAAE,6BAA6B;IAyBhE,6DAA6D;IAC7D,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,6DAA6D;IAC7D,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,4EAA4E;IAC5E,IAAI,aAAa,IAAI,mBAAmB,CAEvC;IAED,oEAAoE;IACpE,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED;;;;OAIG;IACH,IAAI,WAAW,IAAI,WAAW,GAAG,SAAS,CAEzC;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAIhB,QAAQ;IAmCtB,0EAA0E;YAC5D,UAAU;CAQzB"}

package/dist/api/client.js

@@ -14,7 +14,10 @@
  *      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 the HttpOnly `intro_dp_session` cookie.
+ *      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.
@@ -31,6 +34,11 @@ export class IntrospectionApiClient {
     opts;
     fetchImpl;
     cookieClients;
+    /**
+     * Lane established by the most recent exchange. Per instance, never module
+     * scope — two clients on one page holding different lanes is the point.
+     */
+    resolvedEnvironment;
     constructor(opts) {
         this.opts = opts;
         // Native browser `fetch` throws "Illegal invocation" when called as a
@@ -41,11 +49,13 @@ export class IntrospectionApiClient {
         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),
@@ -71,8 +81,16 @@ export class IntrospectionApiClient {
         return this.cookieClients.shares;
     }
     /**
-     * Mint a token via `getToken` and redeem it at the DP for the
-     * `intro_dp_session` cookie. Call once before issuing task requests.
+     * Environment lane this client is connected to, once `connect()` has
+     * resolved. `undefined` before the first exchange, unless the constructor
+     * was given one.
+     */
+    get environment() {
+        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() {
         await this.exchange();
@@ -90,6 +108,19 @@ export class IntrospectionApiClient {
         });
         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(() => ({})));
+        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. */
     async reexchange() {

package/dist/api/client.js.map

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

package/dist/api/http.d.ts

@@ -4,14 +4,29 @@
  * 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 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.
+ * 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";
 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 declare const ENVIRONMENT_HEADER = "x-introspection-environment";
 export interface BrowserHttpConfig {
     /** DP REST base URL every request is prefixed with. */
     apiUrl: string;
@@ -25,6 +40,14 @@ export interface BrowserHttpConfig {
      * `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

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

@@ -1 +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;AAKjC,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;CAanC"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/api/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,UAAU,EACX,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAK5D,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAEhE,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;IACxC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,WAAW,GAAG,SAAS,CAAC;CAC7C;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;gBACvC,GAAG,EAAE,iBAAiB;CAkBnC"}

package/dist/api/http.js

@@ -4,16 +4,30 @@
  * 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 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.
+ * 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 { 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";
 /**
  * Cookie-authenticated HTTP wrapper bound to one DP endpoint. Has no
  * opinion about which resource it serves — the caller picks the path.
@@ -26,7 +40,12 @@ export class BrowserHttpClient extends BaseHttpClient {
             fetch: resolveBrowserFetch(cfg.fetch),
             additionalHeaders: cfg.additionalHeaders,
             transport: {
-                authHeaders: () => ({}),
+                // Still no bearer token — the HttpOnly cookie is the credential. The
+                // only per-request contribution is which lane's cookie to resolve.
+                authHeaders: () => {
+                    const environment = cfg.environment?.();
+                    return environment ? { [ENVIRONMENT_HEADER]: environment } : {};
+                },
                 credentials: "include",
                 onUnauthorized: cfg.onUnauthorized,
             },

package/dist/api/http.js.map

@@ -1 +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,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,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,uEAAuE;YACvE,KAAK,EAAE,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC;YACrC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,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"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/api/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,UAAU,GACX,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,4EAA4E;AAC5E,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,6BAA6B,CAAC;AAyBhE;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IACnD,YAAY,GAAsB;QAChC,KAAK,CAAC;YACJ,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,uEAAuE;YACvE,KAAK,EAAE,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC;YACrC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,SAAS,EAAE;gBACT,qEAAqE;gBACrE,mEAAmE;gBACnE,WAAW,EAAE,GAA2B,EAAE;oBACxC,MAAM,WAAW,GAAG,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;oBACxC,OAAO,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,kBAAkB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClE,CAAC;gBACD,WAAW,EAAE,SAAS;gBACtB,cAAc,EAAE,GAAG,CAAC,cAAc;aACnC;SACF,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/api/index.d.ts

@@ -26,7 +26,7 @@
  *   getToken: () => token,
  * });
  *
- * await client.connect(); // -> intro_dp_session cookie
+ * await client.connect(); // -> intro_dp_<environment> session cookie
  * const run = await client.tasks.start({
  *   prompt: "Summarize my latest order",
  *   runtime_id: runtimeId,
@@ -37,9 +37,9 @@
 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, type BrowserHttpConfig } from "./http.js";
+export { BrowserHttpClient, ENVIRONMENT_HEADER, type BrowserHttpConfig, } from "./http.js";
 export { Paginator, cursorPaginate, type PageSource, } from "@introspection-sdk/http";
 export { EventType } from "@introspection-sdk/types";
-export type { AGUIEvent, BaseEvent, Interrupt, Message, ResumeEntry, RunAgentInput, Task, TaskRun, TaskStatus, TaskRunKind, TaskCreateResponse, TaskListParams, TaskUpdateParams, TaskRunCreateParams, TaskRunResumeParams, TaskCancelResponse, TaskCancelOptions, RunIdentityInput, Paginated, File, FileType, FileListParams, FileUpdateParams, FileCreateTextParams, ListParams, ConversationSummary, ConversationSortField, ConversationItem, ConversationItemList, ConversationListParams, ConversationItemListParams, ConversationItemInclude, ConversationResponse, ResourceShare, ShareResourceType, ShareCreateParams, ShareListParams, } from "@introspection-sdk/types";
+export type { AGUIEvent, BaseEvent, Environment, Interrupt, Message, ResumeEntry, RunAgentInput, Task, TaskRun, TaskStatus, TaskRunKind, TaskCreateResponse, TaskListParams, TaskUpdateParams, TaskRunCreateParams, TaskRunResumeParams, TaskCancelResponse, TaskCancelOptions, RunIdentityInput, Paginated, File, FileType, FileListParams, FileUpdateParams, FileCreateTextParams, ListParams, ConversationSummary, ConversationSortField, ConversationItem, ConversationItemList, ConversationListParams, ConversationItemListParams, ConversationItemInclude, ConversationResponse, ResourceShare, ShareResourceType, ShareCreateParams, ShareListParams, } from "@introspection-sdk/types";
 export { IntrospectionAPIError, AuthenticationError, InsufficientScopeError, NotFoundError, NetworkError, RunnerExpiredError, } from "@introspection-sdk/types";
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/api/index.js

@@ -26,7 +26,7 @@
  *   getToken: () => token,
  * });
  *
- * await client.connect(); // -> intro_dp_session cookie
+ * await client.connect(); // -> intro_dp_<environment> session cookie
  * const run = await client.tasks.start({
  *   prompt: "Summarize my latest order",
  *   runtime_id: runtimeId,
@@ -37,7 +37,7 @@
 export { IntrospectionApiClient, } from "./client.js";
 export { TasksClient, TaskRunsClient, RunHandle, } from "./tasks.js";
 export { ConversationItemsClient, ConversationsClient, FileVersionsClient, FilesClient, SharesClient, } from "@introspection-sdk/http";
-export { BrowserHttpClient } from "./http.js";
+export { BrowserHttpClient, ENVIRONMENT_HEADER, } from "./http.js";
 export { Paginator, cursorPaginate, } from "@introspection-sdk/http";
 export { EventType } from "@introspection-sdk/types";
 export { IntrospectionAPIError, AuthenticationError, InsufficientScopeError, NotFoundError, NetworkError, RunnerExpiredError, } from "@introspection-sdk/types";

package/dist/api/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EACL,sBAAsB,GAEvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,GAGV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,YAAY,GAEb,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAA0B,MAAM,WAAW,CAAC;AACtE,OAAO,EACL,SAAS,EACT,cAAc,GAEf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AA0CrD,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,aAAa,EACb,YAAY,EACZ,kBAAkB,GACnB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EACL,sBAAsB,GAEvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,GAGV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,YAAY,GAEb,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,iBAAiB,EACjB,kBAAkB,GAEnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,SAAS,EACT,cAAc,GAEf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AA2CrD,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,aAAa,EACb,YAAY,EACZ,kBAAkB,GACnB,MAAM,0BAA0B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-sdk/introspection-browser",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "license": "Apache-2.0",
   "description": "Introspection observability SDK for the browser",
   "engines": {
@@ -31,8 +31,8 @@
     "@opentelemetry/api-logs": "^0.221.0",
     "@opentelemetry/sdk-logs": "^0.221.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.221.0",
-    "@introspection-sdk/types": "0.14.0",
-    "@introspection-sdk/http": "0.14.0"
+    "@introspection-sdk/types": "0.16.0",
+    "@introspection-sdk/http": "0.16.0"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",

package/src/api/client.ts

@@ -14,7 +14,10 @@
  *      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 the HttpOnly `intro_dp_session` cookie.
+ *      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.
@@ -31,6 +34,7 @@ import {
   FilesClient,
   SharesClient,
 } from "@introspection-sdk/http";
+import type { Environment } from "@introspection-sdk/types";
 import { TasksClient } from "./tasks.js";
 
 type CookieClients = {
@@ -59,11 +63,29 @@ export interface IntrospectionApiClientOptions {
   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
@@ -74,11 +96,13 @@ export class IntrospectionApiClient {
     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),
@@ -109,8 +133,17 @@ export class IntrospectionApiClient {
   }
 
   /**
-   * Mint a token via `getToken` and redeem it at the DP for the
-   * `intro_dp_session` cookie. Call once before issuing task requests.
+   * 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();
@@ -131,6 +164,24 @@ export class IntrospectionApiClient {
       },
     );
     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. */

package/src/api/http.ts

@@ -4,11 +4,17 @@
  * 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 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.
+ * 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 {
@@ -17,11 +23,22 @@ import {
   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;
@@ -35,6 +52,14 @@ export interface BrowserHttpConfig {
    * `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;
 }
 
 /**
@@ -49,7 +74,12 @@ export class BrowserHttpClient extends BaseHttpClient {
       fetch: resolveBrowserFetch(cfg.fetch),
       additionalHeaders: cfg.additionalHeaders,
       transport: {
-        authHeaders: () => ({}),
+        // 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

@@ -26,7 +26,7 @@
  *   getToken: () => token,
  * });
  *
- * await client.connect(); // -> intro_dp_session cookie
+ * await client.connect(); // -> intro_dp_<environment> session cookie
  * const run = await client.tasks.start({
  *   prompt: "Summarize my latest order",
  *   runtime_id: runtimeId,
@@ -54,7 +54,11 @@ export {
   SharesClient,
   type FileUploadBody,
 } from "@introspection-sdk/http";
-export { BrowserHttpClient, type BrowserHttpConfig } from "./http.js";
+export {
+  BrowserHttpClient,
+  ENVIRONMENT_HEADER,
+  type BrowserHttpConfig,
+} from "./http.js";
 export {
   Paginator,
   cursorPaginate,
@@ -66,6 +70,7 @@ export { EventType } from "@introspection-sdk/types";
 export type {
   AGUIEvent,
   BaseEvent,
+  Environment,
   Interrupt,
   Message,
   ResumeEntry,