@stigmer/react 3.1.7 → 3.1.9

package/src/sharing/__tests__/useSharedAgentProfile.test.tsx

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { Code } from "@connectrpc/connect";
+import { StigmerError } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useSharedAgentProfile } from "../useSharedAgentProfile";
+
+function createMockStigmer(overrides: {
+  getSharedProfile?: (...args: unknown[]) => Promise<unknown>;
+  getSharedProfileForMember?: (...args: unknown[]) => Promise<unknown>;
+} = {}) {
+  return {
+    agentShare: {
+      getSharedProfile:
+        overrides.getSharedProfile ?? vi.fn().mockResolvedValue(null),
+      getSharedProfileForMember:
+        overrides.getSharedProfileForMember ?? vi.fn().mockResolvedValue(null),
+    },
+  } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  };
+}
+
+const PROFILE = {
+  org: "acme",
+  slug: "support-agent",
+  name: "Support Agent",
+  description: "Answers support questions",
+  iconUrl: "",
+  defaultInstanceId: "inst_1",
+};
+
+describe("useSharedAgentProfile", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("fetches the profile by org and slug", async () => {
+    const getSharedProfile = vi.fn().mockResolvedValue(PROFILE);
+    const client = createMockStigmer({ getSharedProfile });
+
+    const { result } = renderHook(
+      () => useSharedAgentProfile("acme", "support-agent"),
+      { wrapper: wrapper(client) },
+    );
+
+    expect(result.current.isLoading).toBe(true);
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.profile).toBe(PROFILE);
+    expect(result.current.error).toBeNull();
+    // The hook builds a GetSharedProfileRequest message; a plain link
+    // carries an empty link token.
+    expect(getSharedProfile).toHaveBeenCalledWith(
+      expect.objectContaining({
+        org: "acme",
+        slug: "support-agent",
+        linkToken: "",
+      }),
+    );
+  });
+
+  it("threads the linkToken option into the public request", async () => {
+    const getSharedProfile = vi.fn().mockResolvedValue(PROFILE);
+    const client = createMockStigmer({ getSharedProfile });
+
+    const { result } = renderHook(
+      () =>
+        useSharedAgentProfile("acme", "support-agent", { linkToken: "tok123" }),
+      { wrapper: wrapper(client) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(getSharedProfile).toHaveBeenCalledWith(
+      expect.objectContaining({ linkToken: "tok123" }),
+    );
+  });
+
+  it("resolves through getSharedProfileForMember for the org audience", async () => {
+    const getSharedProfile = vi.fn();
+    const getSharedProfileForMember = vi.fn().mockResolvedValue(PROFILE);
+    const client = createMockStigmer({
+      getSharedProfile,
+      getSharedProfileForMember,
+    });
+
+    const { result } = renderHook(
+      () =>
+        useSharedAgentProfile("acme", "support-agent", { audience: "org" }),
+      { wrapper: wrapper(client) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.profile).toBe(PROFILE);
+    expect(getSharedProfileForMember).toHaveBeenCalledWith({
+      org: "acme",
+      slug: "support-agent",
+    });
+    // The anonymous path returns NOT_FOUND for org shares by design; the
+    // hook must never fall back to it in org mode.
+    expect(getSharedProfile).not.toHaveBeenCalled();
+  });
+
+  it("maps a member-path NOT_FOUND (non-member) to profile === null", async () => {
+    const getSharedProfileForMember = vi.fn().mockRejectedValue(
+      new StigmerError("not-found", "agent not found", Code.NotFound),
+    );
+    const client = createMockStigmer({ getSharedProfileForMember });
+
+    const { result } = renderHook(
+      () =>
+        useSharedAgentProfile("acme", "support-agent", { audience: "org" }),
+      { wrapper: wrapper(client) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.profile).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  it("skips fetching when org is null", () => {
+    const getSharedProfile = vi.fn();
+    const client = createMockStigmer({ getSharedProfile });
+
+    const { result } = renderHook(
+      () => useSharedAgentProfile(null, "support-agent"),
+      { wrapper: wrapper(client) },
+    );
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.profile).toBeNull();
+    expect(getSharedProfile).not.toHaveBeenCalled();
+  });
+
+  it("skips fetching when slug is null", () => {
+    const getSharedProfile = vi.fn();
+    const client = createMockStigmer({ getSharedProfile });
+
+    const { result } = renderHook(() => useSharedAgentProfile("acme", null), {
+      wrapper: wrapper(client),
+    });
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.profile).toBeNull();
+    expect(getSharedProfile).not.toHaveBeenCalled();
+  });
+
+  it("maps NOT_FOUND (unshared or nonexistent) to null without error", async () => {
+    // The generated client rethrows every failure wrapped as a
+    // StigmerError — reject with the same shape the hook really sees.
+    const getSharedProfile = vi
+      .fn()
+      .mockRejectedValue(
+        new StigmerError("not-found", "agent not found", Code.NotFound),
+      );
+    const client = createMockStigmer({ getSharedProfile });
+
+    const { result } = renderHook(
+      () => useSharedAgentProfile("acme", "revoked-agent"),
+      { wrapper: wrapper(client) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.profile).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  it("exposes non-404 failures as errors", async () => {
+    const getSharedProfile = vi
+      .fn()
+      .mockRejectedValue(new Error("Internal server error"));
+    const client = createMockStigmer({ getSharedProfile });
+
+    const { result } = renderHook(
+      () => useSharedAgentProfile("acme", "support-agent"),
+      { wrapper: wrapper(client) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.error).toBeTruthy();
+    expect(result.current.profile).toBeNull();
+  });
+});

package/src/sharing/index.ts

@@ -0,0 +1,32 @@
+export { useSharedAgentProfile } from "./useSharedAgentProfile.js";
+export type {
+  UseSharedAgentProfileOptions,
+  UseSharedAgentProfileReturn,
+} from "./useSharedAgentProfile.js";
+export { SharedAgentChat } from "./SharedAgentChat.js";
+export type { SharedAgentChatProps } from "./SharedAgentChat.js";
+export { useAgentShare } from "./useAgentShare.js";
+export type { UseAgentShareReturn } from "./useAgentShare.js";
+export {
+  sharingAudienceFromProto,
+  useSaveAgentShare,
+} from "./useSaveAgentShare.js";
+export type {
+  AgentShareDraft,
+  SharingAudience,
+  UseSaveAgentShareReturn,
+} from "./useSaveAgentShare.js";
+export { useRotateShareLink } from "./useRotateShareLink.js";
+export type { UseRotateShareLinkReturn } from "./useRotateShareLink.js";
+export { ShareAgentDialog } from "./ShareAgentDialog.js";
+export type { ShareAgentDialogProps } from "./ShareAgentDialog.js";
+export { useShareAgent } from "./useShareAgent.js";
+export type {
+  UseShareAgentArgs,
+  UseShareAgentReturn,
+} from "./useShareAgent.js";
+export { useShareToolReadiness } from "./useShareToolReadiness.js";
+export type { ShareToolReadiness } from "./useShareToolReadiness.js";
+// Origin validation moved to @stigmer/sdk (framework-free, shared with the
+// CLI); re-exported here so existing @stigmer/react importers keep working.
+export { validateOrigin, MAX_ALLOWED_ORIGINS } from "@stigmer/sdk";

package/src/sharing/useAgentShare.ts

@@ -0,0 +1,91 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { AgentShare } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/api_pb";
+import { GetAgentSharesByAgentRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Return value of {@link useAgentShare}. */
+export interface UseAgentShareReturn {
+  /**
+   * The agent's canonical share, or `null` while loading, on error, or
+   * when the agent has never been shared. `share === null && !isLoading
+   * && !error` means "no share exists yet" — the first save creates it.
+   */
+  readonly share: AgentShare | 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 share from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * The canonical share among an agent's shares: the one whose slug equals
+ * the agent's slug (the server's default when a share is created without
+ * an explicit slug), falling back to the first entry. The data model
+ * allows N shares per agent (decision 011 D3); the console manages the
+ * canonical one in Phase A, so extra shares created via manifests never
+ * confuse the dialog.
+ */
+function pickCanonicalShare(
+  shares: readonly AgentShare[],
+  agentSlug: string,
+): AgentShare | null {
+  return (
+    shares.find((share) => share.metadata?.slug === agentSlug) ??
+    shares[0] ??
+    null
+  );
+}
+
+/**
+ * Data hook that loads an agent's canonical {@link AgentShare} — the
+ * resource carrying the hosted-chat channel configuration (audience,
+ * allowed origins, visitor messages, tool credentials, link token).
+ *
+ * Sharing is channel configuration, not agent behavior (decision 011):
+ * it lives in its own resource, so reading the agent alone can never
+ * tell whether it is shared. This hook is how owner-side surfaces (the
+ * Share dialog) resolve that state.
+ *
+ * Pass `null` for `agent` to skip fetching (stable no-op) — useful
+ * while the agent is still loading. A resolved `null` share means the
+ * agent has never been shared; the first save creates the share.
+ *
+ * @example
+ * ```tsx
+ * const { share, isLoading } = useAgentShare(agent);
+ *
+ * if (isLoading) return <Spinner />;
+ * const enabled = share?.spec?.enabled ?? false;
+ * ```
+ */
+export function useAgentShare(agent: Agent | null): UseAgentShareReturn {
+  const stigmer = useStigmer();
+
+  const agentId = agent?.metadata?.id ?? "";
+  const agentSlug = agent?.metadata?.slug ?? "";
+
+  const fetchFn = agentId
+    ? async () => {
+        const result = await stigmer.agentShare.getByAgent(
+          create(GetAgentSharesByAgentRequestSchema, { agentId }),
+        );
+        return pickCanonicalShare(result.items, agentSlug);
+      }
+    : null;
+
+  const { data: share, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [agentId, agentSlug, stigmer],
+    null as AgentShare | null,
+  );
+
+  return { share, isLoading, isRefetching, error, refetch };
+}

package/src/sharing/useRotateShareLink.ts

@@ -0,0 +1,81 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { AgentShare } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/api_pb";
+import { RotateShareLinkInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useRotateShareLink}. */
+export interface UseRotateShareLinkReturn {
+  /**
+   * Rotate the share's link token via the `rotateShareLink` RPC.
+   * Resolves with the updated share, whose `status.shareLinkToken`
+   * carries the new token for building the fresh share URL.
+   */
+  readonly rotateShareLink: () => Promise<AgentShare | 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 rotates a share's link token.
+ *
+ * Wraps the `stigmer.agentShare.rotateShareLink()` RPC (authorized by
+ * the share's `can_edit`) with loading and error state management. The
+ * server generates the token — there is nothing to supply — and the
+ * previous link stops working the moment the call resolves, including
+ * for visitors mid-conversation. The token lives in
+ * `status.shareLinkToken` (server-owned; this RPC is its sole writer),
+ * so it is never part of a share draft and survives every apply.
+ *
+ * The hook is stateless with respect to the share — adopt the returned
+ * share (or refetch) so the UI shows the new tokened link, matching the
+ * {@link useSaveAgentShare} convention.
+ *
+ * Pass `null` for `shareId` to produce a stable no-op (useful while the
+ * share is still loading, or before the agent has ever been shared —
+ * there is no token to rotate until a share exists).
+ *
+ * @example
+ * ```tsx
+ * const { rotateShareLink, isPending } = useRotateShareLink(
+ *   share?.metadata?.id ?? null,
+ * );
+ *
+ * const updated = await rotateShareLink();
+ * // updated.status.shareLinkToken is the new token
+ * ```
+ */
+export function useRotateShareLink(
+  shareId: string | null,
+): UseRotateShareLinkReturn {
+  const stigmer = useStigmer();
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const rotateShareLink = useCallback(async (): Promise<
+    AgentShare | undefined
+  > => {
+    if (!shareId) return undefined;
+
+    setIsPending(true);
+    setError(null);
+
+    try {
+      return await stigmer.agentShare.rotateShareLink(
+        create(RotateShareLinkInputSchema, { resourceId: shareId }),
+      );
+    } catch (err) {
+      setError(toError(err));
+      throw err;
+    } finally {
+      setIsPending(false);
+    }
+  }, [shareId, stigmer]);
+
+  return { rotateShareLink, isPending, error };
+}

package/src/sharing/useSaveAgentShare.ts

@@ -0,0 +1,186 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { AgentShare } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/api_pb";
+import { AgentShareAudience } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/spec_pb";
+import type { ResourceRef } from "@stigmer/sdk";
+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 share configuration to persist.
+ *
+ * Every field is required by design: saving **replaces the share's whole
+ * spec**, so a caller must always supply the full configuration. A
+ * partial type here would let a toggle change silently wipe
+ * `allowedOrigins`, `messages`, `environmentRefs`, or the `audience` —
+ * the required shape makes that mistake unrepresentable. (The rotatable
+ * link token is exempt: it is server-owned `status`, which survives
+ * every save verbatim.)
+ */
+export interface AgentShareDraft {
+  /** 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`). Empty list = embeddable anywhere.
+   * 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;
+  };
+  /**
+   * Org-shared environments whose values guest conversations receive —
+   * how a tool-using agent becomes chattable over a share link without
+   * touching its pristine default instance. Public-audience only (the
+   * proto CEL rule rejects bindings on org-audience shares, whose member
+   * sessions carry no share linkage in Phase A — decision 011 addendum).
+   */
+  readonly environmentRefs: readonly ResourceRef[];
+}
+
+/**
+ * Maps a proto {@link AgentShareAudience} to the SDK's string union.
+ * Unspecified means public by contract (a share created without an
+ * explicit audience is an anyone-with-link share).
+ */
+export function sharingAudienceFromProto(
+  audience: AgentShareAudience | undefined,
+): SharingAudience {
+  return audience === AgentShareAudience.org ? "org" : "public";
+}
+
+function sharingAudienceToProto(audience: SharingAudience): AgentShareAudience {
+  return audience === "org"
+    ? AgentShareAudience.org
+    : AgentShareAudience.public;
+}
+
+/** Return value of {@link useSaveAgentShare}. */
+export interface UseSaveAgentShareReturn {
+  /**
+   * Persist the complete share configuration. Resolves with the
+   * persisted {@link AgentShare} — adopt it as the new baseline (its
+   * `status.shareLinkToken` carries the live link token).
+   *
+   * `current` is the share being edited, or `null` when the agent has
+   * never been shared — the save then creates the canonical share.
+   */
+  readonly save: (
+    draft: AgentShareDraft,
+    current: AgentShare | null,
+  ) => Promise<AgentShare | 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 persists an agent's canonical share configuration.
+ *
+ * Commits via `stigmer.agentShare.apply()` — an idempotent upsert keyed
+ * on the share's `(org, slug)` identity — so one code path serves both
+ * the first enable (creates the share; the server authorizes on the
+ * referenced agent's `can_edit`) and every later edit. There is
+ * deliberately no create/update branching: the share slug is unique per
+ * org and defaults to the agent's slug, which makes apply-by-identity
+ * exact, and the generated `AgentShareInput` carries no `metadata.id`
+ * for an update to route by anyway.
+ *
+ * Disabling is a save with `enabled: false` — a config-preserving pause
+ * (decision 011 D1). Deleting the share is a separate, destructive
+ * operation this hook does not perform.
+ *
+ * Pass `null` for `agent` to produce a stable no-op (useful while the
+ * agent is still loading).
+ *
+ * @example
+ * ```tsx
+ * const { share } = useAgentShare(agent);
+ * const { save, isPending } = useSaveAgentShare(agent);
+ *
+ * const persisted = await save({ ...draft, enabled: true }, share);
+ * // persisted.status.shareLinkToken is the live link token
+ * ```
+ */
+export function useSaveAgentShare(
+  agent: Agent | null,
+): UseSaveAgentShareReturn {
+  const stigmer = useStigmer();
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const agentOrg = agent?.metadata?.org ?? "";
+  const agentSlug = agent?.metadata?.slug ?? "";
+  const agentName = agent?.metadata?.name ?? "";
+
+  const save = useCallback(
+    async (
+      draft: AgentShareDraft,
+      current: AgentShare | null,
+    ): Promise<AgentShare | undefined> => {
+      if (!agentOrg || !agentSlug) return undefined;
+
+      setIsPending(true);
+      setError(null);
+
+      try {
+        return await stigmer.agentShare.apply({
+          // Identity: the existing share's org/slug when editing (a
+          // manifest-created share may carry a non-default slug — apply
+          // with the agent's slug would create a SECOND share), the
+          // agent's when creating (the server's own D2 default, made
+          // explicit).
+          org: current?.metadata?.org || agentOrg,
+          slug: current?.metadata?.slug || agentSlug,
+          name: current?.metadata?.name || agentName || agentSlug,
+          agentRef: { org: agentOrg, slug: agentSlug },
+          enabled: draft.enabled,
+          // Written as the explicit enum value, never left unspecified —
+          // a share persisted as "public" can't be silently downgraded
+          // by tooling that relies on the unspecified-means-public rule.
+          audience: sharingAudienceToProto(draft.audience),
+          allowedOrigins: [...draft.allowedOrigins],
+          messages: {
+            rateLimited: draft.messages.rateLimited,
+            unavailable: draft.messages.unavailable,
+            conversationEnded: draft.messages.conversationEnded,
+          },
+          environmentRefs: draft.environmentRefs.map((ref) => ({
+            org: ref.org,
+            slug: ref.slug,
+          })),
+        });
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [agentOrg, agentSlug, agentName, stigmer],
+  );
+
+  return { save, isPending, error };
+}