Skip to content

docs(app-kit): state ChatEmbed props, required permission and limits - #19879

Merged
buluoray merged 2 commits into
mainfrom
docs/embed-contract
Oct 15, 2026
Merged

buluoray merged 2 commits into
mainfrom
docs/embed-contract

Conversation

@buluoray

@buluoray buluoray commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An app author can read in the API reference exactly which props ChatEmbed takes, 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/chat path 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

  • Changing any ChatEmbed behaviour (Stop, attachments, live streaming and reasoning are separate work; each limitation is its own line so that work can drop it).
  • Rewriting the Native Chat Panel or other sections.
  • Correcting the embedded-chat note in 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:

  • A table for all ten current ChatEmbedProps, including onFileOpen, onArtifactOpen, and the optional onSend attachment metadata. A host forwards that metadata on its own chat POST.
  • The three chat endpoints covered by /api/chat: transcript reads, sending, and slot approvals. File uploads use POST /api/upload/file and require a separate optional grant; the existing Attachments section explains it.
  • App-token approvals additionally require permissions.sessionApproval; without it, the Gateway returns 403 session_approval_not_granted. Session ownership rules still apply.
  • Poll cadence and the 200/500-row window, including failed-poll backoff; no Stop or reasoning display; Trust sets the session's approval policy to auto. Attachments are supported, not listed as a limitation.
  • A ### Composer heading over the existing composer text. Existing Composer and Attachments content remains unchanged.

Changes in docs/system-specs/modules/ops-mission-control.md:

  • Replace the incorrect claim that /api/approvals* is required with POST /api/chat/slots/{slot}/approve, covered by /api/chat.
  • Distinguish the scoped client's pre-request path check from the Gateway's app-token approval permission check.

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.sh and git diff --check pass. 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), and src/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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners October 13, 2026 18:50
@buluoray
buluoray requested a review from mbriones98 October 13, 2026 18:50
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 13, 2026
@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 0cf3f337fef891107cebd727543a5cf311d6c5f3 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that the ops-mission-control builtin's allowedApiPaths really matches the corrected note before the spec drops /api/approvals*.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 0cf3f337fef891107cebd727543a5cf311d6c5f3 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 0cf3f337fef891107cebd727543a5cf311d6c5f3 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 0cf3f337fef891107cebd727543a5cf311d6c5f3 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0cf3f33

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 0cf3f337fef891107cebd727543a5cf311d6c5f3: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 0cf3f337fef891107cebd727543a5cf311d6c5f3 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 0cf3f33

Verdict parsed from the review's SHA-scoped output markers for commit 0cf3f337fef891107cebd727543a5cf311d6c5f3.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 0cf3f337fef891107cebd727543a5cf311d6c5f3: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 13, 2026
CrysisDeu
CrysisDeu previously approved these changes Oct 13, 2026

@CrysisDeu CrysisDeu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 14, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 14, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]:

Addressed the review in f258f6e with one new docs-only commit (two commits total).

  • Agent default: fixed. ChatEmbedProps declares agent?: string; the component has no destructuring default, and the title strip renders the name only when truthy. The default cell now says "unset (sent as '')" and the description says the title shows it when set. Current main's appSendWire.ts also uses agent: agent || ''.
  • Placeholder: verified and retained, with the exact key added. The requested removal of the ellipsis does not match the loaded English catalog. website/src/i18n/locales/en.json does not define appSdk.chatEmbed.message; its cited "Message" line belongs to a different section. website/src/i18n/locales/en.manual.json defines this key as "Message...". enCatalog.ts merges generated English with manual English, with manual leaves winning. I executed the actual catalog module and passed its result through i18next: t('appSdk.chatEmbed.message') returned "Message...". The same manual value is present on current main. The table now names the key so this can be checked without confusing the two catalogs.
  • Merge sequencing / current behavior: the interface still declares the same eight props on current main. The branch is mergeable without rebasing. Main now reads send receipts through appSendWire and sendTurn, so I removed this PR's stale assertion that the response stream is discarded. The replacement only states the shared fact: replies are displayed from the transcript poll, not from the send response. Later embed changes still need to keep this table and the limitations accurate.
  • AI lanes: the reviewed old head had Design PASS, First Principles and UX skipped, and GPT / Opus no findings. No out-of-scope implementation request remains, so no follow-up issue is needed.

Validation: docs lint passed; comment-history and brand gates passed; git diff --check passed. The agent-default assertion fails on the previous doc and passes on the updated doc. The placeholder assertion matches the executed English translation. The local gate's backend selection passed all 109 tests. Its frontend selection could not start because this worktree lacks Vite dependencies; no frontend code changed, and CI will validate the new head.

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.

@buluoray
buluoray requested a review from iamwhatever October 14, 2026 15:26
@buluoray

buluoray commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Kiro Crew Auto-Pipeline [operator: buluoray#19879]:

  • fixed — embed approval permission (span=5d6a61faa450)

Fixed in 9d60da2. The embedded-chat reference now distinguishes the scoped client's API-path check from the Gateway's authorization check. App-token approvals also require permissions.sessionApproval; without it, the Gateway returns 403 session_approval_not_granted, even for the app's own slots. The text links to the existing Approvals ownership rules.
Verified against src/kiro_crew/dashboard/chat_handlers.py:9070-9115 and :10261-10266: the approve handler invokes deny_session_approval_caller, which checks the live grant before allowing an app caller. This is a documentation correction only; no permission or runtime behavior changes.
Validation: scripts/docs-lint.sh and git diff --check pass. A focused document assertion rejects the prior wording and passes with the correction. All previous-head workflow runs completed before this push; the legacy readiness status was still pending. The two fix commits were squashed with owner approval. The PR now contains two commits. Range-diff preserves the original commit, and the final tree is byte-identical to f30ed0b.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 14, 2026
@buluoray
buluoray force-pushed the docs/embed-contract branch from f30ed0b to 9d60da2 Compare October 14, 2026 16:41
@buluoray

Copy link
Copy Markdown
Contributor Author

🤖 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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 14, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

🤖 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.

@buluoray
buluoray requested a review from iamwhatever October 15, 2026 16:48
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 15, 2026
@buluoray
buluoray enabled auto-merge (squash) October 15, 2026 17:01
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 15, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

🤖 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).
@buluoray
buluoray force-pushed the docs/embed-contract branch from 9aea7a0 to 1e5ca69 Compare October 15, 2026 17:37
@buluoray

Copy link
Copy Markdown
Contributor Author

🤖 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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 15, 2026
@buluoray
buluoray force-pushed the docs/embed-contract branch from 1e5ca69 to 0cf3f33 Compare October 15, 2026 17:49
@buluoray

Copy link
Copy Markdown
Contributor Author

🤖 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.

@buluoray

Copy link
Copy Markdown
Contributor Author

🤖 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.

@buluoray

Copy link
Copy Markdown
Contributor Author

🤖 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.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 15, 2026
@buluoray
buluoray merged commit e76c563 into main Oct 15, 2026
105 of 113 checks passed
@buluoray
buluoray deleted the docs/embed-contract branch October 15, 2026 21:36
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants