@genui/a3-create 0.1.36

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@genui/a3-create",
+  "version": "0.1.36",
+  "description": "CLI scaffolding tool for A3 agentic apps",
+  "keywords": [
+    "genui",
+    "a3",
+    "ai",
+    "agentic",
+    "architecture",
+    "scaffold",
+    "cli"
+  ],
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "create-genui-a3": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "npm run prepare-template && tsup",
+    "postbuild": "chmod +x dist/index.js",
+    "clean": "rm -rf dist template",
+    "prepare-template": "node scripts/prepare-template.mjs",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@aws-sdk/client-bedrock": "^3.750.0",
+    "@aws-sdk/credential-provider-ini": "^3.750.0",
+    "@clack/prompts": "1.1.0",
+    "chalk": "5.4.1",
+    "fs-extra": "11.3.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "11.0.4",
+    "@types/node": "20.19.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/generalui/a3.git"
+  }
+}

package/template/.cursor/rules/example-app.mdc

@@ -0,0 +1,9 @@
+---
+description: Example app rules (pointer to single source)
+globs: "**"
+alwaysApply: true
+---
+
+# Example App
+
+When working in this directory, follow the rules in **CLAUDE.md** in this directory (same content as `.cursorrules` via symlink). Do not duplicate rule content here; CLAUDE.md is the single source of truth for Claude Code and Cursor.

package/template/CLAUDE.md

@@ -0,0 +1,121 @@
+# Example App
+
+Next.js example for @genui/a3. AI rules for this app (Claude Code and Cursor). Single source of truth; Cursor uses via symlink `.cursorrules` → this file.
+
+## Stack
+
+- Next.js 16.1.6 (App Router), React 19, TypeScript 5.9+
+- Testing infrastructure planned (not yet configured)
+- MUI 7 (@mui/material) + styled-components for styling (`app/theme.ts`, `app/ThemeProvider.tsx`)
+
+## Dependencies
+
+- Pin all npm package versions (no `^` or `~`).
+- Use exact versions in package.json so installs are reproducible.
+
+## React / TypeScript
+
+- Named functions over arrow function assignments
+- Proper types and interfaces; follow React hooks rules and lifecycle
+- Error boundaries and handling where appropriate
+- Path aliases (from `tsconfig.json`):
+  - `@atoms` → `./app/components/atoms`
+  - `@molecules` → `./app/components/molecules`
+  - `@organisms` → `./app/components/organisms`
+  - `@components` → `./app/components`
+  - `@constants` → `./app/constants`
+  - `types` → `./app/types` (bare module, no @ prefix)
+
+## Dev Commands
+
+- `npm run dev` — Start Next.js dev server
+- `npm run build` — Build for production
+- `npm run start` — Start production server
+
+## Next.js
+
+- Use App Router, Server Components, Client Components, Server Actions, middleware as appropriate
+
+## Code Organization
+
+- Single-responsibility components; separation of concerns
+- Constants for config and string literals; clean folder structure; DRY
+- Use Atomic Design for component hierarchy (see below)
+- `app/api/` — API routes (agui, chat, stream endpoints)
+- `app/(pages)/` — Route groups (agui, chat, stream pages)
+- `app/agents/` — Agent implementations (e.g. age.ts, greeting.ts)
+- `app/lib/providers/` — Provider factory functions (Anthropic, Bedrock, OpenAI)
+
+## Component hierarchy (Atomic Design)
+
+- Place UI components under `app/components/` in Atomic Design layers:
+  1. **atoms/** — Single-purpose primitives (e.g. MessageBubble, buttons, inputs).
+  2. **molecules/** — Compositions of atoms (e.g. ChatMessage, ChatInput).
+  3. **organisms/** — Compositions of molecules and layout (e.g. Chat, ChatMessageList).
+- Pages import from organisms (or molecules when no organism exists).
+- Each layer may only use components from the same or lower layers (atoms use MUI/styled only; molecules use atoms; organisms use molecules/atoms).
+- Export public components via `index.ts` per folder.
+
+## State & Data
+
+- Appropriate React hooks; clear data flow
+- Handle loading, error, and success states; predictable updates
+
+## Testing
+
+Testing infrastructure is not yet configured for the example app.
+When added, tests should be comprehensive, runnable in isolation, and cover error cases.
+
+## Naming Conventions
+
+- camelCase for variables, functions, and file names
+- PascalCase for React components, interfaces, and type aliases
+- SCREAMING_SNAKE_CASE for module-level constants
+
+## API & UX
+
+- Proper error handling and loading states; correct response types; separate API logic
+- Loading states, clear error messages, responsive design, accessibility
+
+## Security
+
+- Sensitive data handled appropriately (HIPAA-aware)
+- Auth/authz where needed; no keys or tokens in code
+
+## Docs
+
+- Markdown per markdownlint (new line per sentence, "1." for lists; config inherited from root `.markdownlint.json`)
+
+## Workflow
+
+- **Please understand the requirements of this project before building.**
+- **Please ask any clarifying questions before making any changes or recommendations.**
+
+1. Understand requirements (business, technical, non-functional)
+2. Plan implementation
+3. Write tests, then code that passes them
+4. Document decisions; review for best practices
+
+Use latest React and TypeScript syntax. Code should be clean, readable, maintainable, efficient, and DRY.
+
+## A3 Framework Documentation
+
+The `docs/` directory contains essential A3 framework documentation.
+**You MUST read the relevant files below** before implementing or modifying any feature that touches A3 agents, providers, sessions, resilience, or logging.
+
+| File | Topic |
+|---|---|
+| `docs/API-REFERENCE.md` | Core exports, types, and API descriptions |
+| `docs/ARCHITECTURE.md` | Framework architecture and system design |
+| `docs/CORE-CONCEPTS.md` | Agents, providers, and fundamental building blocks |
+| `docs/CUSTOM_LOGGING.md` | Supplying a custom logger via `configureLogger()` |
+| `docs/CUSTOM_PROVIDERS.md` | Creating a custom provider and streaming support |
+| `docs/INITIAL_PROMPT.md` | System prompts and instructions for AI agents |
+| `docs/contributing/LOGGING.md` | Internal logging architecture, `log` singleton, log levels |
+| `docs/PROVIDERS.md` | Provider setup (Bedrock, OpenAI, Anthropic), config options, model fallback, per-agent overrides |
+| `docs/QUICK-START-EXAMPLES.md` | Agent definitions, registration, multi-agent flows, ChatSession usage |
+| `docs/RESILIENCE.md` | Retry, backoff, timeout config, error classification, resilience error handling |
+| `docs/TRANSITIONS.md` | Agent hand-offs and transition control |
+
+When in doubt about A3 API usage, patterns, or configuration — **read the relevant doc file first**.
+Any new `.md` files added to `docs/` are part of this documentation set and should be consulted as needed.

package/template/README.md

@@ -0,0 +1,20 @@
+# A3 App
+
+Built with [GenUI A3](https://www.npmjs.com/package/@genui/a3).
+
+## Documentation
+
+Local documentation is available in the [`./docs`](./docs) folder. Check there for concepts, recipes, and API reference!
+
+## Getting Started
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Learn More
+
+- [A3 Core Documentation](https://www.npmjs.com/package/@genui/a3)
+- [Next.js Documentation](https://nextjs.org/docs)

package/template/_gitignore

@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

package/template/app/ThemeProvider.tsx

@@ -0,0 +1,17 @@
+'use client'
+
+import { ThemeProvider as MuiThemeProvider } from '@mui/material/styles'
+import { ThemeProvider as StyledThemeProvider } from 'styled-components'
+import CssBaseline from '@mui/material/CssBaseline'
+import { theme } from './theme'
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <MuiThemeProvider theme={theme}>
+      <StyledThemeProvider theme={theme}>
+        <CssBaseline />
+        {children}
+      </StyledThemeProvider>
+    </MuiThemeProvider>
+  )
+}

package/template/app/agents/age.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+import { Agent } from '@genui/a3'
+import type { State } from '@agents/state'
+
+/**
+ * Sample age agent that gets the user's age.
+ */
+const agePayload = z.object({
+  userAge: z.string().optional(),
+})
+
+export const ageAgent: Agent<State> = {
+  id: 'age',
+  description: "Gets the user's age.",
+  prompt: `
+    You are a friendly agent. Your goal is to learn the user's age.
+    If you don't know their age yet, ask for it politely.
+    Once you have their age, confirm it and set goalAchieved to true.
+
+    If the user says they want to change their name or use a different name,
+    say "Of course, I can help you with that" and transition to the greeting agent.
+  `,
+  outputSchema: agePayload,
+  transition: ['greeting'],
+}

package/template/app/agents/greeting.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+import { Agent } from '@genui/a3'
+import type { State } from '@agents/state'
+
+/**
+ * Sample greeting agent that demonstrates the AgentRegistry pattern.
+ */
+const greetingPayload = z.object({
+  userName: z.string().optional(),
+})
+
+export const greetingAgent: Agent<State> = {
+  id: 'greeting',
+  description: 'Greets the user and learns their name.',
+  prompt: `
+    You are a friendly greeting agent. Your goal is to greet the user and learn their name.
+    You also handle name changes — if the user wants to update their name, collect the new one.
+    If you don't know their name yet, ask for it politely.
+    Once you have their name, greet them by name and set goalAchieved to true.
+
+    Do not ask "How can I help you today?".
+  `,
+  outputSchema: greetingPayload,
+  transition: (state, agentGoalAchieved) => {
+    if (agentGoalAchieved) {
+      return 'age'
+    }
+    return 'greeting'
+  },
+}

package/template/app/agents/index.ts

@@ -0,0 +1,57 @@
+import { ChatSession, MemorySessionStore, MessageSender } from '@genui/a3'
+import { getProvider } from '@providers'
+import type { State } from '@agents/state'
+import type { Message } from '@genui/a3'
+import { SESSION_INITIAL_MESSAGES } from '@constants/chat'
+
+const globalForStore = globalThis as unknown as {
+  __a3SessionStore?: MemorySessionStore<State>
+}
+
+/**
+ * Get the shared session store, persisted on globalThis to survive HMR.
+ */
+function getSessionStore(): MemorySessionStore<State> {
+  globalForStore.__a3SessionStore ??= new MemorySessionStore<State>()
+  return globalForStore.__a3SessionStore
+}
+
+/**
+ * Create a single assistant message from text.
+ */
+function createInitialMessage(text: string): Message {
+  return {
+    messageId: crypto.randomUUID(),
+    text,
+    metadata: { source: MessageSender.ASSISTANT, timestamp: Date.now() },
+  }
+}
+
+/**
+ * Build the default initial messages for a given session ID.
+ */
+function getDefaultInitialMessages(sessionId: string): Message[] | undefined {
+  const text = SESSION_INITIAL_MESSAGES[sessionId]
+  return text ? [createInitialMessage(text)] : undefined
+}
+
+/**
+ * Get a ChatSession instance for the given session ID.
+ *
+ * @param options - Session configuration with optional overrides
+ * @returns A ChatSession instance configured with the shared store
+ */
+export function getChatSessionInstance(options: {
+  sessionId: string
+  initialAgentId?: string
+  initialMessages?: Message[]
+}): ChatSession<State> {
+  return new ChatSession<State>({
+    sessionId: options.sessionId,
+    store: getSessionStore(),
+    initialAgentId: options.initialAgentId ?? 'greeting',
+    initialState: { userName: undefined },
+    provider: getProvider(),
+    initialMessages: options.initialMessages ?? getDefaultInitialMessages(options.sessionId),
+  })
+}

package/template/app/agents/onboarding/index.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+import { Agent } from '@genui/a3'
+import type { State } from '@agents/state'
+import { prompt } from './prompt'
+
+/**
+ * Agent that knows everything there is to know about A3 framework, answers questions about it and guides users
+ * through the process of using it.
+ */
+export const onboardingAgent: Agent<State> = {
+  id: 'onboarding',
+  description: 'Onboards users to the A3 framework.',
+  prompt: (params) => prompt(params),
+  outputSchema: z.object({}),
+}

package/template/app/agents/onboarding/prompt.ts

@@ -0,0 +1,59 @@
+import { readdir, readFile } from 'fs/promises'
+import { join, relative } from 'path'
+import type { FlowInput } from '@genui/a3'
+import type { State } from '@agents/state'
+
+/**
+ * Recursively find all .md files under a directory.
+ */
+async function findMarkdownFiles(dir: string): Promise<string[]> {
+  const results: string[] = []
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name)
+    if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+      results.push(...(await findMarkdownFiles(fullPath)))
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      results.push(fullPath)
+    }
+  }
+
+  return results
+}
+
+/**
+ * Build the onboarding agent prompt by reading all markdown documentation
+ * from the example project root.
+ */
+export async function prompt(_params: FlowInput<State>): Promise<string> {
+  const projectRoot = process.cwd()
+  const mdFiles = await findMarkdownFiles(projectRoot)
+  const sections: string[] = []
+
+  for (const filePath of mdFiles) {
+    const content = await readFile(filePath, 'utf-8')
+    const relPath = relative(projectRoot, filePath)
+    sections.push(`## ${relPath}\n\n${content}`)
+  }
+
+  const documentation = sections.join('\n\n---\n\n')
+
+  return `
+You are a friendly and knowledgeable onboarding agent for the A3 framework.
+Your goal is to help users understand and get started with A3 by answering their questions
+using the documentation provided below.
+
+# INSTRUCTIONS
+
+- Answer questions accurately based on the documentation below.
+- Include relevant code snippets and examples when helpful.
+- Use markdown formatting for clarity (headings, code blocks, lists, bold/italic).
+- If a question falls outside the documentation scope, say so honestly.
+- Be concise but thorough — provide enough detail to be actionable.
+
+# DOCUMENTATION
+
+${documentation}
+`
+}

package/template/app/agents/registry.ts

@@ -0,0 +1,17 @@
+import { AgentRegistry } from '@genui/a3'
+
+import type { State } from '@agents/state'
+import { greetingAgent } from '@agents/greeting'
+import { ageAgent } from '@agents/age'
+
+/**
+ * Shared agent registry all API routes.
+ */
+const registry = AgentRegistry.getInstance<State>()
+
+export function initRegistry() {
+  registry.clear()
+  registry.register([greetingAgent, ageAgent])
+}
+
+export const agentRegistry = registry

package/template/app/agents/state.ts

@@ -0,0 +1,10 @@
+import { BaseState } from '@genui/a3'
+
+/**
+ * Consumer defines their GLOBAL state extending BaseState.
+ * This state is shared across ALL agents in the session.
+ */
+export interface State extends BaseState {
+  userName?: string
+  userAge?: string
+}

package/template/app/api/agui/route.ts

@@ -0,0 +1,56 @@
+import { NextRequest } from 'next/server'
+import { EventType, type RunAgentInput } from '@ag-ui/client'
+import { EventEncoder } from '@ag-ui/encoder'
+import { AGUIAgent } from '@genui/a3'
+import { getChatSessionInstance } from '@agents'
+import { initRegistry } from '@agents/registry'
+
+const a3Agent = new AGUIAgent({
+  agentId: 'a3-demo',
+  createSession: (input: RunAgentInput) => getChatSessionInstance({ sessionId: input.threadId }),
+})
+
+export async function POST(request: NextRequest) {
+  const body = (await request.json()) as RunAgentInput
+
+  const encoder = new EventEncoder()
+  const events$ = a3Agent.run(body)
+
+  initRegistry()
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const textEncoder = new TextEncoder()
+      const subscription = events$.subscribe({
+        next(event) {
+          controller.enqueue(textEncoder.encode(encoder.encodeSSE(event)))
+        },
+        error(err) {
+          const errorEvent = {
+            type: EventType.RUN_ERROR,
+            message: String(err),
+          }
+          controller.enqueue(textEncoder.encode(encoder.encodeSSE(errorEvent)))
+          controller.close()
+        },
+        complete() {
+          controller.close()
+        },
+      })
+
+      // Clean up on cancel
+      request.signal.addEventListener('abort', () => {
+        subscription.unsubscribe()
+        controller.close()
+      })
+    },
+  })
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': encoder.getContentType(),
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  })
+}

package/template/app/api/chat/route.ts

@@ -0,0 +1,35 @@
+/**
+ * Synchronous (blocking / unary) chat endpoint.
+ * This is the non-streaming version of the /api/stream endpoint.
+ * It waits for the full agent response before returning a complete JSON payload.
+ */
+import { NextRequest, NextResponse } from 'next/server'
+import { getChatSessionInstance } from '@agents'
+import { initRegistry } from '@agents/registry'
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = (await request.json()) as { message?: string; sessionId?: string }
+    const { message, sessionId = 'demo-session' } = body
+
+    if (!message) {
+      return NextResponse.json({ error: 'Message is required' }, { status: 400 })
+    }
+
+    initRegistry()
+
+    const session = getChatSessionInstance({ sessionId })
+    const result = await session.send({ message })
+
+    return NextResponse.json({
+      response: result.responseMessage,
+      activeAgentId: result.activeAgentId,
+      nextAgentId: result.nextAgentId,
+      state: result.state,
+      goalAchieved: result.goalAchieved,
+    })
+  } catch (error) {
+    console.error('Chat error:', error)
+    return NextResponse.json({ error: 'Internal server error', details: String(error) }, { status: 500 })
+  }
+}

package/template/app/api/stream/route.ts

@@ -0,0 +1,57 @@
+import { NextRequest } from 'next/server'
+import { getChatSessionInstance } from '@agents'
+import { SESSION_IDS } from '@constants/chat'
+import { AgentRegistry } from '@genui/a3'
+import type { State } from '@agents/state'
+import { onboardingAgent } from '@agents/onboarding'
+import { initRegistry } from '@agents/registry'
+
+export async function POST(request: NextRequest) {
+  const body = (await request.json()) as { message?: string; sessionId?: string }
+  const { message, sessionId = 'demo-stream-session' } = body
+
+  if (!message) {
+    return new Response(JSON.stringify({ error: 'Message is required' }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+
+  let session = getChatSessionInstance({ sessionId })
+  initRegistry()
+  if (sessionId === SESSION_IDS.ONBOARDING) {
+    const registry = AgentRegistry.getInstance<State>()
+    registry.register(onboardingAgent)
+    session = getChatSessionInstance({ sessionId, initialAgentId: onboardingAgent.id })
+  }
+
+  const encoder = new TextEncoder()
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const event of session.send({ message, stream: true })) {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`))
+        }
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'))
+      } catch (error) {
+        const errorEvent = {
+          type: 'error',
+          error: { message: String(error) },
+          agentId: 'unknown',
+        }
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(errorEvent)}\n\n`))
+      } finally {
+        controller.close()
+      }
+    },
+  })
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  })
+}