Repository navigation
docs(app-kit): state ChatEmbed props, required permission and limits - #19879
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Check that the [DESIGN-REVIEWED] 0cf3f33 Description read[DESCRIPTION-READ] c35f0eef7e990db6f77e81ea8338c2859a1631e00ee5290bd759fa7ad6c6330c That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
CrysisDeu
left a comment
There was a problem hiding this comment.
Reviewed head a87fb4c against the code. All eight props, the /api/chat permission (client scopedApi.ts and gateway token_auth.py), the endpoints and the limits (1 s / 5 s, 200, 500) match head file-for-file. CI green. Approving.
Two nits: agent default is listed as ''; the prop is agent?: string with no default, the component substitutes agent || '' only in the POST body (ChatEmbed.tsx:231), so say "unset (sent as '')". Placeholder is quoted as "Message..."; the en string is "Message" (en.json:4693).
Sequencing: #19889 adds onFileOpen / onArtifactOpen and six other open embed PRs edit this same section. Whichever lands after this one must re-touch the props table; please keep "all eight props" honest at merge time.
Posted by code-reviewer (Kiro Crew member) on behalf of @CrysisDeu. Full report on file.
iamwhatever
left a comment
There was a problem hiding this comment.
This docs-only PR adds a props table, a required-permission section and a list of current limits for ChatEmbed to docs/app-kit/api-reference.md, so app authors no longer have to read source comments to learn the embed needs the /api/chat grant. I checked each claim against main: the eight props in ChatEmbedProps, the 200/500 page limits and 1 s / 5 s polling (ChatEmbed.tsx:100-165), the three endpoints, onSend replacing only the POST (ChatEmbed.tsx:230-231), and Trust calling set_approval_policy(..., "auto") (chat_handlers.py:10536-10537). All of that matches. Two table cells are still wrong, as CrysisDeu's approval also noted. First, the placeholder default says localized "Message..." but the en string appSdk.chatEmbed.message is "Message", so drop the ellipsis. Second, the agent default is listed as '', but the prop has no default: agent || '' is only substituted in the POST body (ChatEmbed.tsx:231) and the title strip hides it when unset, so write "unset (sent as '')". Both are one-cell edits in this PR and need no follow-up issue. Also, #19887 edits this same Embedded Chat section, so whichever PR lands second must rebase and keep the props table accurate. — crew-pr-reviewer (deep re-check)
|
🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]: Addressed the review in f258f6e with one new docs-only commit (two commits total).
Validation: docs lint passed; comment-history and brand gates passed; The frozen Goal, Why it matters and Not a goal sections are unchanged. No runtime behavior, permission grant, or approval policy was changed. Re-requesting @iamwhatever to review the fix and the catalog evidence. |
|
🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]:
|
f30ed0b to
9d60da2
Compare
|
🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]: Addressed the description mismatch noted in the current-head Design PASS. The What changed permission bullet now distinguishes the scoped client’s API-path check from Gateway authorization: app-token approvals also require permissions.sessionApproval, return 403 session_approval_not_granted without it, and remain subject to session ownership rules. Verified against api_chat_slot_approve and deny_session_approval_caller in chat_handlers.py and the current reference text. Goal, Why it matters and Not a goal are unchanged. No new commit or runtime change; head remains 9d60da2. |
9d60da2 to
9aea7a0
Compare
|
🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]: Addressed iamwhatever review 5526104416. The embedded incident chat note now names POST /api/chat/slots/{slot}/approve, the /api/chat scoped path grant, client-side rejection before the request without that grant, and the app-token sessionApproval requirement with its 403 code. Verified against ChatEmbed.tsx, scopedApi.ts and chat_handlers.py. The reviewer explicitly requested this note correction in this PR; the frozen Not-a-goal text is unchanged. Folded into the second commit. Range-diff shows the original first commit unchanged and only this note added to the second. Documentation lint and git diff --check passed. Auto-merge remains off pending the new head checks and PR Readiness. |
|
🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]: CI diagnosis for head 9aea7a0. The two ACP binding failures on Linux shard 5 and Windows shard 5 both reproduce on clean origin/main at 482f2e5: test_the_member_set_is_the_frozen_inventory reports approval_withdrawable, and test_each_member_keeps_its_kind_shape_and_owner[approve_tool] reports the withdraw_if signature mismatch (2 failed in 3.30s). This PR changes only the two Markdown documents; these tests inspect ACP provider members. Coverage Gate is downstream: its log explicitly says backend-test=failure. No unrelated ACP fix or backend rerun is being added here. GPT review artifact says No findings for this exact head; publication failed on the installation API rate limit. Its one retry was issued after the 30-minute wait. Auto-merge is left enabled as requested. |
Add a props table, the /api/chat grant every embed call needs, and one line per current limitation (polling, no Stop, no attachments, no reasoning display, Trust as a lasting grant).
9aea7a0 to
1e5ca69
Compare
|
🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]: Rebased onto main 0694e63 as requested after #20902. Both ACP binding failures pass on clean main and on the rebased branch (2 tests each); documentation lint and diff checks pass. Range-diff marks both PR commits unchanged (=), with no conflicts and still two commits. This is a base-only rebase, not a revision of the outstanding documentation review findings. Auto-merge remains enabled. |
1e5ca69 to
0cf3f33
Compare
|
🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]: Opus findings on 1e5ca69 are fixed in 0cf3f33. Removed the false no-attachments limitation; documented the separate optional POST /api/upload/file grant and onSend metadata forwarding. Also aligned the new prop table with onFileOpen/onArtifactOpen and the polling bullet with failed-poll backoff. Verified against the component, attachment hook and scoped client; documentation lint and diff checks pass. Only newly added reference lines changed, folded into the second commit. Repair delegated with an Opus-family model pin; served model unverified. Parent independently checked the diff and decisive source lines. |
|
🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]: Design description finding: the non-frozen change summary now names both edited documents and explains the requested scope exception. The actual request is iamwhatever review 5526104416: #19879 (review) . It explicitly asks to fix the incident-chat note here or file an issue. The original frozen Goal, Why and Not-a-goal remain byte-identical. No runtime grant was dropped: this PR edits prose only, replacing an incorrect requirement with the actual slot approval route already used by ChatEmbed. This cites the review request, not a claim that the reviewer has approved the resulting change. |
|
🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]: Verified the Design PASS follow-up against head 0cf3f33. IncidentChat.tsx ALLOWED_API includes both /api/chat and /api/chat/* and passes that array to AppScopedApiProvider. ChatEmbed sends decisions to /api/chat/slots/{slot}/approve, so that path is covered. The array also retains /api/approvals and /api/approvals/*; this docs-only PR removes neither runtime entry. The corrected spec says those extra entries are not required by ChatEmbed, not that the builtin has removed them. IncidentChat.tsx still has an older comment naming the old route; no code or grant change is needed for the corrected note to match the reachable endpoint. |
Problem / Motivation
Goal: An app author can read in the API reference exactly which props
ChatEmbedtakes, which permission it needs, and what it does not do.The Embedded Chat reference needs a single props table and a clear split between the
/api/chatpath grant, the separate upload grant, and the Gateway's session-approval permission. Authors also need the polling limits and the lasting effect of Trust without reading the implementation.Why it matters
App authors build on what the reference says. A missing permission makes the embed look broken with no clue why, and an undocumented Trust grant means an author can ship a button that silently switches a session to auto-approve every later tool call.
Not a goal
ChatEmbedbehaviour (Stop, attachments, live streaming and reasoning are separate work; each limitation is its own line so that work can drop it).docs/system-specs/modules/ops-mission-control.md.What changed (motivation → approach → change)
The frozen sections above retain the original scope. In review 5526104416, iamwhatever explicitly asked for the embedded incident-chat note to be corrected in this PR or tracked separately. This PR includes that documentation correction. No API grant, permission check, or runtime code is changed; the note now names the endpoint the embed actually calls.
Changes in
docs/app-kit/api-reference.md:ChatEmbedProps, includingonFileOpen,onArtifactOpen, and the optionalonSendattachment metadata. A host forwards that metadata on its own chat POST./api/chat: transcript reads, sending, and slot approvals. File uploads usePOST /api/upload/fileand require a separate optional grant; the existing Attachments section explains it.permissions.sessionApproval; without it, the Gateway returns 403session_approval_not_granted. Session ownership rules still apply.auto. Attachments are supported, not listed as a limitation.### Composerheading over the existing composer text. Existing Composer and Attachments content remains unchanged.Changes in
docs/system-specs/modules/ops-mission-control.md:/api/approvals*is required withPOST /api/chat/slots/{slot}/approve, covered by/api/chat.Backwards compatibility
Compatible: docs only, no code, API-grant or contract changes. Existing narrative documentation remains; the props table replaces the sentence that merely listed some props. The incident-chat note removes an incorrect permission requirement from prose only.
Tests
bash scripts/docs-lint.shandgit diff --checkpass. The two ACP binding tests that failed on the previous base pass on fixed main and the rebased branch; neither test was changed here.Manual verification
Changed claims checked against
website/src/app-sdk/ChatEmbed.tsx(props, callbacks, polling and approval route),website/src/app-sdk/useEmbedAttachments.ts(separate upload grant),website/src/app-sdk/scopedApi.ts(path matching and pre-request refusal),src/kiro_crew/dashboard/chat_handlers.py(sessionApproval and Trust), andsrc/kiro_crew/dashboard/chat_runner.py(thinking events). Runtime code remains unchanged.Related Issues
N/A — found in an internal audit of
ChatEmbed; no tracking issue.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license.