Data Models

Contents

Overview

erDiagram
    DeviceAuthStore ||--o{ DeviceAuthEntry : contains
    DeviceAuthStore {
        number version
        string deviceId
        record tokens
    }
    DeviceAuthEntry {
        string tokenKey
        unknown tokenValue
    }
    QueuedDeliveryPayload ||--|{ QueuedDelivery : extends
    QueuedDeliveryPayload {
        string channel
        string to
        string accountId
        array payloads
        string threadId
        string replyToId
        boolean bestEffort
        boolean gifPlayback
        boolean forceDocument
        boolean silent
        boolean mirror
    }
    QueuedDelivery {
        string id
        number enqueuedAt
        number retryCount
        number lastAttemptAt
        string lastError
    }
    SessionEntry {
        string sessionId
        number updatedAt
        string sessionFile
        string channel
        string chatType
        string execHost
        string modelOverride
        number inputTokens
        number outputTokens
        string spawnedBy
        number spawnDepth
        string subagentRole
    }
    ExecApprovalsFile ||--o{ ExecApprovalRequest : tracks
    ExecApprovalsFile {
        number version
        string socket
        object defaults
        object agents
    }
    ExecApprovalRequest {
        string id
        object request
        number createdAtMs
        number expiresAtMs
    }
    ExecApprovalResolved {
        string id
        string decision
        string resolvedBy
        number ts
    }

The ER diagram above shows how the six core model families relate. DeviceAuthStore aggregates token entries, QueuedDelivery extends the payload envelope with retry metadata, and the approvals file tracks pending and resolved execution requests.

Decision Points

How It Works

Every model in the store layer follows the same lifecycle: define a TypeScript interface, export it, and consume it in exactly one reader function and one writer function. This ensures a single source of truth for every field name and type.

Device Auth Store

The DeviceAuthStore interface wraps all device-level credentials into a single versioned record. The tokens map uses Record<string, unknown> to allow heterogeneous token formats across providers.

/** Versioned device credential schema */
interface DeviceAuthStore {
  version: 1;
  deviceId: string;
  tokens: Record<string, unknown>;
}

/** Individual token entry with CRUD helpers */
interface DeviceAuthEntry {
  tokenKey: string;
  tokenValue: unknown;
}

function loadDeviceAuthToken(
  store: DeviceAuthStore,
  key: string
): DeviceAuthEntry | undefined {
  const value = store.tokens[key];
  if (value === undefined) return undefined;
  return { tokenKey: key, tokenValue: value };
}

function storeDeviceAuthToken(
  store: DeviceAuthStore,
  key: string,
  value: unknown
): void {
  store.tokens[key] = value;
}

function clearDeviceAuthToken(
  store: DeviceAuthStore,
  key: string
): boolean {
  if (!(key in store.tokens)) return false;
  delete store.tokens[key];
  return true;
}

Delivery Queue Models

The delivery system uses a two-layer type hierarchy. QueuedDeliveryPayload captures the intent (what to deliver, where, and how), while QueuedDelivery extends it with operational metadata used by the retry engine.

interface QueuedDeliveryPayload {
  channel: string;
  to: string;
  accountId?: string;
  payloads: unknown[];
  threadId?: string;
  replyToId?: string;
  bestEffort?: boolean;
  gifPlayback?: boolean;
  forceDocument?: boolean;
  silent?: boolean;
  mirror?: boolean;
}

interface QueuedDelivery extends QueuedDeliveryPayload {
  id: string;
  enqueuedAt: number;
  retryCount: number;
  lastAttemptAt?: number;
  lastError?: string;
}

Session Entry

Each active or historical session is represented by a SessionEntry record. The store layer persists these to a JSON5-formatted session store file, keyed by sessionId.

interface SessionEntry {
  sessionId: string;
  updatedAt: number;
  sessionFile?: string;
  channel?: string;
  chatType?: string;
  execHost?: string;
  modelOverride?: string;
  inputTokens?: number;
  outputTokens?: number;
  spawnedBy?: string;
  spawnDepth?: number;
  subagentRole?: string;
}

Execution Approvals

The approvals subsystem tracks pending and resolved execution requests. ExecApprovalsFile is the top-level container persisted to disk, while request and resolution records are indexed by id.

Utility Types

Two small but critical utility types round out the model layer:

Validation Pipeline

flowchart TD
    A["Raw JSON from disk"] --> B["JSON.parse / JSON5.parse"]
    B --> C{"version field present?"}
    C -- Yes --> D["Match version to schema"]
    C -- No --> E["Reject: invalid format"]
    D --> F{"Schema matches current?"}
    F -- Yes --> G["Zod validation pass"]
    F -- No --> H["Run migration pipeline"]
    H --> G
    G --> I{"All required fields valid?"}
    I -- Yes --> J["Return typed object"]
    I -- No --> K["Return validation error"]
    E --> K

The validation pipeline runs every time a model is loaded from disk. Raw JSON is parsed, version-checked, optionally migrated, then validated through a Zod schema. Only fully validated objects are returned to callers; everything else surfaces as a structured error.

Annotated Code Walkthrough

Walk through how the approval models are defined and consumed end-to-end.

interface ExecApprovalsFile {
  version: 1;
  socket?: string;
  defaults?: Record<string, unknown>;
  agents?: Record<string, unknown>;
}

interface ExecApprovalRequest {
  id: string;
  request: ExecApprovalRequestPayload;
  createdAtMs: number;
  expiresAtMs: number;
}

interface ExecApprovalResolved {
  id: string;
  decision: "approved" | "denied";
  resolvedBy?: string;
  ts: number;
}

async function loadApprovalsFile(
  filePath: string
): Promise<ExecApprovalsFile | null> {
  const raw = await readJsonFile<unknown>(filePath);
  if (!raw || typeof raw !== "object") return null;
  const obj = raw as Record<string, unknown>;
  if (obj.version !== 1) return null;
  return obj as ExecApprovalsFile;
}

interface SystemPresence {
  host?: string;
  ip?: string;
  version?: string;
  platform?: string;
  text: string;
  ts: number;
}

interface HeartbeatEventPayload {
  ts: number;
  status: string;
  to?: string;
  channel?: string;
  indicatorType?: string;
}

Edge Cases & Error Handling

Configuration

Related Topics

See also:

• store overview — the parent sub-module page
• State Migrations — how legacy formats are detected and upgraded
• Query Builder — atomic I/O operations that read and write these models

Directory Map

src/infra/store/
├── device-auth.ts             ← DeviceAuthStore & DeviceAuthEntry types + CRUD helpers
├── delivery-queue.ts          ← QueuedDeliveryPayload, QueuedDelivery, enqueue/ack/fail
├── session-store.ts           ← SessionEntry type & JSON5 session store I/O
├── exec-approvals.ts          ← ExecApprovalsFile, ExecApprovalRequest, ExecApprovalResolved
├── archive.ts                 ← ArchiveExtractLimits type & extraction pipeline
├── fs-safe.ts                 ← SafeOpenResult type & validated file handle helpers
├── presence.ts                ← SystemPresence broadcast record
└── heartbeat.ts               ← HeartbeatEventPayload event tracking type