feat(appkit): agent chat UI primitives

Signed-off-by: Hubert Zub <hubert.zub@databricks.com>

Author: hubertzub-db

apps/dev-playground/client/src/lib/agent-chat.ts

@@ -0,0 +1,38 @@
+import type { UIMessage } from "ai";
+
+/**
+ * AppKit-only data parts emitted by the client `ResponsesApiTransport`
+ * when it sees an `appkit.approval_pending` SSE event from the agents
+ * plugin. The transport exposes them via `useChat`'s `onData` callback;
+ * the route renders an approval card and POSTs the decision back to
+ * `/api/agents/approve`.
+ */
+// Declared as a `type` (not `interface`) so it structurally satisfies
+// the AI SDK's `UIDataTypes = Record<string, unknown>` constraint —
+// `interface`s lack the implicit string index signature `Record` wants.
+export type AgentDataParts = {
+  /**
+   * A destructive tool call is paused on the server-side approval gate.
+   * The client renders an approval card and POSTs the user's decision
+   * to `/api/agents/approve`. The approval gate auto-denies on timeout.
+   */
+  "approval-pending": {
+    approvalId: string;
+    streamId: string;
+    toolName: string;
+    args: unknown;
+    annotations?: {
+      effect?: "read" | "write" | "update" | "destructive";
+      readOnly?: boolean;
+      destructive?: boolean;
+      idempotent?: boolean;
+    };
+  };
+};
+
+/**
+ * Strongly-typed UIMessage for the AppKit agent chat. Used as the type
+ * parameter to `useChat<AgentUIMessage>()` so message metadata, data-part
+ * dispatch, and `onData` callbacks are all type-checked.
+ */
+export type AgentUIMessage = UIMessage<unknown, AgentDataParts>;