Oussama Douhou oussamadouhou
0 Followers · 0 Following
  • Joined on 2025-03-08
Repositories
6
 Projects
1
 Packages Public Activity Starred Repositories

@oussamadouhou/session-sync (1.1.0)

Published 2026-01-28 01:37:57 +00:00 by oussamadouhou

Installation

@oussamadouhou:registry=
npm install @oussamadouhou/session-sync@1.1.0
"@oussamadouhou/session-sync": "1.1.0"

About this package

@oussamadouhou/session-sync

OpenCode plugin that syncs sessions, messages, and tool executions to the Session Manager API.

Installation

npm install -g @oussamadouhou/session-sync

Or in your opencode.json:

{
  "plugin": ["@oussamadouhou/session-sync"]
}

Configuration

Set the following environment variables:

# Required - API key for authentication
export SESSION_API_KEY="your-api-key"

# Optional - API base URL (default: https://session.intra.flexinit.nl)
export SESSION_API_URL="https://session.intra.flexinit.nl"

# Optional - Enable/disable sync (default: true)
export SESSION_SYNC_ENABLED="true"

# Optional - Enable debug logging (default: false)
export SESSION_SYNC_DEBUG="true"

# Optional - Batch size for message sync (default: 10)
export SESSION_SYNC_BATCH_SIZE="10"

# Optional - Retry attempts on API failure (default: 3)
export SESSION_SYNC_RETRY_ATTEMPTS="3"

# Optional - Initial retry delay in milliseconds (default: 1000)
export SESSION_SYNC_RETRY_DELAY_MS="1000"

# Optional - Max dedup map entries to prevent memory leaks (default: 10000)
export SESSION_SYNC_MAX_DEDUP_ENTRIES="10000"

# Optional - Health check interval in milliseconds (default: 300000 = 5 min, 0 to disable)
export SESSION_SYNC_HEALTH_CHECK_INTERVAL_MS="300000"

Features

  • Real-time Session Sync: Automatically syncs session creation and updates
  • Message Batching: Groups messages for efficient API calls
  • Deduplication: Prevents duplicate syncs within 5-second windows with bounded memory
  • Retry with Backoff: Configurable retry with exponential backoff on failures
  • Health Check: Periodic API connectivity verification with status reporting
  • Graceful Shutdown: Proper cleanup on SIGINT, SIGTERM, and SIGHUP signals
  • Todo Tracking: Syncs todo items from sessions
  • Compaction Context: Adds sync and health status to session compaction summaries

What Gets Synced

Event Data Synced
session.created Session metadata (id, project, directory, title)
session.updated Updated session metadata
session.compacted Session metadata after compaction
chat.message Message content, role, model, tokens, cost
todo.updated Todo items with status and priority

How It Works

  1. Session Events: When a session is created or updated, the plugin immediately syncs session metadata to the API.

  2. Message Batching: Messages are queued and flushed in batches every 2 seconds (or 10 seconds if idle) to reduce API calls.

  3. Deduplication: Each session and message is tracked to prevent duplicate syncs within a 5-second window.

  4. Retry Logic: Failed API calls are retried with exponential backoff. Configurable via SESSION_SYNC_RETRY_ATTEMPTS (default: 3) and SESSION_SYNC_RETRY_DELAY_MS (default: 1000ms).

  5. Health Check: The plugin periodically checks API connectivity (default: every 5 minutes). Health status is included in session compaction context. Configure interval via SESSION_SYNC_HEALTH_CHECK_INTERVAL_MS or set to 0 to disable.

  6. Memory Management: Deduplication maps are bounded to prevent memory leaks under high load. Configure max entries via SESSION_SYNC_MAX_DEDUP_ENTRIES (default: 10000).

API Endpoint

The plugin sends data to POST /admin/sync with the following payload:

{
  session: {
    id: string;
    version: string;
    project_id: string;
    directory: string;
    title?: string;
    created_at: number;
    updated_at?: number;
    metadata?: object;
  };
  messages?: Array<{
    id: string;
    role: string;
    agent?: string;
    provider_id?: string;
    model_id?: string;
    created_at: number;
    completed_at?: number;
    cost?: number;
    tokens_input?: number;
    tokens_output?: number;
  }>;
  parts?: Array<{
    id: string;
    message_id: string;
    type: string;
    text?: string;
    tool_name?: string;
    tool_status?: string;
  }>;
  todos?: Array<{
    task_id: string;
    content: string;
    status: string;
    priority?: string;
  }>;
}

Debug Mode

Enable debug logging to see sync activity:

export SESSION_SYNC_DEBUG="true"

Output example:

[Session Sync] Initialized - API: https://session.intra.flexinit.nl
[Session Sync] Session created: ses_abc123
[Session Sync] Synced session ses_abc123: { messages: 5, parts: 12, todos: 0 }
[Session Sync] Message captured: msg_xyz789 (session: ses_abc123)

Development

# Install dependencies
bun install

# Build TypeScript
bun run build

# Watch mode
bun run dev

# Test locally
# Add to .opencode/opencode.jsonc:
# "plugin": ["file:///absolute/path/to/dist/index.js"]

Troubleshooting

No data syncing

  1. Check SESSION_API_KEY is set
  2. Check SESSION_SYNC_ENABLED is not "false"
  3. Enable debug mode: SESSION_SYNC_DEBUG=true

Duplicate syncs

The plugin has built-in deduplication (5s window). If you see duplicates:

  • Check if multiple plugin instances are running
  • Verify you're not loading the plugin twice in config

API errors

Enable debug mode to see retry attempts:

[Session Sync] Retry 1/3 in 1000ms: API error 401: Unauthorized

Health check status

The plugin includes a health check endpoint. In debug mode, you'll see:

[Session Sync] Health check: OK (45ms)
[Session Sync] Health check FAILED: Network error

Health status is also included in session compaction summaries.

License

MIT

Author

Oussama Douhou

Dependencies

Development Dependencies

ID Version
@types/node ^22.0.0
bun-types ^1.2.0
typescript ^5.7.0

Peer Dependencies

ID Version
@opencode-ai/plugin >=1.0.0

Keywords

opencode opencode-plugin plugin session-sync session-manager api-sync ai llm
Details
npm
2026-01-28 01:37:57 +00:00
1
Oussama Douhou
Project Site
MIT
8.5 KiB
Assets (1)
session-sync-1.1.0.tgz 8.5 KiB
Versions (2) View all
1.2.0 2026-01-28
1.1.0 2026-01-28