@stigmer/react 3.1.7 → 3.1.8

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 {
+    agent: {
+      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/__tests__/useUpdateAgentSharing.test.tsx

@@ -0,0 +1,200 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { UpdateAgentSharingInput } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
+import { AgentSharingAudience } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { StigmerContext } from "../../context";
+import {
+  sharingAudienceFromProto,
+  useUpdateAgentSharing,
+  type AgentSharingDraft,
+} from "../useUpdateAgentSharing";
+
+function createMockStigmer(overrides: {
+  updateSharing?: (input: UpdateAgentSharingInput) => Promise<unknown>;
+} = {}) {
+  return {
+    agent: {
+      updateSharing:
+        overrides.updateSharing ?? vi.fn().mockResolvedValue({}),
+    },
+  } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client as never}>
+        {children}
+      </StigmerContext.Provider>
+    );
+  };
+}
+
+const FULL_DRAFT: AgentSharingDraft = {
+  enabled: true,
+  audience: "public",
+  allowedOrigins: ["https://example.com", "https://docs.example.com"],
+  messages: {
+    rateLimited: "Slow down, please.",
+    unavailable: "We're out of credits.",
+    conversationEnded: "This conversation has ended.",
+  },
+};
+
+describe("useUpdateAgentSharing", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("sends the complete sharing block — enabled, origins, and messages", async () => {
+    const updateSharing = vi.fn().mockResolvedValue({});
+    const client = createMockStigmer({ updateSharing });
+
+    const { result } = renderHook(() => useUpdateAgentSharing("agt_1"), {
+      wrapper: wrapper(client),
+    });
+
+    await act(() => result.current.updateSharing(FULL_DRAFT));
+
+    expect(updateSharing).toHaveBeenCalledTimes(1);
+    const input = updateSharing.mock.calls[0][0] as UpdateAgentSharingInput;
+    expect(input.resourceId).toBe("agt_1");
+    expect(input.sharing?.enabled).toBe(true);
+    expect(input.sharing?.allowedOrigins).toEqual([
+      "https://example.com",
+      "https://docs.example.com",
+    ]);
+    expect(input.sharing?.messages?.rateLimited).toBe("Slow down, please.");
+    expect(input.sharing?.messages?.unavailable).toBe("We're out of credits.");
+    expect(input.sharing?.messages?.conversationEnded).toBe(
+      "This conversation has ended.",
+    );
+  });
+
+  it("disabling still carries origins, messages, and audience (toggle never clobbers config)", async () => {
+    const updateSharing = vi.fn().mockResolvedValue({});
+    const client = createMockStigmer({ updateSharing });
+
+    const { result } = renderHook(() => useUpdateAgentSharing("agt_1"), {
+      wrapper: wrapper(client),
+    });
+
+    await act(() =>
+      result.current.updateSharing({
+        ...FULL_DRAFT,
+        enabled: false,
+        audience: "org",
+      }),
+    );
+
+    const input = updateSharing.mock.calls[0][0] as UpdateAgentSharingInput;
+    expect(input.sharing?.enabled).toBe(false);
+    // The RPC replaces spec.sharing wholesale — a disable that dropped
+    // these fields would silently erase the owner's configuration (an
+    // audience drop would silently revert an org-only agent to public).
+    expect(input.sharing?.allowedOrigins).toEqual(FULL_DRAFT.allowedOrigins);
+    expect(input.sharing?.messages?.rateLimited).toBe(
+      FULL_DRAFT.messages.rateLimited,
+    );
+    expect(input.sharing?.audience).toBe(AgentSharingAudience.org);
+  });
+
+  it("maps the audience union to the proto enum, writing public explicitly", async () => {
+    const updateSharing = vi.fn().mockResolvedValue({});
+    const client = createMockStigmer({ updateSharing });
+
+    const { result } = renderHook(() => useUpdateAgentSharing("agt_1"), {
+      wrapper: wrapper(client),
+    });
+
+    await act(() => result.current.updateSharing(FULL_DRAFT));
+    await act(() =>
+      result.current.updateSharing({ ...FULL_DRAFT, audience: "org" }),
+    );
+
+    const first = updateSharing.mock.calls[0][0] as UpdateAgentSharingInput;
+    const second = updateSharing.mock.calls[1][0] as UpdateAgentSharingInput;
+    // "public" persists as the explicit enum value, never unspecified —
+    // a console-managed share can't be downgraded by a later manifest
+    // that relies on the unspecified-means-public default.
+    expect(first.sharing?.audience).toBe(AgentSharingAudience.public);
+    expect(second.sharing?.audience).toBe(AgentSharingAudience.org);
+  });
+
+  it("is a stable no-op when agentId is null", async () => {
+    const updateSharing = vi.fn();
+    const client = createMockStigmer({ updateSharing });
+
+    const { result } = renderHook(() => useUpdateAgentSharing(null), {
+      wrapper: wrapper(client),
+    });
+
+    const returned = await act(() => result.current.updateSharing(FULL_DRAFT));
+    expect(returned).toBeUndefined();
+    expect(updateSharing).not.toHaveBeenCalled();
+  });
+
+  it("exposes isPending during the request", async () => {
+    let resolveRpc: (v: unknown) => void = () => {};
+    const updateSharing = vi.fn().mockReturnValue(
+      new Promise((resolve) => {
+        resolveRpc = resolve;
+      }),
+    );
+    const client = createMockStigmer({ updateSharing });
+
+    const { result } = renderHook(() => useUpdateAgentSharing("agt_1"), {
+      wrapper: wrapper(client),
+    });
+
+    let pending: Promise<unknown>;
+    act(() => {
+      pending = result.current.updateSharing(FULL_DRAFT);
+    });
+    expect(result.current.isPending).toBe(true);
+
+    await act(async () => {
+      resolveRpc({});
+      await pending;
+    });
+    expect(result.current.isPending).toBe(false);
+  });
+
+  it("captures and rethrows RPC errors", async () => {
+    const failure = new Error("permission denied");
+    const updateSharing = vi.fn().mockRejectedValue(failure);
+    const client = createMockStigmer({ updateSharing });
+
+    const { result } = renderHook(() => useUpdateAgentSharing("agt_1"), {
+      wrapper: wrapper(client),
+    });
+
+    let caught: unknown;
+    await act(async () => {
+      try {
+        await result.current.updateSharing(FULL_DRAFT);
+      } catch (err) {
+        caught = err;
+      }
+    });
+
+    expect(caught).toBe(failure);
+    await waitFor(() => expect(result.current.error).toBe(failure));
+    expect(result.current.isPending).toBe(false);
+  });
+});
+
+describe("sharingAudienceFromProto", () => {
+  it("maps unspecified to public (pre-audience shares keep their behavior)", () => {
+    expect(sharingAudienceFromProto(undefined)).toBe("public");
+    expect(sharingAudienceFromProto(AgentSharingAudience.unspecified)).toBe(
+      "public",
+    );
+  });
+
+  it("maps the explicit values", () => {
+    expect(sharingAudienceFromProto(AgentSharingAudience.public)).toBe("public");
+    expect(sharingAudienceFromProto(AgentSharingAudience.org)).toBe("org");
+  });
+});

package/src/sharing/index.ts

@@ -0,0 +1,30 @@
+export { useSharedAgentProfile } from "./useSharedAgentProfile.js";
+export type {
+  UseSharedAgentProfileOptions,
+  UseSharedAgentProfileReturn,
+} from "./useSharedAgentProfile.js";
+export { SharedAgentChat } from "./SharedAgentChat.js";
+export type { SharedAgentChatProps } from "./SharedAgentChat.js";
+export {
+  sharingAudienceFromProto,
+  useUpdateAgentSharing,
+} from "./useUpdateAgentSharing.js";
+export { useRotateShareLink } from "./useRotateShareLink.js";
+export type { UseRotateShareLinkReturn } from "./useRotateShareLink.js";
+export type {
+  AgentSharingDraft,
+  SharingAudience,
+  UseUpdateAgentSharingReturn,
+} from "./useUpdateAgentSharing.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/useRotateShareLink.ts

@@ -0,0 +1,76 @@
+"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 { RotateShareLinkInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useRotateShareLink}. */
+export interface UseRotateShareLinkReturn {
+  /**
+   * Rotate the agent's share-link token via the `rotateShareLink` RPC.
+   * Resolves with the updated agent, whose `status.shareLinkToken`
+   * carries the new token for building the fresh share URL.
+   */
+  readonly rotateShareLink: () => 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 rotates an agent's share-link token.
+ *
+ * Wraps the `stigmer.agent.rotateShareLink()` RPC (authorized by
+ * `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), so it is never part of a sharing draft and survives
+ * manifest applies.
+ *
+ * The hook is stateless with respect to the agent — adopt the returned
+ * agent (or refetch) so the UI shows the new tokened link, matching the
+ * {@link useUpdateAgentSharing} convention.
+ *
+ * Pass `null` for `agentId` to produce a stable no-op (useful while the
+ * agent is still loading).
+ *
+ * @example
+ * ```tsx
+ * const { rotateShareLink, isPending } = useRotateShareLink(agent.metadata.id);
+ *
+ * const updated = await rotateShareLink();
+ * // updated.status.shareLinkToken is the new token
+ * ```
+ */
+export function useRotateShareLink(
+  agentId: string | null,
+): UseRotateShareLinkReturn {
+  const stigmer = useStigmer();
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const rotateShareLink = useCallback(async (): Promise<Agent | undefined> => {
+    if (!agentId) return undefined;
+
+    setIsPending(true);
+    setError(null);
+
+    try {
+      return await stigmer.agent.rotateShareLink(
+        create(RotateShareLinkInputSchema, { resourceId: agentId }),
+      );
+    } catch (err) {
+      setError(toError(err));
+      throw err;
+    } finally {
+      setIsPending(false);
+    }
+  }, [agentId, stigmer]);
+
+  return { rotateShareLink, isPending, error };
+}

package/src/sharing/useShareAgent.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import { useCallback, useState, type ReactNode } from "react";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+import type { DetailAction } from "../resource-detail/types.js";
+import { ShareAgentDialog } from "./ShareAgentDialog.js";
+
+/** Arguments for {@link useShareAgent}. */
+export interface UseShareAgentArgs {
+  /**
+   * The agent whose sharing is managed, or `null` while it is still
+   * loading. When `null`, {@link UseShareAgentReturn.action} is `null`
+   * and the dialog renders nothing — safe to call before the resource
+   * is ready.
+   */
+  readonly agent: Agent | null;
+  /**
+   * Builds the absolute public chat URL for the shared agent. The host
+   * application owns URL construction (its configured public origin may
+   * differ from the rendering origin — e.g. the desktop app). When
+   * omitted, the dialog falls back to the relative `/chat/<org>/<slug>`.
+   */
+  readonly buildShareUrl?: (org: string, slug: string) => string;
+  /**
+   * Called after any sharing change is persisted. Hosts typically pass
+   * the agent data hook's `refetch`.
+   */
+  readonly onSharingChanged?: () => void;
+  /** Menu-item label. @default "Share" */
+  readonly label?: string;
+}
+
+/** Return value of {@link useShareAgent}. */
+export interface UseShareAgentReturn {
+  /**
+   * A ready-to-spread {@link DetailAction} for a kebab/overflow menu, or
+   * `null` when the agent is unavailable or the user lacks `can_edit`.
+   * Lives in the `"sharing"` group, beside "Manage access".
+   */
+  readonly action: DetailAction | null;
+  /** The {@link ShareAgentDialog} node — render it once in the host tree. */
+  readonly dialog: ReactNode;
+  /** Imperatively open the dialog. */
+  readonly open: () => void;
+  /** Whether the dialog is currently open. */
+  readonly isOpen: boolean;
+}
+
+/**
+ * Wires the Share dialog to a kebab/overflow menu — the same trigger
+ * shape as {@link useManageAccess}, its conceptual sibling: Manage access
+ * governs who can *read* the blueprint; Share governs who can *chat* with
+ * the running agent (billed to the owning org).
+ *
+ * Owns the open-state and the `can_edit` gate — the same permission the
+ * `updateSharing` RPC enforces, so the action never appears to a user
+ * whose changes would be rejected. Returns a `null` action while the
+ * agent is loading or the user cannot edit, so the host can
+ * unconditionally fold `action` into its actions array.
+ *
+ * @example
+ * ```tsx
+ * const share = useShareAgent({
+ *   agent,
+ *   buildShareUrl: (org, slug) => `${appOrigin}/chat/${org}/${slug}`,
+ *   onSharingChanged: refetch,
+ * });
+ * // ...
+ * <ResourceDetailShell actions={share.action ? [...actions, share.action] : actions} ... />
+ * {share.dialog}
+ * ```
+ */
+export function useShareAgent({
+  agent,
+  buildShareUrl,
+  onSharingChanged,
+  label = "Share",
+}: UseShareAgentArgs): UseShareAgentReturn {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const agentId = agent?.metadata?.id ?? null;
+  const { allowed: canEdit } = useCheckPermission(
+    agentId ? { kind: "agent", id: agentId } : null,
+    "can_edit",
+  );
+
+  const open = useCallback(() => setIsOpen(true), []);
+
+  const action: DetailAction | null =
+    agent && canEdit
+      ? { id: "share", label, group: "sharing", onAction: open }
+      : null;
+
+  const dialog = agent ? (
+    <ShareAgentDialog
+      open={isOpen}
+      onOpenChange={setIsOpen}
+      agent={agent}
+      buildShareUrl={buildShareUrl}
+      onSharingChanged={onSharingChanged}
+    />
+  ) : null;
+
+  return { action, dialog, open, isOpen };
+}