feat(instance): add an Operations console for sending any operations-API request

[dawsontoth]

Folded in

This PR now carries the whole stack, rebased in a straight line on stage (20 commits, no merge commits), so one Rebase and merge lands all four:

• fix(api): replay a gateway error only for reads, so a write is never sent twice #1891: a gateway error (502/503/504) is replayed only for reads, so a write is never sent twice.
• fix(errors): say a write's outcome is unknown when it got no verdict, not that it failed #1897: a write that got no answer reads as "outcome unknown", not as failed, across every write surface, including import, redeploy and staged-release activation.
• fix(restart): say a restart Harper accepted is not back yet, never that it failed #1899: a restart Harper accepted reads as not back yet, never as failed. The cluster restart loop and the rolling config loop both stop at a member that hasn't come back.

Each of those PRs keeps its own verification and cross-model review record. On the top commit, the full suite (522 files), tsc -b, oxlint and dprint check all pass.

Decided in review:

• Keep fix(errors): say a write's outcome is unknown when it got no verdict, not that it failed #1897's staged-release activation fix.
• Keep fix(restart): say a restart Harper accepted is not back yet, never that it failed #1899 stopping before a member's restart when Cancel is pressed during that member's config write, and reporting its config as pending.
• Keep fix(restart): say a restart Harper accepted is not back yet, never that it failed #1899's wait on a member with no verdict, which can add up to about 7 minutes per member.
• Don't split fix(errors): say a write's outcome is unknown when it got no verdict, not that it failed #1897.

⊙ Problem

Studio has no way to send an arbitrary operation to an instance. The APIs tab is an explorer for the REST port's OpenAPI document (/api/openapi/rest, built from exported resources), and Harper publishes no spec for the operations API. So anything Studio has no page for (system_information, get_analytics, a component's own operation, a one-off sql) means leaving Studio for curl, with credentials copied out of it. #1283 asks for a JSON box that sends to the instance as the signed-in user.

❓ Your call: is the requirement right at this size? I built the minimal slice: one request at a time, no history, no autocomplete, no Cmd+Enter. The alternative is a fuller console (operation-name autocomplete from the role editor's catalog, request history, cURL export). Everything here is additive, so any of that can follow without reworking this.

💡 Solution

A new Operations tab on every instance and cluster, for super users. It holds a Monaco JSON editor (prefilled with {"operation": "describe_all"}) and a Send button, with the status, duration and pretty-printed response (or Harper's error) shown inline underneath. The request goes through the same getInstanceClient client every other page uses, so direct, basic-auth, local and central-manager-proxied connections all work unchanged.

What makes a raw console safe to put in front of a super user:

• Only Harper's own reads go straight through. Everything else opens a confirmation showing the exact body. A read is the restart gate's naming rule (get_/search_/describe_/list_/read_…), and the name must also appear in Studio's catalog of Harper's operations, because a component can register a mutating get_….
• The typed text is sent as-is, at most once. Re-serializing the parse would round integers past 2^53, a primary key among them. A new skipGatewayRetry flag opts the request out of the shared client's 502/503/504 replay.
• Studio is told about the side effects it has to know about. A console restart is tracked with markRestarting until the target answers again, as DESIGN.md requires of any flow that takes an instance down, so the page's polls ride out the outage. logout is refused: it would end the session the rest of Studio is still using.
• Nothing leaves the page. Failures render inline and never go through console.error (RUM reports it) or the global React Query handlers. The buffer is not persisted, because bodies carry passwords and secrets. The console remounts per instance, so a confirmation written for one can never be sent to another. Anything that reached Harper, an error answer included, marks entity queries stale without refetching them.

⚖️ Alternatives

❓ Your call: which requests should confirm? I chose to confirm everything except Harper's built-in reads. The brief asked for a small list of destructive names (drop_*, delete_*, set_configuration, restart…), but the planning reviewer showed that a denylist misses sql DROP/DELETE, alter_role, approve_agent_action and any component operation. The reviewer's own preference was to confirm every request, reads included; I rejected that because reads are most of what a console sends, and confirming describe_all teaches people to click through. Changing it is a one-line predicate change.

❓ Your call: who sees the tab? I gated it on super_user (useInstanceManagePermission), like APIs, Status, Logs, Config and Applications. A non-super user who deep-links in is sent to Databases. Harper authorizes every operation itself (verifyPerms), so this gate is about visibility, not security. Opening it to every signed-in instance user is the alternative and would work, since Harper would refuse what their role can't do. It is a one-line change.

❓ Your call: the 5 MB response limit is progress-bounded, not exact. The cross-model reviewer rated it a blocker because XHR only reports progress about every 50 ms, so a fast response can arrive in full before the abort fires. I overruled that. The only browser adapter that enforces maxContentLength is axios's fetch adapter, and it unconditionally adds a User-Agent request header (axios/lib/adapters/fetch.js). Harper's operations-API CORS allowlist is Content-Type, Authorization, Accept (harper server/operationsServer.ts), so in a browser that sends that header every direct-connect preflight would fail. Display is still truncated at the API explorer's 512,000 characters, so the DOM never receives an unbounded body.

• Extend the APIs explorer instead: rejected. It is driven by the REST OpenAPI spec and sends with its own fetch, which bypasses the instance client's restart gate, Bearer refresh, 401 recovery and proxy routing.
• A typed form per operation: rejected. Harper has no operation-schema discovery (Surface role operation-level grants (permission.operations) in the roles/users UI #1627), so ~110 operations' fields would be hand-maintained across 4.x/5.x.

🔧 Changes

The page

• src/features/instance/operations/index.tsx:
  • OperationsIndex gates on useInstanceManagePermission. It renders nothing while the instance user is still loading, so a super user is never bounced, and sends a non-super user to Databases.
  • The console is keyed by entity, because TanStack Router keeps the page mounted across a param change.
  • send holds a synchronous in-flight ref. It tracks a restart with markRestarting and releases it on a 4xx, otherwise once the target answers again.
  • It marks entity queries stale with refetchType: 'none' for any non-read that reached Harper, and skips state updates after unmount.
  • submit refuses logout and confirms everything that is not a built-in read.
  • The confirmation dialog keeps the last request through its close animation.
  • ResultView shows the status badge and body, the too-large notice, or the "may or may not have run" failure.
• src/features/instance/operations/routes.ts is the lazy operations route, the same createXRouteTree(instanceLayoutRoute) shape as Logs and Status. src/features/instance/routes.ts mounts it in local, cluster and instance mode, keeping getParentRoute and addChildren in lockstep.
• src/features/instance/InstanceNavBar.tsx: the Operations entry, behind canManage.

The request

• src/features/instance/operations/sendOperation.ts:
  • Posts the raw text with responseType: 'text' and skipGatewayRetry, and passes skipRestartGate through for a tracked restart.
  • Abandons the download once progress passes MAX_RESPONSE_BYTES, then formats the body with the explorer's formatResponseBody.
  • Never throws. A caller gone before dispatch, a restart-gate refusal or a replaced connection count as unsent. Anything abandoned mid-flight, and everything else left unanswered, may have run.
• src/features/instance/operations/parseOperationRequest.ts requires a single JSON object with a string operation, and returns the text untouched.
• src/features/instance/operations/operationKinds.ts: isBuiltInRead is the read naming rule plus getOperationInfo from the role editor's catalog.

Shared pieces this touches

• src/integrations/api/isReadOperation.ts is the restart gate's read regex, moved unchanged so both callers share one rule. src/lib/restart/restartGate.ts now calls it with unchanged behavior, and its operationOf comment now notes the console's string bodies.
• src/integrations/api/retryGatewayErrors.ts: a skipGatewayRetry request flag, checked before __retryCount is touched. It is off by default, so no existing call changes.
• src/integrations/api/instance/status/restartInstance.ts: waitUntilAnsweringAfterRestart is extracted from restartInstance, whose behavior is unchanged, so the console waits the same way the Restart button does.
• src/features/instance/databases/modals/recordEditorJson.ts: tryParseJson is split out of tryParseRecordJson, which is unchanged. Also fixed: withoutEngineLocation now strips V8's after JSON at position N (line L column C) too. The record editors were printing that location twice (seen in the browser here as Line 1, column 57: … at position 56 (line 1 column 57)).
• src/features/instance/applications/components/Chat/tools/getUserContext/execute.ts: the chat agent now says the user is in the operations console, instead of describing the last focused file.
• DESIGN.md: a new "Operations console" section with the rules and where each is enforced, and a pointer from the restart section to isReadOperation.

✅ Verification

End-to-end against a real Harper (4.7.40 in a throwaway loopback container, generated test credentials):

• Through the real getInstanceClient interceptor chain and jsdom's XHR: describe_all, create_database and create_table answered 200. An unknown operation answered 400 Operation 'not_a_real_operation' not found and a missing table 404, both rendered as Harper's body. A 6,000-record insert answered 200. A search_by_value returning ~6 MB came back too-large from real progress events, and the same search with limit: 2 came back normally.
• Browser: the page ran in local-studio mode against that container (pnpm dev:local, signed in with the test user). Monaco loaded with no console errors and no DI errors. describe_all sent immediately. A typo produced Line 1, column 57: … inline, which cleared on edit. create_database opened the confirmation with the exact body, sent once on confirm, and answered 200. Cancel on drop_database sent nothing, and the dialog kept its content through the close animation. describe_table on a missing table rendered the 404 body inline. No console.error came from the page; the one console line is the browser's own resource-404 log. Not exercised end-to-end: Harper 5.x and the central-manager proxy (no stage session in this environment).

Unit and component tests: mutation-checked, meaning each guard was reverted locally and its test went red.

• src/features/instance/operations/index.test.tsx:
  • Sending: a read goes straight away. A non-read confirms; Cancel sends nothing; confirming sends exactly the typed body, once. A component get_… confirms. logout is refused. A double click inside one act sends once.
  • Validation: invalid JSON is refused inline with its line and column. A body with no operation is refused, and the message clears on edit.
  • Restart: tracked until the target answers, released on a 4xx, and kept on a 502.
  • Errors and staleness: a write that got an error answer still marks data stale. Harper's 403 renders inline and console.error is never called. An unanswered write "may or may not have run". A write abandoned on unmount still marks data stale.
  • Lifecycle: switching instance discards a pending confirmation. A non-super user is redirected, and nothing redirects before the user loads.
• src/features/instance/operations/sendOperation.test.ts runs the real getInstanceClient (restart gate, replication check and gateway retry installed) with a custom adapter:
  • The typed text is sent verbatim, a 2^53+ integer included. JSON is pretty-printed, non-JSON passed through, and a 4xx body rendered.
  • 502/503/504 are each sent exactly once, while ordinary requests on the same client still retry. The cap aborts above the limit and not at it.
  • Unanswered requests are classified: timeout, restart-gate refusal (with a real markRestarting), gate bypass, caller gone before send, abandoned mid-flight, and connection replaced.
• src/features/instance/operations/parseOperationRequest.test.ts, src/features/instance/operations/operationKinds.test.ts and src/integrations/api/isReadOperation.test.ts cover the validation, the built-in-read rule, and the shared read rule's anchoring.
• src/integrations/api/retryGatewayErrors.test.ts: the flag stops a 502/503/504 replay without touching __retryCount.
• src/features/instance/databases/modals/recordEditorJson.test.ts: the "after JSON" wording loses its duplicated position and keeps the location.
• src/router/__tests__/orgUndefinedRepro.test.ts checks that cluster and instance /operations deep links keep organizationId/clusterId/instanceId. src/features/instance/InstanceNavBar.test.tsx checks the entry is shown to a super user and hidden from anyone else.

Gates (real exit codes, Node 24.21.0, through the husky pre-commit hook): full vitest run passed 401 files, 3,760 tests, exit 0. tsc -b exit 0, oxlint exit 0, dprint check exit 0, and commitlint passed.

Cross-model review: four rounds, codex (gpt-5.6-sol, graded) and gemini (3.1-pro-high) on each; the last was a full round on the squashed head. Planning review came first; it returned better-alternative-exists, and I adopted most of it: raw-text send, no gateway replay, stale-only invalidation, memoized client, and confirming far more. The read-allowlist part I overruled, as in Alternatives. Implementation rounds found and fixed: the console not remounting per entity, read-looking component operations skipping confirmation, restart/logout bypassing Studio's coordinators, in-flight cancellation reported as unsent, state updates after unmount, 5xx treated as not applied, and 4xx skipping stale-marking. I rejected, on evidence:

• Gemini's "the body is sent untrimmed": axios's stringifySafely returns the trimmed string for a JSON string body, and the test asserts the trimmed body.
• Gemini's "restart_service is an outage too": useRestartInstanceClick marks only restart, because restart_service keeps answering.
• Gemini's "the restart gate parses every console body": its interceptor runs only while holdsRequests(…) is true, i.e. only while the entity is tracked as restarting.
• Gemini's "an operation of " restart ", with spaces, skips tracking": Harper resolves operations by exact Map.get(json.operation) (serverUtilities.ts), so that name is an unknown operation, a 400, not a restart.
• Gemini's "the restart gate holds a confirmed component get_… write": it can't duplicate. The in-flight guard blocks a second send, and leaving the page aborts the held request through the gate's signal handling.

The XHR cap remains open as a reviewer blocker; it is the third ❓ above. I left one nit unaddressed: codex called tryParseJson's doc comment narration. Coverage gap: the Cursor legs failed every round with no-receipt (the 1Password SSH agent refused to sign the review CLI's fetch), and the Harper domain adjudicator failed auth (expired Claude OAuth), so no round was adjudicated.

Also found: #1879 (filed, P3): every instance client replays a 502/503/504 for every operation, so a write whose answer a gateway lost runs twice. The console opts out here; the rest of Studio still replays.

Closes #1283
Closes #1879
Closes #1890
Closes #1895

_{🤖 Generated with Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

Related PRs: none found
Complexity: medium

_{Review-Coverage: authored=claude; ran=codex,gemini; blocked=cursor-muse(no-receipt),cursor-composer(no-receipt),domain(auth); declined=cursor-grok,cursor-kimi; rounds=4; full=1 @ aaca36e}

_{Review-Attention: study ~9m (raised: degraded review) @ aaca36e}

[gemini-code-assist]

Code Review

This pull request introduces a new Operations Console feature under the 'Operations' tab for instances and clusters, allowing super users to send freeform operations-API requests. The console includes features such as request validation, confirmation prompts for mutating operations, inline error rendering, and specialized handling for restart operations. Key changes include the addition of the operations route, navigation bar integration, and extensive unit tests. Under the hood, read operation detection was refactored into a shared utility, and Axios was updated to support skipping gateway retries for non-idempotent requests. There are no review comments to address, and I have no additional feedback to provide.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	77.37%	13288 / 17173
🔵	Statements	77.33%	14107 / 18242
🔵	Functions	72.24%	3499 / 4843
🔵	Branches	72.26%	10426 / 14428

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/auth/describeAuthFailure.ts	100%	100%	100%	100%
src/features/cluster/domains/Management.tsx	91.08%	87.69%	90%	92.78%	100, 127, 264-275, 283, 289-290
src/features/clusters/components/ClusterCard.tsx	54.02%	82.97%	25.92%	54.76%	107-119, 123-124, 127, 130-163, 267-296, 382, 457-496
src/features/instance/InstanceNavBar.tsx	100%	96.15%	100%	100%
src/features/instance/routes.ts	100%	100%	100%	100%
src/features/instance/applications/components/Chat/tools/describeToolError.ts	100%	50%	100%	100%
src/features/instance/applications/components/Chat/tools/createApp/execute.ts	75%	50%	50%	75%	21-23, 75-91
src/features/instance/applications/components/Chat/tools/deleteTableRecords/execute.ts	0%	100%	0%	0%	12-29
src/features/instance/applications/components/Chat/tools/dropComponentFile/execute.ts	0%	100%	0%	0%	11-24
src/features/instance/applications/components/Chat/tools/getUserContext/execute.ts	0%	0%	0%	0%	11-88
src/features/instance/applications/components/Chat/tools/insertTableRecords/execute.ts	0%	100%	0%	0%	12-29
src/features/instance/applications/components/Chat/tools/restartHTTPService/execute.ts	77.77%	100%	100%	77.77%	42-52
src/features/instance/applications/components/Chat/tools/setComponentFile/execute.ts	0%	100%	0%	0%	13-32
src/features/instance/applications/components/Chat/tools/updateTableRecords/execute.ts	0%	100%	0%	0%	12-29
src/features/instance/applications/components/NewApplication/useImportApplication.ts	91.78%	82.6%	100%	91.54%	112-116, 118-122, 137-140, 174-175
src/features/instance/applications/hooks/useRenameFiles.tsx	56.66%	35%	40%	55.93%	27, 36, 76, 88, 97-100, 111, 117-169
src/features/instance/applications/modals/RedeployApplicationModal.tsx	75.22%	51.94%	91.66%	74.77%	103, 126-141, 162-169, 173, 179, 197, 211-213, 225-234, 246, 334-344
src/features/instance/applications/modals/RenameFileModal.tsx	37.03%	14.28%	50%	36.53%	40, 47-48, 82-143, 148-149
src/features/instance/applications/modals/reportDeployHealth.ts	84.61%	73.58%	100%	84%	63-67, 72-91
src/features/instance/config/deployments/components/ActivateStagedRelease.tsx	100%	81.25%	100%	100%
src/features/instance/config/secrets/SecretGrantsEditor.tsx	0%	0%	0%	0%	30-78
src/features/instance/databases/components/DatabaseTableView.tsx	72.33%	73.84%	64.91%	71.95%	269, 402-405, 450-459, 636-650, 695-711, 715-723, 732-740, 746-774, 785, 809, 835-850, 857-861, 864-891, 907, 911, 941-942, 1083-1093
src/features/instance/databases/modals/recordEditorJson.ts	70.58%	76%	88.88%	69.69%	70-88
src/features/instance/operations/index.tsx	98.71%	88.15%	100%	98.7%	96
src/features/instance/operations/operationKinds.ts	100%	100%	100%	100%
src/features/instance/operations/parseOperationRequest.ts	100%	100%	100%	100%
src/features/instance/operations/routes.ts	50%	100%	50%	50%	8-9
src/features/instance/operations/sendOperation.ts	91.66%	80.64%	100%	91.17%	102-105
src/features/instance/secrets/SecretModals.tsx	88.88%	85.96%	92.3%	88.88%	130-132, 287-288, 308-309
src/features/organization/roles/modals/AddOrganizationRoleModal.tsx	65.62%	69.23%	50%	65.62%	73, 82, 92-98, 152, 170-198
src/features/organization/roles/modals/EditOrganizationRoleModal.tsx	45.61%	56.86%	33.33%	46.42%	43, 63-67, 102-118, 144, 151-187, 280-310
src/features/organization/settings/index.tsx	72.6%	66.66%	64.7%	74.64%	85-86, 126, 127, 139-143, 150-151, 156-157, 162-165, 204, 268-374, 409-410, 484-485
src/features/organization/users/modals/EditUserModal.tsx	0%	0%	0%	0%	36-172
src/hooks/useApplyLicensesClick.tsx	93.02%	84.84%	50%	92.85%	122, 133, 154
src/hooks/useRestartClusterClick.tsx	93.15%	96.15%	63.63%	92.85%	38, 84, 206, 217, 240
src/hooks/useRestartInstanceClick.ts	89.65%	73.07%	50%	89.65%	43, 84, 98
src/hooks/useRollingConfigUpdate.tsx	95.65%	98.61%	71.42%	95.5%	118, 260, 271, 295
src/integrations/api/isReadOperation.ts	100%	100%	100%	100%
src/integrations/api/retryGatewayErrors.ts	100%	100%	100%	100%
src/integrations/api/unansweredWrite.ts	100%	91.66%	100%	100%
src/integrations/api/instance/applications/packageComponent.ts	66.66%	100%	100%	66.66%	34
src/integrations/api/instance/secrets/secrets.ts	91.3%	89.47%	85%	90.9%	139-146
src/integrations/api/instance/status/restartInstance.ts	100%	100%	100%	100%
src/integrations/api/instance/status/restartUnconfirmed.ts	100%	96.29%	100%	100%
src/integrations/api/sse/resolveInstanceConnection.ts	100%	91.3%	100%	100%
src/lib/restart/restartGate.ts	97.56%	90.9%	100%	97.29%	94
src/react-query/queryClient.ts	98.18%	100%	85.71%	98.18%	121

Generated in workflow #2324 for commit 6cd6fbc by the Vitest Coverage Report Action