@gamalan/pi-gateway 1.0.0

package/README.md

@@ -0,0 +1,366 @@
+# pi-gateway
+
+Hermes-style messaging gateway for pi — a multi-platform agent with per-chat sessions, background task support, and allowlist security.
+
+> Fork of [0xKobold/pi-gateway](https://github.com/0xKobold/pi-gateway) with config-based UID allowlisting.
+
+## Features
+
+- **Multi-platform adapters** — Discord, Telegram, Slack, Twitch, WhatsApp, WebSocket
+- **Per-chat sessions** — isolated conversations with configurable reset policies (daily / idle)
+- **Background tasks** — spawn async work from chats, results delivered when ready
+- **Allowlist security** — DB-based and config-file pre-approved UIDs, optional DM pairing flow
+- **HTTP + WebSocket API** — connect external clients, send prompts, receive streaming responses
+- **pi-native** — runs as a pi extension with `/gateway` slash commands and registered tools
+
+## Installation
+
+Pi supports installing extensions directly from GitHub:
+
+```bash
+pi install git:github.com/gamalan/pi-gateway
+```
+
+Or clone and build manually:
+
+```bash
+git clone https://github.com/gamalan/pi-gateway.git
+cd pi-gateway
+bun install && bun run build
+pi install .
+```
+
+Requires pi coding agent (`@earendil-works/pi-coding-agent >= 0.80.3`) and `@sinclair/typebox >= 0.32.0`.
+
+## Quick Start
+
+```bash
+# Start the gateway
+/gateway start
+
+# Check status
+/gateway status
+
+# Stop
+/gateway stop
+```
+
+The gateway starts on `http://localhost:3847` by default. See `/gateway config` for current settings.
+
+## Configuration
+
+Configuration lives at `~/.pi/gateway/config.json`:
+
+```jsonc
+{
+  "port": 3847,
+  "host": "localhost",
+  "tokens": [],                    // Bearer tokens for API auth (empty = allow all)
+  "corsOrigins": ["*"],
+  "enableWebSocket": true,
+  "enableHttp": true,
+  "security": {
+    "allowAll": true,              // false = enforce allowlist
+    "requirePairing": false,
+    "allowedUids": {},             // pre-approved users (see Security)
+    "adminUids": {},              // users with full access (see Admin Users)
+    "rateLimit": {
+      "maxRequests": 60,
+      "windowMs": 60000
+    }
+  },
+  "sessions": {
+    "resetPolicy": "idle",         // "daily" | "idle" | "both"
+    "dailyHour": 4,                // hour (0-23) for daily reset
+    "idleMinutes": 1440            // minutes before idle reset
+  },
+  "platforms": {
+    "discord": {
+      "enabled": true,
+      "botToken": "your-token",
+      "guildId": "optional-guild-id"
+    },
+    "twitch": {
+      "enabled": true,
+      "clientId": "your-client-id",
+      "clientSecret": "your-secret",
+      "channels": ["channel-name"]
+    },
+    "telegram": {
+      "enabled": true,
+      "token": "your-bot-token",
+      "webhookUrl": "https://..."  // omit for long polling
+    },
+    "slack": {
+      "enabled": true,
+      "webhookUrl": "https://...",
+      "botToken": "optional-bot-token"
+    },
+    "whatsapp": {
+      "enabled": true,
+      "sessionPath": "~/.pi/whatsapp-session",
+      "printQr": true
+    }
+  }
+}
+```
+
+When the gateway starts for the first time with no config file, it
+automatically seeds `~/.pi/gateway/config.json` from the default
+template shipped with the package.  You can also find it at
+`node_modules/pi-gateway/config/config.default.json`.
+
+### Telegram: webhook vs long polling
+
+The gateway auto-detects the mode based on whether `webhookUrl` is set:
+
+| `webhookUrl` | Mode | How it works |
+|---|---|---|
+| Set | **Webhook** | Telegram POSTs updates to `/webhook/telegram` on the gateway's HTTP server. Lowest latency, requires a public URL. |
+| Omitted | **Long polling** | The gateway opens a persistent connection to Telegram's `getUpdates` endpoint (30s timeout). Telegram holds it open and returns immediately when a message arrives — near-real-time, no public URL needed. |
+
+Both modes are real-time. Long polling is NOT interval-based — it keeps one connection alive at all times.
+
+## Security
+
+### Allowlist (DB)
+
+Manage users at runtime via `/gateway` commands:
+
+```bash
+# List allowlisted users
+/gateway allow
+
+# Add a user
+/gateway allow discord 123456789
+
+# Revoke a user (via tool or directly)
+```
+
+### Config-file pre-approved UIDs
+
+Skip pairing entirely by listing UIDs in the `security` block of `config.json`:
+
+```jsonc
+{
+  "security": {
+    "allowAll": false,
+    "allowedUids": {
+      "discord": ["123456789", "987654321"],
+      "telegram": ["1234567890"],
+      "*": ["cross-platform-admin"]
+    },
+    "adminUids": {
+      "discord": ["123456789"],
+      "*": ["cross-platform-admin-uid"]
+    },
+    "rateLimit": {
+      "maxRequests": 60,
+      "windowMs": 60000
+    }
+  }
+}
+```
+
+- Platform-specific keys match that platform only
+- The `"*"` wildcard matches any platform
+- Users in this list are auto-allowed on first contact — no pairing code needed
+- `adminUids` grants full unrestricted access (bypasses all tool policies)
+- All security settings live in the main `config.json` — no separate security file
+
+### Admin Users
+
+Admin users have **full unrestricted access** — they bypass all tool policies and can use every tool pi offers (bash, write, edit, subagent, etc.).
+
+Admins can be set at runtime or via config's `security.adminUids` block:
+
+```jsonc
+{
+  "security": {
+    "adminUids": {
+      "discord": ["123456789"],
+      "*": ["cross-platform-admin-uid"]
+    }
+  }
+}
+```
+
+```bash
+# List all admins (DB + config)
+/gateway admin list
+
+# Grant admin to a user on a specific platform
+/gateway admin add discord 123456789
+
+# Grant admin on ALL platforms
+/gateway admin add * 123456789
+
+# Revoke admin
+/gateway admin remove discord 123456789
+```
+
+Admin users are listed in the status panel and their messages carry a "FULL ACCESS" guard.
+
+### Tool Policy
+
+By default, external users are **restricted to read-only tools** when their messages reach pi: they can search code, inspect files, and ask questions, but cannot write files, execute shell commands, spawn subagents, or modify system state.
+
+The policy is enforced via a system directive prepended to every forwarded message. It is tunable per platform, per user, or globally.
+
+**Default allowed tools:** `read`, `web_search`, `fetch_content`, `fffind`, `ffgrep`, `module_report`, `read_symbol`, code search tools, `lsp_diagnostics`, `lsp_navigation`, `image_generate`, `gateway_*`
+
+**Default denied tools:** `bash`, `write`, `edit`, `subagent`, `todo`, `goal_complete`, `mcp`, `ast_grep_replace`, `agent_browser`, `ask_user_question`, `wait`, `intercom`, `wiki_*`, `lens_diagnostics`
+
+#### Managing Policies
+
+```bash
+# List all explicit policies
+/gateway tool-policy list
+
+# See the default baseline
+/gateway tool-policy defaults
+
+# Allow bash for a specific user
+/gateway tool-policy set discord U123456 bash allow
+
+# Deny write for all users on Discord
+/gateway tool-policy set discord * write deny
+
+# Allow everything for an admin user (glob)
+/gateway tool-policy set * admin-uid * allow
+
+# Remove a policy by ID
+/gateway tool-policy remove 3
+
+# Reset all custom policies to defaults
+/gateway tool-policy reset
+```
+
+Policies can also be managed from within pi sessions via the `gateway_tool_policy` tool.
+
+**Resolution order** (highest wins): user-specific > platform-specific > global. Ties break deny-first (secure by default). The `*` glob matches any tool name. Admin users always bypass all restrictions.
+
+> **Note:** All security configuration (allowlist, admin UIDs, rate limits)
+> lives in the `security` block of `~/.pi/gateway/config.json`. There is
+> no separate security config file. On first run, the gateway
+> auto-seeds a complete default config so you don't have to write one
+> from scratch.
+
+### Pairing Flow
+
+When `requirePairing` is enabled and a user is not in the allowlist:
+
+1. User sends a message → blocked, receives a pairing code
+2. Admin approves with `/gateway pair <code>`
+3. User is added to the DB allowlist
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/gateway start [port]` | Start the gateway |
+| `/gateway stop` | Stop the gateway |
+| `/gateway restart` | Restart the gateway |
+| `/gateway status` | Show running status, platforms, sessions |
+| `/gateway pair [code]` | List pending codes or approve one |
+| `/gateway allow [platform] [userId]` | List allowlist or add a user |
+| `/gateway revoke <platform> <userId>` | Remove a user from the DB allowlist |
+| `/gateway sessions` | List active chat sessions |
+| `/gateway tasks` | List background tasks |
+| `/gateway config` | Show current configuration |
+| `/gateway admin list` | List admin users (DB + config) |
+| `/gateway admin add <p\|*> <uid>` | Grant admin privileges |
+| `/gateway admin remove <p\|*> <uid>` | Revoke admin |
+| `/gateway admin list` | List admin users |
+| `/gateway admin add <p\|*> <uid>` | Grant admin privileges |
+| `/gateway admin remove <p\|*> <uid>` | Revoke admin |
+| `/gateway tool-policy list` | List explicit tool policies |
+| `/gateway tool-policy defaults` | Show default policy baseline |
+| `/gateway tool-policy set <p> <u> <t> allow\|deny` | Add/update a tool policy |
+| `/gateway tool-policy remove <id>` | Delete a policy |
+| `/gateway tool-policy reset` | Clear all, back to defaults |
+
+## HTTP API
+
+Available when the gateway is running:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/status` | GET | Gateway status (running, adapters, clients, sessions) |
+| `/api/sessions` | GET | Active sessions |
+| `/api/background` | GET | Background tasks |
+| `/api/allowlist` | GET | Allowlisted users |
+| `/api/pairing` | GET | Pending pairing codes |
+
+Authenticate with `Authorization: Bearer <token>` if tokens are configured.
+
+## WebSocket API
+
+Connect to `ws://localhost:3847`. Messages are JSON:
+
+```jsonc
+// Send a prompt
+{ "type": "prompt", "data": { "message": "Hello" } }
+
+// Start a background task
+{ "type": "background", "data": { "sessionId": "...", "command": "..." } }
+
+// Ping
+{ "type": "ping" }
+```
+
+Receive responses, background task updates, and agent events as server-pushed messages.
+
+## Registered Tools
+
+The extension registers these tools for use in pi sessions:
+
+- **`gateway_status`** — Check if gateway is running and which adapters are active
+- **`gateway_sessions`** — List active chat sessions
+- **`gateway_background_tasks`** — List and manage background tasks
+- **`gateway_pairing`** — Generate or approve pairing codes
+- **`gateway_tool_policy`** — Manage tool access policies for external users
+
+## Sessions
+
+Each chat gets an isolated session with configurable reset policies:
+
+- **daily** — Session resets at a specific hour each day (default: 4 AM)
+- **idle** — Session resets after N minutes of inactivity
+- **both** — Whichever triggers first
+
+Sessions persist across gateway restarts in `~/.pi/gateway-sessions.db`.
+
+## Background Tasks
+
+Long-running work is spawned in isolated background sessions. Results are delivered back to the parent chat when complete. Managed via `/gateway tasks`.
+
+## Architecture
+
+```
+┌─────────────┐     ┌─────────────────────────────┐
+│  pi agent   │◄───►│        pi-gateway           │
+│  (RPC)      │     │                             │
+└─────────────┘     │  ┌─────────────────────┐    │
+                    │  │ Platform Adapters    │    │
+┌─────────────┐     │  │ Discord · Telegram   │    │
+│ HTTP / WS   │────►│  │ Slack · Twitch       │    │
+│ Clients     │     │  │ WhatsApp · WebSocket │    │
+└─────────────┘     │  └─────────────────────┘    │
+                    │                             │
+                    │  ┌─────────────────────┐    │
+                    │  │ Sessions Store      │    │
+                    │  │ Background Manager  │    │
+                    │  │ Security Layer      │    │
+                    │  └─────────────────────┘    │
+                    └─────────────────────────────┘
+```
+
+- **Platform adapters** translate incoming platform messages into a unified format
+- **Sessions store** (`SQLite`) persists per-chat state with reset policies
+- **Background manager** spawns async child processes, delivers results via chat
+- **Security layer** checks allowlists, manages pairing codes, and enforces rate limits
+
+## License
+
+MIT

package/config/config.default.json

@@ -0,0 +1,51 @@
+{
+  "port": 3847,
+  "host": "localhost",
+  "tokens": [],
+  "corsOrigins": ["*"],
+  "enableWebSocket": true,
+  "enableHttp": true,
+  "security": {
+    "allowAll": true,
+    "requirePairing": false,
+    "allowedUids": {},
+    "adminUids": {},
+    "rateLimit": {
+      "maxRequests": 60,
+      "windowMs": 60000
+    }
+  },
+  "sessions": {
+    "resetPolicy": "idle",
+    "dailyHour": 4,
+    "idleMinutes": 1440
+  },
+  "platforms": {
+    "discord": {
+      "enabled": false,
+      "botToken": "",
+      "guildId": ""
+    },
+    "twitch": {
+      "enabled": false,
+      "clientId": "",
+      "clientSecret": "",
+      "channels": []
+    },
+    "telegram": {
+      "enabled": false,
+      "token": "",
+      "webhookUrl": ""
+    },
+    "slack": {
+      "enabled": false,
+      "webhookUrl": "",
+      "botToken": ""
+    },
+    "whatsapp": {
+      "enabled": false,
+      "sessionPath": "~/.pi/whatsapp-session",
+      "printQr": true
+    }
+  }
+}

package/dist/adapters/base.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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>;
+    /**
+     * 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 declare abstract class BaseAdapter implements PlatformAdapter {
+    abstract readonly platform: string;
+    abstract config: PlatformConfig;
+    protected callbacks: AdapterCallbacks | null;
+    protected running: boolean;
+    initialize(): Promise<void>;
+    start(callbacks: AdapterCallbacks): Promise<void>;
+    stop(): Promise<void>;
+    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>;
+    protected generateMessageId(): string;
+}

package/dist/adapters/base.js

@@ -0,0 +1,34 @@
+/**
+ * Platform Adapter Base - Interface for Hermes-style platform adapters
+ */
+/**
+ * Abstract base class for adapters
+ */
+export class BaseAdapter {
+    callbacks = null;
+    running = false;
+    async initialize() {
+        // Override in subclass
+    }
+    async start(callbacks) {
+        this.callbacks = callbacks;
+        this.running = true;
+    }
+    async stop() {
+        this.running = false;
+        this.callbacks = null;
+    }
+    emitMessage(message) {
+        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);
+            });
+        }
+        return Promise.resolve();
+    }
+    generateMessageId() {
+        return `${this.platform}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/adapters/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/adapters/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AA2EH;;GAEG;AACH,MAAM,OAAgB,WAAW;IAGtB,SAAS,GAA4B,IAAI,CAAC;IAC1C,OAAO,GAAG,KAAK,CAAC;IAE1B,KAAK,CAAC,UAAU;QACf,uBAAuB;IACxB,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,SAA2B;QACtC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,IAAI;QACT,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACvB,CAAC;IAYS,WAAW,CAAC,OAAwB;QAC7C,IAAI,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBACtD,uCAAuC;gBACvC,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,gCAAgC,EAAE,GAAG,CAAC,CAAC;YACvE,CAAC,CAAkB,CAAC;QACrB,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1B,CAAC;IAES,iBAAiB;QAC1B,OAAO,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACnF,CAAC;CACD"}

package/dist/adapters/discord.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Discord Adapter - Hermes-style Discord platform adapter
+ *
+ * Features:
+ * - DM and guild channel support
+ * - Slash command registration
+ * - Typing indicators
+ * - Message editing/deletion
+ * - Rate limit handling
+ */
+import { BaseAdapter, type PlatformConfig } from "./base.js";
+export interface DiscordConfig extends PlatformConfig {
+    platform: "discord";
+    botToken: string;
+    guildId?: string;
+    allowedChannels?: string[];
+    allowedRoles?: string[];
+    requireMention?: boolean;
+}
+export declare class DiscordAdapter extends BaseAdapter {
+    readonly platform: "discord";
+    config: DiscordConfig;
+    private httpClient;
+    private wsConnection;
+    private heartbeatInterval;
+    private sequence;
+    private sessionId;
+    private intents;
+    constructor(config: DiscordConfig);
+    initialize(): Promise<void>;
+    private apiRequest;
+    start(callbacks: any): Promise<void>;
+    private handleGatewayMessage;
+    private startHeartbeat;
+    private identify;
+    private handleDispatch;
+    private handleMessage;
+    private getBotId;
+    sendMessage(channelId: string, content: string): Promise<string>;
+    editMessage(channelId: string, messageId: string, content: string): Promise<void>;
+    deleteMessage(channelId: string, messageId: string): Promise<void>;
+    setTyping(channelId: string, isTyping: boolean): Promise<void>;
+    getStatus(): Promise<{
+        connected: boolean;
+        latency?: number;
+    }>;
+    stop(): Promise<void>;
+    registerSlashCommands(commands: Array<{
+        name: string;
+        description: string;
+        options?: any[];
+    }>): Promise<void>;
+}