Skip to content

Embedded iOS configuration

The iOS in-process runtime uses a maintained application configuration at:

application/python/agent_terminal_app/default_config/embedded-ios/config.json

This file owns the embedded providers, agents, plugin catalog, tool-family assignments, application plugins, mixins, and fixed Reviewer deployment settings. The mobile application does not construct a parallel agent graph.

The iOS preparation script copies the configuration into crystal_lattice_app.zip under the same agent_terminal_app package path. At runtime, the embedded adapter copies the raw JSON unchanged into the app's Application Support config directory and creates AgentApplication with a config-only placeholder environment. Placeholder values do not need to be installed in process-global os.environ.

The adjacent requirements.txt owns the fully pinned third-party dependency closure for this embedded application. Runtime preparation asks pip for platform-neutral py*-none-any wheels, validates that the installed staging tree contains no native extensions or development distributions, and archives the complete validated tree. Distribution names therefore do not need a second mapping to import-package names; for example, python-jsonpath automatically contributes the jsonpath package.

Placeholder ownership

The native settings bridge owns persisted user choices and supplies values for these categories:

  • workspace and application-data paths;
  • provider enabled/readiness state;
  • editable provider URLs and model ids;
  • OpenAI API versus ChatGPT mode;
  • API keys loaded from Keychain;
  • ChatGPT credential and rate-limit paths;
  • the bundled Reviewer CA path;
  • cost-tracking storage.

The Reviewer URL, model, provider, protocol, and tool family are literals in the maintained JSON. Global Settings exposes Show reviewer sample provider; Local provider settings exposes its independent enable switch and caller key.

The maintained and app-support JSON remain secret-free. API keys are resolved from the config-only placeholder map in memory. ChatGPT credentials remain in their plugin-owned file under the app-support auth directory.

Agent availability

The JSON contains the complete supported topology. Agent entries use an enabled placeholder. AgentApplication filters false-like agent values (false, 0, no, off, or an empty value) while loading configuration and does not forward the control key into provider configuration.

This keeps topology reviewable while allowing native settings to make incomplete profiles unavailable. Reviewer availability additionally requires the global Reviewer toggle. Fresh settings hide and disable the profile. First global opt-in activates it, so entering the caller key completes the two-step setup. A native preference records that activation; later hide/show operations preserve an explicitly disabled provider.

Default-plugin parity

The embedded runtime includes these ordinary default-config capabilities:

Capability Embedded status
System message Included
Request options Included
Timestamp and duration Included
ChatGPT authentication Included
Session actions, title, search, status, pinning, archive, ordering, metadata, and attachments Included
Summarize range Included
Rebuild native history Included
Cost tracking Included
Per-session working directory Included; existing descendants of the fixed app workspace
OpenAI Responses native web search Included for direct OpenAI and Reviewer
OpenRouter native web search Included
OpenAI Responses image attachments Included in inline-image mode; Files API/PDF upload is unavailable on the requests transport
OpenRouter image attachments Included
OpenAI Flex, Fast mode, prompt caching, and verbosity Included where the provider/model and API authentication mode support them
OpenAI native compaction Excluded; it imports the OpenAI SDK, which is outside the requests-only iOS dependency set
File context Deferred; GitPython dependency and mobile file-context UX require review
Provider-neutral Tavily search Deferred; native search currently covers only OpenAI Responses and OpenRouter
Web context Deferred; trafilatura dependency overlaps later Tavily work
MCP runtime Deferred until an embedded MCP runtime is approved
Cloud agent Excluded from the on-device runtime
Application-config dotenv editing Excluded; native settings and Keychain own embedded credentials

Direct OpenAI receives auth_mode_options: ["api", "chatgpt"]; Reviewer receives an empty list and remains API-only. Local provider settings chooses the direct OpenAI default. Session Settings can override it independently, and resetting the override restores the current provider default.

The OpenAI card always exposes its API-key field and plugin-driven ChatGPT account actions independently of the default. Account actions do not change that default. Global Settings writes only Reviewer exposure, while the provider form writes provider values; neither rewrites the legacy default-agent preference.

Flex and Fast service-tier controls are hidden when the embedded OpenAI profile uses ChatGPT authentication. They are also hidden for Reviewer so its fixed proxy pricing and daily budget cannot be changed by a session control.

Workspace and working directory

workspace_root is the fixed app-owned filesystem authorization boundary. working_directory is the session-specific directory used to resolve relative file-tool paths. The embedded workspace package contributes a workspace control whose value is an opaque workspace_id, plus plugin-driven action buttons for creating private/shared workspaces and selecting a folder from iOS Files.

Known choices are classified as:

  • private directories under the current session's app-owned area;
  • shared directories under the fixed app workspace; and
  • native-host-authorized external directories represented by opaque grant IDs.

The native host stores and restores security-scoped bookmarks and injects only active grant IDs, display names, and resolved authorized roots into the embedded runtime. Session metadata stores workspace_id and the canonical effective working_directory, never a bookmark. Direct path updates remain limited to the app workspace; an external path is accepted only when derived from an active registered grant.

Both Claude-like and Codex-like tools use the selected working directory as their immediate root. The shared resolver accepts the fixed app root plus active external grants as authorization boundaries, while still rejecting parent traversal, sibling access, symlink escape, missing directories, and unregistered external paths.

Verification

Relevant boundaries include:

pytest application/python/tests/test_embedded_ios_default_config.py -q
pytest mobile/crystal-lattice-control-rn/python_tests -q
npm run build:ios:embedded-providers:bundle
npm run test:ios:embedded-runtime:bundle
npm run test:ios:embedded-providers:bundle
npm --prefix mobile/crystal-lattice-control-rn run detox:build:ios

Archive verification must confirm that the configuration and included plugin packages are imported from crystal_lattice_app.zip, without repository or development-dependency fallback. The embedded-application smoke additionally imports agent_app and its dependency closure from the ZIP and executes a credential-free ChatGPT status action through the bundled application layer.