apps/controller/src/store/schemas.ts (1)

157-166: Consider adding schema migration/preprocessing for backward compatibility.

The cloudProfilesFileSchema requires schemaVersion as a positive integer, but if users have existing cloud profile files without this field (or from a previous format), schema validation will fail. Unlike nexuConfigSchema (lines 105-145) which uses z.preprocess() to normalize missing fields, this schema has no migration path.

If cloud-profiles.json is a new file that didn't exist before this PR, this is fine. However, if there's any possibility of existing files, consider adding preprocessing similar to nexuConfigSchema.

Example preprocessing pattern

export const cloudProfilesFileSchema = z.preprocess((input) => {
  if (typeof input !== "object" || input === null) {
    return input;
  }
  const candidate = input as Record<string, unknown>;
  return {
    schemaVersion: typeof candidate.schemaVersion === "number" ? candidate.schemaVersion : 1,
    profiles: Array.isArray(candidate.profiles) ? candidate.profiles : [],
  };
}, z.object({
  schemaVersion: z.number().int().positive(),
  profiles: z.array(cloudProfileEntrySchema).default([]),
}));

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/controller/src/store/schemas.ts` around lines 157 - 166, The
cloudProfilesFileSchema currently requires schemaVersion and will reject
older/absent fields; add a z.preprocess like nexuConfigSchema to normalize
legacy inputs: in the preprocess handler for cloudProfilesFileSchema detect
non-object or missing schemaVersion/profiles and return an object with
schemaVersion defaulting to 1 and profiles defaulting to [], then validate
against the existing z.object (which uses cloudProfileEntrySchema); this
preserves backward compatibility for existing cloud-profiles.json files while
keeping the same shape for new files.

apps/desktop/src/pages/cloud-profile-page.tsx (2)

14-34: Consider importing types from shared schema.

The CloudStatus type duplicates the shape defined in @nexu/shared. While the renderer may not directly import Zod schemas, you could use z.infer<typeof cloudStatusResponseSchema> if the shared package exports the inferred types, improving type safety and reducing duplication.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/desktop/src/pages/cloud-profile-page.tsx` around lines 14 - 34, Replace
the locally-declared CloudStatus type with the shared inferred type from
`@nexu/shared`: import the exported inferred type (e.g., z.infer<typeof
cloudStatusResponseSchema> or an exported alias) instead of duplicating the
shape; update any references to CloudStatus in this file (e.g., props, state, or
function signatures) to use the imported type name and remove the local type
declaration to keep types consistent and DRY with the shared schema.

---

660-676: Simplify duplicate conditional branches.

Both branches of the ternary render identical JSX. The cloudMessage check isn't affecting the output.

♻️ Proposed simplification

-      {cloudMessage ? (
-        <p className={`runtime-cloud-message is-${statusBannerTone}`}>
-          <span
-            className={`runtime-cloud-message-dot is-${statusBannerTone}`}
-            aria-hidden="true"
-          />
-          <span>{statusBannerMessage}</span>
-        </p>
-      ) : (
-        <p className={`runtime-cloud-message is-${statusBannerTone}`}>
-          <span
-            className={`runtime-cloud-message-dot is-${statusBannerTone}`}
-            aria-hidden="true"
-          />
-          <span>{statusBannerMessage}</span>
-        </p>
-      )}
+      <p className={`runtime-cloud-message is-${statusBannerTone}`}>
+        <span
+          className={`runtime-cloud-message-dot is-${statusBannerTone}`}
+          aria-hidden="true"
+        />
+        <span>{statusBannerMessage}</span>
+      </p>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/desktop/src/pages/cloud-profile-page.tsx` around lines 660 - 676, The
conditional using cloudMessage renders identical JSX in both branches; replace
the ternary with a single unconditional render of the paragraph using the same
classes and values (referencing cloudMessage only if needed elsewhere), e.g.
render the <p> that uses statusBannerTone and statusBannerMessage and the inner
span with class runtime-cloud-message-dot once instead of duplicating it in the
cloudMessage ? ... : ... branches; remove the redundant conditional and keep use
of statusBannerTone/statusBannerMessage to preserve current behavior.

apps/controller/src/routes/desktop-compat-routes.ts (1)

96-103: Consider calling ensureValidDefaultModel() for consistency.

The cloud-profile/connect handler does not call modelProviderService.ensureValidDefaultModel() after the operation, unlike all other mutation handlers (create, update, delete, disconnect, select, import) which do. If connecting a profile can affect the available models, this inconsistency could lead to an invalid default model state.

♻️ Proposed fix for consistency

     async (c) => {
       const body = c.req.valid("json");
       const result = await container.desktopLocalService.connectCloudProfile(
         body.name,
       );
+      await container.modelProviderService.ensureValidDefaultModel();
       const { configPushed } = await container.openclawSyncService.syncAll();
       return c.json({ ...result, configPushed }, 200);
     },

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/controller/src/routes/desktop-compat-routes.ts` around lines 96 - 103,
The cloud-profile/connect route handler currently calls
container.desktopLocalService.connectCloudProfile(...) and then
container.openclawSyncService.syncAll(), but unlike other mutation handlers it
does not call modelProviderService.ensureValidDefaultModel(); update the async
handler to invoke container.modelProviderService.ensureValidDefaultModel() after
the syncAll() (and before returning the JSON response) so the default model
state is validated consistently after connecting a profile.

apps/desktop/src/lib/host-api.ts (1)

97-101: Extract a shared DesktopCloudProfileInput type.

The same payload shape is redeclared three times here. Because this sits on a renderer↔host boundary, duplicating it makes future field/nullability changes drift silently.

♻️ Suggested refactor

+type DesktopCloudProfileInput = {
+  name: string;
+  cloudUrl: string;
+  linkUrl: string;
+};

-export async function createCloudProfile(profile: {
-  name: string;
-  cloudUrl: string;
-  linkUrl: string;
-}) {
+export async function createCloudProfile(profile: DesktopCloudProfileInput) {
   return getHostBridge().invoke("desktop:create-cloud-profile", { profile });
 }

 export async function importCloudProfiles(
-  profiles: Array<{ name: string; cloudUrl: string; linkUrl: string }>,
+  profiles: DesktopCloudProfileInput[],
 ) {
   return getHostBridge().invoke("desktop:import-cloud-profiles", { profiles });
 }

 export async function updateCloudProfile(
   previousName: string,
-  profile: { name: string; cloudUrl: string; linkUrl: string },
+  profile: DesktopCloudProfileInput,
 ) {
   return getHostBridge().invoke("desktop:update-cloud-profile", {
     previousName,
     profile,

Also applies to: 117-125

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/desktop/src/lib/host-api.ts` around lines 97 - 101, Extract a shared
type alias (e.g., DesktopCloudProfileInput) defining { name: string; cloudUrl:
string; linkUrl: string } and replace the inline object literal parameter types
in createCloudProfile and the other functions that redeclare the same shape
(referenced in the diff around createCloudProfile and the block at lines
117-125) to use that alias; update any related import/exports so the
renderer↔host boundary uses the single DesktopCloudProfileInput type to prevent
drift when fields/nullability change.

apps/desktop/shared/host.ts (1)

148-347: Consider extracting a shared CloudProfileStatus type to reduce duplication.

The result types for desktop:create-cloud-profile, desktop:disconnect-cloud-profile, desktop:switch-cloud-profile, etc. all contain an identical nested structure (lines 162-172 repeated ~7 times). Extracting a shared type would reduce maintenance burden.

♻️ Optional: Extract shared type

export type CloudProfileStatus = {
  connected: boolean;
  polling?: boolean;
  userName?: string | null;
  userEmail?: string | null;
  connectedAt?: string | null;
  models?: Array<{
    id: string;
    name: string;
    provider?: string;
  }>;
  cloudUrl: string;
  linkUrl: string | null;
  activeProfileName: string;
  profiles: Array<{
    name: string;
    cloudUrl: string;
    linkUrl: string;
    connected: boolean;
    polling?: boolean;
    userName?: string | null;
    userEmail?: string | null;
    connectedAt?: string | null;
    modelCount: number;
  }>;
};

// Then use in result maps:
"desktop:get-cloud-status": CloudProfileStatus;
"desktop:create-cloud-profile": CloudProfileStatus & { ok: boolean; configPushed: boolean };
// etc.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/desktop/shared/host.ts` around lines 148 - 347, The types for responses
like "desktop:get-cloud-status", "desktop:create-cloud-profile",
"desktop:disconnect-cloud-profile", "desktop:switch-cloud-profile",
"desktop:import-cloud-profiles", "desktop:update-cloud-profile", and
"desktop:delete-cloud-profile" duplicate the same nested structure; extract that
shared shape into a new exported type (e.g., CloudProfileStatus) capturing
connected, polling, userName, userEmail, connectedAt, models, cloudUrl, linkUrl,
activeProfileName, and profiles, then replace the repeated inline definitions
with CloudProfileStatus and compose any extra fields (e.g., ok, configPushed,
browserUrl, error) by intersecting or extending CloudProfileStatus in the
existing result map entries (refer to the existing keys
"desktop:get-cloud-status" and "desktop:create-cloud-profile" to guide where to
swap to CloudProfileStatus).

apps/controller/src/store/nexu-config-store.ts (2)

344-382: Dual-write pattern maintains backward compatibility but increases consistency burden.

writeActiveDesktopCloudState writes identical data to both desktop.cloud and desktop.cloudSessions[activeProfileName]. This supports backward compatibility but creates a consistency responsibility. If either location gets out of sync (e.g., due to a future code path that only updates one), consumers could see inconsistent state.

Consider documenting this pattern with a comment explaining the dual-write rationale and noting that desktop.cloud is the primary read location while cloudSessions provides per-profile persistence.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/controller/src/store/nexu-config-store.ts` around lines 344 - 382, Add a
concise comment in writeActiveDesktopCloudState explaining the intentional
dual-write to desktop.cloud and desktop.cloudSessions[activeProfileName]: state
that this mirrors data for backward compatibility, declare which location
(desktop.cloud) is the primary read location and that cloudSessions provides
per-profile persistence, and note the consistency burden (ensure any future
updates must update both locations) so maintainers know why both are updated and
to keep them in sync.

---

140-156: Consider validating model array elements for defensive parsing.

The function casts cloud.models without validating that array elements conform to the expected shape { id: string; name: string; provider?: string }. If persisted data is malformed (e.g., due to schema migration or file corruption), downstream code may encounter unexpected property accesses.

🛡️ Optional: Add element validation

+function isValidCloudModel(item: unknown): item is { id: string; name: string; provider?: string } {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    typeof (item as Record<string, unknown>).id === "string" &&
+    typeof (item as Record<string, unknown>).name === "string"
+  );
+}
+
 function normalizeDesktopCloudState(
   cloud: Record<string, unknown> | null,
 ): DesktopCloudState {
   return {
     connected: cloud?.connected === true,
     polling: cloud?.polling === true,
     userName: typeof cloud?.userName === "string" ? cloud.userName : null,
     userEmail: typeof cloud?.userEmail === "string" ? cloud.userEmail : null,
     connectedAt:
       typeof cloud?.connectedAt === "string" ? cloud.connectedAt : null,
     linkUrl: typeof cloud?.linkUrl === "string" ? cloud.linkUrl : undefined,
     apiKey: typeof cloud?.apiKey === "string" ? cloud.apiKey : undefined,
-    models: Array.isArray(cloud?.models)
-      ? (cloud.models as Array<{ id: string; name: string; provider?: string }>)
-      : [],
+    models: Array.isArray(cloud?.models)
+      ? cloud.models.filter(isValidCloudModel)
+      : [],
   };
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/controller/src/store/nexu-config-store.ts` around lines 140 - 156, The
normalizeDesktopCloudState function currently casts cloud.models directly, which
can let malformed entries through; update it to defensively validate each
element of cloud.models (in normalizeDesktopCloudState) by checking that each
item is an object with string id and name and optional string provider, then
map/filter the array to a safe Array<{id: string; name: string; provider?:
string}> (or return [] if none valid); do not use a direct cast of cloud.models
— instead iterate, validate types for id/name/provider, and build the normalized
models array before returning it.

apps/controller/openapi.json (1)

1267-1325: ⚠️ Potential issue | 🟡 Minor

Extract the repeated cloud-status shape into a shared schema.

This object graph is copied into cloud-status, cloud-refresh, cloud-profile/connect, and each profile mutation response. The drift is already visible in the selected-profile cloudUrl/linkUrl, which are weaker than the same fields inside profiles[]. Back these endpoints from one shared Zod schema/components ref so the generated spec and SDK stay aligned.

Based on learnings: All request bodies, path params, query params, and responses must have Zod schemas; shared schemas go in packages/shared/src/schemas/, route-local param schemas can stay in the route file

Also applies to: 1448-1506, 1583-1641, 1750-1808, 1926-1984, 2079-2137, 2259-2317, 2412-2470, 2586-2644

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@apps/controller/openapi.json` around lines 1267 - 1325, Extract the repeated
"cloud-status" object into a single shared Zod/OpenAPI component and replace the
duplicated inline definitions used by cloud-status, cloud-refresh,
cloud-profile/connect and the profile mutation responses; create a Zod schema
(e.g., CloudProfileSchema or CloudStatusSchema) under
packages/shared/src/schemas/, ensure it includes name, cloudUrl (format uri),
linkUrl (format uri, nullable where appropriate), connected, polling,
userName/userEmail/connectedAt (nullable) and modelCount (integer >=0), then
update the route schemas and response definitions (the profiles array,
activeProfileName response, and any request/response bodies) to reference this
shared schema so all request bodies, path/query params and responses use the
centralized schema/component and remove the weaker/duplicated inline variants.