Files
pipelines/app/notes/C4-approvals.md
T

149 lines
9.6 KiB
Markdown

# C4-approvals — native permission and question cards
One checked integration slice: the chat conversation now renders recorded
`chat_permission` frames and `form` question frames as native Material/Cupertino
cards, answers them through the landed `ChatRepository` request facade, and
records the outcome. App-only; no server, `web/`, Android/iOS, shell, route or
deployment source was edited.
## What changed
| File | Lines | Responsibility |
| --- | ---: | --- |
| `lib/features/chat/conversation/chat_permission_card_model.dart` | 192 | approval card derivation, risk/resource wording, decision labels, one-shot reply ids |
| `lib/features/chat/conversation/chat_permission_card.dart` | 267 | native approval card: kind/headline/status, six-line resources with full-request disclosure, risk panel, once/always/reject |
| `lib/features/chat/conversation/chat_question_card_model.dart` | 206 | field visibility/values, web validation messages, visible answers, form folding, answer ids |
| `lib/features/chat/conversation/chat_question_card_fields.dart` | 179 | editable field shell, free-text inputs, external-URL text |
| `lib/features/chat/conversation/chat_question_option_controls.dart` | 160 | native single/multi select and boolean controls |
| `lib/features/chat/conversation/chat_question_recorded_answers.dart` | 99 | read-only recorded answers, including unknown keys |
| `lib/features/chat/conversation/chat_question_card.dart` | 275 | pending/answered/expired question card, local answer state, submit/actions |
| `lib/features/chat/conversation/chat_transcript_card.dart` | 96 | card-row builder and small permission/question dispatcher |
| `lib/features/chat/domain/chat_transcript.dart` | +10/-2 | `transcriptRows(..., trailing:)` keeps cards after the message rows |
| `lib/features/chat/conversation/chat_thread_controller.dart` | +140 | folded permission/form frames, answers, errors and one-shot send gates |
| `lib/features/chat/conversation/chat_thread_view.dart` | +26/-6 | builds/dispatches card rows inside the existing conversation list |
| `app/PARITY.md` | row update | states the native cards as Source, with the real-request smoke still open |
| `test/.../chat_permission_card_test.dart` | 300 | model + native behaviour + pushed-frame integration |
| `test/.../chat_question_card_test.dart` | 360 | field rules + native behaviour + pushed-frame integration |
| `tool/chat_approvals_probe.dart` | 167 | real-widget fixture with a scripted replaying gateway |
| `tool/chat_approvals_probe.mjs` | 335 | Chrome CDP interaction, OCR assertions and captures |
Production files stay under the ~250-line aim except the two 267/275-line card
shells; the larger question work is split by responsibility (fields, option
controls, recorded answers) rather than arbitrary fragments.
## Behaviour
- **Permission card.** Kind line `Permission request · {source.type}` when the
server records one, else `Permission request`. Headline `Approve {action}`
(`Approve tool call` when blank). Status `Waiting for your response`.
Resources are the server's non-blank entries joined by newlines, displayed at
most six lines with an ellipsis on the last kept line; when truncated, the
native disclosure `Show full request` carries every recorded resource. The risk
panel uses the server's `message`, else the web's neutral sentence naming the
action, and shows only while pending or after a rejection. Controls use the
exact `Allow once` / `always_label or Always allow` / `Reject` labels and only
while pending.
- **Permission outcome.** Answering settles the card optimistically to the
decision label and `Waiting for the agent to continue…`. A server
`resolved`/`decision` frame always wins, shows the decision label (or
`Already resolved` when the recorded decision is blank) and its `message`/the
web's fallback note. A refusal clears the optimistic answer, keeps the card
pending, and shows the server reason in a live region.
- **Reply wire.** `ChatRepository.replyPermission` sends exactly
`{chat_reply:{session_id,request_id,decision,client:'Web'}}`; no extra field is
added. Each confirmed action has the stable local id
`chat-reply:{requestId}:{decision}` held by a `ChatActionGate`, so a double tap
sends once and a refused send reopens only that id for retry.
- **Question card.** Shows the recorded title (or `Question`) and
`The agent is waiting for your answer.`. Options keep the server's value/label
and description exactly; single-select is a radio group under Material and a
checkmark row under Cupertino, multi-select is checkboxes/checkmarks, booleans
are the explicit Yes/No menu under Material and checkmark rows under Cupertino.
Free text appears for `custom` fields or fields with no options, with number,
email, URL and date keyboards and secret input where recorded.
- **Question rules.** Visibility honours `hidden` and `when` (`eq`/`neq`).
Answers preserve `false` and `0`. Required missing answers, invalid
number/integer, min/max bounds, boolean type, string length and item counts
produce the web's exact messages; invalid input blocks the send and shows the
reason. Visible, non-external, answered fields alone travel in `chat_answer`.
`accept` is sent when the form lists it; `Decline` / `Cancel question` use the
recorded actions and an empty answer map.
- **Question outcome.** Submit is one-shot through the stable id
`chat-answer:{formId}:{action|answer}`. Success marks the form resolved locally
and shows `Answer recorded.`; the server's resolved/cancelled echo replaces it
with the recorded answers. `cancelled` shows `This question expired.`.
Read-only rendering includes answers for fields no longer present, and says
`No answer was recorded.` when the resolved form recorded none. A refusal keeps
the card pending with its typed state and shows the server reason.
- **Composition.** Cards follow the message rows in server order (permissions
then questions), keyed by request/form id so streaming repaints keep an open
disclosure or half-typed answer. Unknown message parts still render through the
existing plain `Unrecognised part` disclosure; nothing in `ChatMessageView` or
the markdown renderer changed.
## Checks actually run (after the final split)
- `flutter analyze` — `No issues found!`
- `flutter test` — `All tests passed!` (1003 tests, including the 20 new focused
card/model/controller cases)
- `flutter build web --output build/web-acceptance` — `✓ Built`
- `node tool/chat_approvals_probe.mjs` for both hosts — see below.
## Browser fixture evidence
The fixture runs the **real** `ChatThreadView`/controller against a scripted
gateway that replays one pending `chat_permission` and one `form` question on
subscribe, then echoes the reply/answer back as a resolved frame. Chrome CDP at
320px logical width, device scale 2, dark appearance, both hosts. Static card
text is OCR-verified because Flutter web paints it on the canvas; controls are
driven through semantics.
Captures and evidence (shared run artifacts):
- `public/chat-approvals-probe/material-cards.png`
- `public/chat-approvals-probe/material-approval-answered.png`
- `public/chat-approvals-probe/material-question-answered.png`
- `public/chat-approvals-probe/material-evidence.json`
- `public/chat-approvals-probe/cupertino-cards.png`
- `public/chat-approvals-probe/cupertino-approval-answered.png`
- `public/chat-approvals-probe/cupertino-question-answered.png`
- `public/chat-approvals-probe/cupertino-evidence.json`
Each run asserted the pending card's recorded action, status, risk, resource
lines and all three control labels; that `Allow once` sent the reply (the fixture's
server resolution replaced it with `Allowed once` and cleared the controls); and
that selecting `Red` + `Send answer` sent the answer and produced the read-only
`Answer recorded.` card. Both runs finished with `sendAnswerStillVisible:false`
and `allowOnceStillVisible:false`. The Material capture also shows no clipped
text at 320/2x; the Cupertino capture uses only Cupertino controls (widget tests
assert no `Material` ancestor in that host).
## Limits, stated plainly
- **No live server request was answered.** The fixture's gateway is scripted and
its reply/answer responses are local; no operator chat, run, approval or real
server was mutated.
- **No authenticated smoke yet.** The `PARITY.md` row remains Source, not Preview:
a real pending approval/question against the authenticated server, and a
multi-client server resolution, are still unverified.
- **Web only.** Android/iOS builds, ADB, emulators and device/OS behavior were not
run (per the app working agreement); source is portable but mobile is
unverified.
- **External question forms** display only their recorded HTTP(S) URL as
selectable text; no URL launcher dependency exists in this app, so they are not
opened from the card. Unsupported URLs show the web's alert wording instead.
- **Uncommitted.** The pipeline input asked for a candidate commit, but the stage
instructions explicitly say not to commit, push or deploy, so the work is left
in the working tree (`flutter/chat-approvals`) with no commit or merge.
## Manager completion after a harness transport failure
The run ended on a harness transport error (`/api/session/active`) after a full
Code visit; the retained tree was complete. Manager verified 173 chat tests,
clean analysis, and the both-host browser probe. Two probe expectations were
corrected against the web rather than against the app: the approval card's
headline is the recorded action (the web has no separate "Permission request"
heading), and OCR merges whitespace, so comparisons now ignore it and accept a
control that is present in the semantics tree. No app behaviour was changed to
make the probe pass.