@stigmer/react 3.12.4 → 3.12.6

package/src/session/useSessionConversation.ts

@@ -9,15 +9,17 @@ 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 {
+  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 +34,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 +108,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.
    *
@@ -674,6 +681,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 +826,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 +843,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,

package/src/session/useSessionPageFlow.ts

@@ -18,7 +18,7 @@ import { useSessionConversation, type UseSessionConversationReturn } from "./use
 import { resolveExecutionRuntimeEnv, type RuntimeEnvProvider } from "./runtime-env.js";
 import { useAgentRefFromSession } from "./useAgentRefFromSession.js";
 import { usePersistedModel, type UsePersistedModelReturn } from "./usePersistedModel.js";
-import { specMcpUsagesToInput, specSkillRefsToInput } from "./session-spec-converters.js";
+import { toSessionUpdateInput } from "@stigmer/sdk";
 import type { SessionAudience } from "./audience.js";
 import { assertValidRunConfig, type SessionRunConfig } from "./run-config.js";
 
@@ -267,6 +267,7 @@ export function useSessionPageFlow(
   // callback's identity must not churn on every render (DD-010).
   const pinnedModelName = runConfig?.modelName;
   const pinnedServiceTier = runConfig?.serviceTier;
+  const pinnedThinkingMode = runConfig?.thinkingMode;
 
   const stigmer = useStigmer();
   const conv = useSessionConversation(sessionId, org);
@@ -401,16 +402,14 @@ export function useSessionPageFlow(
       }
     }
 
-    // MCP server usages
-    const mcpInputs = specMcpUsagesToInput(spec);
-    if (mcpInputs?.length) {
-      setMcpServerUsages(mcpInputs);
+    // MCP server usages and skill references, hydrated through the SDK's
+    // complete update-input mapper (the canonical proto → input lens).
+    const mapped = toSessionUpdateInput(conv.session);
+    if (mapped.mcpServerUsages?.length) {
+      setMcpServerUsages(mapped.mcpServerUsages);
     }
-
-    // Skill references
-    const skillInputs = specSkillRefsToInput(spec);
-    if (skillInputs?.length) {
-      setSkillRefs(skillInputs);
+    if (mapped.skillRefs?.length) {
+      setSkillRefs(mapped.skillRefs);
     }
   }, [conv.session, workspace]);
 
@@ -480,6 +479,10 @@ export function useSessionPageFlow(
         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,
         buildFromPlan: context?.buildFromPlan,
         // Sourced from the session-scoped preference set at the approval gate,
         // not from the composer (the pre-arm toggle was removed).
@@ -490,7 +493,7 @@ export function useSessionPageFlow(
 
       sessionVariables.clear();
     },
-    [conv.sendFollowUp, modelId, pinnedModelName, pinnedServiceTier, workspace, mcpServerUsages, skillRefs, sessionVariables.clear, resolution, agentRef, sessionInstanceId, stigmer, autoApproveAll, getRuntimeEnv],
+    [conv.sendFollowUp, modelId, pinnedModelName, pinnedServiceTier, pinnedThinkingMode, workspace, mcpServerUsages, skillRefs, sessionVariables.clear, resolution, agentRef, sessionInstanceId, stigmer, autoApproveAll, getRuntimeEnv],
   );
 
   // -------------------------------------------------------------------------

package/src/session/useUpdateSession.ts

@@ -25,40 +25,34 @@ export interface UseUpdateSessionReturn {
  * by the backend to identify the resource) and all spec fields.
  *
  * **Full-replace semantics.** The backend replaces the entire spec with
- * what you send — there is no field mask. Round-trip every spec field
- * you do not intend to change, *including `metadata`*: an update built
- * from a reconstructed partial spec silently wipes the fields it omits
- * (workspace entries, MCP servers, and `stigmer.ai/*` metadata keys such
- * as the embedder session context). To change only the subject, prefer
- * the field-level `session.updateSubject()` RPC instead of this hook.
+ * what you send — there is no field mask. Spread the SDK's complete
+ * `toSessionUpdateInput()` mapper and override only the fields you
+ * change: an update built from a reconstructed partial spec silently
+ * wipes the fields it omits (workspace entries, MCP servers, and
+ * `stigmer.ai/*` metadata keys such as the embedder session context).
+ * To change only the subject, prefer the field-level
+ * `session.updateSubject()` RPC instead of this hook.
  *
  * Typically composed into higher-level hooks like
- * {@link useSessionConversation} (whose update path round-trips the
- * fetched spec) rather than used directly. Platform builders who need
- * direct session mutation can use this hook standalone.
+ * {@link useSessionConversation} (whose update path spreads the mapper
+ * over a freshly fetched session) rather than used directly. Platform
+ * builders who need direct session mutation can use this hook
+ * standalone.
  *
  * @example
  * ```tsx
+ * import { toSessionUpdateInput } from "@stigmer/sdk";
+ *
  * function TagSession({ session }: { session: Session }) {
  *   const { update, isUpdating } = useUpdateSession();
  *
  *   async function handleTag() {
- *     const spec = session.spec;
+ *     const mapped = toSessionUpdateInput(session);
  *     await update({
- *       name: session.metadata!.name,
- *       org: session.metadata!.org,
- *       // Full replace: carry over every fetched spec field...
- *       agentInstanceId: spec?.agentInstanceId,
- *       subject: spec?.subject,
- *       harnessStateId: spec?.harnessStateId,
- *       harness: spec?.harness,
- *       cursorMode: spec?.cursorMode,
- *       executionTarget: spec?.executionTarget,
- *       // ...including the spec lists (workspaceEntries, mcpServerUsages,
- *       // skillRefs), converted from the fetched proto exactly as
- *       // useSessionConversation's update path does...
- *       // ...then apply the one change on top of the carried metadata.
- *       metadata: { ...spec?.metadata, "acme/reviewed": "true" },
+ *       ...mapped,
+ *       // Nested values follow the same rule: spread the mapper's
+ *       // complete value, then apply the one change on top.
+ *       metadata: { ...mapped.metadata, "acme/reviewed": "true" },
  *     });
  *   }
  *

package/src/settings/AccountPreferencesSection.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+import { useId } from "react";
+import { AccountPreferencesPanel } from "../identity-account/AccountPreferencesPanel.js";
+
+/** Settings section for editing the current user's declared preferences. */
+export function AccountPreferencesSection() {
+  const headingId = useId();
+
+  return (
+    <section aria-labelledby={headingId}>
+      <h2
+        id={headingId}
+        className="stg:text-foreground stg:mb-1 stg:text-sm stg:font-semibold"
+      >
+        Account Preferences
+      </h2>
+      <p className="stg:text-muted-foreground stg:mb-6 stg:text-xs">
+        Personal standing context shared with agents on executions you run.
+      </p>
+
+      <AccountPreferencesPanel />
+    </section>
+  );
+}

package/src/settings/OrgPreferencesSection.tsx

@@ -0,0 +1,35 @@
+"use client";
+
+import { useId } from "react";
+import { OrgPreferencesPanel } from "../organization/OrgPreferencesPanel.js";
+import { useOrg } from "../organization/OrgProvider.js";
+
+/** Settings section for editing the active organization's declared preferences. */
+export function OrgPreferencesSection() {
+  const headingId = useId();
+  const { activeOrg } = useOrg();
+  const orgId = activeOrg?.metadata?.id ?? "";
+
+  return (
+    <section aria-labelledby={headingId}>
+      <h2
+        id={headingId}
+        className="stg:text-foreground stg:mb-1 stg:text-sm stg:font-semibold"
+      >
+        Organization Preferences
+      </h2>
+      <p className="stg:text-muted-foreground stg:mb-6 stg:text-xs">
+        Standing context shared with agents on every execution run by this
+        organization&apos;s members.
+      </p>
+
+      {!orgId ? (
+        <p className="stg:text-muted-foreground stg:py-4 stg:text-center stg:text-xs">
+          Select an organization to view its preferences.
+        </p>
+      ) : (
+        <OrgPreferencesPanel orgId={orgId} />
+      )}
+    </section>
+  );
+}

package/src/settings/__tests__/settings-nav.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { SETTINGS_NAV_GROUPS } from "../settings-nav";
+
+// The nav model is the single source for the sidebar AND both client-app
+// landing grids — these entries disappearing would silently orphan the
+// preference pages everywhere at once.
+describe("SETTINGS_NAV_GROUPS preference entries", () => {
+  it("lists org preferences in the Organization group", () => {
+    const organization = SETTINGS_NAV_GROUPS.find(
+      (g) => g.label === "Organization",
+    );
+    expect(organization).toBeDefined();
+    expect(
+      organization!.items.find((i) => i.href === "/settings/org-preferences")
+        ?.label,
+    ).toBe("Preferences");
+  });
+
+  it("lists account preferences in the Account group", () => {
+    const account = SETTINGS_NAV_GROUPS.find((g) => g.label === "Account");
+    expect(account).toBeDefined();
+    expect(
+      account!.items.find((i) => i.href === "/settings/account-preferences")
+        ?.label,
+    ).toBe("Preferences");
+  });
+});

package/src/settings/index.ts

@@ -10,6 +10,8 @@ export { BillingSection } from "./BillingSection.js";
 export type { BillingSectionProps } from "./BillingSection.js";
 export { MembersSection } from "./MembersSection.js";
 export { OrgProfileSection } from "./OrgProfileSection.js";
+export { OrgPreferencesSection } from "./OrgPreferencesSection.js";
+export { AccountPreferencesSection } from "./AccountPreferencesSection.js";
 export { EnvironmentsSection } from "./EnvironmentsSection.js";
 export { InvitationsSection } from "./InvitationsSection.js";
 export { IdentityProvidersSection } from "./IdentityProvidersSection.js";

package/src/settings/settings-nav.ts

@@ -13,6 +13,8 @@ import {
   Plug,
   Scale,
   ShieldCheck,
+  SlidersHorizontal,
+  UserCog,
   Users,
 } from "lucide-react";
 
@@ -55,6 +57,11 @@ export const SETTINGS_NAV_GROUPS: readonly SettingsNavGroup[] = [
       "Manage your team, organization identity, and identity providers.",
     items: [
       { href: "/settings/org-profile", label: "Org Profile", icon: Building2 },
+      {
+        href: "/settings/org-preferences",
+        label: "Preferences",
+        icon: SlidersHorizontal,
+      },
       { href: "/settings/members", label: "Members", icon: Users },
       { href: "/settings/invitations", label: "Invitations", icon: Link },
       {
@@ -92,6 +99,17 @@ export const SETTINGS_NAV_GROUPS: readonly SettingsNavGroup[] = [
       { href: "/settings/usage", label: "Usage", icon: BarChart3 },
     ],
   },
+  {
+    label: "Account",
+    description: "Personal settings that apply to you across the platform.",
+    items: [
+      {
+        href: "/settings/account-preferences",
+        label: "Preferences",
+        icon: UserCog,
+      },
+    ],
+  },
 ];
 
 /**

package/src/workflow/ApprovalFormBuilder.tsx

@@ -24,11 +24,17 @@ interface FormFieldEntry {
   enumValues: string;
 }
 
+// ESCALATE carries the outcome-by-name contract (stigmer/stigmer#781): the
+// timeout resolves to the outcome NAMED "escalate" and follows its routing,
+// so the gate must declare that outcome — no extra config fields (the
+// pre-#779 option wrote an `escalation_task` field the proto never had).
+// The builder hints when the outcome is missing; the server validator is
+// the enforcement.
 const TIMEOUT_POLICY_OPTIONS = [
   { value: "HUMAN_INPUT_TIMEOUT_FAIL", label: "Fail — task errors on timeout" },
   { value: "HUMAN_INPUT_TIMEOUT_APPROVE", label: "Auto-approve — proceed as approved" },
   { value: "HUMAN_INPUT_TIMEOUT_DENY", label: "Auto-deny — proceed as denied" },
-  { value: "HUMAN_INPUT_TIMEOUT_ESCALATE", label: "Escalate — branch to escalation task" },
+  { value: "HUMAN_INPUT_TIMEOUT_ESCALATE", label: "Escalate — route via the 'escalate' outcome" },
 ] as const;
 
 const TIMEOUT_UNITS = [
@@ -107,8 +113,7 @@ export const ApprovalFormBuilder = memo(function ApprovalFormBuilder({
       <TimeoutSection
         timeout={typeof cfg.timeout === "number" ? cfg.timeout : 0}
         onTimeout={typeof cfg.on_timeout === "string" ? cfg.on_timeout : ""}
-        escalationTask={typeof cfg.escalation_task === "string" ? cfg.escalation_task : ""}
-        allTaskNames={allTaskNames}
+        hasEscalateOutcome={extractOutcomes(cfg).some((o) => o.name === "escalate")}
         onUpdateConfig={onUpdateConfig}
       />
       <StringListSection
@@ -619,14 +624,12 @@ function FormFieldRow({
 function TimeoutSection({
   timeout,
   onTimeout,
-  escalationTask,
-  allTaskNames,
+  hasEscalateOutcome,
   onUpdateConfig,
 }: {
   timeout: number;
   onTimeout: string;
-  escalationTask: string;
-  allTaskNames: readonly string[];
+  hasEscalateOutcome: boolean;
   onUpdateConfig: (fieldPath: string, value: unknown) => void;
 }) {
   const bestUnit = useMemo(() => {
@@ -665,8 +668,6 @@ function TimeoutSection({
     [timeout, unit, onUpdateConfig],
   );
 
-  const isEscalate = onTimeout === "HUMAN_INPUT_TIMEOUT_ESCALATE";
-
   return (
     <CollapsibleSection title="Timeout">
       <div className="stg:flex stg:items-center stg:gap-1">
@@ -707,27 +708,19 @@ function TimeoutSection({
               <option key={opt.value} value={opt.value}>{opt.label}</option>
             ))}
           </select>
+          {onTimeout === "HUMAN_INPUT_TIMEOUT_ESCALATE" && !hasEscalateOutcome && (
+            <p
+              role="alert"
+              className="stg:text-[10px] stg:text-[var(--stgm-warning,#d97706)]"
+            >
+              Escalate needs an outcome named &quot;escalate&quot; with routing —
+              the timeout resolves to it. Add the outcome above, or the server
+              will reject this workflow.
+            </p>
+          )}
         </div>
       )}
 
-      {isEscalate && (
-        <div className="stg:mt-1.5 stg:flex stg:flex-col stg:gap-1">
-          <label className="stg:text-[10px] stg:text-[var(--stgm-muted-foreground,#737373)]">
-            Escalation task
-          </label>
-          <select
-            value={escalationTask}
-            onChange={(e) => onUpdateConfig("escalation_task", e.target.value || undefined)}
-            className={cn(smallInputClass)}
-            aria-label="Escalation target task"
-          >
-            <option value="">— Select escalation task —</option>
-            {allTaskNames.map((name) => (
-              <option key={name} value={name}>{name}</option>
-            ))}
-          </select>
-        </div>
-      )}
     </CollapsibleSection>
   );
 }

package/src/workflow/WorkflowDetailView.tsx

@@ -9,7 +9,7 @@ import { ValidationState } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/
 import type { WorkflowInput } from "@stigmer/sdk";
 import { useWorkflow } from "./useWorkflow.js";
 import { useUpdateWorkflow } from "./useUpdateWorkflow.js";
-import { workflowToInput } from "./internal/workflowToInput.js";
+import { toWorkflowUpdateInput } from "@stigmer/sdk";
 import { useWorkflowExecutionList } from "./useWorkflowExecutionList.js";
 import { useWorkflowDashboardSummary } from "./useWorkflowDashboardSummary.js";
 import { WorkflowOverviewGraph } from "./WorkflowOverviewGraph.js";
@@ -189,7 +189,7 @@ export function WorkflowDetailView({
       value: WorkflowInput[K],
     ): Promise<boolean> => {
       if (!workflow) return false;
-      const input = workflowToInput(workflow);
+      const input = toWorkflowUpdateInput(workflow);
       (input as unknown as Record<string, unknown>)[field] = value;
       try {
         const updated = await update(input);

package/src/workflow/__tests__/WorkflowInstanceDetailPanel.test.tsx

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  WorkflowInstanceSchema,
+  type WorkflowInstance,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import { WorkflowExecutionVisibility } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/spec_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { WorkflowInstanceInput } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { WorkflowInstanceDetailPanel } from "../instance/WorkflowInstanceDetailPanel";
+
+/**
+ * Regression suite for the full-spec-replace wipe bug: before the
+ * generated-mapper migration, saving environment edits in this panel
+ * silently reset `execution_visibility` (run observability, which has its
+ * own dedicated updateExecutionVisibility RPC and control). The panel
+ * must spread `toWorkflowInstanceUpdateInput` and override only the
+ * environment refs.
+ */
+
+const INSTANCE: WorkflowInstance = create(WorkflowInstanceSchema, {
+  metadata: {
+    id: "wfi-1",
+    name: "Nightly Triage",
+    slug: "nightly-triage",
+    org: "acme",
+  },
+  spec: {
+    workflowId: "wf-1",
+    description: "Runs every night.",
+    environmentRefs: [
+      { org: "acme", slug: "prod", kind: ApiResourceKind.environment },
+    ],
+    executionVisibility: WorkflowExecutionVisibility.organization,
+  },
+});
+
+function renderPanel(update: ReturnType<typeof vi.fn>) {
+  const client = {
+    workflowInstance: { update },
+    iamPolicy: {
+      checkMyPermission: vi.fn(async () => ({ isAuthorized: true })),
+    },
+    environment: {
+      list: vi.fn(async () => ({ items: [], totalCount: 0 })),
+    },
+  } as never;
+  return render(
+    <StigmerContext.Provider value={client}>
+      <WorkflowInstanceDetailPanel instance={INSTANCE} org="acme" onClose={() => {}} />
+    </StigmerContext.Provider>,
+  );
+}
+
+afterEach(cleanup);
+
+describe("WorkflowInstanceDetailPanel save payload", () => {
+  it("round-trips execution_visibility on an environments-only save (the wipe bug)", async () => {
+    const update = vi.fn(async (_input: WorkflowInstanceInput) => INSTANCE);
+    renderPanel(update);
+
+    fireEvent.click(await screen.findByRole("button", { name: "Edit" }));
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() => expect(update).toHaveBeenCalledTimes(1));
+    const input = update.mock.calls[0]![0];
+
+    // The wipe-bug guard: run visibility is edited elsewhere and must
+    // survive an environment save untouched.
+    expect(input.executionVisibility).toBe(
+      WorkflowExecutionVisibility.organization,
+    );
+    expect(input.workflowId).toBe("wf-1");
+    expect(input.description).toBe("Runs every night.");
+    // The form-owned field.
+    expect(input.environmentRefs).toEqual([{ org: "acme", slug: "prod" }]);
+    // Addressing fields.
+    expect(input.org).toBe("acme");
+    expect(input.slug).toBe("nightly-triage");
+  });
+});

package/src/workflow/index.ts

@@ -481,8 +481,6 @@ export {
   type UseUpdateWorkflowReturn,
 } from "./useUpdateWorkflow.js";
 
-export { workflowToInput } from "./internal/workflowToInput.js";
-
 // Starter YAML template for new workflow creation
 export { STARTER_WORKFLOW_YAML } from "./starter-workflow-yaml.js";
 

package/src/workflow/instance/WorkflowInstanceDetailPanel.tsx

@@ -9,7 +9,7 @@ import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apires
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { WorkflowExecutionVisibility } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/spec_pb";
 import type { ResourceRef } from "@stigmer/sdk";
-import { getUserMessage } from "@stigmer/sdk";
+import { getUserMessage, toWorkflowInstanceUpdateInput } from "@stigmer/sdk";
 import { useUpdateWorkflowInstance } from "./useUpdateWorkflowInstance.js";
 import { useDeleteWorkflowInstance } from "./useDeleteWorkflowInstance.js";
 import { RunVisibilityControl } from "./RunVisibilityControl.js";
@@ -104,20 +104,19 @@ export function WorkflowInstanceDetailPanel({
 
   const handleSaveEnvs = useCallback(async () => {
     try {
+      // Full-spec-replace safety: spread the complete mapped input so
+      // unlisted spec fields (e.g. execution_visibility, which has its
+      // own dedicated control above) survive an environment-only save.
       await update({
-        name: meta?.name ?? "",
-        org: meta?.org ?? org,
-        workflowId: spec?.workflowId ?? "",
-        description: spec?.description,
+        ...toWorkflowInstanceUpdateInput(instance),
         environmentRefs: editEnvRefs,
-        visibility: meta?.visibility,
       });
       setIsEditingEnvs(false);
       onUpdated?.();
     } catch {
       // error displayed by hook
     }
-  }, [update, meta, spec, org, editEnvRefs, onUpdated]);
+  }, [update, instance, editEnvRefs, onUpdated]);
 
   const handleDelete = useCallback(async () => {
     setDeleteError(null);

package/src/workflow/useUpdateWorkflow.ts

@@ -23,9 +23,9 @@ export interface UseUpdateWorkflowReturn {
  *
  * Wraps `stigmer.workflow.update(input)` with loading and error state.
  * The caller must provide a **complete** `WorkflowInput` -- the backend
- * performs full spec replacement. Use `workflowToInput()` to reconstruct
- * the input from a fetched workflow, modify the desired field, and pass
- * the result here.
+ * performs full spec replacement. Use `toWorkflowUpdateInput()` (from
+ * `@stigmer/sdk`) to reconstruct the input from a fetched workflow,
+ * modify the desired field, and pass the result here.
  */
 export function useUpdateWorkflow(): UseUpdateWorkflowReturn {
   const stigmer = useStigmer();