Add the missing chat widget + CSS; add 3 gaps found by a second E2E test

Ran a second independent end-to-end build test (fresh Copilot CLI session,
different domain: a "PTO approver" instead of the first test's "expense
approver") to verify the skill's snippets/simplification/bug-fixes actually
help. Result: 12/12 smoke checks, all 7 browser E2E scenarios passed with
screenshots, and verify.sh all green - and per the build's own report, the
bridge snippet worked "completely unmodified except for the AGENT_NAME
constant", azd ai agent init worked exactly as documented, and
verify.sh/smoke.py/browser_e2e.js needed only mechanical domain renames.
Total wall clock was roughly half the first test run's ~1 hour.

That run also surfaced one real, valuable gap: the skill's frontend snippets
only shipped providers.tsx (the <CopilotKit> wrapper + hook registrations)
but never the actual chat WIDGET every consumer needs. The builder had to
discover CopilotChat by reading the installed package's .d.ts files. Added:

- frontend/app/page.tsx - the CopilotChat widget, generalized from this
  run's real, working, screenshot-verified code.
- frontend/app/layout.tsx - minimal root layout wiring globals.css + Providers.
- frontend/app/globals.css - plain CSS (no Tailwind dependency) for the
  .hitl-card/.tool-card class names, so the approval card/tool cards render
  legibly instead of just being present in the DOM unstyled.

Verified these three files by swapping them into the actual test project and
confirming `npm run build` succeeds and the page renders correctly in a
headless browser (screenshot taken, matches expected UI).

Also added 3 troubleshooting.md entries and 1 HITL-section entry for gaps
this run's own REVIEW_NOTES.md flagged: in-memory hosted-agent state is
process-lifetime (restart between verification passes or approvals leak
across runs), a stale process can leave the hosted-agent port bound
(Address already in use on the next `azd ai agent run`), an occasional
transient DeploymentNotFound 404 on the very first request after startup
(retry/restart resolves it), and keeping a renamed gated-tool parameter name
in sync between the Python tool and the frontend's parsed-args cast.

Verified locally with `npx @microsoft/vally-cli lint`: 3/3 checks pass,
21/21 reference files reachable from SKILL.md.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: lordlinus

skills/foundry-hosted-agent-copilotkit/references/snippets/README.md

@@ -32,6 +32,9 @@ adaptation — just don't start there.
 | [`backend/bridge_app.py`](backend/bridge_app.py) | `backend/bridge_app.py` | The ENTIRE bridge in one file: FastAPI AG-UI endpoint, the streaming Responses HTTP client (DIRECT local / platform deployed), the Responses→AG-UI translation, HITL forwarding, and an SSE keep-alive. |
 | [`backend/requirements.txt`](backend/requirements.txt) | `backend/requirements.txt` | Bridge-only deps (no agent-framework/foundry packages — the bridge runs no model). |
 | [CopilotKit catch-all route (`route.ts`)](frontend/app/api/copilotkit/[[...slug]]/route.ts) | `frontend/app/api/copilotkit/[[...slug]]/route.ts` | CopilotKit runtime handler pointed at the bridge. |
+| [`frontend/app/layout.tsx`](frontend/app/layout.tsx) | `frontend/app/layout.tsx` | Root layout: imports `globals.css`, wraps children in `Providers`. |
+| [`frontend/app/page.tsx`](frontend/app/page.tsx) | `frontend/app/page.tsx` | **The actual chat widget** (`CopilotChat`) — the one piece of UI every consumer needs; easy to miss since `providers.tsx` only wraps it. |
+| [`frontend/app/globals.css`](frontend/app/globals.css) | `frontend/app/globals.css` | Plain CSS for the `.hitl-card`/`.tool-card` class names `ApprovalHitl.tsx`/`ToolCards.tsx` use — without this they're functionally correct but visually unstyled. |
 | [`frontend/app/providers.tsx`](frontend/app/providers.tsx) | `frontend/app/providers.tsx` | `<CopilotKit>` provider + HITL/tool-card component registration. |
 | [`frontend/components/ApprovalHitl.tsx`](frontend/components/ApprovalHitl.tsx) | `frontend/components/` | `useHumanInTheLoop` example for the gated tool. |
 | [`frontend/components/ToolCards.tsx`](frontend/components/ToolCards.tsx) | `frontend/components/` | `useRenderTool` examples for both tools. |

skills/foundry-hosted-agent-copilotkit/references/snippets/frontend/app/globals.css

@@ -0,0 +1,75 @@
+/* Minimal, framework-agnostic CSS for the .hitl-card / .tool-card class
+   names used by ApprovalHitl.tsx and ToolCards.tsx. No Tailwind or other
+   build-time CSS dependency required — plain CSS only. Import this from
+   your root layout (e.g. `import "./globals.css"` in app/layout.tsx). */
+
+body {
+  background: #ffffff;
+  color: #171717;
+  font-family: Arial, Helvetica, sans-serif;
+  margin: 0;
+}
+
+.hitl-card {
+  border: 2px solid #d97706;
+  background: #fffbeb;
+  border-radius: 8px;
+  padding: 12px 16px;
+  margin: 8px 0;
+}
+
+.hitl-card--done {
+  border-color: #16a34a;
+  background: #f0fdf4;
+}
+
+.hitl-card__title {
+  font-weight: 700;
+  color: #92400e;
+  margin-bottom: 6px;
+}
+
+.hitl-card__actions {
+  display: flex;
+  gap: 8px;
+  margin-top: 10px;
+}
+
+.hitl-card__actions button {
+  padding: 6px 14px;
+  border-radius: 6px;
+  border: 1px solid #999;
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.hitl-card__actions button[data-testid="hitl-approve-button"] {
+  background: #16a34a;
+  color: white;
+  border-color: #16a34a;
+}
+
+.hitl-card__actions button[data-testid="hitl-reject-button"] {
+  background: #dc2626;
+  color: white;
+  border-color: #dc2626;
+}
+
+.tool-card {
+  border: 1px solid #ccc;
+  background: #f8fafc;
+  border-radius: 8px;
+  padding: 10px 14px;
+  margin: 8px 0;
+}
+
+.tool-card__title {
+  font-weight: 600;
+  color: #334155;
+}
+
+.tool-card__result {
+  white-space: pre-wrap;
+  font-size: 13px;
+  margin-top: 6px;
+}

skills/foundry-hosted-agent-copilotkit/references/snippets/frontend/app/layout.tsx

@@ -0,0 +1,18 @@
+import type { Metadata } from "next";
+import "./globals.css";
+import { Providers } from "./providers";
+
+export const metadata: Metadata = {
+  title: "My Assistant",
+  description: "Internal chat assistant with human-in-the-loop approval",
+};
+
+export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}

skills/foundry-hosted-agent-copilotkit/references/snippets/frontend/app/page.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+import { CopilotChat } from "@copilotkit/react-core/v2";
+import { AGENT_NAME } from "../lib/agent";
+
+// The actual chat WIDGET — the one piece of UI every consumer needs that
+// isn't just plumbing. `providers.tsx` only wraps <CopilotKit> and registers
+// the HITL/tool-card hooks; this page renders the chat window itself.
+// `CopilotChat` takes the same `agentId` convention as the hooks (see
+// lib/agent.ts for why this is a separate identifier from the Foundry
+// hosted agent's own name).
+export default function Home() {
+  return (
+    <main style={{ maxWidth: 820, margin: "0 auto", padding: "24px" }}>
+      <h1 style={{ fontSize: 22, fontWeight: 600, marginBottom: 8 }}>My Assistant</h1>
+      <p style={{ color: "#555", marginBottom: 20 }}>
+        Ask about pending records, or ask to approve a specific record id — approvals require your
+        explicit confirmation.
+      </p>
+      <div style={{ height: "70vh", border: "1px solid #ddd", borderRadius: 8, overflow: "hidden" }}>
+        <CopilotChat agentId={AGENT_NAME} />
+      </div>
+    </main>
+  );
+}

skills/foundry-hosted-agent-copilotkit/references/troubleshooting.md

@@ -11,6 +11,9 @@ what you actually have installed before trusting it.
 | Symptom | Cause | Fix |
 | --- | --- | --- |
 | `python3 -m venv` fails (`ensurepip is not available`) or `pip`/`apt-get install python3-venv` needs sudo you don't have | sandboxed/managed dev environment without system Python tooling | check for `uv` (`which uv`) and use `uv venv` / `uv pip install` instead — it doesn't need `ensurepip` or root. |
+| `smoke.py`/`browser_e2e.js` fail (or pass for the wrong reason) when run back-to-back, or after an interrupted earlier attempt | the hosted agent's example in-memory store (`_RECORDS`/whatever dict you're using) is **process-lifetime** state — every approve/reject call, from any script, mutates the SAME shared data | restart the hosted agent process (`azd ai agent run` / `python main.py`) between independent verification passes to get back to the seeded starting state. Don't assume a fresh run starts clean if a previous script (or an interrupted tool call) already approved/rejected the same record ids. |
+| A new `azd ai agent run` fails with `Address already in use` (often with a confusing hypercorn traceback) | a previous local hosted-agent process from an earlier/interrupted session is still holding the port | find and stop the old process (`ss -ltnp \| grep 8088` or similar) before starting a new one. |
+| The very first request to a freshly-started local hosted agent 404s with `DeploymentNotFound`, even though the deployment demonstrably exists (`az cognitiveservices account deployment list` shows it) | occasional local-dev warm-up flake in the hosted runtime/SDK, not a real config problem | retry once, or restart the hosted agent process with the same env vars — this has been observed to resolve itself immediately on retry. |
 
 ## HITL / approval
 
@@ -21,6 +24,7 @@ what you actually have installed before trusting it.
 | Clicking Approve does nothing / tool never runs | assumed a specific resolve payload shape is framework-enforced | it isn't (see the CopilotKit bridge section below) — make sure your bridge's parser actually matches what the frontend's `respond(...)` sends. |
 | Approve works once, next message 400s with an orphaned tool-call id | stale/replayed approval payload re-sent to the hosted agent | don't replay raw history to the hosted agent; derive the next turn's input from the latest user text or the pending `mcp_approval_response`, chained via `previous_response_id`. |
 | Consequential tool runs WITHOUT asking | Tool missing `approval_mode="always_require"` | Decorate the consequential tool; check for at least one in your structural check. |
+| Approval card renders but shows the wrong/missing id or field when you renamed your gated tool's parameter (e.g. `record_id` → your own name) | the frontend's `ApprovalHitl.tsx` parses `function_arguments` and casts to a specific field name (`{ record_id?: string }` in the snippet) — this must match whatever parameter name your actual Python tool takes, since the bridge itself just forwards the model's raw arguments JSON verbatim | when you rename a gated tool's parameter, update the corresponding field name in the frontend's parsed-args cast to match — this is a presentation-only detail, not a bridge change. |
 
 ## AG-UI rendering (bridge-level)