@stigmer/react 3.7.0 → 3.9.0

package/src/attachment/vision-fit.ts

@@ -0,0 +1,90 @@
+/**
+ * Resolution policy for images attached to agent executions — the pure math
+ * behind {@link prepareImageForVision}.
+ *
+ * Vision providers cap what they will actually look at: Anthropic's standard
+ * tier downscales anything beyond a 1568 px long edge or ~1.15 megapixels
+ * before the model sees it (OpenAI's high-detail tiling lands in the same
+ * range). Shrinking to that ceiling in the browser is therefore
+ * quality-neutral — the provider would do it anyway — while cutting a 4-10 MB
+ * screenshot paste to a few hundred KB before it ever hits the wire.
+ *
+ * Deliberately NOT named "budget": in this codebase *vision budget* means the
+ * runner's per-turn byte/count budget (`VisionBudget` in the runner's
+ * `shared/attachment-vision.ts`, 3 MiB per image raw). That byte cap stays
+ * the runner's concern alone; this module bounds pixels, the provider's
+ * concern. Two limits, one owner each, no constants to drift.
+ */
+
+/**
+ * Maximum long-edge length, mirroring Anthropic's standard-tier limit.
+ * @see https://platform.claude.com/docs/en/build-with-claude/vision
+ */
+export const MAX_VISION_LONG_EDGE_PX = 1568;
+
+/**
+ * Maximum total pixels, mirroring Anthropic's standard-tier visual-token
+ * ceiling (1568 tokens ≈ 1.15 megapixels). For nearly all photos and
+ * screenshots this — not the edge limit — is the binding constraint: a
+ * 1920×1080 screenshot fits the edge limit but still resizes to 1456×819.
+ */
+export const MAX_VISION_PIXELS = 1_150_000;
+
+/** Integer pixel dimensions produced by {@link fitToVisionResolution}. */
+export interface VisionFitSize {
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * True when an image of these dimensions would be downscaled by the
+ * provider — i.e. when resizing it ourselves loses nothing.
+ */
+export function exceedsVisionResolution(width: number, height: number): boolean {
+  return (
+    width * height > MAX_VISION_PIXELS ||
+    Math.max(width, height) > MAX_VISION_LONG_EDGE_PX
+  );
+}
+
+/**
+ * The largest size that fits both vision limits while preserving aspect
+ * ratio. Never upscales: dimensions already within the limits come back
+ * unchanged. Mirrors Anthropic's published "max API fit" computation.
+ *
+ * Degenerate inputs (zero, negative, or non-finite dimensions) come back
+ * unchanged — the caller's decode has already failed or will fail, and this
+ * module never turns a bad input into a crash.
+ */
+export function fitToVisionResolution(width: number, height: number): VisionFitSize {
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    return { width, height };
+  }
+  if (!exceedsVisionResolution(width, height)) {
+    return { width, height };
+  }
+
+  const aspect = width / height;
+
+  // Largest size under the pixel ceiling at this aspect ratio.
+  let fitHeight = Math.sqrt(MAX_VISION_PIXELS / aspect);
+  let fitWidth = fitHeight * aspect;
+
+  // The edge limit takes over only for extreme aspect ratios (panoramas,
+  // tall phone screenshots), where the pixel-fitted size still has a long
+  // edge beyond the cap.
+  if (Math.max(fitWidth, fitHeight) > MAX_VISION_LONG_EDGE_PX) {
+    if (fitWidth >= fitHeight) {
+      fitWidth = MAX_VISION_LONG_EDGE_PX;
+      fitHeight = fitWidth / aspect;
+    } else {
+      fitHeight = MAX_VISION_LONG_EDGE_PX;
+      fitWidth = fitHeight * aspect;
+    }
+  }
+
+  return {
+    width: Math.max(1, Math.floor(Math.min(fitWidth, width))),
+    height: Math.max(1, Math.floor(Math.min(fitHeight, height))),
+  };
+}

package/src/channel/AgentChannelsPanel.tsx

@@ -1,14 +1,16 @@
 "use client";
 
 import { useCallback, useState } from "react";
-import { FileCode2, KeyRound, LayoutTemplate, MessageSquare, MoreHorizontal, Trash2 } from "lucide-react";
+import { FileCode2, KeyRound, LayoutTemplate, MessageSquare, MoreHorizontal, Share2, Trash2 } from "lucide-react";
 import { cn } from "@stigmer/theme";
 import { getUserMessage } from "@stigmer/sdk";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
 import type { ChannelApp } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
 import { AgentChannelInstallState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/status_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { toast } from "../feedback/toast.js";
+import { useManageAccess } from "../access/useManageAccess.js";
 import { ActionMenu } from "../action-menu/index.js";
 import { Button } from "../button/Button.js";
 import { EmptyState } from "../empty-state/EmptyState.js";
@@ -467,6 +469,24 @@ function ChannelCard({
     "can_delete",
   );
 
+  // The channel's canonical access-management home (channel-conversations
+  // F-11): a participant grant covers every conversation on the channel,
+  // so the affordance belongs on the channel card. The conversation
+  // header's "Channel access" button is the point-of-need shortcut to
+  // the same dialog. Self-gates on can_view_access — `action` is null
+  // for viewers who may not see the access list.
+  const access = useManageAccess({
+    resource: id
+      ? {
+          kind: ApiResourceKind.agent_channel,
+          kindString: "agent_channel",
+          id,
+          org: meta?.org ?? "",
+          name: meta?.name || meta?.slug,
+        }
+      : null,
+  });
+
   // On/off is a full-input save with only `enabled` flipped —
   // agentChannelToInput guarantees the toggle can never wipe the agent
   // reference or the provider marker (the fails-closed posture shares use).
@@ -538,10 +558,20 @@ function ChannelCard({
               <ActionMenu.Item
                 icon={<MessageSquare />}
                 onSelect={onViewConversations}
+                /* "Sessions", deliberately not "Conversations": this
+                   dialog is the session-level forensics view (which
+                   sessions served a conversation). The word
+                   Conversations belongs to the top-level customer
+                   surface (channel-conversations DD-004 D-g). */
                 data-cursor-target="channel-conversations"
               >
-                Conversations
+                Sessions
               </ActionMenu.Item>
+              {access.action && (
+                <ActionMenu.Item icon={<Share2 />} onSelect={access.open}>
+                  Manage access
+                </ActionMenu.Item>
+              )}
               {/* Gated on the bar the server enforces for listTemplates
                   (ChannelMessagingReach: can_edit), and on the provider
                   declaring a template registry at all — hidden, not
@@ -591,6 +621,7 @@ function ChannelCard({
         canEdit={canEdit}
         onEditCredentials={onEditCredentials}
       />
+      {access.dialog}
     </div>
   );
 }

package/src/channel/ChannelConversationsDialog.tsx

@@ -7,6 +7,7 @@ import { cn } from "@stigmer/theme";
 import { getUserMessage } from "@stigmer/sdk";
 import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { formatRelativeTime } from "../activity/format-relative-time.js";
 import { Button } from "../button/Button.js";
 import { EmptyState } from "../empty-state/EmptyState.js";
 import { channelSessionExternalUserKey } from "../session/channelOrigin.js";
@@ -37,11 +38,19 @@ export interface ChannelConversationsDialogProps {
 }
 
 /**
- * Lists the conversations a channel created — the Slack/WhatsApp sessions
- * the channel runtime owns, visible to exactly the channel's viewers (the
- * connector and org admins; design decision 012).
+ * Lists the SESSIONS a channel created — the session-level forensics view
+ * (which execution containers served the channel's traffic), visible to
+ * exactly the channel's viewers (the connector and org admins; design
+ * decision 012).
  *
- * Each row shows the conversation subject, the external platform user it
+ * Deliberately titled "Sessions", not "Conversations": the customer-facing
+ * Conversations surface is the top-level `ConversationsWorkbench` over the
+ * conversation timeline API, which supersedes this read for that purpose
+ * (channel-conversations DD-004 D-g). This dialog remains what it actually
+ * is — the observability view underneath a conversation. The component
+ * name keeps its historical export for API stability.
+ *
+ * Each row shows the session subject, the external platform user it
  * belongs to (an opaque provider id in v1), and the last activity time.
  * Rows link to the host's session route, where `SessionViewer` renders the
  * transcript read-only (the observer audience — channel viewers hold
@@ -126,10 +135,10 @@ function ChannelConversationsDialogBody({
             id="channel-conversations-title"
             className="text-sm font-semibold text-popover-foreground"
           >
-            Conversations
+            Sessions
           </h2>
           <p className="mt-0.5 truncate text-xs text-muted-foreground">
-            What people asked {channelName} — read-only, visible to the
+            The sessions {channelName} created — read-only, visible to the
             channel&apos;s owner and org admins.
           </p>
         </div>
@@ -137,7 +146,7 @@ function ChannelConversationsDialogBody({
           variant="ghost"
           size="xs"
           onClick={onClose}
-          aria-label="Close conversations"
+          aria-label="Close sessions"
         >
           <X className="size-4" />
         </Button>
@@ -154,8 +163,8 @@ function ChannelConversationsDialogBody({
           <EmptyState
             variant="first-use"
             icon={<MessageSquare className="size-8" />}
-            title="No conversations yet"
-            description="When someone messages this channel, their conversation appears here."
+            title="No sessions yet"
+            description="When someone messages this channel, the sessions serving them appear here."
           />
         ) : (
           <ul className="space-y-1">
@@ -184,7 +193,7 @@ function ConversationRow({
   readonly session: Session;
   readonly href?: string;
 }) {
-  const subject = session.spec?.subject || "Untitled conversation";
+  const subject = session.spec?.subject || "Untitled session";
   const externalUser = channelSessionExternalUserKey(session);
   const lastActivity = lastActivityDate(session);
 
@@ -242,9 +251,9 @@ function ConversationsSkeleton() {
 }
 
 /**
- * The conversation's last activity: `statusAudit.updatedAt` (bumped on
- * every meaningful status change), falling back to `specAudit.createdAt`
- * — the recent-activity sort key, so the dialog agrees with the server's
+ * The session's last activity: `statusAudit.updatedAt` (bumped on every
+ * meaningful status change), falling back to `specAudit.createdAt` —
+ * the recent-activity sort key, so the dialog agrees with the server's
  * ordering.
  */
 function lastActivityDate(session: Session): Date | null {
@@ -253,15 +262,3 @@ function lastActivityDate(session: Session): Date | null {
     session.status?.audit?.specAudit?.createdAt;
   return ts ? timestampDate(ts) : null;
 }
-
-function formatRelativeTime(date: Date): string {
-  const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
-  if (seconds < 60) return "just now";
-  const minutes = Math.floor(seconds / 60);
-  if (minutes < 60) return `${minutes}m ago`;
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  if (days < 30) return `${days}d ago`;
-  return date.toLocaleDateString();
-}

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

@@ -419,16 +419,47 @@ describe("AgentChannelsPanel", () => {
     expect(screen.queryByRole("switch")).toBeNull();
     expect(screen.queryByRole("button", { name: /connect to slack/i })).toBeNull();
 
-    // The card menu still renders: Conversations is a viewer-level action
+    // The card menu still renders: Sessions is a viewer-level action
     // (everyone who sees the card holds can_view on the channel — the same
-    // bar as viewing its conversations, DD-012). Mutation items stay
+    // bar as viewing its sessions, DD-012). Mutation items stay
     // permission-gated and absent.
     fireEvent.click(screen.getByRole("button", { name: /actions for/i }));
-    expect(screen.getByRole("menuitem", { name: /conversations/i })).toBeTruthy();
+    expect(screen.getByRole("menuitem", { name: /sessions/i })).toBeTruthy();
     expect(screen.queryByRole("menuitem", { name: /tool credentials/i })).toBeNull();
     expect(screen.queryByRole("menuitem", { name: /disconnect/i })).toBeNull();
   });
 
+  it("offers Manage access from the card menu — the channel's canonical access home (F-11)", async () => {
+    const client = createMockStigmer({
+      channels: [makeChannel({ teamName: "Acme HQ" })],
+    });
+    // The dialog's People section lists existing grants on open.
+    (
+      client as { iamPolicy: Record<string, unknown> }
+    ).iamPolicy.listResourceAccessByPrincipal = vi
+      .fn()
+      .mockResolvedValue({ entries: [] });
+    render(
+      <Providers client={client}>
+        <AgentChannelsPanel agent={makeAgent()} />
+      </Providers>,
+    );
+    await waitFor(() => expect(screen.getByText("Support Slack")).toBeTruthy());
+
+    fireEvent.click(screen.getByRole("button", { name: /actions for/i }));
+    fireEvent.click(screen.getByRole("menuitem", { name: /manage access/i }));
+
+    // The one canonical dialog opens, and its subtitle names the channel
+    // — the scope every grant covers (a participant grant is per
+    // channel, never per conversation).
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Manage access" })).toBeTruthy(),
+    );
+    const dialog = document.querySelector("dialog");
+    expect(dialog).not.toBeNull();
+    expect(within(dialog as HTMLElement).getByText("Support Slack")).toBeTruthy();
+  });
+
   it("warns on an installed card when a tool-using agent has no credentials bound", async () => {
     const client = createMockStigmer({
       channels: [makeChannel({ teamName: "Acme HQ" })],
@@ -655,7 +686,7 @@ describe("AgentChannelsPanel", () => {
     // Slack has no template concept: hidden, not disabled — a disabled
     // item would imply the capability might one day exist there.
     expect(
-      await screen.findByRole("menuitem", { name: /conversations/i }),
+      await screen.findByRole("menuitem", { name: /sessions/i }),
     ).toBeTruthy();
     expect(screen.queryByRole("menuitem", { name: "Templates" })).toBeNull();
   });
@@ -681,7 +712,7 @@ describe("AgentChannelsPanel", () => {
     fireEvent.click(screen.getByRole("button", { name: /actions for/i }));
 
     expect(
-      await screen.findByRole("menuitem", { name: /conversations/i }),
+      await screen.findByRole("menuitem", { name: /sessions/i }),
     ).toBeTruthy();
     expect(screen.queryByRole("menuitem", { name: "Templates" })).toBeNull();
   });

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

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { render, screen, cleanup, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
 import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
 import { StigmerContext } from "../../context";
 import { FetchCacheContext } from "../../internal/FetchCacheProvider";
@@ -92,11 +93,47 @@ describe("ChannelConversationsDialog", () => {
     expect(screen.queryAllByRole("link")).toHaveLength(0);
   });
 
+  it("titles itself Sessions and falls back to Untitled session (F-04, DD-004 D-g)", async () => {
+    // The word "conversation" belongs to the customer-facing surface;
+    // this dialog is the session-level forensics view.
+    const listByChannel = vi.fn().mockResolvedValue({
+      entries: [makeChannelSession("ses_1", "")],
+    });
+
+    renderDialog(listByChannel);
+
+    expect(screen.getByRole("heading", { name: "Sessions" })).toBeDefined();
+    await waitFor(() => expect(screen.getByText("Untitled session")).toBeDefined());
+    expect(screen.queryByText("Untitled conversation")).toBeNull();
+  });
+
+  it("formats activity in the shared compact style, matching the inbox (F-04)", async () => {
+    const fiveMinutesAgo = new Date(Date.now() - 5 * 60_000);
+    const listByChannel = vi.fn().mockResolvedValue({
+      entries: [
+        {
+          ...makeChannelSession("ses_1", "Deploy help"),
+          status: {
+            audit: { statusAudit: { updatedAt: timestampFromDate(fiveMinutesAgo) } },
+          },
+        },
+      ],
+    });
+
+    renderDialog(listByChannel);
+
+    // The shared helper's compact single-unit style ("5m"), not the
+    // retired local formatter's "5m ago" — one time vocabulary across
+    // the channel dialog and the conversations inbox.
+    await waitFor(() => expect(screen.getByText("5m")).toBeDefined());
+    expect(screen.queryByText("5m ago")).toBeNull();
+  });
+
   it("shows the empty state when nobody has messaged the channel", async () => {
     renderDialog(vi.fn().mockResolvedValue({ entries: [] }));
 
     await waitFor(() =>
-      expect(screen.getByText("No conversations yet")).toBeDefined(),
+      expect(screen.getByText("No sessions yet")).toBeDefined(),
     );
   });
 

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

@@ -124,6 +124,32 @@ describe("agentChannelToInput", () => {
     expect(input).not.toHaveProperty("appRef");
   });
 
+  it("carries run_config — the toggle must never wipe an API-set execution override", () => {
+    const channel = makeChannel({
+      spec: {
+        agentRef: { org: "acme", slug: "support-agent" },
+        enabled: true,
+        providerConfig: { case: "slack", value: {} },
+        // Set via CLI/API (stigmer/stigmer#360); no console surface edits
+        // it, so it must ride through the full-input rebuild opaquely.
+        runConfig: { modelName: "gpt-5-mini", maxCostUsd: 0.25, maxToolRounds: 8 },
+      },
+    });
+
+    const input = agentChannelToInput(channel);
+    expect(input.runConfig).toEqual({
+      modelName: "gpt-5-mini",
+      maxCostUsd: 0.25,
+      maxToolRounds: 8,
+      serviceTier: undefined,
+    });
+  });
+
+  it("omits runConfig entirely when the channel carries none", () => {
+    const input = agentChannelToInput(makeChannel());
+    expect(input).not.toHaveProperty("runConfig");
+  });
+
   it("omits the slack marker when the provider config is absent", () => {
     const channel = makeChannel({
       spec: {

package/src/channel/providers.ts

@@ -55,6 +55,29 @@ export interface ChannelProviderDescriptor {
    * there one day.
    */
   readonly supportsMessageTemplates: boolean;
+  /**
+   * Whether staff can reply into and take over live conversations on
+   * this provider. Mirrors the server's `ProactiveMessageSender`
+   * registry — the same registry behind `reply`/`takeOver` refusing
+   * senderless providers with FAILED_PRECONDITION ("this channel's
+   * provider has no send lane for staff messages").
+   *
+   * Unlike templates, `false` here renders as DISABLED-with-explanation
+   * rather than hidden: the send lane is a planned capability (the
+   * suppression doors are already wired provider-blind server-side), so
+   * the affordance should say why it is off, not pretend it cannot
+   * exist. The server refusal stays the authoritative backstop.
+   */
+  readonly supportsStaffReplies: boolean;
+  /**
+   * Whether the conversation timeline includes the CUSTOMER's own
+   * messages on this provider. Mirrors the cloud stitcher's inbound
+   * sources: WhatsApp inbound rides a per-conversation event store;
+   * Slack's inbound lane has no timeline source yet, so its timeline
+   * shows only replies, sends, and internal events. Consumers render an
+   * honest notice instead of a silently one-sided thread.
+   */
+  readonly timelineIncludesCustomerMessages: boolean;
 }
 
 /**
@@ -73,6 +96,8 @@ export const CHANNEL_PROVIDERS: readonly ChannelProviderDescriptor[] = [
     Icon: SlackMarkIcon,
     installStyle: "redirect",
     supportsMessageTemplates: false,
+    supportsStaffReplies: false,
+    timelineIncludesCustomerMessages: false,
   },
   {
     id: "whatsapp",
@@ -80,6 +105,8 @@ export const CHANNEL_PROVIDERS: readonly ChannelProviderDescriptor[] = [
     Icon: WhatsAppMarkIcon,
     installStyle: "direct",
     supportsMessageTemplates: true,
+    supportsStaffReplies: true,
+    timelineIncludesCustomerMessages: true,
   },
 ];
 

package/src/channel/useSaveAgentChannel.ts

@@ -23,10 +23,11 @@ import { toError } from "../internal/toError.js";
  * carries its declared `phone_number_id`. Dropping the arm is never an
  * option — the provider oneof is immutable server-side, so a save
  * without it would be refused outright. The channel's bound tool
- * credentials (`environment_refs`) and its channel-app binding
- * (`app_ref`) carry over too — apply semantics would otherwise silently
- * unbind them on every toggle (and an installed channel's app_ref is
- * frozen server-side, so dropping it would refuse the save outright).
+ * credentials (`environment_refs`), its channel-app binding
+ * (`app_ref`), and its per-channel execution override (`run_config`)
+ * carry over too — apply semantics would otherwise silently unbind
+ * them on every toggle (and an installed channel's app_ref is frozen
+ * server-side, so dropping it would refuse the save outright).
  */
 export function agentChannelToInput(channel: AgentChannel): AgentChannelInput {
   const metadata = channel.metadata;
@@ -65,6 +66,19 @@ export function agentChannelToInput(channel: AgentChannel): AgentChannelInput {
           })),
         }
       : {}),
+    // The console does not edit run_config (yet) — it rides through
+    // opaquely so a settings save or pause/resume toggle never wipes an
+    // override set via the CLI or API.
+    ...(spec?.runConfig
+      ? {
+          runConfig: {
+            modelName: spec.runConfig.modelName,
+            maxCostUsd: spec.runConfig.maxCostUsd,
+            maxToolRounds: spec.runConfig.maxToolRounds,
+            serviceTier: spec.runConfig.serviceTier,
+          },
+        }
+      : {}),
   };
 }
 

package/src/composer/ComposerToolbar.tsx

@@ -45,7 +45,7 @@ export interface ComposerToolbarProps {
   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. */
+  /** Enables the fast-tier switch inside the model selector's options area. */
   readonly onServiceTierChange?: (tier: ServiceTierOption) => void;
 
   // -- Right group: Secondary actions (icon-only) ---------------------------