@stigmer/react 3.1.7 → 3.1.9

package/sharing/useShareAgent.d.ts

@@ -0,0 +1,69 @@
+import { type ReactNode } from "react";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { DetailAction } from "../resource-detail/types.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
+ * 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
+ * const share = useShareAgent({
+ *   agent,
+ *   buildShareUrl: (org, slug) => `${appOrigin}/chat/${org}/${slug}`,
+ *   onSharingChanged: refetch,
+ * });
+ * // ...
+ * <ResourceDetailShell actions={share.action ? [...actions, share.action] : actions} ... />
+ * {share.dialog}
+ * ```
+ */
+export declare function useShareAgent({ agent, buildShareUrl, onSharingChanged, label, }: UseShareAgentArgs): UseShareAgentReturn;
+//# sourceMappingURL=useShareAgent.d.ts.map

package/sharing/useShareAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useShareAgent.d.ts","sourceRoot":"","sources":["../../src/sharing/useShareAgent.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oDAAoD,CAAC;AAEhF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/D;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IACrC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,EAC5B,KAAK,EACL,aAAa,EACb,gBAAgB,EAChB,KAAe,GAChB,EAAE,iBAAiB,GAAG,mBAAmB,CA2BzC"}

package/sharing/useShareAgent.js

@@ -0,0 +1,42 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
+import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+import { ShareAgentDialog } from "./ShareAgentDialog.js";
+/**
+ * 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
+ * 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
+ * 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", }) {
+    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 = agent && canEdit
+        ? { id: "share", label, group: "sharing", onAction: open }
+        : null;
+    const dialog = agent ? (_jsx(ShareAgentDialog, { open: isOpen, onOpenChange: setIsOpen, agent: agent, buildShareUrl: buildShareUrl, onSharingChanged: onSharingChanged })) : null;
+    return { action, dialog, open, isOpen };
+}
+//# sourceMappingURL=useShareAgent.js.map

package/sharing/useShareAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useShareAgent.js","sourceRoot":"","sources":["../../src/sharing/useShareAgent.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAkB,MAAM,OAAO,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AA2CzD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,aAAa,CAAC,EAC5B,KAAK,EACL,aAAa,EACb,gBAAgB,EAChB,KAAK,GAAG,OAAO,GACG;IAClB,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE5C,MAAM,OAAO,GAAG,KAAK,EAAE,QAAQ,EAAE,EAAE,IAAI,IAAI,CAAC;IAC5C,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,kBAAkB,CAC7C,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,EAC/C,UAAU,CACX,CAAC;IAEF,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAEpD,MAAM,MAAM,GACV,KAAK,IAAI,OAAO;QACd,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC1D,CAAC,CAAC,IAAI,CAAC;IAEX,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CACrB,KAAC,gBAAgB,IACf,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,SAAS,EACvB,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,aAAa,EAC5B,gBAAgB,EAAE,gBAAgB,GAClC,CACH,CAAC,CAAC,CAAC,IAAI,CAAC;IAET,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1C,CAAC"}

package/sharing/useShareToolReadiness.d.ts

@@ -0,0 +1,52 @@
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { AgentShareDraft } from "./useSaveAgentShare.js";
+/**
+ * Readiness of a share's tool credentials for visitor executions.
+ *
+ * - `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 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[];
+};
+/**
+ * Data hook that checks whether a tool-using shared agent's credentials
+ * will work for visitors — i.e. whether the share binds environments
+ * (`environment_refs`) and each one is shared with the organization
+ * (`visibility_org`).
+ *
+ * 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.
+ *
+ * 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 declare function useShareToolReadiness(agent: Agent, draft: AgentShareDraft): ShareToolReadiness;
+//# sourceMappingURL=useShareToolReadiness.d.ts.map

package/sharing/useShareToolReadiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useShareToolReadiness.d.ts","sourceRoot":"","sources":["../../src/sharing/useShareToolReadiness.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oDAAoD,CAAC;AAIhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAKpF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,eAAe,GACrB,kBAAkB,CAwEpB"}

package/sharing/useShareToolReadiness.js

@@ -0,0 +1,89 @@
+"use client";
+import { useEffect, useMemo, useState } from "react";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { useStigmer } from "../hooks.js";
+import { useDeploymentMode } from "../deployment-mode.js";
+const NA = { status: "na" };
+const NEEDS_CREDENTIALS = { status: "needs-credentials" };
+/**
+ * Data hook that checks whether a tool-using shared agent's credentials
+ * will work for visitors — i.e. whether the share binds environments
+ * (`environment_refs`) and each one is shared with the organization
+ * (`visibility_org`).
+ *
+ * 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.
+ *
+ * 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, draft) {
+    const stigmer = useStigmer();
+    const deploymentMode = useDeploymentMode();
+    const [checked, setChecked] = useState(NA);
+    const hasMcpTools = (agent.spec?.mcpServerUsages?.length ?? 0) > 0;
+    const applicable = draft.enabled &&
+        draft.audience === "public" &&
+        deploymentMode === "cloud" &&
+        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 (!shouldFetch) {
+            setChecked(NA);
+            return;
+        }
+        let cancelled = false;
+        setChecked({ status: "checking" });
+        (async () => {
+            const privateRefs = [];
+            for (const ref of refsKey.split(",")) {
+                const [org, slug] = ref.split("/");
+                try {
+                    const env = await stigmer.environment.getByReference({ org, slug });
+                    if (env.metadata?.visibility !== ApiResourceVisibility.visibility_org) {
+                        privateRefs.push(ref);
+                    }
+                }
+                catch {
+                    // Unreadable ref (deleted, foreign): the runtime's merge will
+                    // skip it for visitors too — surface it as blocking.
+                    privateRefs.push(ref);
+                }
+            }
+            return privateRefs.length === 0
+                ? { status: "ready" }
+                : { status: "blocked", privateEnvironments: privateRefs };
+        })().then((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)
+                setChecked(NA);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [shouldFetch, refsKey, stigmer]);
+    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;
+}
+//# sourceMappingURL=useShareToolReadiness.js.map

package/sharing/useShareToolReadiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useShareToolReadiness.js","sourceRoot":"","sources":["../../src/sharing/useShareToolReadiness.ts"],"names":[],"mappings":"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"}

package/sharing/useSharedAgentProfile.d.ts

@@ -0,0 +1,85 @@
+import { type SharedAgentProfile } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/io_pb";
+import type { SharingAudience } from "./useSaveAgentShare.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 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
+ * 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 declare function useSharedAgentProfile(org: string | null, slug: string | null, options?: UseSharedAgentProfileOptions): UseSharedAgentProfileReturn;
+//# sourceMappingURL=useSharedAgentProfile.d.ts.map

package/sharing/useSharedAgentProfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSharedAgentProfile.d.ts","sourceRoot":"","sources":["../../src/sharing/useSharedAgentProfile.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wDAAwD,CAAC;AAIhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAEpC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qDAAqD;AACrD,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC5C,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,OAAO,CAAC,EAAE,4BAA4B,GACrC,2BAA2B,CA+B7B"}

package/sharing/useSharedAgentProfile.js

@@ -0,0 +1,73 @@
+"use client";
+import { create } from "@bufbuild/protobuf";
+import { GetSharedProfileRequestSchema, } 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";
+/**
+ * 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
+ * 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, slug, options) {
+    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.agentShare.getSharedProfileForMember({ org, slug })
+                    : await stigmer.agentShare.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);
+    return { profile, isLoading, isRefetching, error, refetch };
+}
+//# sourceMappingURL=useSharedAgentProfile.js.map

package/sharing/useSharedAgentProfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSharedAgentProfile.js","sourceRoot":"","sources":["../../src/sharing/useSharedAgentProfile.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EACL,6BAA6B,GAE9B,MAAM,wDAAwD,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AA6CnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAkB,EAClB,IAAmB,EACnB,OAAsC;IAEtC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,QAAQ,CAAC;IAC/C,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;IAE3C,MAAM,OAAO,GACX,GAAG,IAAI,IAAI;QACT,CAAC,CAAC,KAAK,IAAI,EAAE;YACT,IAAI,CAAC;gBACH,gEAAgE;gBAChE,8DAA8D;gBAC9D,6DAA6D;gBAC7D,OAAO,QAAQ,KAAK,KAAK;oBACvB,CAAC,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,yBAAyB,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;oBACnE,CAAC,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,gBAAgB,CACvC,MAAM,CAAC,6BAA6B,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAChE,CAAC;YACR,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,UAAU,CAAC,GAAG,CAAC;oBAAE,OAAO,IAAI,CAAC;gBACjC,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QACH,CAAC,CAAC,IAAI,CAAC;IAEX,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,QAAQ,CACzE,OAAO,EACP,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,EACzC,IAAiC,CAClC,CAAC;IAEF,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC9D,CAAC"}

package/src/agent/AgentDetailView.tsx

@@ -17,6 +17,7 @@ import { agentToInput } from "./internal/agentToInput.js";
 import { ErrorMessage } from "../error/ErrorMessage.js";
 import { VisibilityBadge } from "../library/VisibilitySelector.js";
 import { useManageAccess } from "../access/useManageAccess.js";
+import { useShareAgent } from "../sharing/useShareAgent.js";
 import { ResourceDetailShell } from "../resource-detail/ResourceDetailShell.js";
 import { Section } from "../resource-detail/Section.js";
 import { useDetailTabs } from "../resource-detail/useDetailTabs.js";
@@ -127,6 +128,14 @@ export interface AgentDetailViewProps {
    * Opens the create instance dialog.
    */
   readonly onCreateInstanceClick?: () => void;
+  /**
+   * Builds the absolute public chat URL shown in the Share dialog.
+   * 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>` path.
+   */
+  readonly buildShareUrl?: (org: string, slug: string) => string;
   /**
    * Called when the user clicks an instance row in the Instances tab.
    * Typically opens an instance detail panel.
@@ -204,6 +213,7 @@ export function AgentDetailView({
   defaultTab,
   editable = false,
   onResourceUpdated,
+  buildShareUrl,
   onCreateInstanceClick,
   onInstanceClick,
   onInstanceStartSessionClick,
@@ -306,6 +316,15 @@ export function AgentDetailView({
       : undefined,
   });
 
+  // Share — the sibling consent to Manage access: visibility governs who
+  // can read the blueprint; sharing governs who can chat with the running
+  // agent (billed to the owning org). Same null-until-ready contract.
+  const share = useShareAgent({
+    agent,
+    buildShareUrl,
+    onSharingChanged: refetch,
+  });
+
   if (isLoading) return <LoadingSkeleton className={className} />;
   if (error)
     return <ErrorMessage error={error} retry={refetch} className={className} />;
@@ -344,9 +363,14 @@ export function AgentDetailView({
     <VisibilityBadge visibility={meta.visibility} />
   ) : undefined;
 
-  const mergedActions = access.action
-    ? [...(actions ?? []), access.action]
-    : actions;
+  // Share precedes Manage access within the "sharing" group.
+  const injectedActions = [share.action, access.action].filter(
+    (a): a is NonNullable<typeof a> => a != null,
+  );
+  const mergedActions =
+    injectedActions.length > 0
+      ? [...(actions ?? []), ...injectedActions]
+      : actions;
 
   let tabContent: React.ReactNode;
   if (activeAdditionalTab) {
@@ -402,6 +426,7 @@ export function AgentDetailView({
         {tabContent}
       </ResourceDetailShell>
       {access.dialog}
+      {share.dialog}
     </>
   );
 }

package/src/environment/EnvironmentListPanel.tsx

@@ -4,8 +4,11 @@ import { useCallback, useMemo, useState } from "react";
 import { cn } from "@stigmer/theme";
 import { getUserMessage } from "@stigmer/sdk";
 import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ResourceVisibilityControl } from "../library/ResourceVisibilityControl.js";
 import { useEnvironmentList } from "./useEnvironmentList.js";
 import { EnvironmentVariableEditor } from "./EnvironmentVariableEditor.js";
+import { isShareRestrictedEnvironment } from "./shareRestriction.js";
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -175,6 +178,7 @@ export function EnvironmentListPanel({
             isExpanded={isExpanded}
             onToggle={() => handleToggle(env)}
             readOnly={readOnly}
+            onVisibilityChanged={refetch}
           />
         );
       })}
@@ -191,11 +195,13 @@ function EnvironmentCard({
   isExpanded,
   onToggle,
   readOnly,
+  onVisibilityChanged,
 }: {
   environment: Environment;
   isExpanded: boolean;
   onToggle: () => void;
   readOnly: boolean;
+  onVisibilityChanged: () => void;
 }) {
   const name =
     environment.metadata?.name || environment.metadata?.slug || "Unnamed";
@@ -203,6 +209,12 @@ function EnvironmentCard({
   const variableCount = Object.keys(environment.spec?.data ?? {}).length;
   const environmentId = environment.metadata?.id ?? "";
 
+  // Personal and OAuth-managed environments are never org-shareable
+  // (the backend rejects the transition) — offering the control would
+  // be an error trap, so it is structurally absent for them.
+  const showVisibilityControl =
+    !readOnly && environmentId !== "" && !isShareRestrictedEnvironment(environment);
+
   return (
     <div
       role="listitem"
@@ -213,30 +225,47 @@ function EnvironmentCard({
           : "border-border-muted hover:border-border",
       )}
     >
-      {/* Header — always visible */}
-      <button
-        type="button"
-        onClick={onToggle}
-        aria-expanded={isExpanded}
-        className="flex w-full items-center gap-3 px-3 py-2.5 text-left"
-      >
-        <ChevronIcon expanded={isExpanded} />
+      {/* Header — always visible. The expand toggle and the visibility
+          control are sibling interactive elements (nesting the selector
+          inside the toggle button would be invalid markup). */}
+      <div className="flex w-full items-center gap-3 px-3 py-2.5">
+        <button
+          type="button"
+          onClick={onToggle}
+          aria-expanded={isExpanded}
+          className="flex min-w-0 flex-1 items-center gap-3 text-left"
+        >
+          <ChevronIcon expanded={isExpanded} />
 
-        <div className="min-w-0 flex-1">
-          <span className="block truncate text-sm font-medium text-foreground">
-            {name}
-          </span>
-          {description && (
-            <span className="block truncate text-xs text-muted-foreground">
-              {description}
+          <div className="min-w-0 flex-1">
+            <span className="block truncate text-sm font-medium text-foreground">
+              {name}
             </span>
-          )}
-        </div>
+            {description && (
+              <span className="block truncate text-xs text-muted-foreground">
+                {description}
+              </span>
+            )}
+          </div>
+        </button>
+
+        {showVisibilityControl && (
+          <ResourceVisibilityControl
+            kind="environment"
+            resourceId={environmentId}
+            visibility={
+              environment.metadata?.visibility ??
+              ApiResourceVisibility.visibility_private
+            }
+            onChanged={onVisibilityChanged}
+            className="shrink-0"
+          />
+        )}
 
         <span className="shrink-0 text-xs text-muted-foreground">
           {variableCount} {variableCount === 1 ? "variable" : "variables"}
         </span>
-      </button>
+      </div>
 
       {/* Expanded content — variable editor */}
       {isExpanded && environmentId && (