feat: Add AI Elements Integration with Agents

- Created a Product Requirements Document (PRD) for integrating AI Elements with agents, detailing the problem statement, goals, user stories, scope, success metrics, dependencies, and risks.
- Developed a comprehensive task list for the integration, including tasks for creating context providers, agent configurations, and various UI components.
- Implemented critical fixes for AI SDK v5 compatibility, updating deprecated types and patterns in chat components.
- Established a task overview with status, priority, estimates, and dependencies for each task related to the integration.
- Defined acceptance criteria for each task to ensure clear deliverables and expectations.
- Included implementation notes and code snippets for clarity on how to approach each task.
- Outlined progress tracking phases to monitor the completion of foundational, core UI, enhanced features, and integration/testing tasks.

Author: ssdeanx

.github/instructions/boom.instructions.md .github/-/boom.instructions.md.github/instructions/boom.instructions.md renamed to .github/-/boom.instructions.md

@@ -1,6 +1,7 @@
 ---
+name: Next.js Best Practices
 description: This rule provides comprehensive guidance for Next.js development, covering code organization, performance, security, testing, and common pitfalls. It helps developers build robust, scalable, and maintainable Next.js applications by adhering to community-accepted best practices and coding standards.
-applyTo: ['**.js', '**.jsx', '**.ts', '**.tsx', '**/next.config.js', '**/pages/**', '**/app/**']
+applyTo: "**.js, **.jsx, **.ts, **.tsx, **/next.config.ts, **/pages/**, **/app/**, **/src/components/**, **/ui/**, **/lib/**, **/types/**, **/hooks/**"
 ---
 # Next.js Best Practices
 
@@ -19,10 +20,6 @@ This document outlines best practices for developing Next.js applications, focus
     *   `route.ts`: Defines server-side route handlers (API routes).
     *   `[dynamic-segment]`: Dynamic route segments, using brackets.
     *   `@folder-name`:  Route Groups to organize routes without affecting URL structure.
-*   **`pages/`**: (Legacy - Before Next.js 13) Contains page components.
-    *   `api/`: Serverless functions (API routes).
-    *   `_app.js/tsx`: Custom App component (wraps all pages).
-    *   `_document.js/tsx`: Custom Document component (control the entire HTML document).
 *   **`components/`**: Reusable UI components.
 *   **`lib/`**: Utility functions, helper functions, and third-party integrations.
 *   **`hooks/`**: Custom React hooks.
@@ -36,9 +33,9 @@ This document outlines best practices for developing Next.js applications, focus
 ### File Naming Conventions
 
 *   **Components:** `ComponentName.jsx` or `ComponentName.tsx`
-*   **Pages:** `page.js`, `page.jsx`, `page.ts`, `page.tsx` (within the `app` or `pages` directory)
+*   **Pages:** `page.js`, `page.jsx`, `page.ts`, `page.tsx` (within the `app`)
 *   **Layouts:** `layout.js`, `layout.jsx`, `layout.ts`, `layout.tsx` (within the `app` directory)
-*   **API Routes:** `route.js`, `route.ts` (within the `app/api` directory or `pages/api` directory)
+*   **API Routes:** `route.js`, `route.ts` (within the `app/api` directory)
 *   **Hooks:** `useHookName.js` or `useHookName.ts`
 *   **Styles:** `ComponentName.module.css` or `ComponentName.module.scss`
 *   **Types:** `types.ts` or `interfaces.ts`

…nstructions/instructions.instructions.md .github/-/instructions.instructions.md.github/instructions/instructions.instructions.md renamed to .github/-/instructions.instructions.md .github/instructions/instructions.instructions.md renamed to .github/-/instructions.instructions.md

@@ -1,4 +1,5 @@
 ---
+name: Self-explanatory Code Commenting
 description: 'Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with less comments. Examples are in JavaScript but it should work on any language that has comments.'
 applyTo: '**'
 ---

.github/instructions/next-js.mdc …hub/instructions/next-js.instructions.md.github/instructions/next-js.mdc renamed to .github/instructions/next-js.instructions.md .github/instructions/next-js.mdc renamed to .github/instructions/next-js.instructions.md

@@ -1,4 +1,5 @@
 ---
+name: Taming Copilot
 applyTo: '**'
 description: 'Prevent Copilot from wreaking havoc across your codebase, keeping it under control.'
 ---

.github/instructions/self-explanatory-code-commenting.instructions.md

@@ -0,0 +1,90 @@
+"use client"
+
+import {
+  Artifact,
+  ArtifactHeader,
+  ArtifactTitle,
+  ArtifactDescription,
+  ArtifactActions,
+  ArtifactAction,
+  ArtifactClose,
+  ArtifactContent,
+} from "@/src/components/ai-elements/artifact"
+import { CodeBlock } from "@/src/components/ai-elements/code-block"
+import { CopyIcon, DownloadIcon } from "lucide-react"
+import { useCallback } from "react"
+import { BundledLanguage } from "shiki"
+
+export interface ArtifactData {
+  id: string
+  title: string
+  description?: string
+  type: "code" | "markdown" | "json" | "text"
+  language?: string
+  content: string
+}
+
+export interface AgentArtifactProps {
+  artifact: ArtifactData
+  onClose?: () => void
+}
+
+export function AgentArtifact({ artifact, onClose }: AgentArtifactProps) {
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(artifact.content)
+    } catch (err) {
+      console.error("Failed to copy:", err)
+    }
+  }, [artifact.content])
+
+  const handleDownload = useCallback(() => {
+    const extensions: Record<string, string> = {
+      code: artifact.language || "txt",
+      markdown: "md",
+      json: "json",
+      text: "txt",
+    }
+    const ext = extensions[artifact.type] || "txt"
+    const filename = `${artifact.title.toLowerCase().replace(/\s+/g, "-")}.${ext}`
+
+    const blob = new Blob([artifact.content], { type: "text/plain" })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement("a")
+    a.href = url
+    a.download = filename
+    a.click()
+    URL.revokeObjectURL(url)
+  }, [artifact])
+
+  const language: BundledLanguage = (artifact.language || (artifact.type === "json" ? "json" : "plaintext")) as BundledLanguage
+
+  return (
+    <Artifact className="my-4">
+      <ArtifactHeader>
+        <div className="flex flex-col gap-0.5">
+          <ArtifactTitle>{artifact.title}</ArtifactTitle>
+          {artifact.description && (
+            <ArtifactDescription>{artifact.description}</ArtifactDescription>
+          )}
+        </div>
+        <ArtifactActions>
+          <ArtifactAction
+            tooltip="Copy"
+            icon={CopyIcon}
+            onClick={handleCopy}
+          />
+          <ArtifactAction
+            tooltip="Download"
+            icon={DownloadIcon}
+            onClick={handleDownload}
+          />
+          {onClose && <ArtifactClose onClick={onClose} />}
+        </ArtifactActions>
+      </ArtifactHeader>
+      <ArtifactContent className="p-0">
+        <CodeBlock code={artifact.content} language={language} />
+      </ArtifactContent>
+    </Artifact>
+  )
+}

.github/instructions/taming-copilot.instructions.md

@@ -0,0 +1,28 @@
+"use client"
+
+import {
+  Reasoning,
+  ReasoningTrigger,
+  ReasoningContent,
+} from "@/src/components/ai-elements/reasoning"
+
+export interface AgentReasoningProps {
+  reasoning: string
+  isStreaming: boolean
+  duration?: number
+}
+
+export function AgentReasoning({
+  reasoning,
+  isStreaming,
+  duration,
+}: AgentReasoningProps) {
+  if (!reasoning) return null
+
+  return (
+    <Reasoning isStreaming={isStreaming} duration={duration}>
+      <ReasoningTrigger />
+      <ReasoningContent>{reasoning}</ReasoningContent>
+    </Reasoning>
+  )
+}

app/chat/components/agent-artifact.tsx

@@ -0,0 +1,32 @@
+"use client"
+
+import {
+  Sources,
+  SourcesTrigger,
+  SourcesContent,
+  Source,
+} from "@/src/components/ai-elements/sources"
+import type { Source as SourceType } from "@/app/chat/providers/chat-context"
+
+export interface AgentSourcesProps {
+  sources: SourceType[]
+}
+
+export function AgentSources({ sources }: AgentSourcesProps) {
+  if (!sources || sources.length === 0) return null
+
+  return (
+    <Sources>
+      <SourcesTrigger count={sources.length} />
+      <SourcesContent>
+        {sources.map((source, index) => (
+          <Source
+            key={`${source.url}-${index}`}
+            href={source.url}
+            title={source.title}
+          />
+        ))}
+      </SourcesContent>
+    </Sources>
+  )
+}

app/chat/components/agent-reasoning.tsx

@@ -0,0 +1,48 @@
+"use client"
+
+import {
+  Tool,
+  ToolHeader,
+  ToolContent,
+  ToolInput,
+  ToolOutput,
+} from "@/src/components/ai-elements/tool"
+import type { ToolInvocationState } from "@/app/chat/providers/chat-context"
+import type { DynamicToolUIPart } from "ai"
+
+export interface AgentToolsProps {
+  tools: (ToolInvocationState | DynamicToolUIPart)[]
+}
+
+export function AgentTools({ tools }: AgentToolsProps) {
+  if (!tools || tools.length === 0) return null
+
+  return (
+    <div className="space-y-2">
+      {tools.map((tool) => {
+        const t = tool as ToolInvocationState
+        const toolName = t.toolName || t.type?.replace(/^(tool-|dynamic-tool)/, "") || "unknown"
+        const toolType = `tool-${toolName}` as const
+
+        return (
+          <Tool key={t.toolCallId} defaultOpen={false}>
+            <ToolHeader
+              title={toolName}
+              type={toolType}
+              state={t.state}
+            />
+            <ToolContent>
+              <ToolInput input={t.input} />
+              {(t.state === "output-available" || t.state === "output-error") && (
+                <ToolOutput
+                  output={t.state === "output-available" ? t.output : undefined}
+                  errorText={t.state === "output-error" ? t.errorText : undefined}
+                />
+              )}
+            </ToolContent>
+          </Tool>
+        )
+      })}
+    </div>
+  )
+}

app/chat/components/agent-sources.tsx

@@ -0,0 +1,143 @@
+"use client"
+
+import { Button } from "@/ui/button"
+import {
+  ModelSelector,
+  ModelSelectorTrigger,
+  ModelSelectorContent,
+  ModelSelectorInput,
+  ModelSelectorList,
+  ModelSelectorGroup,
+  ModelSelectorItem,
+  ModelSelectorEmpty,
+  ModelSelectorName,
+} from "@/src/components/ai-elements/model-selector"
+import {
+  Context,
+  ContextTrigger,
+  ContextContent,
+  ContextContentHeader,
+  ContextContentBody,
+  ContextContentFooter,
+  ContextInputUsage,
+  ContextOutputUsage,
+} from "@/src/components/ai-elements/context"
+import { useChatContext } from "@/app/chat/providers/chat-context"
+import {
+  getAgentsByCategory,
+  CATEGORY_LABELS,
+  CATEGORY_ORDER,
+  type AgentConfig,
+} from "@/app/chat/config/agents"
+import { CheckIcon, MessageSquareIcon, Trash2Icon } from "lucide-react"
+import { useMemo, useState } from "react"
+
+const DEFAULT_MAX_TOKENS = 128000
+
+export function ChatHeader() {
+  const { selectedAgent, selectAgent, clearMessages, agentConfig, messages, usage } =
+    useChatContext()
+  const [open, setOpen] = useState(false)
+
+  const agentsByCategory = useMemo(() => getAgentsByCategory(), [])
+
+  const handleSelectAgent = (agent: AgentConfig) => {
+    selectAgent(agent.id)
+    setOpen(false)
+  }
+
+  const usedTokens = usage ? usage.inputTokens + usage.outputTokens : 0
+
+  return (
+    <header className="flex items-center justify-between border-b border-border px-4 py-3">
+      <div className="flex items-center gap-3">
+        <MessageSquareIcon className="size-5 text-muted-foreground" />
+        <div className="flex flex-col">
+          <span className="font-semibold text-sm">AgentStack Chat</span>
+          <span className="text-muted-foreground text-xs">
+            {agentConfig?.description || "AI-powered assistant"}
+          </span>
+        </div>
+      </div>
+
+      <div className="flex items-center gap-2">
+        {usage && usedTokens > 0 && (
+          <Context
+            usedTokens={usedTokens}
+            maxTokens={DEFAULT_MAX_TOKENS}
+            usage={{
+              inputTokens: usage.inputTokens,
+              outputTokens: usage.outputTokens,
+              totalTokens: usage.totalTokens,
+            }}
+          >
+            <ContextTrigger />
+            <ContextContent align="end">
+              <ContextContentHeader />
+              <ContextContentBody className="space-y-1">
+                <ContextInputUsage />
+                <ContextOutputUsage />
+              </ContextContentBody>
+              <ContextContentFooter />
+            </ContextContent>
+          </Context>
+        )}
+
+        <ModelSelector open={open} onOpenChange={setOpen}>
+          <ModelSelectorTrigger asChild>
+            <Button variant="outline" size="sm" className="min-w-[180px] justify-between">
+              <span className="truncate">{agentConfig?.name || selectedAgent}</span>
+            </Button>
+          </ModelSelectorTrigger>
+          <ModelSelectorContent className="w-[320px]">
+            <ModelSelectorInput placeholder="Search agents..." />
+            <ModelSelectorList className="max-h-[400px]">
+              <ModelSelectorEmpty>No agents found.</ModelSelectorEmpty>
+              {CATEGORY_ORDER.map((category) => {
+                const agents = agentsByCategory[category]
+                if (agents.length === 0) return null
+
+                return (
+                  <ModelSelectorGroup
+                    key={category}
+                    heading={CATEGORY_LABELS[category]}
+                  >
+                    {agents.map((agent) => (
+                      <ModelSelectorItem
+                        key={agent.id}
+                        value={agent.id}
+                        onSelect={() => handleSelectAgent(agent)}
+                        className="flex items-center justify-between"
+                      >
+                        <div className="flex flex-col gap-0.5">
+                          <ModelSelectorName>{agent.name}</ModelSelectorName>
+                          <span className="text-muted-foreground text-xs line-clamp-1">
+                            {agent.description}
+                          </span>
+                        </div>
+                        {selectedAgent === agent.id && (
+                          <CheckIcon className="size-4 text-primary" />
+                        )}
+                      </ModelSelectorItem>
+                    ))}
+                  </ModelSelectorGroup>
+                )
+              })}
+            </ModelSelectorList>
+          </ModelSelectorContent>
+        </ModelSelector>
+
+        {messages.length > 0 && (
+          <Button
+            variant="ghost"
+            size="icon"
+            onClick={clearMessages}
+            title="Clear conversation"
+          >
+            <Trash2Icon className="size-4" />
+          </Button>
+        )}
+      </div>
+    </header>
+  )
+}