@stigmer/react 3.1.16 → 3.2.0

package/src/channel/__tests__/useSaveAgentChannel.test.tsx

@@ -0,0 +1,294 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import type { AgentChannelInput } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useSaveAgentChannel, agentChannelToInput } from "../useSaveAgentChannel";
+
+function createMockStigmer(overrides: {
+  apply?: (input: AgentChannelInput) => Promise<unknown>;
+} = {}) {
+  return {
+    agentChannel: {
+      apply: overrides.apply ?? vi.fn().mockResolvedValue({}),
+    },
+  } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client as never}>
+        {children}
+      </StigmerContext.Provider>
+    );
+  };
+}
+
+function makeChannel(overrides: Record<string, unknown> = {}): AgentChannel {
+  return {
+    metadata: {
+      id: "ach_1",
+      name: "Support Slack",
+      slug: "support-slack",
+      org: "acme",
+      labels: {},
+    },
+    spec: {
+      agentRef: { org: "acme", slug: "support-agent" },
+      enabled: true,
+      providerConfig: { case: "slack", value: {} },
+    },
+    status: { installState: 2 },
+    ...overrides,
+  } as never;
+}
+
+describe("agentChannelToInput", () => {
+  it("reproduces an existing channel verbatim", () => {
+    const input = agentChannelToInput(makeChannel());
+
+    expect(input).toEqual({
+      name: "Support Slack",
+      slug: "support-slack",
+      org: "acme",
+      agentRef: { org: "acme", slug: "support-agent" },
+      enabled: true,
+      slack: {},
+    });
+  });
+
+  it("carries labels and omits empty optionals", () => {
+    const channel = makeChannel({
+      metadata: {
+        id: "ach_1",
+        name: "Support Slack",
+        slug: "",
+        org: "acme",
+        labels: { team: "cx" },
+      },
+    });
+
+    const input = agentChannelToInput(channel);
+    expect(input.labels).toEqual({ team: "cx" });
+    // An empty slug must be omitted, not sent as "" — apply would reject it.
+    expect(input).not.toHaveProperty("slug");
+  });
+
+  it("carries environment_refs — the toggle must never wipe bound credentials", () => {
+    const channel = makeChannel({
+      spec: {
+        agentRef: { org: "acme", slug: "support-agent" },
+        enabled: true,
+        providerConfig: { case: "slack", value: {} },
+        environmentRefs: [
+          { org: "acme", slug: "github-credentials" },
+          { org: "acme", slug: "search-credentials" },
+        ],
+      },
+    });
+
+    const input = agentChannelToInput(channel);
+    // Order preserved: the ref list's order is the merge priority.
+    expect(input.environmentRefs).toEqual([
+      { org: "acme", slug: "github-credentials" },
+      { org: "acme", slug: "search-credentials" },
+    ]);
+  });
+
+  it("omits environmentRefs entirely when the channel binds none", () => {
+    const input = agentChannelToInput(makeChannel());
+    expect(input).not.toHaveProperty("environmentRefs");
+  });
+
+  it("carries app_ref — the toggle must never unbind the serving app", () => {
+    const channel = makeChannel({
+      spec: {
+        agentRef: { org: "acme", slug: "support-agent" },
+        enabled: true,
+        providerConfig: { case: "slack", value: {} },
+        appRef: { org: "acme", slug: "acme-support-app" },
+      },
+    });
+
+    const input = agentChannelToInput(channel);
+    // Dropping app_ref on an installed channel would not just rebind to
+    // the platform app — the server FREEZES the binding while installed,
+    // so the toggle itself would be refused.
+    expect(input.appRef).toEqual({ org: "acme", slug: "acme-support-app" });
+  });
+
+  it("omits appRef entirely for platform-app channels", () => {
+    const input = agentChannelToInput(makeChannel());
+    expect(input).not.toHaveProperty("appRef");
+  });
+
+  it("omits the slack marker when the provider config is absent", () => {
+    const channel = makeChannel({
+      spec: {
+        agentRef: { org: "acme", slug: "support-agent" },
+        enabled: false,
+        providerConfig: { case: undefined },
+      },
+    });
+
+    const input = agentChannelToInput(channel);
+    expect(input).not.toHaveProperty("slack");
+    expect(input.enabled).toBe(false);
+  });
+
+  it("carries the whatsapp arm with its number — the toggle must never empty the provider oneof", () => {
+    const channel = makeChannel({
+      spec: {
+        agentRef: { org: "acme", slug: "support-agent" },
+        enabled: true,
+        providerConfig: {
+          case: "whatsapp",
+          value: { phoneNumberId: "106540352242922" },
+        },
+        appRef: { org: "acme", slug: "acme-meta-app" },
+      },
+    });
+
+    const input = agentChannelToInput(channel);
+    // A save without the arm would empty spec.provider_config, which the
+    // server refuses as a provider-immutability violation — the toggle
+    // itself would hard-fail. The declared number rides along because it
+    // lives in spec (unlike Slack, whose config is an empty marker).
+    expect(input.whatsapp).toEqual({ phoneNumberId: "106540352242922" });
+    expect(input).not.toHaveProperty("slack");
+    expect(input.appRef).toEqual({ org: "acme", slug: "acme-meta-app" });
+  });
+});
+
+describe("useSaveAgentChannel", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("applies the input and returns the persisted channel", async () => {
+    const persisted = makeChannel();
+    const apply = vi.fn().mockResolvedValue(persisted);
+    const client = createMockStigmer({ apply });
+
+    const { result } = renderHook(() => useSaveAgentChannel(), {
+      wrapper: wrapper(client),
+    });
+
+    const input: AgentChannelInput = {
+      name: "Support Slack",
+      org: "acme",
+      agentRef: { org: "acme", slug: "support-agent" },
+      enabled: true,
+      slack: {},
+    };
+
+    let returned: AgentChannel | undefined;
+    await act(async () => {
+      returned = await result.current.save(input);
+    });
+
+    expect(apply).toHaveBeenCalledWith(input);
+    expect(returned).toBe(persisted);
+    expect(result.current.error).toBeNull();
+    expect(result.current.isPending).toBe(false);
+  });
+
+  it("supports the toggle idiom: full input with one field changed", async () => {
+    const apply = vi.fn().mockResolvedValue(makeChannel());
+    const client = createMockStigmer({ apply });
+
+    const { result } = renderHook(() => useSaveAgentChannel(), {
+      wrapper: wrapper(client),
+    });
+
+    const boundChannel = makeChannel({
+      spec: {
+        agentRef: { org: "acme", slug: "support-agent" },
+        enabled: true,
+        providerConfig: { case: "slack", value: {} },
+        appRef: { org: "acme", slug: "acme-support-app" },
+        environmentRefs: [{ org: "acme", slug: "github-credentials" }],
+      },
+    });
+
+    await act(async () => {
+      await result.current.save({
+        ...agentChannelToInput(boundChannel),
+        enabled: false,
+      });
+    });
+
+    // The disable toggle must preserve the rest of the spec — a partial
+    // input would silently drop agentRef, the provider marker, the
+    // serving-app binding, or the bound credentials (apply semantics
+    // unbind whatever is omitted).
+    expect(apply).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: "Support Slack",
+        agentRef: { org: "acme", slug: "support-agent" },
+        slack: {},
+        enabled: false,
+        appRef: { org: "acme", slug: "acme-support-app" },
+        environmentRefs: [{ org: "acme", slug: "github-credentials" }],
+      }),
+    );
+  });
+
+  it("tracks isPending during the flight", async () => {
+    let resolveApply: (value: unknown) => void = () => {};
+    const apply = vi.fn().mockImplementation(
+      () => new Promise((resolve) => { resolveApply = resolve; }),
+    );
+    const client = createMockStigmer({ apply });
+
+    const { result } = renderHook(() => useSaveAgentChannel(), {
+      wrapper: wrapper(client),
+    });
+
+    let savePromise: Promise<unknown> = Promise.resolve();
+    act(() => {
+      savePromise = result.current.save({
+        name: "x",
+        org: "acme",
+        agentRef: { org: "acme", slug: "a" },
+        slack: {},
+      });
+    });
+
+    await waitFor(() => expect(result.current.isPending).toBe(true));
+
+    await act(async () => {
+      resolveApply({});
+      await savePromise;
+    });
+    expect(result.current.isPending).toBe(false);
+  });
+
+  it("captures and rethrows save failures", async () => {
+    const apply = vi.fn().mockRejectedValue(new Error("quota exceeded"));
+    const client = createMockStigmer({ apply });
+
+    const { result } = renderHook(() => useSaveAgentChannel(), {
+      wrapper: wrapper(client),
+    });
+
+    await act(async () => {
+      await expect(
+        result.current.save({
+          name: "x",
+          org: "acme",
+          agentRef: { org: "acme", slug: "a" },
+          slack: {},
+        }),
+      ).rejects.toThrow("quota exceeded");
+    });
+
+    expect(result.current.error?.message).toBe("quota exceeded");
+    expect(result.current.isPending).toBe(false);
+
+    act(() => result.current.clearError());
+    expect(result.current.error).toBeNull();
+  });
+});

package/src/channel/connect/ServingAppSection.tsx

@@ -0,0 +1,185 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+import type { ResourceRef } from "@stigmer/sdk";
+import type { ChannelApp } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
+
+/**
+ * "Connect as whom" for the channel connect dialogs (T04 item 2): the
+ * provider's platform app (when the provider has one — Slack) or one of
+ * the org's own channel apps (BYO — the bot carries that app's brand,
+ * and each app is its own bot identity).
+ *
+ * Provider variance is prop-shaped, never branched:
+ *
+ * - `platformOption` present (Slack): "no selection" means the platform
+ *   app, and with zero registered apps the section states that default
+ *   plainly instead of a one-option radio group (which would be noise).
+ * - `platformOption` absent (WhatsApp, BYO-only per DD-WA-2): an app
+ *   selection is required, and with zero registered apps the section
+ *   renders the caller's `emptyBody` — a blocking register-first state,
+ *   because a channel without an app binding could never install.
+ *
+ * Both shapes carry the register affordance: a link when the host
+ * provided `channelAppsHref`, plain guidance text otherwise.
+ */
+export function ServingAppSection({
+  org,
+  apps,
+  value,
+  onChange,
+  disabled,
+  channelAppsHref,
+  idPrefix,
+  platformOption,
+  appHint,
+  emptyBody,
+}: {
+  readonly org: string;
+  /** The org's channel apps, already filtered to this provider. */
+  readonly apps: readonly ChannelApp[];
+  readonly value: ResourceRef | null;
+  readonly onChange: (ref: ResourceRef | null) => void;
+  readonly disabled: boolean;
+  readonly channelAppsHref?: string;
+  /** Option id prefix + radio-group name, unique per dialog (e.g. "stgm-slack-app"). */
+  readonly idPrefix: string;
+  /**
+   * The provider's shared platform app as a selectable option
+   * (`value === null`). Omit for BYO-only providers.
+   */
+  readonly platformOption?: { readonly label: string; readonly hint: string };
+  /** Hint line under each of the org's own apps. */
+  readonly appHint: string;
+  /** Section body when the org has no apps for this provider. */
+  readonly emptyBody: ReactNode;
+}) {
+  if (apps.length === 0) {
+    return (
+      <section aria-label="Connect as">
+        <h3 className="mb-1.5 text-xs font-medium text-foreground">
+          Connect as
+        </h3>
+        {emptyBody}
+      </section>
+    );
+  }
+
+  return (
+    <fieldset>
+      <legend className="mb-1.5 block text-xs font-medium text-foreground">
+        Connect as
+      </legend>
+      <div role="radiogroup" className="space-y-1.5">
+        {platformOption && (
+          <ServingAppOption
+            id={`${idPrefix}-platform`}
+            name={idPrefix}
+            label={platformOption.label}
+            hint={platformOption.hint}
+            checked={value === null}
+            onSelect={() => onChange(null)}
+            disabled={disabled}
+          />
+        )}
+        {apps.map((app) => {
+          const slug = app.metadata?.slug ?? "";
+          const checked = value?.slug === slug;
+          return (
+            <ServingAppOption
+              key={app.metadata?.id ?? slug}
+              id={`${idPrefix}-${slug}`}
+              name={idPrefix}
+              label={app.metadata?.name ?? slug}
+              hint={appHint}
+              checked={checked}
+              onSelect={() => onChange({ org, slug })}
+              disabled={disabled}
+            />
+          );
+        })}
+      </div>
+      <p className="mt-1.5 text-xs text-muted-foreground">
+        <RegisterChannelAppAffordance channelAppsHref={channelAppsHref}>
+          Register a channel app
+        </RegisterChannelAppAffordance>
+        .
+      </p>
+    </fieldset>
+  );
+}
+
+/**
+ * The path from the connect flow to Channel App registration. A link
+ * when the host told us where registration lives; otherwise the label
+ * plus the console location, so embedded hosts without the route still
+ * leave the user oriented. Children are the label ("Register a channel
+ * app" / "register a channel app") so each call site reads as a sentence.
+ */
+export function RegisterChannelAppAffordance({
+  channelAppsHref,
+  children,
+}: {
+  readonly channelAppsHref?: string;
+  readonly children: ReactNode;
+}) {
+  if (!channelAppsHref) {
+    return <>{children} under Settings → Channel Apps</>;
+  }
+  return (
+    <a
+      href={channelAppsHref}
+      className={cn(
+        "font-medium underline underline-offset-2",
+        "hover:no-underline",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded",
+      )}
+    >
+      {children}
+    </a>
+  );
+}
+
+function ServingAppOption({
+  id,
+  name,
+  label,
+  hint,
+  checked,
+  onSelect,
+  disabled,
+}: {
+  readonly id: string;
+  readonly name: string;
+  readonly label: string;
+  readonly hint: string;
+  readonly checked: boolean;
+  readonly onSelect: () => void;
+  readonly disabled: boolean;
+}) {
+  return (
+    <label
+      htmlFor={id}
+      className={cn(
+        "flex cursor-pointer items-start gap-2 rounded-md border px-2.5 py-1.5",
+        checked ? "border-ring bg-accent" : "border-border hover:bg-accent-hover",
+        disabled && "pointer-events-none opacity-50",
+      )}
+    >
+      <input
+        id={id}
+        type="radio"
+        name={name}
+        checked={checked}
+        onChange={onSelect}
+        disabled={disabled}
+        className="mt-0.5 accent-current"
+      />
+      <span className="min-w-0">
+        <span className="block text-xs font-medium text-foreground">{label}</span>
+        <span className="block text-[0.65rem] text-muted-foreground">{hint}</span>
+      </span>
+    </label>
+  );
+}

package/src/channel/connect/ToolCredentialsSection.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+import { useState } from "react";
+import { cn } from "@stigmer/theme";
+import type { ResourceRef } from "@stigmer/sdk";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { ChannelToolCredentials } from "../ChannelToolCredentials.js";
+import { ChevronIcon } from "./icons.js";
+
+/**
+ * Collapsible credential-binding section for the connect dialogs' create
+ * mode (the ShareAgentDialog ToolCredentialsSection pattern). Expanded by
+ * default when the agent uses MCP tools — for those agents this is
+ * essential configuration, not an advanced option: without a binding,
+ * every channel message that needs a tool is refused.
+ *
+ * Provider-agnostic by construction: bindings are agent + environment
+ * facts, so both connect dialogs render this section unchanged.
+ */
+export function ToolCredentialsSection({
+  agent,
+  org,
+  value,
+  onChange,
+  disabled,
+}: {
+  readonly agent: Agent;
+  readonly org: string;
+  readonly value: readonly ResourceRef[];
+  readonly onChange: (refs: ResourceRef[]) => void;
+  readonly disabled: boolean;
+}) {
+  const hasMcpTools = (agent.spec?.mcpServerUsages?.length ?? 0) > 0;
+  const [expanded, setExpanded] = useState(hasMcpTools || value.length > 0);
+
+  return (
+    <section>
+      <button
+        type="button"
+        onClick={() => setExpanded((v) => !v)}
+        aria-expanded={expanded}
+        className={cn(
+          "inline-flex items-center gap-1 text-xs font-medium text-muted-foreground",
+          "hover:text-foreground",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded",
+        )}
+      >
+        <ChevronIcon
+          className={cn("size-3 transition-transform", expanded && "rotate-90")}
+        />
+        Tool credentials
+      </button>
+
+      {expanded && (
+        <div className="mt-2">
+          <ChannelToolCredentials
+            agent={agent}
+            org={org}
+            value={value}
+            onChange={onChange}
+            disabled={disabled}
+          />
+        </div>
+      )}
+    </section>
+  );
+}

package/src/channel/connect/VerbatimRefusal.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { getUserMessage } from "@stigmer/sdk";
+
+/**
+ * The plain install-refusal alert: the server's copy rendered verbatim —
+ * the server owns that vocabulary. Both connect dialogs fall back to
+ * this for any refusal they don't recognize; provider-guided refusals
+ * (a known ErrorInfo reason with actionable copy) stay provider-local
+ * and reuse {@link RefusalBox} for the chrome.
+ */
+export function VerbatimRefusal({ error }: { readonly error: Error }) {
+  return <RefusalBox>{getUserMessage(error)}</RefusalBox>;
+}
+
+/** The refusal alert chrome, shared by verbatim and guided refusals. */
+export function RefusalBox({ children }: { readonly children: ReactNode }) {
+  return (
+    <div
+      role="alert"
+      className="space-y-1 rounded-md border border-destructive/30 bg-destructive-subtle px-3 py-2 text-xs text-destructive"
+    >
+      {children}
+    </div>
+  );
+}

package/src/channel/connect/icons.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/**
+ * Inline icons shared by the channel connect dialogs. Package-internal:
+ * content-level pieces stay domain-local (the channel-app/internal.tsx
+ * convention).
+ */
+
+export function CloseIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" aria-hidden="true">
+      <path d="m3 3 8 8M11 3l-8 8" />
+    </svg>
+  );
+}
+
+export function CheckIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="m3 8.5 3.5 3.5L13 5" />
+    </svg>
+  );
+}
+
+export function ChevronIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="m4.5 2.5 3.5 3.5-3.5 3.5" />
+    </svg>
+  );
+}
+
+export function Spinner({ className }: { readonly className?: string }) {
+  return (
+    <svg className={cn("animate-spin", className)} viewBox="0 0 16 16" fill="none" aria-hidden="true">
+      <circle cx="8" cy="8" r="6.5" stroke="currentColor" strokeOpacity="0.25" strokeWidth="2" />
+      <path d="M14.5 8A6.5 6.5 0 0 0 8 1.5" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
+    </svg>
+  );
+}

package/src/channel/index.ts

@@ -0,0 +1,65 @@
+export { useAgentChannelList } from "./useAgentChannelList.js";
+export type { UseAgentChannelListReturn } from "./useAgentChannelList.js";
+
+export { useOrgAgentChannelList } from "./useOrgAgentChannelList.js";
+export type { UseOrgAgentChannelListReturn } from "./useOrgAgentChannelList.js";
+
+export { CHANNEL_PROVIDERS, channelProviderOf } from "./providers.js";
+export type {
+  ChannelProviderDescriptor,
+  ChannelProviderId,
+  ChannelInstallStyle,
+} from "./providers.js";
+
+export {
+  channelPresentationOf,
+  DEFAULT_CHANNEL_PRESENTATION,
+} from "./providerPresentation.js";
+export type { ChannelProviderPresentation } from "./providerPresentation.js";
+
+export { useAgentChannel } from "./useAgentChannel.js";
+export type { UseAgentChannelReturn } from "./useAgentChannel.js";
+
+export { useSaveAgentChannel, agentChannelToInput } from "./useSaveAgentChannel.js";
+export type { UseSaveAgentChannelReturn } from "./useSaveAgentChannel.js";
+
+export { useCreateAgentChannel } from "./useCreateAgentChannel.js";
+export type { UseCreateAgentChannelReturn } from "./useCreateAgentChannel.js";
+
+export { useDeleteAgentChannel } from "./useDeleteAgentChannel.js";
+export type { UseDeleteAgentChannelReturn } from "./useDeleteAgentChannel.js";
+
+export { useConnectSlackChannel } from "./useConnectSlackChannel.js";
+export type {
+  UseConnectSlackChannelReturn,
+  SlackConnectPhase,
+} from "./useConnectSlackChannel.js";
+
+export { useInstallChannel } from "./useInstallChannel.js";
+export type {
+  UseInstallChannelReturn,
+  InstallChannelPhase,
+} from "./useInstallChannel.js";
+
+export { useChannelToolReadiness } from "./useChannelToolReadiness.js";
+
+export { useChannelSessions } from "./useChannelSessions.js";
+export type { UseChannelSessionsReturn } from "./useChannelSessions.js";
+
+export { AgentChannelsPanel } from "./AgentChannelsPanel.js";
+export type { AgentChannelsPanelProps } from "./AgentChannelsPanel.js";
+
+export { ConnectSlackDialog } from "./ConnectSlackDialog.js";
+export type { ConnectSlackDialogProps } from "./ConnectSlackDialog.js";
+
+export { ConnectWhatsAppDialog } from "./ConnectWhatsAppDialog.js";
+export type { ConnectWhatsAppDialogProps } from "./ConnectWhatsAppDialog.js";
+
+export { ChannelCredentialsDialog } from "./ChannelCredentialsDialog.js";
+export type { ChannelCredentialsDialogProps } from "./ChannelCredentialsDialog.js";
+
+export { ChannelToolCredentials } from "./ChannelToolCredentials.js";
+export type { ChannelToolCredentialsProps } from "./ChannelToolCredentials.js";
+
+export { ChannelConversationsDialog } from "./ChannelConversationsDialog.js";
+export type { ChannelConversationsDialogProps } from "./ChannelConversationsDialog.js";