WIP: Example custom ikp message

[sarah-inkeep]

[vercel[bot]]

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

Project	Deployment	Preview	Comments	Updated (UTC)
agents-docs	Ready	Preview	Comment	Sep 17, 2025 3:55am
agents-manage-api	Ready	Preview	Comment	Sep 17, 2025 3:55am
agents-manage-ui	Ready	Preview	Comment	Sep 17, 2025 3:55am
agents-run-api	Ready	Preview	Comment	Sep 17, 2025 3:55am

[claude[bot]]

Claude finished @sarah-inkeep's task —— View job

---

PR Review: Custom IKP Message Component

This PR adds a custom IkpMessage component for the agents-ui package. After analyzing the implementation and comparing it to existing patterns, I have several architectural and code quality concerns to address.

Review Progress:

• [x] Read changed files and understand implementation
• [x] Research existing codebase patterns
• [x] Check repo guidelines and conventions
• [x] Analyze code quality and architecture
• [x] Provide comprehensive feedback

---

🚨 Critical Architecture Issues

1. Duplication and Inconsistency (HIGH PRIORITY)

There are now two different IkpMessage implementations in the codebase:

• New: agents-ui/src/IkpMessage.tsx (71 lines, basic functionality)
• Existing: agents-manage-ui/src/components/graph/playground/ikp-message.tsx (495 lines, full-featured)

Problems:

• The existing implementation at agents-manage-ui/src/components/graph/playground/ikp-message.tsx:341-492 is significantly more sophisticated, handling:

  • Citations and tooltips
  • Data operations with expandable UI
  • Streaming states with loading indicators
  • Artifacts and source references
  • Complex markdown rendering with Streamdown
  • Proper accessibility with ARIA patterns

• The new implementation is a basic subset that only handles text rendering

• This creates two sources of truth for the same component concept

• No abstraction or shared base component

Recommendation: Either consolidate these implementations or create a proper abstraction layer to avoid code duplication and inconsistency.

2. Missing Repository Requirements Compliance

According to CLAUDE.md:154-184, ALL new features MUST include:

• ❌ Unit Tests: No tests found in agents-ui/__tests__/ or *.test.ts files
• ❌ UI Components in agents-manage-ui: This is only adding to agents-ui
• ❌ Documentation updates: The MDX snippet is documentation, but doesn't follow the required pattern of updating agents-docs/content/docs/ with navigation updates

🔍 Code Quality & Design Issues

3. Type Safety Concerns (MEDIUM PRIORITY)

// agents-ui/src/IkpMessage.tsx:54-55
const DataArtifact = ({ messagePart }: { messagePart: Message['parts'][number] }) => {
  const { data } = messagePart; // ❌ Unsafe access - no type guard

Issue: Direct access to data property without type checking. The existing implementation properly handles this.

4. Inconsistent Error Handling (MEDIUM PRIORITY)

// agents-ui/src/IkpMessage.tsx:12-15
{message.parts
  .filter((part) => part.type === 'text')
  .map((part) => part.text) // ❌ Could be undefined
  .join('')}

Issue: No null/undefined checks on part.text. The existing implementation uses part.text || ''.

5. Naming and Semantic Issues (LOW-MEDIUM PRIORITY)

// agents-ui/src/IkpMessage.tsx:1
import './App.css'; // ❌ Wrong CSS import

Issue: Importing App.css from a message component is semantically incorrect and creates unnecessary coupling.

6. Component Decomposition Without Clear Purpose (LOW PRIORITY)

The new implementation breaks down into UserMessage and AssistantMessage components, but:

• These aren't reused elsewhere
• The decomposition doesn't provide clear benefits over the existing pattern
• Adds complexity without clear architectural advantage

🎯 Customer Impact Considerations

7. Feature Parity Gap (HIGH PRIORITY)

Customers using this new component will lose significant functionality compared to the existing implementation:

• No citation support
• No data operation visualization
• No streaming indicators
• No accessibility features
• No error boundaries

8. Documentation Inconsistency

The MDX documentation shows a simplified implementation that doesn't match either the new component or the existing full-featured one, creating confusion about capabilities.

📋 Recommendations

Immediate Actions (HIGH PRIORITY)

1. Choose One Approach:

   • Either extend/improve the existing implementation in agents-manage-ui
   • Or create a proper abstraction that both can inherit from
   • Don't maintain two separate implementations

2. Add Required Components:

   • Add unit tests following the pattern in CLAUDE.md:121-138
   • Follow the mandatory requirements from CLAUDE.md:154-184

Code Improvements (MEDIUM PRIORITY)

3. Type Safety:

   // Add proper type guards
   const { data } = messagePart;
   if (!data) return null;
   

4. Error Handling:

   .map((part) => part.text || '')
   

5. Styling Approach:

   • Remove App.css import from message component
   • Use dedicated component CSS or styled-components

Architecture Decisions (SYSTEM LEVEL)

6. Component Strategy: Decide on the component customization strategy:
   • Should there be a base IkpMessage with extension points?
   • Should this be configuration-driven vs. component replacement?
   • How do we maintain feature parity across different use cases?

💡 Positive Aspects

• Clean component structure with logical role-based rendering
• Good TypeScript usage for prop types
• Follows React functional component patterns
• The documentation snippet provides a clear example

🚦 Severity Assessment

• Blockers: Mandatory requirements not met (tests, proper documentation)
• High: Code duplication and feature parity issues
• Medium: Type safety and error handling
• Low: Naming and import issues

---

This PR shows good intent to provide component customization, but needs significant architectural consideration to avoid technical debt and maintain consistency with the existing codebase patterns.