Core Components

DataLayer

Unified storage backend that wraps Turso (libSQL) for cloud sync or local SQLite for offline use. All subsystems (Task Queue, Agent Mail, Memory System) read and write through the DataLayer.

Storage Modes

ModeBackendUse Case
localSQLite (.jetpack/jetpack.db)Single-machine, offline, quick start
tursoTurso cloud + embedded replicaMulti-machine sync, production

Core Tables

-- Tasks (Task Queue)
CREATE TABLE tasks (
  id TEXT PRIMARY KEY,
  parent_id TEXT,
  title TEXT NOT NULL,
  status TEXT DEFAULT 'pending',
  priority TEXT DEFAULT 'medium',
  required_skills TEXT,        -- JSON array
  dependencies TEXT,           -- JSON array of task IDs
  claimed_by TEXT,
  session_id TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Agents
CREATE TABLE agents (
  id TEXT PRIMARY KEY,
  name TEXT,
  status TEXT DEFAULT 'idle',
  skills TEXT,                 -- JSON array
  session_id TEXT,
  last_heartbeat DATETIME
);

-- Messages (Agent Mail)
CREATE TABLE messages (
  id TEXT PRIMARY KEY,
  type TEXT NOT NULL,
  from_agent TEXT,
  to_agent TEXT,
  payload TEXT,                -- JSON
  thread_id TEXT,
  timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- File Reservations (Advisory)
CREATE TABLE file_reservations (
  id TEXT PRIMARY KEY,
  agent_id TEXT,
  task_id TEXT,
  file_path TEXT,
  reservation_type TEXT,       -- edit | read | create | delete
  status TEXT DEFAULT 'active',
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Memory (Memory System)
CREATE TABLE memories (
  id TEXT PRIMARY KEY,
  type TEXT,
  content TEXT,
  importance REAL DEFAULT 0.5,
  embedding F32_BLOB(1536),    -- Vector column (Turso native)
  metadata TEXT,               -- JSON
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

API Usage

import { createLibSQLLocalDataLayer } from '@jetpack-agent/data';

// Local mode (default)
const dataLayer = await createLibSQLLocalDataLayer('.jetpack/jetpack.db');

// Turso mode (cloud sync + embedded replicas)
import { createTursoDataLayer } from '@jetpack-agent/data';
const dataLayer = await createTursoDataLayer({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

// Access sub-interfaces (DataLayer is an interface, not a class)
dataLayer.tasks          // Task operations (create, list, claim, update)
dataLayer.messages       // Agent Mail operations (broadcast, send, receive)
dataLayer.memories       // Memory operations (store, getTaskContext)
dataLayer.reservations   // Advisory file reservations
dataLayer.leases         // Hard exclusive leases

Turso Embedded Replicas

In Turso mode, the DataLayer keeps a local embedded replica that syncs with the cloud database. This gives you local-speed reads with cloud durability.

Agent writes task update
    │
    ▼
Local embedded replica (.turso/local.db)
    │
    ├─► Immediate local read (fast)
    └─► Async sync to Turso cloud
            │
            ▼
        Other agents see update on next sync