@openhands/agent-canvas 1.0.0-alpha.9 → 1.0.0-beta.2

package/dist/utils/mcp-marketplace-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-marketplace-utils.js","names":[],"sources":["../../src/utils/mcp-marketplace-utils.ts"],"sourcesContent":["import { MCPServerConfig } from \"#/types/mcp-server\";\nimport type {\n  IntegrationCatalogEntry as MarketplaceEntry,\n  IntegrationTransport as MarketplaceTemplate,\n} from \"@openhands/extensions/integrations\";\n\nconst tryUrl = (raw: string): URL | null => {\n  try {\n    return new URL(raw);\n  } catch {\n    return null;\n  }\n};\n\n/**\n * Loose URL match that ignores query strings, trailing slashes, and\n * default ports. We want clicking \"Linear\" to flag the entry as\n * installed even if the user pasted the URL with extra trailing slash\n * or a different port-equivalent variant.\n *\n * Defensive against runtime data that doesn't match the static type:\n * if either input is not a string (e.g. parsed from an older settings\n * blob), we fall through the URL parsing path and the safe trim\n * fallback below, never calling `.replace` on undefined.\n */\nexport function urlsMatch(a: unknown, b: unknown): boolean {\n  const aStr = typeof a === \"string\" ? a : \"\";\n  const bStr = typeof b === \"string\" ? b : \"\";\n  if (!aStr || !bStr) return false;\n  const left = tryUrl(aStr);\n  const right = tryUrl(bStr);\n  if (!left || !right) {\n    return aStr.replace(/\\/+$/, \"\") === bStr.replace(/\\/+$/, \"\");\n  }\n  return (\n    left.protocol === right.protocol &&\n    left.host === right.host &&\n    left.pathname.replace(/\\/+$/, \"\") === right.pathname.replace(/\\/+$/, \"\")\n  );\n}\n\n/**\n * Get the default transport template from an integration catalog entry.\n * Integrations may have multiple connection options; we use the default\n * one (or the first if no default is specified). Only MCP-backed options\n * have a `transport` field.\n */\nexport function getDefaultTemplate(\n  entry: MarketplaceEntry,\n): MarketplaceTemplate | undefined {\n  const option =\n    entry.connectionOptions.find(\n      (o) => o.id === entry.defaultConnectionOptionId,\n    ) ?? entry.connectionOptions[0];\n  return option?.transport;\n}\n\n/**\n * Get the stdio (API key-based) transport template from an integration entry.\n * Many integrations have multiple connection options (e.g., OAuth + stdio).\n * Since OAuth isn't implemented in the UI yet, the install modal should use\n * this function to get the stdio-based option that can be configured with\n * API keys/tokens.\n *\n * Falls back to getDefaultTemplate if no stdio option exists.\n */\nexport function getInstallableTemplate(\n  entry: MarketplaceEntry,\n): MarketplaceTemplate | undefined {\n  // First, try to find a stdio option (API key-based, what we can actually install)\n  const stdioOption = entry.connectionOptions.find(\n    (o) => o.transport?.kind === \"stdio\",\n  );\n  if (stdioOption?.transport) return stdioOption.transport;\n\n  // Fall back to the default template (could be shttp/sse with api_key)\n  return getDefaultTemplate(entry);\n}\n\n/**\n * Decide whether a marketplace template is already represented by one\n * of the installed MCP servers. Used to render an \"Installed\" badge on\n * the marketplace tile. Returns the first matching server, or null.\n */\nexport function findInstalledMatch(\n  template: MarketplaceTemplate,\n  servers: MCPServerConfig[],\n): MCPServerConfig | null {\n  if (template.kind === \"shttp\") {\n    const tplUrl = template.url;\n    if (!tplUrl) return null;\n    return (\n      servers.find(\n        (s) => s.type === \"shttp\" && !!s.url && urlsMatch(s.url, tplUrl),\n      ) ?? null\n    );\n  }\n\n  if (template.kind === \"sse\") {\n    const tplUrl = template.url;\n    if (!tplUrl) return null;\n    return (\n      servers.find(\n        (s) => s.type === \"sse\" && !!s.url && urlsMatch(s.url, tplUrl),\n      ) ?? null\n    );\n  }\n\n  // stdio: match on the registered server name.\n  return (\n    servers.find((s) => s.type === \"stdio\" && s.name === template.serverName) ??\n    null\n  );\n}\n\nexport function isMarketplaceEntryAvailable(\n  entry: MarketplaceEntry,\n  backendKind: \"local\" | \"cloud\",\n): boolean {\n  if (!entry.runtimeAvailability || entry.runtimeAvailability === \"all\")\n    return true;\n  return entry.runtimeAvailability === backendKind;\n}\n\nfunction normalize(query: string): string {\n  return query.trim().toLowerCase();\n}\n\n/**\n * Case-insensitive substring match against the catalog entry's\n * user-visible identity (name, description, id, keywords). Empty\n * queries always match.\n */\nexport function getMarketplaceEntriesByPopularity(\n  catalog: MarketplaceEntry[],\n): MarketplaceEntry[] {\n  return catalog\n    .map((entry, index) => ({ entry, index }))\n    .sort((a, b) => {\n      const byPopularity =\n        (b.entry.popularityRank ?? 0) - (a.entry.popularityRank ?? 0);\n      return byPopularity || a.index - b.index;\n    })\n    .map(({ entry }) => entry);\n}\n\nexport function getMarketplaceEntryById(\n  id: string,\n  catalog: MarketplaceEntry[],\n): MarketplaceEntry | undefined {\n  return catalog.find((entry) => entry.id === id);\n}\n\nexport function marketplaceEntryMatchesQuery(\n  entry: MarketplaceEntry,\n  rawQuery: string,\n): boolean {\n  const q = normalize(rawQuery);\n  if (!q) return true;\n  const haystack = [\n    entry.name,\n    entry.description,\n    entry.id,\n    ...(entry.keywords ?? []),\n  ]\n    .join(\" \")\n    .toLowerCase();\n  return haystack.includes(q);\n}\n\n/**\n * Search match for an installed (already-configured) server. We\n * search the server's own identifying fields and — if it's a catalog\n * entry — its catalog name/keywords too, so typing \"Slack\" matches\n * the installed Slack tile even though the persisted server is just\n * `{ type: \"stdio\", name: \"slack\", ... }`.\n */\nexport function installedServerMatchesQuery(\n  server: MCPServerConfig,\n  catalogEntry: MarketplaceEntry | undefined,\n  rawQuery: string,\n): boolean {\n  const q = normalize(rawQuery);\n  if (!q) return true;\n  const haystack = [\n    server.type,\n    \"name\" in server ? server.name : undefined,\n    \"command\" in server ? server.command : undefined,\n    \"args\" in server ? server.args?.join(\" \") : undefined,\n    \"url\" in server ? server.url : undefined,\n    catalogEntry?.name,\n    catalogEntry?.description,\n    catalogEntry?.id,\n    ...(catalogEntry?.keywords ?? []),\n  ]\n    .filter(Boolean)\n    .join(\" \")\n    .toLowerCase();\n  return haystack.includes(q);\n}\n\n/**\n * Look up the catalog entry that best matches an installed server.\n * Mirrors the lookup used in `installed-server-card.tsx` for\n * rendering the friendly icon.\n *\n * Since an entry may have multiple connection options (e.g., OAuth + stdio),\n * we check ALL templates in the entry's connectionOptions, not just the default.\n */\nexport function findCatalogEntryForServer(\n  server: MCPServerConfig,\n  catalog: MarketplaceEntry[],\n): MarketplaceEntry | undefined {\n  return catalog.find((entry) => {\n    // Check all connection options, not just the default\n    for (const option of entry.connectionOptions) {\n      const tpl = option.transport;\n      if (!tpl) continue;\n      if (tpl.kind === \"stdio\") {\n        if (server.type === \"stdio\" && server.name === tpl.serverName)\n          return true;\n      }\n      // Reuse the same loose URL match as `findInstalledMatch` so a\n      // server whose URL was normalized by the backend (trailing slash\n      // stripped, query string dropped, etc.) still gets paired with\n      // its catalog tile — otherwise the installed-servers list would\n      // render the generic icon while the marketplace shows the\n      // entry as installed, which is confusing.\n      if (tpl.kind === \"shttp\") {\n        if (server.type === \"shttp\" && urlsMatch(server.url, tpl.url))\n          return true;\n      }\n      if (tpl.kind === \"sse\") {\n        if (server.type === \"sse\" && urlsMatch(server.url, tpl.url))\n          return true;\n      }\n    }\n    return false;\n  });\n}\n"],"mappings":";AAMA,IAAM,KAAU,MAA4B;AAC1C,KAAI;AACF,SAAO,IAAI,IAAI,EAAI;SACb;AACN,SAAO;;;AAeX,SAAgB,EAAU,GAAY,GAAqB;CACzD,IAAM,IAAO,OAAO,KAAM,WAAW,IAAI,IACnC,IAAO,OAAO,KAAM,WAAW,IAAI;AACzC,KAAI,CAAC,KAAQ,CAAC,EAAM,QAAO;CAC3B,IAAM,IAAO,EAAO,EAAK,EACnB,IAAQ,EAAO,EAAK;AAI1B,QAHI,CAAC,KAAQ,CAAC,IACL,EAAK,QAAQ,QAAQ,GAAG,KAAK,EAAK,QAAQ,QAAQ,GAAG,GAG5D,EAAK,aAAa,EAAM,YACxB,EAAK,SAAS,EAAM,QACpB,EAAK,SAAS,QAAQ,QAAQ,GAAG,KAAK,EAAM,SAAS,QAAQ,QAAQ,GAAG;;AAU5E,SAAgB,EACd,GACiC;AAKjC,SAHE,EAAM,kBAAkB,MACrB,MAAM,EAAE,OAAO,EAAM,0BACvB,IAAI,EAAM,kBAAkB,KAChB;;AAYjB,SAAgB,EACd,GACiC;CAEjC,IAAM,IAAc,EAAM,kBAAkB,MACzC,MAAM,EAAE,WAAW,SAAS,QAC9B;AAID,QAHI,GAAa,YAAkB,EAAY,YAGxC,EAAmB,EAAM;;AAuClC,SAAgB,EACd,GACA,GACS;AAGT,QAFI,CAAC,EAAM,uBAAuB,EAAM,wBAAwB,QACvD,KACF,EAAM,wBAAwB;;AAGvC,SAAS,EAAU,GAAuB;AACxC,QAAO,EAAM,MAAM,CAAC,aAAa;;AAQnC,SAAgB,EACd,GACoB;AACpB,QAAO,EACJ,KAAK,GAAO,OAAW;EAAE;EAAO;EAAO,EAAE,CACzC,MAAM,GAAG,OAEL,EAAE,MAAM,kBAAkB,MAAM,EAAE,MAAM,kBAAkB,MACtC,EAAE,QAAQ,EAAE,MACnC,CACD,KAAK,EAAE,eAAY,EAAM;;AAU9B,SAAgB,EACd,GACA,GACS;CACT,IAAM,IAAI,EAAU,EAAS;AAU7B,QATK,IACY;EACf,EAAM;EACN,EAAM;EACN,EAAM;EACN,GAAI,EAAM,YAAY,EAAE;EACzB,CACE,KAAK,IAAI,CACT,aACI,CAAS,SAAS,EAAE,GATZ;;AAmBjB,SAAgB,EACd,GACA,GACA,GACS;CACT,IAAM,IAAI,EAAU,EAAS;AAgB7B,QAfK,IACY;EACf,EAAO;EACP,UAAU,IAAS,EAAO,OAAO,KAAA;EACjC,aAAa,IAAS,EAAO,UAAU,KAAA;EACvC,UAAU,IAAS,EAAO,MAAM,KAAK,IAAI,GAAG,KAAA;EAC5C,SAAS,IAAS,EAAO,MAAM,KAAA;EAC/B,GAAc;EACd,GAAc;EACd,GAAc;EACd,GAAI,GAAc,YAAY,EAAE;EACjC,CACE,OAAO,QAAQ,CACf,KAAK,IAAI,CACT,aACI,CAAS,SAAS,EAAE,GAfZ;;AA0BjB,SAAgB,EACd,GACA,GAC8B;AAC9B,QAAO,EAAQ,MAAM,MAAU;AAE7B,OAAK,IAAM,KAAU,EAAM,mBAAmB;GAC5C,IAAM,IAAM,EAAO;AACd,aACD,EAAI,SAAS,WACX,EAAO,SAAS,WAAW,EAAO,SAAS,EAAI,cASjD,EAAI,SAAS,WACX,EAAO,SAAS,WAAW,EAAU,EAAO,KAAK,EAAI,IAAI,IAG3D,EAAI,SAAS,SACX,EAAO,SAAS,SAAS,EAAU,EAAO,KAAK,EAAI,IAAI,EACzD,QAAO;;AAGb,SAAO;GACP"}
+{"version":3,"file":"mcp-marketplace-utils.js","names":[],"sources":["../../src/utils/mcp-marketplace-utils.ts"],"sourcesContent":["import { MCPServerConfig } from \"#/types/mcp-server\";\nimport type {\n  IntegrationCatalogEntry as MarketplaceEntry,\n  IntegrationConnectionOption,\n  IntegrationTransport,\n} from \"@openhands/extensions/integrations\";\n\nexport type { MarketplaceEntry };\n\nexport type McpMarketplaceConnectionOption = IntegrationConnectionOption & {\n  provider: \"mcp\";\n  transport: IntegrationTransport;\n};\n\nexport function getMcpConnectionOptions(\n  entry: MarketplaceEntry,\n): McpMarketplaceConnectionOption[] {\n  return entry.connectionOptions.filter(\n    (option): option is McpMarketplaceConnectionOption =>\n      option.provider === \"mcp\" && !!option.transport,\n  );\n}\n\nexport function getDefaultMcpConnectionOption(\n  entry: MarketplaceEntry,\n): McpMarketplaceConnectionOption | undefined {\n  const options = getMcpConnectionOptions(entry);\n  return (\n    options.find((option) => option.id === entry.defaultConnectionOptionId) ??\n    options[0]\n  );\n}\n\nfunction isLocallyInstallableMcpOption(\n  option: McpMarketplaceConnectionOption,\n): boolean {\n  // The local install modal writes static MCP server config. OAuth options\n  // describe hosted redirect flows, so prefer an API/stdio fallback when one\n  // exists and leave OAuth as the default connection for hosted integrations.\n  return option.auth.strategy !== \"oauth2\";\n}\n\nexport function getInstallableMcpConnectionOption(\n  entry: MarketplaceEntry,\n): McpMarketplaceConnectionOption | undefined {\n  const options = getMcpConnectionOptions(entry);\n  const defaultOption = options.find(\n    (option) => option.id === entry.defaultConnectionOptionId,\n  );\n  if (defaultOption && isLocallyInstallableMcpOption(defaultOption)) {\n    return defaultOption;\n  }\n  return options.find(isLocallyInstallableMcpOption);\n}\n\nexport function getDefaultMcpTransport(\n  entry: MarketplaceEntry,\n): IntegrationTransport | undefined {\n  return getDefaultMcpConnectionOption(entry)?.transport;\n}\n\nexport function getMcpMarketplaceCatalog(\n  catalog: MarketplaceEntry[],\n): MarketplaceEntry[] {\n  return catalog.filter((entry) => !!getDefaultMcpConnectionOption(entry));\n}\n\nconst tryUrl = (raw: string): URL | null => {\n  try {\n    return new URL(raw);\n  } catch {\n    return null;\n  }\n};\n\n/**\n * Loose URL match that ignores query strings, trailing slashes, and\n * default ports. We want clicking \"Linear\" to flag the entry as\n * installed even if the user pasted the URL with extra trailing slash\n * or a different port-equivalent variant.\n *\n * Defensive against runtime data that doesn't match the static type:\n * if either input is not a string (e.g. parsed from an older settings\n * blob), we fall through the URL parsing path and the safe trim\n * fallback below, never calling `.replace` on undefined.\n */\nexport function urlsMatch(a: unknown, b: unknown): boolean {\n  const aStr = typeof a === \"string\" ? a : \"\";\n  const bStr = typeof b === \"string\" ? b : \"\";\n  if (!aStr || !bStr) return false;\n  const left = tryUrl(aStr);\n  const right = tryUrl(bStr);\n  if (!left || !right) {\n    return aStr.replace(/\\/+$/, \"\") === bStr.replace(/\\/+$/, \"\");\n  }\n  return (\n    left.protocol === right.protocol &&\n    left.host === right.host &&\n    left.pathname.replace(/\\/+$/, \"\") === right.pathname.replace(/\\/+$/, \"\")\n  );\n}\n\n/**\n * Decide whether a marketplace template is already represented by one\n * of the installed MCP servers. Used to render an \"Installed\" badge on\n * the marketplace tile. Returns the first matching server, or null.\n */\nexport function findInstalledMatch(\n  transport: IntegrationTransport,\n  servers: MCPServerConfig[],\n): MCPServerConfig | null {\n  return (\n    servers.find((server) => transportMatchesServer(transport, server)) ?? null\n  );\n}\n\nexport function findInstalledEntryMatch(\n  entry: MarketplaceEntry,\n  servers: MCPServerConfig[],\n): MCPServerConfig | null {\n  for (const option of getMcpConnectionOptions(entry)) {\n    const match = findInstalledMatch(option.transport, servers);\n    if (match) return match;\n  }\n  return null;\n}\n\nfunction transportMatchesServer(\n  transport: IntegrationTransport,\n  server: MCPServerConfig,\n): boolean {\n  if (transport.kind === \"shttp\") {\n    const tplUrl = transport.url;\n    return (\n      server.type === \"shttp\" && !!server.url && urlsMatch(server.url, tplUrl)\n    );\n  }\n\n  if (transport.kind === \"sse\") {\n    const tplUrl = transport.url;\n    return (\n      server.type === \"sse\" && !!server.url && urlsMatch(server.url, tplUrl)\n    );\n  }\n\n  // stdio: match on the registered server name.\n  return server.type === \"stdio\" && server.name === transport.serverName;\n}\n\nexport function isMarketplaceEntryAvailable(\n  entry: MarketplaceEntry,\n  backendKind: \"local\" | \"cloud\",\n): boolean {\n  if (!entry.runtimeAvailability || entry.runtimeAvailability === \"all\")\n    return true;\n  return entry.runtimeAvailability === backendKind;\n}\n\nfunction normalize(query: string): string {\n  return query.trim().toLowerCase();\n}\n\n/**\n * Case-insensitive substring match against the catalog entry's\n * user-visible identity (name, description, id, keywords). Empty\n * queries always match.\n */\nexport function getMarketplaceEntriesByPopularity(\n  catalog: MarketplaceEntry[],\n): MarketplaceEntry[] {\n  return catalog\n    .map((entry, index) => ({ entry, index }))\n    .sort((a, b) => {\n      const byPopularity =\n        (b.entry.popularityRank ?? 0) - (a.entry.popularityRank ?? 0);\n      return byPopularity || a.index - b.index;\n    })\n    .map(({ entry }) => entry);\n}\n\nexport function getMarketplaceEntryById(\n  id: string,\n  catalog: MarketplaceEntry[],\n): MarketplaceEntry | undefined {\n  return catalog.find((entry) => entry.id === id);\n}\n\nexport function marketplaceEntryMatchesQuery(\n  entry: MarketplaceEntry,\n  rawQuery: string,\n): boolean {\n  const q = normalize(rawQuery);\n  if (!q) return true;\n  const haystack = [\n    entry.name,\n    entry.description,\n    entry.id,\n    ...(entry.keywords ?? []),\n  ]\n    .join(\" \")\n    .toLowerCase();\n  return haystack.includes(q);\n}\n\n/**\n * Search match for an installed (already-configured) server. We\n * search the server's own identifying fields and — if it's a catalog\n * entry — its catalog name/keywords too, so typing \"Slack\" matches\n * the installed Slack tile even though the persisted server is just\n * `{ type: \"stdio\", name: \"slack\", ... }`.\n */\nexport function installedServerMatchesQuery(\n  server: MCPServerConfig,\n  catalogEntry: MarketplaceEntry | undefined,\n  rawQuery: string,\n): boolean {\n  const q = normalize(rawQuery);\n  if (!q) return true;\n  const haystack = [\n    server.type,\n    \"name\" in server ? server.name : undefined,\n    \"command\" in server ? server.command : undefined,\n    \"args\" in server ? server.args?.join(\" \") : undefined,\n    \"url\" in server ? server.url : undefined,\n    catalogEntry?.name,\n    catalogEntry?.description,\n    catalogEntry?.id,\n    ...(catalogEntry?.keywords ?? []),\n  ]\n    .filter(Boolean)\n    .join(\" \")\n    .toLowerCase();\n  return haystack.includes(q);\n}\n\n/**\n * Look up the catalog entry that best matches an installed server.\n * Mirrors the lookup used in `installed-server-card.tsx` for\n * rendering the friendly icon.\n */\nexport function findCatalogEntryForServer(\n  server: MCPServerConfig,\n  catalog: MarketplaceEntry[],\n): MarketplaceEntry | undefined {\n  return catalog.find((entry) => {\n    // Check every MCP option rather than only the default. Some unified\n    // integration entries default to OAuth-hosted MCP while still exposing\n    // an API/stdio option; existing installed servers should match either.\n    return getMcpConnectionOptions(entry).some((option) =>\n      transportMatchesServer(option.transport, server),\n    );\n  });\n}\n"],"mappings":"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"}

package/dist/utils/sdk-settings-schema.cjs

@@ -1,2 +1,2 @@
-require(`../_virtual/_rolldown/runtime.cjs`);const e=require(`./sdk-settings-field-metadata.cjs`);var t=new Set([`llm.model`,`llm.api_key`,`llm.base_url`]),n={basic:new Set([`critical`]),advanced:new Set([`critical`,`major`]),all:new Set([`critical`,`major`,`minor`])};function r(e){return!!e&&Array.isArray(e.sections)}function i(e){return r(e)?e.sections.flatMap(e=>e.fields):[]}function a(e,t){if(!e)return;let n=t.split(`.`),r=e;for(let e of n){if(typeof r!=`object`||!r)return;r=r[e]}return r}function o(e,t,n){let r=t.split(`.`),i=e;for(let e=0;e<r.length-1;e+=1){let t=r[e];(i[t]==null||typeof i[t]!=`object`||Array.isArray(i[t]))&&(i[t]={}),i=i[t]}i[r[r.length-1]]=n}function s(e,t,n=`agent_settings`){return a(e[n],t)??null}function c(e,t){return s(e,t,`agent_settings`)}function l(e){return e.choices.length>0}function u(e){return e.prominence===`critical`}function d(e){return e.prominence===`minor`}function f(e,t){let n=t??e.default;return l(e)?n==null?``:String(n):e.value_type===`boolean`?!!(n??!1):n==null?``:e.value_type===`array`||e.value_type===`object`?JSON.stringify(n,null,2):String(n)}function p(e,t){if(t===void 0)return null;if(e.value_type===`boolean`){if(typeof t==`string`){if(t===`true`)return!0;if(t===`false`)return!1}return t===null?null:!!t}if(e.value_type===`integer`||e.value_type===`number`){if(t===``||t===null)return null;let e=typeof t==`number`?t:Number(String(t));return Number.isNaN(e)?null:e}if(e.value_type===`array`||e.value_type===`object`){if(t===null||e.value_type===`object`&&typeof t==`object`&&!Array.isArray(t)&&Object.keys(t).length===0)return null;if(typeof t==`string`){let n=t.trim();if(!n)return null;try{let t=JSON.parse(n);return e.value_type===`object`&&typeof t==`object`&&t&&!Array.isArray(t)&&Object.keys(t).length===0?null:JSON.stringify(t)}catch{return n}}return JSON.stringify(t)}return t===null?null:String(t)}function m(e,t,n=`agent_settings`){let r=t??(n===`conversation_settings`?e.conversation_settings_schema:e.agent_settings_schema);return r?Object.fromEntries(i(r).map(t=>[t.key,f(t,s(e,t.key,n))])):{}}function h(e,t,n=`agent_settings`){let r=t??(n===`conversation_settings`?e.conversation_settings_schema:e.agent_settings_schema);if(!r)return`basic`;let a=!1,o=!1;for(let t of i(r))u(t)||p(t,s(e,t.key,n)??t.default??null)!==p(t,t.default??null)&&(d(t)?a=!0:o=!0);return a?`all`:o?`advanced`:`basic`}function g(e,t){return e.depends_on.every(e=>t[e]===!0)}function _(e){if(typeof e==`boolean`)return e;let t=e.trim().toLowerCase();if(!t)return null;if(t===`true`)return!0;if(t===`false`)return!1;throw Error(`Expected a boolean value, received: ${e}`)}function v(t,n){if(t.value_type===`boolean`)return _(n);if(t.value_type===`integer`||t.value_type===`number`){let r=String(n).trim();if(!r)return null;let i=Number(r);if(Number.isNaN(i))throw Error(`Expected a numeric value, received: ${r}`);if(t.value_type===`integer`&&!Number.isInteger(i))throw Error(`Expected an integer value, received: ${r}`);let a=e.getSettingsFieldConstraints(t.key);if(a?.min!=null&&i<a.min)throw Error(`${t.label} must be at least ${a.min}`);if(a?.max!=null&&i>a.max)throw Error(`${t.label} must be at most ${a.max}`);return i}if(t.value_type===`array`||t.value_type===`object`){let e=String(n).trim();if(!e)return null;let r;try{r=JSON.parse(e)}catch{throw Error(`Invalid JSON for ${t.label}`)}if(t.value_type===`array`){if(!Array.isArray(r))throw Error(`${t.label} must be a JSON array`);return r}if(r===null||Array.isArray(r)||typeof r!=`object`)throw Error(`${t.label} must be a JSON object`);return r}let r=String(n);return r===``&&!t.secret?null:r}function y(e,t,n){let r={};for(let a of i(e))n[a.key]&&o(r,a.key,v(a,t[a.key]));return r}function b(e,t){return n[t].has(e.prominence)}function x(e,t,n,r){let a=y(e,t,n);for(let t of i(e))b(t,r)||o(a,t.key,t.default??null);return a}function S(e,n,i,a=t){return r(e)?e.sections.map(e=>({...e,fields:e.fields.filter(e=>!a.has(e.key)&&b(e,i)&&g(e,n))})).filter(e=>e.fields.length>0):[]}function C(e){return e?i(e).some(e=>e.prominence===`major`):!1}function w(e){return e?i(e).some(e=>e.prominence===`minor`):!1}exports.buildInitialSettingsFormValues=m,exports.buildSdkSettingsPayloadForView=x,exports.getAgentSettingValue=c,exports.getVisibleSettingsSections=S,exports.hasAdvancedSettings=C,exports.hasMinorSettings=w,exports.inferInitialView=h,exports.isValidSettingsSchema=r;
+require(`../_virtual/_rolldown/runtime.cjs`);const e=require(`./sdk-settings-field-metadata.cjs`);var t=new Set([`llm.model`,`llm.api_key`,`llm.base_url`]),n={basic:new Set([`critical`]),advanced:new Set([`critical`,`major`]),all:new Set([`critical`,`major`,`minor`])};function r(e){return!!e&&Array.isArray(e.sections)}function i(e){return r(e)?e.sections.flatMap(e=>e.fields):[]}function a(e,t){if(!e)return;let n=t.split(`.`),r=e;for(let e of n){if(typeof r!=`object`||!r)return;r=r[e]}return r}function o(e,t,n){let r=t.split(`.`),i=e;for(let e=0;e<r.length-1;e+=1){let t=r[e];(i[t]==null||typeof i[t]!=`object`||Array.isArray(i[t]))&&(i[t]={}),i=i[t]}i[r[r.length-1]]=n}function s(e,t,n=`agent_settings`){return a(e[n],t)??null}function c(e,t){return s(e,t,`agent_settings`)}function l(e){return e.choices.length>0}function u(e){return e.prominence===`critical`}function d(e){return e.prominence===`minor`}function f(e,t){let n=t??e.default;return l(e)?n==null?``:String(n):e.value_type===`boolean`?!!(n??!1):n==null?``:e.value_type===`array`||e.value_type===`object`?JSON.stringify(n,null,2):String(n)}function p(e,t){if(t===void 0)return null;if(e.value_type===`boolean`){if(typeof t==`string`){if(t===`true`)return!0;if(t===`false`)return!1}return t===null?null:!!t}if(e.value_type===`integer`||e.value_type===`number`){if(t===``||t===null)return null;let e=typeof t==`number`?t:Number(String(t));return Number.isNaN(e)?null:e}if(e.value_type===`array`||e.value_type===`object`){if(t===null||e.value_type===`object`&&typeof t==`object`&&!Array.isArray(t)&&Object.keys(t).length===0)return null;if(typeof t==`string`){let n=t.trim();if(!n)return null;try{let t=JSON.parse(n);return e.value_type===`object`&&typeof t==`object`&&t&&!Array.isArray(t)&&Object.keys(t).length===0?null:JSON.stringify(t)}catch{return n}}return JSON.stringify(t)}return t===null?null:String(t)}function m(e,t,n=`agent_settings`){let r=t??(n===`conversation_settings`?e.conversation_settings_schema:e.agent_settings_schema);return r?Object.fromEntries(i(r).map(t=>[t.key,f(t,s(e,t.key,n))])):{}}function h(e,t,n=`agent_settings`){let r=t??(n===`conversation_settings`?e.conversation_settings_schema:e.agent_settings_schema);if(!r)return`basic`;let a=!1,o=!1;for(let t of i(r))u(t)||p(t,s(e,t.key,n)??t.default??null)!==p(t,t.default??null)&&(d(t)?a=!0:o=!0);return a?`all`:o?`advanced`:`basic`}function g(e,t){return e.depends_on.every(e=>t[e]===!0)}function _(e){if(typeof e==`boolean`)return e;let t=e.trim().toLowerCase();if(!t)return null;if(t===`true`)return!0;if(t===`false`)return!1;throw Error(`Expected a boolean value, received: ${e}`)}function v(t,n){if(t.value_type===`boolean`)return _(n);if(t.value_type===`integer`||t.value_type===`number`){let r=String(n).trim();if(!r)return null;let i=Number(r);if(Number.isNaN(i))throw Error(`Expected a numeric value, received: ${r}`);if(t.value_type===`integer`&&!Number.isInteger(i))throw Error(`Expected an integer value, received: ${r}`);let a=e.getSettingsFieldConstraints(t.key);if(a?.min!=null&&i<a.min)throw Error(`${t.label} must be at least ${a.min}`);if(a?.max!=null&&i>a.max)throw Error(`${t.label} must be at most ${a.max}`);return i}if(t.value_type===`array`||t.value_type===`object`){let e=String(n).trim();if(!e)return null;let r;try{r=JSON.parse(e)}catch{throw Error(`Invalid JSON for ${t.label}`)}if(t.value_type===`array`){if(!Array.isArray(r))throw Error(`${t.label} must be a JSON array`);return r}if(r===null||Array.isArray(r)||typeof r!=`object`)throw Error(`${t.label} must be a JSON object`);return r}let r=String(n);return r===``&&!t.secret?null:r}function y(e,t,n){let r={};for(let a of i(e))n[a.key]&&o(r,a.key,v(a,t[a.key]));return r}function b(e,t){return n[t].has(e.prominence)}function x(e,t,n,r){let a=y(e,t,n);for(let t of i(e))b(t,r)||o(a,t.key,t.default??null);return a}function S(e,n,i,a=t){return r(e)?e.sections.map(e=>({...e,fields:e.fields.filter(e=>!a.has(e.key)&&b(e,i)&&g(e,n))})).filter(e=>e.fields.length>0):[]}function C(e){return e?i(e).some(e=>e.prominence===`major`):!1}function w(e){return e?i(e).some(e=>e.prominence===`minor`):!1}exports.buildInitialSettingsFormValues=m,exports.buildSdkSettingsPayload=y,exports.buildSdkSettingsPayloadForView=x,exports.getAgentSettingValue=c,exports.getVisibleSettingsSections=S,exports.hasAdvancedSettings=C,exports.hasMinorSettings=w,exports.inferInitialView=h,exports.isValidSettingsSchema=r;
 //# sourceMappingURL=sdk-settings-schema.cjs.map

package/dist/utils/sdk-settings-schema.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-settings-schema.cjs","names":[],"sources":["../../src/utils/sdk-settings-schema.ts"],"sourcesContent":["import {\n  SettingProminence,\n  Settings,\n  SettingsFieldSchema,\n  SettingsSchema,\n  SettingsSectionSchema,\n  SettingsValue,\n} from \"#/types/settings\";\nimport { getSettingsFieldConstraints } from \"#/utils/sdk-settings-field-metadata\";\n\nexport type SettingsFormValues = Record<string, string | boolean>;\nexport type SettingsDirtyState = Record<string, boolean>;\nexport type SdkSettingsPayload = Record<string, SettingsValue>;\nexport type SettingsValueSource = \"agent_settings\" | \"conversation_settings\";\n\nexport type SettingsView = \"basic\" | \"advanced\" | \"all\";\n\n/** Fields that are rendered by purpose-built components instead of the\n *  generic `SchemaField` renderer. */\nexport const SPECIALLY_RENDERED_KEYS = new Set([\n  \"llm.model\",\n  \"llm.api_key\",\n  \"llm.base_url\",\n]);\n\n/** Prominence tiers visible at each view level. */\nconst VIEW_PROMINENCES: Record<SettingsView, Set<SettingProminence>> = {\n  basic: new Set<SettingProminence>([\"critical\"]),\n  advanced: new Set<SettingProminence>([\"critical\", \"major\"]),\n  all: new Set<SettingProminence>([\"critical\", \"major\", \"minor\"]),\n};\n\n/**\n * True when `schema` looks like a usable `SettingsSchema` — i.e. an\n * object with an array `sections` field. Guards every helper in this\n * module against malformed/empty schema responses (e.g. when the\n * frontend ends up pointing at a host that does not actually serve\n * `/api/settings/agent-schema`, such as an unconfigured Vercel preview\n * origin that returns the React Router SPA shell for arbitrary\n * `/api/*` paths). Without this check, `schema.sections.filter(...)`\n * inside `SdkSectionPage` blows up with\n * `Cannot read properties of undefined (reading 'filter')` and React\n * Router escalates to a full-screen error page.\n */\nexport function isValidSettingsSchema(\n  schema: SettingsSchema | null | undefined,\n): schema is SettingsSchema {\n  return !!schema && Array.isArray((schema as SettingsSchema).sections);\n}\n\nfunction getSchemaFields(schema: SettingsSchema): SettingsFieldSchema[] {\n  if (!isValidSettingsSchema(schema)) return [];\n  return schema.sections.flatMap((section) => section.fields);\n}\n\n/** Traverse a nested object using a dotted key path (e.g. \"llm.model\"). */\nfunction lookupDotted(\n  obj: Record<string, unknown> | null | undefined,\n  key: string,\n): unknown {\n  if (!obj) return undefined;\n  const parts = key.split(\".\");\n  let current: unknown = obj;\n  for (const part of parts) {\n    if (current == null || typeof current !== \"object\") return undefined;\n    current = (current as Record<string, unknown>)[part];\n  }\n  return current;\n}\n\n/** Set a value in a nested object at a dotted key path (e.g. \"llm.model\"). */\nfunction setDotted(\n  obj: Record<string, unknown>,\n  key: string,\n  value: unknown,\n): void {\n  const parts = key.split(\".\");\n  let current: Record<string, unknown> = obj;\n  for (let i = 0; i < parts.length - 1; i += 1) {\n    const part = parts[i];\n    if (\n      current[part] == null ||\n      typeof current[part] !== \"object\" ||\n      Array.isArray(current[part])\n    ) {\n      current[part] = {};\n    }\n    current = current[part] as Record<string, unknown>;\n  }\n  current[parts[parts.length - 1]] = value;\n}\n\nexport function getSettingValue(\n  settings: Settings,\n  key: string,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsValue {\n  return (lookupDotted(settings[source] as Record<string, unknown>, key) ??\n    null) as SettingsValue;\n}\n\nexport function getAgentSettingValue(\n  settings: Settings,\n  key: string,\n): SettingsValue {\n  return getSettingValue(settings, key, \"agent_settings\");\n}\n\nexport function getConversationSettingValue(\n  settings: Settings,\n  key: string,\n): SettingsValue {\n  return getSettingValue(settings, key, \"conversation_settings\");\n}\n\nfunction isChoiceField(field: SettingsFieldSchema): boolean {\n  return field.choices.length > 0;\n}\n\nfunction isCriticalField(field: SettingsFieldSchema): boolean {\n  return field.prominence === \"critical\";\n}\n\nfunction isMinorField(field: SettingsFieldSchema): boolean {\n  return field.prominence === \"minor\";\n}\n\nfunction normalizeFieldValue(\n  field: SettingsFieldSchema,\n  rawValue: unknown,\n): string | boolean {\n  const resolvedValue = rawValue ?? field.default;\n\n  if (isChoiceField(field)) {\n    return resolvedValue === null || resolvedValue === undefined\n      ? \"\"\n      : String(resolvedValue);\n  }\n\n  if (field.value_type === \"boolean\") {\n    return Boolean(resolvedValue ?? false);\n  }\n\n  if (resolvedValue === null || resolvedValue === undefined) {\n    return \"\";\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    return JSON.stringify(resolvedValue, null, 2);\n  }\n\n  return String(resolvedValue);\n}\n\nfunction normalizeComparableValue(\n  field: SettingsFieldSchema,\n  rawValue: unknown,\n): boolean | number | string | null {\n  if (rawValue === undefined) {\n    return null;\n  }\n\n  if (field.value_type === \"boolean\") {\n    if (typeof rawValue === \"string\") {\n      if (rawValue === \"true\") {\n        return true;\n      }\n      if (rawValue === \"false\") {\n        return false;\n      }\n    }\n    if (rawValue === null) {\n      return null;\n    }\n    return Boolean(rawValue);\n  }\n\n  if (field.value_type === \"integer\" || field.value_type === \"number\") {\n    if (rawValue === \"\" || rawValue === null) {\n      return null;\n    }\n\n    const parsedValue =\n      typeof rawValue === \"number\" ? rawValue : Number(String(rawValue));\n    return Number.isNaN(parsedValue) ? null : parsedValue;\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    if (rawValue === null) {\n      return null;\n    }\n\n    // Treat empty objects as null so that serializer artifacts\n    // (e.g. mcp_config: {} vs schema default null) don't trigger\n    // a spurious view escalation in inferInitialView.\n    if (\n      field.value_type === \"object\" &&\n      typeof rawValue === \"object\" &&\n      !Array.isArray(rawValue) &&\n      Object.keys(rawValue as Record<string, unknown>).length === 0\n    ) {\n      return null;\n    }\n\n    if (typeof rawValue === \"string\") {\n      const trimmedValue = rawValue.trim();\n      if (!trimmedValue) {\n        return null;\n      }\n      try {\n        const parsed: unknown = JSON.parse(trimmedValue);\n        // Also normalise stringified empty objects\n        if (\n          field.value_type === \"object\" &&\n          parsed !== null &&\n          typeof parsed === \"object\" &&\n          !Array.isArray(parsed) &&\n          Object.keys(parsed as Record<string, unknown>).length === 0\n        ) {\n          return null;\n        }\n        return JSON.stringify(parsed);\n      } catch {\n        return trimmedValue;\n      }\n    }\n\n    return JSON.stringify(rawValue);\n  }\n\n  if (rawValue === null) {\n    return null;\n  }\n\n  return String(rawValue);\n}\n\nexport function buildInitialSettingsFormValues(\n  settings: Settings,\n  schemaOverride?: SettingsSchema | null,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsFormValues {\n  const schema =\n    schemaOverride ??\n    (source === \"conversation_settings\"\n      ? settings.conversation_settings_schema\n      : settings.agent_settings_schema);\n  if (!schema) {\n    return {};\n  }\n\n  return Object.fromEntries(\n    getSchemaFields(schema).map((field) => [\n      field.key,\n      normalizeFieldValue(field, getSettingValue(settings, field.key, source)),\n    ]),\n  );\n}\n\nexport function inferInitialView(\n  settings: Settings,\n  schemaOverride?: SettingsSchema | null,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsView {\n  const schema =\n    schemaOverride ??\n    (source === \"conversation_settings\"\n      ? settings.conversation_settings_schema\n      : settings.agent_settings_schema);\n  if (!schema) {\n    return \"basic\";\n  }\n\n  let hasMinorOverride = false;\n  let hasMajorOverride = false;\n\n  for (const field of getSchemaFields(schema)) {\n    if (!isCriticalField(field)) {\n      const currentValue = getSettingValue(settings, field.key, source);\n      const isDifferent =\n        normalizeComparableValue(\n          field,\n          currentValue ?? field.default ?? null,\n        ) !== normalizeComparableValue(field, field.default ?? null);\n\n      if (isDifferent) {\n        if (isMinorField(field)) {\n          hasMinorOverride = true;\n        } else {\n          hasMajorOverride = true;\n        }\n      }\n    }\n  }\n\n  if (hasMinorOverride) return \"all\";\n  if (hasMajorOverride) return \"advanced\";\n  return \"basic\";\n}\n\n/** Determine which view tier to default to based on whether the user has\n *  overridden any non-critical settings. */\nexport function hasAdvancedSettingsOverrides(settings: Settings): boolean {\n  return inferInitialView(settings) !== \"basic\";\n}\n\nexport function isSettingsFieldVisible(\n  field: SettingsFieldSchema,\n  values: SettingsFormValues,\n): boolean {\n  return field.depends_on.every((dependency) => values[dependency] === true);\n}\n\nfunction parseBooleanFieldValue(rawValue: string | boolean): boolean | null {\n  if (typeof rawValue === \"boolean\") {\n    return rawValue;\n  }\n\n  const normalizedValue = rawValue.trim().toLowerCase();\n  if (!normalizedValue) {\n    return null;\n  }\n  if (normalizedValue === \"true\") {\n    return true;\n  }\n  if (normalizedValue === \"false\") {\n    return false;\n  }\n\n  throw new Error(`Expected a boolean value, received: ${rawValue}`);\n}\n\nfunction coerceFieldValue(\n  field: SettingsFieldSchema,\n  rawValue: string | boolean,\n): SettingsValue {\n  if (field.value_type === \"boolean\") {\n    return parseBooleanFieldValue(rawValue);\n  }\n\n  if (field.value_type === \"integer\" || field.value_type === \"number\") {\n    const stringValue = String(rawValue).trim();\n    if (!stringValue) {\n      return null;\n    }\n\n    const parsedValue = Number(stringValue);\n    if (Number.isNaN(parsedValue)) {\n      throw new Error(`Expected a numeric value, received: ${stringValue}`);\n    }\n    if (field.value_type === \"integer\" && !Number.isInteger(parsedValue)) {\n      throw new Error(`Expected an integer value, received: ${stringValue}`);\n    }\n\n    const constraints = getSettingsFieldConstraints(field.key);\n    if (constraints?.min != null && parsedValue < constraints.min) {\n      throw new Error(`${field.label} must be at least ${constraints.min}`);\n    }\n    if (constraints?.max != null && parsedValue > constraints.max) {\n      throw new Error(`${field.label} must be at most ${constraints.max}`);\n    }\n\n    return parsedValue;\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    const stringValue = String(rawValue).trim();\n    if (!stringValue) {\n      return null;\n    }\n\n    let parsedValue: unknown;\n    try {\n      parsedValue = JSON.parse(stringValue);\n    } catch {\n      throw new Error(`Invalid JSON for ${field.label}`);\n    }\n\n    if (field.value_type === \"array\") {\n      if (!Array.isArray(parsedValue)) {\n        throw new Error(`${field.label} must be a JSON array`);\n      }\n      return parsedValue as SettingsValue[];\n    }\n\n    if (\n      parsedValue === null ||\n      Array.isArray(parsedValue) ||\n      typeof parsedValue !== \"object\"\n    ) {\n      throw new Error(`${field.label} must be a JSON object`);\n    }\n\n    return parsedValue as { [key: string]: SettingsValue };\n  }\n\n  const stringValue = String(rawValue);\n  if (stringValue === \"\" && !field.secret) {\n    return null;\n  }\n\n  return stringValue;\n}\n\nexport function buildSdkSettingsPayload(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  dirty: SettingsDirtyState,\n): SdkSettingsPayload {\n  const payload: Record<string, unknown> = {};\n\n  for (const field of getSchemaFields(schema)) {\n    if (dirty[field.key]) {\n      setDotted(payload, field.key, coerceFieldValue(field, values[field.key]));\n    }\n  }\n\n  return payload as SdkSettingsPayload;\n}\n\nfunction isFieldVisibleInView(\n  field: SettingsFieldSchema,\n  view: SettingsView,\n): boolean {\n  return VIEW_PROMINENCES[view].has(field.prominence);\n}\n\nexport function buildSdkSettingsPayloadForView(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  dirty: SettingsDirtyState,\n  view: SettingsView,\n): SdkSettingsPayload {\n  const payload = buildSdkSettingsPayload(schema, values, dirty) as Record<\n    string,\n    unknown\n  >;\n\n  for (const field of getSchemaFields(schema)) {\n    if (!isFieldVisibleInView(field, view)) {\n      setDotted(payload, field.key, field.default ?? null);\n    }\n  }\n\n  return payload as SdkSettingsPayload;\n}\n\n/** Return sections with fields filtered for the current view tier.\n *  Specially-rendered fields are excluded from the generic list. */\nexport function getVisibleSettingsSections(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  view: SettingsView,\n  excludeKeys: Set<string> = SPECIALLY_RENDERED_KEYS,\n): SettingsSectionSchema[] {\n  if (!isValidSettingsSchema(schema)) return [];\n  return schema.sections\n    .map((section) => ({\n      ...section,\n      fields: section.fields.filter(\n        (field) =>\n          !excludeKeys.has(field.key) &&\n          isFieldVisibleInView(field, view) &&\n          isSettingsFieldVisible(field, values),\n      ),\n    }))\n    .filter((section) => section.fields.length > 0);\n}\n\n/** Whether the schema has any fields visible in the \"advanced\" tier. */\nexport function hasAdvancedSettings(schema: SettingsSchema | null): boolean {\n  if (!schema) return false;\n  return getSchemaFields(schema).some((f) => f.prominence === \"major\");\n}\n\n/** Whether the schema has any \"minor\" prominence fields. */\nexport function hasMinorSettings(schema: SettingsSchema | null): boolean {\n  if (!schema) return false;\n  return getSchemaFields(schema).some((f) => f.prominence === \"minor\");\n}\n"],"mappings":"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"}
+{"version":3,"file":"sdk-settings-schema.cjs","names":[],"sources":["../../src/utils/sdk-settings-schema.ts"],"sourcesContent":["import {\n  SettingProminence,\n  Settings,\n  SettingsFieldSchema,\n  SettingsSchema,\n  SettingsSectionSchema,\n  SettingsValue,\n} from \"#/types/settings\";\nimport { getSettingsFieldConstraints } from \"#/utils/sdk-settings-field-metadata\";\n\nexport type SettingsFormValues = Record<string, string | boolean>;\nexport type SettingsDirtyState = Record<string, boolean>;\nexport type SdkSettingsPayload = Record<string, SettingsValue>;\nexport type SettingsValueSource = \"agent_settings\" | \"conversation_settings\";\n\nexport type SettingsView = \"basic\" | \"advanced\" | \"all\";\n\n/** Fields that are rendered by purpose-built components instead of the\n *  generic `SchemaField` renderer. */\nexport const SPECIALLY_RENDERED_KEYS = new Set([\n  \"llm.model\",\n  \"llm.api_key\",\n  \"llm.base_url\",\n]);\n\n/** Prominence tiers visible at each view level. */\nconst VIEW_PROMINENCES: Record<SettingsView, Set<SettingProminence>> = {\n  basic: new Set<SettingProminence>([\"critical\"]),\n  advanced: new Set<SettingProminence>([\"critical\", \"major\"]),\n  all: new Set<SettingProminence>([\"critical\", \"major\", \"minor\"]),\n};\n\n/**\n * True when `schema` looks like a usable `SettingsSchema` — i.e. an\n * object with an array `sections` field. Guards every helper in this\n * module against malformed/empty schema responses (e.g. when the\n * frontend ends up pointing at a host that does not actually serve\n * `/api/settings/agent-schema`, such as an unconfigured Vercel preview\n * origin that returns the React Router SPA shell for arbitrary\n * `/api/*` paths). Without this check, `schema.sections.filter(...)`\n * inside `SdkSectionPage` blows up with\n * `Cannot read properties of undefined (reading 'filter')` and React\n * Router escalates to a full-screen error page.\n */\nexport function isValidSettingsSchema(\n  schema: SettingsSchema | null | undefined,\n): schema is SettingsSchema {\n  return !!schema && Array.isArray((schema as SettingsSchema).sections);\n}\n\nfunction getSchemaFields(schema: SettingsSchema): SettingsFieldSchema[] {\n  if (!isValidSettingsSchema(schema)) return [];\n  return schema.sections.flatMap((section) => section.fields);\n}\n\n/** Traverse a nested object using a dotted key path (e.g. \"llm.model\"). */\nfunction lookupDotted(\n  obj: Record<string, unknown> | null | undefined,\n  key: string,\n): unknown {\n  if (!obj) return undefined;\n  const parts = key.split(\".\");\n  let current: unknown = obj;\n  for (const part of parts) {\n    if (current == null || typeof current !== \"object\") return undefined;\n    current = (current as Record<string, unknown>)[part];\n  }\n  return current;\n}\n\n/** Set a value in a nested object at a dotted key path (e.g. \"llm.model\"). */\nfunction setDotted(\n  obj: Record<string, unknown>,\n  key: string,\n  value: unknown,\n): void {\n  const parts = key.split(\".\");\n  let current: Record<string, unknown> = obj;\n  for (let i = 0; i < parts.length - 1; i += 1) {\n    const part = parts[i];\n    if (\n      current[part] == null ||\n      typeof current[part] !== \"object\" ||\n      Array.isArray(current[part])\n    ) {\n      current[part] = {};\n    }\n    current = current[part] as Record<string, unknown>;\n  }\n  current[parts[parts.length - 1]] = value;\n}\n\nexport function getSettingValue(\n  settings: Settings,\n  key: string,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsValue {\n  return (lookupDotted(settings[source] as Record<string, unknown>, key) ??\n    null) as SettingsValue;\n}\n\nexport function getAgentSettingValue(\n  settings: Settings,\n  key: string,\n): SettingsValue {\n  return getSettingValue(settings, key, \"agent_settings\");\n}\n\nexport function getConversationSettingValue(\n  settings: Settings,\n  key: string,\n): SettingsValue {\n  return getSettingValue(settings, key, \"conversation_settings\");\n}\n\nfunction isChoiceField(field: SettingsFieldSchema): boolean {\n  return field.choices.length > 0;\n}\n\nfunction isCriticalField(field: SettingsFieldSchema): boolean {\n  return field.prominence === \"critical\";\n}\n\nfunction isMinorField(field: SettingsFieldSchema): boolean {\n  return field.prominence === \"minor\";\n}\n\nexport function normalizeFieldValue(\n  field: SettingsFieldSchema,\n  rawValue: unknown,\n): string | boolean {\n  const resolvedValue = rawValue ?? field.default;\n\n  if (isChoiceField(field)) {\n    return resolvedValue === null || resolvedValue === undefined\n      ? \"\"\n      : String(resolvedValue);\n  }\n\n  if (field.value_type === \"boolean\") {\n    return Boolean(resolvedValue ?? false);\n  }\n\n  if (resolvedValue === null || resolvedValue === undefined) {\n    return \"\";\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    return JSON.stringify(resolvedValue, null, 2);\n  }\n\n  return String(resolvedValue);\n}\n\nfunction normalizeComparableValue(\n  field: SettingsFieldSchema,\n  rawValue: unknown,\n): boolean | number | string | null {\n  if (rawValue === undefined) {\n    return null;\n  }\n\n  if (field.value_type === \"boolean\") {\n    if (typeof rawValue === \"string\") {\n      if (rawValue === \"true\") {\n        return true;\n      }\n      if (rawValue === \"false\") {\n        return false;\n      }\n    }\n    if (rawValue === null) {\n      return null;\n    }\n    return Boolean(rawValue);\n  }\n\n  if (field.value_type === \"integer\" || field.value_type === \"number\") {\n    if (rawValue === \"\" || rawValue === null) {\n      return null;\n    }\n\n    const parsedValue =\n      typeof rawValue === \"number\" ? rawValue : Number(String(rawValue));\n    return Number.isNaN(parsedValue) ? null : parsedValue;\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    if (rawValue === null) {\n      return null;\n    }\n\n    // Treat empty objects as null so that serializer artifacts\n    // (e.g. mcp_config: {} vs schema default null) don't trigger\n    // a spurious view escalation in inferInitialView.\n    if (\n      field.value_type === \"object\" &&\n      typeof rawValue === \"object\" &&\n      !Array.isArray(rawValue) &&\n      Object.keys(rawValue as Record<string, unknown>).length === 0\n    ) {\n      return null;\n    }\n\n    if (typeof rawValue === \"string\") {\n      const trimmedValue = rawValue.trim();\n      if (!trimmedValue) {\n        return null;\n      }\n      try {\n        const parsed: unknown = JSON.parse(trimmedValue);\n        // Also normalise stringified empty objects\n        if (\n          field.value_type === \"object\" &&\n          parsed !== null &&\n          typeof parsed === \"object\" &&\n          !Array.isArray(parsed) &&\n          Object.keys(parsed as Record<string, unknown>).length === 0\n        ) {\n          return null;\n        }\n        return JSON.stringify(parsed);\n      } catch {\n        return trimmedValue;\n      }\n    }\n\n    return JSON.stringify(rawValue);\n  }\n\n  if (rawValue === null) {\n    return null;\n  }\n\n  return String(rawValue);\n}\n\nexport function buildInitialSettingsFormValues(\n  settings: Settings,\n  schemaOverride?: SettingsSchema | null,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsFormValues {\n  const schema =\n    schemaOverride ??\n    (source === \"conversation_settings\"\n      ? settings.conversation_settings_schema\n      : settings.agent_settings_schema);\n  if (!schema) {\n    return {};\n  }\n\n  return Object.fromEntries(\n    getSchemaFields(schema).map((field) => [\n      field.key,\n      normalizeFieldValue(field, getSettingValue(settings, field.key, source)),\n    ]),\n  );\n}\n\nexport function inferInitialView(\n  settings: Settings,\n  schemaOverride?: SettingsSchema | null,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsView {\n  const schema =\n    schemaOverride ??\n    (source === \"conversation_settings\"\n      ? settings.conversation_settings_schema\n      : settings.agent_settings_schema);\n  if (!schema) {\n    return \"basic\";\n  }\n\n  let hasMinorOverride = false;\n  let hasMajorOverride = false;\n\n  for (const field of getSchemaFields(schema)) {\n    if (!isCriticalField(field)) {\n      const currentValue = getSettingValue(settings, field.key, source);\n      const isDifferent =\n        normalizeComparableValue(\n          field,\n          currentValue ?? field.default ?? null,\n        ) !== normalizeComparableValue(field, field.default ?? null);\n\n      if (isDifferent) {\n        if (isMinorField(field)) {\n          hasMinorOverride = true;\n        } else {\n          hasMajorOverride = true;\n        }\n      }\n    }\n  }\n\n  if (hasMinorOverride) return \"all\";\n  if (hasMajorOverride) return \"advanced\";\n  return \"basic\";\n}\n\n/** Determine which view tier to default to based on whether the user has\n *  overridden any non-critical settings. */\nexport function hasAdvancedSettingsOverrides(settings: Settings): boolean {\n  return inferInitialView(settings) !== \"basic\";\n}\n\nexport function isSettingsFieldVisible(\n  field: SettingsFieldSchema,\n  values: SettingsFormValues,\n): boolean {\n  return field.depends_on.every((dependency) => values[dependency] === true);\n}\n\nfunction parseBooleanFieldValue(rawValue: string | boolean): boolean | null {\n  if (typeof rawValue === \"boolean\") {\n    return rawValue;\n  }\n\n  const normalizedValue = rawValue.trim().toLowerCase();\n  if (!normalizedValue) {\n    return null;\n  }\n  if (normalizedValue === \"true\") {\n    return true;\n  }\n  if (normalizedValue === \"false\") {\n    return false;\n  }\n\n  throw new Error(`Expected a boolean value, received: ${rawValue}`);\n}\n\nfunction coerceFieldValue(\n  field: SettingsFieldSchema,\n  rawValue: string | boolean,\n): SettingsValue {\n  if (field.value_type === \"boolean\") {\n    return parseBooleanFieldValue(rawValue);\n  }\n\n  if (field.value_type === \"integer\" || field.value_type === \"number\") {\n    const stringValue = String(rawValue).trim();\n    if (!stringValue) {\n      return null;\n    }\n\n    const parsedValue = Number(stringValue);\n    if (Number.isNaN(parsedValue)) {\n      throw new Error(`Expected a numeric value, received: ${stringValue}`);\n    }\n    if (field.value_type === \"integer\" && !Number.isInteger(parsedValue)) {\n      throw new Error(`Expected an integer value, received: ${stringValue}`);\n    }\n\n    const constraints = getSettingsFieldConstraints(field.key);\n    if (constraints?.min != null && parsedValue < constraints.min) {\n      throw new Error(`${field.label} must be at least ${constraints.min}`);\n    }\n    if (constraints?.max != null && parsedValue > constraints.max) {\n      throw new Error(`${field.label} must be at most ${constraints.max}`);\n    }\n\n    return parsedValue;\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    const stringValue = String(rawValue).trim();\n    if (!stringValue) {\n      return null;\n    }\n\n    let parsedValue: unknown;\n    try {\n      parsedValue = JSON.parse(stringValue);\n    } catch {\n      throw new Error(`Invalid JSON for ${field.label}`);\n    }\n\n    if (field.value_type === \"array\") {\n      if (!Array.isArray(parsedValue)) {\n        throw new Error(`${field.label} must be a JSON array`);\n      }\n      return parsedValue as SettingsValue[];\n    }\n\n    if (\n      parsedValue === null ||\n      Array.isArray(parsedValue) ||\n      typeof parsedValue !== \"object\"\n    ) {\n      throw new Error(`${field.label} must be a JSON object`);\n    }\n\n    return parsedValue as { [key: string]: SettingsValue };\n  }\n\n  const stringValue = String(rawValue);\n  if (stringValue === \"\" && !field.secret) {\n    return null;\n  }\n\n  return stringValue;\n}\n\nexport function buildSdkSettingsPayload(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  dirty: SettingsDirtyState,\n): SdkSettingsPayload {\n  const payload: Record<string, unknown> = {};\n\n  for (const field of getSchemaFields(schema)) {\n    if (dirty[field.key]) {\n      setDotted(payload, field.key, coerceFieldValue(field, values[field.key]));\n    }\n  }\n\n  return payload as SdkSettingsPayload;\n}\n\nfunction isFieldVisibleInView(\n  field: SettingsFieldSchema,\n  view: SettingsView,\n): boolean {\n  return VIEW_PROMINENCES[view].has(field.prominence);\n}\n\nexport function buildSdkSettingsPayloadForView(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  dirty: SettingsDirtyState,\n  view: SettingsView,\n): SdkSettingsPayload {\n  const payload = buildSdkSettingsPayload(schema, values, dirty) as Record<\n    string,\n    unknown\n  >;\n\n  for (const field of getSchemaFields(schema)) {\n    if (!isFieldVisibleInView(field, view)) {\n      setDotted(payload, field.key, field.default ?? null);\n    }\n  }\n\n  return payload as SdkSettingsPayload;\n}\n\n/** Return sections with fields filtered for the current view tier.\n *  Specially-rendered fields are excluded from the generic list. */\nexport function getVisibleSettingsSections(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  view: SettingsView,\n  excludeKeys: Set<string> = SPECIALLY_RENDERED_KEYS,\n): SettingsSectionSchema[] {\n  if (!isValidSettingsSchema(schema)) return [];\n  return schema.sections\n    .map((section) => ({\n      ...section,\n      fields: section.fields.filter(\n        (field) =>\n          !excludeKeys.has(field.key) &&\n          isFieldVisibleInView(field, view) &&\n          isSettingsFieldVisible(field, values),\n      ),\n    }))\n    .filter((section) => section.fields.length > 0);\n}\n\n/** Whether the schema has any fields visible in the \"advanced\" tier. */\nexport function hasAdvancedSettings(schema: SettingsSchema | null): boolean {\n  if (!schema) return false;\n  return getSchemaFields(schema).some((f) => f.prominence === \"major\");\n}\n\n/** Whether the schema has any \"minor\" prominence fields. */\nexport function hasMinorSettings(schema: SettingsSchema | null): boolean {\n  if (!schema) return false;\n  return getSchemaFields(schema).some((f) => f.prominence === \"minor\");\n}\n"],"mappings":"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"}

package/dist/utils/sdk-settings-schema.d.ts

@@ -23,6 +23,7 @@ export declare function isValidSettingsSchema(schema: SettingsSchema | null | un
 export declare function getSettingValue(settings: Settings, key: string, source?: SettingsValueSource): SettingsValue;
 export declare function getAgentSettingValue(settings: Settings, key: string): SettingsValue;
 export declare function getConversationSettingValue(settings: Settings, key: string): SettingsValue;
+export declare function normalizeFieldValue(field: SettingsFieldSchema, rawValue: unknown): string | boolean;
 export declare function buildInitialSettingsFormValues(settings: Settings, schemaOverride?: SettingsSchema | null, source?: SettingsValueSource): SettingsFormValues;
 export declare function inferInitialView(settings: Settings, schemaOverride?: SettingsSchema | null, source?: SettingsValueSource): SettingsView;
 /** Determine which view tier to default to based on whether the user has

package/dist/utils/sdk-settings-schema.js

@@ -165,6 +165,6 @@ function w(e) {
 	return e ? i(e).some((e) => e.prominence === "minor") : !1;
 }
 //#endregion
-export { m as buildInitialSettingsFormValues, x as buildSdkSettingsPayloadForView, c as getAgentSettingValue, S as getVisibleSettingsSections, C as hasAdvancedSettings, w as hasMinorSettings, h as inferInitialView, r as isValidSettingsSchema };
+export { m as buildInitialSettingsFormValues, y as buildSdkSettingsPayload, x as buildSdkSettingsPayloadForView, c as getAgentSettingValue, S as getVisibleSettingsSections, C as hasAdvancedSettings, w as hasMinorSettings, h as inferInitialView, r as isValidSettingsSchema };
 
 //# sourceMappingURL=sdk-settings-schema.js.map

package/dist/utils/sdk-settings-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-settings-schema.js","names":[],"sources":["../../src/utils/sdk-settings-schema.ts"],"sourcesContent":["import {\n  SettingProminence,\n  Settings,\n  SettingsFieldSchema,\n  SettingsSchema,\n  SettingsSectionSchema,\n  SettingsValue,\n} from \"#/types/settings\";\nimport { getSettingsFieldConstraints } from \"#/utils/sdk-settings-field-metadata\";\n\nexport type SettingsFormValues = Record<string, string | boolean>;\nexport type SettingsDirtyState = Record<string, boolean>;\nexport type SdkSettingsPayload = Record<string, SettingsValue>;\nexport type SettingsValueSource = \"agent_settings\" | \"conversation_settings\";\n\nexport type SettingsView = \"basic\" | \"advanced\" | \"all\";\n\n/** Fields that are rendered by purpose-built components instead of the\n *  generic `SchemaField` renderer. */\nexport const SPECIALLY_RENDERED_KEYS = new Set([\n  \"llm.model\",\n  \"llm.api_key\",\n  \"llm.base_url\",\n]);\n\n/** Prominence tiers visible at each view level. */\nconst VIEW_PROMINENCES: Record<SettingsView, Set<SettingProminence>> = {\n  basic: new Set<SettingProminence>([\"critical\"]),\n  advanced: new Set<SettingProminence>([\"critical\", \"major\"]),\n  all: new Set<SettingProminence>([\"critical\", \"major\", \"minor\"]),\n};\n\n/**\n * True when `schema` looks like a usable `SettingsSchema` — i.e. an\n * object with an array `sections` field. Guards every helper in this\n * module against malformed/empty schema responses (e.g. when the\n * frontend ends up pointing at a host that does not actually serve\n * `/api/settings/agent-schema`, such as an unconfigured Vercel preview\n * origin that returns the React Router SPA shell for arbitrary\n * `/api/*` paths). Without this check, `schema.sections.filter(...)`\n * inside `SdkSectionPage` blows up with\n * `Cannot read properties of undefined (reading 'filter')` and React\n * Router escalates to a full-screen error page.\n */\nexport function isValidSettingsSchema(\n  schema: SettingsSchema | null | undefined,\n): schema is SettingsSchema {\n  return !!schema && Array.isArray((schema as SettingsSchema).sections);\n}\n\nfunction getSchemaFields(schema: SettingsSchema): SettingsFieldSchema[] {\n  if (!isValidSettingsSchema(schema)) return [];\n  return schema.sections.flatMap((section) => section.fields);\n}\n\n/** Traverse a nested object using a dotted key path (e.g. \"llm.model\"). */\nfunction lookupDotted(\n  obj: Record<string, unknown> | null | undefined,\n  key: string,\n): unknown {\n  if (!obj) return undefined;\n  const parts = key.split(\".\");\n  let current: unknown = obj;\n  for (const part of parts) {\n    if (current == null || typeof current !== \"object\") return undefined;\n    current = (current as Record<string, unknown>)[part];\n  }\n  return current;\n}\n\n/** Set a value in a nested object at a dotted key path (e.g. \"llm.model\"). */\nfunction setDotted(\n  obj: Record<string, unknown>,\n  key: string,\n  value: unknown,\n): void {\n  const parts = key.split(\".\");\n  let current: Record<string, unknown> = obj;\n  for (let i = 0; i < parts.length - 1; i += 1) {\n    const part = parts[i];\n    if (\n      current[part] == null ||\n      typeof current[part] !== \"object\" ||\n      Array.isArray(current[part])\n    ) {\n      current[part] = {};\n    }\n    current = current[part] as Record<string, unknown>;\n  }\n  current[parts[parts.length - 1]] = value;\n}\n\nexport function getSettingValue(\n  settings: Settings,\n  key: string,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsValue {\n  return (lookupDotted(settings[source] as Record<string, unknown>, key) ??\n    null) as SettingsValue;\n}\n\nexport function getAgentSettingValue(\n  settings: Settings,\n  key: string,\n): SettingsValue {\n  return getSettingValue(settings, key, \"agent_settings\");\n}\n\nexport function getConversationSettingValue(\n  settings: Settings,\n  key: string,\n): SettingsValue {\n  return getSettingValue(settings, key, \"conversation_settings\");\n}\n\nfunction isChoiceField(field: SettingsFieldSchema): boolean {\n  return field.choices.length > 0;\n}\n\nfunction isCriticalField(field: SettingsFieldSchema): boolean {\n  return field.prominence === \"critical\";\n}\n\nfunction isMinorField(field: SettingsFieldSchema): boolean {\n  return field.prominence === \"minor\";\n}\n\nfunction normalizeFieldValue(\n  field: SettingsFieldSchema,\n  rawValue: unknown,\n): string | boolean {\n  const resolvedValue = rawValue ?? field.default;\n\n  if (isChoiceField(field)) {\n    return resolvedValue === null || resolvedValue === undefined\n      ? \"\"\n      : String(resolvedValue);\n  }\n\n  if (field.value_type === \"boolean\") {\n    return Boolean(resolvedValue ?? false);\n  }\n\n  if (resolvedValue === null || resolvedValue === undefined) {\n    return \"\";\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    return JSON.stringify(resolvedValue, null, 2);\n  }\n\n  return String(resolvedValue);\n}\n\nfunction normalizeComparableValue(\n  field: SettingsFieldSchema,\n  rawValue: unknown,\n): boolean | number | string | null {\n  if (rawValue === undefined) {\n    return null;\n  }\n\n  if (field.value_type === \"boolean\") {\n    if (typeof rawValue === \"string\") {\n      if (rawValue === \"true\") {\n        return true;\n      }\n      if (rawValue === \"false\") {\n        return false;\n      }\n    }\n    if (rawValue === null) {\n      return null;\n    }\n    return Boolean(rawValue);\n  }\n\n  if (field.value_type === \"integer\" || field.value_type === \"number\") {\n    if (rawValue === \"\" || rawValue === null) {\n      return null;\n    }\n\n    const parsedValue =\n      typeof rawValue === \"number\" ? rawValue : Number(String(rawValue));\n    return Number.isNaN(parsedValue) ? null : parsedValue;\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    if (rawValue === null) {\n      return null;\n    }\n\n    // Treat empty objects as null so that serializer artifacts\n    // (e.g. mcp_config: {} vs schema default null) don't trigger\n    // a spurious view escalation in inferInitialView.\n    if (\n      field.value_type === \"object\" &&\n      typeof rawValue === \"object\" &&\n      !Array.isArray(rawValue) &&\n      Object.keys(rawValue as Record<string, unknown>).length === 0\n    ) {\n      return null;\n    }\n\n    if (typeof rawValue === \"string\") {\n      const trimmedValue = rawValue.trim();\n      if (!trimmedValue) {\n        return null;\n      }\n      try {\n        const parsed: unknown = JSON.parse(trimmedValue);\n        // Also normalise stringified empty objects\n        if (\n          field.value_type === \"object\" &&\n          parsed !== null &&\n          typeof parsed === \"object\" &&\n          !Array.isArray(parsed) &&\n          Object.keys(parsed as Record<string, unknown>).length === 0\n        ) {\n          return null;\n        }\n        return JSON.stringify(parsed);\n      } catch {\n        return trimmedValue;\n      }\n    }\n\n    return JSON.stringify(rawValue);\n  }\n\n  if (rawValue === null) {\n    return null;\n  }\n\n  return String(rawValue);\n}\n\nexport function buildInitialSettingsFormValues(\n  settings: Settings,\n  schemaOverride?: SettingsSchema | null,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsFormValues {\n  const schema =\n    schemaOverride ??\n    (source === \"conversation_settings\"\n      ? settings.conversation_settings_schema\n      : settings.agent_settings_schema);\n  if (!schema) {\n    return {};\n  }\n\n  return Object.fromEntries(\n    getSchemaFields(schema).map((field) => [\n      field.key,\n      normalizeFieldValue(field, getSettingValue(settings, field.key, source)),\n    ]),\n  );\n}\n\nexport function inferInitialView(\n  settings: Settings,\n  schemaOverride?: SettingsSchema | null,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsView {\n  const schema =\n    schemaOverride ??\n    (source === \"conversation_settings\"\n      ? settings.conversation_settings_schema\n      : settings.agent_settings_schema);\n  if (!schema) {\n    return \"basic\";\n  }\n\n  let hasMinorOverride = false;\n  let hasMajorOverride = false;\n\n  for (const field of getSchemaFields(schema)) {\n    if (!isCriticalField(field)) {\n      const currentValue = getSettingValue(settings, field.key, source);\n      const isDifferent =\n        normalizeComparableValue(\n          field,\n          currentValue ?? field.default ?? null,\n        ) !== normalizeComparableValue(field, field.default ?? null);\n\n      if (isDifferent) {\n        if (isMinorField(field)) {\n          hasMinorOverride = true;\n        } else {\n          hasMajorOverride = true;\n        }\n      }\n    }\n  }\n\n  if (hasMinorOverride) return \"all\";\n  if (hasMajorOverride) return \"advanced\";\n  return \"basic\";\n}\n\n/** Determine which view tier to default to based on whether the user has\n *  overridden any non-critical settings. */\nexport function hasAdvancedSettingsOverrides(settings: Settings): boolean {\n  return inferInitialView(settings) !== \"basic\";\n}\n\nexport function isSettingsFieldVisible(\n  field: SettingsFieldSchema,\n  values: SettingsFormValues,\n): boolean {\n  return field.depends_on.every((dependency) => values[dependency] === true);\n}\n\nfunction parseBooleanFieldValue(rawValue: string | boolean): boolean | null {\n  if (typeof rawValue === \"boolean\") {\n    return rawValue;\n  }\n\n  const normalizedValue = rawValue.trim().toLowerCase();\n  if (!normalizedValue) {\n    return null;\n  }\n  if (normalizedValue === \"true\") {\n    return true;\n  }\n  if (normalizedValue === \"false\") {\n    return false;\n  }\n\n  throw new Error(`Expected a boolean value, received: ${rawValue}`);\n}\n\nfunction coerceFieldValue(\n  field: SettingsFieldSchema,\n  rawValue: string | boolean,\n): SettingsValue {\n  if (field.value_type === \"boolean\") {\n    return parseBooleanFieldValue(rawValue);\n  }\n\n  if (field.value_type === \"integer\" || field.value_type === \"number\") {\n    const stringValue = String(rawValue).trim();\n    if (!stringValue) {\n      return null;\n    }\n\n    const parsedValue = Number(stringValue);\n    if (Number.isNaN(parsedValue)) {\n      throw new Error(`Expected a numeric value, received: ${stringValue}`);\n    }\n    if (field.value_type === \"integer\" && !Number.isInteger(parsedValue)) {\n      throw new Error(`Expected an integer value, received: ${stringValue}`);\n    }\n\n    const constraints = getSettingsFieldConstraints(field.key);\n    if (constraints?.min != null && parsedValue < constraints.min) {\n      throw new Error(`${field.label} must be at least ${constraints.min}`);\n    }\n    if (constraints?.max != null && parsedValue > constraints.max) {\n      throw new Error(`${field.label} must be at most ${constraints.max}`);\n    }\n\n    return parsedValue;\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    const stringValue = String(rawValue).trim();\n    if (!stringValue) {\n      return null;\n    }\n\n    let parsedValue: unknown;\n    try {\n      parsedValue = JSON.parse(stringValue);\n    } catch {\n      throw new Error(`Invalid JSON for ${field.label}`);\n    }\n\n    if (field.value_type === \"array\") {\n      if (!Array.isArray(parsedValue)) {\n        throw new Error(`${field.label} must be a JSON array`);\n      }\n      return parsedValue as SettingsValue[];\n    }\n\n    if (\n      parsedValue === null ||\n      Array.isArray(parsedValue) ||\n      typeof parsedValue !== \"object\"\n    ) {\n      throw new Error(`${field.label} must be a JSON object`);\n    }\n\n    return parsedValue as { [key: string]: SettingsValue };\n  }\n\n  const stringValue = String(rawValue);\n  if (stringValue === \"\" && !field.secret) {\n    return null;\n  }\n\n  return stringValue;\n}\n\nexport function buildSdkSettingsPayload(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  dirty: SettingsDirtyState,\n): SdkSettingsPayload {\n  const payload: Record<string, unknown> = {};\n\n  for (const field of getSchemaFields(schema)) {\n    if (dirty[field.key]) {\n      setDotted(payload, field.key, coerceFieldValue(field, values[field.key]));\n    }\n  }\n\n  return payload as SdkSettingsPayload;\n}\n\nfunction isFieldVisibleInView(\n  field: SettingsFieldSchema,\n  view: SettingsView,\n): boolean {\n  return VIEW_PROMINENCES[view].has(field.prominence);\n}\n\nexport function buildSdkSettingsPayloadForView(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  dirty: SettingsDirtyState,\n  view: SettingsView,\n): SdkSettingsPayload {\n  const payload = buildSdkSettingsPayload(schema, values, dirty) as Record<\n    string,\n    unknown\n  >;\n\n  for (const field of getSchemaFields(schema)) {\n    if (!isFieldVisibleInView(field, view)) {\n      setDotted(payload, field.key, field.default ?? null);\n    }\n  }\n\n  return payload as SdkSettingsPayload;\n}\n\n/** Return sections with fields filtered for the current view tier.\n *  Specially-rendered fields are excluded from the generic list. */\nexport function getVisibleSettingsSections(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  view: SettingsView,\n  excludeKeys: Set<string> = SPECIALLY_RENDERED_KEYS,\n): SettingsSectionSchema[] {\n  if (!isValidSettingsSchema(schema)) return [];\n  return schema.sections\n    .map((section) => ({\n      ...section,\n      fields: section.fields.filter(\n        (field) =>\n          !excludeKeys.has(field.key) &&\n          isFieldVisibleInView(field, view) &&\n          isSettingsFieldVisible(field, values),\n      ),\n    }))\n    .filter((section) => section.fields.length > 0);\n}\n\n/** Whether the schema has any fields visible in the \"advanced\" tier. */\nexport function hasAdvancedSettings(schema: SettingsSchema | null): boolean {\n  if (!schema) return false;\n  return getSchemaFields(schema).some((f) => f.prominence === \"major\");\n}\n\n/** Whether the schema has any \"minor\" prominence fields. */\nexport function hasMinorSettings(schema: SettingsSchema | null): boolean {\n  if (!schema) return false;\n  return getSchemaFields(schema).some((f) => f.prominence === \"minor\");\n}\n"],"mappings":"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"}
+{"version":3,"file":"sdk-settings-schema.js","names":[],"sources":["../../src/utils/sdk-settings-schema.ts"],"sourcesContent":["import {\n  SettingProminence,\n  Settings,\n  SettingsFieldSchema,\n  SettingsSchema,\n  SettingsSectionSchema,\n  SettingsValue,\n} from \"#/types/settings\";\nimport { getSettingsFieldConstraints } from \"#/utils/sdk-settings-field-metadata\";\n\nexport type SettingsFormValues = Record<string, string | boolean>;\nexport type SettingsDirtyState = Record<string, boolean>;\nexport type SdkSettingsPayload = Record<string, SettingsValue>;\nexport type SettingsValueSource = \"agent_settings\" | \"conversation_settings\";\n\nexport type SettingsView = \"basic\" | \"advanced\" | \"all\";\n\n/** Fields that are rendered by purpose-built components instead of the\n *  generic `SchemaField` renderer. */\nexport const SPECIALLY_RENDERED_KEYS = new Set([\n  \"llm.model\",\n  \"llm.api_key\",\n  \"llm.base_url\",\n]);\n\n/** Prominence tiers visible at each view level. */\nconst VIEW_PROMINENCES: Record<SettingsView, Set<SettingProminence>> = {\n  basic: new Set<SettingProminence>([\"critical\"]),\n  advanced: new Set<SettingProminence>([\"critical\", \"major\"]),\n  all: new Set<SettingProminence>([\"critical\", \"major\", \"minor\"]),\n};\n\n/**\n * True when `schema` looks like a usable `SettingsSchema` — i.e. an\n * object with an array `sections` field. Guards every helper in this\n * module against malformed/empty schema responses (e.g. when the\n * frontend ends up pointing at a host that does not actually serve\n * `/api/settings/agent-schema`, such as an unconfigured Vercel preview\n * origin that returns the React Router SPA shell for arbitrary\n * `/api/*` paths). Without this check, `schema.sections.filter(...)`\n * inside `SdkSectionPage` blows up with\n * `Cannot read properties of undefined (reading 'filter')` and React\n * Router escalates to a full-screen error page.\n */\nexport function isValidSettingsSchema(\n  schema: SettingsSchema | null | undefined,\n): schema is SettingsSchema {\n  return !!schema && Array.isArray((schema as SettingsSchema).sections);\n}\n\nfunction getSchemaFields(schema: SettingsSchema): SettingsFieldSchema[] {\n  if (!isValidSettingsSchema(schema)) return [];\n  return schema.sections.flatMap((section) => section.fields);\n}\n\n/** Traverse a nested object using a dotted key path (e.g. \"llm.model\"). */\nfunction lookupDotted(\n  obj: Record<string, unknown> | null | undefined,\n  key: string,\n): unknown {\n  if (!obj) return undefined;\n  const parts = key.split(\".\");\n  let current: unknown = obj;\n  for (const part of parts) {\n    if (current == null || typeof current !== \"object\") return undefined;\n    current = (current as Record<string, unknown>)[part];\n  }\n  return current;\n}\n\n/** Set a value in a nested object at a dotted key path (e.g. \"llm.model\"). */\nfunction setDotted(\n  obj: Record<string, unknown>,\n  key: string,\n  value: unknown,\n): void {\n  const parts = key.split(\".\");\n  let current: Record<string, unknown> = obj;\n  for (let i = 0; i < parts.length - 1; i += 1) {\n    const part = parts[i];\n    if (\n      current[part] == null ||\n      typeof current[part] !== \"object\" ||\n      Array.isArray(current[part])\n    ) {\n      current[part] = {};\n    }\n    current = current[part] as Record<string, unknown>;\n  }\n  current[parts[parts.length - 1]] = value;\n}\n\nexport function getSettingValue(\n  settings: Settings,\n  key: string,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsValue {\n  return (lookupDotted(settings[source] as Record<string, unknown>, key) ??\n    null) as SettingsValue;\n}\n\nexport function getAgentSettingValue(\n  settings: Settings,\n  key: string,\n): SettingsValue {\n  return getSettingValue(settings, key, \"agent_settings\");\n}\n\nexport function getConversationSettingValue(\n  settings: Settings,\n  key: string,\n): SettingsValue {\n  return getSettingValue(settings, key, \"conversation_settings\");\n}\n\nfunction isChoiceField(field: SettingsFieldSchema): boolean {\n  return field.choices.length > 0;\n}\n\nfunction isCriticalField(field: SettingsFieldSchema): boolean {\n  return field.prominence === \"critical\";\n}\n\nfunction isMinorField(field: SettingsFieldSchema): boolean {\n  return field.prominence === \"minor\";\n}\n\nexport function normalizeFieldValue(\n  field: SettingsFieldSchema,\n  rawValue: unknown,\n): string | boolean {\n  const resolvedValue = rawValue ?? field.default;\n\n  if (isChoiceField(field)) {\n    return resolvedValue === null || resolvedValue === undefined\n      ? \"\"\n      : String(resolvedValue);\n  }\n\n  if (field.value_type === \"boolean\") {\n    return Boolean(resolvedValue ?? false);\n  }\n\n  if (resolvedValue === null || resolvedValue === undefined) {\n    return \"\";\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    return JSON.stringify(resolvedValue, null, 2);\n  }\n\n  return String(resolvedValue);\n}\n\nfunction normalizeComparableValue(\n  field: SettingsFieldSchema,\n  rawValue: unknown,\n): boolean | number | string | null {\n  if (rawValue === undefined) {\n    return null;\n  }\n\n  if (field.value_type === \"boolean\") {\n    if (typeof rawValue === \"string\") {\n      if (rawValue === \"true\") {\n        return true;\n      }\n      if (rawValue === \"false\") {\n        return false;\n      }\n    }\n    if (rawValue === null) {\n      return null;\n    }\n    return Boolean(rawValue);\n  }\n\n  if (field.value_type === \"integer\" || field.value_type === \"number\") {\n    if (rawValue === \"\" || rawValue === null) {\n      return null;\n    }\n\n    const parsedValue =\n      typeof rawValue === \"number\" ? rawValue : Number(String(rawValue));\n    return Number.isNaN(parsedValue) ? null : parsedValue;\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    if (rawValue === null) {\n      return null;\n    }\n\n    // Treat empty objects as null so that serializer artifacts\n    // (e.g. mcp_config: {} vs schema default null) don't trigger\n    // a spurious view escalation in inferInitialView.\n    if (\n      field.value_type === \"object\" &&\n      typeof rawValue === \"object\" &&\n      !Array.isArray(rawValue) &&\n      Object.keys(rawValue as Record<string, unknown>).length === 0\n    ) {\n      return null;\n    }\n\n    if (typeof rawValue === \"string\") {\n      const trimmedValue = rawValue.trim();\n      if (!trimmedValue) {\n        return null;\n      }\n      try {\n        const parsed: unknown = JSON.parse(trimmedValue);\n        // Also normalise stringified empty objects\n        if (\n          field.value_type === \"object\" &&\n          parsed !== null &&\n          typeof parsed === \"object\" &&\n          !Array.isArray(parsed) &&\n          Object.keys(parsed as Record<string, unknown>).length === 0\n        ) {\n          return null;\n        }\n        return JSON.stringify(parsed);\n      } catch {\n        return trimmedValue;\n      }\n    }\n\n    return JSON.stringify(rawValue);\n  }\n\n  if (rawValue === null) {\n    return null;\n  }\n\n  return String(rawValue);\n}\n\nexport function buildInitialSettingsFormValues(\n  settings: Settings,\n  schemaOverride?: SettingsSchema | null,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsFormValues {\n  const schema =\n    schemaOverride ??\n    (source === \"conversation_settings\"\n      ? settings.conversation_settings_schema\n      : settings.agent_settings_schema);\n  if (!schema) {\n    return {};\n  }\n\n  return Object.fromEntries(\n    getSchemaFields(schema).map((field) => [\n      field.key,\n      normalizeFieldValue(field, getSettingValue(settings, field.key, source)),\n    ]),\n  );\n}\n\nexport function inferInitialView(\n  settings: Settings,\n  schemaOverride?: SettingsSchema | null,\n  source: SettingsValueSource = \"agent_settings\",\n): SettingsView {\n  const schema =\n    schemaOverride ??\n    (source === \"conversation_settings\"\n      ? settings.conversation_settings_schema\n      : settings.agent_settings_schema);\n  if (!schema) {\n    return \"basic\";\n  }\n\n  let hasMinorOverride = false;\n  let hasMajorOverride = false;\n\n  for (const field of getSchemaFields(schema)) {\n    if (!isCriticalField(field)) {\n      const currentValue = getSettingValue(settings, field.key, source);\n      const isDifferent =\n        normalizeComparableValue(\n          field,\n          currentValue ?? field.default ?? null,\n        ) !== normalizeComparableValue(field, field.default ?? null);\n\n      if (isDifferent) {\n        if (isMinorField(field)) {\n          hasMinorOverride = true;\n        } else {\n          hasMajorOverride = true;\n        }\n      }\n    }\n  }\n\n  if (hasMinorOverride) return \"all\";\n  if (hasMajorOverride) return \"advanced\";\n  return \"basic\";\n}\n\n/** Determine which view tier to default to based on whether the user has\n *  overridden any non-critical settings. */\nexport function hasAdvancedSettingsOverrides(settings: Settings): boolean {\n  return inferInitialView(settings) !== \"basic\";\n}\n\nexport function isSettingsFieldVisible(\n  field: SettingsFieldSchema,\n  values: SettingsFormValues,\n): boolean {\n  return field.depends_on.every((dependency) => values[dependency] === true);\n}\n\nfunction parseBooleanFieldValue(rawValue: string | boolean): boolean | null {\n  if (typeof rawValue === \"boolean\") {\n    return rawValue;\n  }\n\n  const normalizedValue = rawValue.trim().toLowerCase();\n  if (!normalizedValue) {\n    return null;\n  }\n  if (normalizedValue === \"true\") {\n    return true;\n  }\n  if (normalizedValue === \"false\") {\n    return false;\n  }\n\n  throw new Error(`Expected a boolean value, received: ${rawValue}`);\n}\n\nfunction coerceFieldValue(\n  field: SettingsFieldSchema,\n  rawValue: string | boolean,\n): SettingsValue {\n  if (field.value_type === \"boolean\") {\n    return parseBooleanFieldValue(rawValue);\n  }\n\n  if (field.value_type === \"integer\" || field.value_type === \"number\") {\n    const stringValue = String(rawValue).trim();\n    if (!stringValue) {\n      return null;\n    }\n\n    const parsedValue = Number(stringValue);\n    if (Number.isNaN(parsedValue)) {\n      throw new Error(`Expected a numeric value, received: ${stringValue}`);\n    }\n    if (field.value_type === \"integer\" && !Number.isInteger(parsedValue)) {\n      throw new Error(`Expected an integer value, received: ${stringValue}`);\n    }\n\n    const constraints = getSettingsFieldConstraints(field.key);\n    if (constraints?.min != null && parsedValue < constraints.min) {\n      throw new Error(`${field.label} must be at least ${constraints.min}`);\n    }\n    if (constraints?.max != null && parsedValue > constraints.max) {\n      throw new Error(`${field.label} must be at most ${constraints.max}`);\n    }\n\n    return parsedValue;\n  }\n\n  if (field.value_type === \"array\" || field.value_type === \"object\") {\n    const stringValue = String(rawValue).trim();\n    if (!stringValue) {\n      return null;\n    }\n\n    let parsedValue: unknown;\n    try {\n      parsedValue = JSON.parse(stringValue);\n    } catch {\n      throw new Error(`Invalid JSON for ${field.label}`);\n    }\n\n    if (field.value_type === \"array\") {\n      if (!Array.isArray(parsedValue)) {\n        throw new Error(`${field.label} must be a JSON array`);\n      }\n      return parsedValue as SettingsValue[];\n    }\n\n    if (\n      parsedValue === null ||\n      Array.isArray(parsedValue) ||\n      typeof parsedValue !== \"object\"\n    ) {\n      throw new Error(`${field.label} must be a JSON object`);\n    }\n\n    return parsedValue as { [key: string]: SettingsValue };\n  }\n\n  const stringValue = String(rawValue);\n  if (stringValue === \"\" && !field.secret) {\n    return null;\n  }\n\n  return stringValue;\n}\n\nexport function buildSdkSettingsPayload(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  dirty: SettingsDirtyState,\n): SdkSettingsPayload {\n  const payload: Record<string, unknown> = {};\n\n  for (const field of getSchemaFields(schema)) {\n    if (dirty[field.key]) {\n      setDotted(payload, field.key, coerceFieldValue(field, values[field.key]));\n    }\n  }\n\n  return payload as SdkSettingsPayload;\n}\n\nfunction isFieldVisibleInView(\n  field: SettingsFieldSchema,\n  view: SettingsView,\n): boolean {\n  return VIEW_PROMINENCES[view].has(field.prominence);\n}\n\nexport function buildSdkSettingsPayloadForView(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  dirty: SettingsDirtyState,\n  view: SettingsView,\n): SdkSettingsPayload {\n  const payload = buildSdkSettingsPayload(schema, values, dirty) as Record<\n    string,\n    unknown\n  >;\n\n  for (const field of getSchemaFields(schema)) {\n    if (!isFieldVisibleInView(field, view)) {\n      setDotted(payload, field.key, field.default ?? null);\n    }\n  }\n\n  return payload as SdkSettingsPayload;\n}\n\n/** Return sections with fields filtered for the current view tier.\n *  Specially-rendered fields are excluded from the generic list. */\nexport function getVisibleSettingsSections(\n  schema: SettingsSchema,\n  values: SettingsFormValues,\n  view: SettingsView,\n  excludeKeys: Set<string> = SPECIALLY_RENDERED_KEYS,\n): SettingsSectionSchema[] {\n  if (!isValidSettingsSchema(schema)) return [];\n  return schema.sections\n    .map((section) => ({\n      ...section,\n      fields: section.fields.filter(\n        (field) =>\n          !excludeKeys.has(field.key) &&\n          isFieldVisibleInView(field, view) &&\n          isSettingsFieldVisible(field, values),\n      ),\n    }))\n    .filter((section) => section.fields.length > 0);\n}\n\n/** Whether the schema has any fields visible in the \"advanced\" tier. */\nexport function hasAdvancedSettings(schema: SettingsSchema | null): boolean {\n  if (!schema) return false;\n  return getSchemaFields(schema).some((f) => f.prominence === \"major\");\n}\n\n/** Whether the schema has any \"minor\" prominence fields. */\nexport function hasMinorSettings(schema: SettingsSchema | null): boolean {\n  if (!schema) return false;\n  return getSchemaFields(schema).some((f) => f.prominence === \"minor\");\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/agent-canvas",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0-beta.2",
   "description": "Agent Canvas UI for OpenHands - run AI coding agents with a visual interface",
   "license": "MIT",
   "private": false,

package/scripts/dev-safe.mjs

@@ -42,7 +42,6 @@ const LOCAL_AGENT_SERVER_SUBDIRS = [
   "openhands-tools",
   "openhands-workspace",
 ];
-const DEFAULT_SECRET_KEY = SHARED_DEFAULTS.defaults.secretKey;
 const DEFAULT_AGENT_SERVER_VERSION = SHARED_DEFAULTS.versions.agentServer;
 const FRONTEND_REQUIRED_BINS = ["cross-env", "react-router"];
 
@@ -54,20 +53,36 @@ export function generateRandomApiKey() {
   return randomBytes(32).toString("hex");
 }
 
-// Where the auto-generated default session API key is persisted so it stays
-// stable across `npm run dev` restarts. Keeping the key stable means the value
-// baked into the frontend (VITE_SESSION_API_KEY) and the persisted
-// backend-registry entry (`openhands-backends` localStorage) stay in sync
-// without users needing to set anything in `.env`.
+// Where the auto-generated API key is persisted so it stays stable across
+// `npm run dev` restarts. Keeping the key stable means the value baked into
+// the frontend (VITE_SESSION_API_KEY) and the persisted backend-registry entry
+// (`openhands-backends` localStorage) stay in sync without users needing to
+// set anything in `.env`.
 //
 // To rotate the key, delete this file. To pin a key explicitly, export
-// SESSION_API_KEY (or OH_SESSION_API_KEYS_0 / VITE_SESSION_API_KEY) -- those
-// take precedence over the persisted file.
-export const DEFAULT_SESSION_API_KEY_PATH = path.join(
+// LOCAL_BACKEND_API_KEY — it takes precedence over the persisted file.
+export const DEFAULT_API_KEY_PATH = path.join(
   homedir(),
   ".openhands",
   "agent-canvas",
-  "session-api-key.txt",
+  "api-key.txt",
+);
+
+/** @deprecated Use DEFAULT_API_KEY_PATH */
+export const DEFAULT_SESSION_API_KEY_PATH = DEFAULT_API_KEY_PATH;
+
+// Where the OH_SECRET_KEY is persisted so dev mode and Docker mode share the
+// same encryption key when both use ~/.openhands as their state directory.
+// docker/entrypoint.sh reads and writes this same file, so whichever mode runs
+// first generates the key and the other picks it up automatically.
+//
+// To rotate the key, delete this file and restart both modes. To pin a key
+// explicitly, export OH_SECRET_KEY — that takes precedence over the file.
+export const DEFAULT_SECRET_KEY_PATH = path.join(
+  homedir(),
+  ".openhands",
+  "agent-canvas",
+  "secret-key.txt",
 );
 
 // Cache so repeated lookups within a single process return the same key,
@@ -75,22 +90,29 @@ export const DEFAULT_SESSION_API_KEY_PATH = path.join(
 const persistedApiKeyCache = new Map();
 
 /**
- * Load the persisted default session API key, generating + persisting one if
- * the file doesn't exist yet.
+ * Load the persisted default API key, generating + persisting one if the file
+ * doesn't exist yet.
  *
  * Best-effort: if the file can't be written (e.g. read-only home dir), we
  * fall back to an in-memory key for this process so dev still works -- the
  * key just won't survive a restart.
  *
  * @param {string} filePath - Where to read/write the key.
- * @returns {string} The (hex) session API key.
+ * @returns {string} The (hex) API key.
  */
-export function getOrCreatePersistedSessionApiKey(
-  filePath = DEFAULT_SESSION_API_KEY_PATH,
+export function getOrCreatePersistedApiKeyFile(
+  filePath = DEFAULT_API_KEY_PATH,
 ) {
   return getOrCreatePersistedApiKey(filePath, "session");
 }
 
+/** @deprecated Use getOrCreatePersistedApiKeyFile */
+export function getOrCreatePersistedSessionApiKey(
+  filePath = DEFAULT_API_KEY_PATH,
+) {
+  return getOrCreatePersistedApiKeyFile(filePath);
+}
+
 /**
  * Load a persisted default API key, generating + persisting one if the file
  * doesn't exist yet.
@@ -568,26 +590,26 @@ function buildConfigFromPorts(ports, cwd, env) {
   );
   const conversationsPath = path.join(stateDir, "conversations");
   const workspacesPath = path.join(stateDir, "workspaces");
-  // Use provided secret key or default for local development
-  const secretKey = env.OH_SECRET_KEY || DEFAULT_SECRET_KEY;
-  // Use provided session API key or fall back to a key persisted to
-  // ~/.openhands/agent-canvas/session-api-key.txt. Persisting on disk keeps
-  // the agent-server, the Vite-baked VITE_SESSION_API_KEY, and any
+  // Use provided secret key, or read/generate one persisted to
+  // ~/.openhands/agent-canvas/secret-key.txt. Persisting ensures dev mode
+  // and Docker mode share the same encryption key when they mount the same
+  // ~/.openhands directory (docker/entrypoint.sh reads/writes the same file).
+  const secretKeyPath =
+    env.OH_SECRET_KEY_PATH || DEFAULT_SECRET_KEY_PATH;
+  const secretKey =
+    env.OH_SECRET_KEY || getOrCreatePersistedApiKey(secretKeyPath, "secret");
+  // Use the user-provided LOCAL_BACKEND_API_KEY or fall back to a key
+  // persisted to ~/.openhands/agent-canvas/api-key.txt. Persisting on disk
+  // keeps the agent-server, the Vite-baked VITE_SESSION_API_KEY, and any
   // `openhands-backends` localStorage entries the frontend has cached all
   // pointing at the same value across dev restarts.
   //
-  // Check multiple env vars that may be used:
-  // - SESSION_API_KEY: Common name
-  // - OH_SESSION_API_KEYS_0: Used by agent-server V1 config
-  // - VITE_SESSION_API_KEY: Used by frontend config
+  // LOCAL_BACKEND_API_KEY is the single user-facing env var for the API key.
   // OH_SESSION_API_KEY_PATH overrides the persisted file path (used by tests).
-  const persistedKeyPath =
-    env.OH_SESSION_API_KEY_PATH || DEFAULT_SESSION_API_KEY_PATH;
+  const persistedKeyPath = env.OH_SESSION_API_KEY_PATH || DEFAULT_API_KEY_PATH;
   const sessionApiKey =
-    env.SESSION_API_KEY ||
-    env.OH_SESSION_API_KEYS_0 ||
-    env.VITE_SESSION_API_KEY ||
-    getOrCreatePersistedSessionApiKey(persistedKeyPath);
+    env.LOCAL_BACKEND_API_KEY ||
+    getOrCreatePersistedApiKeyFile(persistedKeyPath);
 
   // Host directory containing Agent-Canvas-specific Python tools (e.g. the
   // canvas_ui tool). Added to OH_EXTRA_PYTHON_PATH below so the agent-server
@@ -899,16 +921,13 @@ async function main() {
 
   const secretKeySource = process.env.OH_SECRET_KEY
     ? "custom (from OH_SECRET_KEY)"
-    : "default (for local development)";
-
-  const sessionKeySource =
-    process.env.SESSION_API_KEY ||
-    process.env.OH_SESSION_API_KEYS_0 ||
-    process.env.VITE_SESSION_API_KEY
-      ? "custom (from env)"
-      : `persisted (${
-          process.env.OH_SESSION_API_KEY_PATH || DEFAULT_SESSION_API_KEY_PATH
-        })`;
+    : `persisted (${process.env.OH_SECRET_KEY_PATH || DEFAULT_SECRET_KEY_PATH})`;
+
+  const sessionKeySource = process.env.LOCAL_BACKEND_API_KEY
+    ? "custom (from LOCAL_BACKEND_API_KEY)"
+    : `persisted (${
+        process.env.OH_SESSION_API_KEY_PATH || DEFAULT_API_KEY_PATH
+      })`;
 
   console.log(`- agent-server: ${agentServerCmd.source}`);
   console.log(`- backend: ${config.backendBaseUrl}`);

package/scripts/dev-static.mjs

@@ -388,9 +388,8 @@ function startStaticServer(config) {
       "0.0.0.0",
       "--port",
       String(config.vitePort),
-      // Inject the runtime session key so the pre-built frontend can
-      // authenticate to agent-server without VITE_SESSION_API_KEY being baked
-      // into the bundle at publish time.
+      // Inject the API key so the pre-built frontend can authenticate
+      // to the agent-server without a baked-in VITE_SESSION_API_KEY.
       ...(config.sessionApiKey
         ? ["--session-api-key", config.sessionApiKey]
         : []),