docs: row 330 P4 brief as the Console proxy page; Q250 amendments to the Vikunja 237 design
Jason's Q46 and Q47 (DECISIONS Q250, mos-1606): accounts are entered in the Console's own proxy page and D8's /proxy/ forward to the upstream panel is dropped. The new P4 brief is its own file so the rows doc blob that rows 329 and 331-333 pin stays unchanged. Design D5-D8, D10, D20, migration step 4, J3-J5, the rows table and the Mos rulings list are amended.
This commit is contained in:
1 parent
0ce22dde65
commit
696ea3a3af
2 files changed
+167
-39
No files matched your search
@@ -0,0 +1,129 @@
|
||||
# Brief: row 330 (P4), the Console proxy page
|
||||
|
||||
Written 2026-10-24 by Sage for Mos's mos-1606, which carries Jason's Q46 and Q47 answers (DECISIONS Q250).
|
||||
Read the design (`docs/plans/2026-10-24_stack-model-proxy.md`, amended for Q250) and the rows doc
|
||||
(`docs/plans/2026-10-24_model-proxy-rows.md`) first. The rows doc's "Rules for every row" apply here
|
||||
unchanged. Line numbers are at origin/refactor 0ce22dde6. Check them before you edit.
|
||||
|
||||
This brief replaces two parts of the rows doc:
|
||||
- its P4 brief (the `/proxy/` forward to the upstream panel, rows doc :118-182), which is dropped with D8;
|
||||
- P1's two panel acceptance bullets (rows doc :104-108). P1's finding on the OAuth callback URL for Claude
|
||||
and Codex still counts, and this row uses it.
|
||||
|
||||
The rows doc isn't edited, because every row from 329 to 333 pins that file's blob and row 329 is near its
|
||||
landing. The P4 brief lives here instead.
|
||||
|
||||
## Brief: P4 the Console proxy page
|
||||
|
||||
**Why.** Q250: Jason enters accounts in the Console's own proxy page, not in the upstream panel. The page
|
||||
calls bus routes, and the bus calls the proxy's management API (D12). The management key stays in the bus
|
||||
(D6). No new hostname is added. A panel subdomain is a fallback only if our page can't keep up with the
|
||||
management API across pinned proxy upgrades, and that call is Jason's (Q46).
|
||||
|
||||
**What ships.**
|
||||
|
||||
1. **Bus verbs.** New broker verbs for the page, for example `proxy.accounts`, `proxy.login.start`,
|
||||
`proxy.login.submit`, `proxy.login.status`, `proxy.login.cancel`, `proxy.priority.set` and
|
||||
`proxy.keys`. Settle the names in BUILD.md.
|
||||
- Every verb is human-only. A tester, agent or granted-user caller refuses `human-required`, the way
|
||||
the grants admin verbs do (`packages/bus/src/broker.mjs`:3721-3731).
|
||||
- With no proxy in the validated config (P1 item 3), every verb refuses `not-configured`.
|
||||
- Each verb calls the management client from P1 (`packages/model-proxy/src/client.mjs`). P4 adds the
|
||||
calls it needs under P1's rules: the key goes only in the `Authorization` header, only to loopback,
|
||||
and each call writes a receipt with no body and no secret.
|
||||
- A proxy that doesn't answer refuses `proxy-down`, with no retry.
|
||||
2. **Accounts.** `proxy.accounts` lists the upstream accounts from the pinned version's credentials
|
||||
endpoint (`/credentials` in the 8.0.27 doc,
|
||||
`agents/researcher/work/i1-proxy-test/docs/management-api-v8.0.27.md`:101).
|
||||
- The bus copies only allowlisted fields: provider, a display name, status and priority, plus an
|
||||
account id (the first 12 hex of a sha256, as for key ids). Every other field is dropped, so no token
|
||||
can pass through even if the proxy returns one.
|
||||
- Record in BUILD.md which endpoint and fields the pinned version has.
|
||||
3. **OAuth sign-in** through `oauth/auth-url`, `oauth/callback` and `oauth/status`
|
||||
(management-api-v8.0.27.md:108-138).
|
||||
- **Start.** The page picks a provider from an allowlist: `claude` and `codex`. Adding a provider is a
|
||||
reviewed change. The bus calls `auth-url` and returns the authorization URL and the `state`. The page
|
||||
opens the URL in a new tab with `noopener` and `noreferrer`.
|
||||
- **Return.** After Jason signs in, the provider redirects to the callback URL that the proxy named.
|
||||
P1's acceptance records that URL for each provider. If the redirect reaches the proxy directly, the
|
||||
status poll shows the result. If it doesn't, Jason pastes the full URL from the address bar into the
|
||||
page, and the bus POSTs it to `oauth/callback` as `redirect_url`.
|
||||
- **Checks on a pasted URL.** It must parse as a URL, stay under a size limit, and carry a `state` that
|
||||
this bus started and that hasn't finished. Anything else refuses `login-state-unknown` or
|
||||
`callback-url-invalid`. The URL carries the authorization code, so it is never logged, stored or
|
||||
echoed back.
|
||||
- **Status.** Only an `ok` from `oauth/status` counts as signed in. An accepted callback with status
|
||||
`wait` doesn't, because the doc says acceptance isn't completion (:136-138). The bus stops polling
|
||||
on `ok`, `error`, or after a timeout setting (default 300 s).
|
||||
- **Cancel** calls `DELETE oauth/session`.
|
||||
4. **Priority.** `proxy.priority.set` sets one account's priority, an integer in a range the builder
|
||||
records. Use the pinned version's credential-field endpoint (`/credentials/fields` PATCH in the 8.0.27
|
||||
doc). Confirm it on the stand-in and record what it changes. A bad account id or value refuses
|
||||
`priority-invalid`.
|
||||
5. **Client keys, list only.** `proxy.keys` reads `GET /config/access/api-keys`, maps each value to its key
|
||||
id in memory and drops the value (D15).
|
||||
- It joins P2's record to show agent, issue time and state for each key id.
|
||||
- The sentinel is labelled. A key without this instance's prefix shows as "not stack-managed".
|
||||
- The page has no key write. Issue and revoke stay with hire and fire (P2).
|
||||
6. **Usage.** P5's Console view (rows doc P5 item 3) sits on this page. Whichever of P4 and P5 lands
|
||||
second puts it there. P4 adds no usage source.
|
||||
7. **The page and its Console routes.** An owner-only `/proxy` page in `packages/webui`, built like the
|
||||
existing pages, with routes under `/api/proxy/`.
|
||||
- Each route makes one call over the owner's human transport, the way the Agents section does
|
||||
(`AGENT_ROUTES` at `packages/webui/src/serve.mjs`:451, `agentCaller` at
|
||||
`packages/webui/src/console-bus.mjs`:12). `consoleBus` gets a `PROXY_VERBS` list, and the caller
|
||||
refuses any other verb.
|
||||
- Writes need a signed-in owner, the Console's own `Origin`, `sec-fetch-site: same-origin`, `--send`
|
||||
and a named host, as `agentSend` checks (`serve.mjs`:459-470). The routes are refused for a granted
|
||||
user (`userRoute`), on the tester listener and on a loopback Host.
|
||||
- The Console never holds the management key, never reads `proxy` from the config, and never opens a
|
||||
connection to the proxy port.
|
||||
- Logs record method, route, status and user only. They never record the authorization URL, a pasted
|
||||
callback URL, a state or a body.
|
||||
8. **Upgrade check.** An acceptance script, beside P1's and outside the gate's `scripts/test-*.sh` set,
|
||||
runs the bus verbs against the pinned binary under `unshare -rn`. It uses a made-up config, key and
|
||||
data root in a fresh temp root, the same way P1's run does.
|
||||
- With no network, it checks what can be checked offline. The account list starts empty. `auth-url`
|
||||
returns a URL and a state for `claude` and for `codex`. A callback with a made-up code never reports
|
||||
`ok`. A priority set on a made-up credential reads back, if the stand-in can hold one. The key list
|
||||
returns ids only.
|
||||
- It prints the endpoints and fields the page relies on, so a version change shows up as a diff.
|
||||
- `packages/model-proxy/README.md` records the rule: a PIN change lands only with this script's output
|
||||
for the new version in that row's BUILD.md, and Sage's landing gate checks for it.
|
||||
- If the script fails on a new version and the row can't fix the page, the row stops. Sage takes Q46's
|
||||
fallback to Jason through Mos.
|
||||
|
||||
**Tests.** Cover each of these:
|
||||
- every verb against a fake management server;
|
||||
- each refusal code by its own test (mos-1590): `not-configured`, `human-required` for the tester, an
|
||||
agent and a granted user, a provider outside the allowlist, `login-state-unknown`,
|
||||
`callback-url-invalid`, `priority-invalid` and `proxy-down`;
|
||||
- a fake that puts token-like values in every credential field, where no value reaches a response, log or
|
||||
receipt;
|
||||
- a fake key list with full values, where only ids come back, the sentinel is labelled and a foreign key
|
||||
is marked;
|
||||
- no authorization URL, callback URL, code or state in any log or receipt;
|
||||
- an accepted callback with status `wait` not reported as signed in;
|
||||
- the Console routes: owner allowed, and a granted user, the tester listener, a loopback Host, a
|
||||
signed-out request, a cross-origin request and a request without `sec-fetch-site` each refused, and
|
||||
every write read-only without `--send`;
|
||||
- no `packages/webui` module imports the model-proxy client or reads the `proxy` config.
|
||||
|
||||
**Out of scope.**
|
||||
- Upstream API keys such as z.ai. Mos's list for the page (mos-1606) doesn't name them, and entering one
|
||||
means a secret crosses the Console. Sage has asked Mos. Until Mos rules, the page has no API-key entry.
|
||||
- Removing or disabling an account, and every routing setting other than account priority.
|
||||
- Issuing or revoking client keys (P2), and any usage source (P5).
|
||||
- The upstream panel, any forward to the proxy port, and the subdomain fallback.
|
||||
- Traefik, DNS, Authentik settings, and the .54 Console's provider (Q218).
|
||||
- Any live instance, the management key, and the 8317 proxy.
|
||||
|
||||
**Order.** P4 starts when P1 lands, because it needs P1's client and config contract. It rebases on P2
|
||||
before its gate, for the key join, and lands after P2.
|
||||
|
||||
**Gate.** Gladstone gives the first Codex review, and Filbert reviews the landing candidate. The model-proxy,
|
||||
bus and webui suites run whole, webui with `MOSAIC_REQUIRE_EDITOR_BUILD=1`. Every touched test file runs
|
||||
whole. The named mutants below are killed. Every package suite but queue plus every `scripts/test-*.sh` is
|
||||
green on Sage's landing gate. BUILD.md has the upgrade-check output on the pinned version. Mutants: the
|
||||
accounts verb returns an unfiltered field; the callback verb skips the state check; a `/api/proxy/` route
|
||||
accepts a granted user.
|
||||
@@ -5,6 +5,12 @@ becomes the stack's credential and routing layer, with Q116 and Q127 still in fo
|
||||
Mos rules it before any code. Its build rows go to new Codex gpt-6.1-sol threads (Q246), and each gets its own
|
||||
brief once Mos has ruled. Line numbers are at origin/refactor 2ce476d54.
|
||||
|
||||
**Amendments.** Mos's mos-1600, mos-1601 and mos-1602 changes live in the row briefs
|
||||
(`docs/plans/2026-10-24_model-proxy-rows.md`), which win over this design where they differ. Jason's Q46
|
||||
and Q47 answers (DECISIONS Q250, mos-1606, 2026-10-24) are written into this file: accounts are entered in
|
||||
the Console's own proxy page, and the `/proxy/` forward to the upstream panel (D8) is dropped. The P4 brief
|
||||
for that page is `docs/plans/2026-10-24_proxy-page-brief.md`. Text marked "(Q250)" below is that change.
|
||||
|
||||
Not to be confused with queue row 237 ("one decision lands once", `2026-10-20_agent-credentials.md`). This is
|
||||
Vikunja task 237.
|
||||
|
||||
@@ -75,11 +81,13 @@ whose sha256 matches PIN. The control panel asset is pinned the same way, with
|
||||
(`config.example.v8.0.27.yaml`:94-103), and that would be unreviewed code behind Authentik. The stack never
|
||||
copies the 8317 binary. The first fetch of the release asset counts as external access, so it is Jason's
|
||||
step J1 or a row Mos approves. For containerized installs the binary and panel go into the proxy image
|
||||
(section 8).
|
||||
(section 8). Q250: nothing serves the panel to the Console now. P1 keeps the pin as built, and
|
||||
removing it is a later cleanup.
|
||||
|
||||
D5. **Initial config, then hands off.** The stack writes `config.yaml` once, when `<dataRoot>/proxy/` is
|
||||
first created, from a template in `packages/model-proxy/`, and never writes the file again. After that the
|
||||
stack changes the proxy only through the management API, and Jason changes it only through the panel.
|
||||
stack changes the proxy only through the management API, and Jason changes it only through the Console's
|
||||
proxy page, which calls the bus, which calls the management API (Q250).
|
||||
Row 96 point 2 (every management write rewrites the whole file and reorders it) then stops mattering,
|
||||
because nobody edits the file by hand. The template sets the defaults in section 3 and section 7,
|
||||
`request-retry: 0` so no hidden retries happen (as in row 96), the client-key list holding only the
|
||||
@@ -93,31 +101,22 @@ prompt doesn't echo the key. It writes the key to `<configDir>/secrets/proxy-man
|
||||
the initial `config.yaml`. The proxy hashes it in place on its first start (row 96 point 6). The stack reads
|
||||
only the secrets file, never the hashed value in config. The holder is the bus process alone (D12). The
|
||||
sandbox doesn't mount `<configDir>/secrets`, so no session can read the key, and no verb returns it. Jason
|
||||
types the same key into the panel to sign in. An agent never runs the prompt (Q173).
|
||||
types the key only at that prompt. The Console's proxy page needs only his Console sign-in, and the bus adds
|
||||
the key to its own management calls (Q250). An agent never runs the prompt (Q173).
|
||||
|
||||
D7. **Upstream credentials.** Jason adds every upstream account in the proxy's own panel: OAuth sign-ins
|
||||
(Claude, Codex and the others CLIProxyAPI supports) and API keys (for example z.ai). They live in the
|
||||
D7. **Upstream credentials.** Accounts are entered in the Console's proxy page (Q250). It covers OAuth
|
||||
sign-ins for Claude and Codex through the management API's `oauth/auth-url`, `oauth/callback` and
|
||||
`oauth/status`, and account priority. Whether the page also takes upstream API keys (for example z.ai) is
|
||||
open with Mos. They live in the
|
||||
proxy's `auth/` directory and config and nowhere else. There is no per-seat credential file. The stack never
|
||||
reads, copies or logs an upstream credential.
|
||||
|
||||
D8. **Panel path.** The Console forwards `https://mosaic.woltje.com/proxy/` to `127.0.0.1:<proxy.port>`, for
|
||||
the panel route and the management routes only. It forwards only after its existing auth-header and
|
||||
allowed-user check (decision 103, `packages/webui/src/serve.mjs`:453-469) passes. The Console never adds or
|
||||
stores the management key. Jason types it in the panel, and it passes through the forward. This adds no DNS
|
||||
record and no subdomain, as Q116 requires. Traefik and the tunnel already deliver mosaic.woltje.com to the
|
||||
Console (7332), so no infra change is needed. The forward gives no new authority. The management key
|
||||
is the barrier, and loopback processes can already reach the proxy port. Authentik is the outer layer. The
|
||||
#385 hole (a loopback process forging the Host and header) applies here the same way and is no worse,
|
||||
since the management key is still required.
|
||||
|
||||
A second Console (.54) forwards to its own instance's proxy, and its Authentik provider settings are Jason's
|
||||
(Q218).
|
||||
|
||||
Checks for the build row, on a stand-in under `unshare -rn` as in row 96:
|
||||
- the pinned panel works under the `/proxy/` sub-path (rewrite or base-path setting);
|
||||
- an OAuth sign-in done from the panel through the forward completes. If the callback can't return through
|
||||
the forward, the fallback is Jason running the proxy's CLI login in his own shell (`-claude-login
|
||||
-no-browser` and similar), and J3 says so.
|
||||
D8. **Dropped (Q250).** The design had the Console forward `https://mosaic.woltje.com/proxy/` to the
|
||||
proxy's own panel. Jason's Q46 and Q47 answers replace it with the Console's own proxy page (D7). The page
|
||||
calls bus routes, the bus calls the management API (D12), and the management key stays in the bus (D6). No
|
||||
new hostname is added. A panel subdomain is a fallback only if our page can't keep up with the management
|
||||
API across pinned proxy upgrades, and that call is Jason's. Each pinned upgrade runs the page's acceptance
|
||||
script against the new version (P4 brief item 8).
|
||||
|
||||
## 3. Priority routing, and how the business routing table maps onto it
|
||||
|
||||
@@ -131,10 +130,12 @@ The proxy picks which upstream account serves that model. The two don't overlap:
|
||||
- Account failover inside one model is the proxy's job. The stack doesn't model accounts per session.
|
||||
|
||||
D10. **Priority settings.** Defaults set in the template are listed below (Q222: settings with defaults).
|
||||
Jason can change all of them in the panel.
|
||||
Jason sets account priority in the Console's proxy page. The other routing settings keep the template
|
||||
defaults, and a page control for them is a later row (Q250).
|
||||
- `routing.strategy: fill-first`. A subscription account is used until it is rate-limited or out of quota, then
|
||||
the next one (`config.example`:150).
|
||||
- Each account gets a `priority` (larger first, `config.example`:480). Jason sets the order in the panel (J4).
|
||||
- Each account gets a `priority` (larger first, `config.example`:480). Jason sets the order in the Console's
|
||||
proxy page (J4).
|
||||
- `routing.session-affinity: true`, so a session stays on one account while it works and keeps its prompt
|
||||
cache (:154-171). Default `session-affinity-rebind-on: quota`, so a transient 5xx doesn't move a session.
|
||||
- No model aliases or alias pools by default. A pool that maps one name to several upstream models
|
||||
@@ -270,7 +271,7 @@ D20. **Settings and who changes them.** Every number in this design is a setting
|
||||
`rotateBy` 30 d, `proxy.rotateGraceMinutes` 120, `proxy.firstOutputSeconds` 120, `usage.cliproxyQueue.pollSeconds`
|
||||
15, routing strategy fill-first, affinity on. The per-key daily quota and the rotation period guard the human
|
||||
from agents, so only a human can change them (Q222). The routing settings live in the proxy and only Jason
|
||||
changes them, in the panel.
|
||||
changes them. Account priority is in the Console's proxy page, and the rest keep their defaults (Q250).
|
||||
|
||||
## 8. Row 157 re-scope (#1652, Vikunja 617)
|
||||
|
||||
@@ -297,7 +298,7 @@ changes. Cutover, per instance, with Jason present (Q127):
|
||||
2. Jason fetches and verifies the pinned binary and panel (J1). ops-01 or Sage checks the sha256 against PIN.
|
||||
3. Jason adds the `proxy` section to the instance config (J2), runs `mosaic proxy init` (D6), and starts
|
||||
`mosaic-proxy.service`. The bus isn't restarted yet.
|
||||
4. Jason signs in to the panel and adds the accounts (J3, J4). No session uses the proxy yet.
|
||||
4. Jason adds the accounts in the Console's proxy page (J3, J4). No session uses the proxy yet.
|
||||
5. A Console or bus restart (Jason or Mos, per Q173) picks up the section. The bus reconciles, issues a key
|
||||
for each listed agent, and runs D17's preflight for each one. Any refusal stops the cutover, and the fix
|
||||
is to remove the section and restart.
|
||||
@@ -318,15 +319,13 @@ accounts (J7). The 8317 host proxy and its clients are not part of any step.
|
||||
- **J2.** Add `"proxy": { "port": <port from the cutover note>, "binary": "<path>" }` to the instance's
|
||||
`config.json`, in an editor.
|
||||
- **J3.** In a terminal of your own, run `mosaic proxy init` and type a new management key twice. Keep it in your
|
||||
password manager. Then open `https://mosaic.woltje.com/proxy/` and sign in to Authentik as jason.woltje.
|
||||
Paste the management key into the panel's login box.
|
||||
- **J4.** In the panel's auth or OAuth page, sign in to each subscription account you want this instance to use
|
||||
(Claude, Codex, and so on). On the API keys page, paste each API key you want it to have (for example z.ai).
|
||||
Set each account's priority. The highest one is used first, and the next one only when the first is
|
||||
limited. If an OAuth sign-in doesn't return to the panel, run the CLI login the cutover note gives, in your
|
||||
own terminal.
|
||||
- **J5.** Watch the Console while the two test sessions run (cutover step 6), and confirm the panel's usage page
|
||||
shows their requests on the account you expect.
|
||||
password manager. You don't type it anywhere else (Q250).
|
||||
- **J4.** Open the Console's proxy page and sign in to Authentik as jason.woltje. Sign in to each subscription
|
||||
account you want this instance to use (Claude, Codex). If the sign-in tab doesn't return on its own, copy
|
||||
the full address from that tab and paste it into the page. Set each account's priority. The highest one is
|
||||
used first, and the next one only when the first is limited. API keys such as z.ai wait on Mos's ruling.
|
||||
- **J5.** Watch the Console while the two test sessions run (cutover step 6), and confirm the proxy page's usage
|
||||
section shows their requests on the account you expect.
|
||||
- **J6.** After 7 days on the proxy, delete `claude-session.env` for that instance.
|
||||
- **J7.** For Melanie's .54 hub, decide which accounts it uses: hers, yours, or new ones. Then do J2 to J4 on .54
|
||||
through its own Console's Authentik provider (Q218). Only accounts you entered for that hub go into its
|
||||
@@ -339,10 +338,10 @@ credentials, so a Claude reviewer (Dewey) gives the second review. Sage runs the
|
||||
|
||||
| Row | Piece | Depends on |
|
||||
|---|---|---|
|
||||
| P1 | `packages/model-proxy/`: PIN, template, management client, `mosaic proxy init`, the `mosaic-proxy` unit, config `proxy` section, stand-in tests (empty list, `/v1/models` local, 401 shape, panel sub-path, OAuth through the forward) | Mos's ruling on D3 |
|
||||
| P1 | `packages/model-proxy/`: PIN, template, management client, `mosaic proxy init`, the `mosaic-proxy` unit, config `proxy` section, stand-in tests (empty list, `/v1/models` local, 401 shape, OAuth callback URL; the panel checks are dropped, Q250) | Mos's ruling on D3 |
|
||||
| P2 | Per-agent keys: `model` store kind, issue, rotate, revoke, reconcile, D17 preflight | P1, rows 194 and 199 |
|
||||
| P3 | Harness config: Claude Code env, pi `models.json` and preflight, `sessionEnv` proxy mode | P2 |
|
||||
| P4 | Console `/proxy/` forward behind the existing auth check | P1 |
|
||||
| P4 | The Console proxy page and its bus verbs (Q250, `2026-10-24_proxy-page-brief.md`) | P1; lands after P2 |
|
||||
| P5 | `usage` plug-in kind and the `cliproxy-queue` module; key ids in `launch.limits.tokens` | P2 |
|
||||
| P6 | Row 157 brief amendment (section 8) | Row 157 resuming |
|
||||
| P7 | Cutover note and per-instance window (section 9) | P1 to P4 landed; Jason present |
|
||||
@@ -353,7 +352,7 @@ The Codex harness config (D16) goes with the Codex harness row, which isn't on t
|
||||
|
||||
1. D1/D3: the `proxy` section in the instance config (a schema change), and the proxy as its own user unit.
|
||||
2. D6: the management key set by Jason at a human-only prompt and held only by the bus process.
|
||||
3. D8: the Console forwards `/proxy/` rather than a new Traefik route.
|
||||
3. D8: ruled. Jason's Q46 and Q47 (Q250) drop the forward for the Console's own proxy page.
|
||||
4. D13: an implicit per-agent model key with no role-file change.
|
||||
5. D15: plaintext keys at rest accepted under those limits.
|
||||
6. D16: proxy mode drops the instance-wide provider variables from every session.
|
||||
|
||||
Reference in new issue
Block a user