Skip to main content

Deploy the optional Complexity custom runtime

Deploy native Complexity views with COMPLEXITY_CUSTOM_RUNTIME_ENABLED=0 unless the target host passes the custom-runtime containment checks. The root Compose configuration defaults to 0.

Release requirements​

Use Linux x86_64 with glibc, Python 3.10 or newer, and libseccomp.so.2. The accepted library versions are exactly 2.5.4 and 2.5.5 with their matching packaged policy hashes. Other versions or failed kernel checks leave the capability unavailable.

Follow backend preparation in the selected release environment. The normal pnpm build copies runtime assets only. Run pnpm complexity:runtime:prepare explicitly to create dist/lib/complexity/custom-runtime/python/.

The preparation command uses the vendored, hash-checked wheel without downloads. Do not replace the wheel, policy, or manifest to bypass a failed check. A normal shared backend build must work without optional Python preparation.

For a pinned-source deployment, follow the reviewed-source release procedure. Prepare the same source and target environment that the service will use. A restart alone does not rebuild artifacts or prepare Python.

Activation and fallback​

After the host containment checks pass, configure COMPLEXITY_CUSTOM_RUNTIME_ENABLED=1 for the selected deployment. ComplexityService first probes v1 against the current kernel at startup. After v1 succeeds, it probes v2 secret-completion updates. A successful v2 probe enables v2 authoring with secretCompletion. An unavailable v2 probe retains v1 authoring without trusted secret entry. Existing v1 outputs still use the exact v1 package.

The backend checks the packaged assets, accepted policy, unprivileged child identity, restricted system calls, and actual kernel process state. Successful asset copying or Python preparation alone does not enable authoring.

If the runtime is disabled or unavailable, native versions 1–3 remain supported. Custom views show readable fallback content and host status instead of executing generated browser code. Keep unrelated services and application data intact during a scoped release.

What users can do​

Custom views use version 4 of the existing displayOpenUI tool. They keep the existing tool grants and permissions. There is no separate permission shortcut for custom source.

Users can interact with approved controls and save declared, nonsecret values for the exact output revision. Mount, reload, and preview do not save values. A save checks the expected state version before it writes, so another window cannot silently overwrite newer values.

Saved values remain available after reload. They use the chat’s protected-history storage and encryption policy. They do not automatically enter a model request.

Runtime v2 can show trusted secret fields outside the generated tree. Mark as provided discards the value and sends only an unverified completion boolean. There is no vault, credential verification, secret consumer, or permission grant. The session lasts at most 60 seconds. Lock, close, reload, and reconnect clear entry and completion status. Runtime v1 reports secret entry as unavailable.

Open mail can appear only when an approved, ready host implementation advertises it for the completed view. Its trusted button belongs outside the guest tree. Generated custom buttons cannot execute mailbox actions. Create draft requires its separate host gate, the action ledger, and current tool and mailbox authorization. ComplexityService enables that host gate at startup. A normal canonical save needs no extra approval. Review-required proposals use trusted host Apply/cancel with version-bound baseline checks.

Read custom-view controls for preview, retry, source copying, and saved-value behavior. Read runtime limits for resource ceilings.

Host-action ledger​

The ledger supports persistent Open mail and Create draft intents, status recovery, and proposal review. Custom-view activation alone does not enable mailbox writes. ComplexityService enables the separate draft gate at startup, but draft capabilities also require this table and current authorization.

Preserve the existing database

The ledger SQL is additive, but its presence changes the openMail path to persistent intent tracking. Complete the safety review of that path before applying SQL. Preserve existing tables, data, model names, @map/@@map mappings, and foreign-key actions in both Prisma schemas. Do not use prisma db pull, a reset, or data-loss flags to synchronize these schemas.

Apply the additive SQL​

Use the approved database connection for the selected instance. The existing complexity.chats and complexity.messages tables must exist.

  1. Check whether complexity.ui_action_intents already exists with this read-only query:

    SELECT to_regclass('complexity.ui_action_intents');

  2. If the table is absent, apply mailGen/ECS_MovePST_To_TempSQL/DB_Lib/Sql/20261021_complexity_ui_actions.sql through the approved database client.

  3. Check the new table, constraints, and indexes against that SQL file.

  4. Check that the existing tables and foreign keys remain intact.

The SQL creates the intent table, its chat/message foreign keys, and its indexes. It does not alter existing tables. The file is not idempotent. If the table already exists or application fails, inspect the database state before another attempt. Do not drop the table to retry.

The ledger stores encrypted action requests and results. Its status, ownership, revision, and operation identifiers support authorization and reconciliation. Table presence alone does not prove that the action implementation is ready.

Validate and generate both Prisma clients​

Use the dependencies and database configuration already prepared for each application. From mailGen/msmicroservices-architexture/, run:

pnpm exec prisma validate --schema src/prisma/schema.prisma
pnpm exec prisma generate --schema src/prisma/schema.prisma

From mailGen/bff/apps/web/, run:

pnpm exec prisma validate --schema prisma/schema.prisma
pnpm exec prisma generate --schema prisma/schema.prisma

Both schemas map ComplexityUiActionIntent to complexity.ui_action_intents, with camelCase fields mapped to snake_case columns. Keep their table, column, key, and relation mappings aligned. Schema validation and client generation do not apply the SQL or prove database preservation.

Before release, compare the schema change against the existing schema offline. Stop if it removes an existing table or changes an existing mapping or foreign-key action. Client generation is preparation, not activation. Use the approved scoped release procedure for rebuilt services.

See draft-gate and missing-table behavior. configureUiDraftActions(true) enables the host gate. It does not replace ledger readiness, current grants, or mailbox checks. configureUiDraftActions(false) disables draft capabilities. Authenticated recovery reads the existing intent for the exact output and action, including from another tab. Recovery never reruns the writer.