@stigmer/react 3.12.1 → 3.12.2

package/src/session/SessionViewer.tsx

@@ -61,7 +61,8 @@ import {
 import type { SetupTabProps } from "./facets/SetupTab.js";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { RuntimeEnvProvider } from "./runtime-env.js";
-import type { SessionAudience } from "./audience.js";
+import type { SessionAudience, SessionPanelMode } from "./audience.js";
+import type { SessionRunConfig } from "./run-config.js";
 
 /**
  * Where the approved plan mounts in the implement execution's workspace —
@@ -226,6 +227,66 @@ export interface SessionViewerProps {
    * @default "integrator"
    */
   readonly audience?: SessionAudience;
+  /**
+   * Owner-pinned model/tier for every execution sent from this viewer
+   * (stigmer/stigmer#664) — for product-embedded conversations where
+   * the platform, not the end user, decides what serves the session
+   * (pair with `audience="endUser"`). A pinned model wins over the
+   * composer, the persisted Console preference, and the last
+   * execution's model — follow-ups and retries included — and hides
+   * the model picker (a control that has no effect must not render).
+   * Ignored for the `"guest"` audience, whose execution config the
+   * server-side share policy owns. See {@link SessionRunConfig}.
+   */
+  readonly runConfig?: SessionRunConfig;
+  /**
+   * Whether the follow-up composer offers the model picker. `false`
+   * hides the picker while keeping the SDK's model sourcing (persisted
+   * preference, then the last execution's model) — for hosts whose
+   * surrounding surface owns model choice without pinning it. Forced
+   * off by a {@link SessionViewerProps.runConfig} model pin and for the
+   * `"guest"` audience.
+   *
+   * @default true
+   */
+  readonly showModelSelector?: boolean;
+  /**
+   * Whether the viewer offers the session panel at all. `"none"` removes the
+   * panel AND its toggle chip, suppresses plan-mode auto-open, and lets
+   * transcript file paths keep their default copy behavior — for hosts whose
+   * surrounding surface already renders the workspace — while keeping every
+   * composer capability the audience allows. This is the panel half of what
+   * `audience="guest"` does, WITHOUT guest's composer strip-down; guest
+   * still forces it regardless of this prop. A union (not a boolean) so a
+   * future mode (e.g. a host-rendered panel) extends rather than breaks it.
+   *
+   * @default "auto"
+   */
+  readonly panel?: SessionPanelMode;
+  /**
+   * Initial open state of the session panel in uncontrolled mode — a docking
+   * host that wants the workspace visible from the first paint passes `true`.
+   * Ignored when {@link SessionViewerProps.panelOpen} is provided.
+   *
+   * @default false
+   */
+  readonly defaultPanelOpen?: boolean;
+  /**
+   * Controlled open state of the session panel. When provided, the host owns
+   * the panel: the chip toggle, file/plan/artifact opens, and plan-mode
+   * auto-open surface through {@link SessionViewerProps.onPanelOpenChange}
+   * instead of flipping state, and the panel follows this value. Leave
+   * `undefined` for the self-managing default.
+   */
+  readonly panelOpen?: boolean;
+  /**
+   * Called on every panel open/close transition, in BOTH modes — pass it
+   * alone (uncontrolled) to simply observe the panel, e.g. widening a docked
+   * pane when a streaming plan auto-opens it and reclaiming the room on
+   * close. See {@link UseSessionPanelOptions.onOpenChange} for the exact
+   * request-vs-transition semantics in each mode.
+   */
+  readonly onPanelOpenChange?: (open: boolean) => void;
   /**
    * Slot for host-injected header actions. Rendered in the top-right corner
    * of the viewer, beside the panel chip. Keeps the SDK organism
@@ -306,15 +367,32 @@ export function SessionViewer({
   workspaceContentSearcher,
   getRuntimeEnv,
   audience = "integrator",
+  runConfig,
+  showModelSelector = true,
+  panel: panelMode = "auto",
+  defaultPanelOpen,
+  panelOpen,
+  onPanelOpenChange,
   headerActions,
   accessSlot,
   onApplied,
   threadSlots,
   className,
 }: SessionViewerProps) {
-  const flow = useSessionPageFlow({ sessionId, org, getRuntimeEnv, audience });
+  const flow = useSessionPageFlow({
+    sessionId,
+    org,
+    getRuntimeEnv,
+    audience,
+    runConfig,
+  });
   const { conv } = flow;
   const isGuest = audience === "guest";
+  // A pinned model makes the picker a dead control (the pin wins over any
+  // choice it could offer), so the pin forces it hidden; the guest strip
+  // and the host's explicit opt-out compose with it.
+  const modelSelectorVisible =
+    showModelSelector && !isGuest && runConfig?.modelName === undefined;
   // Channel-originated sessions (Slack/WhatsApp conversations owned by the
   // channel runtime) are read-only for every console caller — the server
   // grants channel viewers can_view without can_create_execution_in — so the
@@ -326,6 +404,12 @@ export function SessionViewer({
   // Curated audiences (endUser, guest, observer) lock the agent and hide the
   // integrator configuration; guest and observer add their own restrictions.
   const isCurated = audience !== "integrator" || isObserver;
+  // The one flag every panel affordance keys on: the host opted out
+  // (`panel="none"`) or the audience forbids it (guests have no business
+  // with session configuration). Everything the panel touches — the chip,
+  // the region, plan auto-open, transcript path clicks — gates on this, so
+  // the four affordances can never drift apart.
+  const panelEnabled = panelMode !== "none" && !isGuest;
 
   const [modelId, setModelId] = flow.model;
   const [interactionMode, setInteractionMode] = flow.interactionMode;
@@ -405,9 +489,16 @@ export function SessionViewer({
   const panel = useSessionPanel({
     phase: hasPhase ? phase : null,
     hasChanges: hasWriteBacks,
-    // A streaming plan auto-opens the panel via its key — but guests have
-    // no panel, so the trigger is suppressed along with the chip.
-    planKey: isGuest ? null : panelPlanKey,
+    // A streaming plan auto-opens the panel via its key — but a viewer
+    // without a panel (guest, or panel="none") suppresses the trigger
+    // along with the chip.
+    planKey: panelEnabled ? panelPlanKey : null,
+    // With the panel disabled the controller is pinned controlled-closed
+    // and unobserved — airtight inertness, not just hidden UI: no intent
+    // can flip state or reach the host's callback.
+    open: panelEnabled ? panelOpen : false,
+    defaultOpen: defaultPanelOpen,
+    onOpenChange: panelEnabled ? onPanelOpenChange : undefined,
   });
 
   const handleBuildFromPlan = useCallback(() => {
@@ -520,10 +611,10 @@ export function SessionViewer({
   // (which subscribes), never this streaming column.
   const handleTranscriptFilePathClick = useCallback(
     (path: string): boolean => {
-      // Guests have no panel (and no file viewer), so paths keep their
-      // default copy behavior instead of opening a surface that cannot
-      // render.
-      if (isGuest) return false;
+      // No panel (guest, or panel="none") means no file viewer, so paths
+      // keep their default copy behavior instead of opening a surface that
+      // cannot render.
+      if (!panelEnabled) return false;
       const selection = resolveWorkspaceFileSelection(
         path,
         flow.workspace.entries,
@@ -533,7 +624,7 @@ export function SessionViewer({
       panel.openFile(selection.entryId, selection.path);
       return true;
     },
-    [isGuest, flow.workspace.entries, flow.sandboxWorkspaceRoot, panel.openFile],
+    [panelEnabled, flow.workspace.entries, flow.sandboxWorkspaceRoot, panel.openFile],
   );
 
   if (conv.isLoading) {
@@ -558,12 +649,12 @@ export function SessionViewer({
       // Top-right controls: host actions + the panel chip. The chip is the
       // panel's always-mounted toggle; while collapsed it carries only the
       // pending-item count. Execution status is never surfaced as header
-      // chrome — the thread itself communicates run state. Guests get no
-      // chip: the panel exposes session configuration a visitor has no
-      // business with, so its only toggle is simply absent.
+      // chrome — the thread itself communicates run state. A viewer without
+      // a panel (guests — session configuration is not a visitor's business
+      // — or a host's panel="none") has no toggle: it is simply absent.
       headerActions={headerActions}
       chip={
-        !isGuest ? (
+        panelEnabled ? (
           <SessionPanelChip
             isOpen={panel.isOpen}
             onToggle={panel.isOpen ? panel.closePanel : panel.openPanel}
@@ -594,11 +685,12 @@ export function SessionViewer({
           isCurated={isCurated}
           isGuest={isGuest}
           isObserver={isObserver}
+          modelSelectorVisible={modelSelectorVisible}
           threadSlots={threadSlots}
         />
       }
       panel={
-        panel.isOpen && !isGuest ? (
+        panel.isOpen && panelEnabled ? (
           <SessionPanelRegion
             flow={flow}
             org={org}
@@ -675,6 +767,13 @@ interface ConversationColumnProps {
    * stream indicators stay (watching an in-flight turn is the point).
    */
   readonly isObserver: boolean;
+  /**
+   * Whether the composer offers the model picker — the composed result
+   * of the host's `showModelSelector`, the guest strip, and a
+   * `runConfig` model pin (a pinned model makes the picker a dead
+   * control, so the pin forces it hidden).
+   */
+  readonly modelSelectorVisible: boolean;
   readonly threadSlots?: MessageThreadSlots;
 }
 
@@ -699,6 +798,7 @@ const ConversationColumn = memo(function ConversationColumn({
   isCurated,
   isGuest,
   isObserver,
+  modelSelectorVisible,
   threadSlots,
 }: ConversationColumnProps) {
   const { conv } = flow;
@@ -891,7 +991,7 @@ const ConversationColumn = memo(function ConversationColumn({
             interactionMode={interactionMode}
             onInteractionModeChange={setInteractionMode}
             showInteractionModePicker={!isGuest}
-            showModelSelector={!isGuest}
+            showModelSelector={modelSelectorVisible}
             enableAttachments={!isGuest}
             workspace={isGuest ? undefined : flow.workspace}
             gitHubConnection={isGuest ? undefined : gitHubConnection}
@@ -1290,7 +1390,10 @@ function SessionStarting() {
  * Low-weight, always-visible indicator shown while the session-scoped
  * auto-approve preference is active. The "Turn off" control reverts the
  * preference in one click — the safety affordance for "Approve & don't ask
- * again". Nothing about approvals appears until the user opts in at a gate.
+ * again". Visible from the first render when the host pre-armed the
+ * preference via `StigmerProvider`'s `approvalDefaults` (#302); otherwise
+ * nothing about approvals appears until the user opts in at a gate. Either
+ * way the user keeps the last word.
  */
 function AutoApproveIndicator({ onTurnOff }: { onTurnOff: () => void }) {
   return (

package/src/session/__tests__/audienceWiring.test.tsx

@@ -441,3 +441,79 @@ describe("SessionViewer — audience wiring", () => {
     expect(alert.textContent).toContain("token mint failed");
   });
 });
+
+describe("owner-pinned runConfig wiring (#664)", () => {
+  const PIN = { modelName: "pinned-model", serviceTier: "fast" } as const;
+
+  it("SessionViewer forwards runConfig to the flow and hides the model picker (no dead controls)", () => {
+    render(
+      <SessionViewer sessionId="ses_1" org="acme" audience="endUser" runConfig={PIN} />,
+    );
+
+    expect(mockUseSessionPageFlow).toHaveBeenCalledWith(
+      expect.objectContaining({ runConfig: PIN }),
+    );
+    expect(lastComposerProps().showModelSelector).toBe(false);
+  });
+
+  it("SessionViewer keeps the picker for endUser without a pin (the #167 curation contract)", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" audience="endUser" />);
+
+    expect(lastComposerProps().showModelSelector).toBe(true);
+  });
+
+  it("SessionViewer honors showModelSelector={false} alone — hidden picker, no pin", () => {
+    render(
+      <SessionViewer sessionId="ses_1" org="acme" showModelSelector={false} />,
+    );
+
+    expect(mockUseSessionPageFlow).toHaveBeenCalledWith(
+      expect.objectContaining({ runConfig: undefined }),
+    );
+    expect(lastComposerProps().showModelSelector).toBe(false);
+  });
+
+  it("SessionViewer: a tier-only pin (no model) keeps the picker — nothing pins the model", () => {
+    // The flow hook itself rejects this shape at render (fail-fast, covered
+    // by its own suite); the wiring contract here is only that picker
+    // visibility keys on the MODEL pin, never on the tier.
+    render(
+      <SessionViewer
+        sessionId="ses_1"
+        org="acme"
+        runConfig={{ serviceTier: "standard" }}
+      />,
+    );
+
+    expect(lastComposerProps().showModelSelector).toBe(true);
+  });
+
+  it("NewSessionViewer forwards runConfig to the flow and hides the model picker (DD-016 parity)", () => {
+    render(
+      <NewSessionViewer
+        org="acme"
+        onSessionCreated={vi.fn()}
+        audience="endUser"
+        initialAgentRef={AGENT_REF}
+        runConfig={PIN}
+      />,
+    );
+
+    expect(mockUseNewSessionFlow).toHaveBeenCalledWith(
+      expect.objectContaining({ runConfig: PIN }),
+    );
+    expect(lastComposerProps().showModelSelector).toBe(false);
+  });
+
+  it("NewSessionViewer honors showModelSelector={false} alone (DD-016 parity)", () => {
+    render(
+      <NewSessionViewer
+        org="acme"
+        onSessionCreated={vi.fn()}
+        showModelSelector={false}
+      />,
+    );
+
+    expect(lastComposerProps().showModelSelector).toBe(false);
+  });
+});

package/src/session/__tests__/panelNegotiation.test.tsx

@@ -0,0 +1,302 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+
+// ---------------------------------------------------------------------------
+// Wiring-contract tests for the session panel's host-negotiation surface
+// (issue #300): `panel="none"` omission, `defaultPanelOpen`, and the
+// controlled/observed `panelOpen` + `onPanelOpenChange` pair on both session
+// organisms.
+//
+// The contract under test is the one the PanelChip's aria labels already
+// promise ("Show panel"/"Hide panel") — the same seam the issue's filer
+// watched with a MutationObserver. These tests are what retires that
+// workaround: every open/close beat must reach `onPanelOpenChange`.
+//
+// Same probe/stub setup as audienceWiring.test.tsx: the composer and thread
+// are prop-capturing probes; the flow hooks are stubbed to a loaded state.
+// ---------------------------------------------------------------------------
+
+type CapturedProps = Record<string, unknown>;
+
+const composerProps: CapturedProps[] = [];
+vi.mock("../../composer", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../composer")>();
+  return {
+    ...actual,
+    SessionComposer: (props: CapturedProps) => {
+      composerProps.push(props);
+      return <div data-testid="composer-probe" />;
+    },
+  };
+});
+
+vi.mock("../facets/SetupTab", () => ({
+  SetupTab: () => <div data-testid="setup-probe" />,
+}));
+
+vi.mock("../../execution/MessageThread", () => ({
+  MessageThread: () => <div data-testid="thread-probe" />,
+}));
+
+const stubWorkspace = {
+  entries: [],
+  hasEntries: false,
+  toInput: vi.fn().mockReturnValue([]),
+  addGitRepo: vi.fn(),
+  addLocalPath: vi.fn(),
+  removeEntry: vi.fn(),
+  clear: vi.fn(),
+};
+
+const stubSessionVariables = { entries: [], isEmpty: true, clear: vi.fn() };
+
+const stubNewSessionFlow = {
+  harness: "native" as const,
+  setHarness: vi.fn(),
+  modelId: undefined,
+  setModelId: vi.fn(),
+  agentRef: { org: "acme", slug: "support-bot" },
+  setAgentRef: vi.fn(),
+  resolution: null,
+  setResolution: vi.fn(),
+  mcpServerUsages: [],
+  setMcpServerUsages: vi.fn(),
+  skillRefs: [],
+  setSkillRefs: vi.fn(),
+  workspace: stubWorkspace,
+  sessionVariables: stubSessionVariables,
+  isSubmitting: false,
+  submitError: null,
+  submit: vi.fn(),
+};
+vi.mock("../useNewSessionFlow", () => ({
+  useNewSessionFlow: () => stubNewSessionFlow,
+}));
+
+const stubConv = {
+  session: { spec: {} },
+  isLoading: false,
+  loadError: null,
+  completedExecutions: [],
+  activeStreamExecution: null,
+  activePhase: null,
+  isStreaming: false,
+  isConnecting: false,
+  sendFollowUp: vi.fn(),
+  canSendFollowUp: true,
+  isSending: false,
+  sendError: null,
+  clearSendError: vi.fn(),
+  retryLastSend: vi.fn(),
+  pendingUserMessage: null,
+  workspaceEntries: [],
+  mcpServerUsages: [],
+  skillRefs: [],
+  pendingApprovals: [],
+  submitApproval: vi.fn(),
+  submittingApprovalIds: new Set<string>(),
+  fileChangeSets: [],
+  submitFileDecision: vi.fn(),
+  submittingFileDecisionKeys: new Set<string>(),
+  fileDecisionErrors: new Map<string, Error>(),
+  streamError: null,
+  reconnectStream: vi.fn(),
+  approvalError: null,
+};
+
+const stubSessionPageFlow = {
+  conv: stubConv,
+  harness: "native" as const,
+  executionTarget: undefined,
+  model: [undefined, vi.fn()] as const,
+  interactionMode: ["agent" as const, vi.fn()] as const,
+  agentRef: { org: "acme", slug: "support-bot" },
+  setAgentRef: vi.fn(),
+  resolution: null,
+  setResolution: vi.fn(),
+  isDefaultAgent: false,
+  mcpServerUsages: [],
+  setMcpServerUsages: vi.fn(),
+  skillRefs: [],
+  setSkillRefs: vi.fn(),
+  workspace: stubWorkspace,
+  sessionVariables: stubSessionVariables,
+  autoApproveAll: false,
+  setAutoApproveAll: vi.fn(),
+  submitApproval: vi.fn(),
+  handleSubmit: vi.fn(),
+  submitError: null as Error | null,
+  displayExecution: null,
+  allExecutions: [],
+  sandboxWorkspaceRoot: undefined,
+};
+vi.mock("../useSessionPageFlow", () => ({
+  useSessionPageFlow: () => stubSessionPageFlow,
+}));
+
+vi.mock("../../hooks", () => ({
+  useStigmer: () => ({
+    agentExecution: {
+      uploadAttachment: vi.fn(),
+      getArtifactContent: vi.fn(),
+    },
+  }),
+}));
+
+import { NewSessionViewer } from "../NewSessionViewer";
+import { SessionViewer } from "../SessionViewer";
+
+function lastComposerProps(): CapturedProps {
+  expect(composerProps.length).toBeGreaterThan(0);
+  return composerProps.at(-1)!;
+}
+
+function chipButton(): HTMLElement | null {
+  return (
+    screen.queryByRole("button", { name: "Show panel" }) ??
+    screen.queryByRole("button", { name: "Hide panel" })
+  );
+}
+
+beforeEach(() => {
+  composerProps.length = 0;
+});
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe("SessionViewer — panel=\"none\"", () => {
+  it("removes the chip and never renders the panel", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" panel="none" />);
+    expect(chipButton()).toBeNull();
+  });
+
+  it("keeps every composer capability the audience allows — the guest contrast", () => {
+    // The point of panel="none": omission WITHOUT audience="guest"'s
+    // composer strip-down. Assert the exact capabilities guest removes.
+    render(<SessionViewer sessionId="ses_1" org="acme" panel="none" />);
+
+    const props = lastComposerProps();
+    expect(props.showInteractionModePicker).toBe(true);
+    expect(props.showModelSelector).toBe(true);
+    expect(props.enableAttachments).toBe(true);
+    expect(props.lockAgent).toBe(false);
+    expect(props.onMcpServerUsagesChange).toBeDefined();
+  });
+
+  it("keeps controlled props inert — panelOpen cannot force a surface that does not exist", () => {
+    const onPanelOpenChange = vi.fn();
+    render(
+      <SessionViewer
+        sessionId="ses_1"
+        org="acme"
+        panel="none"
+        panelOpen={true}
+        onPanelOpenChange={onPanelOpenChange}
+      />,
+    );
+    expect(chipButton()).toBeNull();
+    expect(onPanelOpenChange).not.toHaveBeenCalled();
+  });
+});
+
+describe("SessionViewer — observed panel state (uncontrolled + onPanelOpenChange)", () => {
+  it("reports chip toggles — the seam that retires the aria-expanded MutationObserver", () => {
+    const seen: boolean[] = [];
+    render(
+      <SessionViewer
+        sessionId="ses_1"
+        org="acme"
+        onPanelOpenChange={(open) => seen.push(open)}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Show panel" }));
+    expect(seen).toEqual([true]);
+    fireEvent.click(screen.getByRole("button", { name: "Hide panel" }));
+    expect(seen).toEqual([true, false]);
+  });
+
+  it("starts open with defaultPanelOpen, without a spurious notification", () => {
+    const onPanelOpenChange = vi.fn();
+    render(
+      <SessionViewer
+        sessionId="ses_1"
+        org="acme"
+        defaultPanelOpen
+        onPanelOpenChange={onPanelOpenChange}
+      />,
+    );
+
+    expect(screen.getByRole("button", { name: "Hide panel" })).toBeDefined();
+    expect(onPanelOpenChange).not.toHaveBeenCalled();
+  });
+});
+
+describe("SessionViewer — controlled panel state", () => {
+  it("follows panelOpen and surfaces the chip's request without applying it", () => {
+    const seen: boolean[] = [];
+    const onPanelOpenChange = (open: boolean) => seen.push(open);
+    const { rerender } = render(
+      <SessionViewer
+        sessionId="ses_1"
+        org="acme"
+        panelOpen={false}
+        onPanelOpenChange={onPanelOpenChange}
+      />,
+    );
+
+    // The chip requests; the host owns the state — nothing moves yet.
+    fireEvent.click(screen.getByRole("button", { name: "Show panel" }));
+    expect(seen).toEqual([true]);
+    expect(screen.getByRole("button", { name: "Show panel" })).toBeDefined();
+
+    // The host grants the request: the panel opens and the chip flips.
+    rerender(
+      <SessionViewer
+        sessionId="ses_1"
+        org="acme"
+        panelOpen={true}
+        onPanelOpenChange={onPanelOpenChange}
+      />,
+    );
+    expect(screen.getByRole("button", { name: "Hide panel" })).toBeDefined();
+  });
+});
+
+describe("NewSessionViewer — panel negotiation (DD-016 parity)", () => {
+  it("panel=\"none\" removes the chip while the composer keeps its capabilities", () => {
+    render(
+      <NewSessionViewer org="acme" onSessionCreated={vi.fn()} panel="none" />,
+    );
+
+    expect(chipButton()).toBeNull();
+    const props = lastComposerProps();
+    expect(props.showInteractionModePicker).toBe(true);
+    expect(props.lockAgent).toBe(false);
+  });
+
+  it("reports chip toggles through onPanelOpenChange", () => {
+    const seen: boolean[] = [];
+    render(
+      <NewSessionViewer
+        org="acme"
+        onSessionCreated={vi.fn()}
+        onPanelOpenChange={(open) => seen.push(open)}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Show panel" }));
+    fireEvent.click(screen.getByRole("button", { name: "Hide panel" }));
+    expect(seen).toEqual([true, false]);
+  });
+
+  it("starts open with defaultPanelOpen", () => {
+    render(
+      <NewSessionViewer org="acme" onSessionCreated={vi.fn()} defaultPanelOpen />,
+    );
+    expect(screen.getByRole("button", { name: "Hide panel" })).toBeDefined();
+  });
+});