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

9.6 KiB

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.