docs: consolidate agent operating guidance
This commit is contained in:
Codex
@@ -1,6 +1,6 @@
|
||||
# Master Server Ops
|
||||
|
||||
This document records master-server architecture and decision rules. **Operations commands (Moon Bridge management, profile smoke tests, MiniMax session recovery) have moved to the `unidesk-ops` skill** (`~/.agents/skills/unidesk-ops/SKILL.md`). Do not place secrets, one-off incident logs, or dated changelog notes here.
|
||||
This document records master-server architecture and decision rules. Installed Codex wrappers own their command syntax; this reference owns profile boundaries, safety rules and acceptance criteria. General server lifecycle and GC commands remain in the `unidesk-ops` skill. Do not place secrets, one-off incident logs, or dated changelog notes here.
|
||||
|
||||
## Execution Boundary
|
||||
|
||||
@@ -10,7 +10,7 @@ This document records master-server architecture and decision rules. **Operation
|
||||
|
||||
## Codex Provider Profiles
|
||||
|
||||
`dscx`, `mxcx`, and `acx` are local Codex profile wrappers under `/root/.local/bin/`. They are host-level tools, not UniDesk service code. `acx` is the unified multi-model entry; `gocx` remains the OpenCode Zen Go compatibility entry, and older single-model `dscx-go`, `dfcx-go`, and `glcx-go` wrappers are compatibility entries. Usage commands are in `unidesk-ops` skill.
|
||||
`mycx` and `oncx` are stable system Codex wrappers under `/usr/local/bin/`; both use the default `/root/.codex` home and are described in the shared-state subsection below. `dscx`, `mxcx`, and `acx` are isolated local Codex profile wrappers under `/root/.local/bin/`. They are host-level tools, not UniDesk service code. `acx` is the unified multi-model entry; `gocx` remains the OpenCode Zen Go compatibility entry, and older single-model `dscx-go`, `dfcx-go`, and `glcx-go` wrappers are compatibility entries.
|
||||
|
||||
- `dscx` uses `CODEX_HOME=/root/.codex-deepseek-v4-pro`, model `deepseek-v4-pro`, Codex custom provider `deepseek`, and local Moon Bridge at `http://127.0.0.1:38440/v1`.
|
||||
- `mxcx` uses `CODEX_HOME=/root/.codex-minimax-m3`, model `MiniMax-M3`, Codex custom provider `minimax`, and local Moon Bridge at `http://127.0.0.1:38441/v1`.
|
||||
@@ -22,7 +22,7 @@ This document records master-server architecture and decision rules. **Operation
|
||||
- `acx` includes all OpenCode Zen Go upstream slugs plus `gpt-5.5-only` and `gpt-5.5-sub2api` in one `model-catalog.json` so Codex can use `/model` or `-m <model>` within the same profile.
|
||||
- `acx` routes OpenCode Zen Go models to the existing `gocx` Moon Bridge. GPT models must not pass through Moon Bridge or the ACX router: `gpt-5.5-only` uses the direct `only` OpenAI-compatible Responses endpoint and `gpt-5.5-sub2api` uses the Sub2API pool endpoint, both with upstream model `gpt-5.5`.
|
||||
- GPT direct providers must receive their API key through an environment-key path such as `ACX_GPT_DIRECT_API_KEY`, read from the matching `/root/.codex/auth.json.<profile>` file by the wrapper. Do not let direct GPT calls fall back to `/root/.codex-acx/auth.json`; that file may contain only the local-router dummy key.
|
||||
- All wrappers read upstream API keys from profile auth files or wrapper-injected environment variables; generated Moon Bridge or router runtime configs live under the profile `.tmp/` directory with mode `0600`. Do not copy upstream keys into documentation.
|
||||
- Isolated Moon Bridge and router wrappers read upstream API keys from profile auth files or, where the compatibility path still requires it, wrapper-injected environment variables; generated runtime configs live under the profile `.tmp/` directory with mode `0600`. This compatibility rule does not apply to `mycx` Pika auth, whose command-backed contract is defined below. Do not copy upstream keys into documentation.
|
||||
- Each profile must include `model_catalog_json` in `config.toml` pointing to a profile-local `model-catalog.json` entry for its active model. Missing catalog metadata causes Codex to fall back to default metadata, which lowers the effective context window and prints `Model metadata ... not found`.
|
||||
- Profile context metadata must match the intended upstream limit closely enough for Codex auto-compact to fire before provider rejection. Keep the local profile metadata in sync with the actual model family you are routing to.
|
||||
- Current master-server profile baselines:
|
||||
@@ -32,9 +32,43 @@ This document records master-server architecture and decision rules. **Operation
|
||||
- Keep the wrapper-generated Moon Bridge/router metadata aligned with the profile `config.toml` and `model-catalog.json`. If these diverge, Codex and the local admission layer may disagree about compaction and request size behavior.
|
||||
- `hyueapi.com` / `.hyueapi.com` must remain in `NO_PROXY` / `no_proxy` for Codex API channels.
|
||||
|
||||
### Shared CODEX_HOME Wrappers (`mycx` / `oncx`)
|
||||
|
||||
`mycx` and `oncx` reuse the same system `codex` binary and the same `/root/.codex` state tree. Their stable entrypoints are native executable wrappers, not shell functions:
|
||||
|
||||
- `/usr/local/bin/mycx` selects profile `pika`; its writable profile layer is `/root/.codex/pika.config.toml`.
|
||||
- `/usr/local/bin/oncx` selects profile `only`; its writable profile layer is `/root/.codex/only.config.toml`.
|
||||
- `/root/.codex/config.toml` is the shared base layer, while `/root/.codex/state_5.sqlite` and `/root/.codex/sessions/**/rollout-*.jsonl` hold the shared session index and durable transcripts.
|
||||
- The Webterm declaration in `config/platform-infra/webterm.yaml` starts `mycx`; wrapper path or startup changes must preserve that original entrypoint and include a Webterm launch check.
|
||||
- `codex-pool configure-local` owns only the unsuffixed shared `config.toml` and `auth.json` consumer files described in `docs/reference/platform-infra.md`. It does not own the profile-v2 `pika.config.toml`, `only.config.toml`, or `auth.json.pika` files and must not regenerate them as Sub2API consumer state.
|
||||
- Shell startup files must not define same-name functions that shadow these executables or regenerate profile files on launch. After changing a wrapper, existing Codex processes must be exited and existing shells must clear stale functions or start a new shell before validation.
|
||||
|
||||
For profile-v2, `/model` persists `model` and reasoning effort to the active profile file. The two wrappers therefore remember their last selections independently. `-m` and `-c model...` / `-c model_reasoning_effort...` are runtime overrides and must not be treated as persistent model selection. A fresh same-profile restart, a switch between profiles, and resuming an existing session are distinct behaviors and must be diagnosed separately.
|
||||
|
||||
Session discovery has an additional identity boundary:
|
||||
|
||||
- Sharing `CODEX_HOME` does not guarantee identical `/resume` results. The picker also filters by the effective provider ID and by cwd, source, and archive state.
|
||||
- Provider IDs are persisted, case-sensitive session bucket keys. The active wrappers use distinct provider identities, and historical sessions can retain earlier capitalization or provider names.
|
||||
- In the deployed picker behavior, `--all` removes the cwd restriction but does not remove the provider restriction. Revalidate this contract after Codex upgrades before changing wrappers or migrating history.
|
||||
- Resume uses the current profile's effective model, provider, and reasoning overrides; it does not necessarily restore the model last recorded by the selected session. Fresh model persistence and session-model restoration must therefore have separate acceptance criteria.
|
||||
- Rollout JSONL is durable history and can repopulate the SQLite index. Never change only `state_5.sqlite` to merge provider buckets. A reviewed history migration must stop active Codex processes, update rollout metadata with a structured JSON parser, update the SQLite index transactionally, preserve provenance, and verify the same session ID set after reindexing.
|
||||
|
||||
Provider identity is a compatibility contract. Any change to `CODEX_HOME`, profile name, provider ID, or provider-ID capitalization must preflight existing history and warn or block when it would create a new hidden bucket. Do not make different real backends impersonate one provider solely to merge picker lists. The preferred future unification is a picker policy with explicit `current`, `all`, or configured aliases, visible origin-provider metadata, and an explicit continue/fork decision for cross-provider resume.
|
||||
|
||||
Pika authentication must use command-backed provider auth from `[model_providers.Pika.auth]`, with the credential source `/root/.codex/auth.json.pika` restricted to mode `0600`. Do not export the Pika API key into the wrapper or Codex environment: inherited environment variables can be captured by shell snapshots and propagated to child tools. Shell snapshots must also be restricted to mode `0600` and must not contain reusable credentials. Treat any plaintext snapshot occurrence as credential exposure, remove the copy, and rotate the credential.
|
||||
|
||||
Diagnostics and validation must remain secret-safe:
|
||||
|
||||
- Report only effective `CODEX_HOME`, wrapper path, active profile file, provider ID, model/reasoning, session counts by provider, credential presence or fingerprint, and relevant file modes.
|
||||
- Verify each profile by selecting a non-baseline `/model`, exiting, fresh-starting the same wrapper, and confirming the selection remains while the other profile file is unchanged.
|
||||
- Verify a temporary CLI override does not rewrite the profile, and verify Pika command-backed auth works with the corresponding API-key environment variable absent.
|
||||
- When `/resume` differs, compare `CODEX_HOME`, provider ID, cwd, source, and archive filters before attributing the result to storage loss or caching.
|
||||
|
||||
The investigation evidence and source-level rationale for these rules are retained in [UniDesk issue #1640](https://github.com/pikasTech/unidesk/issues/1640); this document is the authority for the active long-term contract.
|
||||
|
||||
## Moon Bridge
|
||||
|
||||
Moon Bridge is installed as `/root/.local/bin/moonbridge`. The binary exposes OpenAI Responses endpoints and bridges Codex to provider-specific upstream APIs. Operations commands are in `unidesk-ops` skill.
|
||||
Moon Bridge is installed as `/root/.local/bin/moonbridge`. The binary exposes OpenAI Responses endpoints and bridges Codex to provider-specific upstream APIs. The installed profile wrappers own bridge command syntax; this section records the supported runtime behavior.
|
||||
|
||||
The local source copy for the installed patched build is `/root/src/moon-bridge-sanitize`. When changing Moon Bridge, keep the change narrow, run package-level tests, build a replacement binary, back up the previous binary, then restart affected profile bridges. Default master-server build restrictions still apply.
|
||||
|
||||
@@ -77,7 +111,7 @@ Sanitizer rules: recursively scans `ResponsesRequest.input`, repairs tool-call `
|
||||
|
||||
## MiniMax Session Recovery
|
||||
|
||||
`mxcx` includes a cleanup and guard layer for corrupted MiniMax-backed session JSONL. **Recovery operations commands are in `unidesk-ops` skill.** This section only documents behavioral rules.
|
||||
`mxcx` includes a cleanup and guard layer for corrupted MiniMax-backed session JSONL. The wrapper owns recovery command syntax; this section documents behavioral rules.
|
||||
|
||||
- `mxcx resume` auto-runs `session-clean` + `session-guard` before invoking Codex. Uses `CODEX_HOME=/root/.codex-minimax-m3` profile.
|
||||
- `session-clean` is strictly scoped to invalid tool-call `arguments`: malformed JSON, MiniMax sentinel text, and schema-invalid cases. Must preserve line order, non-tool messages, reasoning, outputs, token records, and session metadata. Must not compact/summarize/truncate/reorder transcript.
|
||||
|
||||
Reference in New Issue
Block a user