Package Structure & Responsibilities

Core Principle

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

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

Package Responsibilities

Framework Structure

Viber is distributed as a single unified package (viber) with targeted exports for framework integrations. This simplifies dependency management while maintaining modular separation of concerns.

viber (Main Export)

Import: import { ... } from "viber"

The core runtime engine that allows you to build, orchestrate, and run agents.

Contains:

• Core Abstractions: Agent, Space, Task, Plan
• Orchestration: XAgent (The project manager)
• Data Types: All shared interfaces and configuration types
• Server Adapters: node adapter integration
• Storage: Built-in support for local (SQLite/FileSystem) and supabase (Cloud) persistence logic
• Tools: Standard toolsets for file I/O, browsing, and search

viber/react

Import: import { ... } from "viber/react"

React integration layer for building custom UIs.

Contains:

• useAgent: Hook for connecting to an agent instance
• useSpace: Hook for managing space state
• AgentProvider: Context provider

viber/svelte

Import: import { ... } from "viber/svelte"

Svelte 5 integration layer using Runes.

Contains:

• createAgentStore: Reactive store for agent state
• createSpaceStore: Reactive store for space management

viber/defaults (Internal)

Default configurations for agents, prompts, and tools are bundled within the main package to provide “batteries-included” functionality.

---

Data Flow

viber (Unified Runtime)
    ↓ manages
Space (Persistent Container)
    ↓ contains
Artifacts, History, Config
    ↓ persisted via
Built-in Storage Adapters (Local/Supabase)

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). Viber 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

Aspect	Task-Oriented	Space-Oriented (Viber)
Lifecycle	Start → Execute → End	Create → Collaborate → Pause → Resume → …
State	Ephemeral	Persistent
Artifacts	Output files	Living documents with history
Context	Per-task	Accumulated across sessions
Use Case	Automation scripts	Document editing, research, collaboration