@stigmer/react 3.1.13 → 3.1.14

package/src/sharing/useSaveAgentShare.ts

@@ -76,6 +76,48 @@ function sharingAudienceToProto(audience: SharingAudience): AgentShareAudience {
     : AgentShareAudience.public;
 }
 
+/**
+ * Projects a share into the editable {@link AgentShareDraft} — the
+ * single constructor for the full-spec drafts every save requires.
+ * `null` (no share yet) seeds the same defaults the server would apply
+ * on first create.
+ *
+ * Shared by the Share dialog (draft seeding) and the share list's
+ * pause/resume toggle, so a toggle rebuilds the complete spec with only
+ * `enabled` flipped and can never wipe origins, messages, or credential
+ * bindings — the fails-closed posture {@link AgentShareDraft} exists to
+ * enforce.
+ */
+export function draftFromShare(share: AgentShare | null): AgentShareDraft {
+  const spec = share?.spec;
+  return {
+    enabled: spec?.enabled ?? false,
+    audience: sharingAudienceFromProto(spec?.audience),
+    allowedOrigins: spec?.allowedOrigins ?? [],
+    messages: {
+      rateLimited: spec?.messages?.rateLimited ?? "",
+      unavailable: spec?.messages?.unavailable ?? "",
+      conversationEnded: spec?.messages?.conversationEnded ?? "",
+    },
+    environmentRefs: (spec?.environmentRefs ?? []).map((ref) => ({
+      org: ref.org,
+      slug: ref.slug,
+    })),
+  };
+}
+
+/**
+ * Identity for a share being created: its display name and URL slug in
+ * the sharing org's namespace. Only consulted when `current` is `null`
+ * — an existing share's identity is immutable (decision 011 D2).
+ */
+export interface AgentShareCreateIdentity {
+  /** Display name for the new share. */
+  readonly name: string;
+  /** URL slug for the new share — appears in `/chat/<org>/<slug>`. */
+  readonly slug: string;
+}
+
 /** Return value of {@link useSaveAgentShare}. */
 export interface UseSaveAgentShareReturn {
   /**
@@ -83,12 +125,14 @@ export interface UseSaveAgentShareReturn {
    * 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.
+   * `current` is the share being edited, or `null` to create one —
+   * named by `createIdentity` when given, else the server's defaults
+   * (the agent's own name and slug).
    */
   readonly save: (
     draft: AgentShareDraft,
     current: AgentShare | null,
+    createIdentity?: AgentShareCreateIdentity,
   ) => Promise<AgentShare | undefined>;
   /** `true` while the RPC is in flight. */
   readonly isPending: boolean;
@@ -97,36 +141,36 @@ export interface UseSaveAgentShareReturn {
 }
 
 /**
- * Behavior hook that persists an agent's canonical share configuration.
+ * Behavior hook that persists an agent share's 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.
+ * creation (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, which makes
+ * apply-by-identity exact, and the generated `AgentShareInput` carries
+ * no `metadata.id` for an update to route by anyway. A create that
+ * collides on `(org, slug)` rejects with an already-exists error rather
+ * than touching the existing share.
  *
  * 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.
+ * operation ({@link useDeleteAgentShare}).
  *
- * `shareOrg` selects which org's channel a first save creates and
- * defaults to the agent's own org. Pass the viewer's org to create a
- * **cross-org share** (decision 013) — the server then authorizes on the
- * public agent's `can_execute` plus `can_create_agent_share` in the
- * sharing org, and bills that org.
+ * `shareOrg` selects which org owns a created share and defaults to the
+ * agent's own org. Pass the viewer's org to create a **cross-org
+ * share** (decision 013) — the server then authorizes on the public
+ * agent's `can_execute` plus `can_create_agent_share` in the sharing
+ * org, and bills that org.
  *
  * 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);
+ * const persisted = await save({ ...draftFromShare(share), enabled: true }, share);
  * // persisted.status.shareLinkToken is the live link token
  * ```
  */
@@ -147,6 +191,7 @@ export function useSaveAgentShare(
     async (
       draft: AgentShareDraft,
       current: AgentShare | null,
+      createIdentity?: AgentShareCreateIdentity,
     ): Promise<AgentShare | undefined> => {
       if (!agentOrg || !agentSlug) return undefined;
 
@@ -156,13 +201,18 @@ export function useSaveAgentShare(
       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
-          // sharing org + the agent's slug when creating (the server's
-          // own D2 default, made explicit).
+          // share may carry a non-default slug — apply with the agent's
+          // slug would create a SECOND share); when creating, the
+          // sharing org + the caller-chosen identity, falling back to
+          // the agent's own slug/name (the server's D2 default, made
+          // explicit).
           org: current?.metadata?.org || resolvedShareOrg,
-          slug: current?.metadata?.slug || agentSlug,
-          name: current?.metadata?.name || agentName || agentSlug,
+          slug: current?.metadata?.slug || createIdentity?.slug || agentSlug,
+          name:
+            current?.metadata?.name ||
+            createIdentity?.name ||
+            agentName ||
+            agentSlug,
           agentRef: { org: agentOrg, slug: agentSlug },
           enabled: draft.enabled,
           // Written as the explicit enum value, never left unspecified —