@mitralab.io/platform-sdk 1.1.2 → 1.1.3

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to this project are documented in this file.
 
+## 1.1.3
+
+- A chat created through `session({ create: true })` over the `auto` or `websocket` transport is
+  born on the T3 box: the create request carries `runtime: "T3"`. A chat created with
+  `transport: "http"` stays on the runner, and an explicit `runtime` is forwarded as given.
+- The box channel is asked for once. The Copilot now holds the channel request while the box
+  boots, so the 2 s polling on a 202 answer is gone; a 202 from an older Copilot means the chat
+  follows the Copilot socket.
+- Depend on `@mitralab.io/sdk-core@0.2.4`, which carries the `runtime` session option into the
+  create request, exports `AgentTaskRuntime`, and sends a prompt whose task already exists even
+  when the session was closed inside its `taskCreated` handler.
+
+## 1.2.0-beta.1
+
+- Add `signInWithEmail()`: the platform auth page collects the address and the one-time code, and
+  the single-use exchange code it returns is redeemed at IAM's `/auth/magic-link/exchange` for the
+  same app session Google and Microsoft SSO already produce.
+- Add `completeEmailSignInRedirect()`, which finishes both the mobile redirect and the tab opened
+  by the link in the message.
+- Keep the pending email request, the one-time state and the auth page URL and never a token, in
+  `localStorage` for 10 minutes, so the tab opened by the link in the message finishes the flow
+  through the same state check the redirect uses. Writing it is best effort for a popup and
+  required for a redirect.
+- Consume a fragment of the flow's own provider even when it cannot be completed, so a rejected or
+  expired redirect is reported once instead of on every reload. A fragment of another flow stays
+  untouched, and a pending request is still dropped only when it expires.
+- Name the flow in the one-time state (`google.<random>`, `microsoft.<random>`, `email.<random>`),
+  which the auth page echoes verbatim, so every `complete*SignInRedirect()` recognizes its own
+  fragment: a fragment from another method returns `null` untouched, whatever this browser has
+  pending, and an application that offers all three can call all three at startup in any order. A
+  fragment that names this flow without matching its pending request is rejected as forged.
+- Generalize the auth page handshake into `AuthPageFlow`, parameterized by provider, exchange
+  route, and where the pending request lives, instead of a second copy for email.
+- Upgrading mid-flow: a redirect started by an earlier version stored a state without the provider
+  name, so the completion after the upgrade returns `null` and the person signs in again. Nothing
+  is lost beyond that one attempt, and only for redirects in flight during the upgrade.
+- Give each provider its own popup window name.
+- Point the deprecated `signIn` and `signUp` failures at `signInWithEmail()`.
+
 ## 1.1.0-beta.2
 
 `1.1.0-beta.1` was published from `main` before this change landed, so it still depends on Core `0.2.0-beta.0`; use `1.1.0-beta.2`.

package/README.md

@@ -50,7 +50,7 @@ The client derives service endpoints from `apiUrl`: `/iam`, `/data-manager`, `/f
 
 The Platform SDK owns:
 
-- browser Google SSO, logout, and session refresh
+- browser Google and Microsoft SSO, browser email sign-in, logout, and session refresh
 - trusted session adoption for the embedded app preview
 - session persistence in `localStorage`
 - auth-state listeners
@@ -76,7 +76,7 @@ unsubscribe()
 
 Authentication state is stored under `mitra_auth_{appId}`. Before each authenticated native request, the SDK checks a JWT's `exp` claim with a 30-second safety window and refreshes directly through IAM when needed. Opaque tokens, malformed JWTs, and JWTs without a numeric `exp` remain server-authoritative and proceed to the request. A `401` still triggers reactive recovery and at most one retry. If another login or bridged session replaced the token while the request was in flight, the retry uses that current token without refreshing its session. If sign-out cleared the token, the old `401` neither refreshes nor retries.
 
-The generated-application authentication flow is Google SSO. The old native `signIn` and `signUp` names fail locally with `UNSUPPORTED_AUTH_METHOD` because IAM has no email/password endpoints. Deprecated login bindings remain available only through the legacy reexports.
+A generated application signs people in with Google SSO, Microsoft SSO, or email. The old native `signIn` and `signUp` names fail locally with `UNSUPPORTED_AUTH_METHOD` because IAM has no email/password endpoints; `signInWithEmail()` is the email flow that replaced them. Deprecated login bindings remain available only through the legacy reexports.
 
 ### Signing in as a process
 
@@ -158,6 +158,72 @@ const mitra = createClient({
 })
 ```
 
+### Signing in with email
+
+Email sign-in needs neither a password nor an SSO account. The same platform page opens, a popup
+by default, collects the address, sends a six-digit code, and IAM answers with a single-use
+exchange code that the SDK redeems at `/iam/api/v1/auth/magic-link/exchange`. What comes back is
+the app session SSO already returns, persisted and refreshed the same way:
+
+```typescript
+const user = await mitra.auth.signInWithEmail()
+```
+
+Redirect mode navigates the current page instead of opening a popup, and is completed during
+startup like the SSO redirect:
+
+```typescript
+await mitra.auth.signInWithEmail({ mode: "redirect" })
+```
+
+```typescript
+const emailUser = await mitra.auth.completeEmailSignInRedirect()
+```
+
+Call `completeEmailSignInRedirect()` at startup even when sign-in was started as a popup, because
+the message carries a link as well as the code, and that link opens a **new tab**. That tab never
+saw the popup, so the pending request has to outlive the tab that opened it: the one-time state
+and the resolved auth page URL are written to `localStorage` under `mitra_email_redirect_{appId}`
+for 10 minutes, dropped when the flow completes, or discarded as stale the next time a result is read. `sessionStorage`,
+which the SSO redirect uses, is scoped to a single tab and cannot answer for another one. The link still has
+to be opened in the same browser that started the sign-in: another browser or device has no pending request,
+refuses the fragment, and the exchange code was already spent by the page. On another device, use the
+six-digit code in the popup instead.
+
+**No token is written there.** What is persisted is only the record of a request already in
+flight, which is the smallest thing that lets the other tab finish it, and it expires on its own.
+The tab opened by the link comes back with the same one-time state the flow started with, so it
+is completed by exactly the check the redirect uses; a request older than 10 minutes is discarded
+rather than completed. Writing the request is best effort for a popup: without `localStorage` the
+popup still signs in and only the completion from the link is lost, while redirect mode, which has
+nowhere else to keep it, fails at the start.
+
+When the person finishes in the tab the link opened, the `signInWithEmail()` call still waiting in
+the original tab eventually times out. Treat that rejection as a cancelled popup: the session is
+already established wherever the application called `completeEmailSignInRedirect()`.
+
+One fragment belongs to one flow, and an application that offers more than one method can call
+every completion at startup, in any order:
+
+```typescript
+const user =
+  (await mitra.auth.completeEmailSignInRedirect()) ??
+  (await mitra.auth.completeGoogleSignInRedirect()) ??
+  (await mitra.auth.completeMicrosoftSignInRedirect())
+```
+
+A chain like that propagates a rejection: an expired request or a forged fragment on the first
+completion keeps the others from running. Wrap each call in `try`/`catch` when the application
+should still try the remaining methods after one of them refuses a fragment.
+
+The one-time state each flow generates names that flow, as in `google.<random>` or
+`email.<random>`, and the auth page echoes it verbatim, so a completion recognizes its own
+fragment. A fragment from another method returns `null` and leaves the fragment and that other
+flow's pending request untouched, whatever this browser has pending. A fragment that does name
+this flow but does not match its pending request is rejected as forged, and the fragment is
+removed from the URL on the way out, so the rejection is reported once instead of on every
+reload.
+
 ## Entities
 
 ```typescript
@@ -246,7 +312,9 @@ unsubscribe()
 session.close()
 ```
 
-Open an existing task with `session({ taskId })`. The default `auto` transport refreshes before connecting, asks the Copilot where the chat is served, and opens whichever channel it names: the box that runs the agent when one is offered, `/copilot/ws/tasks/{taskId}` otherwise. The choice belongs to the server, never to application configuration, so a Copilot that stops offering the box leaves every application on the Copilot socket without a republish. Opening the box never asks it to replay, whether the conversation is new to the session or is being opened again after an idle close: what an idle conversation missed is history, which the application loads over REST. A box socket that drops in the middle of a turn is redialed by the SDK itself, with a bounded backoff (1, 2, 4, 8 and 16 seconds) and the replay from the last position seen on that socket, so the answer keeps streaming; a position taken on one box is forgotten when the Copilot points the conversation to another box; replayed `textChunk` frames reach the `delta` event like live text. While that happens the session emits `raw` events of type `channelReconnecting` (payload `attempt`, `maxAttempts`, `reason`) and `channelConnected` (payload `attempt`); the session `status` stays `streaming`, because Core has no reconnecting status. The disconnect reaches Core, and with it the `error` event, only when the attempts run out or the Copilot no longer offers the box. A drop with no turn in flight, a channel taken over by another tab (close code 4409), and any close of the Copilot socket the session did not ask for are reported at once, whatever the code, so the next send reopens the channel instead of waiting on a socket that is gone. Recovery through persisted history plus the HTTP/SSE channel is unchanged. Set `transport: "http"` when WebSockets are unavailable. Messages sent during a turn enter a FIFO queue with a maximum of 10 items; the session also exposes edit, remove, clear, approval, cancel, history, close, and typed events.
+A chat created with `create: true` over the `auto` or `websocket` transport is born on the T3 box (`runtime: "T3"` in the create request), so the first open does not wait for the box to adopt it; a chat created with `transport: "http"` stays on the Copilot runner. Pass `runtime: "RUNNER"` or `runtime: "T3"` to decide explicitly.
+
+Open an existing task with `session({ taskId })`. The default `auto` transport refreshes before connecting, asks the Copilot once where the chat is served, and opens whichever channel it names: the box that runs the agent when one is offered, `/copilot/ws/tasks/{taskId}` otherwise. The Copilot holds that request while the box boots and answers only once the box is ready or cannot be had; the SDK does not poll. The choice belongs to the server, never to application configuration, so a Copilot that stops offering the box leaves every application on the Copilot socket without a republish. Opening the box never asks it to replay, whether the conversation is new to the session or is being opened again after an idle close: what an idle conversation missed is history, which the application loads over REST. A box socket that drops in the middle of a turn is redialed by the SDK itself, with a bounded backoff (1, 2, 4, 8 and 16 seconds) and the replay from the last position seen on that socket, so the answer keeps streaming; a position taken on one box is forgotten when the Copilot points the conversation to another box; replayed `textChunk` frames reach the `delta` event like live text. While that happens the session emits `raw` events of type `channelReconnecting` (payload `attempt`, `maxAttempts`, `reason`) and `channelConnected` (payload `attempt`); the session `status` stays `streaming`, because Core has no reconnecting status. The disconnect reaches Core, and with it the `error` event, only when the attempts run out or the Copilot no longer offers the box. A drop with no turn in flight, a channel taken over by another tab (close code 4409), and any close of the Copilot socket the session did not ask for are reported at once, whatever the code, so the next send reopens the channel instead of waiting on a socket that is gone. Recovery through persisted history plus the HTTP/SSE channel is unchanged. Set `transport: "http"` when WebSockets are unavailable. Messages sent during a turn enter a FIFO queue with a maximum of 10 items; the session also exposes edit, remove, clear, approval, cancel, history, close, and typed events.
 
 A prompt sent while the browser says it is offline (`navigator.onLine === false`) does not enter Core at all, because Core opens the channel and reads the turn baseline before the prompt goes out and every one of those requests would fail first: the session keeps the prompt in an outbox, emits a `raw` event of type `inputUnsent` (payload `attempt` 0, `reason`, `waitingForOnline` true) and hands it to Core, in order, when the browser fires `online`; the turn starts then. A prompt whose `POST /inputs` went out but got no response at all is kept the same way: the session sends the same request again when the browser fires `online` or on a bounded backoff (2, 5, 10, 20 and 40 seconds), while the turn stays `streaming`, with `inputUnsent` events (payload `attempt`, `reason`, `waitingForOnline`, `retryInMs` when a timer is armed) and, once it goes through, `inputSent` (payload `attempts`). A response from the server, an error included, is never retried: the prompt fails through the `error` event as before. A session closed with a prompt still waiting emits `error` with code `INPUT_UNSENT` before it goes quiet, and `sendAndWait` rejects. The retry cannot tell a request the server never received from one whose response was lost on the way back, so a prompt may reach the server twice in that case; the Copilot's `/inputs` accepts no client message id yet. The public `agentTasks.sendInput` primitive is not held back: it fails immediately, as it always did.
 

package/dist/index.cjs

@@ -434,16 +434,37 @@ async function resolveApiKeySession(publicClient, appId, apiKey) {
   );
 }
 
-// src/modules/google-auth.ts
+// src/modules/auth-page-flow.ts
 var import_sdk_core2 = require("@mitralab.io/sdk-core");
 var RESULT_TYPE = "mitra-oauth-result";
-var PROVIDER_LABELS = {
-  google: "Google",
-  microsoft: "Microsoft"
+var FIVE_MINUTES_MS = 5 * 60 * 1e3;
+var TEN_MINUTES_MS = 10 * 60 * 1e3;
+var PROVIDERS = {
+  google: {
+    label: "Google",
+    exchangePath: "/api/v1/auth/google",
+    sendsRedirectUri: true,
+    redirectStorage: "sessionStorage",
+    popupTimeoutMs: FIVE_MINUTES_MS
+  },
+  microsoft: {
+    label: "Microsoft",
+    exchangePath: "/api/v1/auth/microsoft",
+    sendsRedirectUri: true,
+    redirectStorage: "sessionStorage",
+    popupTimeoutMs: FIVE_MINUTES_MS
+  },
+  email: {
+    label: "Email",
+    exchangePath: "/api/v1/auth/magic-link/exchange",
+    sendsRedirectUri: false,
+    redirectStorage: "localStorage",
+    pendingRequestTtlMs: TEN_MINUTES_MS,
+    popupTimeoutMs: TEN_MINUTES_MS
+  }
 };
 var POPUP_WIDTH = 480;
 var POPUP_HEIGHT = 600;
-var POPUP_TIMEOUT_MS = 5 * 60 * 1e3;
 var POPUP_CLOSED_POLL_MS = 500;
 function expectAuthTokenResponse(value) {
   const response = (0, import_sdk_core2.expectObject)(
@@ -464,12 +485,13 @@ function expectAuthTokenResponse(value) {
     tokenType: response.tokenType
   };
 }
-var GoogleAuthFlow = class {
+var AuthPageFlow = class {
   appId;
   apiUrl;
   configuredAuthPageUrl;
   client;
   provider;
+  profile;
   providerLabel;
   redirectStorageKey;
   popupPromise = null;
@@ -479,7 +501,8 @@ var GoogleAuthFlow = class {
     this.configuredAuthPageUrl = config.authPageUrl;
     this.client = config.client;
     this.provider = config.provider ?? "google";
-    this.providerLabel = PROVIDER_LABELS[this.provider];
+    this.profile = PROVIDERS[this.provider];
+    this.providerLabel = this.profile.label;
     this.redirectStorageKey = `mitra_${this.provider}_redirect_${config.appId}`;
   }
   signIn(options = {}) {
@@ -496,6 +519,19 @@ var GoogleAuthFlow = class {
     });
     return this.popupPromise;
   }
+  /**
+   * Finishes a redirect this provider started, or returns `null` when the URL
+   * carries no result or carries one that belongs to another provider's flow.
+   *
+   * The state generated at the start of every flow is prefixed with the provider
+   * name, and the auth page echoes it verbatim, so a fragment identifies its own
+   * flow. An application that offers several methods can call every completion
+   * at startup, in any order, even while other methods have requests pending.
+   *
+   * A fragment of this flow is always consumed, including when it cannot be
+   * completed, so a failure is reported once instead of on every reload. A
+   * fragment of another flow is left exactly as it was found.
+   */
   async completeRedirect() {
     const browserWindow = this.requireBrowser();
     const params = new URLSearchParams(browserWindow.location.hash.replace(/^#/, ""));
@@ -504,17 +540,36 @@ var GoogleAuthFlow = class {
     const error = params.get("errorMitra");
     if (code === null && state === null && error === null) return null;
     const context = this.readRedirectContext(browserWindow);
-    if (!state?.trim()) {
-      throw new Error(`${this.providerLabel} sign-in redirect is missing state.`);
+    const hasState = state !== null && state.trim() !== "";
+    if (hasState && !this.ownsState(state)) return null;
+    if (!hasState && !context) return null;
+    if (!hasState) {
+      throw this.discardOwnRedirect(
+        browserWindow,
+        `${this.providerLabel} sign-in redirect is missing state.`
+      );
+    }
+    if (context && this.hasExpired(context)) {
+      this.clearRedirectContext(browserWindow);
+      throw this.discardOwnRedirect(
+        browserWindow,
+        `${this.providerLabel} sign-in request expired before it was completed.`
+      );
     }
     if (context?.state !== state) {
-      throw new Error(`Invalid ${this.providerLabel} sign-in state (possible CSRF).`);
+      throw this.discardOwnRedirect(
+        browserWindow,
+        `Invalid ${this.providerLabel} sign-in state (possible CSRF).`
+      );
     }
     const expectedRedirectUri = this.getRedirectUri(
       resolveAuthPageUrl(this.apiUrl, this.configuredAuthPageUrl, browserWindow)
     );
     if (context.redirectUri !== expectedRedirectUri) {
-      throw new Error(`${this.providerLabel} sign-in redirect context is invalid.`);
+      throw this.discardOwnRedirect(
+        browserWindow,
+        `${this.providerLabel} sign-in redirect context is invalid.`
+      );
     }
     this.cleanRedirectFragment(browserWindow);
     this.clearRedirectContext(browserWindow);
@@ -533,8 +588,13 @@ var GoogleAuthFlow = class {
       this.configuredAuthPageUrl,
       browserWindow
     );
+    const completedInAnotherTab = this.profile.pendingRequestTtlMs !== void 0;
+    if (completedInAnotherTab) {
+      this.writeRedirectContext(browserWindow, this.newRedirectContext(state, authPageUrl));
+    }
     const popup = this.openPopup(browserWindow, this.buildStartUrl(browserWindow, authPageUrl, state));
     const result = await this.waitForPopupResult(browserWindow, popup, authPageUrl.origin, state);
+    if (completedInAnotherTab) this.clearRedirectContext(browserWindow);
     if (result.code) return this.exchangeCode(result.code, this.getRedirectUri(authPageUrl));
     return expectAuthTokenResponse(result.token);
   }
@@ -545,20 +605,20 @@ var GoogleAuthFlow = class {
       this.configuredAuthPageUrl,
       browserWindow
     );
-    const context = {
-      state,
-      redirectUri: this.getRedirectUri(authPageUrl)
-    };
-    this.persistRedirectContext(browserWindow, context);
+    if (!this.writeRedirectContext(browserWindow, this.newRedirectContext(state, authPageUrl))) {
+      throw new Error(
+        `${this.providerLabel} sign-in redirect requires ${this.profile.redirectStorage}.`
+      );
+    }
     const startUrl = this.buildStartUrl(browserWindow, authPageUrl, state);
     browserWindow.location.assign(startUrl.toString());
     return new Promise(() => void 0);
   }
   async exchangeCode(code, redirectUri) {
-    const response = await this.client.post(`/api/v1/auth/${this.provider}`, {
+    const response = await this.client.post(this.profile.exchangePath, {
       appId: this.appId,
       code,
-      redirectUri
+      ...this.profile.sendsRedirectUri ? { redirectUri } : {}
     });
     return expectAuthTokenResponse(response);
   }
@@ -575,13 +635,41 @@ var GoogleAuthFlow = class {
   getRedirectUri(authPageUrl) {
     return `${authPageUrl.origin}${authPageUrl.pathname}`;
   }
+  newRedirectContext(state, authPageUrl) {
+    return {
+      state,
+      redirectUri: this.getRedirectUri(authPageUrl),
+      createdAt: Date.now()
+    };
+  }
+  /**
+   * Reports a fragment of this flow that cannot be completed, dropping it from the
+   * URL first. Nobody else claims a fragment that names this flow, so leaving it
+   * there would make the application fail again on every reload.
+   */
+  discardOwnRedirect(browserWindow, message) {
+    this.cleanRedirectFragment(browserWindow);
+    return new Error(message);
+  }
+  /** Whether a state echoed by the auth page was generated by this provider's flow. */
+  ownsState(state) {
+    return state.startsWith(`${this.provider}.`);
+  }
+  hasExpired(context) {
+    const ttlMs = this.profile.pendingRequestTtlMs;
+    if (ttlMs === void 0) return false;
+    if (!Number.isFinite(context.createdAt)) return true;
+    return Date.now() - context.createdAt > ttlMs;
+  }
+  /** A one-time state that names the flow that created it, so its fragment is recognizable. */
   generateState() {
     if (!globalThis.crypto?.getRandomValues) {
       throw new Error(`${this.providerLabel} sign-in requires crypto.getRandomValues.`);
     }
     const bytes = new Uint8Array(16);
     globalThis.crypto.getRandomValues(bytes);
-    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    const random = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${this.provider}.${random}`;
   }
   openPopup(browserWindow, url) {
     const outerWidth = browserWindow.outerWidth || browserWindow.screen.width;
@@ -590,7 +678,7 @@ var GoogleAuthFlow = class {
     const top = Math.max(0, (browserWindow.screenY || 0) + (outerHeight - POPUP_HEIGHT) / 2);
     const popup = browserWindow.open(
       url.toString(),
-      "mitra-google-oauth",
+      `mitra-${this.provider}-auth`,
       `width=${POPUP_WIDTH},height=${POPUP_HEIGHT},left=${left},top=${top},menubar=no,toolbar=no,status=no`
     );
     if (!popup) {
@@ -603,7 +691,7 @@ var GoogleAuthFlow = class {
       const timeout = globalThis.setTimeout(() => {
         cleanup();
         reject(new Error(`${this.providerLabel} sign-in timed out.`));
-      }, POPUP_TIMEOUT_MS);
+      }, this.profile.popupTimeoutMs);
       const closedPoll = globalThis.setInterval(() => {
         if (popup.closed) {
           cleanup();
@@ -628,7 +716,7 @@ var GoogleAuthFlow = class {
         const code = typeof data.code === "string" && data.code.trim() ? data.code : void 0;
         if (!code && data.token === void 0) {
           cleanup();
-          reject(new Error("Google auth page returned neither code nor token."));
+          reject(new Error(`${this.providerLabel} auth page returned neither code nor token.`));
           return;
         }
         cleanup();
@@ -643,22 +731,28 @@ var GoogleAuthFlow = class {
       browserWindow.addEventListener("message", onMessage);
     });
   }
-  persistRedirectContext(browserWindow, context) {
+  /** Writes the pending request, reporting whether storage accepted it. */
+  writeRedirectContext(browserWindow, context) {
     try {
-      browserWindow.sessionStorage.setItem(this.redirectStorageKey, JSON.stringify(context));
+      browserWindow[this.profile.redirectStorage].setItem(
+        this.redirectStorageKey,
+        JSON.stringify(context)
+      );
+      return true;
     } catch {
-      throw new Error(`${this.providerLabel} sign-in redirect requires sessionStorage.`);
+      return false;
     }
   }
   readRedirectContext(browserWindow) {
     try {
-      const raw = browserWindow.sessionStorage.getItem(this.redirectStorageKey);
+      const raw = browserWindow[this.profile.redirectStorage].getItem(this.redirectStorageKey);
       if (!raw) return null;
       const value = JSON.parse(raw);
       if (typeof value.state !== "string" || typeof value.redirectUri !== "string") return null;
       return {
         state: value.state,
-        redirectUri: value.redirectUri
+        redirectUri: value.redirectUri,
+        createdAt: typeof value.createdAt === "number" ? value.createdAt : Number.NaN
       };
     } catch {
       return null;
@@ -666,7 +760,7 @@ var GoogleAuthFlow = class {
   }
   clearRedirectContext(browserWindow) {
     try {
-      browserWindow.sessionStorage.removeItem(this.redirectStorageKey);
+      browserWindow[this.profile.redirectStorage].removeItem(this.redirectStorageKey);
     } catch {
     }
   }
@@ -736,6 +830,7 @@ var AuthModule = class {
   currentUserApi;
   googleAuth;
   microsoftAuth;
+  emailAuth;
   constructor(appId, iamBaseUrl, options = {}) {
     this.appId = appId;
     const trimmedIamBaseUrl = stripTrailingSlashes(iamBaseUrl);
@@ -752,19 +847,26 @@ var AuthModule = class {
       onUnauthorized: (requestToken) => this.handleUnauthorized(requestToken)
     });
     this.currentUserApi = (0, import_sdk_core3.createAuthModule)(this.authedClient, coreErrors);
-    this.googleAuth = new GoogleAuthFlow({
+    this.googleAuth = new AuthPageFlow({
       appId,
       apiUrl,
       authPageUrl: options.authPageUrl,
       client: this.publicClient
     });
-    this.microsoftAuth = new GoogleAuthFlow({
+    this.microsoftAuth = new AuthPageFlow({
       appId,
       apiUrl,
       authPageUrl: options.authPageUrl,
       client: this.publicClient,
       provider: "microsoft"
     });
+    this.emailAuth = new AuthPageFlow({
+      appId,
+      apiUrl,
+      authPageUrl: options.authPageUrl,
+      client: this.publicClient,
+      provider: "email"
+    });
     this.loadFromStorage();
     const readAccessToken = () => this.#accessToken;
     sessionPorts.set(this, {
@@ -790,10 +892,10 @@ var AuthModule = class {
   get isAuthenticated() {
     return this._currentUser !== null && this.#accessToken !== null;
   }
-  /** @deprecated Email/password authentication is not implemented by IAM. Use Google or Microsoft SSO. */
+  /** @deprecated Email/password authentication is not implemented by IAM. Use signInWithEmail() or SSO. */
   async signIn(_credentials) {
     throw new MitraApiError(
-      "Email/password authentication is not available. Use signInWithGoogle() or signInWithMicrosoft().",
+      "Email/password authentication is not available. Use signInWithEmail(), signInWithGoogle() or signInWithMicrosoft().",
       0,
       "UNSUPPORTED_AUTH_METHOD"
     );
@@ -879,8 +981,10 @@ var AuthModule = class {
    *
    * The method consumes and clears the fragment and stored CSRF context, sends
    * the single-use code directly to IAM, persists both tokens, calls `auth.me()`,
-   * and notifies auth-state listeners. It returns `null` when the current URL is
-   * not a Google SSO redirect. Redirect errors must carry the same `stateMitra`
+   * and notifies auth-state listeners. It returns `null` when the current URL
+   * carries no redirect result, and also when it carries one this flow never
+   * started, so an application that offers several methods can call every
+   * completion at startup. Redirect errors must carry the same `stateMitra`
    * stored at the start of the flow before their message is exposed or consumed.
    *
    * @returns The authenticated user, or `null` when no redirect result is present.
@@ -916,10 +1020,54 @@ var AuthModule = class {
     const tokenResponse = await this.microsoftAuth.completeRedirect();
     return tokenResponse ? this.establishSession(tokenResponse) : null;
   }
-  /** @deprecated Email/password registration is not implemented by IAM. Use Google or Microsoft SSO. */
+  /**
+   * Signs in with a one-time code sent by email: the same auth-page handshake as
+   * SSO, where the platform page collects the address and the code, and IAM
+   * hands back a single-use exchange code redeemed at `/auth/magic-link/exchange`.
+   * Popup by default; redirect mode navigates away.
+   *
+   * The message also carries a link. Because that link opens a new tab, the
+   * pending request is kept in `localStorage` for 10 minutes - the one-time state
+   * and the auth page URL, never a token - so
+   * {@link completeEmailSignInRedirect} can finish the flow in that tab.
+   *
+   * @param options - Popup or redirect mode.
+   * @returns The authenticated and hydrated user in popup mode.
+   * @throws {MitraApiError} When IAM rejects the exchange code.
+   * @throws {Error} When the browser blocks or cancels the popup, the flow times
+   * out, or the response fails origin, source, state, or shape validation. A
+   * person who finishes through the link instead of the popup leaves this call
+   * to time out, which the application should treat as a cancelled popup.
+   *
+   * @example
+   * ```typescript
+   * const user = await mitra.auth.signInWithEmail();
+   * ```
+   */
+  async signInWithEmail(options = {}) {
+    return this.establishSession(await this.emailAuth.signIn(options));
+  }
+  /**
+   * Completes an email sign-in from `#codeMitra` and `#stateMitra`, during
+   * application startup like {@link completeGoogleSignInRedirect}.
+   *
+   * It covers both ways the flow comes back, and they are the same check: a
+   * redirect in the tab that started it, and the tab the link in the message
+   * opened. Both carry the one-time state this SDK generated, which the second
+   * tab matches against the pending request kept in `localStorage`. A request
+   * older than 10 minutes is discarded instead of completed.
+   *
+   * @returns The authenticated user, or `null` when the URL carries no result or
+   * carries one that belongs to another sign-in method's flow.
+   */
+  async completeEmailSignInRedirect() {
+    const tokenResponse = await this.emailAuth.completeRedirect();
+    return tokenResponse ? this.establishSession(tokenResponse) : null;
+  }
+  /** @deprecated Email/password registration is not implemented by IAM. Use signInWithEmail() or SSO. */
   async signUp(_data) {
     throw new MitraApiError(
-      "Email/password registration is not available. Use signInWithGoogle() or signInWithMicrosoft().",
+      "Email/password registration is not available. Use signInWithEmail(), signInWithGoogle() or signInWithMicrosoft().",
       0,
       "UNSUPPORTED_AUTH_METHOD"
     );
@@ -1660,8 +1808,6 @@ function holdSendsWhileOffline(session, outbox) {
 
 // src/modules/agent-session.ts
 var CONNECT_TIMEOUT_MS = 15e3;
-var CHANNEL_BOOT_TIMEOUT_MS = 9e4;
-var CHANNEL_BOOT_RETRY_MS = 2e3;
 var SILENCE_TIMEOUT_MS = 6e4;
 var RECONNECT_DELAYS_MS = [1e3, 2e3, 4e3, 8e3, 16e3];
 var SUPERSEDED_CLOSE_CODE = 4409;
@@ -1827,28 +1973,28 @@ var BrowserAgentTaskEventSource = class {
   requestDirectChannel(taskId, token, signal) {
     return this.askDirectChannel(taskId, token, signal).catch(() => null);
   }
-  /** Like `requestDirectChannel`, but a request the network lost is thrown, not a refusal. */
+  /**
+   * Like `requestDirectChannel`, but a request the network lost is thrown, not a refusal.
+   *
+   * One request. The copilot holds it while the box boots and answers 200 with the channel, or
+   * an error status once the box cannot be had. A 202 comes only from a copilot older than that
+   * contract, which used to mean "still booting, ask again": there is no channel to open, and
+   * the conversation follows the copilot socket. Polling here again would put the wait back on
+   * the client that the server now owns.
+   */
   async askDirectChannel(taskId, token, signal) {
+    if (signal?.aborted) return null;
     const url = `${this.apiUrl}/copilot/api/v1/tasks/${encodeURIComponent(taskId)}/channel`;
-    const deadline = Date.now() + CHANNEL_BOOT_TIMEOUT_MS;
-    for (; ; ) {
-      if (signal?.aborted) return null;
-      const response = await globalThis.fetch(url, {
-        method: "POST",
-        headers: { Authorization: `Bearer ${stripBearer2(token)}` },
-        ...signal ? { signal } : {}
-      });
-      if (response.status === 202) {
-        if (Date.now() >= deadline) return null;
-        await sleep(CHANNEL_BOOT_RETRY_MS, signal);
-        continue;
-      }
-      if (!response.ok) return null;
-      try {
-        return toDirectChannel(await response.json(), this.apiUrl);
-      } catch {
-        return null;
-      }
+    const response = await globalThis.fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${stripBearer2(token)}` },
+      ...signal ? { signal } : {}
+    });
+    if (response.status === 202 || !response.ok) return null;
+    try {
+      return toDirectChannel(await response.json(), this.apiUrl);
+    } catch {
+      return null;
     }
   }
   async openWebSocket(taskId, observer, signal) {
@@ -2136,6 +2282,10 @@ var BrowserAgentTaskEventSource = class {
 };
 
 // src/modules/agent-tasks.ts
+function bornOnBox(options) {
+  if (!("create" in options) || options.runtime || options.transport === "http") return options;
+  return { ...options, runtime: "T3" };
+}
 function createBrowserAgentTasksModule(httpClient, auth, apiUrl) {
   const tasks = (0, import_sdk_core8.createAgentTasksModule)(httpClient, coreErrors);
   const source = new BrowserAgentTaskEventSource(auth, apiUrl);
@@ -2165,7 +2315,7 @@ function createBrowserAgentTasksModule(httpClient, auth, apiUrl) {
     eventSource
   });
   return (0, import_sdk_core8.withAgentTaskSessions)(tasks, {
-    session: (options) => holdSendsWhileOffline(manager.session(options), outbox)
+    session: (options) => holdSendsWhileOffline(manager.session(bornOnBox(options)), outbox)
   });
 }