@stigmer/react 3.5.3 → 3.7.0

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

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import { renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { AgentChannelInstallState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/status_pb";
+import { DeploymentModeContext } from "../../deployment-mode";
+import { useChannelTemplateReadiness } from "../useChannelTemplateReadiness";
+
+function makeChannel(overrides?: {
+  installState?: AgentChannelInstallState;
+  enabled?: boolean;
+  proactiveMessagingEnabled?: boolean;
+}): AgentChannel {
+  return {
+    metadata: { id: "ach_1", org: "acme", slug: "wa-main" },
+    spec: {
+      enabled: overrides?.enabled ?? true,
+      proactiveMessagingEnabled: overrides?.proactiveMessagingEnabled ?? true,
+    },
+    status: {
+      installState:
+        overrides?.installState ?? AgentChannelInstallState.installed,
+    },
+  } as unknown as AgentChannel;
+}
+
+function wrapper(mode: "cloud" | "local" = "cloud") {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <DeploymentModeContext.Provider value={mode}>
+        {children}
+      </DeploymentModeContext.Provider>
+    );
+  };
+}
+
+function readinessOf(
+  channel: AgentChannel,
+  mode: "cloud" | "local" = "cloud",
+) {
+  const { result } = renderHook(() => useChannelTemplateReadiness(channel), {
+    wrapper: wrapper(mode),
+  });
+  return result.current;
+}
+
+describe("useChannelTemplateReadiness", () => {
+  it("is ready for an installed, enabled, proactive channel on cloud", () => {
+    expect(readinessOf(makeChannel())).toEqual({ status: "ready" });
+  });
+
+  it("is cloud-only on a local deployment — the template registry is cloud runtime", () => {
+    expect(readinessOf(makeChannel(), "local")).toEqual({
+      status: "cloud-only",
+    });
+  });
+
+  it("is not-installed for a pending install", () => {
+    expect(
+      readinessOf(
+        makeChannel({
+          installState: AgentChannelInstallState.pending_install,
+        }),
+      ),
+    ).toEqual({ status: "not-installed" });
+  });
+
+  it("is not-installed for a revoked install — coarse on purpose, describeChannel carries the distinction", () => {
+    expect(
+      readinessOf(
+        makeChannel({ installState: AgentChannelInstallState.revoked }),
+      ),
+    ).toEqual({ status: "not-installed" });
+  });
+
+  it("is channel-off when the serving switch is off", () => {
+    expect(readinessOf(makeChannel({ enabled: false }))).toEqual({
+      status: "channel-off",
+    });
+  });
+
+  it("is not-proactive when the grant is missing", () => {
+    expect(
+      readinessOf(makeChannel({ proactiveMessagingEnabled: false })),
+    ).toEqual({ status: "not-proactive" });
+  });
+
+  // The gate order is the server's (ChannelMessagingReach.resolveDirect:
+  // installed → enabled → proactive). A channel failing several gates
+  // must report the FIRST, so the teaching state names the next fix.
+  it("resolves gates in the server's order — first failure wins", () => {
+    expect(
+      readinessOf(
+        makeChannel({
+          installState: AgentChannelInstallState.pending_install,
+          enabled: false,
+          proactiveMessagingEnabled: false,
+        }),
+        "local",
+      ),
+    ).toEqual({ status: "cloud-only" });
+
+    expect(
+      readinessOf(
+        makeChannel({
+          installState: AgentChannelInstallState.pending_install,
+          enabled: false,
+          proactiveMessagingEnabled: false,
+        }),
+      ),
+    ).toEqual({ status: "not-installed" });
+
+    expect(
+      readinessOf(
+        makeChannel({ enabled: false, proactiveMessagingEnabled: false }),
+      ),
+    ).toEqual({ status: "channel-off" });
+  });
+
+  it("treats a channel with no status/spec as not yet installed", () => {
+    const bare = { metadata: { id: "ach_2" } } as unknown as AgentChannel;
+    expect(readinessOf(bare)).toEqual({ status: "not-installed" });
+  });
+});

package/src/channel/index.ts

@@ -17,6 +17,9 @@ export {
 } from "./providerPresentation.js";
 export type { ChannelProviderPresentation } from "./providerPresentation.js";
 
+export { templateStatusPhase, splitTemplateBody } from "./templatePresentation.js";
+export type { TemplateBodySegment } from "./templatePresentation.js";
+
 export { useAgentChannel } from "./useAgentChannel.js";
 export type { UseAgentChannelReturn } from "./useAgentChannel.js";
 
@@ -43,9 +46,18 @@ export type {
 
 export { useChannelToolReadiness } from "./useChannelToolReadiness.js";
 
+export { useChannelTemplateReadiness } from "./useChannelTemplateReadiness.js";
+export type { ChannelTemplateReadiness } from "./useChannelTemplateReadiness.js";
+
 export { useChannelSessions } from "./useChannelSessions.js";
 export type { UseChannelSessionsReturn } from "./useChannelSessions.js";
 
+export { useChannelTemplateList } from "./useChannelTemplateList.js";
+export type {
+  UseChannelTemplateListOptions,
+  UseChannelTemplateListReturn,
+} from "./useChannelTemplateList.js";
+
 export { AgentChannelsPanel } from "./AgentChannelsPanel.js";
 export type { AgentChannelsPanelProps } from "./AgentChannelsPanel.js";
 
@@ -63,3 +75,6 @@ export type { ChannelToolCredentialsProps } from "./ChannelToolCredentials.js";
 
 export { ChannelConversationsDialog } from "./ChannelConversationsDialog.js";
 export type { ChannelConversationsDialogProps } from "./ChannelConversationsDialog.js";
+
+export { ChannelTemplatesDialog } from "./ChannelTemplatesDialog.js";
+export type { ChannelTemplatesDialogProps } from "./ChannelTemplatesDialog.js";

package/src/channel/providers.ts

@@ -43,6 +43,18 @@ export interface ChannelProviderDescriptor {
   readonly Icon: ComponentType<{ readonly className?: string }>;
   /** How this provider's install flow runs. */
   readonly installStyle: ChannelInstallStyle;
+  /**
+   * Whether this provider has a message-template registry the console
+   * can list (`listTemplates`). Mirrors the server's proactive-sender
+   * registry, which is the de-facto provider filter behind that RPC —
+   * a provider with no registered sender answers `PROVIDER_UNSUPPORTED`.
+   *
+   * `false` for Slack is not a gap: Slack has no template concept at
+   * all, so consumers hide the Templates affordance entirely rather
+   * than disable it — a disabled item would falsely imply it may work
+   * there one day.
+   */
+  readonly supportsMessageTemplates: boolean;
 }
 
 /**
@@ -55,8 +67,20 @@ export interface ChannelProviderDescriptor {
  * demos. A third entry is the signal to fold these into a provider menu.
  */
 export const CHANNEL_PROVIDERS: readonly ChannelProviderDescriptor[] = [
-  { id: "slack", label: "Slack", Icon: SlackMarkIcon, installStyle: "redirect" },
-  { id: "whatsapp", label: "WhatsApp", Icon: WhatsAppMarkIcon, installStyle: "direct" },
+  {
+    id: "slack",
+    label: "Slack",
+    Icon: SlackMarkIcon,
+    installStyle: "redirect",
+    supportsMessageTemplates: false,
+  },
+  {
+    id: "whatsapp",
+    label: "WhatsApp",
+    Icon: WhatsAppMarkIcon,
+    installStyle: "direct",
+    supportsMessageTemplates: true,
+  },
 ];
 
 /**

package/src/channel/templatePresentation.ts

@@ -0,0 +1,82 @@
+import type { StatusPhase } from "../resource-workbench/types.js";
+
+/**
+ * Display helpers for provider message templates — the template
+ * counterpart of {@link ChannelProviderPresentation}'s module split:
+ * `ChannelTemplatesDialog` renders, this module decides how a
+ * provider-verbatim template projects onto the SDK's display
+ * vocabulary. Pure functions, one writer each.
+ */
+
+/**
+ * Map a provider-verbatim template status onto a {@link StatusPhase}
+ * for `StatusBadge` coloring.
+ *
+ * The wire carries the provider's own vocabulary, never a Stigmer enum
+ * (DD-003 D6) — so the caller renders the verbatim status string as the
+ * badge label and uses this phase only for the color. WhatsApp's
+ * observed set exceeds the documented five (IN_APPEAL, LIMIT_EXCEEDED,
+ * PENDING_DELETION, DELETED occur, and Meta can add more), so unknown
+ * statuses deliberately land on `draft` — a neutral tone that renders
+ * the provider's word without claiming to understand it.
+ */
+export function templateStatusPhase(status: string): StatusPhase {
+  switch (status) {
+    case "APPROVED":
+      return "ready";
+    case "PENDING":
+    case "IN_APPEAL":
+      return "pending";
+    case "PAUSED":
+    case "LIMIT_EXCEEDED":
+      return "degraded";
+    case "REJECTED":
+    case "DISABLED":
+      return "failed";
+    case "PENDING_DELETION":
+    case "DELETED":
+      return "disabled";
+    default:
+      return "draft";
+  }
+}
+
+/** One segment of a template body: literal text or a `{{...}}` placeholder. */
+export interface TemplateBodySegment {
+  readonly kind: "text" | "placeholder";
+  /** The verbatim slice, braces included for placeholders (`"{{1}}"`). */
+  readonly value: string;
+}
+
+/**
+ * The provider's placeholder shape: `{{1}}` (positional) or
+ * `{{customer_name}}` (named). Single braces and unbalanced braces are
+ * literal text — the provider would not have accepted them either.
+ */
+const PLACEHOLDER = /\{\{\s*[A-Za-z0-9_]+\s*\}\}/g;
+
+/**
+ * Split a template body into text and placeholder segments so the
+ * placeholders — the parts the agent fills at send time — can render
+ * visually distinct from the literal copy.
+ *
+ * The concatenation of all segment values is always the input,
+ * verbatim: this function classifies, it never rewrites.
+ */
+export function splitTemplateBody(
+  body: string,
+): readonly TemplateBodySegment[] {
+  const segments: TemplateBodySegment[] = [];
+  let lastIndex = 0;
+  for (const match of body.matchAll(PLACEHOLDER)) {
+    if (match.index > lastIndex) {
+      segments.push({ kind: "text", value: body.slice(lastIndex, match.index) });
+    }
+    segments.push({ kind: "placeholder", value: match[0] });
+    lastIndex = match.index + match[0].length;
+  }
+  if (lastIndex < body.length) {
+    segments.push({ kind: "text", value: body.slice(lastIndex) });
+  }
+  return segments;
+}

package/src/channel/useChannelTemplateList.ts

@@ -0,0 +1,123 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { ChannelTemplate } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import { ListChannelTemplatesInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Options for {@link useChannelTemplateList}. */
+export interface UseChannelTemplateListOptions {
+  /**
+   * When `true`, only templates the provider will accept for sending
+   * are returned (WhatsApp: status APPROVED). The console leaves it
+   * unset to render every status with its badge; agent-composition
+   * surfaces set it so a model never drafts against a paused or
+   * pending template.
+   */
+  readonly approvedOnly?: boolean;
+}
+
+/** Return value of {@link useChannelTemplateList}. */
+export interface UseChannelTemplateListReturn {
+  /**
+   * The channel provider's templates, verbatim, in provider order.
+   * Empty while loading, on error, and when the registry answered with
+   * no templates — `templates.length === 0 && !isLoading && !error`
+   * means the provider reported none, which callers should phrase as
+   * "none found" rather than "none exist" (an empty success is
+   * indistinguishable from a filtered or truncated one).
+   */
+  readonly templates: readonly ChannelTemplate[];
+  /** `true` while the initial fetch is in flight and no data is shown. */
+  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;
+  /** Re-fetch the templates from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * How often to re-read the registry while any template is PENDING.
+ * Matches the server's template-cache TTL (60s) — polling faster only
+ * re-reads a cached answer.
+ */
+const PENDING_POLL_INTERVAL_MS = 60_000;
+
+/**
+ * Data hook that lists a channel's message templates as the channel's
+ * provider registry reports them (`listTemplates`) — every field
+ * provider-verbatim, including approval `status`, the provider's
+ * `rejectionReason`, and Stigmer's own `unsupportedReason` (why this
+ * platform version cannot send an otherwise-approved template).
+ *
+ * The channel is addressed by `slug` + `org` (not id), because that is
+ * the RPC's key — the provider registry is derived from the channel's
+ * phone number, not stored on any Stigmer resource. Pass an empty
+ * `channelSlug` or `org` to skip fetching (stable no-op).
+ *
+ * While any entry is PENDING the hook polls every 60 seconds — the
+ * server's registry-cache TTL, so a faster interval would only re-read
+ * a cached answer. There is deliberately no `refetchInterval` option:
+ * the pending-only conditional poll is the hook's policy, and
+ * `approvedOnly` (a wire field) is the only knob exposed.
+ *
+ * Results are never cached across mounts: a template's approval status
+ * can change on the provider's side at any time, and rendering a stale
+ * "APPROVED" is exactly what this surface must not do.
+ *
+ * @example
+ * ```tsx
+ * const { templates, isLoading, error } = useChannelTemplateList(
+ *   channel.metadata?.slug ?? "",
+ *   channel.metadata?.org ?? "",
+ * );
+ * ```
+ */
+export function useChannelTemplateList(
+  channelSlug: string,
+  org: string,
+  options?: UseChannelTemplateListOptions,
+): UseChannelTemplateListReturn {
+  const stigmer = useStigmer();
+  const approvedOnly = options?.approvedOnly ?? false;
+
+  // The pending-only poll rides useFetch's own guarded interval (the
+  // ONE polling implementation) rather than a second setInterval here.
+  // The interval cannot be derived inline — it depends on the data the
+  // same useFetch call returns — so it round-trips through state: data
+  // arrives, the effect below flips the interval, useFetch re-arms.
+  const [pollInterval, setPollInterval] = useState<number | false>(false);
+
+  const fetchFn =
+    channelSlug && org
+      ? async () => {
+          const result = await stigmer.agentChannel.listTemplates(
+            create(ListChannelTemplatesInputSchema, {
+              channel: channelSlug,
+              org,
+              approvedOnly,
+            }),
+          );
+          return result.entries;
+        }
+      : null;
+
+  const { data: templates, isLoading, isRefetching, error, refetch } =
+    useFetch(
+      fetchFn,
+      [channelSlug, org, approvedOnly, stigmer],
+      [] as ChannelTemplate[],
+      { refetchInterval: pollInterval },
+    );
+
+  const hasPending = templates.some((t) => t.status === "PENDING");
+  useEffect(() => {
+    setPollInterval(hasPending ? PENDING_POLL_INTERVAL_MS : false);
+  }, [hasPending]);
+
+  return { templates, isLoading, isRefetching, error, refetch };
+}

package/src/channel/useChannelTemplateReadiness.ts

@@ -0,0 +1,69 @@
+"use client";
+
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { AgentChannelInstallState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/status_pb";
+import { useDeploymentMode } from "../deployment-mode.js";
+
+/**
+ * Whether a channel can answer a template-registry read
+ * (`listTemplates`), and if not, which precondition fails first.
+ *
+ * - `cloud-only` — the deployment is not cloud; the template registry
+ *   is part of the cloud channel runtime.
+ * - `not-installed` — the provider install has not completed (covers
+ *   both pending and revoked; render the per-provider
+ *   `describeChannel` sentence, which already distinguishes them).
+ * - `channel-off` — the owner's serving switch (`spec.enabled`) is off.
+ * - `not-proactive` — `spec.proactive_messaging_enabled` is not set;
+ *   business-initiated messaging (and with it the template surface)
+ *   is not granted on this channel.
+ * - `ready` — the read can be made.
+ */
+export type ChannelTemplateReadiness =
+  | { readonly status: "cloud-only" }
+  | { readonly status: "not-installed" }
+  | { readonly status: "channel-off" }
+  | { readonly status: "not-proactive" }
+  | { readonly status: "ready" };
+
+/**
+ * Resolve whether a channel's template registry can be read, without a
+ * network call — the courtesy pre-check for the Templates surface.
+ *
+ * Mirrors the server's own gate order for `listTemplates`
+ * (`ChannelMessagingReach.resolveDirect`: installed → enabled →
+ * proactive grant), answering from fields already on the fetched
+ * {@link AgentChannel}. The server stays authoritative: a `ready`
+ * verdict here only means the call is worth making, and whatever the
+ * server then says wins.
+ *
+ * Two shape choices are deliberate. `channel-off` and `not-proactive`
+ * are split although the server collapses them into one refusal —
+ * their fixes differ (flip the card's serving switch vs. grant
+ * `proactive_messaging_enabled`). And `not-installed` stays coarse
+ * across pending/revoked, because `providerPresentation`'s
+ * `describeChannel` already renders the right sentence for each.
+ *
+ * @example
+ * ```tsx
+ * const readiness = useChannelTemplateReadiness(channel);
+ * if (readiness.status !== "ready") return <TeachingState ... />;
+ * ```
+ */
+export function useChannelTemplateReadiness(
+  channel: AgentChannel,
+): ChannelTemplateReadiness {
+  const deploymentMode = useDeploymentMode();
+
+  if (deploymentMode !== "cloud") return { status: "cloud-only" };
+  if (
+    channel.status?.installState !== AgentChannelInstallState.installed
+  ) {
+    return { status: "not-installed" };
+  }
+  if (!channel.spec?.enabled) return { status: "channel-off" };
+  if (!channel.spec.proactiveMessagingEnabled) {
+    return { status: "not-proactive" };
+  }
+  return { status: "ready" };
+}

package/src/composer/ComposerToolbar.tsx

@@ -6,6 +6,7 @@ import { ConfigureMenu, type ConfigureMenuItem } from "./ConfigureMenu.js";
 import { ModelSelector } from "../models/ModelSelector.js";
 import { HarnessSelector } from "../models/HarnessSelector.js";
 import type { HarnessOption } from "../models/harness.js";
+import type { ServiceTierOption } from "../models/service-tier.js";
 import { InteractionModePicker, type InteractionModeOption } from "./InteractionModePicker.js";
 import {
   PaperclipIcon,
@@ -42,6 +43,10 @@ export interface ComposerToolbarProps {
   readonly showModelSelector: boolean;
   readonly modelId?: string;
   readonly onModelChange: (id: string) => void;
+  /** Current service tier for the selected model (#357). */
+  readonly serviceTier?: ServiceTierOption;
+  /** Enables the fast-tier toggle inside the model selector. */
+  readonly onServiceTierChange?: (tier: ServiceTierOption) => void;
 
   // -- Right group: Secondary actions (icon-only) ---------------------------
 
@@ -115,6 +120,8 @@ export function ComposerToolbar({
   showModelSelector,
   modelId,
   onModelChange,
+  serviceTier,
+  onServiceTierChange,
 }: ComposerToolbarProps) {
   const showHarnessSeparate = showHarnessSelector && !showModelSelector;
 
@@ -146,6 +153,8 @@ export function ComposerToolbar({
             harness={showHarnessSelector ? undefined : harness}
             initialHarness={showHarnessSelector ? harness : undefined}
             onHarnessChange={showHarnessSelector ? onHarnessChange : undefined}
+            serviceTier={serviceTier}
+            onServiceTierChange={onServiceTierChange}
             disabled={disabled}
           />
         )}

package/src/composer/SessionComposer.tsx

@@ -7,6 +7,7 @@ import { useComposer } from "./useComposer.js";
 import { ComposerToolbar } from "./ComposerToolbar.js";
 import { type ConfigureMenuItem } from "./ConfigureMenu.js";
 import type { HarnessOption } from "../models/harness.js";
+import type { ServiceTierOption } from "../models/service-tier.js";
 import type { InteractionModeOption } from "./InteractionModePicker.js";
 import { parseModelKey } from "../models/registry.js";
 import { WorkspaceEditor } from "../workspace/WorkspaceEditor.js";
@@ -147,6 +148,14 @@ export interface SessionComposerSubmitContext {
    * Pass to execution creation as `execution_config.interaction_mode`.
    */
   readonly interactionMode?: InteractionModeOption;
+  /**
+   * Service tier the user actively selected for this execution
+   * (stigmer/stigmer#357). Only ever `"fast"` — an untouched toggle means
+   * "platform default" and is carried as `undefined`, preserving the
+   * unspecified-vs-explicit distinction all the way to the ledger.
+   * Pass to execution creation as `execution_config.service_tier`.
+   */
+  readonly serviceTier?: ServiceTierOption;
   /**
    * Workspace-relative file paths the user referenced via drag-to-reference.
    *
@@ -622,6 +631,11 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
     setModelIdRaw(id);
   }, []);
 
+  // Service tier (#357): composer-local state like modelId. "standard" is
+  // the resting default; the ModelSelector's fail-safe resets it when the
+  // user switches to a model without a fast tier.
+  const [serviceTier, setServiceTier] = useState<ServiceTierOption>("standard");
+
   const [displayNames, setDisplayNames] = useState<Map<string, string>>(
     () => new Map(),
   );
@@ -850,13 +864,20 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
           : undefined);
       const hasFileRefs = enableFileReferences && fileRefs.hasRefs;
       const buildFromPlan = overrides?.buildFromPlan;
+      // Carried only when the user actively chose fast: an untouched
+      // toggle means "platform default" (which resolves to standard in
+      // the runner), and the UNSPECIFIED-vs-explicit distinction is
+      // load-bearing telemetry (#357).
+      const effectiveServiceTier = serviceTier === "fast" ? serviceTier : undefined;
 
       const context: SessionComposerSubmitContext | undefined =
         hasEnv || hasAttachments || effectiveMode || hasFileRefs || buildFromPlan
+        || effectiveServiceTier
           ? {
               runtimeEnv: hasEnv ? env : undefined,
               attachments: hasAttachments ? attachmentInputs : undefined,
               interactionMode: effectiveMode,
+              serviceTier: effectiveServiceTier,
               workspaceFileRefs: hasFileRefs ? [...fileRefs.refs] : undefined,
               buildFromPlan,
             }
@@ -874,7 +895,7 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
         fileRefs.clear();
       }
     },
-    [onSubmit, modelId, stigmer, agentSetup.state, mcpSetup.pendingRuntimeEnv, sessionVariables, enableAttachments, attachments, personalEnv, showInteractionModePicker, interactionMode],
+    [onSubmit, modelId, serviceTier, stigmer, agentSetup.state, mcpSetup.pendingRuntimeEnv, sessionVariables, enableAttachments, attachments, personalEnv, showInteractionModePicker, interactionMode],
   );
 
   const composer = useComposer({
@@ -1614,6 +1635,8 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
           showModelSelector={showModelSelector}
           modelId={modelId}
           onModelChange={handleModelChange}
+          serviceTier={serviceTier}
+          onServiceTierChange={setServiceTier}
         />
       </div>
     </div>