feat!: spec'd /qqq/v1 assistant endpoints; tools on core's UiApiInvoker (QQQ RC.6) #19

2026-10-13T19:44:39Z

KofTwentyTwo commented

2026-10-13 19:44:39 +00:00

(Migrated from github.com)

Spec'd `/qqq/v1` assistant endpoints; tools on core's `UiApiInvoker` (QQQ 4.1.0-RC.6)

This was a draft until a QQQ release had qqq#1128. QQQ 4.1.0-RC.6 has it, so the PR now builds against Central. I took it over from the earlier assistant agent and merged in everything on develop since: P-a through P-g, answer presentation, bulk-load tools (#38) and the provider-api split.

What it does

The assistant's endpoints are spec'd operations. The UI API extension assistant is at 1.0.0 with prefix /assistant. It covers config, conversations, turns and events (text/event-stream), cancel, feedback, actions and access.
- URLs, bodies and statuses are unchanged.
- The operations appear in /qqq/v1/openapi.yaml. The committed fragment and its baseline are checked by core's UiApiContract.check.
- The raw routes are removed.
Every tool runs through core's UiApiInvoker (CoreUiApiGateway), with the caller's UiApiCredentials. LoopbackUiApiGateway is deleted.
- Client channel: assistant/<turnId>, and for scheduled runs assistant/scheduled/<taskId>. Core sets it server side.
- Form params: passed to withFormParam.
- Extra headers (X-QQQ-AI-Route): these go through HeaderedUiApiInvoker. It is a stand-in, marked STAND-IN(core=QRun-IO/qqq#1190, removeBy=RC.8), with a test that reserved headers are dropped.
- Scheduled-run login: the designated user still logs in through a plain manageSession call, the same login a UI client does.
Classification: core's DataClassification replaces the qbit stand-in, which is deleted (the rest of #28). The default source merges core metadata with the config map.
History: core's default wall denies audit* to the assistant. Owner decision: that is a hard wall. So get_record_history is offered only when a host explicitly opts its audit tables in. The opt-in is documented and tested both ways, and kof22 does not opt in.

Tests

./mvnw verify passes against RC.6: 320 tests, 1 skipped (Docker-only), with the JaCoCo gates met. Coverage includes:

AssistantRouteProviderTest through the spec'd endpoints;
the UiApiToolsSecurityTest denial matrix through the invoker;
the golden and red-team evals;
ArchUnit;
scheduled tasks;
RAG, presentation and bulk-load.

Stacked next: X1/Y1, which covers deny registration for every assistant_* object, a startup check, admin-denied tests, audit clientChannel and auditHref. #21 (write mode) follows after core Preferences (qqq#1162).

🤖 Generated with Claude Code

## Spec'd `/qqq/v1` assistant endpoints; tools on core's `UiApiInvoker` (QQQ 4.1.0-RC.6) This was a draft until a QQQ release had qqq#1128. QQQ **4.1.0-RC.6** has it, so the PR now builds against Central. I took it over from the earlier assistant agent and merged in everything on develop since: P-a through P-g, answer presentation, bulk-load tools (#38) and the provider-api split. ### What it does - **The assistant's endpoints are spec'd operations.** The UI API extension `assistant` is at 1.0.0 with prefix `/assistant`. It covers config, conversations, turns and events (`text/event-stream`), cancel, feedback, actions and access. - URLs, bodies and statuses are unchanged. - The operations appear in `/qqq/v1/openapi.yaml`. The committed fragment and its baseline are checked by core's `UiApiContract.check`. - The raw routes are removed. - **Every tool runs through core's `UiApiInvoker`** (`CoreUiApiGateway`), with the caller's `UiApiCredentials`. `LoopbackUiApiGateway` is deleted. - **Client channel:** `assistant/<turnId>`, and for scheduled runs `assistant/scheduled/<taskId>`. Core sets it server side. - **Form params:** passed to `withFormParam`. - **Extra headers (`X-QQQ-AI-Route`):** these go through `HeaderedUiApiInvoker`. It is a stand-in, marked **STAND-IN(core=QRun-IO/qqq#1190, removeBy=RC.8)**, with a test that reserved headers are dropped. - **Scheduled-run login:** the designated user still logs in through a plain `manageSession` call, the same login a UI client does. - **Classification:** core's `DataClassification` replaces the qbit stand-in, which is deleted (the rest of #28). The default source merges core metadata with the config map. - **History:** core's default wall denies `audit*` to the assistant. Owner decision: that is a hard wall. So `get_record_history` is offered **only** when a host explicitly opts its audit tables in. The opt-in is documented and tested both ways, and kof22 does not opt in. ### Tests `./mvnw verify` passes against RC.6: 320 tests, 1 skipped (Docker-only), with the JaCoCo gates met. Coverage includes: - `AssistantRouteProviderTest` through the spec'd endpoints; - the `UiApiToolsSecurityTest` denial matrix through the invoker; - the golden and red-team evals; - ArchUnit; - scheduled tasks; - RAG, presentation and bulk-load. **Stacked next:** X1/Y1, which covers deny registration for every `assistant_*` object, a startup check, admin-denied tests, audit `clientChannel` and `auditHref`. #21 (write mode) follows after core Preferences (qqq#1162). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qbit-assistant#19

feat!: spec'd /qqq/v1 assistant endpoints; tools on core's UiApiInvoker (QQQ RC.6) #19

Spec'd /qqq/v1 assistant endpoints; tools on core's UiApiInvoker (QQQ 4.1.0-RC.6)

What it does

Tests

Spec'd `/qqq/v1` assistant endpoints; tools on core's `UiApiInvoker` (QQQ 4.1.0-RC.6)