@stigmer/react 3.1.8 → 3.1.9

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

@@ -12,7 +12,7 @@ function createMockStigmer(overrides: {
   getSharedProfileForMember?: (...args: unknown[]) => Promise<unknown>;
 } = {}) {
   return {
-    agent: {
+    agentShare: {
       getSharedProfile:
         overrides.getSharedProfile ?? vi.fn().mockResolvedValue(null),
       getSharedProfileForMember:

package/src/sharing/index.ts

@@ -5,17 +5,19 @@ export type {
 } 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,
-  useUpdateAgentSharing,
-} from "./useUpdateAgentSharing.js";
-export { useRotateShareLink } from "./useRotateShareLink.js";
-export type { UseRotateShareLinkReturn } from "./useRotateShareLink.js";
+  useSaveAgentShare,
+} from "./useSaveAgentShare.js";
 export type {
-  AgentSharingDraft,
+  AgentShareDraft,
   SharingAudience,
-  UseUpdateAgentSharingReturn,
-} from "./useUpdateAgentSharing.js";
+  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";

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

@@ -2,19 +2,19 @@
 
 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 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 agent's share-link token via the `rotateShareLink` RPC.
-   * Resolves with the updated agent, whose `status.shareLinkToken`
+   * 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<Agent | undefined>;
+  readonly rotateShareLink: () => Promise<AgentShare | undefined>;
   /** `true` while the RPC is in flight. */
   readonly isPending: boolean;
   /** The last error from the RPC, or `null`. */
@@ -22,47 +22,52 @@ export interface UseRotateShareLinkReturn {
 }
 
 /**
- * Behavior hook that rotates an agent's share-link token.
+ * Behavior hook that rotates a share's 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.
+ * 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 agent — adopt the returned
- * agent (or refetch) so the UI shows the new tokened link, matching the
- * {@link useUpdateAgentSharing} convention.
+ * 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 `agentId` to produce a stable no-op (useful while the
- * agent is still loading).
+ * 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(agent.metadata.id);
+ * const { rotateShareLink, isPending } = useRotateShareLink(
+ *   share?.metadata?.id ?? null,
+ * );
  *
  * const updated = await rotateShareLink();
  * // updated.status.shareLinkToken is the new token
  * ```
  */
 export function useRotateShareLink(
-  agentId: string | null,
+  shareId: 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;
+  const rotateShareLink = useCallback(async (): Promise<
+    AgentShare | undefined
+  > => {
+    if (!shareId) return undefined;
 
     setIsPending(true);
     setError(null);
 
     try {
-      return await stigmer.agent.rotateShareLink(
-        create(RotateShareLinkInputSchema, { resourceId: agentId }),
+      return await stigmer.agentShare.rotateShareLink(
+        create(RotateShareLinkInputSchema, { resourceId: shareId }),
       );
     } catch (err) {
       setError(toError(err));
@@ -70,7 +75,7 @@ export function useRotateShareLink(
     } finally {
       setIsPending(false);
     }
-  }, [agentId, stigmer]);
+  }, [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 };
+}

package/src/sharing/useShareAgent.tsx

@@ -54,10 +54,11 @@ export interface UseShareAgentReturn {
  * 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.
+ * AgentShare create/apply handlers enforce on the referenced agent, 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

package/src/sharing/useShareToolReadiness.ts

@@ -1,106 +1,106 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, 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";
+import type { AgentShareDraft } from "./useSaveAgentShare.js";
 
 /**
- * Readiness of a shared agent's tool credentials for visitor (and
- * teammate) executions.
+ * Readiness of a share's tool credentials for visitor executions.
  *
- * - `na` — nothing to check: the agent uses no MCP tools, the check is
- *   disabled, or the deployment cannot serve guest chat (local mode).
+ * - `na` — nothing to check: the agent uses no MCP tools, sharing is
+ *   off, the audience is org (bindings are public-audience only), or
+ *   the deployment cannot serve guest chat (local mode).
+ * - `needs-credentials` — the agent uses MCP tools but the share has no
+ *   environments bound: visitors' tool calls will fail until the owner
+ *   binds credentials.
  * - `checking` — lookups in flight.
- * - `ready` — every environment bound to the agent's default instance is
- *   shared with the organization.
+ * - `ready` — every environment bound to the share 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: "needs-credentials" }
   | { readonly status: "checking" }
   | { readonly status: "ready" }
   | { readonly status: "blocked"; readonly privateEnvironments: readonly string[] };
 
 const NA: ShareToolReadiness = { status: "na" };
+const NEEDS_CREDENTIALS: ShareToolReadiness = { status: "needs-credentials" };
 
 /**
  * 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`).
+ * will work for visitors — i.e. whether the share binds environments
+ * (`environment_refs`) and each one is 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.
+ * Guest executions receive credentials exclusively from the share's own
+ * `environment_refs`, resolved through the org-shared environment seam
+ * (decision 011 — the agent's default instance stays pristine and is
+ * never consulted). So a tool-using agent with an empty binding list is
+ * *guaranteed* broken for visitors, and this hook says so explicitly
+ * (`needs-credentials`) instead of staying silent — the gap that made
+ * session 12's misconfiguration invisible until a visitor's first
+ * message failed.
  *
- * 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.
+ * The check runs only when the share is enabled with a public audience
+ * (org-audience shares reject bindings at the proto boundary), 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,
+  draft: AgentShareDraft,
 ): ShareToolReadiness {
   const stigmer = useStigmer();
   const deploymentMode = useDeploymentMode();
-  const [readiness, setReadiness] = useState<ShareToolReadiness>(NA);
+  const [checked, setChecked] = useState<ShareToolReadiness>(NA);
 
-  const agentId = agent.metadata?.id ?? "";
   const hasMcpTools = (agent.spec?.mcpServerUsages?.length ?? 0) > 0;
-  const defaultInstanceId = agent.status?.defaultInstanceId ?? "";
-
-  const shouldCheck =
-    enabled &&
+  const applicable =
+    draft.enabled &&
+    draft.audience === "public" &&
     deploymentMode === "cloud" &&
-    hasMcpTools &&
-    defaultInstanceId !== "";
+    hasMcpTools;
+
+  // Stable key for the effect: the visibility lookups depend only on
+  // which environments are bound, not on the array's identity.
+  const refsKey = useMemo(
+    () => draft.environmentRefs.map((ref) => `${ref.org}/${ref.slug}`).join(","),
+    [draft.environmentRefs],
+  );
+
+  const shouldFetch = applicable && refsKey !== "";
 
   useEffect(() => {
-    if (!shouldCheck) {
-      setReadiness(NA);
+    if (!shouldFetch) {
+      setChecked(NA);
       return;
     }
 
     let cancelled = false;
-    setReadiness({ status: "checking" });
+    setChecked({ 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) {
+      for (const ref of refsKey.split(",")) {
+        const [org, slug] = ref.split("/");
         try {
-          const env = await stigmer.environment.getByReference({
-            org: ref.org,
-            slug: ref.slug,
-          });
+          const env = await stigmer.environment.getByReference({ org, slug });
           if (
             env.metadata?.visibility !== ApiResourceVisibility.visibility_org
           ) {
-            privateRefs.push(`${ref.org}/${ref.slug}`);
+            privateRefs.push(ref);
           }
         } catch {
-          // Unreadable ref (deleted, foreign): the runtime will skip it
-          // for visitors too — surface it as blocking.
-          privateRefs.push(`${ref.org}/${ref.slug}`);
+          // Unreadable ref (deleted, foreign): the runtime's merge will
+          // skip it for visitors too — surface it as blocking.
+          privateRefs.push(ref);
         }
       }
 
@@ -109,21 +109,23 @@ export function useShareToolReadiness(
         : { status: "blocked", privateEnvironments: privateRefs };
     })().then(
       (result) => {
-        if (!cancelled) setReadiness(result);
+        if (!cancelled) setChecked(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);
+        if (!cancelled) setChecked(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]);
+  }, [shouldFetch, refsKey, stigmer]);
 
-  return readiness;
+  if (!applicable) return NA;
+  // Zero bindings needs no lookup: a tool-using agent without bound
+  // credentials is broken for visitors by construction.
+  if (refsKey === "") return NEEDS_CREDENTIALS;
+  return checked;
 }

package/src/sharing/useSharedAgentProfile.ts

@@ -4,11 +4,11 @@ import { create } from "@bufbuild/protobuf";
 import {
   GetSharedProfileRequestSchema,
   type SharedAgentProfile,
-} from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
+} from "@stigmer/protos/ai/stigmer/agentic/agentshare/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";
+import type { SharingAudience } from "./useSaveAgentShare.js";
 
 /** Options for {@link useSharedAgentProfile}. */
 export interface UseSharedAgentProfileOptions {
@@ -53,8 +53,9 @@ export interface UseSharedAgentProfileReturn {
 }
 
 /**
- * Data hook that fetches a shared agent's public profile by
- * organization and agent slug.
+ * Data hook that fetches a shared agent's public profile by the org and
+ * slug from the share URL (the share's slug — it defaults to the
+ * agent's, so existing links resolve unchanged).
  *
  * By default this hook calls the `getSharedProfile` endpoint, which is
  * **public** — it requires no authentication. The server returns a
@@ -110,8 +111,8 @@ export function useSharedAgentProfile(
             // 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(
+              ? await stigmer.agentShare.getSharedProfileForMember({ org, slug })
+              : await stigmer.agentShare.getSharedProfile(
                   create(GetSharedProfileRequestSchema, { org, slug, linkToken }),
                 );
           } catch (err) {