@stigmer/react 3.39.1-dev.20260928194002 → 3.40.1

package/src/plan-catalog/PlanCatalogConsole.tsx

@@ -0,0 +1,197 @@
+"use client";
+
+import { useState } from "react";
+import { cn } from "@stigmer/theme";
+import { getUserMessage, isUnimplemented } from "@stigmer/sdk";
+import type { Plan } from "@stigmer/protos/ai/stigmer/billing/plan/v1/api_pb";
+import { PlanInstrument } from "@stigmer/protos/ai/stigmer/billing/plan/v1/spec_pb";
+import { PlanLifecycle } from "@stigmer/protos/ai/stigmer/billing/plan/v1/status_pb";
+import { formatCreditBalance } from "../billing/format.js";
+import { formatManagedOrganizations, formatUsageShare, offeredFeatures } from "../billing/plan-features.js";
+import { usePlans } from "../billing/usePlans.js";
+import { Button } from "../button/index.js";
+import { ApiResourceKind, useResourceAvailable } from "../deployment-mode.js";
+import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+import { CloudFeatureNotice } from "../internal/CloudFeatureNotice.js";
+import { UNSTYLED_LIST } from "../internal/element-resets.js";
+import { FEATURE_COPY, isNamedFeature } from "../internal/features.js";
+import { ConfirmDialog } from "../resource-detail/ConfirmDialog.js";
+import { useConfirmAction } from "../resource-detail/useConfirmAction.js";
+import { StatusBadge } from "../resource-workbench/components/StatusBadge.js";
+import { PlanCreateForm } from "./PlanCreateForm.js";
+import { PlansAccessNotice } from "./PlansAccessNotice.js";
+import { useRetirePlan } from "./usePlanMutations.js";
+
+/** The platform object the catalog's permission is held on. */
+const PLATFORM = { kind: "platform", id: "stigmer" } as const;
+
+/** Props for {@link PlanCatalogConsole}. */
+export interface PlanCatalogConsoleProps {
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * The platform-operator console for the Stigmer Cloud plan catalog: every
+ * plan, retired ones included, with its terms and what it offers; retiring
+ * a plan; and creating one.
+ *
+ * Every signed-in caller may read the catalog, so the page gates on
+ * `can_manage_plans` on `platform:stigmer` itself, and anyone without it
+ * sees the designed access notice. Organizations choose their plan under
+ * Billing, not here.
+ *
+ * @example
+ * ```tsx
+ * <PlanCatalogConsole />
+ * ```
+ */
+export function PlanCatalogConsole({ className }: PlanCatalogConsoleProps) {
+  const available = useResourceAvailable(ApiResourceKind.plan);
+  const operator = useCheckPermission(available ? PLATFORM : null, "can_manage_plans", { fail: "closed" });
+  const catalog = usePlans({ includeRetired: true, enabled: available && operator.allowed });
+  const retirer = useRetirePlan();
+  const { confirmState, confirm, handleConfirm, handleCancel } = useConfirmAction();
+  const [creating, setCreating] = useState(false);
+
+  const header = <ConsoleHeader onCreate={operator.allowed && !creating ? () => setCreating(true) : undefined} />;
+
+  if (!available || (catalog.error && isUnimplemented(catalog.error))) {
+    return (
+      <div className={cn("stg:space-y-3", className)}>
+        {header}
+        <CloudFeatureNotice>
+          Plans are sold on Stigmer Cloud. The server this console is connected to serves no plan catalog.
+        </CloudFeatureNotice>
+      </div>
+    );
+  }
+  if (operator.isLoading || (operator.allowed && catalog.plans === null && catalog.error === null)) {
+    return (
+      <div className={cn("stg:space-y-2", className)} aria-busy="true">
+        {Array.from({ length: 3 }, (_, i) => (
+          <div key={i} className="stg:h-12 stg:animate-pulse stg:rounded-lg stg:bg-muted-subtle" />
+        ))}
+      </div>
+    );
+  }
+  if (!operator.allowed) {
+    return (
+      <div className={cn("stg:space-y-3", className)}>
+        {header}
+        <PlansAccessNotice />
+      </div>
+    );
+  }
+  if (catalog.error) {
+    return (
+      <div className={cn("stg:space-y-3", className)}>
+        {header}
+        <p className="stg:text-sm stg:text-destructive" role="alert">
+          {getUserMessage(catalog.error)}
+        </p>
+        <Button variant="outline" onClick={catalog.refetch}>
+          Try again
+        </Button>
+      </div>
+    );
+  }
+
+  const retire = async (plan: Plan) => {
+    const ok = await confirm({
+      title: `Retire ${plan.metadata?.name ?? "this plan"}?`,
+      description:
+        "It can no longer be bought. Every organization already on it keeps it, invoiced by its terms. Retiring is final.",
+      confirmLabel: "Retire",
+      variant: "destructive",
+    });
+    if (ok) {
+      retirer.retirePlan(plan.metadata?.id ?? "").then(catalog.refetch, () => undefined);
+    }
+  };
+
+  return (
+    <div className={cn("stg:space-y-4", className)}>
+      {header}
+      {creating ? (
+        <div className="stg:rounded-lg stg:border stg:border-border stg:bg-card stg:p-4">
+          <PlanCreateForm
+            onCreated={() => {
+              setCreating(false);
+              catalog.refetch();
+            }}
+            onCancel={() => setCreating(false)}
+          />
+        </div>
+      ) : null}
+      {retirer.error && (
+        <p className="stg:text-xs stg:text-destructive" role="alert">
+          {getUserMessage(retirer.error)}
+        </p>
+      )}
+      <ul className={cn(UNSTYLED_LIST, "stg:space-y-2")} aria-label="Plan catalog">
+        {(catalog.plans ?? []).map((plan) => (
+          <PlanRow key={plan.metadata?.id} plan={plan} onRetire={() => void retire(plan)} busy={retirer.isSubmitting} />
+        ))}
+      </ul>
+      <ConfirmDialog state={confirmState} onConfirm={handleConfirm} onCancel={handleCancel} />
+    </div>
+  );
+}
+
+function ConsoleHeader({ onCreate }: { readonly onCreate?: () => void }) {
+  return (
+    <div className="stg:flex stg:items-start stg:justify-between stg:gap-3">
+      <div>
+        <h2 className="stg:text-sm stg:font-semibold stg:text-foreground">Plans</h2>
+        <p className="stg:text-xs stg:text-muted-foreground">
+          The plans organizations subscribe to. A plan&apos;s terms are final; change them with a new plan and retire the
+          old one.
+        </p>
+      </div>
+      {onCreate && (
+        <Button size="xs" onClick={onCreate}>
+          New plan
+        </Button>
+      )}
+    </div>
+  );
+}
+
+function PlanRow({ plan, onRetire, busy }: { readonly plan: Plan; readonly onRetire: () => void; readonly busy: boolean }) {
+  const active = plan.status?.lifecycle === PlanLifecycle.active;
+  const license = plan.spec?.instrument === PlanInstrument.license;
+  const terms = plan.spec?.terms;
+  const listed = (plan.spec?.entitlements?.features ?? []).filter(isNamedFeature).map((f) => FEATURE_COPY[f].label);
+  const offered = new Set(offeredFeatures(plan.spec?.entitlements).map((f) => f.label));
+  const managed = formatManagedOrganizations(plan.spec?.entitlements, terms);
+  return (
+    <li className="stg:rounded-lg stg:border stg:border-border stg:bg-card stg:p-3">
+      <div className="stg:flex stg:items-center stg:justify-between stg:gap-3">
+        <div className="stg:min-w-0">
+          <p className="stg:truncate stg:text-sm stg:font-medium stg:text-foreground">
+            {plan.metadata?.name}{" "}
+            <span className="stg:font-normal stg:text-muted-foreground">({plan.metadata?.slug})</span>
+          </p>
+          <p className="stg:text-xs stg:text-muted-foreground">
+            {license
+              ? "Issued as a license"
+              : `${formatCreditBalance(terms?.monthlyMinimumMicros ?? BigInt(0))}/month ${formatUsageShare(terms)}`}
+          </p>
+        </div>
+        <div className="stg:flex stg:shrink-0 stg:items-center stg:gap-2">
+          <StatusBadge phase={active ? "ready" : "disabled"} label={active ? "On sale" : "Retired"} />
+          {active && (
+            <Button variant="outline" size="xs" onClick={onRetire} disabled={busy}>
+              Retire
+            </Button>
+          )}
+        </div>
+      </div>
+      <p className="stg:mt-1 stg:text-xs stg:text-muted-foreground">
+        {listed.map((label) => (offered.has(label) ? label : `${label} (not offered yet)`)).join(" · ")}
+        {managed === "" ? "" : ` · ${managed}`}
+      </p>
+    </li>
+  );
+}

package/src/plan-catalog/PlanCreateForm.tsx

@@ -0,0 +1,167 @@
+"use client";
+
+import { useState, type FormEvent } from "react";
+import { cn } from "@stigmer/theme";
+import { getUserMessage } from "@stigmer/sdk";
+import type { Plan } from "@stigmer/protos/ai/stigmer/billing/plan/v1/api_pb";
+import { Feature } from "@stigmer/protos/ai/stigmer/platform/v1/entitlement_pb";
+import { Button } from "../button/index.js";
+import { UNSTYLED_FIELDSET } from "../internal/element-resets.js";
+import { FEATURE_COPY, type NamedFeature } from "../internal/features.js";
+import { Field, INPUT_CLASSES } from "../internal/form-primitives.js";
+import { EMPTY_PLAN_DRAFT, planInputFromDraft, type PlanDraft } from "./plan-draft.js";
+import { useCreatePlan } from "./usePlanMutations.js";
+
+/** The features a subscription plan can list, in contract order. */
+const PLAN_FEATURES: readonly NamedFeature[] = [
+  Feature.channels,
+  Feature.sharing,
+  Feature.teams,
+  Feature.managed_organizations,
+  Feature.byo_provider_keys,
+  Feature.sso_enforcement,
+];
+
+/** Props for {@link PlanCreateForm}. */
+export interface PlanCreateFormProps {
+  /** Fired with the created plan. */
+  readonly onCreated: (plan: Plan) => void;
+  /** Fired when the operator leaves without creating. */
+  readonly onCancel: () => void;
+}
+
+/**
+ * Adds a subscription plan to the catalog: its name and handle, its
+ * monthly minimum and usage share, its features, and the managed
+ * organizations it includes. The form states before submitting that a
+ * plan's terms are final: a change of terms is a new plan, and the old
+ * one is retired.
+ */
+export function PlanCreateForm({ onCreated, onCancel }: PlanCreateFormProps) {
+  const creator = useCreatePlan();
+  const [draft, setDraft] = useState<PlanDraft>(EMPTY_PLAN_DRAFT);
+  const [confirming, setConfirming] = useState(false);
+  const result = planInputFromDraft(draft);
+  const set = <K extends keyof PlanDraft>(key: K, value: PlanDraft[K]) => {
+    setConfirming(false);
+    setDraft((current) => ({ ...current, [key]: value }));
+  };
+  const toggle = (feature: Feature, on: boolean) =>
+    set("features", on ? [...draft.features, feature] : draft.features.filter((f) => f !== feature));
+
+  const submit = (e: FormEvent) => {
+    e.preventDefault();
+    if (!result.ok) return;
+    if (!confirming) {
+      setConfirming(true);
+      return;
+    }
+    creator.createPlan(result.input).then(onCreated, () => undefined);
+  };
+
+  const fieldError = (field: keyof PlanDraft) =>
+    !result.ok && result.field === field && draft[field] !== "" ? (
+      <span className="stg:block stg:text-xs stg:text-destructive">{result.message}</span>
+    ) : null;
+
+  return (
+    <form onSubmit={submit} className="stg:space-y-4" aria-label="New plan">
+      <div className="stg:grid stg:gap-3 stg:sm:grid-cols-2">
+        <Field label="Name" required>
+          <input className={INPUT_CLASSES} value={draft.name} onChange={(e) => set("name", e.target.value)} />
+        </Field>
+        <Field label="Handle (slug)" required>
+          <input
+            className={INPUT_CLASSES}
+            value={draft.slug}
+            placeholder="team-2027"
+            onChange={(e) => set("slug", e.target.value)}
+          />
+          {fieldError("slug")}
+        </Field>
+        <Field label="Monthly minimum (USD)" required>
+          <input
+            className={INPUT_CLASSES}
+            inputMode="decimal"
+            value={draft.monthlyMinimumUsd}
+            onChange={(e) => set("monthlyMinimumUsd", e.target.value)}
+          />
+          {fieldError("monthlyMinimumUsd")}
+        </Field>
+        <Field label="Usage share (% of provider cost)" required>
+          <input
+            className={INPUT_CLASSES}
+            inputMode="decimal"
+            value={draft.usageSharePercent}
+            onChange={(e) => set("usageSharePercent", e.target.value)}
+          />
+          {fieldError("usageSharePercent")}
+        </Field>
+      </div>
+
+      <fieldset className={cn(UNSTYLED_FIELDSET, "stg:space-y-2")}>
+        <legend className="stg:mb-1 stg:text-xs stg:font-medium stg:text-muted-foreground">Features</legend>
+        {PLAN_FEATURES.map((feature) => (
+          <label key={feature} className="stg:flex stg:items-start stg:gap-2 stg:text-sm">
+            <input
+              type="checkbox"
+              className="stg:mt-0.5"
+              checked={draft.features.includes(feature)}
+              onChange={(e) => toggle(feature, e.target.checked)}
+            />
+            <span>
+              <span className="stg:block stg:text-foreground">{FEATURE_COPY[feature].label}</span>
+              <span className="stg:block stg:text-xs stg:text-muted-foreground">
+                {FEATURE_COPY[feature].description}
+              </span>
+            </span>
+          </label>
+        ))}
+      </fieldset>
+
+      {draft.features.includes(Feature.managed_organizations) && (
+        <div className="stg:grid stg:gap-3 stg:sm:grid-cols-2">
+          <Field label="Managed organizations included (empty: unlimited)">
+            <input
+              className={INPUT_CLASSES}
+              inputMode="numeric"
+              value={draft.includedManagedOrganizations}
+              onChange={(e) => set("includedManagedOrganizations", e.target.value)}
+            />
+            {fieldError("includedManagedOrganizations")}
+          </Field>
+          <Field label="Each one beyond (USD/month)">
+            <input
+              className={INPUT_CLASSES}
+              inputMode="decimal"
+              value={draft.perExtraOrganizationUsd}
+              onChange={(e) => set("perExtraOrganizationUsd", e.target.value)}
+            />
+            {fieldError("perExtraOrganizationUsd")}
+          </Field>
+        </div>
+      )}
+
+      {confirming && (
+        <p className="stg:rounded-md stg:bg-muted-subtle stg:px-3 stg:py-2 stg:text-xs stg:text-foreground" role="status">
+          A plan&apos;s terms are final once it exists: every subscriber on it is invoiced by them. A change of terms is
+          a new plan, and this one is retired. Create it?
+        </p>
+      )}
+      {creator.error && (
+        <p className="stg:text-xs stg:text-destructive" role="alert">
+          {getUserMessage(creator.error)}
+        </p>
+      )}
+
+      <div className="stg:flex stg:justify-end stg:gap-2">
+        <Button variant="ghost" size="sm" type="button" onClick={onCancel} disabled={creator.isSubmitting}>
+          Cancel
+        </Button>
+        <Button size="sm" type="submit" disabled={!result.ok || creator.isSubmitting}>
+          {confirming ? "Create plan" : "Review"}
+        </Button>
+      </div>
+    </form>
+  );
+}

package/src/plan-catalog/PlansAccessNotice.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import { EmptyState } from "../empty-state/index.js";
+
+/**
+ * The access-denied state for the plan catalog's operator surface.
+ * Server-side authorization (`can_manage_plans` on `platform:stigmer`) is
+ * the real gate; this is the designed face of it for anyone who reaches
+ * the route without the permission.
+ */
+export function PlansAccessNotice({ className }: { readonly className?: string }) {
+  return (
+    <EmptyState
+      variant="permission"
+      className={className}
+      title="Platform operator access required"
+      description="The plan catalog is managed by Stigmer's platform operators: a plan's terms are what every subscriber on it is invoiced. Organization roles do not grant access; organizations choose their plan under Billing."
+    />
+  );
+}

package/src/plan-catalog/index.ts

@@ -0,0 +1,14 @@
+// Plan catalog: the platform-operator console for the Stigmer Cloud plans
+// organizations subscribe to (gated on can_manage_plans). Choosing a plan
+// is the customer-facing billing surface's (../billing).
+
+// Behavior hooks
+export { useCreatePlan, useRetirePlan } from "./usePlanMutations.js";
+export type { UseCreatePlanReturn, UseRetirePlanReturn } from "./usePlanMutations.js";
+
+// Styled components
+export { PlanCatalogConsole } from "./PlanCatalogConsole.js";
+export type { PlanCatalogConsoleProps } from "./PlanCatalogConsole.js";
+export { PlanCreateForm } from "./PlanCreateForm.js";
+export type { PlanCreateFormProps } from "./PlanCreateForm.js";
+export { PlansAccessNotice } from "./PlansAccessNotice.js";

package/src/plan-catalog/plan-draft.ts

@@ -0,0 +1,116 @@
+// The plan create form's draft and its translation to the SDK's
+// PlanInput: dollars typed by an operator become exact micros, a percent
+// becomes basis points, and every field the contract cannot take is
+// refused here with the field that is wrong, before a request is sent.
+
+import type { PlanInput } from "@stigmer/sdk";
+import { PlanInstrument } from "@stigmer/protos/ai/stigmer/billing/plan/v1/spec_pb";
+import { Feature } from "@stigmer/protos/ai/stigmer/platform/v1/entitlement_pb";
+
+// BigInt(...), not literals: the docs site compiles this source for a
+// target below ES2020, which has no BigInt literal syntax.
+const MICROS_PER_CENT = BigInt(10_000);
+const CENTS_PER_USD = BigInt(100);
+
+/** What an operator types to create a subscription plan. */
+export interface PlanDraft {
+  readonly name: string;
+  readonly slug: string;
+  readonly monthlyMinimumUsd: string;
+  readonly usageSharePercent: string;
+  readonly features: readonly Feature[];
+  /** Empty: the plan includes every managed organization. */
+  readonly includedManagedOrganizations: string;
+  readonly perExtraOrganizationUsd: string;
+}
+
+export const EMPTY_PLAN_DRAFT: PlanDraft = {
+  name: "",
+  slug: "",
+  monthlyMinimumUsd: "",
+  usageSharePercent: "10",
+  features: [Feature.channels, Feature.sharing],
+  includedManagedOrganizations: "",
+  perExtraOrganizationUsd: "",
+};
+
+/** The draft as a PlanInput, or the first field that is wrong and why. */
+export type PlanDraftResult =
+  | { readonly ok: true; readonly input: PlanInput }
+  | { readonly ok: false; readonly field: keyof PlanDraft; readonly message: string };
+
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** A dollar amount with at most two decimals as exact micros, or `null`. */
+export function parseUsd(text: string): bigint | null {
+  const match = /^(\d+)(?:\.(\d{1,2}))?$/.exec(text.trim());
+  if (match === null) {
+    return null;
+  }
+  const cents = BigInt(match[1] ?? "0") * CENTS_PER_USD + BigInt((match[2] ?? "").padEnd(2, "0"));
+  return cents * MICROS_PER_CENT;
+}
+
+/** A percent with at most two decimals as basis points, or `null`. */
+export function parseBasisPoints(text: string): number | null {
+  const match = /^(\d{1,3})(?:\.(\d{1,2}))?$/.exec(text.trim());
+  if (match === null) {
+    return null;
+  }
+  const points = Number(match[1]) * 100 + Number((match[2] ?? "").padEnd(2, "0"));
+  return points <= 10_000 ? points : null;
+}
+
+/** Translate a draft into the create request, refusing what the contract cannot take. */
+export function planInputFromDraft(draft: PlanDraft): PlanDraftResult {
+  const name = draft.name.trim();
+  if (name === "") {
+    return { ok: false, field: "name", message: "A plan needs a name." };
+  }
+  const slug = draft.slug.trim();
+  if (!SLUG.test(slug)) {
+    return { ok: false, field: "slug", message: "Lowercase letters, digits and single hyphens, e.g. team-2027." };
+  }
+  const minimum = parseUsd(draft.monthlyMinimumUsd);
+  if (minimum === null) {
+    return { ok: false, field: "monthlyMinimumUsd", message: "A dollar amount, e.g. 99 or 99.50." };
+  }
+  const share = parseBasisPoints(draft.usageSharePercent);
+  if (share === null) {
+    return { ok: false, field: "usageSharePercent", message: "A percent from 0 to 100, e.g. 10." };
+  }
+  const managed = draft.features.includes(Feature.managed_organizations);
+  let includedManagedOrganizations: number | undefined;
+  let perExtraOrganizationMicros: bigint | undefined;
+  if (managed && draft.includedManagedOrganizations.trim() !== "") {
+    const included = Number(draft.includedManagedOrganizations.trim());
+    if (!Number.isInteger(included) || included < 0) {
+      return { ok: false, field: "includedManagedOrganizations", message: "A whole number, or empty for unlimited." };
+    }
+    includedManagedOrganizations = included;
+    const fee = parseUsd(draft.perExtraOrganizationUsd === "" ? "0" : draft.perExtraOrganizationUsd);
+    if (fee === null) {
+      return { ok: false, field: "perExtraOrganizationUsd", message: "A dollar amount per organization, e.g. 25." };
+    }
+    perExtraOrganizationMicros = fee;
+  }
+  return {
+    ok: true,
+    input: {
+      name,
+      slug,
+      org: "",
+      instrument: PlanInstrument.subscription,
+      entitlements: {
+        features: [...new Set(draft.features)].sort((a, b) => a - b),
+        ...(includedManagedOrganizations === undefined ? {} : { limits: { includedManagedOrganizations } }),
+      },
+      terms: {
+        monthlyMinimumMicros: minimum,
+        usageShareBasisPoints: share,
+        ...(perExtraOrganizationMicros === undefined ? {} : { perExtraOrganizationMicros }),
+      },
+    },
+  };
+}
+

package/src/plan-catalog/usePlanMutations.ts

@@ -0,0 +1,94 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import type { PlanInput } from "@stigmer/sdk";
+import type { Plan } from "@stigmer/protos/ai/stigmer/billing/plan/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useCreatePlan}. */
+export interface UseCreatePlanReturn {
+  /**
+   * Add a plan to the catalog. A plan's terms are final once it exists:
+   * there is no update, so changed terms are a new plan and the old one
+   * is retired.
+   */
+  readonly createPlan: (input: PlanInput) => Promise<Plan>;
+  /** `true` while a create is in flight. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behaviour hook that adds a plan to the Stigmer Cloud catalog.
+ * Platform-operator surface: `can_manage_plans` on `platform:stigmer`.
+ */
+export function useCreatePlan(): UseCreatePlanReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const createPlan = useCallback(
+    async (input: PlanInput): Promise<Plan> => {
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        return await stigmer.plan.create(input);
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer.plan],
+  );
+  const clearError = useCallback(() => setError(null), []);
+  return useMemo(() => ({ createPlan, isSubmitting, error, clearError }), [createPlan, isSubmitting, error, clearError]);
+}
+
+/** Return value of {@link useRetirePlan}. */
+export interface UseRetirePlanReturn {
+  /**
+   * Retire a plan: it can no longer be bought, and every subscription
+   * already on it keeps it. Retiring is final.
+   */
+  readonly retirePlan: (planId: string) => Promise<Plan>;
+  /** `true` while a retire is in flight. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behaviour hook that retires a catalog plan.
+ * Platform-operator surface: `can_manage_plans` on `platform:stigmer`.
+ */
+export function useRetirePlan(): UseRetirePlanReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const retirePlan = useCallback(
+    async (planId: string): Promise<Plan> => {
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        return await stigmer.plan.retire(planId);
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer.plan],
+  );
+  const clearError = useCallback(() => setError(null), []);
+  return useMemo(() => ({ retirePlan, isSubmitting, error, clearError }), [retirePlan, isSubmitting, error, clearError]);
+}

package/src/settings/ChannelAppsSection.tsx

@@ -8,9 +8,11 @@ import {
   type ChannelAppCreateHandoff,
 } from "../channel-app/CreateChannelAppForm.js";
 import { ChannelAppDetailPanel } from "../channel-app/ChannelAppDetailPanel.js";
+import { CHANNEL_APPS_MANAGED_BY_ADMINS } from "../channel-app/copy.js";
 import { useDeploymentMode } from "../deployment-mode.js";
+import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
 import { CloudFeatureNotice } from "../internal/CloudFeatureNotice.js";
-import { useActiveOrgSlug } from "../organization/OrgProvider.js";
+import { useActiveOrgId, useActiveOrgSlug } from "../organization/OrgProvider.js";
 
 type FlowState =
   | { phase: "idle" }
@@ -36,13 +38,27 @@ type FlowState =
  *
  * After registering an app here, the connect dialog on any agent's
  * Channels tab offers it as the serving app.
+ *
+ * "New channel app" is offered once the server confirms the caller holds
+ * `can_create_channel_app` on the organization. The list shows only the
+ * apps the caller may view (their creator, anyone granted viewer on one,
+ * and the organization's admins), so a caller who may not create channel
+ * apps is told that the organization's admins manage them rather than that
+ * none is registered.
  */
 export function ChannelAppsSection() {
   const headingId = useId();
   const org = useActiveOrgSlug();
+  const orgId = useActiveOrgId();
   // Channel installs (the consumer of these credentials) are cloud-only;
   // gate the whole section the way the Channels tab gates connects.
   const installsAvailable = useDeploymentMode() === "cloud";
+  const createCheck = useCheckPermission(
+    installsAvailable && orgId ? { kind: "organization", id: orgId } : null,
+    "can_create_channel_app",
+  );
+  const canCreate = !createCheck.isLoading && createCheck.allowed;
+  const deniedCreate = !createCheck.isLoading && !createCheck.allowed;
 
   const [flow, setFlow] = useState<FlowState>({ phase: "idle" });
   const listRefetchRef = useRef<(() => void) | null>(null);
@@ -82,7 +98,7 @@ export function ChannelAppsSection() {
           Channel Apps
         </h2>
 
-        {installsAvailable && org && flow.phase === "idle" && (
+        {installsAvailable && org && canCreate && flow.phase === "idle" && (
           <button
             type="button"
             onClick={() => setFlow({ phase: "creating" })}
@@ -127,6 +143,7 @@ export function ChannelAppsSection() {
           org={org}
           onEdit={(app) => setFlow({ phase: "editing", channelApp: app })}
           onRefetchRef={handleRefetchRef}
+          emptyState={deniedCreate ? CHANNEL_APPS_MANAGED_BY_ADMINS : undefined}
         />
       )}
     </section>