@stigmer/react 3.1.16 → 3.2.0

package/src/channel/providerPresentation.ts

@@ -0,0 +1,154 @@
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { AgentChannelInstallState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/status_pb";
+import type { ChannelProviderId } from "./providers.js";
+
+/**
+ * Per-provider copy for the channel management surfaces.
+ *
+ * Split from {@link ChannelProviderDescriptor} deliberately: the registry
+ * carries a provider's *identity* (id, label, icon, install style) —
+ * stable facts every surface needs — while this module carries the
+ * *prose* the channels panel renders per provider. Keeping prose out of
+ * the descriptor keeps the registry declaration-shaped, and keeping it
+ * here keeps `AgentChannelsPanel` free of provider `if` branches.
+ */
+export interface ChannelProviderPresentation {
+  readonly id: ChannelProviderId;
+  /**
+   * One-line install facts under the channel name (the card's second
+   * line): where the channel is installed, since when, or why it isn't
+   * serving yet.
+   */
+  readonly describeChannel: (channel: AgentChannel) => string;
+  /**
+   * The card's serving-app line: which provider app serves the channel
+   * and how members reach the agent through it. `servingAppName` is the
+   * resolved ChannelApp name, or `null` for the platform app (Slack
+   * only — WhatsApp is BYO-only and always has one).
+   */
+  readonly servingLine: (servingAppName: string | null) => string;
+  /** Body copy of the disconnect confirmation prompt. */
+  readonly disconnectDescription: (channelName: string) => string;
+}
+
+const slackPresentation: ChannelProviderPresentation = {
+  id: "slack",
+  describeChannel: (channel) => {
+    const slack =
+      channel.status?.providerStatus?.case === "slack"
+        ? channel.status.providerStatus.value
+        : null;
+    const installedAt = slack?.installedAt
+      ? timestampDate(slack.installedAt)
+      : null;
+    switch (installStateOf(channel)) {
+      case AgentChannelInstallState.installed:
+        return [
+          slack?.teamName ? `Workspace: ${slack.teamName}` : "Workspace connected",
+          installedAt ? `since ${formatDate(installedAt)}` : null,
+        ]
+          .filter(Boolean)
+          .join(" \u00b7 ");
+      case AgentChannelInstallState.revoked:
+        return slack?.teamName
+          ? `The Slack app was removed from ${slack.teamName} — reconnect to resume.`
+          : "The Slack app was removed from the workspace — reconnect to resume.";
+      default:
+        return "The Slack install hasn't been completed yet.";
+    }
+  },
+  servingLine: (servingAppName) =>
+    servingAppName
+      ? `Serving app: ${servingAppName} (your app) — members @mention ${servingAppName}`
+      : "Serving app: Stigmer — members @mention Stigmer",
+  disconnectDescription: (channelName) =>
+    `"${channelName}" stops serving immediately and its stored Slack ` +
+    "install (including credentials) is removed. Members of the " +
+    "workspace can no longer reach the agent. To pause without " +
+    "disconnecting, turn the channel off instead.",
+};
+
+const whatsappPresentation: ChannelProviderPresentation = {
+  id: "whatsapp",
+  describeChannel: (channel) => {
+    const whatsapp =
+      channel.status?.providerStatus?.case === "whatsapp"
+        ? channel.status.providerStatus.value
+        : null;
+    const installedAt = whatsapp?.installedAt
+      ? timestampDate(whatsapp.installedAt)
+      : null;
+    switch (installStateOf(channel)) {
+      case AgentChannelInstallState.installed: {
+        const number =
+          whatsapp?.displayPhoneNumber || whatsapp?.phoneNumberId || null;
+        return [
+          number ? `Number: ${number}` : "Number connected",
+          whatsapp?.verifiedName ? `(${whatsapp.verifiedName})` : null,
+          installedAt ? `since ${formatDate(installedAt)}` : null,
+        ]
+          .filter(Boolean)
+          .join(" \u00b7 ");
+      }
+      // Meta emits no revocation events (DD-010), so WhatsApp channels
+      // never transition to revoked today — handled anyway so a future
+      // server that learns to observe revocation degrades sensibly.
+      case AgentChannelInstallState.revoked:
+        return "The WhatsApp connection was revoked — reconnect to resume.";
+      default:
+        return "The WhatsApp connection hasn't been completed yet.";
+    }
+  },
+  servingLine: (servingAppName) =>
+    servingAppName
+      ? `Serving app: ${servingAppName} (your Meta app) — people message the connected number`
+      : "Serving app: your Meta app — people message the connected number",
+  disconnectDescription: (channelName) =>
+    // No "(including credentials)" arm: WhatsApp credentials live on the
+    // shared ChannelApp (DD-WA-3) and outlive any one channel.
+    `"${channelName}" stops serving immediately and its WhatsApp ` +
+    "number binding is removed. People can no longer reach the agent " +
+    "on that number. To pause without disconnecting, turn the channel " +
+    "off instead.",
+};
+
+const PRESENTATIONS: readonly ChannelProviderPresentation[] = [
+  slackPresentation,
+  whatsappPresentation,
+];
+
+/**
+ * Fallback presentation for provider cases this UI doesn't know yet (a
+ * newer server) — the first registered provider, mirroring the panel's
+ * icon fallback to `CHANNEL_PROVIDERS[0]` so an unknown provider renders
+ * consistently rather than half-known.
+ */
+export const DEFAULT_CHANNEL_PRESENTATION: ChannelProviderPresentation =
+  slackPresentation;
+
+/**
+ * Resolve a provider's presentation from a `provider_config` oneof case
+ * name. Returns `null` for unknown cases — callers fall back the same
+ * way they do for {@link channelProviderOf}.
+ */
+export function channelPresentationOf(
+  providerCase: string | undefined,
+): ChannelProviderPresentation | null {
+  return PRESENTATIONS.find((p) => p.id === providerCase) ?? null;
+}
+
+function installStateOf(channel: AgentChannel): AgentChannelInstallState {
+  return (
+    channel.status?.installState ??
+    AgentChannelInstallState.agent_channel_install_state_unspecified
+  );
+}
+
+function formatDate(date: Date): string {
+  return date.toLocaleDateString(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}

package/src/channel/providers.ts

@@ -0,0 +1,73 @@
+import type { ComponentType } from "react";
+import { SlackMarkIcon } from "./SlackMarkIcon.js";
+import { WhatsAppMarkIcon } from "./WhatsAppMarkIcon.js";
+
+/**
+ * Identifier of a channel provider — matches the `provider_config` oneof
+ * case name on `AgentChannelSpec` / `ChannelAppSpec`, which is the wire
+ * discriminator every channel surface already switches on.
+ */
+export type ChannelProviderId = "slack" | "whatsapp";
+
+/**
+ * How a provider's install flow runs — the client-side hint for whether
+ * connecting needs a browser popup.
+ *
+ * - `redirect`: an OAuth consent redirect (Slack). The client opens a
+ *   popup synchronously inside the user gesture — before `initiateInstall`
+ *   answers — because browsers only allow `window.open` from a gesture
+ *   call stack.
+ * - `direct`: `initiateInstall` runs the whole install server-side and
+ *   answers `completed=true` (WhatsApp, DD-WA-1). No popup, no callback
+ *   route; the client refetches the channel.
+ *
+ * The server's `InitiateChannelInstallOutput.completed` field stays the
+ * authoritative outcome (DD-WA-1b) — this hint only decides whether to
+ * pre-open a popup at all.
+ */
+export type ChannelInstallStyle = "redirect" | "direct";
+
+/**
+ * Display descriptor for a channel provider.
+ *
+ * The single place a provider's UI identity lives. Adding a provider
+ * means adding a registry entry here (plus its presentation copy in
+ * providerPresentation.tsx); consumers derive labels, icons, and connect
+ * affordances from the registry instead of hardcoding a provider.
+ */
+export interface ChannelProviderDescriptor {
+  readonly id: ChannelProviderId;
+  /** Human-readable provider name ("Slack"). */
+  readonly label: string;
+  /** Brand mark; consumers size it via className. */
+  readonly Icon: ComponentType<{ readonly className?: string }>;
+  /** How this provider's install flow runs. */
+  readonly installStyle: ChannelInstallStyle;
+}
+
+/**
+ * All channel providers this UI can render, in display order.
+ *
+ * With two providers the connect affordance renders as one visible
+ * "Connect to {label}" button per provider — deliberately NOT a dropdown
+ * menu: two options are clearer side by side (visibility over a hidden
+ * menu), and each button keeps its own stable cursor target for the docs
+ * demos. A third entry is the signal to fold these into a provider menu.
+ */
+export const CHANNEL_PROVIDERS: readonly ChannelProviderDescriptor[] = [
+  { id: "slack", label: "Slack", Icon: SlackMarkIcon, installStyle: "redirect" },
+  { id: "whatsapp", label: "WhatsApp", Icon: WhatsAppMarkIcon, installStyle: "direct" },
+];
+
+/**
+ * Resolve a provider descriptor from a `provider_config` oneof case name.
+ *
+ * Returns `null` for unknown cases (e.g. a newer server returning a
+ * provider this UI doesn't know yet) — callers hide or fall back rather
+ * than render a half-known provider.
+ */
+export function channelProviderOf(
+  providerCase: string | undefined,
+): ChannelProviderDescriptor | null {
+  return CHANNEL_PROVIDERS.find((p) => p.id === providerCase) ?? null;
+}

package/src/channel/useAgentChannel.ts

@@ -0,0 +1,58 @@
+"use client";
+
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { isNotFound } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Return value of {@link useAgentChannel}. */
+export interface UseAgentChannelReturn {
+  /**
+   * The channel, or `null` while loading, on error, or when no channel
+   * with that ID exists (not-found is data, not an error).
+   */
+  readonly channel: AgentChannel | null;
+  /** `true` while the initial fetch is in flight and no data is shown. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Re-fetch the channel from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that loads a single {@link AgentChannel} by ID.
+ *
+ * Not-found maps to `channel === null` rather than an error, so callers
+ * can render an absent channel (e.g. deleted in another tab) without
+ * error styling. Pass an empty `id` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { channel, isLoading, refetch } = useAgentChannel(channelId);
+ * ```
+ */
+export function useAgentChannel(id: string): UseAgentChannelReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn = id
+    ? async () => {
+        try {
+          return await stigmer.agentChannel.get(id);
+        } catch (err) {
+          if (isNotFound(err)) return null;
+          throw err;
+        }
+      }
+    : null;
+
+  const { data: channel, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [id, stigmer],
+    null as AgentChannel | null,
+  );
+
+  return { channel, isLoading, isRefetching, error, refetch };
+}

package/src/channel/useAgentChannelList.ts

@@ -0,0 +1,69 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { GetAgentChannelsByAgentRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Return value of {@link useAgentChannelList}. */
+export interface UseAgentChannelListReturn {
+  /**
+   * Every channel of the agent visible to the caller, in server order.
+   * Empty while loading, on error, or when the agent has no channels —
+   * `channels.length === 0 && !isLoading && !error` means "no channels
+   * exist yet".
+   */
+  readonly channels: readonly AgentChannel[];
+  /** `true` while the initial fetch is in flight and no data is shown. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Re-fetch the channels from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that loads an agent's {@link AgentChannel} resources — the
+ * connections that expose the agent on external messaging platforms
+ * (Slack in v1, more providers later).
+ *
+ * A channel serves traffic only when its provider install completed
+ * (`status.installState === installed`) AND the owner's serving switch is
+ * on (`spec.enabled`) — the two axes the Channels tab renders.
+ *
+ * Pass `org` to scope the list to one organization's channels; the server
+ * only ever narrows the permission-bounded view. Pass an empty `agentId`
+ * to skip fetching (stable no-op) — useful while the agent is still
+ * loading.
+ *
+ * @example
+ * ```tsx
+ * const { channels, isLoading, refetch } = useAgentChannelList(
+ *   agent?.metadata?.id ?? "",
+ *   viewerOrg,
+ * );
+ * ```
+ */
+export function useAgentChannelList(agentId: string, org?: string): UseAgentChannelListReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn = agentId
+    ? async () => {
+        const result = await stigmer.agentChannel.getByAgent(
+          create(GetAgentChannelsByAgentRequestSchema, { agentId, org: org ?? "" }),
+        );
+        return result.items;
+      }
+    : null;
+
+  const { data: channels, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [agentId, org, stigmer],
+    [] as AgentChannel[],
+  );
+
+  return { channels, isLoading, isRefetching, error, refetch };
+}

package/src/channel/useChannelSessions.ts

@@ -0,0 +1,73 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { ListSessionsByChannelRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Return value of {@link useChannelSessions}. */
+export interface UseChannelSessionsReturn {
+  /**
+   * The channel's conversations (one session per external conversation),
+   * newest activity first. Empty while loading, on error, or when nobody
+   * has messaged the channel yet — `sessions.length === 0 && !isLoading
+   * && !error` means "no conversations yet".
+   */
+  readonly sessions: readonly Session[];
+  /** `true` while the initial fetch is in flight and no data is shown. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /**
+   * Error from the last failed request, or `null` when healthy. A
+   * PERMISSION_DENIED here means the caller cannot view the channel —
+   * conversations are visible to exactly the channel's viewers (the
+   * connector and org admins).
+   */
+  readonly error: Error | null;
+  /** Re-fetch the conversations from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that loads the conversations an {@link AgentChannel} created —
+ * the Slack/WhatsApp sessions the channel runtime owns (design decision
+ * 012: channel-session read-only observability).
+ *
+ * The server enforces the visibility boundary twice: the caller must hold
+ * `can_view` on the channel, and results are filtered to sessions the
+ * caller can individually view. Open a returned session with
+ * `SessionViewer` — it self-selects the read-only `"observer"` audience
+ * for channel-originated sessions.
+ *
+ * Pass an empty `channelId` to skip fetching (stable no-op) — useful
+ * while the channel list is still loading.
+ *
+ * @example
+ * ```tsx
+ * const { sessions, isLoading, error } = useChannelSessions(
+ *   channel.metadata?.id ?? "",
+ * );
+ * ```
+ */
+export function useChannelSessions(channelId: string): UseChannelSessionsReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn = channelId
+    ? async () => {
+        const result = await stigmer.session.listByChannel(
+          create(ListSessionsByChannelRequestSchema, { channelId }),
+        );
+        return result.entries;
+      }
+    : null;
+
+  const { data: sessions, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [channelId, stigmer],
+    [] as Session[],
+  );
+
+  return { sessions, isLoading, isRefetching, error, refetch };
+}

package/src/channel/useChannelToolReadiness.ts

@@ -0,0 +1,39 @@
+"use client";
+
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { ResourceRef } from "@stigmer/sdk";
+import { useDeploymentMode } from "../deployment-mode.js";
+import {
+  useToolCredentialsReadiness,
+  type ToolCredentialsReadiness,
+} from "../environment/useToolCredentialsReadiness.js";
+
+/**
+ * Channel-scoped wrapper over {@link useToolCredentialsReadiness}:
+ * checks whether a tool-using agent's credentials will work over a
+ * channel — i.e. whether the channel binds environments
+ * (`AgentChannelSpec.environment_refs`) and each one is shared with the
+ * organization.
+ *
+ * Channel executions receive credentials exclusively from the
+ * channel's own bindings, resolved through the org-shared environment
+ * seam — exactly the share contract, without the audience arm (channels
+ * have no audience concept). So a tool-using agent on a channel with no
+ * bindings is guaranteed to refuse every workspace message that needs a
+ * tool.
+ *
+ * The check runs only when serving is enabled (a paused channel serves
+ * no traffic), the deployment is cloud (the channel runtime is
+ * cloud-only), and the agent declares MCP server usages.
+ */
+export function useChannelToolReadiness(
+  agent: Agent,
+  enabled: boolean,
+  environmentRefs: readonly ResourceRef[],
+): ToolCredentialsReadiness {
+  const deploymentMode = useDeploymentMode();
+  const hasMcpTools = (agent.spec?.mcpServerUsages?.length ?? 0) > 0;
+  const applicable = enabled && deploymentMode === "cloud" && hasMcpTools;
+
+  return useToolCredentialsReadiness(applicable, environmentRefs);
+}

package/src/channel/useConnectSlackChannel.ts

@@ -0,0 +1,195 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import {
+  InitiateChannelInstallInputSchema,
+  CompleteChannelInstallInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import {
+  openOAuthPopup,
+  popupBlockedError,
+  waitForOAuthCallback,
+  closeOAuthPopup,
+} from "../internal/oauthPopup.js";
+
+/**
+ * Progress phases of the Slack channel install flow.
+ *
+ * Mirrors the MCP OAuth phases minus `connecting` — a channel install has
+ * no tool-discovery step; `completeInstall` returns the installed channel
+ * directly.
+ */
+export type SlackConnectPhase =
+  | "idle"
+  | "initiating"
+  | "awaiting-callback"
+  | "completing"
+  | "done";
+
+/** Return value of {@link useConnectSlackChannel}. */
+export interface UseConnectSlackChannelReturn {
+  /**
+   * Run the Slack install flow for a channel.
+   *
+   * Opens a popup for Slack's "Add to Slack" consent screen, waits for
+   * the OAuth callback, then exchanges the authorization code via
+   * `completeInstall`. Works for first installs and re-installs after
+   * revocation alike (the server transitions `revoked → installed`).
+   *
+   * **Must be called from a synchronous user-gesture handler** (e.g. an
+   * `onClick` callback) so the browser allows the popup. The popup is
+   * opened synchronously before any async work to avoid popup blockers.
+   *
+   * Failure modes surface as `error` with server-authored copy:
+   * a deployment without Slack app credentials or an OSS backend refuses
+   * at `initiating` (FAILED_PRECONDITION); duplicate-workspace and
+   * Enterprise Grid installs refuse at `completing`.
+   *
+   * @param channelId - System-generated ID (metadata.id) of the channel.
+   * @returns The installed AgentChannel (status carries the Slack facts).
+   */
+  readonly connect: (channelId: string) => Promise<AgentChannel>;
+  /** `true` while any phase of the install flow is in progress. */
+  readonly isInProgress: boolean;
+  /** Current phase of the install flow. */
+  readonly phase: SlackConnectPhase;
+  /** Error from the most recent unsuccessful attempt, or `null`. */
+  readonly error: Error | null;
+  /** Reset the hook to idle state, cancelling any in-flight flow. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that orchestrates the Slack channel install flow.
+ *
+ * Handles the complete lifecycle:
+ * 1. Calls `initiateInstall` to get Slack's authorization URL + state
+ * 2. Opens a popup window to the "Add to Slack" consent screen
+ * 3. Waits for the callback (`postMessage` + BroadcastChannel, via the
+ *    shared `internal/oauthPopup.ts` machinery)
+ * 4. Calls `completeInstall` to exchange the code — the server stores the
+ *    bot token and records the install facts on `status.slack`
+ *
+ * The callback page is the same `OAuthCallbackHandler` component used by
+ * MCP OAuth, hosted on the console's Slack redirect route.
+ *
+ * @example
+ * ```tsx
+ * const slack = useConnectSlackChannel();
+ *
+ * async function handleConnect() {
+ *   try {
+ *     const installed = await slack.connect(channel.metadata.id);
+ *     refetch();
+ *   } catch {
+ *     // error is available via slack.error
+ *   }
+ * }
+ *
+ * <button onClick={handleConnect} disabled={slack.isInProgress}>
+ *   {slack.isInProgress ? "Connecting..." : "Connect to Slack"}
+ * </button>
+ * ```
+ */
+export function useConnectSlackChannel(): UseConnectSlackChannelReturn {
+  const stigmer = useStigmer();
+  const [phase, setPhase] = useState<SlackConnectPhase>("idle");
+  const [error, setError] = useState<Error | null>(null);
+
+  const popupRef = useRef<Window | null>(null);
+  const cleanupRef = useRef<(() => void) | null>(null);
+  const cancelledRef = useRef(false);
+
+  useEffect(() => {
+    return () => {
+      cleanupRef.current?.();
+    };
+  }, []);
+
+  const clearError = useCallback(() => {
+    if (cleanupRef.current || popupRef.current) {
+      cancelledRef.current = true;
+      cleanupRef.current?.();
+      closeOAuthPopup(popupRef.current);
+      popupRef.current = null;
+      cleanupRef.current = null;
+    }
+    setPhase("idle");
+    setError(null);
+  }, []);
+
+  const connect = useCallback(
+    async (channelId: string): Promise<AgentChannel> => {
+      setPhase("initiating");
+      setError(null);
+      cancelledRef.current = false;
+
+      cleanupRef.current?.();
+
+      const popup = openOAuthPopup();
+      if (!popup) {
+        const blocked = popupBlockedError();
+        setError(blocked);
+        setPhase("idle");
+        throw blocked;
+      }
+
+      popupRef.current = popup;
+
+      try {
+        const initOutput = await stigmer.agentChannel.initiateInstall(
+          create(InitiateChannelInstallInputSchema, { resourceId: channelId }),
+        );
+
+        popup.location.href = initOutput.authorizationUrl;
+        setPhase("awaiting-callback");
+
+        const { code, state } = await waitForOAuthCallback(
+          popup,
+          initOutput.state,
+          (dispose) => {
+            cleanupRef.current = dispose;
+          },
+        );
+
+        setPhase("completing");
+
+        const channel = await stigmer.agentChannel.completeInstall(
+          create(CompleteChannelInstallInputSchema, {
+            resourceId: channelId,
+            state,
+            code,
+          }),
+        );
+
+        setPhase("done");
+        return channel;
+      } catch (err) {
+        const wrapped = toError(err);
+        if (!cancelledRef.current) {
+          setError(wrapped);
+          setPhase("idle");
+          closeOAuthPopup(popup);
+        }
+        cancelledRef.current = false;
+        throw wrapped;
+      } finally {
+        popupRef.current = null;
+        cleanupRef.current = null;
+      }
+    },
+    [stigmer],
+  );
+
+  return {
+    connect,
+    isInProgress: phase !== "idle" && phase !== "done",
+    phase,
+    error,
+    clearError,
+  };
+}