npm - @genui/a3-create - Versions diffs - 0.1.36 - Mend

@genui/a3-create 0.1.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (91) hide show

package/README.md +123 -0
package/dist/index.js +684 -0
package/package.json +52 -0
package/template/.cursor/rules/example-app.mdc +9 -0
package/template/CLAUDE.md +121 -0
package/template/README.md +20 -0
package/template/_gitignore +36 -0
package/template/app/ThemeProvider.tsx +17 -0
package/template/app/agents/age.ts +25 -0
package/template/app/agents/greeting.ts +30 -0
package/template/app/agents/index.ts +57 -0
package/template/app/agents/onboarding/index.ts +15 -0
package/template/app/agents/onboarding/prompt.ts +59 -0
package/template/app/agents/registry.ts +17 -0
package/template/app/agents/state.ts +10 -0
package/template/app/api/agui/route.ts +56 -0
package/template/app/api/chat/route.ts +35 -0
package/template/app/api/stream/route.ts +57 -0
package/template/app/apple-icon-dark.png +0 -0
package/template/app/apple-icon.png +0 -0
package/template/app/components/atoms/AgentNode.tsx +56 -0
package/template/app/components/atoms/AppLogo.tsx +44 -0
package/template/app/components/atoms/ChatContainer.tsx +13 -0
package/template/app/components/atoms/ChatHeader.tsx +49 -0
package/template/app/components/atoms/MarkdownRenderer.tsx +134 -0
package/template/app/components/atoms/MessageBubble.tsx +21 -0
package/template/app/components/atoms/TransitionEdge.tsx +49 -0
package/template/app/components/atoms/index.ts +7 -0
package/template/app/components/molecules/ChatInput.tsx +94 -0
package/template/app/components/molecules/ChatMessage.tsx +45 -0
package/template/app/components/molecules/index.ts +2 -0
package/template/app/components/organisms/AgentGraph.tsx +75 -0
package/template/app/components/organisms/AguiChat.tsx +133 -0
package/template/app/components/organisms/Chat.tsx +88 -0
package/template/app/components/organisms/ChatMessageList.tsx +35 -0
package/template/app/components/organisms/ExamplePageLayout.tsx +118 -0
package/template/app/components/organisms/OnboardingChat.tsx +24 -0
package/template/app/components/organisms/Sidebar.tsx +147 -0
package/template/app/components/organisms/SidebarLayout.tsx +58 -0
package/template/app/components/organisms/StateViewer.tsx +126 -0
package/template/app/components/organisms/StreamChat.tsx +173 -0
package/template/app/components/organisms/index.ts +10 -0
package/template/app/constants/chat.ts +52 -0
package/template/app/constants/paths.ts +1 -0
package/template/app/constants/ui.ts +61 -0
package/template/app/examples/agui/page.tsx +26 -0
package/template/app/examples/chat/page.tsx +26 -0
package/template/app/examples/page.tsx +106 -0
package/template/app/examples/stream/page.tsx +26 -0
package/template/app/favicon-dark.ico +0 -0
package/template/app/favicon.ico +0 -0
package/template/app/icon.svg +13 -0
package/template/app/layout.tsx +36 -0
package/template/app/lib/actions/restartSession.ts +10 -0
package/template/app/lib/getAgentGraphData.ts +43 -0
package/template/app/lib/getGraphLayout.ts +99 -0
package/template/app/lib/hooks/useRestart.ts +33 -0
package/template/app/lib/parseTransitionTargets.ts +140 -0
package/template/app/lib/providers/anthropic.ts +12 -0
package/template/app/lib/providers/bedrock.ts +12 -0
package/template/app/lib/providers/openai.ts +10 -0
package/template/app/onboarding/page.tsx +21 -0
package/template/app/page.tsx +16 -0
package/template/app/styled.d.ts +6 -0
package/template/app/theme.ts +22 -0
package/template/docs/A3-README.md +121 -0
package/template/docs/API-REFERENCE.md +85 -0
package/template/docs/ARCHITECTURE.md +84 -0
package/template/docs/CORE-CONCEPTS.md +347 -0
package/template/docs/CUSTOM_LOGGING.md +36 -0
package/template/docs/CUSTOM_PROVIDERS.md +642 -0
package/template/docs/CUSTOM_STORES.md +228 -0
package/template/docs/PROVIDER-ANTHROPIC.md +45 -0
package/template/docs/PROVIDER-BEDROCK.md +45 -0
package/template/docs/PROVIDER-OPENAI.md +47 -0
package/template/docs/PROVIDERS.md +124 -0
package/template/docs/QUICK-START-EXAMPLES.md +197 -0
package/template/docs/RESILIENCE.md +226 -0
package/template/docs/TRANSITIONS.md +245 -0
package/template/docs/WIDGETS.md +331 -0
package/template/docs/contributing/LOGGING.md +104 -0
package/template/docs/designs/a3-gtm-strategy.md +280 -0
package/template/docs/designs/a3-platform-vision.md +276 -0
package/template/next-env.d.ts +6 -0
package/template/next.config.mjs +15 -0
package/template/package.json +41 -0
package/template/public/android-chrome-192x192.png +0 -0
package/template/public/android-chrome-512x512.png +0 -0
package/template/public/site.webmanifest +11 -0
package/template/scripts/dev.mjs +29 -0
package/template/tsconfig.json +47 -0

package/template/app/layout.tsx ADDED Viewed

@@ -0,0 +1,36 @@
+import type { Metadata } from 'next'
+import { ThemeProvider } from './ThemeProvider'
+import { SidebarLayout } from '@organisms'
+import { APP_TITLE, APP_DESCRIPTION } from '@constants/ui'
+export const metadata: Metadata = {
+  title: APP_TITLE,
+  description: APP_DESCRIPTION,
+  icons: [
+    { rel: 'icon', url: '/favicon.ico', type: 'image/x-icon', sizes: '32x32', media: '(prefers-color-scheme: light)' },
+    {
+      rel: 'icon',
+      url: '/favicon-dark.ico',
+      type: 'image/x-icon',
+      sizes: '32x32',
+      media: '(prefers-color-scheme: dark)',
+    },
+    { rel: 'icon', url: '/icon.svg', type: 'image/svg+xml', media: '(prefers-color-scheme: light)' },
+    { rel: 'icon', url: '/icon.svg', type: 'image/svg+xml', media: '(prefers-color-scheme: dark)' },
+    { rel: 'apple-touch-icon', url: '/apple-icon.png', media: '(prefers-color-scheme: light)' },
+    { rel: 'apple-touch-icon', url: '/apple-icon-dark.png', media: '(prefers-color-scheme: dark)' },
+  ],
+  manifest: '/site.webmanifest',
+}
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <ThemeProvider>
+          <SidebarLayout>{children}</SidebarLayout>
+        </ThemeProvider>
+      </body>
+    </html>
+  )
+}

package/template/app/lib/actions/restartSession.ts ADDED Viewed

@@ -0,0 +1,10 @@
+'use server'
+import { getChatSessionInstance } from '@agents'
+import { initRegistry } from '@agents/registry'
+export async function restartSession(sessionId: string) {
+  initRegistry()
+  const session = getChatSessionInstance({ sessionId })
+  return await session.restart()
+}

package/template/app/lib/getAgentGraphData.ts ADDED Viewed

@@ -0,0 +1,43 @@
+import { agentRegistry } from '@agents/registry'
+import { getTransitionTargetMap } from './parseTransitionTargets'
+export type AgentInfo = {
+  id: string
+  description: string
+  transition: { type: 'deterministic' | 'dynamic' | 'none'; targets: string[] }
+}
+/**
+ * Returns registered agents with transition metadata for the AgentGraph visualization component.
+ * Caller is responsible for ensuring agents are registered before calling this function.
+ *
+ * For deterministic transitions (functions), uses AST parsing to discover the actual
+ * target agent IDs from the source code rather than listing all other agents.
+ */
+export function getAgentGraphData(): AgentInfo[] {
+  const agents = agentRegistry.getAll()
+  const allAgentIds = agents.map((a) => a.id)
+  const targetMap = getTransitionTargetMap()
+  return agents.map((agent) => {
+    let type: 'deterministic' | 'dynamic' | 'none'
+    let targets: string[]
+    if (Array.isArray(agent.transition)) {
+      type = 'dynamic'
+      targets = agent.transition
+    } else if (typeof agent.transition === 'function') {
+      type = 'deterministic'
+      targets = targetMap.get(agent.id) ?? allAgentIds.filter((id) => id !== agent.id)
+    } else {
+      type = 'none'
+      targets = []
+    }
+    return {
+      id: agent.id,
+      description: agent.description,
+      transition: { type, targets },
+    }
+  })
+}

package/template/app/lib/getGraphLayout.ts ADDED Viewed

@@ -0,0 +1,99 @@
+import dagre from '@dagrejs/dagre'
+import { MarkerType, type Node, type Edge } from '@xyflow/react'
+import type { AgentInfo } from './getAgentGraphData'
+const NODE_WIDTH = 160
+const NODE_HEIGHT = 44
+/**
+ * Compute a top-to-bottom dagre layout for the agent graph and return
+ * React Flow–compatible nodes and edges.
+ *
+ * Self-loop edges are excluded from dagre (which expects a DAG) and added
+ * separately with a custom `selfLoop` edge type.
+ */
+export function getGraphLayout(agents: AgentInfo[], activeAgentId: string | null): { nodes: Node[]; edges: Edge[] } {
+  const g = new dagre.graphlib.Graph()
+  g.setDefaultEdgeLabel(() => ({}))
+  g.setGraph({ rankdir: 'TB', ranksep: 60, nodesep: 40 })
+  for (const agent of agents) {
+    g.setNode(agent.id, { width: NODE_WIDTH, height: NODE_HEIGHT })
+  }
+  for (const agent of agents) {
+    for (const target of agent.transition.targets) {
+      if (target !== agent.id) {
+        g.setEdge(agent.id, target)
+      }
+    }
+  }
+  dagre.layout(g)
+  const resolvedActiveId = activeAgentId ?? agents[0]?.id ?? null
+  const nodes: Node[] = agents.map((agent) => {
+    const { x, y } = g.node(agent.id) as unknown as { x: number; y: number }
+    return {
+      id: agent.id,
+      position: { x: x - NODE_WIDTH / 2, y: y - NODE_HEIGHT / 2 },
+      data: {
+        label: agent.id,
+        isActive: agent.id === resolvedActiveId,
+        description: agent.description,
+      },
+      type: 'agent',
+    }
+  })
+  const positionOf = new Map<string, { x: number; y: number }>()
+  for (const agent of agents) {
+    const { x, y } = g.node(agent.id) as unknown as { x: number; y: number }
+    positionOf.set(agent.id, { x, y })
+  }
+  const edges: Edge[] = []
+  for (const agent of agents) {
+    const isDynamic = agent.transition.type === 'dynamic'
+    const strokeColor = isDynamic ? '#94a3b8' : '#64748b'
+    for (const target of agent.transition.targets) {
+      const marker = {
+        type: MarkerType.ArrowClosed,
+        color: strokeColor,
+        width: 15,
+        height: 15,
+      }
+      if (target === agent.id) {
+        edges.push({
+          id: `${agent.id}-${target}`,
+          source: agent.id,
+          target,
+          type: 'selfLoop',
+          data: { isDynamic },
+          markerEnd: marker,
+          sourceHandle: 'source-bottom',
+          targetHandle: 'target-top',
+        })
+      } else {
+        const sourceY = positionOf.get(agent.id)!.y
+        const targetY = positionOf.get(target)!.y
+        const isBackEdge = sourceY >= targetY
+        edges.push({
+          id: `${agent.id}-${target}`,
+          source: agent.id,
+          target,
+          type: isDynamic ? 'dynamic' : 'deterministic',
+          markerEnd: marker,
+          sourceHandle: isBackEdge ? 'source-right' : 'source-bottom',
+          targetHandle: isBackEdge ? 'target-right' : 'target-top',
+        })
+      }
+    }
+  }
+  return { nodes, edges }
+}

package/template/app/lib/hooks/useRestart.ts ADDED Viewed

@@ -0,0 +1,33 @@
+import { useState, useCallback } from 'react'
+import type { Dispatch, SetStateAction } from 'react'
+import type { Message } from '@genui/a3'
+export interface RestartResult {
+  messages: Message[]
+  activeAgentId: string | null
+  state: Record<string, unknown>
+}
+interface UseRestartOptions {
+  onRestart?: () => Promise<RestartResult>
+  setMessages: Dispatch<SetStateAction<Message[]>>
+  onSessionUpdate?: (update: { activeAgentId: string | null; state: Record<string, unknown> }) => void
+}
+export function useRestart({ onRestart, setMessages, onSessionUpdate }: UseRestartOptions) {
+  const [isRestarting, setIsRestarting] = useState(false)
+  const handleRestart = useCallback(async () => {
+    if (!onRestart) return
+    setIsRestarting(true)
+    try {
+      const fresh = await onRestart()
+      setMessages(fresh.messages)
+      onSessionUpdate?.({ activeAgentId: fresh.activeAgentId, state: fresh.state })
+    } finally {
+      setIsRestarting(false)
+    }
+  }, [onRestart, setMessages, onSessionUpdate])
+  return { isRestarting, handleRestart: onRestart ? handleRestart : undefined }
+}

package/template/app/lib/parseTransitionTargets.ts ADDED Viewed

@@ -0,0 +1,140 @@
+import * as ts from 'typescript'
+import * as fs from 'fs'
+import * as path from 'path'
+const SKIP_FILES = new Set(['state.ts', 'registry.ts', 'index.ts'])
+let cached: Map<string, string[]> | null = null
+/**
+ * Parse agent source files to extract transition targets using TypeScript's AST.
+ * Results are cached for the server lifecycle.
+ *
+ * For array transitions, extracts string elements directly.
+ * For function transitions, walks the function body to collect string literals
+ * from return statements and ternary expressions, then cross-references against
+ * known agent IDs to filter out non-agent strings.
+ *
+ * @returns Map from agent ID to transition target agent IDs
+ */
+export function getTransitionTargetMap(): Map<string, string[]> {
+  if (cached) return cached
+  cached = new Map()
+  const agentsDir = path.join(process.cwd(), 'app/agents')
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(agentsDir, { withFileTypes: true })
+  } catch {
+    return cached
+  }
+  const fileNames = entries
+    .filter((e) => e.isFile() && e.name.endsWith('.ts') && !SKIP_FILES.has(e.name))
+    .map((e) => e.name)
+  // First pass: parse all files and collect agent IDs
+  const fileData: { agentId: string; transitionNode: ts.Node | null }[] = []
+  const allAgentIds = new Set<string>()
+  for (const fileName of fileNames) {
+    try {
+      const source = fs.readFileSync(path.join(agentsDir, fileName), 'utf-8')
+      const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true)
+      const info = extractAgentInfo(sf)
+      if (info) {
+        allAgentIds.add(info.agentId)
+        fileData.push(info)
+      }
+    } catch {
+      // Skip unparseable files
+    }
+  }
+  // Second pass: extract transition targets and cross-reference against known IDs
+  for (const { agentId, transitionNode } of fileData) {
+    if (!transitionNode) continue
+    const targets = extractTargets(transitionNode, allAgentIds)
+    if (targets.length > 0) {
+      cached.set(agentId, targets)
+    }
+  }
+  return cached
+}
+function extractAgentInfo(
+  sf: ts.SourceFile
+): { agentId: string; transitionNode: ts.Node | null } | null {
+  let agentId: string | null = null
+  let transitionNode: ts.Node | null = null
+  function visit(node: ts.Node) {
+    if (ts.isObjectLiteralExpression(node)) {
+      let id: string | null = null
+      let transition: ts.Node | null = null
+      for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue
+        if (prop.name.text === 'id' && ts.isStringLiteral(prop.initializer)) {
+          id = prop.initializer.text
+        }
+        if (prop.name.text === 'transition') {
+          transition = prop.initializer
+        }
+      }
+      if (id) {
+        agentId = id
+        transitionNode = transition
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  ts.forEachChild(sf, visit)
+  return agentId ? { agentId, transitionNode } : null
+}
+function extractTargets(node: ts.Node, allAgentIds: Set<string>): string[] {
+  if (ts.isArrayLiteralExpression(node)) {
+    return node.elements
+      .filter(ts.isStringLiteral)
+      .map((el) => el.text)
+      .filter((text) => allAgentIds.has(text))
+  }
+  if (ts.isFunctionExpression(node) || ts.isArrowFunction(node)) {
+    const strings = new Set<string>()
+    if (ts.isBlock(node.body)) {
+      collectReturnStrings(node.body, strings)
+    } else {
+      // Expression body (arrow function without braces)
+      collectStringLiterals(node.body, strings)
+    }
+    return Array.from(strings).filter((s) => allAgentIds.has(s))
+  }
+  return []
+}
+function collectReturnStrings(node: ts.Node, strings: Set<string>) {
+  if (ts.isReturnStatement(node) && node.expression) {
+    collectStringLiterals(node.expression, strings)
+    return
+  }
+  ts.forEachChild(node, (child) => collectReturnStrings(child, strings))
+}
+function collectStringLiterals(node: ts.Node, strings: Set<string>) {
+  if (ts.isStringLiteral(node)) {
+    strings.add(node.text)
+    return
+  }
+  if (ts.isConditionalExpression(node)) {
+    collectStringLiterals(node.whenTrue, strings)
+    collectStringLiterals(node.whenFalse, strings)
+    return
+  }
+  ts.forEachChild(node, (child) => collectStringLiterals(child, strings))
+}

package/template/app/lib/providers/anthropic.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import { createAnthropicProvider } from '@genui/a3-anthropic'
+let _instance: ReturnType<typeof createAnthropicProvider> | null = null
+export function getAnthropicProvider() {
+  if (!_instance) {
+    _instance = createAnthropicProvider({
+      models: ['claude-sonnet-4-6', 'claude-haiku-4-5-20251001'],
+    })
+  }
+  return _instance
+}

package/template/app/lib/providers/bedrock.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import { createBedrockProvider } from '@genui/a3-bedrock'
+let _instance: ReturnType<typeof createBedrockProvider> | null = null
+export function getBedrockProvider() {
+  if (!_instance) {
+    _instance = createBedrockProvider({
+      models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0', 'us.anthropic.claude-haiku-4-5-20251001-v1:0'],
+    })
+  }
+  return _instance
+}

package/template/app/lib/providers/openai.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import { createOpenAIProvider } from '@genui/a3-openai'
+let _instance: ReturnType<typeof createOpenAIProvider> | null = null
+export function getOpenAIProvider() {
+  if (!_instance) {
+    _instance = createOpenAIProvider({ models: ['gpt-4o', 'gpt-4o-mini'] })
+  }
+  return _instance
+}

package/template/app/onboarding/page.tsx ADDED Viewed

@@ -0,0 +1,21 @@
+import { Box, Typography } from '@mui/material'
+import { OnboardingChat } from '@organisms'
+import { getChatSessionInstance } from '@agents'
+import { SESSION_IDS } from '@constants/chat'
+import { ONBOARDING_TAGLINE } from '@constants/ui'
+export default async function OnboardingPage() {
+  const session = getChatSessionInstance({ sessionId: SESSION_IDS.ONBOARDING, initialAgentId: 'onboarding' })
+  const sessionData = await session.getOrCreateSessionData()
+  return (
+    <>
+      <Box sx={{ px: 3, py: 3, textAlign: 'center' }}>
+        <Typography variant="body1" color="text.secondary" dangerouslySetInnerHTML={{ __html: ONBOARDING_TAGLINE }} />
+      </Box>
+      <Box sx={{ flex: 1, display: 'flex', flexDirection: 'column', overflow: 'hidden', pb: 3, px: { xs: 2, sm: 3, md: 5, lg: 8 } }}>
+        <OnboardingChat sessionId={SESSION_IDS.ONBOARDING} initialMessages={sessionData.messages} />
+      </Box>
+    </>
+  )
+}

package/template/app/page.tsx ADDED Viewed

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { Box, Container } from '@mui/material'
+import { MarkdownRenderer } from '@atoms'
+export default function Home() {
+  const readme = readFileSync(join(process.cwd(), 'docs/A3-README.md'), 'utf-8')
+  return (
+    <Container maxWidth="md" sx={{ py: 4 }}>
+      <Box sx={{ px: { xs: 1, sm: 2 } }}>
+        <MarkdownRenderer content={readme} />
+      </Box>
+    </Container>
+  )
+}

package/template/app/styled.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+import 'styled-components'
+import type { Theme } from '@mui/material/styles'
+declare module 'styled-components' {
+  export type DefaultTheme = Theme
+}

package/template/app/theme.ts ADDED Viewed

@@ -0,0 +1,22 @@
+import { createTheme } from '@mui/material/styles'
+export const theme = createTheme({
+  palette: {
+    primary: {
+      main: '#2563eb',
+    },
+    background: {
+      default: '#f9fafb',
+      paper: '#ffffff',
+    },
+  },
+  components: {
+    MuiCssBaseline: {
+      styleOverrides: {
+        html: { maxWidth: '100vw', overflowX: 'hidden' },
+        body: { maxWidth: '100vw', overflowX: 'hidden' },
+        a: { color: 'inherit', textDecoration: 'none' },
+      },
+    },
+  },
+})

package/template/docs/A3-README.md ADDED Viewed

@@ -0,0 +1,121 @@
+# @genui/a3
+[![npm version](https://img.shields.io/npm/v/@genui)](https://www.npmjs.com/package/@genui/a3)
+[![license](https://img.shields.io/npm/l/@genui/a3)](https://github.com/generalui/a3/blob/main/LICENSE)
+**Predictable, governable multi-agent orchestration for TypeScript.**
+Production agentic systems need more than prompt chains: They need
+deterministic guardrails, structured output, and routing you can reason about.
+A3 combines flexible LLM reasoning with hard-coded control:
+Zod-validated responses, deterministic or LLM-driven routing, and shared typed state.
+No graphs. No state machines. Just agents and code.
+## Feature Highlights
+- **Deterministic + LLM-driven routing** -- code-controlled transitions or let the LLM pick from a bounded set
+- **Structured output** -- Zod schemas validate every LLM response at runtime
+- **Multi-agent orchestration** -- agents hand off to each other with shared typed state
+- **Streaming** -- real-time token streaming with AG-UI-compatible events
+- **Pluggable providers** -- Bedrock, OpenAI, Anthropic; or [build your own](./docs/CUSTOM_PROVIDERS.md)
+- **Pluggable session stores** -- swap in-memory, Redis, or your own persistence
+- **TypeScript-native** -- full type safety from agent definitions to response handling
+- **Dual ESM/CJS** -- works in any Node.js environment
+## Why A3?
+Most agentic frameworks optimize for demos, not production.
+Prompt-only agents break when inputs drift.
+Graph-based orchestration becomes unmaintainable at scale.
+None of them give you compile-time safety or runtime validation out of the box.
+A3's approach: **define agents, register them, and let the framework handle routing —
+with guardrails at every layer.**
+- **Every response validated:** Zod schemas enforce structure at runtime, not just in types
+- **Routing you can reason about:** deterministic transitions via code, or bounded LLM-driven selection
+- **Typed shared state:** one state object flows across agents with full TypeScript safety
+- **Swap providers, not code:** Bedrock, OpenAI, Anthropic; switch with one line
+## Quick Start
+Scaffold a new project:
+```bash
+# Fastest way to start — scaffolds a full Next.js app
+npx @genui/a3-create@latest my-app
+cd my-app
+```
+Or add A3 to an existing project:
+```bash
+npm install @genui/a3 @genui/a3-bedrock zod
+```
+```typescript
+import { z } from 'zod'
+import { Agent, AgentRegistry, BaseState, ChatSession, MemorySessionStore } from '@genui/a3'
+import { createBedrockProvider } from '@genui/a3-bedrock'
+interface MyState extends BaseState { userName?: string }
+const agent: Agent<MyState> = {
+  id: 'greeter',
+  description: 'Greets the user and collects their name',
+  prompt: 'You are a friendly greeting agent. Ask for the user\'s name.',
+  outputSchema: z.object({ userName: z.string().optional() }),
+}
+AgentRegistry.getInstance<MyState>().register(agent)
+const session = new ChatSession<MyState>({
+  sessionId: 'demo',
+  store: new MemorySessionStore(),
+  initialAgentId: 'greeter',
+  initialState: { userName: undefined },
+  provider: createBedrockProvider({ models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0'] }),
+})
+const result = await session.send({ message: 'Hello!' })
+console.log(result.responseMessage)
+```
+See more examples in the [Quick Start & Examples guide](./docs/QUICK-START-EXAMPLES.md).
+## Documentation
+- [Core Concepts](./docs/CORE-CONCEPTS.md) -- agents, routing, state, schemas, streaming, providers, stores
+- [Architecture](./docs/ARCHITECTURE.md) -- system diagram and request flow
+- [API Reference](./docs/API-REFERENCE.md) -- exports, methods, and response fields
+- [Quick Start & Examples](./docs/QUICK-START-EXAMPLES.md) -- single-agent and multi-agent walkthroughs
+- [Providers](./docs/PROVIDERS.md) -- configuring Bedrock, OpenAI, and Anthropic
+- [Custom Providers](./docs/CUSTOM_PROVIDERS.md) -- building your own provider
+- [Resilience](./docs/RESILIENCE.md) -- retries, timeouts, and model fallback
+- [Custom Logging](./docs/CUSTOM_LOGGING.md) -- plugging in your own logger
+- [Custom Stores](./docs/CUSTOM_STORES.md) -- implementing your own session store
+## Roadmap
+- **Tool use** -- agent-invoked tool execution within the response cycle
+## Requirements
+- Node.js 20.19.0+
+- TypeScript 5.9+
+- `zod` 4.x (included as a dependency)
+- A configured LLM provider ([Bedrock, OpenAI, or Anthropic](./docs/PROVIDERS.md))
+## Contributing
+```bash
+npm install          # Install dependencies
+npm run build        # Build
+npm run test:unit    # Run unit tests
+npm run lint         # Lint
+```
+## License
+MIT

package/template/docs/API-REFERENCE.md ADDED Viewed

@@ -0,0 +1,85 @@
+# API Reference
+## Core Exports
+| Export | Type | Description |
+|---|---|---|
+| `ChatSession` | Class | Primary interface for sending messages and managing conversations |
+| `AgentRegistry` | Class | Singleton registry for agent registration and lookup |
+| `AGUIAgent` | Class | AG-UI protocol integration for standardized agent-to-frontend streaming |
+| `simpleAgentResponse` | Function | Default blocking response generator for agents |
+| `simpleAgentResponseStream` | Function | Default streaming response generator for agents |
+| `getAgentResponse` | Function | Low-level blocking agent response pipeline (prompt, schema, LLM call, validation) |
+| `getAgentResponseStream` | Function | Low-level streaming agent response pipeline |
+| `manageFlow` | Function | Blocking chat flow orchestration with automatic agent chaining |
+| `manageFlowStream` | Function | Streaming variant of `manageFlow` yielding `StreamEvent`s |
+| `createFullOutputSchema` | Function | Merges agent schema with base response fields |
+| `MemorySessionStore` | Class | In-memory session store for development and testing |
+## ChatSession Methods
+| Method | Returns | Description |
+|---|---|---|
+| `send({ message })` | `Promise<ChatResponse<TState>>` | Send a user message and get the agent's response (blocking) |
+| `send({ message, stream: true })` | `AsyncGenerator<StreamEvent<TState>>` | Send a message and stream the response as events |
+| `getSessionData()` | `Promise<SessionData<TState> \| null>` | Load current session state without sending a message |
+| `getOrCreateSessionData()` | `Promise<SessionData<TState>>` | Load session or create with initial values if none exists |
+| `upsertSessionData(updates)` | `Promise<void>` | Merge partial updates into the current session |
+| `getHistory()` | `Promise<Message[]>` | Retrieve conversation history |
+| `clear()` | `Promise<void>` | Delete the session from the store |
+## AgentRegistry Methods
+| Method | Returns | Description |
+|---|---|---|
+| `getInstance()` | `AgentRegistry<TState>` | Get the singleton instance |
+| `resetInstance()` | `void` | Reset the singleton (for testing) |
+| `register(agents)` | `void` | Register one or more agents (throws on duplicate ID) |
+| `unregister(agentOrId)` | `boolean` | Remove an agent by ID or agent instance |
+| `get(id)` | `Agent<TState> \| undefined` | Look up an agent by ID |
+| `getAll()` | `Agent<TState>[]` | Get all registered agents |
+| `has(id)` | `boolean` | Check if an agent is registered |
+| `getDescriptions()` | `Record<string, string>` | Map of agent IDs to their descriptions |
+| `clear()` | `void` | Remove all registered agents (for testing) |
+| `count` | `number` | Number of registered agents (getter) |
+## ChatResponse Fields
+| Field | Type | Description |
+|---|---|---|
+| `responseMessage` | `string` | The agent's text response to the user |
+| `activeAgentId` | `string \| null` | The agent that generated this response |
+| `nextAgentId` | `string \| null` | The agent that will handle the next message |
+| `state` | `TState` | Updated session state after this turn |
+| `goalAchieved` | `boolean` | Whether the agent considers its goal complete |
+| `sessionId` | `string` | Session identifier |
+| `widgets` | `object \| undefined` | Optional widget data for rich UI rendering |
+## ChatSessionConfig
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `sessionId` | `string` | *required* | Unique session identifier |
+| `store` | `SessionStore` | `undefined` | Storage adapter for session persistence |
+| `initialAgentId` | `AgentId` | *required* | Agent to start the conversation |
+| `initialState` | `TState` | `undefined` | Initial state for new sessions |
+| `initialChatContext` | `TContext` | `undefined` | Initial chat context for new sessions |
+| `initialMessages` | `Message[]` | `undefined` | Pre-populated conversation messages |
+| `provider` | `Provider` | *required* | LLM provider instance for this session |
+| `agentRecursionLimit` | `number` | `10` | Maximum automatic agent transitions per `send()` call. See [Transitions — Recursion Limit](./TRANSITIONS.md#recursion-limit) |
+## Agent Properties
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `id` | `AgentId` | Yes | Unique identifier for the agent |
+| `description` | `string` | Yes | What this agent does (used in agent pool prompts) |
+| `name` | `string` | No | Human-readable display name |
+| `prompt` | `string \| (input) => Promise<string>` | Yes | System prompt string or async function returning the prompt |
+| `outputSchema` | `ZodObject \| (sessionData) => ZodObject` | Yes | Zod schema defining structured data to extract from LLM responses |
+| `provider` | `Provider` | No | Per-agent provider override; falls back to session-level provider |
+| `generateResponse` | `(input) => Promise \| AsyncGenerator` | No | Custom response generator. See [Custom generateResponse](./CORE-CONCEPTS.md#custom-generateresponse) |
+| `setState` | `(data, state) => TState` | No | Maps extracted LLM data into session state (defaults to shallow merge) |
+| `transition` | `AgentId[] \| (state, goalAchieved) => AgentId` | No | Routing config. **Array**: LLM picks from listed IDs. **Function**: code decides. **Omitted**: LLM unconstrained. See [Transitions](./TRANSITIONS.md) |
+| `filterHistoryStrategy` | `(messages) => Conversation` | No | Custom function to filter conversation history before sending to the LLM |
+| `widgets` | `Record<string, ZodObject> \| (sessionData) => Record` | No | Zod schemas defining widgets available to the agent |