feat(examples): ai-ap-builder-freestyle

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-site	Ready	Preview	Comment	Dec 11, 2025 7:19am
rivetkit-serverless	Error			Dec 11, 2025 7:19am

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Dec 11, 2025 7:19am
rivet-inspector	Ignored	Preview		Dec 11, 2025 7:19am

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(examples): ai-ap-builder-freestyle #3617 👈 (View in Graphite)
• fix: add serverless backfill #3588 : 1 other dependent PR (#3622 )
• chore: fix runner config creation #3580
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: AI App Builder Freestyle Example

Overview

This PR adds a comprehensive AI-powered app builder example using Freestyle sandboxes, RivetKit actors, and Anthropic Claude. The example demonstrates a multi-step agentic AI system that can create, modify, and deploy web applications through natural language.

Size: 3,484 additions, 73 deletions across 43 files

---

🎯 Code Quality & Architecture

Strengths

• Well-structured actor pattern: The userApp and userAppList actors demonstrate excellent separation of concerns with clear state management, ephemeral variables, and action organization.
• Good use of RivetKit patterns: Proper use of createState, createVars, broadcast events, and actor-to-actor communication.
• Comprehensive system prompt: The 398-line system message provides clear guidance for the AI agent on project structure, API usage, and best practices.
• Real-time updates: Excellent implementation of streaming updates with step-by-step progress broadcasting to the frontend.

Areas for Improvement

1. Error Handling 🔴

user-app.ts (lines 273-309): Error handling in sendChatMessage could be more robust:

• Generic catch block loses important error context
• No distinction between network errors, timeout errors, and API errors
• Consider specific error types for better debugging and user feedback

// Current:
catch (err) {
  if (err instanceof Error && err.name === "AbortError") { ... }
  console.error("[appStore.sendChatMessage] Error:", err);
  // Generic error message
}

// Suggested: Add more specific error handling
catch (err) {
  if (err instanceof Error) {
    if (err.name === "AbortError") { ... }
    else if (err.message.includes("timeout")) { ... }
    else if (err.message.includes("API key")) { ... }
  }
}

2. Security Concerns 🟡

ai-service.ts (lines 74-99): The Morph edit tool directly writes files without validation:

• No sanitization of target_file path (potential path traversal)
• No validation of file contents before writing
• Files could be written outside intended directories

// Add path validation:
if (target_file.includes("..") || path.isAbsolute(target_file)) {
  throw new Error("Invalid file path");
}

freestyle.ts (lines 4-13): API keys are validated at startup, but consider:

• Adding key format validation (not just presence)
• Masking keys in logs for security

3. Type Safety 🟡

ai-service.ts (lines 146-147): Using any type for tools object:

// eslint-disable-next-line @typescript-eslint/no-explicit-any
const tools: Record<string, Tool<any, any>> = {

While this may be necessary for MCP tool integration, consider defining more specific types or interfaces for better type safety.

AppEditorPage.tsx (line 35): Connection type is any:

const userAppConnectionRef = useRef<any>(null);

Should use proper typing from RivetKit client types.

4. Resource Management 🟡

ai-service.ts (lines 246-251): MCP client cleanup is only in finally block:

• If function returns early or throws before reaching try block, cleanup won't happen
• Consider using a cleanup pattern that handles all code paths

user-app.ts (lines 310-314): finally block clears abort controller, but:

• Should verify connection cleanup in all error scenarios
• Consider adding timeout for abort controller cleanup

5. Performance Considerations 🟡

ai-service.ts (lines 28-36): Lazy initialization of Morph client is good, but:

• No connection pooling or reuse
• Consider caching connections per request context

user-app.ts (lines 199-211): Message conversion happens on every chat:

const coreMessages: CoreMessage[] = previousMessages
  .map((m: UIMessage) => { /* ... */ })
  .filter((m) => m.content.trim() \!== "");

For long conversations, this could be optimized with memoization or incremental updates.

---

🔒 Security Review

Critical Issues

None identified.

Medium Priority

1. Path traversal vulnerability in Morph edit tool (ai-service.ts:74-99)
2. API key exposure - Ensure keys aren't logged (check all console.log statements)
3. Input validation - User messages should be sanitized before AI processing

Low Priority

1. Add rate limiting for AI API calls to prevent abuse
2. Consider adding CSRF protection if not already handled by framework
3. Validate domain names in publishApp action (user-app.ts:335)

---

🧪 Test Coverage

Missing: No test files included in this PR.

Recommendations:

1. Add unit tests for actor actions (especially sendChatMessage, createApp)
2. Integration tests for AI service with mocked responses
3. E2E tests for critical user flows (create app, send message, publish)
4. Test error scenarios (API failures, timeouts, invalid inputs)

---

📊 Performance

Potential Issues

1. Memory leak risk: Long-running conversations could accumulate large message arrays in actor state

   • Consider implementing message pagination or archival
   • Add max message limit per app

2. Streaming overhead: Broadcasting every character update could be expensive

   • Consider throttling updates (e.g., batch updates every 100ms)

3. MCP client creation: Creating new client per message (ai-service.ts:132-136)

   • Consider connection pooling if performance becomes an issue

---

🎨 Code Style & Conventions

Follows CLAUDE.md Guidelines ✅

• Uses hard tabs (configured in project)
• Proper structured logging with tracing
• Follows timestamp conventions (createdAt)
• Good use of TypeScript interfaces

Minor Style Issues

1. Inconsistent logging prefixes: Mix of [sendMessage], [appStore.sendChatMessage]

   • Standardize to component/function names

2. Magic numbers: Some hardcoded values could be constants

   // user-app.ts:130
   if (c.vars.streamStatus && Date.now() - c.vars.streamLastUpdate > 15000) {
   // Consider: const STREAM_TIMEOUT_MS = 15000;

3. Comment clarity: Some inline comments are verbose

   • Example: user-app.ts:50-51 could be more concise

---

🐛 Potential Bugs

High Priority

1. Race condition in AppEditorPage.tsx (lines 56-63):

   const setupConnections = async () => {
     const userAppConnection = await client.userApp.get([appId]).connect();
     if (\!mounted) {
       userAppConnection?.dispose?.();
       return;
     }

   If component unmounts during connection setup, disposal is conditional. Should use try-finally.

2. Message deduplication (user-app.ts:167-171):

   const existingMessage = c.state.messages.find((m) => m.id === message.id);
   if (\!existingMessage) {
     c.state.messages.push(message);

   This only checks for duplicates, but doesn't handle the case where a message with the same ID already exists (should it update or skip?).

Medium Priority

1. Undefined behavior: ai-service.ts:93 - No null check for response.choices[0]
2. Missing validation: user-app-list.ts:31 - No validation that appId is a valid format

---

📝 Documentation

Good

• Inline comments explain complex logic
• Type interfaces are well-documented
• System prompt provides comprehensive guidance

Could Improve

1. Add JSDoc comments for public actor actions
2. Document the streaming message protocol (stepUpdate format)
3. Add README specific to this example (setup, env vars, architecture)
4. Document error codes and handling strategies

---

✅ Recommendations

Must Fix (Before Merge)

1. Add path validation in Morph edit tool to prevent path traversal
2. Fix race condition in connection cleanup (AppEditorPage.tsx)
3. Add null checks for API response handling

Should Fix (High Priority)

1. Improve error handling in sendChatMessage with specific error types
2. Add type safety for connection and tool types (remove any)
3. Implement message pagination or archival to prevent memory issues
4. Add basic test coverage for critical paths

Nice to Have (Low Priority)

1. Add rate limiting for AI calls
2. Standardize logging prefixes
3. Extract magic numbers to constants
4. Add comprehensive JSDoc documentation
5. Consider connection pooling for performance optimization

---

🎯 Overall Assessment

Quality Score: 7.5/10

This is a well-architected example that demonstrates advanced RivetKit patterns and AI integration. The code is generally clean and follows project conventions. The main areas for improvement are:

• Security hardening (path validation)
• Error handling robustness
• Test coverage
• Type safety improvements

The PR shows strong understanding of actor patterns, real-time communication, and AI agent orchestration. With the recommended fixes, this would be an excellent example for the community.

---

Minor Issue: RivetKit Error Type Fix

rivetkit-typescript/packages/rivetkit/src/actor/errors.ts:95
Good catch on the typo fix:

-"Variables not enabled. Must implement `createVars` or `vars` to use state..."
+"Variables not enabled. Must implement `createVars` or `vars` to use variables..."

This correctly changes "state" to "variables" in the error message. ✅