@stigmer/react 3.12.1 → 3.12.2

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

@@ -5,6 +5,8 @@ import { DEFAULT_MODEL_ID, DEFAULT_CURSOR_MODEL_ID, parseRegistryJson } from "..
 import { ModelRegistryContext } from "../../models/ModelRegistryContext";
 import type { ModelRegistryState } from "../../models/ModelRegistryContext";
 import { ExecutionTargetContext } from "../../execution-target-context";
+import { ApprovalDefaultsContext } from "../../approval-defaults-context";
+import type { ApprovalDefaults } from "../../approval-defaults-context";
 import { RunnerAdapterContext } from "../../runner-adapter";
 import type { RunnerAdapter } from "../../runner-adapter";
 const mockGetByReference = vi.fn();
@@ -71,16 +73,19 @@ const TEST_MODELS = parseRegistryJson({
 function createWrapper(
   executionTarget?: "local" | "cloud",
   adapter: RunnerAdapter | null = null,
+  approvalDefaults?: ApprovalDefaults,
 ) {
   const state: ModelRegistryState = { models: TEST_MODELS, isLoading: false, error: null, refetch: () => {} };
   return function Wrapper({ children }: { children: ReactNode }) {
     return (
       <ExecutionTargetContext.Provider value={executionTarget}>
-        <RunnerAdapterContext.Provider value={adapter}>
-          <ModelRegistryContext.Provider value={state}>
-            {children}
-          </ModelRegistryContext.Provider>
-        </RunnerAdapterContext.Provider>
+        <ApprovalDefaultsContext.Provider value={approvalDefaults}>
+          <RunnerAdapterContext.Provider value={adapter}>
+            <ModelRegistryContext.Provider value={state}>
+              {children}
+            </ModelRegistryContext.Provider>
+          </RunnerAdapterContext.Provider>
+        </ApprovalDefaultsContext.Provider>
       </ExecutionTargetContext.Provider>
     );
   };
@@ -291,6 +296,86 @@ describe("useNewSessionFlow", () => {
     });
   });
 
+  describe("submit — owner-pinned runConfig (#664)", () => {
+    it("stamps the pinned model and fast tier over the composer's selection and the restored preference", async () => {
+      localStorage.setItem(STORAGE_KEY_MODEL_NATIVE, DEFAULT_MODEL_ID);
+      const { result } = renderHook(
+        () =>
+          useNewSessionFlow({
+            ...defaultOptions(),
+            runConfig: { modelName: "pinned-model", serviceTier: "fast" },
+          }),
+        { wrapper: createWrapper() },
+      );
+
+      await act(async () => {
+        await result.current.submit("Hello", "user-picked-model");
+      });
+
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.modelName).toBe("pinned-model");
+      expect(execInput.serviceTier).toBe("fast");
+    });
+
+    it("a model-only pin suppresses a composer-armed fast tier (the pin owns the whole run config)", async () => {
+      const { result } = renderHook(
+        () =>
+          useNewSessionFlow({
+            ...defaultOptions(),
+            runConfig: { modelName: "pinned-model" },
+          }),
+        { wrapper: createWrapper() },
+      );
+
+      await act(async () => {
+        await result.current.submit("Hello", undefined, { serviceTier: "fast" });
+      });
+
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.modelName).toBe("pinned-model");
+      expect(execInput.serviceTier).toBeUndefined();
+    });
+
+    it("ignores the pin entirely for guests — the platform share policy owns guest config", async () => {
+      const { result } = renderHook(
+        () =>
+          useNewSessionFlow({
+            ...defaultOptions(),
+            audience: "guest",
+            runConfig: { modelName: "pinned-model", serviceTier: "fast" },
+          }),
+        { wrapper: createWrapper() },
+      );
+
+      // Guests submit against an explicitly pinned shared agent.
+      act(() => {
+        result.current.setAgentRef({ org: "acme", slug: "shared-agent" });
+        result.current.setResolution({ mode: "saved", instanceId: "inst-shared" });
+      });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.modelName).toBeUndefined();
+      expect(execInput.serviceTier).toBeUndefined();
+    });
+
+    it("throws at render for the statically-wrong pin (fast tier, no model)", () => {
+      expect(() =>
+        renderHook(
+          () =>
+            useNewSessionFlow({
+              ...defaultOptions(),
+              runConfig: { serviceTier: "fast" },
+            }),
+          { wrapper: createWrapper() },
+        ),
+      ).toThrowError(/serviceTier "fast" requires modelName/);
+    });
+  });
+
   describe("submit — one-call bootstrap", () => {
     it("creates the execution with an embedded sessionSpec in a single call", async () => {
       const opts = defaultOptions();
@@ -320,6 +405,32 @@ describe("useNewSessionFlow", () => {
       expect(execInput.sessionSpec.harness).toBe("native");
     });
 
+    it("omits autoApproveAll by default (fail-closed gates unchanged)", async () => {
+      const opts = defaultOptions();
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.autoApproveAll).toBeUndefined();
+    });
+
+    it("forwards the host approval default into the bootstrap create (#302)", async () => {
+      const opts = defaultOptions();
+      const { result } = renderHook(() => useNewSessionFlow(opts), {
+        wrapper: createWrapper(undefined, null, { autoApproveAll: true }),
+      });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.autoApproveAll).toBe(true);
+    });
+
     it("passes cursor harness in the sessionSpec after switching", async () => {
       const opts = defaultOptions();
       const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
@@ -844,6 +955,24 @@ describe("useNewSessionFlow", () => {
       expect(result.current.harness).toBe("cursor");
     });
 
+    it("never inherits the host approval default — guests get platform policy (#302)", async () => {
+      const opts = { ...defaultOptions(), audience: "guest" as const };
+      const { result } = renderHook(() => useNewSessionFlow(opts), {
+        wrapper: createWrapper(undefined, null, { autoApproveAll: true }),
+      });
+
+      act(() => {
+        result.current.setAgentRef({ org: "acme", slug: "support-bot" });
+        result.current.setResolution({ mode: "saved", instanceId: "shared-inst" });
+      });
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.autoApproveAll).toBeUndefined();
+    });
+
     it("ignores the embedder's defaultHarness — guests get platform policy", () => {
       const opts = {
         ...defaultOptions(),

package/src/session/__tests__/useSessionPageFlow.autoApprove.test.tsx

@@ -62,10 +62,23 @@ vi.mock("../useAgentRefFromSession", () => ({
   useAgentRefFromSession: () => ({ agentRef: null }),
 }));
 
+import type { ReactNode } from "react";
 import { useSessionPageFlow } from "../useSessionPageFlow";
+import { ApprovalDefaultsContext } from "../../approval-defaults-context";
 
 const OPTS = { sessionId: "ses_1", org: "acme" };
 
+/** Renders the hook under a provider-level host approval default (#302). */
+function hostDefaultWrapper(autoApproveAll: boolean) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <ApprovalDefaultsContext.Provider value={{ autoApproveAll }}>
+        {children}
+      </ApprovalDefaultsContext.Provider>
+    );
+  };
+}
+
 describe("useSessionPageFlow — gate-driven auto-approve", () => {
   beforeEach(() => {
     mockSubmitApproval.mockResolvedValue(undefined);
@@ -147,3 +160,64 @@ describe("useSessionPageFlow — gate-driven auto-approve", () => {
     expect(followUpOpts.autoApproveAll).toBeUndefined();
   });
 });
+
+describe("useSessionPageFlow — host-set approval default (#302)", () => {
+  beforeEach(() => {
+    mockSubmitApproval.mockResolvedValue(undefined);
+  });
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("arms autoApproveAll from the provider default, before any gate", () => {
+    const { result } = renderHook(() => useSessionPageFlow(OPTS), {
+      wrapper: hostDefaultWrapper(true),
+    });
+    expect(result.current.autoApproveAll).toBe(true);
+  });
+
+  it("carries the host default into the very first follow-up", async () => {
+    const { result } = renderHook(() => useSessionPageFlow(OPTS), {
+      wrapper: hostDefaultWrapper(true),
+    });
+
+    await act(async () => {
+      await result.current.handleSubmit("first message");
+    });
+
+    const followUpOpts = mockSendFollowUp.mock.calls[0][1];
+    expect(followUpOpts.autoApproveAll).toBe(true);
+  });
+
+  it("the user's Turn off beats the host default for the rest of the session", async () => {
+    const { result } = renderHook(() => useSessionPageFlow(OPTS), {
+      wrapper: hostDefaultWrapper(true),
+    });
+
+    act(() => {
+      result.current.setAutoApproveAll(false);
+    });
+    expect(result.current.autoApproveAll).toBe(false);
+
+    await act(async () => {
+      await result.current.handleSubmit("after turn off");
+    });
+    const followUpOpts = mockSendFollowUp.mock.calls.at(-1)?.[1];
+    expect(followUpOpts.autoApproveAll).toBeUndefined();
+  });
+
+  it("guests never inherit the host default", () => {
+    const { result } = renderHook(
+      () => useSessionPageFlow({ ...OPTS, audience: "guest" }),
+      { wrapper: hostDefaultWrapper(true) },
+    );
+    expect(result.current.autoApproveAll).toBe(false);
+  });
+
+  it("an explicit false default changes nothing", () => {
+    const { result } = renderHook(() => useSessionPageFlow(OPTS), {
+      wrapper: hostDefaultWrapper(false),
+    });
+    expect(result.current.autoApproveAll).toBe(false);
+  });
+});

package/src/session/__tests__/useSessionPageFlow.runConfig.test.tsx

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+// ---------------------------------------------------------------------------
+// Owner-pinned run config for useSessionPageFlow (stigmer/stigmer#664).
+//
+// A platform-billed embedder pins the model/tier once and every follow-up
+// carries it — winning over the composer's selection, the persisted
+// Console preference, and the last execution's model — including retries,
+// which re-enter the same submit path. Guests never carry a pin: their
+// execution config is owned by the server-side share policy.
+// ---------------------------------------------------------------------------
+
+const mockSendFollowUp = vi.fn();
+
+const mockConv = {
+  session: { spec: { agentInstanceId: "inst_bound" } },
+  isLoading: false,
+  completedExecutions: [] as unknown[],
+  activeStreamExecution: null,
+  workspaceEntries: [] as unknown[],
+  submitApproval: vi.fn(),
+  sendFollowUp: mockSendFollowUp,
+};
+vi.mock("../useSessionConversation", () => ({
+  useSessionConversation: () => mockConv,
+}));
+
+vi.mock("../../hooks", () => ({
+  useStigmer: () => ({ agent: { getByReference: vi.fn() } }),
+}));
+
+vi.mock("../../agent", () => ({
+  useDefaultAgent: () => ({ agent: null, isLoading: false, error: null }),
+}));
+
+const mockWorkspace = {
+  entries: [],
+  hasEntries: false,
+  toInput: vi.fn().mockReturnValue([]),
+  addGitRepo: vi.fn(),
+  addLocalPath: vi.fn(),
+  removeEntry: vi.fn(),
+  clear: vi.fn(),
+};
+vi.mock("../../workspace", () => ({
+  useWorkspaceEntries: () => mockWorkspace,
+}));
+
+vi.mock("../../execution/useSessionVariables", () => ({
+  useSessionVariables: () => ({ variables: [], isEmpty: true, clear: vi.fn() }),
+}));
+
+// Honors `enabled` like the real hook (contract pinned by its own tests).
+vi.mock("../usePersistedModel", () => ({
+  usePersistedModel: (opts?: { enabled?: boolean }) =>
+    (opts?.enabled === false
+      ? ([undefined, vi.fn()] as const)
+      : (["persisted-model", vi.fn()] as const)),
+}));
+
+vi.mock("../useAgentRefFromSession", () => ({
+  useAgentRefFromSession: () => ({ agentRef: null }),
+}));
+
+import { useSessionPageFlow } from "../useSessionPageFlow";
+
+const OPTS = { sessionId: "ses_1", org: "acme" };
+const PIN = { modelName: "pinned-model", serviceTier: "fast" } as const;
+
+describe("useSessionPageFlow — owner-pinned runConfig (#664)", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("stamps the pinned model and fast tier on a composer follow-up, over the composer's own selection", async () => {
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, runConfig: PIN }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up", "user-picked-model", {
+        serviceTier: undefined,
+      });
+    });
+
+    const options = mockSendFollowUp.mock.calls[0][1];
+    expect(options.modelName).toBe("pinned-model");
+    expect(options.serviceTier).toBe("fast");
+  });
+
+  it("stamps the pin on a bare re-submit (the execution-retry path passes no composer args)", async () => {
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, runConfig: PIN }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("retry me");
+    });
+
+    const options = mockSendFollowUp.mock.calls[0][1];
+    expect(options.modelName).toBe("pinned-model");
+    expect(options.serviceTier).toBe("fast");
+  });
+
+  it("a model-only pin suppresses a composer-armed fast tier (the pin owns the whole run config)", async () => {
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, runConfig: { modelName: "pinned-model" } }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up", undefined, {
+        serviceTier: "fast",
+      });
+    });
+
+    const options = mockSendFollowUp.mock.calls[0][1];
+    expect(options.modelName).toBe("pinned-model");
+    expect(options.serviceTier).toBeUndefined();
+  });
+
+  it("keeps the unpinned behavior byte-identical when no runConfig is given", async () => {
+    const { result } = renderHook(() => useSessionPageFlow(OPTS));
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up", "user-picked-model", {
+        serviceTier: "fast",
+      });
+    });
+
+    const options = mockSendFollowUp.mock.calls[0][1];
+    expect(options.modelName).toBe("user-picked-model");
+    expect(options.serviceTier).toBe("fast");
+  });
+
+  it("ignores the pin entirely for guests — their no-modelName invariant survives a misconfigured embed", async () => {
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, audience: "guest", runConfig: PIN }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up");
+    });
+
+    const options = mockSendFollowUp.mock.calls[0][1];
+    expect(options.modelName).toBeUndefined();
+    expect(options.serviceTier).toBeUndefined();
+  });
+
+  it("throws at render for the statically-wrong pin (fast tier, no model)", () => {
+    expect(() =>
+      renderHook(() =>
+        useSessionPageFlow({ ...OPTS, runConfig: { serviceTier: "fast" } }),
+      ),
+    ).toThrowError(/serviceTier "fast" requires modelName/);
+  });
+});

package/src/session/__tests__/useSessionPanel.test.ts

@@ -278,6 +278,120 @@ describe("useSessionPanel — artifact document tabs", () => {
   });
 });
 
+describe("useSessionPanel — observed open state (uncontrolled + onOpenChange)", () => {
+  // The panel opens ITSELF (file/artifact/plan opens, plan auto-open), so —
+  // unlike useDetailTabs' user-driven-only tabs — onOpenChange fires in BOTH
+  // modes: passing only the callback observes the panel without controlling
+  // it (the issue-#300 docking-host case).
+  it("reports the chip toggle without taking control", () => {
+    const seen: boolean[] = [];
+    const { result } = renderPanel({ onOpenChange: (o) => seen.push(o) });
+    act(() => result.current.openPanel());
+    expect(result.current.isOpen).toBe(true);
+    act(() => result.current.closePanel());
+    expect(result.current.isOpen).toBe(false);
+    expect(seen).toEqual([true, false]);
+  });
+
+  it("reports internal open intents (openFile), once per actual transition", () => {
+    const seen: boolean[] = [];
+    const { result } = renderPanel({ onOpenChange: (o) => seen.push(o) });
+    act(() => result.current.openFile("e1", "a.ts"));
+    // Already open — a second open intent is not a transition.
+    act(() => result.current.openFile("e1", "b.ts"));
+    act(() => result.current.openPanel());
+    expect(seen).toEqual([true]);
+  });
+
+  it("reports the plan auto-open — the beat a docking host makes room for", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { rerender } = renderPanel({ onOpenChange });
+    rerender({ phase: null, hasChanges: false, planKey: "e1:streaming", onOpenChange });
+    expect(seen).toEqual([true]);
+  });
+
+  it("starts open when defaultOpen is set, without a spurious notification", () => {
+    const seen: boolean[] = [];
+    const { result } = renderPanel({
+      defaultOpen: true,
+      onOpenChange: (o) => seen.push(o),
+    });
+    expect(result.current.isOpen).toBe(true);
+    expect(seen).toEqual([]);
+  });
+});
+
+describe("useSessionPanel — controlled open state", () => {
+  it("follows the host's open value and ignores defaultOpen", () => {
+    const { result, rerender } = renderPanel({ open: false, defaultOpen: true });
+    expect(result.current.isOpen).toBe(false);
+    rerender({ phase: null, hasChanges: false, open: true, defaultOpen: true });
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("surfaces intents through onOpenChange without flipping state itself", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result, rerender } = renderPanel({ open: false, onOpenChange });
+    act(() => result.current.openPanel());
+    expect(seen).toEqual([true]);
+    expect(result.current.isOpen).toBe(false);
+    // The host grants the request.
+    rerender({ phase: null, hasChanges: false, open: true, onOpenChange });
+    expect(result.current.isOpen).toBe(true);
+    act(() => result.current.closePanel());
+    expect(seen).toEqual([true, false]);
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("re-fires a declined request (once per request, not per transition)", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result } = renderPanel({ open: false, onOpenChange });
+    act(() => result.current.openFile("e1", "a.ts"));
+    // The host declined (open stayed false) — a later intent must re-fire,
+    // not be swallowed by a stale "already requested" memory.
+    act(() => result.current.openFile("e1", "b.ts"));
+    expect(seen).toEqual([true, true]);
+  });
+
+  it("plan auto-open is reported, not applied — but the tab is pinned and ready", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result, rerender } = renderPanel({ open: false, onOpenChange });
+    rerender({
+      phase: null,
+      hasChanges: false,
+      planKey: "e1:hash-a",
+      open: false,
+      onOpenChange,
+    });
+    expect(seen).toEqual([true]);
+    expect(result.current.isOpen).toBe(false);
+    // View state stays SDK-owned: the plan tab is pinned regardless, so the
+    // moment the host opens the panel the plan is what greets the user.
+    expect(result.current.editorsStore.getSnapshot().editors).toEqual([
+      { entryId: PLAN_DOCUMENT_ENTRY_ID, path: PLAN_DOCUMENT_PATH, preview: false },
+    ]);
+  });
+
+  it("auto-surfaces Changes against the HOST's open state, not the internal one", () => {
+    // The first-write-back trigger reads the effective open value: a
+    // controlled-open panel (whose internal state was never touched) must
+    // still surface Changes…
+    const { result, rerender } = renderPanel({ open: true });
+    rerender({ phase: null, hasChanges: true, open: true });
+    expect(result.current.view).toBe("changes");
+  });
+
+  it("…and a controlled-closed panel must not", () => {
+    const { result, rerender } = renderPanel({ open: false });
+    rerender({ phase: null, hasChanges: true, open: false });
+    expect(result.current.view).toBe("files");
+  });
+});
+
 describe("useSessionPanel — defaultView (home view)", () => {
   it("seeds the view to the provided defaultView (launcher homes on Config)", () => {
     const { result } = renderPanel({ defaultView: "configure" });

package/src/session/audience.ts

@@ -45,3 +45,21 @@
  * presentation means without breaking embedders.
  */
 export type SessionAudience = "integrator" | "endUser" | "guest" | "observer";
+
+/**
+ * Whether the session organisms offer the session panel surface.
+ *
+ * - `"auto"` (default) — the panel and its toggle chip are available
+ *   whenever the audience allows them (every audience except `"guest"`).
+ * - `"none"` — the panel and chip are absent entirely: plan-mode
+ *   auto-open is suppressed and transcript file paths keep their default
+ *   copy behavior. For hosts whose surrounding surface already renders
+ *   the workspace — the composer keeps every capability the audience
+ *   allows, which is what separates this from `audience="guest"`.
+ *
+ * Orthogonal to {@link SessionAudience} on purpose: audience is who is
+ * looking, panel mode is what the host's geometry has room for. A union
+ * (not a boolean) so a future mode — e.g. a host-rendered panel fed by
+ * the SDK's controller — extends the vocabulary instead of breaking it.
+ */
+export type SessionPanelMode = "auto" | "none";

package/src/session/index.ts

@@ -2,7 +2,8 @@ export { toProtoExecutionTarget, fromProtoExecutionTarget } from "./execution-ta
 export type { ExecutionTargetOption } from "./execution-target.js";
 
 export type { RuntimeEnvProvider } from "./runtime-env.js";
-export type { SessionAudience } from "./audience.js";
+export type { SessionAudience, SessionPanelMode } from "./audience.js";
+export type { SessionRunConfig } from "./run-config.js";
 export {
   CHANNEL_SESSION_LABELS,
   isChannelOriginSession,

package/src/session/run-config.ts

@@ -0,0 +1,59 @@
+import type { ServiceTierOption } from "../models/service-tier.js";
+
+/**
+ * Owner-pinned execution config for a session surface
+ * (stigmer/stigmer#664) — the client-side subset of the platform
+ * `RunConfig` that AgentShare and AgentChannel specs pin server-side
+ * (stigmer/stigmer#360). Budget clamps (`max_cost_usd`,
+ * `max_tool_rounds`) are deliberately absent: those are enforcement,
+ * which only the server can own.
+ *
+ * Passed to `SessionViewer` / `NewSessionViewer` (or the underlying
+ * flow hooks) by embedders whose product — not the end user — decides
+ * what serves the conversation: every execution on the surface (first
+ * message, follow-ups, retries) carries the pinned values, and the
+ * model picker hides automatically (a control that has no effect must
+ * not render).
+ *
+ * This is presentation-level pinning for product-embedded sessions,
+ * not a security boundary — a caller with the session's credentials
+ * can still create executions directly. Share/channel surfaces, where
+ * the audience is untrusted, get the server-enforced `RunConfig` on
+ * their specs instead.
+ *
+ * Ignored entirely for the `"guest"` audience: guest execution config
+ * is owned by the server-side share policy, and guest sends carrying
+ * no `modelName` is a pinned invariant.
+ */
+export interface SessionRunConfig {
+  /**
+   * Model every execution runs, as a plain `modelId` from the model
+   * registry. Wins over the composer's selection, the persisted
+   * Console preference, and the last execution's model.
+   */
+  readonly modelName?: string;
+  /**
+   * Service tier for every execution. `"fast"` requires
+   * {@link modelName}: the fast tier is a per-model price (the server
+   * refuses it fail-closed for Auto), so a tier pin without a model
+   * pin is a host configuration error and throws at submit.
+   */
+  readonly serviceTier?: ServiceTierOption;
+}
+
+/**
+ * Fail fast on the one statically-wrong shape: `serviceTier: "fast"`
+ * with no pinned model. Every layer below (composer gate, server
+ * validation) would refuse it anyway — but those surface as an end
+ * user's failed send, while this names the embedder's bug at the
+ * seam where it was written.
+ */
+export function assertValidRunConfig(runConfig: SessionRunConfig): void {
+  if (runConfig.serviceTier === "fast" && !runConfig.modelName) {
+    throw new Error(
+      "SessionRunConfig: serviceTier \"fast\" requires modelName — the fast "
+        + "tier is a per-model price and Auto (no pinned model) has no tier "
+        + "dimension. Pin the model the surface should run.",
+    );
+  }
+}