@stigmer/react 3.1.7 → 3.1.8

package/src/sharing/useShareToolReadiness.ts

@@ -0,0 +1,129 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { useStigmer } from "../hooks.js";
+import { useDeploymentMode } from "../deployment-mode.js";
+
+/**
+ * Readiness of a shared agent's tool credentials for visitor (and
+ * teammate) executions.
+ *
+ * - `na` — nothing to check: the agent uses no MCP tools, the check is
+ *   disabled, or the deployment cannot serve guest chat (local mode).
+ * - `checking` — lookups in flight.
+ * - `ready` — every environment bound to the agent's default instance is
+ *   shared with the organization.
+ * - `blocked` — one or more bound environments are private; their
+ *   `org/slug` references are listed for the hint copy.
+ */
+export type ShareToolReadiness =
+  | { readonly status: "na" }
+  | { readonly status: "checking" }
+  | { readonly status: "ready" }
+  | { readonly status: "blocked"; readonly privateEnvironments: readonly string[] };
+
+const NA: ShareToolReadiness = { status: "na" };
+
+/**
+ * Data hook that checks whether a tool-using shared agent's credentials
+ * will work for visitors — i.e. whether the environments bound to its
+ * default instance are shared with the organization (`visibility_org`).
+ *
+ * Guest and teammate executions can only use org-shared environments;
+ * a private environment's secrets are creator-only and silently
+ * unavailable to them, so the agent's tools would fail at runtime. This
+ * hook powers the Share dialog's pre-flight hint, catching the
+ * misconfiguration at share time instead of at the visitor's first
+ * message.
+ *
+ * Scope note: environments bound via `environment_refs` are the
+ * supported credential path for shared agents. Credentials that only
+ * exist in the owner's personal environment are also invisible to
+ * guests, but are not detectable from the instance binding — the
+ * runtime's enriched FAILED_PRECONDITION error covers that case.
+ *
+ * The check runs only when `enabled` is true, the deployment is cloud
+ * (local mode has no guest runtime or secret gating), and the agent
+ * declares MCP server usages. All lookups run as the owner viewing the
+ * dialog, who can read the bound environments.
+ */
+export function useShareToolReadiness(
+  agent: Agent,
+  enabled: boolean,
+): ShareToolReadiness {
+  const stigmer = useStigmer();
+  const deploymentMode = useDeploymentMode();
+  const [readiness, setReadiness] = useState<ShareToolReadiness>(NA);
+
+  const agentId = agent.metadata?.id ?? "";
+  const hasMcpTools = (agent.spec?.mcpServerUsages?.length ?? 0) > 0;
+  const defaultInstanceId = agent.status?.defaultInstanceId ?? "";
+
+  const shouldCheck =
+    enabled &&
+    deploymentMode === "cloud" &&
+    hasMcpTools &&
+    defaultInstanceId !== "";
+
+  useEffect(() => {
+    if (!shouldCheck) {
+      setReadiness(NA);
+      return;
+    }
+
+    let cancelled = false;
+    setReadiness({ status: "checking" });
+
+    (async (): Promise<ShareToolReadiness> => {
+      const instance = await stigmer.agentInstance.get(defaultInstanceId);
+      const refs = instance.spec?.environmentRefs ?? [];
+      if (refs.length === 0) {
+        // No bound environments to assess. The tools may need no
+        // credentials at all — do not warn on a guess.
+        return NA;
+      }
+
+      const privateRefs: string[] = [];
+      for (const ref of refs) {
+        try {
+          const env = await stigmer.environment.getByReference({
+            org: ref.org,
+            slug: ref.slug,
+          });
+          if (
+            env.metadata?.visibility !== ApiResourceVisibility.visibility_org
+          ) {
+            privateRefs.push(`${ref.org}/${ref.slug}`);
+          }
+        } catch {
+          // Unreadable ref (deleted, foreign): the runtime will skip it
+          // for visitors too — surface it as blocking.
+          privateRefs.push(`${ref.org}/${ref.slug}`);
+        }
+      }
+
+      return privateRefs.length === 0
+        ? { status: "ready" }
+        : { status: "blocked", privateEnvironments: privateRefs };
+    })().then(
+      (result) => {
+        if (!cancelled) setReadiness(result);
+      },
+      () => {
+        // The hint is best-effort pre-flight advice — a failed check must
+        // never block the dialog. The runtime error path still diagnoses.
+        if (!cancelled) setReadiness(NA);
+      },
+    );
+
+    return () => {
+      cancelled = true;
+    };
+    // agentId stands in for the agent object identity: the inputs that
+    // matter (instance id, MCP usage presence) are covered explicitly.
+  }, [shouldCheck, defaultInstanceId, agentId, stigmer]);
+
+  return readiness;
+}

package/src/sharing/useSharedAgentProfile.ts

@@ -0,0 +1,131 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import {
+  GetSharedProfileRequestSchema,
+  type SharedAgentProfile,
+} from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
+import { isNotFound } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+import type { SharingAudience } from "./useUpdateAgentSharing.js";
+
+/** Options for {@link useSharedAgentProfile}. */
+export interface UseSharedAgentProfileOptions {
+  /**
+   * Which resolution path to use.
+   *
+   * - `"public"` (default) — the anonymous `getSharedProfile` RPC. An
+   *   org-audience share answers NOT_FOUND here by design.
+   * - `"org"` — the authenticated `getSharedProfileForMember` RPC, which
+   *   resolves org-audience shares for signed-in members of the owning
+   *   organization (and public shares too). Requires a `StigmerProvider`
+   *   whose client carries the member's token.
+   */
+  readonly audience?: SharingAudience;
+
+  /**
+   * Share-link token from the URL's `?k=` parameter (public path only).
+   *
+   * Required when the share link has been locked with a rotatable token;
+   * harmless on plain links. On a locked link a missing or rotated-away
+   * token resolves to `profile === null`, indistinguishable from an
+   * agent that does not exist.
+   */
+  readonly linkToken?: string;
+}
+
+/** Return value of {@link useSharedAgentProfile}. */
+export interface UseSharedAgentProfileReturn {
+  /**
+   * The shared agent's public profile, or `null` while loading, on
+   * error, or when the agent is not shared.
+   */
+  readonly profile: SharedAgentProfile | null;
+  /** `true` while the initial fetch or a refetch is in flight. */
+  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;
+  /** Discard cached data and re-fetch the profile from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a shared agent's public profile by
+ * organization and agent slug.
+ *
+ * By default this hook calls the `getSharedProfile` endpoint, which is
+ * **public** — it requires no authentication. The server returns a
+ * trimmed projection safe for anonymous visitors: name, description,
+ * icon, and the default instance id needed to start a session
+ * (an identifier, not a capability — session creation still requires
+ * an authorized token, e.g. a guest token from `createGuestAuth`).
+ * With `{ audience: "org" }` it calls the authenticated
+ * `getSharedProfileForMember` endpoint instead, which resolves
+ * org-members-only shares for a signed-in member.
+ *
+ * **Not-shared handling:** the server answers NOT_FOUND for "this
+ * agent does not exist", "this agent is not shared", and (on the
+ * member path) "you are not a member of this organization" — all
+ * indistinguishable by design so a share URL leaks nothing. The hook
+ * maps that to `profile === null` without raising an error, matching
+ * `useAgent`'s not-found convention:
+ * `profile === null && !isLoading && !error` means unavailable.
+ *
+ * Pass `null` for either `org` or `slug` to skip fetching (stable
+ * no-op) — useful while route params are still resolving.
+ *
+ * **Note**: Although authentication is not required by the server,
+ * the hook still requires a `StigmerProvider` ancestor because it
+ * needs the transport configuration (API base URL) to make the
+ * request.
+ *
+ * @example
+ * ```tsx
+ * const { profile, isLoading, error } = useSharedAgentProfile(org, slug);
+ *
+ * if (isLoading) return <Spinner />;
+ * if (error) return <ErrorCard error={error} />;
+ * if (!profile) return <AgentUnavailable />;
+ *
+ * return <h1>{profile.name}</h1>;
+ * ```
+ */
+export function useSharedAgentProfile(
+  org: string | null,
+  slug: string | null,
+  options?: UseSharedAgentProfileOptions,
+): UseSharedAgentProfileReturn {
+  const stigmer = useStigmer();
+  const audience = options?.audience ?? "public";
+  const linkToken = options?.linkToken ?? "";
+
+  const fetchFn =
+    org && slug
+      ? async () => {
+          try {
+            // The member path is tokenless by contract: org-audience access
+            // is gated by live membership, and token-locked public shares
+            // deliberately refuse there (see getSharedProfileForMember).
+            return audience === "org"
+              ? await stigmer.agent.getSharedProfileForMember({ org, slug })
+              : await stigmer.agent.getSharedProfile(
+                  create(GetSharedProfileRequestSchema, { org, slug, linkToken }),
+                );
+          } catch (err) {
+            if (isNotFound(err)) return null;
+            throw err;
+          }
+        }
+      : null;
+
+  const { data: profile, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [org, slug, audience, linkToken, stigmer],
+    null as SharedAgentProfile | null,
+  );
+
+  return { profile, isLoading, isRefetching, error, refetch };
+}

package/src/sharing/useUpdateAgentSharing.ts

@@ -0,0 +1,151 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { UpdateAgentSharingInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
+import {
+  AgentSharingAudience,
+  AgentSharingSchema,
+  AgentSharingMessagesSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/**
+ * Who can chat with a shared agent over its hosted link.
+ *
+ * - `"public"` — anyone with the link; visitors are anonymous guests.
+ * - `"org"` — signed-in members of the owning organization only.
+ *   Membership is checked on every conversation turn, so access ends the
+ *   moment a member leaves the org.
+ */
+export type SharingAudience = "public" | "org";
+
+/**
+ * A complete sharing configuration to persist.
+ *
+ * Every field is required by design: the `updateSharing` RPC **replaces**
+ * the agent's whole `spec.sharing` block, so a caller must always supply
+ * the full configuration. A partial type here would let a toggle change
+ * silently wipe `allowedOrigins`, `messages`, or the `audience` — the
+ * required shape makes that mistake unrepresentable.
+ */
+export interface AgentSharingDraft {
+  /** Whether hosted-chat access for the configured audience is enabled. */
+  readonly enabled: boolean;
+  /** Who can chat: anyone with the link, or org members only. */
+  readonly audience: SharingAudience;
+  /**
+   * Exact web origins allowed to embed the shared agent
+   * (e.g. `https://example.com`). Stored now; enforced by the embed
+   * widget's Origin check. Embedding is public-audience only.
+   */
+  readonly allowedOrigins: readonly string[];
+  /** Owner-customized visitor refusal copy. Empty strings mean platform defaults. */
+  readonly messages: {
+    /** Shown when a visitor exceeds the message rate limit. */
+    readonly rateLimited: string;
+    /** Shown when the org's credits are exhausted (sharing fails closed). */
+    readonly unavailable: string;
+    /** Shown when a conversation hits its turn limit or inactivity timeout. */
+    readonly conversationEnded: string;
+  };
+}
+
+/**
+ * Maps a proto {@link AgentSharingAudience} to the SDK's string union.
+ * Unspecified means public by contract (pre-audience shares keep their
+ * anyone-with-link behavior).
+ */
+export function sharingAudienceFromProto(
+  audience: AgentSharingAudience | undefined,
+): SharingAudience {
+  return audience === AgentSharingAudience.org ? "org" : "public";
+}
+
+function sharingAudienceToProto(audience: SharingAudience): AgentSharingAudience {
+  return audience === "org"
+    ? AgentSharingAudience.org
+    : AgentSharingAudience.public;
+}
+
+/** Return value of {@link useUpdateAgentSharing}. */
+export interface UseUpdateAgentSharingReturn {
+  /**
+   * Persist the complete sharing configuration via the `updateSharing`
+   * RPC. Resolves with the updated agent.
+   */
+  readonly updateSharing: (draft: AgentSharingDraft) => Promise<Agent | undefined>;
+  /** `true` while the RPC is in flight. */
+  readonly isPending: boolean;
+  /** The last error from the RPC, or `null`. */
+  readonly error: Error | null;
+}
+
+/**
+ * Behavior hook that updates an agent's sharing configuration.
+ *
+ * Wraps the targeted `stigmer.agent.updateSharing()` RPC (authorized by
+ * `can_edit`) with loading and error state management. The hook is
+ * stateless with respect to the agent — the caller refreshes the resource
+ * after a successful update (e.g. via `refetch` from `useAgent`), matching
+ * the {@link useUpdateVisibility} convention.
+ *
+ * Pass `null` for `agentId` to produce a stable no-op (useful while the
+ * agent is still loading).
+ *
+ * @example
+ * ```tsx
+ * const { updateSharing, isPending } = useUpdateAgentSharing(agent.metadata.id);
+ *
+ * await updateSharing({
+ *   enabled: true,
+ *   audience: "public",
+ *   allowedOrigins: ["https://example.com"],
+ *   messages: { rateLimited: "", unavailable: "", conversationEnded: "" },
+ * });
+ * refetch();
+ * ```
+ */
+export function useUpdateAgentSharing(
+  agentId: string | null,
+): UseUpdateAgentSharingReturn {
+  const stigmer = useStigmer();
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const updateSharing = useCallback(
+    async (draft: AgentSharingDraft): Promise<Agent | undefined> => {
+      if (!agentId) return undefined;
+
+      setIsPending(true);
+      setError(null);
+
+      try {
+        const input = create(UpdateAgentSharingInputSchema, {
+          resourceId: agentId,
+          sharing: create(AgentSharingSchema, {
+            enabled: draft.enabled,
+            audience: sharingAudienceToProto(draft.audience),
+            allowedOrigins: [...draft.allowedOrigins],
+            messages: create(AgentSharingMessagesSchema, {
+              rateLimited: draft.messages.rateLimited,
+              unavailable: draft.messages.unavailable,
+              conversationEnded: draft.messages.conversationEnded,
+            }),
+          }),
+        });
+        return await stigmer.agent.updateSharing(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [agentId, stigmer],
+  );
+
+  return { updateSharing, isPending, error };
+}

package/src/switch/Switch.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link Switch}. */
+export interface SwitchProps {
+  /** Whether the switch is on. */
+  readonly checked: boolean;
+  /** Called with the next value when the user toggles the switch. */
+  readonly onCheckedChange: (checked: boolean) => void;
+  /** When `true`, the switch is shown but non-interactive. */
+  readonly disabled?: boolean;
+  /**
+   * Accessible name. Required unless `aria-labelledby` points at a
+   * visible label element.
+   */
+  readonly "aria-label"?: string;
+  /** ID of the element that labels this switch. */
+  readonly "aria-labelledby"?: string;
+  /** Element ID, for association with an external `<label htmlFor>`. */
+  readonly id?: string;
+  /** Additional CSS classes for the root button. */
+  readonly className?: string;
+}
+
+/**
+ * Accessible on/off toggle following the WAI-ARIA Switch pattern.
+ *
+ * Built on a native `<button role="switch">` so Space/Enter activation,
+ * focus, and disabled semantics come from the platform. `aria-checked`
+ * reflects the state for assistive technology.
+ *
+ * Use a switch only for instant binary state changes that take effect
+ * immediately (e.g. enabling sharing) — not for choices that need a
+ * separate save step (use radios or a select for those).
+ *
+ * The visible track is compact; an invisible expanded hit area keeps the
+ * touch target at ~44px without disturbing layout. All visual properties
+ * flow through `--stgm-*` design tokens, and the thumb transition is
+ * suppressed under `prefers-reduced-motion`.
+ *
+ * @example
+ * ```tsx
+ * <Switch
+ *   checked={sharing.enabled}
+ *   onCheckedChange={(next) => save({ ...sharing, enabled: next })}
+ *   aria-label="Enable sharing"
+ * />
+ * ```
+ */
+export function Switch({
+  checked,
+  onCheckedChange,
+  disabled,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledby,
+  id,
+  className,
+}: SwitchProps) {
+  return (
+    <button
+      type="button"
+      role="switch"
+      id={id}
+      aria-checked={checked}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledby}
+      disabled={disabled}
+      onClick={() => onCheckedChange(!checked)}
+      className={cn(
+        // Track. `relative` anchors both the thumb and the expanded hit area.
+        "relative inline-flex h-5 w-9 shrink-0 items-center rounded-full transition-colors",
+        "motion-reduce:transition-none",
+        checked ? "bg-primary" : "bg-muted",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:pointer-events-none disabled:opacity-50",
+        // Expanded invisible hit area (~44px tall) for touch targets.
+        "after:absolute after:-inset-3 after:content-['']",
+        className,
+      )}
+    >
+      <span
+        aria-hidden="true"
+        className={cn(
+          "pointer-events-none block size-4 rounded-full bg-background shadow-sm transition-transform",
+          "motion-reduce:transition-none",
+          checked ? "translate-x-[18px]" : "translate-x-0.5",
+        )}
+      />
+    </button>
+  );
+}

package/src/switch/__tests__/Switch.test.tsx

@@ -0,0 +1,88 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Switch } from "../Switch";
+
+afterEach(cleanup);
+
+describe("Switch", () => {
+  it("renders as role=switch with aria-checked reflecting state", () => {
+    const { rerender } = render(
+      <Switch checked={false} onCheckedChange={() => {}} aria-label="Enable sharing" />,
+    );
+
+    const el = screen.getByRole("switch", { name: "Enable sharing" });
+    expect(el.getAttribute("aria-checked")).toBe("false");
+
+    rerender(
+      <Switch checked onCheckedChange={() => {}} aria-label="Enable sharing" />,
+    );
+    expect(el.getAttribute("aria-checked")).toBe("true");
+  });
+
+  it("calls onCheckedChange with the next value on click", () => {
+    const onCheckedChange = vi.fn();
+    render(
+      <Switch checked={false} onCheckedChange={onCheckedChange} aria-label="Enable sharing" />,
+    );
+
+    screen.getByRole("switch").click();
+    expect(onCheckedChange).toHaveBeenCalledTimes(1);
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+  });
+
+  it("calls onCheckedChange(false) when toggling off", () => {
+    const onCheckedChange = vi.fn();
+    render(
+      <Switch checked onCheckedChange={onCheckedChange} aria-label="Enable sharing" />,
+    );
+
+    screen.getByRole("switch").click();
+    expect(onCheckedChange).toHaveBeenCalledWith(false);
+  });
+
+  it("is a native button, so Space/Enter activation comes from the platform", () => {
+    render(
+      <Switch checked={false} onCheckedChange={() => {}} aria-label="Enable sharing" />,
+    );
+
+    const el = screen.getByRole("switch");
+    // happy-dom does not synthesize click from keydown; assert the native
+    // button element carries the behavior instead of re-implementing it.
+    expect(el.tagName).toBe("BUTTON");
+    expect(el.getAttribute("type")).toBe("button");
+  });
+
+  it("does not fire when disabled", () => {
+    const onCheckedChange = vi.fn();
+    render(
+      <Switch
+        checked={false}
+        onCheckedChange={onCheckedChange}
+        disabled
+        aria-label="Enable sharing"
+      />,
+    );
+
+    const el = screen.getByRole("switch") as HTMLButtonElement;
+    expect(el.disabled).toBe(true);
+    el.click();
+    expect(onCheckedChange).not.toHaveBeenCalled();
+  });
+
+  it("supports aria-labelledby for external labels", () => {
+    render(
+      <>
+        <span id="share-label">Enable sharing</span>
+        <Switch
+          checked={false}
+          onCheckedChange={() => {}}
+          aria-labelledby="share-label"
+        />
+      </>,
+    );
+
+    expect(
+      screen.getByRole("switch", { name: "Enable sharing" }),
+    ).toBeTruthy();
+  });
+});

package/src/switch/index.ts

@@ -0,0 +1,2 @@
+export { Switch } from "./Switch.js";
+export type { SwitchProps } from "./Switch.js";