Skip to content

feat(config): persist zero data retention in settings.json - #227

Open
Trex-Hub wants to merge 5 commits into
patlux:mainfrom
Trex-Hub:feat/zdr-settings
Open

Trex-Hub wants to merge 5 commits into
patlux:mainfrom
Trex-Hub:feat/zdr-settings

Conversation

@Trex-Hub

Copy link
Copy Markdown

What

Makes the zero-data-retention opt-in configurable without a process restart, and visible.

ZDR was environment-only (CMD_ZDR=1 / COMMANDCODE_ZDR=1) and read once while the extension registered its models, so:

  • enabling it meant exporting a variable before starting the host,
  • disabling it meant restarting the host,
  • and no command reported which state was active.

How it resolves

  1. CMD_ZDR=1 (documented) or COMMANDCODE_ZDR=1 (legacy alias) — wins, so a shell export cannot be weakened by a settings file.
  2. { "commandcode": { "enableZDR": true } } in the agent settings.json (~/.pi/agent/settings.json for pi).
  3. Otherwise off.

Only a literal true counts, so a typo cannot silently weaken privacy. /commandcode-status and /commandcode-diagnostics now print the effective state and its source.

/commandcode-zdr [on|off]

  • No argument: reports the effective state and source.
  • on / off: writes commandcode.enableZDR into the agent settings.json, preserving every other key. A malformed or non-object file is refused rather than overwritten.
  • off while CMD_ZDR/COMMANDCODE_ZDR is set is refused with an explanation, because the environment wins.
  • The provider is re-registered afterwards, the same path /commandcode-refresh uses, so the header changes on the next request and pi re-resolves the current model (_refreshCurrentModelFromRegistry).

Two host details that shaped this

  • pi.getSettings() is not readable while extensions load (getSettings: notInitialized in the loader). The state therefore starts from the environment, which is readable at load, and is completed on session_start. A state change re-registers the provider.
  • ModelRuntime.registerProvider merges a re-registration over the previous registration and preserves undefined values. createProviderConfig now always registers a headers object (headers ?? {}); otherwise turning ZDR off would keep the previously registered x-cmd-zdr header. Model-level headers follow the same rule, so {} is what clears it.

Settings written externally still apply only after /reload or a restart, consistent with how the host reloads settings.

Tests

  • tests/test-zdr.ts (new, wired into test and test:unit plus a test:zdr script): env parsing, true-only settings, environment precedence, header/description, and the writer — preserving unrelated keys, creating a missing agent directory, 0600 mode, and refusing malformed or non-object files without modifying them.
  • tests/test-pi-local.mjs: real pi against the mock API — with CMD_ZDR unset, settings.json alone sends x-cmd-zdr: 1; with neither opt-in the header is absent; the RPC command list includes commandcode-zdr.
  • Checks run: npm run typecheck, npm run test:unit, node tests/test-pi-local.mjs, node tests/test-pi-isolated.mjs, node tests/test-pi-authenticated.mjs, node tests/test-endpoint-routing.mjs, node tests/test-host-protocols.mjs, the node --test release/maintenance/host-helper batch, npm run typecheck:entrypoint against installed pi 1.5.2, npm run format:check, git diff --check. OMP tests skip locally (no omp binary) and rely on CI.

ZDR was environment-only and read once at registration, so opting in needed
`CMD_ZDR=1` in the host's environment and opting back out needed a restart.
Nothing in the host surfaced which state was active.

- `commandcode.enableZDR: true` in the agent `settings.json` now opts in. The
  documented `CMD_ZDR`/`COMMANDCODE_ZDR` variables keep precedence so a shell
  export cannot be weakened by a file, and only a literal `true` counts.
- `/commandcode-zdr [on|off]` reports the effective state and writes the key,
  preserving every other settings key. A malformed or non-object file is never
  overwritten, and `off` is refused while the environment forces ZDR on.
- Host settings are unreadable while extensions load, so the opt-in starts from
  the environment and is completed on `session_start`. A changed state
  re-registers the provider, which is the only way to change a registration
  header, so a toggle applies to the next request instead of the next restart.
- `createProviderConfig` now always registers a `headers` object
  (`headers ?? {}`): pi merges a re-registration over the previous one and
  preserves undefined values, so an absent object would keep sending a ZDR
  header after it is turned off.
- `/commandcode-status` and `/commandcode-diagnostics` report the state.

@pierreraby pierreraby left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this. I tested this exact head with Pi 1.5.2 and Oh My Pi 18.22.0 against a loopback mock. The existing test suite passes on both, and Pi adds/removes the header on the next request without a restart. I found three gaps in additional tests:

  1. OMP reports ZDR on while inference still sends no ZDR header. Unset both ZDR environment variables, start OMP with a Command Code model using Responses, run /commandcode-zdr on, then send a prompt. The command reports that the change applies to the next request, but the mock receives no x-cmd-zdr. After refreshing the host registry and reselecting the model, the header appears; /commandcode-zdr off then leaves it on the next request. Restarting with commandcode.enableZDR: true still on disk reports off and sends no header. In a fresh OMP home, I also observed the host migrate the initial settings.json to settings.json.bak and create config.yml. As a control, CMD_ZDR=1 sends the header on both hosts. Please make the command track the actual outgoing header and use a storage path the host can read back, or scope the persistent command to Pi and leave OMP on the existing env-only path. An RPC test should assert the next HTTP request after on and off, not just the notification.
  2. Quota keeps the startup header (index.ts:510–513, src/quota-command.ts:57). With no env opt-in, run /commandcode-zdr on, then /commandcode-quota: I observed /alpha/whoami without x-cmd-zdr, even on Pi where inference sends it. Please resolve the current header when the quota command runs.
  3. Saving replaces a symlinked settings.json (src/zdr.ts:109). With settings.json pointing to a managed settings file, the save replaces the symlink with a regular file and leaves the target unchanged. Please preserve the link by updating its target, or refuse the save without changing either file; a temp-directory test can cover this.

- limit /commandcode-zdr on|off to pi; other hosts keep the CMD_ZDR env opt-in
- resolve the ZDR header per /commandcode-quota run
- update a symlinked settings.json through its target, refuse dangling links
- test the next outgoing request after /commandcode-zdr on and off
@Trex-Hub
Trex-Hub requested a review from pierreraby November 18, 2026 15:13
@Trex-Hub

Copy link
Copy Markdown
Author

Thanks @pierreraby, all three points are addressed in 116c7cb.

  1. OMP / /commandcode-zdr: I took the "scope the persistent command to Pi" option. On a host without registerApiProvider (OMP), /commandcode-zdr on|off now refuses and points to CMD_ZDR=1, so OMP stays on the env-only path and never touches settings.json. Plain /commandcode-zdr still shows state. On Pi, a new RPC test in tests/test-pi-local.mjs asserts the x-cmd-zdr header on the next HTTP request after on and after off, not just the notification. I don't use OMP, so I couldn't test that. Please run those tests and let me know if it needs any changes.
  2. Quota header: registerCommandCodeQuota now accepts a headers function, resolved on each run, so /commandcode-quota sends the current x-cmd-zdr. Covered by a unit test in tests/test-quota-command.ts.
  3. Symlinked settings.json: the save now writes through the link to its target and keeps the symlink. A dangling link is refused with no changes. Both cases are tested in tests/test-zdr.ts.

Test limitation: the quota fix is only covered by that unit test. The mock Command Code server in tests/test-pi-local.mjs has no /alpha/whoami route, so there is no end-to-end check that the quota request carries x-cmd-zdr after /commandcode-zdr on. I can add a route and header assertion there if you'd like it in this PR.

@pierreraby

Copy link
Copy Markdown
Collaborator

Thanks — I retested 116c7cb on Pi 1.5.2 and OMP 18.22.0 against a loopback mock. All three original findings are resolved: OMP refuses persistent edits while keeping CMD_ZDR=1 working, Pi's quota request follows the current ZDR state in both directions, and a symlinked settings file keeps its link.

One remaining case on Pi: the command writes the global settings file, but startup reads the merged global and project settings through pi.getSettings(). I reproduced it with both ZDR env vars unset:

  1. In a trusted project, set {"commandcode":{"enableZDR":false}} in the project's .pi/settings.json.
  2. Run /commandcode-zdr on. The global settings now contain enableZDR: true, and the next inference request sends x-cmd-zdr: 1.
  3. Restart Pi in the same project. The global setting is still true, but the command reports off and the first inference request omits the header. Removing the project override restores the header after restart.

Could we read and write this global opt-in from the same agent settings file, keeping CMD_ZDR=1 and its legacy alias above it? A restart regression test with a conflicting trusted project setting would pin the behavior. The command should not promise that ZDR survives restart if the project can silently turn it off.

- read the same agent-directory settings.json the command writes instead of
  the host's merged global+project view, so a project override cannot turn the
  persisted opt-in off after restart
- treat a missing or malformed settings file as off during startup; the write
  path still refuses to overwrite it
- add a restart regression with a conflicting trusted project setting
- document that project .pi/settings.json is not consulted for this opt-in
@Trex-Hub

Copy link
Copy Markdown
Author

Thanks @pierreraby — fixed in 32e44e1.

Startup now reads the same file the command writes. applyHostZdr() no longer calls pi.getSettings() (merged global+project); it reads <agent-dir>/settings.json directly through a new loadZdrSettings(). Precedence stays CMD_ZDR / COMMANDCODE_ZDR (env, documented alias) above the agent settings file. A missing, unreadable or malformed agent file is treated as off at startup; /commandcode-zdr on|off still refuses to overwrite a malformed file and still writes through a settings.json symlink.

This also means a project .pi/settings.json can no longer turn the opt-in on, not just off. I documented that the agent-directory file owns this key. If you'd rather have a trusted project enable it (OR semantics) while never being able to disable it, say so and I'll add that.

Restart regression test. In tests/test-pi-local.mjs: global settings.json has commandcode.enableZDR: true and defaultProjectTrust: "always"; the run's cwd is a temp project whose .pi/settings.json has {"commandcode":{"enableZDR":false}}. The first inference request after startup asserts x-cmd-zdr: 1. tests/test-zdr.ts also covers direct read of true/false, a missing file, a symlinked file, and malformed content.

Checks on this commit: npm run typecheck, npm run typecheck:entrypoint, npm run format:check, npm run test:unit, and node tests/test-pi-local.mjs (the omp compat test skips here — no omp binary).

@pierreraby

Copy link
Copy Markdown
Collaborator

Thanks — I confirmed on Pi 1.5.2 that 32e44e1 fixes the global/project conflict in both directions, and the full local suite passed with Pi and OMP 18.22.0 required. Two additional loopback tests showed regressions compared with 116c7cb:

  1. OMP now reads a leftover settings.json despite the env-only contract. With both ZDR env vars unset, put a native config.yml and a settings.json containing {"commandcode":{"enableZDR":true}} in OMP's agent directory. With 116c7cb, ZDR reports off and neither inference nor /alpha/whoami gets x-cmd-zdr. With 32e44e1, it reports on and both requests get the header. The command still refuses on and off. Please use the same Pi-only guard for the settings read as for the write; keeping CMD_ZDR=1 working on OMP is the control.
  2. Pi silently loses the opt-in when the global file starts with a UTF-8 BOM. With no ZDR env vars, prepend a UTF-8 BOM to an otherwise valid global settings.json containing {"commandcode":{"enableZDR":true}}. Pi's settings parser accepts it, and 116c7cb sends x-cmd-zdr: 1. At 32e44e1, the status says off and both inference and /alpha/whoami omit the header. Removing only the BOM restores it. Please strip a single leading BOM in both the reader and writer (while still refusing genuinely malformed JSON on write) and add a regression test.

- gate the startup settings.json read behind the same pi-only probe as the
  /commandcode-zdr write, so OMP keeps the environment-only contract and a
  leftover settings.json cannot turn ZDR on there; CMD_ZDR=1 still applies
- strip one leading UTF-8 BOM in both the reader and the writer so the host's
  BOM-tolerant settings parser cannot silently drop the saved opt-in, while a
  malformed file is still refused on write
- add unit regressions for BOM handling and an OMP regression that a leftover
  settings.json is ignored and the environment opt-in still works
@Trex-Hub

Copy link
Copy Markdown
Author

Thanks — both regressions are fixed in 2a84bbe.

  1. OMP no longer reads a leftover settings.json. The startup read now goes through the same pi-only probe as the /commandcode-zdr write (settingsZdrSupported(), i.e. the registerApiProvider probe), so on OMP the opt-in resolves from the environment only. CMD_ZDR=1 / COMMANDCODE_ZDR=1 still work there, and the command still refuses on/off with the same message. Regression: tests/test-omp-compat.mjs writes {"commandcode":{"enableZDR":true}} into OMP's agent directory, asserts a chat request carries no x-cmd-zdr with both env vars unset, then asserts CMD_ZDR=1 still sends x-cmd-zdr: 1.
  2. A single leading UTF-8 BOM is stripped in the reader and the writer. src/zdr.ts gained stripBom(); loadZdrSettings() parses the BOM-stripped text, and saveZdrSetting() strips one BOM before parsing while still refusing genuinely malformed JSON (and leaving the file untouched). A BOM-only file is treated as empty rather than malformed. Regressions in tests/test-zdr.ts: BOM-prefixed valid settings resolve to on, a second BOM stays malformed, a BOM-prefixed writer round-trip preserves unrelated keys and rewrites without a BOM, and BOM-prefixed malformed content is still refused.

Checks run locally on 2a84bbe: npm run typecheck, npm run format:check, npm run test:unit (full suite, all pass), node tests/test-pi-local.mjs (PASS), npm run typecheck:entrypoint -- /usr/local/lib/node_modules/@earendil-works/pi-coding-agent (PASS), git diff --check. tests/test-omp-compat.mjs is added for CI since omp is not installed here.

@pierreraby

Copy link
Copy Markdown
Collaborator

Thanks for sticking with this, @Trex-Hub. I retested 2a84bbe on Pi 1.5.2 and OMP 18.22.0: both runtime fixes work, including the BOM settings file on Pi and a real leftover settings file on OMP. No further changes to the provider logic are needed from my review.

There's one small test-only fix left in tests/test-omp-compat.mjs: with OMP installed, the suite stops at line 362 with ReferenceError: Cannot access 'chatArgs' before initialization. Here's the exact adjustment I tested in a local copy:

  1. Move the existing const chatArgs = [...] above the print-mode test, and reuse it for that test and the two ZDR calls.

  2. Before writing the leftover settings.json, make sure a native OMP config already exists. In this isolated test home I used writeFileSync(join(agentDir, "config.yml"), "{}\n", { flag: "wx" }). Then, after the env-unset run and before checking the header, confirm the old file is still there and still set to true:

    assert.equal(
      JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf8")).commandcode.enableZDR,
      true,
    )

    Add readFileSync to the node:fs import. Without the native config fixture, OMP can migrate the legacy file out of the way, and moving chatArgs alone makes the test pass even on the buggy 32e44e1. With both adjustments, the targeted test passes on 2a84bbe and fails on 32e44e1 for the expected reason (x-cmd-zdr is 1 instead of absent).

Once that's in, I'll rerun the full suite with OMP required. Thanks again for the contribution and the quick follow-ups.

- move the shared chatArgs above the print-mode test and reuse it there and
  in both ZDR calls, fixing the ReferenceError when OMP is installed
- create a native config.yml before the leftover settings.json fixture so OMP
  cannot migrate the legacy file away, and assert the file survived so the
  test fails on the buggy head for the right reason
@Trex-Hub

Copy link
Copy Markdown
Author

Thanks @pierreraby — fixed in 9f22b73.

Both test-only adjustments are in tests/test-omp-compat.mjs:

  1. const chatArgs = [...] now lives above the print-mode test; that test and both ZDR calls reuse it, so nothing reads it before initialization.
  2. Before the leftover settings.json fixture, the test writes a native config.yml (writeFileSync(..., { flag: "wx" })). After the env-unset run it asserts the old file is still present and still commandcode.enableZDR: true, so OMP cannot migrate it away and the test only passes because OMP ignored it. readFileSync was added to the node:fs import.

With both, the targeted case passes on 2a84bbe/9f22b73 and fails on 32e44e1 for the expected reason (x-cmd-zdr: 1 instead of absent).

Checks locally: node --check, Prettier, npm run typecheck; test-omp-compat skips here because omp is not installed, so the OMP-required run in CI is the real gate.

@Trex-Hub

Copy link
Copy Markdown
Author

Verified with OMP locally as well: installed OMP 19.0.1 (Bun 1.4.4) and ran

OMP_BIN=/home/harness/.local/bin/omp OMP_COMPAT_REQUIRED=1 node tests/test-omp-compat.mjs

It passes, including a leftover settings.json does not enable ZDR and CMD_ZDR=1 still enables ZDR on OMP. No code changes beyond 9f22b73.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants