@stigmer/react 3.0.6 → 3.0.7-dev.20260611143057

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

@@ -0,0 +1,274 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+
+// ---------------------------------------------------------------------------
+// Wiring-contract tests for the `audience` preset on the session organisms.
+//
+// The composer and inspector are replaced with prop-capturing probes so the
+// tests assert exactly what `audience="endUser"` maps to: a locked agent,
+// unwired MCP/skill/session-variable pickers, and a read-only Setup tab.
+// The molecules' own behavior is covered by their co-located tests.
+// ---------------------------------------------------------------------------
+
+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" />;
+    },
+  };
+});
+
+const inspectorProps: CapturedProps[] = [];
+vi.mock("../inspector/SessionInspector", () => ({
+  SessionInspector: (props: CapturedProps) => {
+    inspectorProps.push(props);
+    return <div data-testid="inspector-probe" />;
+  },
+}));
+
+vi.mock("../../execution/MessageThread", () => ({
+  MessageThread: () => <div data-testid="thread-probe" />,
+}));
+
+// ---------------------------------------------------------------------------
+// Flow stubs — the organisms own these hooks; stub them to a loaded state.
+// ---------------------------------------------------------------------------
+
+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(),
+};
+const mockUseNewSessionFlow = vi.fn((_options: unknown) => stubNewSessionFlow);
+vi.mock("../useNewSessionFlow", () => ({
+  useNewSessionFlow: (options: unknown) => mockUseNewSessionFlow(options),
+}));
+
+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(),
+  pendingUserMessage: null,
+  workspaceEntries: [],
+  mcpServerUsages: [],
+  skillRefs: [],
+  pendingApprovals: [],
+  submitApproval: vi.fn(),
+  submittingApprovalIds: new Set<string>(),
+  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,
+};
+const mockUseSessionPageFlow = vi.fn((_options: unknown) => stubSessionPageFlow);
+vi.mock("../useSessionPageFlow", () => ({
+  useSessionPageFlow: (options: unknown) => mockUseSessionPageFlow(options),
+}));
+
+import { NewSessionViewer } from "../NewSessionViewer";
+import { SessionViewer } from "../SessionViewer";
+
+const AGENT_REF = { org: "acme", slug: "support-bot" };
+
+function lastComposerProps(): CapturedProps {
+  expect(composerProps.length).toBeGreaterThan(0);
+  return composerProps.at(-1)!;
+}
+
+function lastSessionConfig(): { mutations?: unknown } {
+  expect(inspectorProps.length).toBeGreaterThan(0);
+  return inspectorProps.at(-1)!.sessionConfig as { mutations?: unknown };
+}
+
+beforeEach(() => {
+  composerProps.length = 0;
+  inspectorProps.length = 0;
+  stubSessionPageFlow.submitError = null;
+});
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe("NewSessionViewer — audience wiring", () => {
+  it("integrator (default): full configuration surface, agent unlocked", () => {
+    render(
+      <NewSessionViewer
+        org="acme"
+        onSessionCreated={vi.fn()}
+        initialAgentRef={AGENT_REF}
+      />,
+    );
+
+    const props = lastComposerProps();
+    expect(props.lockAgent).toBe(false);
+    expect(props.onMcpServerUsagesChange).toBeDefined();
+    expect(props.onSkillRefsChange).toBeDefined();
+    expect(props.sessionVariables).toBeDefined();
+    expect(lastSessionConfig().mutations).toBeDefined();
+  });
+
+  it("endUser with a pinned agent: locked agent, integrator pickers unwired", () => {
+    render(
+      <NewSessionViewer
+        org="acme"
+        onSessionCreated={vi.fn()}
+        audience="endUser"
+        initialAgentRef={AGENT_REF}
+      />,
+    );
+
+    const props = lastComposerProps();
+    expect(props.lockAgent).toBe(true);
+    expect(props.onMcpServerUsagesChange).toBeUndefined();
+    expect(props.onSkillRefsChange).toBeUndefined();
+    expect(props.sessionVariables).toBeUndefined();
+    // End-user controls survive the curation.
+    expect(props.showHarnessSelector).toBe(true);
+    expect(props.showInteractionModePicker).toBe(true);
+    // Setup tab is read-only: no remove affordances for pinned config.
+    expect(lastSessionConfig().mutations).toBeUndefined();
+  });
+
+  it("endUser without a pinned agent: pickers hidden but agent not locked", () => {
+    render(
+      <NewSessionViewer
+        org="acme"
+        onSessionCreated={vi.fn()}
+        audience="endUser"
+      />,
+    );
+
+    expect(lastComposerProps().lockAgent).toBe(false);
+  });
+
+  it("forwards getRuntimeEnv and defaultHarness to the flow", () => {
+    const getRuntimeEnv = vi.fn();
+    render(
+      <NewSessionViewer
+        org="acme"
+        onSessionCreated={vi.fn()}
+        getRuntimeEnv={getRuntimeEnv}
+        defaultHarness="cursor"
+      />,
+    );
+
+    expect(mockUseNewSessionFlow).toHaveBeenCalledWith(
+      expect.objectContaining({ getRuntimeEnv, defaultHarness: "cursor" }),
+    );
+  });
+});
+
+describe("SessionViewer — audience wiring", () => {
+  it("integrator (default): full configuration surface, agent unlocked", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+
+    const props = lastComposerProps();
+    expect(props.lockAgent).toBe(false);
+    expect(props.onMcpServerUsagesChange).toBeDefined();
+    expect(props.onSkillRefsChange).toBeDefined();
+    expect(props.sessionVariables).toBeDefined();
+    expect(lastSessionConfig().mutations).toBeDefined();
+  });
+
+  it("endUser: locked agent, integrator pickers unwired, read-only Setup tab", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" audience="endUser" />);
+
+    const props = lastComposerProps();
+    expect(props.lockAgent).toBe(true);
+    expect(props.onMcpServerUsagesChange).toBeUndefined();
+    expect(props.onSkillRefsChange).toBeUndefined();
+    expect(props.sessionVariables).toBeUndefined();
+    // End-user controls survive the curation.
+    expect(props.showInteractionModePicker).toBe(true);
+    expect(lastSessionConfig().mutations).toBeUndefined();
+  });
+
+  it("forwards getRuntimeEnv to the flow", () => {
+    const getRuntimeEnv = vi.fn();
+    render(
+      <SessionViewer sessionId="ses_1" org="acme" getRuntimeEnv={getRuntimeEnv} />,
+    );
+
+    expect(mockUseSessionPageFlow).toHaveBeenCalledWith(
+      expect.objectContaining({ getRuntimeEnv }),
+    );
+  });
+
+  it("renders the flow's submitError through the send-error banner", () => {
+    stubSessionPageFlow.submitError = new Error("token mint failed");
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+
+    const alert = screen.getByRole("alert");
+    expect(alert.textContent).toContain("token mint failed");
+  });
+});

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

@@ -468,6 +468,128 @@ describe("useNewSessionFlow", () => {
     });
   });
 
+  describe("host runtime env (getRuntimeEnv)", () => {
+    it("merges host env into the first execution, host wins on collisions", async () => {
+      const getRuntimeEnv = vi.fn().mockResolvedValue({
+        PLATFORM_TOKEN: { value: "fresh-token", isSecret: true },
+      });
+      const opts = { ...defaultOptions(), getRuntimeEnv };
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("Hello", undefined, {
+          runtimeEnv: {
+            PLATFORM_TOKEN: { value: "stale-token", isSecret: true },
+            USER_VAR: { value: "kept" },
+          },
+        });
+      });
+
+      expect(getRuntimeEnv).toHaveBeenCalledTimes(1);
+      const execInput = mockCreateExecution.mock.calls[0][0];
+      expect(execInput.runtimeEnv).toEqual({
+        PLATFORM_TOKEN: { value: "fresh-token", isSecret: true },
+        USER_VAR: { value: "kept" },
+      });
+    });
+
+    it("evaluates the provider fresh on every submission", async () => {
+      let mint = 0;
+      const getRuntimeEnv = vi.fn(() => ({
+        TOKEN: { value: `token-${++mint}` },
+      }));
+      const opts = { ...defaultOptions(), getRuntimeEnv };
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("First");
+      });
+      await act(async () => {
+        await result.current.submit("Second");
+      });
+
+      expect(getRuntimeEnv).toHaveBeenCalledTimes(2);
+      expect(mockCreateExecution.mock.calls[0][0].runtimeEnv).toEqual({
+        TOKEN: { value: "token-1" },
+      });
+      expect(mockCreateExecution.mock.calls[1][0].runtimeEnv).toEqual({
+        TOKEN: { value: "token-2" },
+      });
+    });
+
+    it("aborts before session creation when the provider throws", async () => {
+      const getRuntimeEnv = vi.fn().mockRejectedValue(new Error("token mint failed"));
+      const opts = { ...defaultOptions(), getRuntimeEnv };
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      // No orphan session, no execution — the failure is fully pre-flight.
+      expect(mockCreateSession).not.toHaveBeenCalled();
+      expect(mockCreateExecution).not.toHaveBeenCalled();
+      expect(result.current.submitError).toContain("token mint failed");
+      expect(opts.onError).toHaveBeenCalled();
+      expect(result.current.isSubmitting).toBe(false);
+    });
+
+    it("passes composer env through untouched when no provider is configured", async () => {
+      const opts = defaultOptions();
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("Hello", undefined, {
+          runtimeEnv: { USER_VAR: { value: "composer-only" } },
+        });
+      });
+
+      expect(mockCreateExecution.mock.calls[0][0].runtimeEnv).toEqual({
+        USER_VAR: { value: "composer-only" },
+      });
+    });
+  });
+
+  describe("defaultHarness", () => {
+    it("seeds the embedder default when no harness is stored", () => {
+      const opts = { ...defaultOptions(), defaultHarness: "cursor" as const };
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      expect(result.current.harness).toBe("cursor");
+    });
+
+    it("stored user choice outranks the embedder default", () => {
+      localStorage.setItem(STORAGE_KEY_HARNESS, "native");
+      const opts = { ...defaultOptions(), defaultHarness: "cursor" as const };
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      expect(result.current.harness).toBe("native");
+    });
+
+    it("does not persist the seeded default — only explicit choices", () => {
+      const opts = { ...defaultOptions(), defaultHarness: "cursor" as const };
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      // Seeding must not masquerade as a user choice, otherwise the
+      // embedder default would stop applying after the first visit.
+      expect(localStorage.getItem(STORAGE_KEY_HARNESS)).toBeNull();
+
+      act(() => result.current.setHarness("native"));
+      expect(localStorage.getItem(STORAGE_KEY_HARNESS)).toBe("native");
+    });
+
+    it("submits sessions with the seeded default harness", async () => {
+      const opts = { ...defaultOptions(), defaultHarness: "cursor" as const };
+      const { result } = renderHook(() => useNewSessionFlow(opts), { wrapper: createWrapper() });
+
+      await act(async () => {
+        await result.current.submit("Hello");
+      });
+
+      expect(mockCreateSession.mock.calls[0][0].harness).toBe("cursor");
+    });
+  });
+
   describe("submit while default agent is loading", () => {
     it("awaits default agent and creates session when fetch resolves", async () => {
       const resolvedAgent = { status: { defaultInstanceId: "awaited-inst" } };

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

@@ -0,0 +1,170 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+// ---------------------------------------------------------------------------
+// Mocks — useSessionPageFlow composes many hooks; we stub them to isolate the
+// host runtime-env behavior (per-follow-up evaluation, host-wins merge, and
+// fail-fast into submitError before any optimistic UI).
+// ---------------------------------------------------------------------------
+
+const mockSendFollowUp = vi.fn();
+
+const mockConv = {
+  session: { spec: {} },
+  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,
+}));
+
+const mockSessionVariables = {
+  variables: [],
+  isEmpty: true,
+  clear: vi.fn(),
+};
+vi.mock("../../execution/useSessionVariables", () => ({
+  useSessionVariables: () => mockSessionVariables,
+}));
+
+vi.mock("../usePersistedModel", () => ({
+  usePersistedModel: () => ["model-x", vi.fn()] as const,
+}));
+
+vi.mock("../useAgentRefFromSession", () => ({
+  useAgentRefFromSession: () => ({ agentRef: null }),
+}));
+
+import { useSessionPageFlow } from "../useSessionPageFlow";
+
+const OPTS = { sessionId: "ses_1", org: "acme" };
+
+describe("useSessionPageFlow — host runtime env (getRuntimeEnv)", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("merges host env into follow-ups, host wins on collisions", async () => {
+    const getRuntimeEnv = vi.fn().mockResolvedValue({
+      PLATFORM_TOKEN: { value: "fresh-token", isSecret: true },
+    });
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, getRuntimeEnv }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up", undefined, {
+        runtimeEnv: {
+          PLATFORM_TOKEN: { value: "stale-token", isSecret: true },
+          USER_VAR: { value: "kept" },
+        },
+      });
+    });
+
+    expect(mockSendFollowUp).toHaveBeenCalledTimes(1);
+    expect(mockSendFollowUp.mock.calls[0][1].runtimeEnv).toEqual({
+      PLATFORM_TOKEN: { value: "fresh-token", isSecret: true },
+      USER_VAR: { value: "kept" },
+    });
+  });
+
+  it("evaluates the provider fresh on every follow-up", async () => {
+    let mint = 0;
+    const getRuntimeEnv = vi.fn(() => ({ TOKEN: { value: `token-${++mint}` } }));
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, getRuntimeEnv }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("first");
+    });
+    await act(async () => {
+      await result.current.handleSubmit("second");
+    });
+
+    expect(getRuntimeEnv).toHaveBeenCalledTimes(2);
+    expect(mockSendFollowUp.mock.calls[0][1].runtimeEnv).toEqual({
+      TOKEN: { value: "token-1" },
+    });
+    expect(mockSendFollowUp.mock.calls[1][1].runtimeEnv).toEqual({
+      TOKEN: { value: "token-2" },
+    });
+  });
+
+  it("blocks the send and sets submitError when the provider throws", async () => {
+    const getRuntimeEnv = vi.fn().mockRejectedValue(new Error("token mint failed"));
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, getRuntimeEnv }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up");
+    });
+
+    // Nothing was sent: no optimistic message, no session-variable clear.
+    expect(mockSendFollowUp).not.toHaveBeenCalled();
+    expect(mockSessionVariables.clear).not.toHaveBeenCalled();
+    expect(result.current.submitError).toBeInstanceOf(Error);
+    expect(result.current.submitError?.message).toBe("token mint failed");
+  });
+
+  it("clears submitError at the start of the next submission", async () => {
+    const getRuntimeEnv = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("transient failure"))
+      .mockResolvedValue({ TOKEN: { value: "ok" } });
+    const { result } = renderHook(() =>
+      useSessionPageFlow({ ...OPTS, getRuntimeEnv }),
+    );
+
+    await act(async () => {
+      await result.current.handleSubmit("fails");
+    });
+    expect(result.current.submitError).not.toBeNull();
+
+    await act(async () => {
+      await result.current.handleSubmit("succeeds");
+    });
+    expect(result.current.submitError).toBeNull();
+    expect(mockSendFollowUp).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes composer env through untouched when no provider is configured", async () => {
+    const { result } = renderHook(() => useSessionPageFlow(OPTS));
+
+    await act(async () => {
+      await result.current.handleSubmit("follow up", undefined, {
+        runtimeEnv: { USER_VAR: { value: "composer-only" } },
+      });
+    });
+
+    expect(mockSendFollowUp.mock.calls[0][1].runtimeEnv).toEqual({
+      USER_VAR: { value: "composer-only" },
+    });
+  });
+});

package/src/session/audience.ts

@@ -0,0 +1,20 @@
+/**
+ * Who the session organisms (`SessionViewer` / `NewSessionViewer`) are
+ * presented to.
+ *
+ * - `"integrator"` (default) — the full configuration surface: agent
+ *   picker, MCP servers, skills, and session variables. The presentation
+ *   used by the Stigmer Console, where the person at the keyboard is
+ *   composing the session's configuration.
+ * - `"endUser"` — a curated, product-embedded chat. The agent (and its
+ *   MCP servers, skills, and identity) is configured upstream by the
+ *   embedding platform; the end user chats, picks a model, toggles
+ *   Agent/Plan mode, and attaches workspaces, but never reconfigures
+ *   the agent. The organisms lock the agent and hide the integrator
+ *   pickers, in both the composer and the inspector's Setup tab.
+ *
+ * A preset rather than individual flags: "end user" is a product intent,
+ * and keeping it in one place lets the SDK evolve what that presentation
+ * means without breaking embedders.
+ */
+export type SessionAudience = "integrator" | "endUser";

package/src/session/index.ts

@@ -1,6 +1,9 @@
 export { toProtoExecutionTarget, fromProtoExecutionTarget } from "./execution-target";
 export type { ExecutionTargetOption } from "./execution-target";
 
+export type { RuntimeEnvProvider } from "./runtime-env";
+export type { SessionAudience } from "./audience";
+
 export { useCreateSession } from "./useCreateSession";
 export type {
   SharedSessionFields,

package/src/session/runtime-env.ts

@@ -0,0 +1,57 @@
+import type { EnvVarInput } from "@stigmer/sdk";
+
+/**
+ * Host-app callback that supplies environment variables for a single
+ * execution.
+ *
+ * Invoked once per execution, at submit time — never cached — so
+ * short-lived credentials (e.g. a freshly minted platform token scoped
+ * to the signed-in user) are always current when the execution starts.
+ * May return the variables synchronously or via a promise.
+ *
+ * Host-provided values take precedence over composer-collected env on
+ * key collisions: the host injects identity material, and a stale or
+ * user-supplied value must never shadow it.
+ *
+ * If the provider throws (or rejects), the submission is aborted and
+ * the error surfaces through the owning flow's error channel — an
+ * execution never runs with missing or stale credentials.
+ *
+ * @example
+ * ```tsx
+ * <SessionViewer
+ *   sessionId={id}
+ *   org={org}
+ *   getRuntimeEnv={async () => ({
+ *     PLATFORM_TOKEN: { value: await mintShortLivedToken(), isSecret: true },
+ *     PLATFORM_ORG: { value: activeOrg },
+ *   })}
+ * />
+ * ```
+ */
+export type RuntimeEnvProvider = () =>
+  | Promise<Record<string, EnvVarInput>>
+  | Record<string, EnvVarInput>;
+
+/**
+ * Resolves the effective `runtimeEnv` for one execution by merging
+ * composer-collected env with host-provided env from a
+ * {@link RuntimeEnvProvider}.
+ *
+ * Host values win on key collisions (see {@link RuntimeEnvProvider}).
+ * Returns `undefined` when neither source contributes any variables,
+ * so callers can pass the result straight to execution creation.
+ *
+ * Provider errors are intentionally not caught here: callers must
+ * treat a failure as fatal for the submission. Callers without a
+ * provider should pass the composer env through directly rather than
+ * paying this function's await.
+ */
+export async function resolveExecutionRuntimeEnv(
+  getRuntimeEnv: RuntimeEnvProvider,
+  composerEnv: Record<string, EnvVarInput> | undefined,
+): Promise<Record<string, EnvVarInput> | undefined> {
+  const hostEnv = await getRuntimeEnv();
+  const merged = { ...composerEnv, ...hostEnv };
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}