@stigmer/react 3.12.5 → 3.12.7

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

@@ -11,11 +11,20 @@ import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 const mockSubmitApproval = vi.fn<(t: string, a: ApprovalAction, c?: string) => Promise<void>>();
 const mockSendFollowUp = vi.fn();
 
+/** Loosely-typed conversation stub — individual tests mutate the arming and
+ * gate fields, and restore them in their afterEach. */
 const mockConv = {
-  session: { spec: {} },
+  session: { spec: {} } as {
+    spec: object;
+    metadata?: { labels?: Record<string, string> };
+  },
   isLoading: false,
   completedExecutions: [] as unknown[],
-  activeStreamExecution: null,
+  activeStreamExecution: null as {
+    spec?: { autoApproveAll?: boolean };
+    status?: object;
+  } | null,
+  pendingApprovals: [] as { toolCallId: string }[],
   workspaceEntries: [] as unknown[],
   submitApproval: mockSubmitApproval,
   sendFollowUp: mockSendFollowUp,
@@ -221,3 +230,168 @@ describe("useSessionPageFlow — host-set approval default (#302)", () => {
     expect(result.current.autoApproveAll).toBe(false);
   });
 });
+
+describe("useSessionPageFlow — arming derived from the in-flight run (#816)", () => {
+  afterEach(() => {
+    mockConv.activeStreamExecution = null;
+    mockConv.completedExecutions = [];
+    vi.clearAllMocks();
+  });
+
+  it("reflects an active execution armed at create (launcher handoff)", () => {
+    mockConv.activeStreamExecution = { spec: { autoApproveAll: true }, status: {} };
+    const { result } = renderHook(() => useSessionPageFlow(OPTS));
+    expect(result.current.autoApproveAll).toBe(true);
+  });
+
+  it("the user's explicit OFF beats the armed run for follow-up carry", async () => {
+    mockConv.activeStreamExecution = { spec: { autoApproveAll: true }, status: {} };
+    const { result } = renderHook(() => useSessionPageFlow(OPTS));
+
+    act(() => {
+      result.current.setAutoApproveAll(false);
+    });
+    expect(result.current.autoApproveAll).toBe(false);
+
+    await act(async () => {
+      await result.current.handleSubmit("after explicit off");
+    });
+    const followUpOpts = mockSendFollowUp.mock.calls.at(-1)?.[1];
+    expect(followUpOpts.autoApproveAll).toBeUndefined();
+  });
+
+  it("never derives from PAST executions (the reset-on-reload consent contract)", () => {
+    // A reloaded page whose history contains an armed run must come up at
+    // the host default — deriving from history would make the consent
+    // silently survive reloads.
+    mockConv.completedExecutions = [{ spec: { autoApproveAll: true }, status: {} }];
+    const { result } = renderHook(() => useSessionPageFlow(OPTS));
+    expect(result.current.autoApproveAll).toBe(false);
+  });
+});
+
+describe("useSessionPageFlow — armed responder (#816, the walk-away scenario)", () => {
+  beforeEach(() => {
+    mockSubmitApproval.mockResolvedValue(undefined);
+  });
+  afterEach(() => {
+    mockConv.pendingApprovals = [];
+    mockConv.activeStreamExecution = null;
+    mockConv.session = { spec: {} };
+    vi.clearAllMocks();
+  });
+
+  it("releases a gate that appears while armed", async () => {
+    const { rerender } = renderHook(() => useSessionPageFlow(OPTS), {
+      wrapper: hostDefaultWrapper(true),
+    });
+
+    mockConv.pendingApprovals = [{ toolCallId: "tc1" }];
+    await act(async () => rerender());
+
+    expect(mockSubmitApproval).toHaveBeenCalledExactlyOnceWith(
+      "tc1",
+      ApprovalAction.APPROVE_ALL,
+    );
+  });
+
+  it("releases a gate already waiting when the toggle flips ON", async () => {
+    mockConv.pendingApprovals = [{ toolCallId: "tc9" }];
+    const { result } = renderHook(() => useSessionPageFlow(OPTS));
+    expect(mockSubmitApproval).not.toHaveBeenCalled();
+
+    await act(async () => {
+      result.current.setAutoApproveAll(true);
+    });
+
+    expect(mockSubmitApproval).toHaveBeenCalledExactlyOnceWith(
+      "tc9",
+      ApprovalAction.APPROVE_ALL,
+    );
+  });
+
+  it("submits once per gate across re-renders", async () => {
+    const { rerender } = renderHook(() => useSessionPageFlow(OPTS), {
+      wrapper: hostDefaultWrapper(true),
+    });
+
+    mockConv.pendingApprovals = [{ toolCallId: "tc1" }];
+    await act(async () => rerender());
+    await act(async () => rerender());
+
+    expect(mockSubmitApproval).toHaveBeenCalledTimes(1);
+  });
+
+  it("covers a LATER gate of a different class (lease scope contract)", async () => {
+    // A gate-time APPROVE_ALL grants a class-scoped lease, so a second gate
+    // of another class still parks — the responder must answer it too.
+    const { rerender } = renderHook(() => useSessionPageFlow(OPTS), {
+      wrapper: hostDefaultWrapper(true),
+    });
+
+    mockConv.pendingApprovals = [{ toolCallId: "tc-shell" }];
+    await act(async () => rerender());
+    mockConv.pendingApprovals = [{ toolCallId: "tc-write" }];
+    await act(async () => rerender());
+
+    expect(mockSubmitApproval).toHaveBeenCalledTimes(2);
+    expect(mockSubmitApproval).toHaveBeenLastCalledWith(
+      "tc-write",
+      ApprovalAction.APPROVE_ALL,
+    );
+  });
+
+  it("does not retry a failed submission (the card stays for manual action)", async () => {
+    mockSubmitApproval.mockRejectedValue(new Error("boom"));
+    const { rerender } = renderHook(() => useSessionPageFlow(OPTS), {
+      wrapper: hostDefaultWrapper(true),
+    });
+
+    mockConv.pendingApprovals = [{ toolCallId: "tc1" }];
+    await act(async () => rerender());
+    await act(async () => rerender());
+
+    expect(mockSubmitApproval).toHaveBeenCalledTimes(1);
+  });
+
+  it("stays inert while OFF", async () => {
+    const { rerender } = renderHook(() => useSessionPageFlow(OPTS));
+
+    mockConv.pendingApprovals = [{ toolCallId: "tc1" }];
+    await act(async () => rerender());
+
+    expect(mockSubmitApproval).not.toHaveBeenCalled();
+  });
+
+  it("never fires for a guest, even when the run itself is armed", async () => {
+    mockConv.activeStreamExecution = { spec: { autoApproveAll: true }, status: {} };
+    mockConv.pendingApprovals = [{ toolCallId: "tc1" }];
+    renderHook(() => useSessionPageFlow({ ...OPTS, audience: "guest" }), {
+      wrapper: hostDefaultWrapper(true),
+    });
+
+    expect(mockSubmitApproval).not.toHaveBeenCalled();
+  });
+
+  it("never fires for an observer", async () => {
+    mockConv.pendingApprovals = [{ toolCallId: "tc1" }];
+    renderHook(() => useSessionPageFlow({ ...OPTS, audience: "observer" }), {
+      wrapper: hostDefaultWrapper(true),
+    });
+
+    expect(mockSubmitApproval).not.toHaveBeenCalled();
+  });
+
+  it("never fires for a channel-origin session (read-only by construction)", async () => {
+    mockConv.session = {
+      spec: {},
+      metadata: { labels: { "stigmer.ai/channel-id": "ch_1" } },
+    };
+    mockConv.pendingApprovals = [{ toolCallId: "tc1" }];
+    renderHook(() => useSessionPageFlow(OPTS), {
+      wrapper: hostDefaultWrapper(true),
+    });
+
+    expect(mockSubmitApproval).not.toHaveBeenCalled();
+  });
+});

package/src/session/index.ts

@@ -39,6 +39,15 @@ export type {
   UseSessionConversationReturn,
 } from "./useSessionConversation.js";
 
+export { useExportTranscript } from "./useExportTranscript.js";
+export type {
+  UseExportTranscriptOptions,
+  UseExportTranscriptReturn,
+} from "./useExportTranscript.js";
+
+export { TranscriptExportMenu } from "./TranscriptExportMenu.js";
+export type { TranscriptExportMenuProps } from "./TranscriptExportMenu.js";
+
 export { useSessionArtifacts, artifactKey } from "./useSessionArtifacts.js";
 export type {
   SessionArtifactEntry,

package/src/session/run-config.ts

@@ -1,4 +1,5 @@
 import type { ServiceTierOption } from "../models/service-tier.js";
+import type { ThinkingModeOption } from "../models/thinking-mode.js";
 
 /**
  * Owner-pinned execution config for a session surface
@@ -39,6 +40,14 @@ export interface SessionRunConfig {
    * pin is a host configuration error and throws at submit.
    */
   readonly serviceTier?: ServiceTierOption;
+  /**
+   * Thinking mode for every execution (stigmer/stigmer#772).
+   * `"enabled"` requires {@link modelName} under the same contract as
+   * {@link serviceTier}: thinking is a per-model capability (the server
+   * refuses it fail-closed for Auto), so a mode pin without a model pin
+   * is a host configuration error and throws at submit.
+   */
+  readonly thinkingMode?: ThinkingModeOption;
 }
 
 /**
@@ -56,4 +65,11 @@ export function assertValidRunConfig(runConfig: SessionRunConfig): void {
         + "dimension. Pin the model the surface should run.",
     );
   }
+  if (runConfig.thinkingMode === "enabled" && !runConfig.modelName) {
+    throw new Error(
+      "SessionRunConfig: thinkingMode \"enabled\" requires modelName — "
+        + "thinking is a per-model capability and Auto (no pinned model) has "
+        + "no variant dimensions. Pin the model the surface should run.",
+    );
+  }
 }

package/src/session/useExportTranscript.ts

@@ -0,0 +1,171 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import {
+  fetchSessionTranscript,
+  resolvedSubject,
+  transcriptToJson,
+  transcriptToMarkdown,
+  type SessionTranscript,
+} from "@stigmer/sdk";
+import { toast } from "../feedback/toast.js";
+import { useStigmer } from "../hooks.js";
+import { downloadTextFile } from "../internal/download.js";
+import { generateSlug } from "../internal/slug.js";
+import { toError } from "../internal/toError.js";
+
+/** Options for {@link useExportTranscript}. */
+export interface UseExportTranscriptOptions {
+  /**
+   * Keep turns replaced by edit-and-resubmit in the export, marked as
+   * superseded. Defaults to `false` — the conversation as the viewer
+   * shows it.
+   */
+  readonly includeSuperseded?: boolean;
+}
+
+/** Return value of {@link useExportTranscript}. */
+export interface UseExportTranscriptReturn {
+  /** Copy the whole conversation as Markdown to the clipboard. */
+  readonly copyMarkdown: () => Promise<void>;
+  /** Download the whole conversation as a Markdown file. */
+  readonly downloadMarkdown: () => Promise<void>;
+  /** Download the whole conversation as a structured JSON file. */
+  readonly downloadJson: () => Promise<void>;
+  /** `true` while a transcript fetch (and offload resolution) is in flight. */
+  readonly isExporting: boolean;
+  /** The last export failure, or `null`. Cleared when a new export starts. */
+  readonly error: Error | null;
+}
+
+/**
+ * Behavior hook that exports a session's whole conversation — thinking,
+ * tool calls with offloaded outputs resolved, sub-agent turns, timestamps —
+ * as Markdown (copy or download) or structured JSON (stigmer/stigmer#814).
+ *
+ * Lazy: nothing is fetched until an action is invoked. Each action fetches
+ * the canonical transcript via `fetchSessionTranscript` (the SDK's one
+ * authoritative assembly), so every export surface produces identical
+ * content. Feedback follows the `useExportResource` convention: toasts for
+ * success/failure, plus a typed `error` for hosts that render their own.
+ *
+ * @example
+ * ```tsx
+ * const exporter = useExportTranscript(sessionId);
+ *
+ * <ActionMenu.Item onSelect={exporter.copyMarkdown}>Copy transcript</ActionMenu.Item>
+ * <ActionMenu.Item onSelect={exporter.downloadMarkdown}>Download .md</ActionMenu.Item>
+ * <ActionMenu.Item onSelect={exporter.downloadJson}>Download .json</ActionMenu.Item>
+ * ```
+ */
+export function useExportTranscript(
+  sessionId: string | null,
+  options?: UseExportTranscriptOptions,
+): UseExportTranscriptReturn {
+  const stigmer = useStigmer();
+  const includeSuperseded = options?.includeSuperseded === true;
+  const [isExporting, setIsExporting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchTranscript = useCallback((): Promise<SessionTranscript> => {
+    if (!sessionId) {
+      return Promise.reject(
+        new Error(
+          "Cannot export a transcript without a session id. Pass the session's " +
+            "id to useExportTranscript once the session exists.",
+        ),
+      );
+    }
+    return fetchSessionTranscript(stigmer, sessionId, { includeSuperseded });
+  }, [stigmer, sessionId, includeSuperseded]);
+
+  const copyMarkdown = useCallback(async (): Promise<void> => {
+    setError(null);
+    setIsExporting(true);
+    const markdown = fetchTranscript().then(
+      (t) => transcriptToMarkdown(t, { generatedAt: new Date().toISOString() }),
+    );
+    try {
+      // The transcript is fetched before it can be copied, and WebKit (the
+      // desktop app's webview) only honors clipboard writes inside the user
+      // gesture's task — a plain writeText after the await is rejected
+      // there. ClipboardItem accepts a promise, letting the write start
+      // synchronously in the gesture while the content resolves.
+      if (typeof ClipboardItem !== "undefined" && navigator.clipboard?.write) {
+        await navigator.clipboard.write([
+          new ClipboardItem({
+            "text/plain": markdown.then(
+              (text) => new Blob([text], { type: "text/plain" }),
+            ),
+          }),
+        ]);
+      } else {
+        await navigator.clipboard.writeText(await markdown);
+      }
+      toast.success("Transcript copied to clipboard");
+    } catch (e) {
+      const err = toError(e);
+      setError(err);
+      toast.error(`Couldn't copy the transcript: ${err.message}`);
+    } finally {
+      setIsExporting(false);
+    }
+  }, [fetchTranscript]);
+
+  const download = useCallback(
+    async (serialize: (t: SessionTranscript) => { content: string; extension: string; mimeType: string }): Promise<void> => {
+      setError(null);
+      setIsExporting(true);
+      try {
+        const transcript = await fetchTranscript();
+        const { content, extension, mimeType } = serialize(transcript);
+        downloadTextFile(
+          content,
+          `${transcriptFilename(transcript)}.${extension}`,
+          mimeType,
+        );
+      } catch (e) {
+        const err = toError(e);
+        setError(err);
+        toast.error(`Couldn't export the transcript: ${err.message}`);
+      } finally {
+        setIsExporting(false);
+      }
+    },
+    [fetchTranscript],
+  );
+
+  const downloadMarkdown = useCallback(
+    () =>
+      download((t) => ({
+        content: transcriptToMarkdown(t, {
+          generatedAt: new Date().toISOString(),
+        }),
+        extension: "md",
+        mimeType: "text/markdown",
+      })),
+    [download],
+  );
+
+  const downloadJson = useCallback(
+    () =>
+      download((t) => ({
+        content: JSON.stringify(transcriptToJson(t), null, 2),
+        extension: "json",
+        mimeType: "application/json",
+      })),
+    [download],
+  );
+
+  return useMemo(
+    () => ({ copyMarkdown, downloadMarkdown, downloadJson, isExporting, error }),
+    [copyMarkdown, downloadMarkdown, downloadJson, isExporting, error],
+  );
+}
+
+/** `<subject-slug>-transcript`, falling back to the session id. */
+function transcriptFilename(transcript: SessionTranscript): string {
+  const subject = resolvedSubject(transcript.session.spec?.subject);
+  const slug = subject ? generateSlug(subject).slice(0, 60) : "";
+  return `${slug || transcript.session.metadata?.id || "session"}-transcript`;
+}

package/src/session/useNewSessionFlow.ts

@@ -218,6 +218,18 @@ export interface UseNewSessionFlowReturn {
   /** Session variables (per-execution secrets) manager. */
   readonly sessionVariables: UseSessionVariablesReturn;
 
+  /**
+   * Pre-arm "auto-approve tool calls" for the session this surface will
+   * create (stigmer/stigmer#816, the walk-away scenario). Seeded from the
+   * host's `StigmerProvider` `approvalDefaults` (#302, guests excluded);
+   * the user's toggle wins from then on. Carried into the bootstrap create
+   * as `spec.auto_approve_all` — the whole-run server-side bypass — so the
+   * first run stays covered even if the user closes the tab.
+   */
+  readonly autoApproveAll: boolean;
+  /** Set the user's explicit auto-approve choice for the created session. */
+  readonly setAutoApproveAll: (value: boolean) => void;
+
   /** `true` while the create session + execution flow is in flight. */
   readonly isSubmitting: boolean;
   /** Human-readable error from the last failed submission, or `null`. */
@@ -307,16 +319,22 @@ export function useNewSessionFlow(
   if (runConfig) assertValidRunConfig(runConfig);
   const pinnedModelName = runConfig?.modelName;
   const pinnedServiceTier = runConfig?.serviceTier;
+  const pinnedThinkingMode = runConfig?.thinkingMode;
   const contextTarget = useExecutionTarget();
   const executionTarget = options.executionTarget ?? contextTarget;
   const adapter = useRunnerAdapter();
-  // Host approval default (#302): pre-arm auto_approve_all on the bootstrap
-  // create when the provider says so. Guests never inherit it — a share-link
-  // visitor is not the operator the host's trust judgment covers (the
-  // GUEST_HARNESS fixed-platform-policy reasoning).
+  // Auto-approve for the session about to be created (#816): the host
+  // approval default (#302) seeds the INITIAL state only; the user's
+  // composer toggle wins from then on. Guests never inherit the default
+  // and never see the toggle — a share-link visitor is not the operator
+  // the host's trust judgment covers (the GUEST_HARNESS
+  // fixed-platform-policy reasoning). Carried into the bootstrap create as
+  // spec.auto_approve_all, the whole-run server-side bypass — the created
+  // run stays covered even if this tab dies before its first gate.
   const approvalDefaults = useApprovalDefaults();
-  const autoApproveAll =
-    (!isGuest && approvalDefaults?.autoApproveAll) || undefined;
+  const [autoApproveAll, setAutoApproveAll] = useState(
+    () => !isGuest && (approvalDefaults?.autoApproveAll ?? false),
+  );
 
   const [harness, setHarnessRaw] = useState<HarnessOption>(() => {
     // Guests get the fixed platform policy (see GUEST_HARNESS) and never
@@ -490,8 +508,14 @@ export function useNewSessionFlow(
           serviceTier: pinnedModelName
             ? (pinnedServiceTier === "fast" ? "fast" : undefined)
             : context?.serviceTier,
+          // The tier's #772 twin, same pin-wins + only-explicit-enabled rule.
+          thinkingMode: pinnedModelName
+            ? (pinnedThinkingMode === "enabled" ? "enabled" : undefined)
+            : context?.thinkingMode,
           workspaceFileRefs: context?.workspaceFileRefs,
-          autoApproveAll,
+          // Only an armed state travels; false stays off the wire (the
+          // serviceTier/thinkingMode only-explicit discipline).
+          autoApproveAll: autoApproveAll || undefined,
         };
 
         // Resolve which agent the bootstrapped session runs against: an
@@ -584,6 +608,7 @@ export function useNewSessionFlow(
       effectiveModelId,
       pinnedModelName,
       pinnedServiceTier,
+      pinnedThinkingMode,
       workspace,
       mcpServerUsages,
       skillRefs,
@@ -618,6 +643,8 @@ export function useNewSessionFlow(
     setSkillRefs,
     workspace,
     sessionVariables,
+    autoApproveAll,
+    setAutoApproveAll,
     isSubmitting,
     submitError,
     submit,

package/src/session/useSessionConversation.ts

@@ -9,15 +9,18 @@ import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_
 import type { McpServerUsage as ProtoMcpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { WorkspaceEntry as ProtoWorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
 import type { ApiResourceReference as ProtoApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import type {
-  AttachmentInput,
-  EnvVarInput,
-  McpServerUsageInput,
-  ResourceRef,
-  WorkspaceEntryInput,
+import {
+  supersededExecutionIds,
+  toSessionUpdateInput,
+  type AttachmentInput,
+  type EnvVarInput,
+  type McpServerUsageInput,
+  type ResourceRef,
+  type WorkspaceEntryInput,
 } from "@stigmer/sdk";
 import { isTerminalPhase } from "../execution/execution-phases.js";
 import type { ServiceTierOption } from "../models/service-tier.js";
+import type { ThinkingModeOption } from "../models/thinking-mode.js";
 import { useStigmer } from "../hooks.js";
 import { toError } from "../internal/toError.js";
 import { useConversationStoreRef } from "../internal/store/index.js";
@@ -32,11 +35,6 @@ import { useSession } from "./useSession.js";
 import { useSessionExecutions } from "./useSessionExecutions.js";
 import { useUpdateSession } from "./useUpdateSession.js";
 import { useLocalSessionWorker } from "./useLocalSessionWorker.js";
-import {
-  specWorkspaceToInput,
-  specMcpUsagesToInput,
-  specSkillRefsToInput,
-} from "./session-spec-converters.js";
 
 /**
  * Cadence for re-discovering the session's executions while the live stream
@@ -111,6 +109,16 @@ export interface SendFollowUpOptions {
    * @see {@link SharedAgentExecutionFields.serviceTier}
    */
   readonly serviceTier?: ServiceTierOption;
+  /**
+   * Thinking mode for this execution's model calls (stigmer/stigmer#772).
+   *
+   * Only set when the user actively selected `"enabled"`; `undefined`
+   * preserves the unspecified-vs-explicit distinction (unset resolves to
+   * disabled on the platform side — never the provider account default).
+   *
+   * @see {@link SharedAgentExecutionFields.thinkingMode}
+   */
+  readonly thinkingMode?: ThinkingModeOption;
   /**
    * Marks this execution as a Build-from-plan turn.
    *
@@ -537,13 +545,11 @@ export function useSessionConversation(
     }
   }, [activeExecutionId, stream.phase, refetch]);
 
-  // Executions replaced via edit-and-resubmit. The successor carries
-  // `spec.supersedes_execution_id`; hiding the superseded turn makes the
-  // edited message read as a single corrected exchange (in-place replace).
-  // The link must also be read off the live stream copy — right after a
-  // resubmit, the successor streams before the list refetch delivers it.
-  // Display-only: the raw `executions` list (and therefore active-id
-  // resolution above) is never filtered.
+  // Executions replaced via edit-and-resubmit (the shared conversation rule —
+  // see supersededExecutionIds in @stigmer/sdk for the why). The extra id is
+  // the live stream copy's link: right after a resubmit, the successor streams
+  // before the list refetch delivers it. Display-only: the raw `executions`
+  // list (and therefore active-id resolution above) is never filtered.
   //
   // Dep is the scalar link, NOT stream.execution: the stream object changes
   // reference every frame, and rebuilding the Set per frame would hand
@@ -551,15 +557,10 @@ export function useSessionConversation(
   // memoization (DD-010).
   const streamSupersededId =
     stream.execution?.spec?.supersedesExecutionId || null;
-  const supersededIds = useMemo(() => {
-    const ids = new Set<string>();
-    for (const e of executions) {
-      const superseded = e.spec?.supersedesExecutionId;
-      if (superseded) ids.add(superseded);
-    }
-    if (streamSupersededId) ids.add(streamSupersededId);
-    return ids;
-  }, [executions, streamSupersededId]);
+  const supersededIds = useMemo(
+    () => supersededExecutionIds(executions, streamSupersededId),
+    [executions, streamSupersededId],
+  );
 
   const completedExecutions = useMemo(() => {
     return executions.filter((e) => {
@@ -674,6 +675,7 @@ export function useSessionConversation(
           attachments: options?.attachments,
           interactionMode: options?.interactionMode,
           serviceTier: options?.serviceTier,
+          thinkingMode: options?.thinkingMode,
           buildFromPlan: options?.buildFromPlan,
           autoApproveAll: options?.autoApproveAll,
           workspaceFileRefs: options?.workspaceFileRefs,
@@ -818,13 +820,13 @@ export function useSessionConversation(
 // ---------------------------------------------------------------------------
 
 /**
- * Converts the existing Session proto into a SessionInput suitable for
- * the update RPC (which uses replace semantics — the full spec is sent).
- *
- * For each session-level collection (workspace, MCP servers, skills):
- * if an override is provided, it replaces the existing value; otherwise
- * the current session value is preserved by converting it back to input
- * format.
+ * Builds the SessionInput for the update RPC (which uses replace
+ * semantics — the full spec is sent) by spreading the SDK's complete
+ * generated mapper and overriding only the session-level collections the
+ * caller provided. An override replaces the existing value; an omitted
+ * field keeps the fetched session's value (an empty-array override
+ * clears the collection — normalized to absent, the mappers' canonical
+ * shape).
  */
 function buildUpdateInput(
   session: Session,
@@ -835,30 +837,14 @@ function buildUpdateInput(
     skillRefs?: ResourceRef[];
   },
 ) {
-  const meta = session.metadata!;
-  const spec = session.spec;
-
-  const workspaceEntries =
-    overrides.workspaceEntries ?? specWorkspaceToInput(spec);
-
-  const mcpServerUsages =
-    overrides.mcpServerUsages ?? specMcpUsagesToInput(spec);
-
-  const skillRefs = overrides.skillRefs ?? specSkillRefsToInput(spec);
+  const mapped = toSessionUpdateInput(session);
+  const workspaceEntries = overrides.workspaceEntries ?? mapped.workspaceEntries;
+  const mcpServerUsages = overrides.mcpServerUsages ?? mapped.mcpServerUsages;
+  const skillRefs = overrides.skillRefs ?? mapped.skillRefs;
 
   return {
-    name: meta.name,
-    org: meta.org,
-    agentInstanceId: overrides.agentInstanceId ?? (spec?.agentInstanceId || undefined),
-    subject: spec?.subject || undefined,
-    harnessStateId: spec?.harnessStateId || undefined,
-    harness: spec?.harness,
-    cursorMode: spec?.cursorMode,
-    executionTarget: spec?.executionTarget,
-    metadata:
-      spec?.metadata && Object.keys(spec.metadata).length > 0
-        ? { ...spec.metadata }
-        : undefined,
+    ...mapped,
+    agentInstanceId: overrides.agentInstanceId ?? mapped.agentInstanceId,
     workspaceEntries: workspaceEntries?.length ? workspaceEntries : undefined,
     mcpServerUsages: mcpServerUsages?.length ? mcpServerUsages : undefined,
     skillRefs: skillRefs?.length ? skillRefs : undefined,