Package Structure & Responsibilities

Core Principle

VibeX is a Space-oriented collaborative workspace platform. Unlike task-oriented frameworks, VibeX provides persistent workspaces where artifacts evolve through continuous user-agent collaboration.

The vibex package is the unified runtime engine that manages Spaces, XAgents, artifact evolution, and defines adapter interfaces. Storage implementations are provided by @vibex/local (SQLite/filesystem) and @vibex/supabase (cloud).

Package Responsibilities

vibex - The Space-Oriented Runtime

Position: Central runtime that manages persistent workspaces, artifact evolution, and defines data interfaces.

Contains:

• ✅ Space Management

  • Space container (persistent workspace)
  • Artifact management with version history
  • Conversation history persistence
  • Configuration management
  • SpaceManager - Unified access layer

• ✅ Mission/Plan/Task Management

  • Mission: User’s substantial goals with lifecycle
  • Plan: Strategy that evolves with feedback
  • Task: Individual work items within a Plan

• ✅ XAgent (Project Manager)

  • User-facing interface for each Space
  • Coordinates specialist agents
  • Maintains context across sessions
  • Creates and adapts Plans

• ✅ Specialist Agents

  • Base Agent class
  • Agent registry
  • Tool integration
  • Agent factory (createVibexAgent)

• ✅ Execution Engine (Internal)

  • DAG-based execution for complex operations
  • Pause/resume capability
  • Human-in-the-loop steps

• ✅ Adapter Interfaces (ResourceAdapter, StorageAdapter, KnowledgeAdapter)

Does NOT contain:

• ❌ Storage implementations (see @vibex/local, @vibex/supabase)

Dependencies:

• Uses @vibex/core for shared types
• Uses @vibex/tools for tool implementations
• Uses @vibex/defaults for configurations

@vibex/core - Shared Types

Position: Type definitions shared across all packages.

Contains:

• ✅ Agent types (AgentConfig, AgentContext, AgentResponse)
• ✅ Tool types (CoreTool, ToolInfo)
• ✅ Message types (ModelMessage, XMessage, XMessagePart)
• ✅ Space types (data models for persistence)
• ✅ Adapter interfaces (ResourceAdapter, StorageAdapter, KnowledgeAdapter)
• ✅ Common types (XError, StreamChunk, ModelConfig)

Key Principle: No runtime code, only type definitions.

@vibex/local - Local Storage Implementations

Position: Local/offline storage implementations using SQLite and filesystem.

Contains:

• ✅ LocalResourceAdapter - SQLite for structured data
• ✅ LocalStorageAdapter - Filesystem for artifact files
• ✅ LocalKnowledgeAdapter - JSON + in-memory vectors

@vibex/supabase - Cloud Backend

Position: Supabase implementations for cloud deployment.

Contains:

• ✅ SupabaseResourceAdapter - PostgreSQL for structured data
• ✅ SupabaseStorageAdapter - Supabase Storage for files
• ✅ SupabaseKnowledgeAdapter - pgvector for embeddings

@vibex/tools - Tool Library

Position: First-party tool implementations.

Contains:

• ✅ Web browsing (Playwright)
• ✅ File I/O
• ✅ Search operations
• ✅ Database tools
• ✅ Browser Agent

@vibex/react - React Integration

Position: React-facing API for building frontends.

Contains:

• ✅ React hooks (useXChat)
• ✅ Message types (XChatMessage, XChatStatus)
• ✅ Utility functions for message handling
• ✅ Server actions wrapper

@vibex/defaults - Configurations

Position: Default configurations and templates.

Contains:

• ✅ Default agent configurations (YAML)
• ✅ Prompt templates
• ✅ Space templates
• ✅ Tool configurations

Data Flow

vibex (Runtime)
    ↓ manages
Space (Persistent Container)
    ↓ contains
Artifacts, History, Config
    ↓ persisted via
SpaceManager + Adapters
    ↓ uses implementations from
@vibex/local (SQLite/FS) or @vibex/supabase (Cloud)

Key Concepts

Hierarchy

Space (persistent container)
  └── Mission (user's substantial goal)
        └── Plan (strategy, evolves)
              └── Task[] (individual work items)

Note: Our “Task” is different from AI SDK’s “steps” (multi-turn tool loops). VibeX Tasks are higher-level work items.

Mission Lifecycle

// Create a Space and start a Mission
const space = await XAgent.start("Write my thesis");
// Creates: Space + Mission("Write my thesis") + initial Plan
 
// Work on Tasks within the Plan
await xAgent.chat("Write the introduction"); // Executes Task, creates artifact v1
await xAgent.chat("Make it more concise"); // Creates artifact v2
 
// Resume later (next day, next week...)
const space = await XAgent.resume(spaceId);
await xAgent.chat("Now work on chapter 2"); // Full context preserved, Plan adapts

Artifact Evolution

// Artifacts are versioned automatically
thesis.md
├── v1: Initial draft
├── v2: More concise
├── v3: Added citations
└── v4: Final polish
 
// Can access any version
const v2 = await space.getArtifactVersion("thesis.md", 2);

Context Accumulation

// Context builds up over the session
await xAgent.chat("Research topic X"); // Context: research
await xAgent.chat("Focus on Y aspect"); // Context: research + Y
await xAgent.chat("Write a summary"); // Context: research + Y + findings
// XAgent knows everything discussed

Comparison to Task-Oriented Design