diff --git a/.agents/skills/testing-opencodex-management-api/SKILL.md b/.agents/skills/testing-opencodex-management-api/SKILL.md new file mode 100644 index 00000000000..60f5453a2b6 --- /dev/null +++ b/.agents/skills/testing-opencodex-management-api/SKILL.md @@ -0,0 +1,120 @@ +--- +name: testing-opencodex-management-api +description: Exercise the OpenCodex management API in a disposable, isolated development environment without touching personal client state. +--- + +# Testing the OpenCodex management API + +## Isolation is a prerequisite + +Use a disposable OS account, container, or VM with a disposable OS home. Do not run this +recipe in your normal desktop account merely by changing `OPENCODEX_HOME`. +That variable relocates OpenCodex state, not every client or shell integration. +On macOS, even disabling `claudeCode.systemEnv` can remove an existing managed block +from the OS home's `.zshrc`; `CLAUDE_CONFIG_DIR` does not redirect that file. +Raycast integration can also update existing OpenCodex-owned entries under the OS home. +A temporary client directory alone is therefore not a complete isolation boundary. + +Within the disposable environment, allocate a unique scratch directory and set `HOME` +to a fresh directory inside it before startup. A `HOME` override in a normal desktop +account is not a substitute for the disposable account, container, or VM. Set all of +`OPENCODEX_HOME`, `CODEX_HOME`, `CODEX_SQLITE_HOME`, `GROK_HOME`, `CLAUDE_CONFIG_DIR`, and +`OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR` to distinct directories inside it before startup. +Confirm the effective OS home belongs to the disposable account. Do not copy personal +tokens, client configuration, shell profiles, or keychain contents into this environment. +Start from a clean environment or inspect inherited path overrides before launching. +Codex SQLite state resolves in this order: a root `sqlite_home` key in +`CODEX_HOME/config.toml`, then `CODEX_SQLITE_HOME`, then `CODEX_HOME` itself. Keep the +scratch `CODEX_HOME/config.toml` free of an outside `sqlite_home`, resolve the effective +SQLite home with that precedence, and abort unless it is inside the scratch directory. + +Save a scratch `config.json` under `OPENCODEX_HOME` with an unused loopback port: + +```json +{ + "port": 19100, + "hostname": "127.0.0.1", + "codexAutoStart": false, + "syncResumeHistory": false, + "clientIntegrations": {"codex": false, "grok": false, "claude-desktop": false}, + "claudeCode": {"enabled": false, "injectAgents": false, "systemEnv": false} +} +``` + +Use both redirected client homes and integration disables. Disabled integrations may +still remove owned artifacts. `codexAutoStart` alone does not disable startup sync: +desired-state checks also consider integration settings and the hub/loopback-listener +role. Do not depend on any one flag as an isolation boundary. + +## Start and authenticate + +Install the repository's locked development dependencies and use the Bun version named +by `package.json`. Check that the selected Bun executable is available in this shell; +do not assume a particular developer's PATH layout. Start one foreground instance: + +```sh +bun run src/cli/index.ts start --port 19100 +``` + +Avoid `ensure`, tray, and service installation paths for this exercise: they can spawn +detached processes or alter persistent service state. Do not enable live providers or +submit billable traffic unless that separate test is explicitly authorized. + +Prefer reading the scratch instance's generated `admin-api-token` locally. Alternatively, +provision a randomly generated `OPENCODEX_ADMIN_AUTH_TOKEN` used only for this test. +It must differ from every data-plane API key; a collision makes management authentication +unavailable. Never paste the token into a PR, screenshot, log, or tracked fixture. + +Management requests accept `x-opencodex-api-key: ` or +`Authorization: Bearer `. Missing authorization is refused. A valid token +does not bypass route-specific origin, session, or policy requirements. Keep requests +loopback-only and do not follow redirects with credentials. + +## Focused Lab automation exercise + +Read `GET /api/lab/automation` for policy and live scheduler state; inspect recorded runs +with `GET /api/lab/automation/runs`. Enabling automation is an explicit state change, +not a requirement for a basic management-authentication test. + +A policy write uses `PUT /api/lab/automation`, for example: + +```json +{"policy":{"enabled":true,"layers":{"protocolConformance":true}}} +``` + +Serialize policy writes. The read/merge and save do not share one lock, so concurrent +writers can overwrite each other's changes even though publication itself is atomic. +Re-read the policy after changing it. + +A fixture-only manual run uses `POST /api/lab/automation/run` with this request body: + +```json +{"evidenceLayer":"protocol_conformance","scenarioId":"responses-core.protocol.request-shape"} +``` + +For `live_route_compatibility`, include `providerName` and `modelId` in the POST request +body, not as substitute top-level configuration fields. The named provider must already +exist in `config.providers`, and live calls require authorization and suitable test +credentials. Lab must also be active at proxy startup: a later policy PUT alone does +not register the live route executor. Enable automation in the disposable home, stop +the foreground proxy, and start it again before a separately authorized live run. +The fixture-only protocol exercise above does not need this restart. Consult +`planManualLabRun` in `src/lab/automation/planner.ts` for accepted +combinations instead of guessing a scenario or provider. + +The manual endpoint awaits dispatch and returns a run/trigger result. Inspect the returned +status rather than assuming success or a terminal run. Scheduler work is separate and +may not appear immediately; read the configured scheduler limits instead of sleeping for +a hard-coded interval. + +## Stop and inspect + +Send one interrupt to the foreground process and let its bounded cleanup/drain finish. +A clean shutdown exits with zero; cleanup or drain failures may exit nonzero. A second +signal requests forced termination and is not proof of successful cleanup. +Check that the test listener and any test-owned children have stopped before removing +the exact scratch tree. Do not clean directories based on a name pattern or age. +Capture only redacted status, exit code, exact test commands, and observed results. + +This is a development testing recipe. It does not replace the operating reference in +`skills/ocx/` or the consent rules in `AGENTS_INSTALL.md`. diff --git a/AGENTS.md b/AGENTS.md index 64c6c3106fc..e4c1ce1b41f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -208,6 +208,9 @@ bun run build:gui # Vite GUI build proxy, as opposed to [`AGENTS_INSTALL.md`](./AGENTS_INSTALL.md) (installing and operating consent) or this file (changing the codebase). Its surface map is generated: +For development tests of the management API, use the isolated +[management API test recipe](./.agents/skills/testing-opencodex-management-api/SKILL.md). + ```bash bun run skill:surface # regenerate after adding a capability bun run skill:surface:check # what CI asserts diff --git a/devlog/_plan/260927_release_train_4/clients-proxy/000_plan.md b/devlog/_plan/260927_release_train_4/clients-proxy/000_plan.md new file mode 100644 index 00000000000..48cb5c03cdd --- /dev/null +++ b/devlog/_plan/260927_release_train_4/clients-proxy/000_plan.md @@ -0,0 +1,123 @@ +# Release train 4: clients and proxy lane + +At `origin/dev` `24b2f39b77` on 2026-09-27, this lane has a mix of useful client +integrations, routing changes, and proposals whose current diffs are not safe to +land. Carry the bounded changes through ordinary PRs to `dev`, correct the observed +regressions, and leave concrete reasons on proposals that need a new contract. + +## Loop specification + +- Archetype: satisfy the release-train acceptance contract, one dependency-ordered + work phase per PABCD cycle. +- Trigger: the release train 4 `clients-proxy` lane assignment. +- Goal: land verified client/proxy changes that help the next release and record a + disposition for every assigned PR and issue. +- Non-goals: `main`, `preview`, releases, version changes, other lanes, writes to + contributor forks, automatic third-party installer execution, and eager client + activation on the three core request paths. +- Verifier: the focused commands in the decade docs, `bun run test:changed`, + `bun run typecheck`, `bun run structure:check`, `bun run privacy:scan`, + `bun run skill:surface:check` when CLI capabilities change, exact-head PR CI, + and a successful post-merge `dev` CI run. Conditional branches have explicit + activation cases in their phase documents. +- Stop condition: every row below has a supported merge or hold decision, each + landed PR passed its actual required jobs, source PRs/issues received the + appropriate links and disposition, and the final `dev` run succeeded. +- Memory artifact: this numbered unit, its phase evidence, and the lane's + session-bound goalplan/ledger. +- Terminal outcomes: DONE means that stop condition holds; NOOP means no + candidate survived review; NEEDS_HUMAN means an external contract or approval + blocks a specific candidate; BLOCKED means repeated external failure prevents + all meaningful progress; UNSAFE means validation found an unresolved release + blocker. There is no user-specified token or wall-clock bound. +- Escalation: a new scope, an unresolvable security boundary, or a required + external account decision goes to the coordinator. PR push/merge and issue/PR + disposition within this lane are already authorized. + +All source edits, Git operations, and tests use this lane's dedicated +worktree checkout. The native +session directory is used only for ignored FSM and goalplan state. Local full +suite may be omitted due to seven concurrent lane worktrees; focused regressions +remain mandatory, and each PR's Verification section will state the exact +commands, results, and coverage left to CI. + +## Source ownership and selection + +`structure/clients/integrations.md:27-55` assigns pure client builders to +`src/clients/config-export.ts`, detection paths to +`src/integrations/registry.ts`, and snapshot/classification/writes to the shared +integration modules. New clients stay explicit and use those seams. The three +core request files (`src/router.ts`, `src/server/lifecycle.ts`, +`src/server/responses/core.ts`) must retain the Lab import boundary enforced by +`tests/lab/core-lab-boundary.test.ts`. `src/config/proxy-env.ts` owns process +proxy activation (`structure/config-proxy.md:1-20`). + +| Item | Current head/state | Decision and evidence | Work phase | +| --- | --- | --- | --- | +| #6051 | `987b8097`, open | Carry the disposable-home management-API recipe with a discoverable contributor link; `.agents/skills/` has no existing entry point. | [010](010_recipe.md) | +| #5893 / #5853 | `3743320a`, draft | Carry only when every macOS exception maps faithfully onto the bypass variables the active transports read, or discovery refuses before any environment write; an inherited SOCKS proxy keeps its existing path. | [020](020_macos_proxy.md) | +| #5950 / #5660 | `ef03f5ab`, open | Carry Qoder after current-base revalidation of opt-in config writes, restore, and path handling (`src/clients/config-export/qoder.ts`, PR test). | [030](030_qoder.md) | +| #5272 | `7dd796d7`, open | Carry Kilo after checking all merged config candidates; first-file-only selection can be overridden by a later legacy file (`src/clients/config-export/kilo.ts:57-63` in PR). | [040](040_kilo.md) | +| #5193 | `91090f80`, open/conflicting | Reimplement a focused Droid slice on current `dev` only if its client contract and export provenance can be proven. The PR's broad rewrite changes shared loopback export behavior. | [050](050_droid.md) | +| #5871 | `ba2d2600`, open/conflicting | Carry after conflict repair and an outbound decision-payload regression (`src/combos/jev.ts:588-595` in PR). | [060](060_jev.md) | +| #5983 / #5982 | `cd45810f`, open | Carry with explicit non-memory metadata taking precedence over the subagent header fallback (`src/server/responses/memory-models.ts:65` in PR). | [070](070_memory.md) | +| #5905 / #5679 | `19948a38`, draft | Hold: opening regular Cursor integration status can automatically fetch an external installer manifest. Decide explicit opt-in and cover timeout/status before carry. | [080](080_held_items.md) | +| #3833 | `d47e376b`, draft | Hold: Command Code rejects the exported literal `apiKey` placeholder; the PR test only checks presence. Needs supported client credential form and live client proof. | [080](080_held_items.md) | +| #4854 | open | Hold OpenScience until its actual config schema and ownership paths are established. Manual OpenAI-compatible endpoint is available. | [080](080_held_items.md) | +| #3494 | open | Hold VS Code extension integration until one named extension's supported settings and reload lifecycle are verified. | [080](080_held_items.md) | +| #1416 | open | Hold Orca launch manifest until the stopped-proxy, secret-free consumer contract is pinned; live-catalog config export is the wrong bootstrap path. | [080](080_held_items.md) | +| #2811 | open | Design only: #5016 was closed because `plan` required `managed: true` that the production inspector never reports. A reachable provenance proof precedes apply. | [080](080_held_items.md) | + +## Dependency order and merge method + +`010` establishes the verification recipe, `020` owns outbound proxy activation, +`030` proves the existing client path on current `dev`, and `040`/`050` reuse that +verified roster with one client at a time. `060` precedes `070` because both touch +`src/types/config.ts`; that is a merge-conflict dependency, not a runtime one. +`080` records held items after each applicable outcome. [090](090_final_ci.md) +checks the latest integrated tree. Each carried source PR becomes a new ordinary +`dev` PR from this lane, with a `Co-authored-by` trailer in the PR description +or branch commit. Git authorship alone does not satisfy the carry policy. A +large or conflicted source diff is reduced before +landing; the source PR is thanked, linked, and closed only once its replacement +is merged. No GitHub native stack or tip-only CI exception is selected. + +For every batch, fetch `origin/dev` again, inspect the source PR's current head +and diff, check the file-size ratchet and merged union/locale/count consumers, +run focused tests and typecheck, perform explicit security review for any +credential, proxy, installer, or authentication boundary, then inspect +required CI at the exact new PR +head before merging. GUI changes need a screenshot in the PR description from +the separate `pr-assets` branch, never committed to the PR branch. Merge only +when the new PR head contains the latest `origin/dev`; dispatch `ci.yml` on +`dev` manually as specified in [090](090_final_ci.md) and inspect its exact +head before the next batch. + +## Consultation and uncertainty + +The architect proposal: D1 existing +integration ownership and D2 proxy ownership accepted; D3 Cursor discovery +amended to hold pending opt-in; D4 managed clients accepted with #3833 held; +D5 new client proposals held pending primary client contracts; D6 JEV then +memory accepted; D7 Codex updater remains design-only. Four independent source +PR reviewers examined the candidates. The architect's first reflection +found three gaps: attribution trailer, explicit security review, and the +recipe's OS-home isolation condition. All three were folded into this revision +before independent audit. Their findings are proposals; each carry is +rechecked on the actual integrated diff and current `dev`. + +Baseline verifier preflight on `24b2f39b77`: `bun run typecheck`, +`bun run structure:check`, `bun run privacy:scan`, +`bun run skill:surface:check`, and `bun test +tests/lab/core-lab-boundary.test.ts` each exited 0; the Lab guard ran 25 +tests. These check the baseline and this planning tree only. New PR behavior +still requires the phase-specific commands after the relevant diff is present. +`bun run test:changed` on this docs-only staged diff selected zero tests and +exited 1; it is not evidence of test passage. Docs checks and semantic audit +cover the roadmap, and implementation batches rerun changed tests. + +The same architect rechecked the D2 safety amendment and returned ALIGNED. +The independent A reviewer first +reported six blockers, then one remaining test-layout blocker; every finding +was folded into the relevant decade document and its final verdict was PASS. +This closes the roadmap design review, not any proposed code change. diff --git a/devlog/_plan/260927_release_train_4/clients-proxy/010_recipe.md b/devlog/_plan/260927_release_train_4/clients-proxy/010_recipe.md new file mode 100644 index 00000000000..4af0bdb796b --- /dev/null +++ b/devlog/_plan/260927_release_train_4/clients-proxy/010_recipe.md @@ -0,0 +1,95 @@ +# Phase 1: management API test recipe (#6051) + +The preceding D concluded that the reviewed roadmap is locked at `ce5a406862`; +the next action is this bounded recipe carry. Depends on `000_plan.md`; +docs-only carry, then one ordinary PR. The source PR +adds `.agents/skills/testing-opencodex-management-api/SKILL.md` with a +disposable-home setup and correct Lab requests. It needs a repository entry +point before another agent can reliably discover it. + +## Exact change map + +- NEW `.agents/skills/testing-opencodex-management-api/SKILL.md`: carry the + 108-line source recipe from #6051 head `987b8097624e50e6c39b00aca145fe4755043c4b` + with source-verified isolation and activation corrections after checking every command and path against current + management routes. Preserve its disposable OS account/home, container, or + VM prerequisite; redirect client homes and disable integrations before a + smoke. `OPENCODEX_HOME` alone does not isolate client writes. Keep explicit + token read, bounded process cleanup, and authorization before live-provider + requests. No secret values or real account identifiers enter examples. +- MODIFY `AGENTS.md` near the Commands and `skills/ocx/` guidance: add one + contributor-facing link to the test recipe. Before: only the runtime-control + `skills/ocx/` reference is discoverable (`AGENTS.md:207-209`). After: one + sentence identifies `.agents/skills/testing-opencodex-management-api/SKILL.md` + as the development test recipe, while `skills/ocx/` remains the operating + reference and `AGENTS_INSTALL.md` retains consent guidance. Do not change + runtime imports, CLI capabilities, or the generated operating-surface map. +- MODIFY `010_recipe.md` with a short outcome addendum after validation, + naming the carried source SHA, attribution, and exact command results. The + carry commit or PR body + must contain `Co-authored-by: luvs01 <27862058+luvs01@users.noreply.github.com>`. + +## Acceptance and proof + +Read the recipe's executable examples against +`src/server/management/lab-automation-routes.ts:119-180` and +`src/lab/automation/planner.ts:278-340`; POST fields are body fields and PUT +policy fields are supported there. `bun test +tests/lab/lab-automation-management-http.test.ts` ran at the base and passed +2 tests; it checks route cancel/pagination, not the prose or POST example. +Run a smoke only in a disposable OS account/home, +container, or VM with redirected client homes and integrations disabled; +the current desktop account does not meet this precondition, so record the +smoke as unrun. Confirm the carried file against the pinned PR head, its +frontmatter and link target. Stage every changed and new file before running +`git diff --cached --check` and `bun run privacy:scan`; the scan uses +`git ls-files`, so an untracked skill would be invisible. After commit run +`git diff origin/dev...HEAD --check`. Also run `bun run structure:check` and +`bun run typecheck`. These commands protect +the tree and paths; semantic correctness of the recipe needs source review. +`bun run test:changed` can select zero tests for a docs-only diff and is then +not passing evidence. A docs-only CI skip is recorded as skipped, not +as a passing suite. PR template Summary/Verification/Checklist, source author +credit, exact-head required checks, and post-merge `dev` CI still apply. + +The architect proposed D1-R (carry the +isolation and route examples), D1-L (one AGENTS discovery link), and D1-V +(attribution and exact gates). All three are accepted. Putting the recipe in +`skills/ocx/` would confuse development tests with operating guidance; a +PR-only link would not be durable. + +## Local carry outcome + +Imported the recipe from #6051 head +`987b8097624e50e6c39b00aca145fe4755043c4b`; the initial `cmp` +against that Git object exited 0 at 108 lines. C-phase implementation review +then required two source-grounded corrections to the final copy: redirecting +Codex's SQLite home and disabling resume-history sync in the disposable +configuration, and activating Lab at startup before a separately authorized +live-route run. The isolation instructions also require `HOME` to point into +the disposable scratch root. The final recipe therefore intentionally differs from the +source PR. `AGENTS.md:212` links it beside +the operating reference. The same independent A reviewer first found that +an unstaged whitespace check would miss a staged change and the privacy scan +would miss an untracked skill; the plan now stages all files before both gates, +and the reviewer returned PASS. + +After staging, `git diff --cached --check`, `bun run privacy:scan`, +`bun run structure:check`, and `bun run typecheck` exited 0. `bun test +tests/lab/lab-automation-management-http.test.ts +tests/lab/lab-automation.test.ts` passed 24 tests with 0 failures. These tests +cover the route and planner baseline, not the prose; route and planner source +were read against the example fields. `bun run test:changed` exited 1 because +the docs-only diff selected 0 tests. The live smoke was not run in this +desktop account: it lacks the disposable OS-home prerequisite. Full local +suite is omitted due to concurrent lane worktrees; CI remains the broader +gate. PR-head and post-merge `dev` CI evidence are recorded after publication. + +After the C-phase corrections, the scratch `config.json` example parsed as +JSON with `syncResumeHistory: false`; `git diff --cached --check` and +`bun run privacy:scan` exited 0 on the staged revision. The independent +implementation reviewer rechecked the SQLite and Lab startup paths and +returned PASS. A separate token/isolation security reviewer also returned +PASS on the amended recipe. Neither reviewer ran the live smoke, and the +24-test route/planner run and typecheck predate only these documentation edits; +no runtime source changed between those checks and this revision. diff --git a/devlog/_plan/260927_release_train_4/clients-proxy/020_macos_proxy.md b/devlog/_plan/260927_release_train_4/clients-proxy/020_macos_proxy.md new file mode 100644 index 00000000000..4890553c7a8 --- /dev/null +++ b/devlog/_plan/260927_release_train_4/clients-proxy/020_macos_proxy.md @@ -0,0 +1,61 @@ +# Phase 2: macOS system proxy discovery (#5893) + +Depends on `010_recipe.md` for lane order. Carry the small proxy change after +rebasing its draft head onto current `dev`; do not change Windows discovery or +explicit proxy precedence. `structure/config-proxy.md:1-20` owns the contract. + +## Exact change map + +- NEW `src/config/macos-system-proxy.ts`: observe and parse macOS system + proxy settings only on Darwin; return no discovery for disabled, malformed, + or unavailable settings. No caller imports this module on every request. +- MODIFY `src/config/proxy-env.ts`: before, `proxy: "auto"` considers the + existing Windows path and merges loopback bypasses. After, Darwin discovery + is considered only for that explicit setting and when no inherited scheme + proxy wins. Translate macOS exceptions only when their matching semantics + are proven equivalent to Bun's `no_proxy` semantics. A bare name such as + `localhost` must not enter either effective proxy-bypass variable as a + suffix. If any system exception is not faithfully representable, refuse + macOS auto-discovery and leave process proxy variables unchanged with a + privacy-safe diagnostic. Preserve the address-only loopback bypass. Add + proven-safe entries to the bypass variable the selected HTTP(S) transport + actually reads. If inherited `ALL_PROXY`/`all_proxy` selects SOCKS, + macOS discovery must not add scheme proxies or discovered exceptions. + Preserve the inherited proxy path and assert both transports' + effective routes when the two bypass variables disagree. Redact + credential-bearing proxy URLs. +- MODIFY `tests/server/proxy-env.test.ts`: retain source tests and add a case + with lowercase `no_proxy` distinct from uppercase `NO_PROXY`; assert the + effective bypass after activation. Drive a request to `localhost` and + `app.localhost` (or the proxy matcher used by that request) and prove that + the exception does not widen direct egress. An unrepresentable exception + must refuse discovery before the normal `mergeNoProxyEntries` tail; assert + a full byte-identical snapshot of `HTTP_PROXY`, `HTTPS_PROXY`, lowercase + equivalents, `ALL_PROXY`, `all_proxy`, `NO_PROXY`, and `no_proxy`. Cover + safe wildcard/IP entries, malformed/disabled `scutil` output, explicit + environment precedence, `proxy` unset, inherited SOCKS `ALL_PROXY` with + conflicting uppercase/lowercase bypass lists, and unchanged Windows + behavior. Tests use + a mocked system command; they do not claim a real macOS Settings session. +- MODIFY `structure/config-proxy.md` and the English plus affected translated + `docs-site/src/content/docs/*/reference/configuration/server.md` pages to + state the actual opt-in/automatic precedence after code is verified. + +## Acceptance and proof + +Activation scenario: Darwin with `config.proxy: "auto"`, no inherited HTTP(S) +or SOCKS proxy (`ALL_PROXY`/`all_proxy` included), and valid system settings +sets the proxy and safely representable bypass list. Bypass precedence is +asserted per transport: Bun's native HTTP(S) fetch reads a non-empty lowercase +`no_proxy` before `NO_PROXY`, while `resolveProxyRoute` honors an explicitly +defined uppercase `NO_PROXY`, including an empty value. Tests keep route +assertions for both transports when the two variables disagree. +Negative scenarios: unset `config.proxy` never reads system settings or mutates +egress, inherited HTTP(S) or SOCKS proxy wins without mixed bypass semantics, +unrepresentable exceptions refuse before any environment write, disabled or +bad system settings leave egress unchanged, and Windows keeps its prior route. Run +`bun test tests/server/proxy-env.test.ts`, `bun run test:changed`, `bun run +typecheck`, `bun run structure:check`, and `bun run privacy:scan`. Build +`docs-site/` if docs change. `tests/lab/core-lab-boundary.test.ts` checks the +core import rule. Perform explicit security review of credential-bearing +proxy URL handling. Recheck exact-head CI and live `dev` CI before the next batch. diff --git a/devlog/_plan/260927_release_train_4/clients-proxy/030_qoder.md b/devlog/_plan/260927_release_train_4/clients-proxy/030_qoder.md new file mode 100644 index 00000000000..b80d8c1ba45 --- /dev/null +++ b/devlog/_plan/260927_release_train_4/clients-proxy/030_qoder.md @@ -0,0 +1,46 @@ +# Phase 3: opt-in Qoder client (#5950) + +Depends on the preceding lane batch's `dev` result; Qoder reuses the existing +pure export, registry and journaled writer seams rather than adding request +path code. The source PR touches 36 files, including GUI and translations; +carry one coherent client slice and remove unrelated drift. + +## Exact change map + +- NEW `src/clients/config-export/qoder.ts`: build the documented provider + contribution and exact managed fragment paths. Loopback may use a + non-secret placeholder; remote bind must have a supported admission header + or refuse. +- MODIFY `src/clients/config-export/contracts.ts` and + `src/clients/config-export.ts`: before, Qoder is absent from the export ID + union/registry. After, `qoder` is a named opt-in export with a derived + roster count, not a hand-written total. +- MODIFY `src/integrations/registry.ts` and `mutation-plan.ts`: resolve a + Qoder-supported user path, validate file/directory safety, and use the + common status/preview/apply/disable/restore classifier. No automatic + detection write or core request-path import. +- MODIFY `src/cli/help.ts`, `src/cli/registry.ts`, the GUI integration lists, + routing, marks, API IDs, and affected locales to expose the same client ID. + Update `docs-site/src/content/docs/guides/integrations.md`, + `structure/clients/integrations.md`, and + `structure/dashboard-and-usage.md` in the same change. +- MODIFY/NEW tests under `tests/clients/`, `tests/config/`, `tests/gui/`, and + `gui/tests/` for exact generated shape, absent client, foreign keys, + symlink/unsafe path refusal, drift, snapshot-before-write, disable, and + byte-exact restore. Register new test names in both test-layout manifests. + +## Acceptance and proof + +Activation: an operator explicitly enables Qoder against a disposable config; +the generated provider is present and a later disable/restore recovers prior +bytes. A hostile or changed file refuses without overwrite. Windows path +tests use a Windows-shaped home/env and confirm no POSIX-only assumption. +Run `bun test tests/clients/qoder-client.test.ts +tests/clients/integrations-state.test.ts +tests/config/client-config-export-new-clients.test.ts`, relevant `gui/tests/`, +`bun run test:changed`, `bun run typecheck`, `bun run lint:gui`, +`bun run build:gui`, `bun run structure:check`, `bun run privacy:scan`, +and `bun run skill:surface:check` if the capability registry changes. +Perform explicit security review of admission and config serialization. Check +the file-size ratchet, test-layout manifests, locale union, screenshot, +exact-head required CI, and merged `dev` run. diff --git a/devlog/_plan/260927_release_train_4/clients-proxy/040_kilo.md b/devlog/_plan/260927_release_train_4/clients-proxy/040_kilo.md new file mode 100644 index 00000000000..f7e578e92d4 --- /dev/null +++ b/devlog/_plan/260927_release_train_4/clients-proxy/040_kilo.md @@ -0,0 +1,42 @@ +# Phase 4: Kilo managed config (#5272) + +Depends on `030_qoder.md` to reconcile the shared export-client union and GUI +roster once per current `dev` head. The PR's 57-file slice includes a JSONC +writer extension; preserve comments and all unrelated client state. + +## Exact change map + +- NEW `src/clients/config-export/kilo.ts`: generate the documented Kilo + provider block and resolve the active global config path. Before, no Kilo + export exists. After, a config is selected only when later legacy files + cannot override its managed `provider.opencodex` block. If two candidate + files can supply that block, status and apply refuse with a clear conflict; + no first-file-wins write that appears successful but is ineffective. +- MODIFY `src/clients/config-export.ts`, `contracts.ts`, + `src/integrations/registry.ts`, `target.ts`, `state.ts`, `writer.ts`, + `mutation-plan.ts`, `config-io.ts`, and `src/lib/jsonc.ts` only as required + for source-preserving JSONC and the common ownership contract. The parser + must reject non-roundtrippable syntax before mutation and keep unrelated + comment-bearing bytes recoverable from the snapshot. +- MODIFY the CLI export/help/registry entries, GUI integration registry and + affected locale keys, public integration documentation, and + `structure/clients/integrations.md` for the actual Kilo path. +- NEW/MODIFY `tests/clients/kilo-client.test.ts` and adjacent config/GUI + tests: add a two-file precedence conflict fixture with distinct provider + values, byte-exact restore of an initial comment-bearing file, unsafe path + refusal, and Windows-shaped home/path resolution. Register test files in + both test-layout manifests. + +## Acceptance and proof + +Activation: explicit apply to an unambiguous Kilo install writes only owned +fields; disabling and restoring leave foreign JSONC and original bytes intact. +Conflict activation: a later candidate file contains the same provider key; +status and mutation both refuse before snapshot/write. Run +`bun test tests/clients/kilo-client.test.ts +tests/config/client-config-export.test.ts`, the relevant `gui/tests`, +`bun run test:changed`, `bun run typecheck`, `bun run lint:gui`, +`bun run build:gui`, `bun run structure:check`, `bun run privacy:scan`, +and `bun run skill:surface:check` if capabilities change. Check screenshot, +merged file-size cap, union/locale counts, explicit credential/path security +review, exact-head CI, and post-merge `dev`. diff --git a/devlog/_plan/260927_release_train_4/clients-proxy/050_droid.md b/devlog/_plan/260927_release_train_4/clients-proxy/050_droid.md new file mode 100644 index 00000000000..c33d2aa7b26 --- /dev/null +++ b/devlog/_plan/260927_release_train_4/clients-proxy/050_droid.md @@ -0,0 +1,42 @@ +# Phase 5: focused Factory Droid integration (#5193) + +Depends on `040_kilo.md` for shared roster reconciliation. The source PR +conflicts with current `dev` and changes 83 files, including broad export +behavior and unrelated test harnesses. Reimplement the narrow client thesis; +if the installed Droid contract cannot be verified, record a hold and leave +the source PR open with a reason. + +## Exact change map if verified + +- NEW `src/clients/config-export/droid.ts`: build only Droid's documented + settings and per-model rows using the documented user settings path. Do not + add an automatic startup/config write or copy provider credentials. +- MODIFY `src/clients/config-export.ts`, `contracts.ts`, + `src/integrations/registry.ts`, and `mutation-plan.ts` to add the typed ID + and exact managed fragments. Before, Droid is absent. After, explicit + export/enable uses the shared journal and restore path. +- MODIFY `src/cli/export-command.ts` only if Droid needs a distinct + loopback catalog source. Preserve the existing catalog provenance for every + other loopback-only client; the source PR's all-client redirect is not + accepted without a separate proof. Update CLI help, GUI roster/locales, + `docs-site/src/content/docs/guides/integrations.md`, and + `structure/clients/integrations.md` for the verified client slice. +- NEW `tests/clients/droid-client.test.ts`: assert exact client-consumed + settings, foreign model preservation, symlink/unsafe path refusal, Windows + path, drift, disable and exact-byte restore. MODIFY + `tests/cli/cli-export-command.test.ts` to prove existing clients retain + their old catalog/selection source. Register the new test in both manifests. + +## Acceptance and proof + +Activation: a disposable Droid config is explicitly enabled and subsequently +restored. Negative: a changed user model or unsafe target refuses before +overwrite, and a non-Droid loopback client exports the same catalog as before. +Run `bun test tests/clients/droid-client.test.ts +tests/cli/cli-export-command.test.ts`, relevant integration and GUI tests, +`bun run test:changed`, `bun run typecheck`, `bun run lint:gui`, +`bun run build:gui`, `bun run structure:check`, `bun run privacy:scan`, and +surface check if needed. Do not claim live Droid behavior from a synthetic +fixture alone; verify the documented client schema before committing the +implementation. Explicit credential/path security review, a GUI screenshot, +and exact-head CI precede merge. diff --git a/devlog/_plan/260927_release_train_4/clients-proxy/060_jev.md b/devlog/_plan/260927_release_train_4/clients-proxy/060_jev.md new file mode 100644 index 00000000000..1970ba9786e --- /dev/null +++ b/devlog/_plan/260927_release_train_4/clients-proxy/060_jev.md @@ -0,0 +1,40 @@ +# Phase 6: operator JEV model profiles (#5871) + +Depends on the shared type/roster reconciliation from prior batches; the PR +currently conflicts with `dev`. Keep profile settings optional and off the +single-provider/no-profile request path. + +## Exact change map + +- MODIFY `src/types/config.ts` and `src/combos/types.ts`: add an optional + target-keyed profile shape. Trace creation in management input, persistence + through config serialization/deserialization, and consumption by JEV; a + missing profile retains the old request shape. +- MODIFY `src/combos/jev.ts`: insert an operator-authored per-target note into + the outbound decision payload while retaining existing candidate bounds + and built-in profile behavior. Validate and bound that freeform text at the + input boundary, document that it is sent to the decision provider, and + review privacy/security implications explicitly. Do not widen the target + model set or create a new unsolicited model request. +- MODIFY `src/server/management/combo-routes.ts`, + `src/server/responses/core-combo.ts`, GUI combo workspace controls/data, + relevant locales, `docs-site/src/content/docs/guides/combos.md`, and + `structure/providers-and-adapters.md` to expose and describe that same + optional shape. Keep locale keys exhaustive. +- MODIFY `tests/routing/jev-decision.test.ts` to capture the actual outbound + request and assert the selected target note appears. Also test absent + profile, wrong target, and bound candidates; update management and GUI tests. + +## Acceptance and proof + +Activation: configure a note for target A, invoke JEV with A, and observe it in +the outbound decision payload; invoke B/absent profile and observe the prior +payload. Run `bun test tests/routing/jev-decision.test.ts +tests/routing/combo-management-api.test.ts`, relevant `gui/tests`, +`bun run test:changed`, `bun run typecheck`, `bun run lint:gui`, +`bun run build:gui`, `bun run structure:check`, `bun run privacy:scan`, +and `bun test tests/lab/core-lab-boundary.test.ts`. Recheck the current-base +union/locale and file-size ratchet; inspect the actual transmitted note, +its bounds, privacy handling, and user-facing disclosure in a security review. +GUI screenshot and exact-head CI are +required before merge. diff --git a/devlog/_plan/260927_release_train_4/clients-proxy/070_memory.md b/devlog/_plan/260927_release_train_4/clients-proxy/070_memory.md new file mode 100644 index 00000000000..ae1384f1629 --- /dev/null +++ b/devlog/_plan/260927_release_train_4/clients-proxy/070_memory.md @@ -0,0 +1,58 @@ +# Phase 7: selected models for Codex memory (#5983) + +Depends on `060_jev.md` for serial changes to `src/types/config.ts`. The source +PR spans 51 files. The carried classifier treats explicit turn metadata as +authoritative and consults the `x-openai-subagent` header only when that +metadata is absent. + +## Exact change map + +- NEW `src/server/responses/memory-models.ts`: classify memory phases from + validated turn metadata. Before: no memory-specific target. After: an + explicit `none`/non-memory metadata result returns no memory route, and the + legacy subagent header is consulted only when metadata is absent. Reject + malformed target settings without silently selecting a different model. +- MODIFY `src/server/responses/request-prepare.ts` and the related normalize, + options, availability, and config modules only to thread the selected + memory target through both HTTP and WebSocket admission. Do not import Lab + from `src/server/responses/core.ts`, `src/router.ts`, or + `src/server/lifecycle.ts`; do not add a timer for no-memory users. +- MODIFY `src/types/config.ts`, `src/types/request.ts`, config schema/leaf + validation, CLI/config docs, management config route, and GUI Memory panel + and locale keys so input, persisted value, reload and consumers agree. No + hand-counted preset/capability totals. +- REVIEW and MODIFY the relevant mapped source-of-truth documents: + `structure/config.md` for the persisted setting, + `structure/transports/responses.md` and + `structure/transports/responses-failover.md` for routing behavior, + `structure/gui-and-management-api.md` for settings exposure, and + `structure/providers-and-adapters.md` for `src/types/` ownership. + Check the other documents mapped to `src/server/` in + `structure/INDEX.md`; update any whose described contract changes. +- NEW `tests/responses/responses-memory-models.test.ts`: send explicit + non-memory metadata plus a subagent header and assert the normal model + serves the request. Cover real memory metadata, absent metadata fallback, + unavailable selected target, HTTP and WebSocket entry, and no-memory + baseline. The WebSocket case must enter through actual WebSocket admission, + not merely call the classifier with `transport: "websocket"`. +- NEW `tests/config/settings-memory-models.test.ts`: cover accepted and + rejected persisted memory targets, load degradation, and management-save + behavior without dropping unrelated config. +- MODIFY relevant `gui/tests` for model selection and disabled/unknown + targets. Register both new test files in `scripts/test-layout/layout.json` + and `tests/fixtures/test-layout-expected.json`. + +## Acceptance and proof + +Activation: a memory-phase request with configured target routes there; +explicit non-memory metadata never routes there even with the fallback header; +no setting retains current behavior. Run `bun test +tests/responses/responses-memory-models.test.ts +tests/responses/responses-shadow-intercept.test.ts +tests/config/settings-memory-models.test.ts`, a WebSocket entry-path +regression, and the relevant `gui/tests`, +`bun run test:changed`, `bun run typecheck`, `bun run lint:gui`, +`bun run build:gui`, `bun run structure:check`, `bun run privacy:scan`, +and `bun test tests/lab/core-lab-boundary.test.ts`. Inspect user-facing +English/translated docs, current merged type unions and file-size caps. +Require GUI screenshot and exact-head CI before merge. diff --git a/devlog/_plan/260927_release_train_4/clients-proxy/080_held_items.md b/devlog/_plan/260927_release_train_4/clients-proxy/080_held_items.md new file mode 100644 index 00000000000..e4b1bf32ad1 --- /dev/null +++ b/devlog/_plan/260927_release_train_4/clients-proxy/080_held_items.md @@ -0,0 +1,38 @@ +# Phase 8: source PR and issue disposition + +Depends on outcomes from `010`-`070`. This is a GitHub triage phase, not a +product-code batch. It is complete only when each row has a current link and +the correct open/closed state. Comments are in English and name the specific +missing proof or replaced PR. Do not close a source PR until its replacement +has merged into `dev`; leave a genuine enhancement open when held. + +## Exact external change map + +- COMMENT, then CLOSE replaced source PRs #6051, #5893, #5950, #5272, + #5193, #5871, #5983 only if the corresponding carried behavior actually + landed. Include the lane PR and merge SHA and thank the original author. +- COMMENT, KEEP OPEN #5905: opening Cursor status currently fetches a remote + installer manifest without a user action. Ask for an explicit discovery + policy and timeout/status regression. Keep draft and no installer launch. +- COMMENT, KEEP OPEN #3833: the literal `apiKey` placeholder in its export is + rejected by Command Code; require a documented supported keyless/reference + form and client-side proof, then refresh against `dev` and security review. +- COMMENT, KEEP OPEN #4854: require OpenScience config path/schema and + override/restore ownership evidence; the manual endpoint remains usable. +- COMMENT, KEEP OPEN #3494: require one named VS Code extension's officially + supported settings, reload behavior, and per-scope ownership contract. +- COMMENT, KEEP OPEN #1416: require a versioned, secret-free Orca launch + manifest that can be generated while the proxy is stopped; do not insert + it into live model export before the consumer schema is agreed. +- COMMENT, KEEP OPEN #2811: record the design-only judgment. #5016 was + closed unmerged because `managed: true` was unreachable from the production + inspector. Establish a real provenance predicate and read-only plan before + considering an apply mutation. +- CLOSE linked #5853, #5660, and #5982 only when the exact behavior is on + `dev`, with the lane merge link. #5679 remains open while #5905 is held. + +## Acceptance and proof + +Fetch each PR/issue after each comment/close and verify state and URL. Do not +count a `gh` command's exit alone as proof. The issue-close list is conditional +on actual merged outcomes. Re-read source authors for attribution trailers. diff --git a/devlog/_plan/260927_release_train_4/clients-proxy/090_final_ci.md b/devlog/_plan/260927_release_train_4/clients-proxy/090_final_ci.md new file mode 100644 index 00000000000..c80f76faf0d --- /dev/null +++ b/devlog/_plan/260927_release_train_4/clients-proxy/090_final_ci.md @@ -0,0 +1,32 @@ +# Phase 9: final integration and CI + +Depends on all selected carries and triage. This phase writes no product code +unless the last `dev` run exposes a lane-owned regression; any repair gets its +own new PABCD work phase and ordinary PR. + +## Exact evidence map + +- MODIFY `devlog/_plan/260927_release_train_4/clients-proxy/000_plan.md` + disposition rows when outcomes change. Before: candidate judgments at + `origin/dev` `24b2f39b77`; after: each row names actual lane PR, merge SHA, + source PR/issue state, and any residual hold. +- NEW a numbered outcome file under this unit, recording each PR head and + merge SHA, focused commands and their exits, required CI run IDs/URLs, + final `dev` run URL, and remaining cross-lane file overlaps. + +## Acceptance and proof + +Fetch latest `origin/dev`; for every lane PR, retain the exact pre-merge PR +head SHA and required-job run IDs that passed before merge. `ci.yml` does +not run on a push to `dev`, so after the merge resolve the integrated `dev` +commit and explicitly dispatch `gh workflow run ci.yml -R +lidge-jun/opencodex --ref dev -f lane=all`. Identify the resulting run by +`workflow_dispatch` event and exact `headSha`, then record its run ID, URL, +attempt, requested jobs and final conclusions. If `dev` moves before dispatch, +refresh the head and verify the run covers that newer integrated tree instead +of claiming evidence for an older SHA. Missing, skipped, cancelled, pending, +failed, and wrong-head results do not count as passing for requested jobs. +Compare changed paths +against other lane overlap in the final report. `git status --short` must +contain no unaccounted files, and each source PR/issue closure must point to +the actual integrated SHA.