@openhands/agent-canvas 1.0.0-alpha.8 → 1.0.0-beta.1

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.8",
+  "version": "1.0.0-beta.1",
   "description": "Agent Canvas UI for OpenHands - run AI coding agents with a visual interface",
   "license": "MIT",
   "private": false,
@@ -23,8 +23,8 @@
     "@heroui/react": "2.8.10",
     "@microlink/react-json-view": "1.31.20",
     "@monaco-editor/react": "4.7.0",
-    "@openhands/extensions": "git+https://github.com/OpenHands/extensions.git#39711065f53166c52608462f60a4c8507253ce56",
-    "@openhands/typescript-client": "1.24.0",
+    "@openhands/extensions": "git+https://github.com/OpenHands/extensions.git#e14f740c59b4bfd7369d4bb6aea5eeb33dd05909",
+    "@openhands/typescript-client": "1.24.3",
     "@react-router/node": "7.14.2",
     "@react-router/serve": "7.14.2",
     "@tailwindcss/vite": "4.2.4",

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.
@@ -210,6 +232,36 @@ function tryPort(port, host = "127.0.0.1") {
   });
 }
 
+/**
+ * Assert that all listed ports are available, throwing a descriptive error if
+ * any are already in use.
+ *
+ * Intended as a pre-flight check before spawning services so that a concurrent
+ * agent-canvas instance is detected immediately rather than silently starting
+ * on a different port.
+ *
+ * @param {Array<{name: string, port: number}>} portConfigs - Named port list
+ * @param {string} [host]
+ */
+export async function assertPortsFree(portConfigs, host = "127.0.0.1") {
+  const results = await Promise.all(
+    portConfigs.map(async ({ name, port }) => ({
+      name,
+      port,
+      free: await tryPort(port, host),
+    })),
+  );
+  const busy = results.filter(({ free }) => !free);
+  if (busy.length === 0) return;
+
+  const lines = busy.map(({ name, port }) => `   • ${name}: port ${port}`).join("\n");
+  throw new Error(
+    `Cannot start: the following ports are already in use:\n\n${lines}\n\n` +
+      `Another agent-canvas instance may already be running.\n` +
+      `Stop it first, or override the port via environment variables (e.g. PORT=<other>).`,
+  );
+}
+
 /**
  * Find multiple free ports at once, each preferring its specified default.
  *
@@ -491,26 +543,14 @@ export async function buildSafeDevConfigAsync(
     preferredBackendPort + 1,
   );
 
-  // Find available ports, preferring the defaults
-  const ports = await findFreePorts([
-    { name: "backend", preferred: preferredBackendPort },
-    { name: "vscode", preferred: preferredVscodePort },
+  // Fail fast if any required port is already in use.
+  await assertPortsFree([
+    { name: "agent-server", port: preferredBackendPort },
+    { name: "vscode", port: preferredVscodePort },
   ]);
 
-  // Log if we're using non-default ports
-  if (ports.backend !== preferredBackendPort) {
-    console.log(
-      `  ℹ Port ${preferredBackendPort} busy, using ${ports.backend} for agent-server`,
-    );
-  }
-  if (ports.vscode !== preferredVscodePort) {
-    console.log(
-      `  ℹ Port ${preferredVscodePort} busy, using ${ports.vscode} for vscode`,
-    );
-  }
-
   return buildConfigFromPorts(
-    { backendPort: ports.backend, vscodePort: ports.vscode },
+    { backendPort: preferredBackendPort, vscodePort: preferredVscodePort },
     cwd,
     env,
   );
@@ -550,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
@@ -881,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]
         : []),