@gamalan/pi-gateway 1.0.0

package/dist/sessions/store.js

@@ -0,0 +1,247 @@
+/**
+ * Session Store - Hermes-style per-chat session management
+ *
+ * Features:
+ * - Per-chat sessions with unique IDs
+ * - Reset policies: daily (hour-based) and idle (minutes-based)
+ * - Session persistence across restarts
+ * - Background session isolation
+ */
+import Database from "better-sqlite3";
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, mkdirSync } from "fs";
+import { logger } from "../logger.js";
+const GATEWAY_DIR = join(homedir(), ".pi");
+const SESSIONS_DB = join(GATEWAY_DIR, "gateway-sessions.db");
+let db = null;
+/**
+ * Initialize session database
+ */
+export function initSessionStore() {
+    if (db)
+        return db;
+    if (!existsSync(GATEWAY_DIR)) {
+        mkdirSync(GATEWAY_DIR, { recursive: true });
+    }
+    db = new Database(SESSIONS_DB);
+    db.exec("PRAGMA journal_mode = WAL;");
+    // Sessions table
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      platform TEXT NOT NULL,
+      channel_id TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      reset_policy TEXT NOT NULL DEFAULT 'idle',
+      daily_hour INTEGER NOT NULL DEFAULT 4,
+      idle_minutes INTEGER NOT NULL DEFAULT 1440,
+      last_activity INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      is_background INTEGER NOT NULL DEFAULT 0,
+      parent_session_id TEXT,
+      FOREIGN KEY (parent_session_id) REFERENCES sessions(id)
+    )
+  `);
+    // Indexes for fast lookups
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_platform_channel ON sessions(platform, channel_id)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_activity ON sessions(last_activity)`);
+    logger.info("[SessionStore] Database initialized");
+    return db;
+}
+/**
+ * Generate unique session ID
+ */
+export function generateSessionId() {
+    return `sess-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+/**
+ * Get or create session for a platform/channel
+ */
+export function getOrCreateSession(platform, channelId, userId, config) {
+    const database = initSessionStore();
+    // Try to find existing active session
+    const existing = database
+        .prepare(`
+    SELECT * FROM sessions 
+    WHERE platform = ? AND channel_id = ? AND is_background = 0
+    ORDER BY last_activity DESC
+    LIMIT 1
+  `)
+        .get(platform, channelId);
+    if (existing) {
+        // Check if session needs reset
+        if (shouldResetSession(existing)) {
+            // Delete old session, create fresh one
+            database.prepare("DELETE FROM sessions WHERE id = ?").run(existing.id);
+        }
+        else {
+            // Update last activity and return
+            database
+                .prepare("UPDATE sessions SET last_activity = ? WHERE id = ?")
+                .run(Date.now(), existing.id);
+            return rowToSession(existing);
+        }
+    }
+    // Create new session
+    const id = generateSessionId();
+    const now = Date.now();
+    const session = {
+        id,
+        platform,
+        channelId,
+        userId,
+        resetPolicy: config?.resetPolicy ?? "idle",
+        dailyHour: config?.dailyHour ?? 4,
+        idleMinutes: config?.idleMinutes ?? 1440,
+        lastActivity: now,
+        createdAt: now,
+        isBackground: false,
+        ...config,
+    };
+    database
+        .prepare(`
+    INSERT INTO sessions (id, platform, channel_id, user_id, reset_policy, daily_hour, idle_minutes, last_activity, created_at, is_background, parent_session_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `)
+        .run(session.id, session.platform, session.channelId, session.userId, session.resetPolicy, session.dailyHour, session.idleMinutes, session.lastActivity, session.createdAt, session.isBackground ? 1 : 0, session.parentSessionId ?? null);
+    logger.info(`[SessionStore] Created session ${id.slice(0, 12)}... for ${platform}/${channelId}`);
+    return session;
+}
+/**
+ * Create a background session (isolated from parent)
+ */
+export function createBackgroundSession(platform, channelId, userId, parentSessionId) {
+    const database = initSessionStore();
+    const id = generateSessionId();
+    const now = Date.now();
+    const session = {
+        id,
+        platform,
+        channelId,
+        userId,
+        resetPolicy: "idle",
+        dailyHour: 4,
+        idleMinutes: 1440,
+        lastActivity: now,
+        createdAt: now,
+        isBackground: true,
+        parentSessionId,
+    };
+    database
+        .prepare(`
+    INSERT INTO sessions (id, platform, channel_id, user_id, reset_policy, daily_hour, idle_minutes, last_activity, created_at, is_background, parent_session_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `)
+        .run(session.id, session.platform, session.channelId, session.userId, session.resetPolicy, session.dailyHour, session.idleMinutes, session.lastActivity, session.createdAt, 1, // is_background
+    session.parentSessionId ?? null);
+    logger.info(`[SessionStore] Created background session ${id.slice(0, 12)}...`);
+    return session;
+}
+/**
+ * Check if session should be reset
+ */
+function shouldResetSession(row) {
+    const now = Date.now();
+    // Check idle timeout
+    const idleMs = row.idle_minutes * 60 * 1000;
+    if (now - row.last_activity > idleMs) {
+        logger.info(`[SessionStore] Session ${row.id.slice(0, 8)} reset: idle timeout`);
+        return true;
+    }
+    // Check daily reset
+    if (row.reset_policy === "daily" || row.reset_policy === "both") {
+        const lastActivity = new Date(row.last_activity);
+        const nowDate = new Date(now);
+        // Check if we crossed the daily reset hour since last activity
+        if (lastActivity.getHours() < row.daily_hour &&
+            nowDate.getHours() >= row.daily_hour) {
+            logger.info(`[SessionStore] Session ${row.id.slice(0, 8)} reset: daily at ${row.daily_hour}:00`);
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Update session last activity
+ */
+export function touchSession(sessionId) {
+    const database = initSessionStore();
+    database
+        .prepare("UPDATE sessions SET last_activity = ? WHERE id = ?")
+        .run(Date.now(), sessionId);
+}
+/**
+ * Get session by ID
+ */
+export function getSession(sessionId) {
+    const database = initSessionStore();
+    const row = database
+        .prepare("SELECT * FROM sessions WHERE id = ?")
+        .get(sessionId);
+    return row ? rowToSession(row) : null;
+}
+/**
+ * Delete session
+ */
+export function deleteSession(sessionId) {
+    const database = initSessionStore();
+    database.prepare("DELETE FROM sessions WHERE id = ?").run(sessionId);
+}
+/**
+ * List sessions by platform
+ */
+export function listSessions(platform) {
+    const database = initSessionStore();
+    const query = platform
+        ? "SELECT * FROM sessions WHERE platform = ? AND is_background = 0 ORDER BY last_activity DESC"
+        : "SELECT * FROM sessions WHERE is_background = 0 ORDER BY last_activity DESC";
+    const rows = platform
+        ? database.prepare(query).all(platform)
+        : database.prepare(query).all();
+    return rows.map(rowToSession);
+}
+/**
+ * Clean up stale sessions
+ */
+export function cleanupStaleSessions() {
+    const database = initSessionStore();
+    const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000; // 7 days
+    const result = database
+        .prepare("DELETE FROM sessions WHERE last_activity < ?")
+        .run(cutoff);
+    return result.changes;
+}
+/**
+ * Get background sessions for delivery
+ */
+export function getPendingBackgroundResults() {
+    const database = initSessionStore();
+    // Background sessions that exist but parent still needs delivery
+    const rows = database
+        .prepare(`
+    SELECT s.* FROM sessions s
+    WHERE s.is_background = 1
+    ORDER BY s.created_at ASC
+  `)
+        .all();
+    return rows.map(rowToSession);
+}
+// Helper to convert DB row to SessionConfig
+function rowToSession(row) {
+    return {
+        id: row.id,
+        platform: row.platform,
+        channelId: row.channel_id,
+        userId: row.user_id,
+        resetPolicy: row.reset_policy,
+        dailyHour: row.daily_hour,
+        idleMinutes: row.idle_minutes,
+        lastActivity: row.last_activity,
+        createdAt: row.created_at,
+        isBackground: row.is_background === 1,
+        parentSessionId: row.parent_session_id ?? undefined,
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/sessions/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/sessions/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@gamalan/pi-gateway",
+  "version": "1.0.0",
+  "description": "Hermes-style messaging gateway for pi - multi-platform agent with sessions, security, and background tasks",
+  "author": "0xKobold <original>; forked by gamalan",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["pi-package", "pi-extension", "gateway", "messaging", "hermes", "multi-platform"],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "config/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npx tsx tests/index.ts",
+    "demo": "npx tsx tests/demo-server.ts",
+    "client": "npx tsx tests/client-demo.ts",
+    "prepublishOnly": "rm -rf dist && tsc"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.37",
+    "@types/ws": "^8.18.1",
+    "@whiskeysockets/baileys": "^7.0.0-rc13",
+    "@types/better-sqlite3": "^7.6.0",
+    "tsx": "^4.19.0",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.3",
+    "@sinclair/typebox": ">=0.32.0"
+  },
+  "pi": {
+    "extensions": ["./dist/index.js"]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gamalan/pi-gateway.git"
+  }
+}

package/src/adapters/base.ts

@@ -0,0 +1,124 @@
+/**
+ * Platform Adapter Base - Interface for Hermes-style platform adapters
+ */
+
+export interface PlatformMessage {
+	id: string;
+	platform: string;
+	channelId: string;
+	userId: string;
+	content: string;
+	timestamp: number;
+	metadata?: Record<string, unknown>;
+}
+
+export interface PlatformConfig {
+	enabled: boolean;
+	platform: string;
+	token?: string;
+	botToken?: string;
+	webhookSecret?: string;
+}
+
+export interface AdapterCallbacks {
+	onMessage: (message: PlatformMessage) => Promise<void>;
+	onTyping?: (userId: string, isTyping: boolean) => void;
+	onDisconnect?: () => void;
+}
+
+export interface PlatformAdapter {
+	readonly platform: string;
+	readonly config: PlatformConfig;
+
+	/**
+	 * Initialize the adapter
+	 */
+	initialize(): Promise<void>;
+
+	/**
+	 * Start listening for messages
+	 */
+	start(callbacks: AdapterCallbacks): Promise<void>;
+
+	/**
+	 * Stop listening
+	 */
+	stop(): Promise<void>;
+
+	/**
+	 * Send a message to a channel
+	 */
+	sendMessage(channelId: string, content: string): Promise<string>; // Returns message ID
+
+	/**
+	 * Edit an existing message
+	 */
+	editMessage(
+		channelId: string,
+		messageId: string,
+		content: string,
+	): Promise<void>;
+
+	/**
+	 * Delete a message
+	 */
+	deleteMessage(channelId: string, messageId: string): Promise<void>;
+
+	/**
+	 * Set typing indicator
+	 */
+	setTyping(channelId: string, isTyping: boolean): Promise<void>;
+
+	/**
+	 * Get adapter health status
+	 */
+	getStatus(): Promise<{ connected: boolean; latency?: number }>;
+}
+
+/**
+ * Abstract base class for adapters
+ */
+export abstract class BaseAdapter implements PlatformAdapter {
+	abstract readonly platform: string;
+	abstract config: PlatformConfig;
+	protected callbacks: AdapterCallbacks | null = null;
+	protected running = false;
+
+	async initialize(): Promise<void> {
+		// Override in subclass
+	}
+
+	async start(callbacks: AdapterCallbacks): Promise<void> {
+		this.callbacks = callbacks;
+		this.running = true;
+	}
+
+	async stop(): Promise<void> {
+		this.running = false;
+		this.callbacks = null;
+	}
+
+	abstract sendMessage(channelId: string, content: string): Promise<string>;
+	abstract editMessage(
+		channelId: string,
+		messageId: string,
+		content: string,
+	): Promise<void>;
+	abstract deleteMessage(channelId: string, messageId: string): Promise<void>;
+	abstract setTyping(channelId: string, isTyping: boolean): Promise<void>;
+	abstract getStatus(): Promise<{ connected: boolean; latency?: number }>;
+
+	protected emitMessage(message: PlatformMessage): Promise<void> {
+		if (this.callbacks?.onMessage) {
+			return this.callbacks.onMessage(message).catch((err) => {
+				// Log but don't crash the adapter loop
+				console.error(`[${this.platform}] Error in onMessage callback:`, err);
+			}) as Promise<void>;
+		}
+		return Promise.resolve();
+	}
+
+	protected generateMessageId(): string {
+		return `${this.platform}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+	}
+}