@stigmer/react 3.1.12 → 3.1.14

package/src/sharing/__tests__/{useAgentShare.test.tsx → useAgentShares.test.tsx}

@@ -4,7 +4,7 @@ import type { ReactNode } from "react";
 import type { GetAgentSharesByAgentRequest } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/io_pb";
 import { StigmerContext } from "../../context";
 import { FetchCacheContext } from "../../internal/FetchCacheProvider";
-import { useAgentShare } from "../useAgentShare";
+import { useAgentShares } from "../useAgentShares";
 
 function createMockStigmer(overrides: {
   getByAgent?: (input: GetAgentSharesByAgentRequest) => Promise<unknown>;
@@ -30,105 +30,84 @@ function wrapper(client: unknown) {
   };
 }
 
-const AGENT = {
-  metadata: {
-    id: "agt_1",
-    org: "acme",
-    slug: "support-agent",
-    name: "Support Agent",
-  },
-} as never;
-
-function makeShare(slug: string, id = `ash_${slug}`) {
+function makeShare(org: string, slug: string, id = `ash_${org}_${slug}`) {
   return {
-    metadata: { id, org: "acme", slug },
+    metadata: { id, org, slug },
     spec: { enabled: true },
   };
 }
 
-describe("useAgentShare", () => {
+describe("useAgentShares", () => {
   beforeEach(() => {
     vi.restoreAllMocks();
   });
 
   it("loads the agent's shares by agent id", async () => {
-    const share = makeShare("support-agent");
+    const share = makeShare("acme", "support-agent");
     const getByAgent = vi
       .fn()
       .mockResolvedValue({ totalCount: 1, items: [share] });
     const client = createMockStigmer({ getByAgent });
 
-    const { result } = renderHook(() => useAgentShare(AGENT), {
+    const { result } = renderHook(() => useAgentShares("agt_1"), {
       wrapper: wrapper(client),
     });
 
     expect(result.current.isLoading).toBe(true);
     await waitFor(() => expect(result.current.isLoading).toBe(false));
 
-    expect(result.current.share).toBe(share);
+    expect(result.current.shares).toEqual([share]);
     expect(result.current.error).toBeNull();
     expect(getByAgent).toHaveBeenCalledWith(
       expect.objectContaining({ agentId: "agt_1" }),
     );
   });
 
-  it("resolves null (no share yet) when the agent has never been shared", async () => {
-    const client = createMockStigmer();
-
-    const { result } = renderHook(() => useAgentShare(AGENT), {
-      wrapper: wrapper(client),
-    });
-
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    // The no-share state is not an error: the first save creates the share.
-    expect(result.current.share).toBeNull();
-    expect(result.current.error).toBeNull();
-  });
-
-  it("picks the slug-matching share as canonical when several exist", async () => {
-    const canonical = makeShare("support-agent");
-    const renamed = makeShare("support-help-desk");
+  it("returns the FULL list — never collapses to a canonical share", async () => {
+    // An agent can carry N shares across N orgs (decision 011 D3 +
+    // decision 013): the owner's, a renamed sibling, another org's
+    // external channel. The management surface shows them all.
+    const owner = makeShare("acme", "support-agent");
+    const renamed = makeShare("acme", "support-help-desk");
+    const external = makeShare("consumer-org", "support-agent");
     const getByAgent = vi
       .fn()
-      .mockResolvedValue({ totalCount: 2, items: [renamed, canonical] });
+      .mockResolvedValue({ totalCount: 3, items: [owner, renamed, external] });
     const client = createMockStigmer({ getByAgent });
 
-    const { result } = renderHook(() => useAgentShare(AGENT), {
+    const { result } = renderHook(() => useAgentShares("agt_1"), {
       wrapper: wrapper(client),
     });
 
     await waitFor(() => expect(result.current.isLoading).toBe(false));
-    expect(result.current.share).toBe(canonical);
+    expect(result.current.shares).toEqual([owner, renamed, external]);
   });
 
-  it("falls back to the first share when none matches the agent slug", async () => {
-    // A manifest-created share with a custom slug is still manageable —
-    // preferring it over "no share" keeps the dialog editing the real row.
-    const renamed = makeShare("support-help-desk");
-    const getByAgent = vi
-      .fn()
-      .mockResolvedValue({ totalCount: 1, items: [renamed] });
-    const client = createMockStigmer({ getByAgent });
+  it("resolves empty (no shares yet) when the agent has never been shared", async () => {
+    const client = createMockStigmer();
 
-    const { result } = renderHook(() => useAgentShare(AGENT), {
+    const { result } = renderHook(() => useAgentShares("agt_1"), {
       wrapper: wrapper(client),
     });
 
     await waitFor(() => expect(result.current.isLoading).toBe(false));
-    expect(result.current.share).toBe(renamed);
+
+    // The no-share state is not an error: creating the first share is
+    // the empty state's call to action.
+    expect(result.current.shares).toEqual([]);
+    expect(result.current.error).toBeNull();
   });
 
-  it("skips fetching while the agent is null (stable no-op)", () => {
+  it("skips fetching while the agent id is empty (stable no-op)", () => {
     const getByAgent = vi.fn();
     const client = createMockStigmer({ getByAgent });
 
-    const { result } = renderHook(() => useAgentShare(null), {
+    const { result } = renderHook(() => useAgentShares(""), {
       wrapper: wrapper(client),
     });
 
     expect(result.current.isLoading).toBe(false);
-    expect(result.current.share).toBeNull();
+    expect(result.current.shares).toEqual([]);
     expect(getByAgent).not.toHaveBeenCalled();
   });
 
@@ -138,12 +117,29 @@ describe("useAgentShare", () => {
       .mockRejectedValue(new Error("backend unavailable"));
     const client = createMockStigmer({ getByAgent });
 
-    const { result } = renderHook(() => useAgentShare(AGENT), {
+    const { result } = renderHook(() => useAgentShares("agt_1"), {
       wrapper: wrapper(client),
     });
 
     await waitFor(() => expect(result.current.isLoading).toBe(false));
     expect(result.current.error).toBeTruthy();
-    expect(result.current.share).toBeNull();
+    expect(result.current.shares).toEqual([]);
+  });
+
+  it("refetches on demand", async () => {
+    const getByAgent = vi
+      .fn()
+      .mockResolvedValue({ totalCount: 0, items: [] });
+    const client = createMockStigmer({ getByAgent });
+
+    const { result } = renderHook(() => useAgentShares("agt_1"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(getByAgent).toHaveBeenCalledTimes(1);
+
+    result.current.refetch();
+    await waitFor(() => expect(getByAgent).toHaveBeenCalledTimes(2));
   });
 });

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

@@ -0,0 +1,190 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useCanCreateAgentShare } from "../useCanCreateAgentShare";
+
+function createMockStigmer(overrides: {
+  isAuthorized?: boolean;
+  checkMyPermission?: (...args: unknown[]) => Promise<unknown>;
+} = {}) {
+  return {
+    iamPolicy: {
+      checkMyPermission:
+        overrides.checkMyPermission ??
+        vi.fn().mockResolvedValue({
+          isAuthorized: overrides.isAuthorized ?? true,
+        }),
+    },
+  } 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>
+    );
+  };
+}
+
+function makeAgent(visibility?: ApiResourceVisibility) {
+  return {
+    metadata: {
+      id: "agt_1",
+      org: "acme",
+      slug: "support-agent",
+      name: "Support Agent",
+      ...(visibility !== undefined && { visibility }),
+    },
+    spec: {},
+  } as never;
+}
+
+function permissionCheckOf(client: unknown) {
+  return (
+    client as { iamPolicy: { checkMyPermission: ReturnType<typeof vi.fn> } }
+  ).iamPolicy.checkMyPermission;
+}
+
+describe("useCanCreateAgentShare", () => {
+  it("is not allowed while the agent is loading — no affordance flash", () => {
+    const client = createMockStigmer();
+    const { result } = renderHook(() => useCanCreateAgentShare(null, "acme"), {
+      wrapper: wrapper(client),
+    });
+
+    expect(result.current.allowed).toBe(false);
+    expect(permissionCheckOf(client)).not.toHaveBeenCalled();
+  });
+
+  describe("same-org (viewer org equals the agent's, or omitted)", () => {
+    it("requires agent can_edit — the server's Phase A create bar", async () => {
+      const client = createMockStigmer({ isAuthorized: true });
+      const { result } = renderHook(
+        () => useCanCreateAgentShare(makeAgent(), "acme"),
+        { wrapper: wrapper(client) },
+      );
+
+      await waitFor(() => expect(result.current.allowed).toBe(true));
+      expect(result.current.isCrossOrg).toBe(false);
+      expect(result.current.shareOrg).toBe("acme");
+
+      const input = permissionCheckOf(client).mock.calls[0][0] as {
+        resource?: { kind: string; id: string };
+        relation: string;
+      };
+      expect(input.relation).toBe("can_edit");
+      expect(input.resource?.kind).toBe("agent");
+      expect(input.resource?.id).toBe("agt_1");
+    });
+
+    it("defaults the share org to the agent's own when viewerOrg is omitted", async () => {
+      const client = createMockStigmer({ isAuthorized: true });
+      const { result } = renderHook(
+        () => useCanCreateAgentShare(makeAgent()),
+        { wrapper: wrapper(client) },
+      );
+
+      await waitFor(() => expect(result.current.allowed).toBe(true));
+      expect(result.current.shareOrg).toBe("acme");
+      expect(result.current.isCrossOrg).toBe(false);
+    });
+
+    it("refuses when the viewer lacks can_edit", async () => {
+      const client = createMockStigmer({ isAuthorized: false });
+      const { result } = renderHook(
+        () => useCanCreateAgentShare(makeAgent(), "acme"),
+        { wrapper: wrapper(client) },
+      );
+
+      await waitFor(() => expect(permissionCheckOf(client)).toHaveBeenCalled());
+      await waitFor(() => expect(result.current.allowed).toBe(false));
+    });
+  });
+
+  describe("cross-org (decision 013 D2's two-sided bar)", () => {
+    it("allows on a public agent when the viewer holds can_create_agent_share in their org", async () => {
+      const client = createMockStigmer({ isAuthorized: true });
+      const { result } = renderHook(
+        () =>
+          useCanCreateAgentShare(
+            makeAgent(ApiResourceVisibility.visibility_public),
+            "consumer-org",
+          ),
+        { wrapper: wrapper(client) },
+      );
+
+      await waitFor(() => expect(result.current.allowed).toBe(true));
+      expect(result.current.isCrossOrg).toBe(true);
+      expect(result.current.shareOrg).toBe("consumer-org");
+
+      const input = permissionCheckOf(client).mock.calls[0][0] as {
+        resource?: { kind: string; id: string };
+        relation: string;
+      };
+      expect(input.relation).toBe("can_create_agent_share");
+      expect(input.resource?.kind).toBe("organization");
+      // An Organization's id equals its slug (ApiResourceMetadata.id).
+      expect(input.resource?.id).toBe("consumer-org");
+    });
+
+    it("refuses on a non-public agent without any permission RPC — visibility IS the consent (D1)", () => {
+      const client = createMockStigmer();
+      const { result } = renderHook(
+        () => useCanCreateAgentShare(makeAgent(), "consumer-org"),
+        { wrapper: wrapper(client) },
+      );
+
+      expect(result.current.allowed).toBe(false);
+      expect(result.current.isCrossOrg).toBe(true);
+      expect(permissionCheckOf(client)).not.toHaveBeenCalled();
+    });
+
+    it("refuses when the viewer lacks can_create_agent_share", async () => {
+      const client = createMockStigmer({ isAuthorized: false });
+      const { result } = renderHook(
+        () =>
+          useCanCreateAgentShare(
+            makeAgent(ApiResourceVisibility.visibility_public),
+            "consumer-org",
+          ),
+        { wrapper: wrapper(client) },
+      );
+
+      await waitFor(() => expect(permissionCheckOf(client)).toHaveBeenCalled());
+      await waitFor(() => expect(result.current.allowed).toBe(false));
+    });
+
+    it("creates in the VIEWER's org even when the viewer could also edit the agent", async () => {
+      // The case that produced the old double-entry confusion: a user
+      // holding can_edit on a public agent while acting as another org.
+      // There is exactly one answer now — the share lands in the org
+      // they are acting as, on that org's bill.
+      const client = createMockStigmer({ isAuthorized: true });
+      const { result } = renderHook(
+        () =>
+          useCanCreateAgentShare(
+            makeAgent(ApiResourceVisibility.visibility_public),
+            "personal",
+          ),
+        { wrapper: wrapper(client) },
+      );
+
+      await waitFor(() => expect(result.current.allowed).toBe(true));
+      expect(result.current.shareOrg).toBe("personal");
+      expect(result.current.isCrossOrg).toBe(true);
+      // Only the org-side bar is consulted — the agent-side can_edit
+      // check belongs to the same-org branch alone.
+      const relations = permissionCheckOf(client).mock.calls.map(
+        (call: unknown[]) => (call[0] as { relation: string }).relation,
+      );
+      expect(relations).toEqual(["can_create_agent_share"]);
+    });
+  });
+});

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

@@ -163,6 +163,54 @@ describe("useSaveAgentShare", () => {
     expect(second.audience).toBe(AgentShareAudience.org);
   });
 
+  describe("cross-org create identity (shareOrg — decision 013)", () => {
+    it("a first save lands the share in the sharing org, agent_ref stays the agent's", async () => {
+      const apply = vi.fn().mockResolvedValue({});
+      const client = createMockStigmer({ apply });
+
+      const { result } = renderHook(
+        () => useSaveAgentShare(AGENT, "consumer-org"),
+        { wrapper: wrapper(client) },
+      );
+
+      await act(() => result.current.save(FULL_DRAFT, null));
+
+      const input = apply.mock.calls[0][0] as AgentShareInput;
+      // The share is the sharing org's resource (its URL, billing, and
+      // credentials), while agent_ref keeps pointing at the provider's
+      // blueprint — the whole point of a cross-org share.
+      expect(input.org).toBe("consumer-org");
+      expect(input.slug).toBe("support-agent");
+      expect(input.agentRef).toEqual({ org: "acme", slug: "support-agent" });
+    });
+
+    it("editing an existing cross-org share keeps ITS identity, not the hook argument's", async () => {
+      const apply = vi.fn().mockResolvedValue({});
+      const client = createMockStigmer({ apply });
+      const externalShare = {
+        metadata: {
+          id: "ash_ext",
+          org: "consumer-org",
+          slug: "renamed-channel",
+          name: "Renamed Channel",
+        },
+        spec: { enabled: true },
+      } as AgentShare;
+
+      const { result } = renderHook(
+        () => useSaveAgentShare(AGENT, "consumer-org"),
+        { wrapper: wrapper(client) },
+      );
+
+      await act(() => result.current.save(FULL_DRAFT, externalShare));
+
+      const input = apply.mock.calls[0][0] as AgentShareInput;
+      expect(input.org).toBe("consumer-org");
+      expect(input.slug).toBe("renamed-channel");
+      expect(input.agentRef).toEqual({ org: "acme", slug: "support-agent" });
+    });
+  });
+
   it("is a stable no-op when the agent is null", async () => {
     const apply = vi.fn();
     const client = createMockStigmer({ apply });

package/src/sharing/index.ts

@@ -5,26 +5,29 @@ 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 { useAgentShares } from "./useAgentShares.js";
+export type { UseAgentSharesReturn } from "./useAgentShares.js";
+export { useCanCreateAgentShare } from "./useCanCreateAgentShare.js";
+export type { UseCanCreateAgentShareReturn } from "./useCanCreateAgentShare.js";
 export {
+  draftFromShare,
   sharingAudienceFromProto,
   useSaveAgentShare,
 } from "./useSaveAgentShare.js";
 export type {
+  AgentShareCreateIdentity,
   AgentShareDraft,
   SharingAudience,
   UseSaveAgentShareReturn,
 } from "./useSaveAgentShare.js";
+export { useDeleteAgentShare } from "./useDeleteAgentShare.js";
+export type { UseDeleteAgentShareReturn } from "./useDeleteAgentShare.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 { AgentShareList } from "./AgentShareList.js";
+export type { AgentShareListProps } from "./AgentShareList.js";
 export { useShareToolReadiness } from "./useShareToolReadiness.js";
 export type { ShareToolReadiness } from "./useShareToolReadiness.js";
 // Origin validation moved to @stigmer/sdk (framework-free, shared with the

package/src/sharing/useAgentShares.ts

@@ -0,0 +1,68 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+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 useAgentShares}. */
+export interface UseAgentSharesReturn {
+  /**
+   * Every share of the agent visible to the caller, in server order.
+   * Empty while loading, on error, or when the agent has never been
+   * shared — `shares.length === 0 && !isLoading && !error` means "no
+   * shares exist yet".
+   */
+  readonly shares: readonly AgentShare[];
+  /** `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 shares from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that loads all of an agent's {@link AgentShare} resources —
+ * the channels carrying its hosted-chat configuration (audience, allowed
+ * origins, visitor messages, tool credentials, link token).
+ *
+ * Sharing is channel configuration, not agent behavior (decision 011):
+ * an agent can carry N shares, each with its own URL, billing org, and
+ * credentials (decision 011 D3 + decision 013 cross-org shares). This
+ * hook returns the full list; the server already scopes it to shares the
+ * caller can view (FGA-filtered in cloud, unfiltered in the single-user
+ * OSS edition), so a viewer sees their own org's channels and never
+ * another org's.
+ *
+ * Pass an empty `agentId` to skip fetching (stable no-op) — useful
+ * while the agent is still loading.
+ *
+ * @example
+ * ```tsx
+ * const { shares, isLoading, refetch } = useAgentShares(agent?.metadata?.id ?? "");
+ * ```
+ */
+export function useAgentShares(agentId: string): UseAgentSharesReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn = agentId
+    ? async () => {
+        const result = await stigmer.agentShare.getByAgent(
+          create(GetAgentSharesByAgentRequestSchema, { agentId }),
+        );
+        return result.items;
+      }
+    : null;
+
+  const { data: shares, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [agentId, stigmer],
+    [] as AgentShare[],
+  );
+
+  return { shares, isLoading, isRefetching, error, refetch };
+}

package/src/sharing/useCanCreateAgentShare.ts

@@ -0,0 +1,74 @@
+"use client";
+
+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 { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+
+/** Return value of {@link useCanCreateAgentShare}. */
+export interface UseCanCreateAgentShareReturn {
+  /** Whether the viewer may create a share of this agent in `shareOrg`. */
+  readonly allowed: boolean;
+  /**
+   * The org that would own the new share — the viewer's org when set,
+   * else the agent's own. The share's URL, billing, and credential
+   * bindings all belong to this org.
+   */
+  readonly shareOrg: string;
+  /** Whether creating in `shareOrg` would be a cross-org share (decision 013). */
+  readonly isCrossOrg: boolean;
+}
+
+/**
+ * Mirrors the server's AgentShare create bar so create affordances never
+ * appear to a user whose create would be refused:
+ *
+ * - **Same-org** (`shareOrg` equals the agent's org): agent `can_edit` —
+ *   the exact permission the create/apply handlers enforce on the
+ *   referenced agent.
+ * - **Cross-org** (decision 013 D2, two-sided): the agent must be
+ *   `visibility_public` — the origin org's implicit consent (D1), and
+ *   the client-side proxy for the `can_execute`-via-`allow_public` half
+ *   of the bar — and the viewer must hold `can_create_agent_share` in
+ *   their own org (admin-level: a public share spends that org's credits
+ *   on the open internet). The org check uses the org slug as the
+ *   resource id — an Organization's id equals its slug
+ *   (ApiResourceMetadata.id).
+ *
+ * On the OSS edition {@link useCheckPermission} degrades to allowed
+ * (no IAM service), matching the backend's documented no-op
+ * authorization (decision 011 D4).
+ *
+ * Pass `null` for `agent` while it loads — `allowed` stays `false` so
+ * no affordance flashes before the gate can be evaluated.
+ *
+ * @param agent      The agent to share, or `null` while loading.
+ * @param viewerOrg  The viewer's active org. Empty/omitted means the
+ *                   agent's own org (the same-org owner flow).
+ */
+export function useCanCreateAgentShare(
+  agent: Agent | null,
+  viewerOrg?: string,
+): UseCanCreateAgentShareReturn {
+  const agentId = agent?.metadata?.id ?? "";
+  const agentOrg = agent?.metadata?.org ?? "";
+  const shareOrg = viewerOrg || agentOrg;
+  const isCrossOrg = shareOrg !== "" && shareOrg !== agentOrg;
+  const isPublic =
+    agent?.metadata?.visibility === ApiResourceVisibility.visibility_public;
+
+  // Both permission checks are declared unconditionally (hook rules);
+  // each skips its RPC (null resource) when its branch doesn't apply.
+  const { allowed: canEditAgent } = useCheckPermission(
+    !isCrossOrg && agentId ? { kind: "agent", id: agentId } : null,
+    "can_edit",
+  );
+  const { allowed: canCreateInOrg } = useCheckPermission(
+    isCrossOrg && isPublic ? { kind: "organization", id: shareOrg } : null,
+    "can_create_agent_share",
+  );
+
+  const allowed =
+    !!agent && (isCrossOrg ? isPublic && canCreateInOrg : canEditAgent);
+
+  return { allowed, shareOrg, isCrossOrg };
+}

package/src/sharing/useDeleteAgentShare.ts

@@ -0,0 +1,73 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { AgentShare } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useDeleteAgentShare}. */
+export interface UseDeleteAgentShareReturn {
+  /**
+   * Delete an agent share by ID. Returns the deleted resource.
+   *
+   * Deleting a share is full teardown (decision 011 D1): its hosted
+   * link dies immediately — including for visitors mid-conversation —
+   * and its configuration (origins, messages, credential bindings, link
+   * token) is gone. To stop serving while keeping the configuration,
+   * save the share with `enabled: false` instead (a config-preserving
+   * pause via {@link useSaveAgentShare}).
+   */
+  readonly deleteShare: (id: string) => Promise<AgentShare>;
+  /** `true` while the delete request is in flight. */
+  readonly isDeleting: boolean;
+  /** Error from the last failed delete, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that deletes an {@link AgentShare} resource.
+ *
+ * Wraps `stigmer.agentShare.delete()` (authorized by the share's
+ * `can_delete`) with loading/error state. The caller is responsible for
+ * post-delete UI updates (e.g. refreshing the share list) and for
+ * confirming the destructive action — the delete-vs-pause distinction
+ * belongs in the confirmation copy.
+ *
+ * @example
+ * ```tsx
+ * const { deleteShare, isDeleting } = useDeleteAgentShare();
+ *
+ * const handleDelete = async () => {
+ *   await deleteShare(share.metadata.id);
+ *   refetch(); // refresh the share list
+ * };
+ * ```
+ */
+export function useDeleteAgentShare(): UseDeleteAgentShareReturn {
+  const stigmer = useStigmer();
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const deleteShare = useCallback(
+    async (id: string): Promise<AgentShare> => {
+      setIsDeleting(true);
+      setError(null);
+
+      try {
+        return await stigmer.agentShare.delete(id);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsDeleting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { deleteShare, isDeleting, error, clearError };
+}