@0xmaxma/claude-gateway 1.1.10 → 1.2.1

package/lib/pairing.ts

@@ -0,0 +1,326 @@
+/**
+ * Shared pairing primitives for both scripts/create-agent.ts and mcp/tools/agent/handlers.ts.
+ * Uses fetch (available in Node 18+ and Bun) — no https module dependency.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomBytes } from 'crypto';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TelegramFirstDM {
+  senderId: string;
+  chatId: string;
+  /** getUpdates offset to use for the next poll call */
+  nextOffset: number;
+}
+
+export interface DiscordFirstDM {
+  senderId: string;
+  channelId: string;
+}
+
+interface TgUpdate {
+  update_id: number;
+  message?: {
+    from: { id: number };
+    chat: { id: number; type: string };
+    text?: string;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Telegram helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Long-poll Telegram getUpdates until the first private DM arrives.
+ * Returns sender/chat IDs plus the next polling offset.
+ */
+export async function pollForFirstTelegramDM(
+  token: string,
+  timeoutMs = 10 * 60 * 1000,
+): Promise<TelegramFirstDM> {
+  const deadline = Date.now() + timeoutMs;
+  let offset = 0;
+
+  while (Date.now() < deadline) {
+    const remaining = Math.max(0, deadline - Date.now());
+    const pollSecs = Math.min(30, Math.ceil(remaining / 1000));
+    if (pollSecs === 0) break;
+
+    try {
+      const url = `https://api.telegram.org/bot${token}/getUpdates?offset=${offset}&timeout=${pollSecs}&allowed_updates=%5B%22message%22%5D`;
+      const res = await fetch(url);
+      const data = (await res.json()) as { ok: boolean; result: TgUpdate[] };
+
+      if (data.ok && data.result.length > 0) {
+        for (const update of data.result) {
+          offset = update.update_id + 1;
+          if (update.message?.chat.type === 'private') {
+            return {
+              senderId: String(update.message.from.id),
+              chatId: String(update.message.chat.id),
+              nextOffset: offset,
+            };
+          }
+        }
+      }
+    } catch {
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+  }
+
+  throw new Error('Timed out waiting for first Telegram DM');
+}
+
+/**
+ * Poll getUpdates until the user in chatId replies with the expected code.
+ * Returns true if confirmed, false on timeout.
+ */
+export async function pollForTelegramCode(
+  token: string,
+  chatId: string,
+  expectedCode: string,
+  offset: number,
+  timeoutMs = 3 * 60 * 1000,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  let currentOffset = offset;
+
+  while (Date.now() < deadline) {
+    const remaining = Math.max(0, deadline - Date.now());
+    const pollSecs = Math.min(30, Math.ceil(remaining / 1000));
+    if (pollSecs === 0) break;
+
+    try {
+      const url = `https://api.telegram.org/bot${token}/getUpdates?offset=${currentOffset}&timeout=${pollSecs}&allowed_updates=%5B%22message%22%5D`;
+      const res = await fetch(url);
+      const data = (await res.json()) as { ok: boolean; result: TgUpdate[] };
+
+      if (data.ok && data.result.length > 0) {
+        for (const update of data.result) {
+          currentOffset = update.update_id + 1;
+          if (
+            update.message?.chat.type === 'private' &&
+            String(update.message.chat.id) === chatId &&
+            update.message.text?.trim().toLowerCase() === expectedCode
+          ) {
+            return true;
+          }
+        }
+      }
+    } catch {
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+  }
+
+  return false;
+}
+
+/** Send a message to a Telegram chat. Errors are swallowed (non-fatal). */
+export async function sendTelegramMessage(
+  token: string,
+  chatId: string,
+  text: string,
+): Promise<void> {
+  try {
+    await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ chat_id: chatId, text }),
+    });
+  } catch {
+    // Not fatal
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Discord helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Connect to the Discord gateway via WebSocket and wait for the first DM.
+ * Returns sender and channel IDs.
+ */
+export async function pollForFirstDiscordDM(
+  token: string,
+  timeoutMs = 10 * 60 * 1000,
+): Promise<DiscordFirstDM> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const WS = (globalThis as any).WebSocket as typeof WebSocket;
+  return new Promise((resolve, reject) => {
+    let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+    let resolved = false;
+
+    const ws = new WS('wss://gateway.discord.gg/?v=10&encoding=json');
+
+    const deadline = setTimeout(() => {
+      ws.close();
+      reject(new Error('Pairing timeout — no Discord DM received within the allowed time'));
+    }, timeoutMs);
+
+    ws.onmessage = (event: MessageEvent) => {
+      const payload = JSON.parse(event.data as string) as {
+        op: number;
+        d: Record<string, unknown>;
+        t?: string;
+      };
+      const { op, d, t } = payload;
+
+      if (op === 10) {
+        const interval = (d.heartbeat_interval as number) ?? 41250;
+        heartbeatTimer = setInterval(() => ws.send(JSON.stringify({ op: 1, d: null })), interval);
+        ws.send(
+          JSON.stringify({
+            op: 2,
+            d: {
+              token,
+              intents: 4096 + 32768, // DIRECT_MESSAGES + MESSAGE_CONTENT
+              properties: { os: 'linux', browser: 'claude-gateway', device: 'claude-gateway' },
+            },
+          }),
+        );
+      } else if (op === 0 && t === 'MESSAGE_CREATE') {
+        const msg = d as Record<string, unknown>;
+        const author = msg['author'] as Record<string, unknown> | undefined;
+        if (!msg['guild_id'] && !author?.['bot']) {
+          if (!resolved) {
+            resolved = true;
+            clearTimeout(deadline);
+            if (heartbeatTimer) clearInterval(heartbeatTimer);
+            ws.close();
+            resolve({
+              senderId: String(author?.['id'] ?? ''),
+              channelId: String(msg['channel_id']),
+            });
+          }
+        }
+      }
+    };
+
+    ws.onerror = () => {
+      clearTimeout(deadline);
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
+      reject(new Error('Discord WebSocket error during pairing'));
+    };
+  });
+}
+
+/** Send a message to a Discord channel. Errors are swallowed (non-fatal). */
+export async function sendDiscordMessage(
+  token: string,
+  channelId: string,
+  text: string,
+): Promise<void> {
+  try {
+    await fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bot ${token}`,
+      },
+      body: JSON.stringify({ content: text }),
+    });
+  } catch {
+    // Not fatal
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Access.json writers
+// ---------------------------------------------------------------------------
+
+export function writeTelegramAccess(stateDir: string, senderId: string): void {
+  fs.writeFileSync(
+    path.join(stateDir, 'access.json'),
+    JSON.stringify(
+      { dmPolicy: 'allowlist', allowFrom: [senderId], groups: {}, pending: {} },
+      null,
+      2,
+    ),
+    { mode: 0o600 },
+  );
+}
+
+export function writeDiscordAccess(stateDir: string, senderId: string): void {
+  fs.writeFileSync(
+    path.join(stateDir, 'access.json'),
+    JSON.stringify(
+      {
+        dmPolicy: 'allowlist',
+        allowFrom: [senderId],
+        guildAllowlist: [],
+        channelAllowlist: [],
+        roleAllowlist: [],
+        pending: {},
+      },
+      null,
+      2,
+    ) + '\n',
+    { mode: 0o600 },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// High-level non-interactive pairing (for MCP — no terminal readline)
+// ---------------------------------------------------------------------------
+
+/**
+ * Full non-interactive Telegram pairing:
+ * 1. Wait for first DM → 2. Send code → 3. Wait for user to reply with code → 4. Write access.json
+ */
+export async function pairTelegramUser(
+  token: string,
+  stateDir: string,
+  timeoutMs = 8 * 60 * 1000,
+): Promise<{ chatId: string }> {
+  const { senderId, chatId, nextOffset } = await pollForFirstTelegramDM(token, timeoutMs);
+
+  const code = randomBytes(3).toString('hex');
+  await sendTelegramMessage(
+    token,
+    chatId,
+    `Pairing code: ${code}\n\nReply with this code to complete pairing.`,
+  );
+
+  const confirmed = await pollForTelegramCode(token, chatId, code, nextOffset, 3 * 60 * 1000);
+  if (!confirmed) {
+    throw new Error('Pairing timed out — user did not reply with the pairing code within 3 minutes');
+  }
+
+  writeTelegramAccess(stateDir, senderId);
+  await sendTelegramMessage(token, chatId, "You're connected! Send me a message to get started.");
+
+  return { chatId };
+}
+
+/**
+ * Full non-interactive Discord pairing:
+ * 1. Wait for first DM → 2. Send code → 3. Auto-approve (no HTTP polling for Discord code reply) → 4. Write access.json
+ *
+ * Discord does not support HTTP-based message polling, so code confirmation is skipped;
+ * the first DM sender is trusted as the owner.
+ */
+export async function pairDiscordUser(
+  token: string,
+  stateDir: string,
+  timeoutMs = 8 * 60 * 1000,
+): Promise<{ channelId: string }> {
+  const { senderId, channelId } = await pollForFirstDiscordDM(token, timeoutMs);
+
+  const code = randomBytes(3).toString('hex');
+  await sendDiscordMessage(
+    token,
+    channelId,
+    `Pairing code: ${code}\n\nYou have been automatically paired as the bot owner.`,
+  );
+
+  writeDiscordAccess(stateDir, senderId);
+  await sendDiscordMessage(token, channelId, "You're connected! Send me a message to get started.");
+
+  return { channelId };
+}

package/mcp/server.ts

@@ -18,6 +18,7 @@ import { CronModule } from './tools/cron/module';
 import { SkillsModule } from './tools/skills/module';
 import { AgentModule } from './tools/agent/module';
 import { BrowserModule } from './tools/browser/module';
+import { AppsModule } from './tools/apps/module';
 import type { ChannelModule, ToolModule, McpToolDefinition } from './types';
 
 const ORIGIN_CHANNEL = process.env.GATEWAY_ORIGIN_CHANNEL ?? '';
@@ -35,6 +36,7 @@ const modules: AnyModule[] = [
   new SkillsModule(),
   new AgentModule(),
   new BrowserModule(),
+  new AppsModule(),
 ];
 
 // Build tool-to-module mapping for enabled modules

package/mcp/tools/apps/client.ts

@@ -0,0 +1,78 @@
+/**
+ * HTTP client for the gateway apps REST API.
+ */
+
+export class AppsClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+
+  constructor(apiUrl: string, apiKey?: string) {
+    this.baseUrl = apiUrl.replace(/\/$/, '');
+    this.apiKey = apiKey ?? '';
+  }
+
+  private url(p: string): string {
+    return `${this.baseUrl}/api/v1/apps${p}`;
+  }
+
+  private async request(method: string, p: string, body?: unknown): Promise<unknown> {
+    const headers: Record<string, string> = {};
+    if (body) headers['Content-Type'] = 'application/json';
+    if (this.apiKey) headers['Authorization'] = `Bearer ${this.apiKey}`;
+
+    const res = await fetch(this.url(p), {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`Apps API ${method} ${p} failed: HTTP ${res.status} ${text}`);
+    }
+
+    const ct = res.headers.get('content-type') ?? '';
+    if (ct.includes('application/json')) return res.json();
+    return res.text();
+  }
+
+  async listRegistry(): Promise<unknown> {
+    return this.request('GET', '/registry');
+  }
+
+  async getRegistry(name: string): Promise<unknown> {
+    return this.request('GET', `/registry/${encodeURIComponent(name)}`);
+  }
+
+  async listApps(): Promise<unknown> {
+    return this.request('GET', '');
+  }
+
+  async getApp(name: string): Promise<unknown> {
+    return this.request('GET', `/${encodeURIComponent(name)}`);
+  }
+
+  async getVersion(name: string): Promise<unknown> {
+    return this.request('GET', `/${encodeURIComponent(name)}/version`);
+  }
+
+  async install(params: Record<string, unknown>): Promise<unknown> {
+    return this.request('POST', '/install', params);
+  }
+
+  async pollJob(jobId: string): Promise<unknown> {
+    return this.request('GET', `/jobs/${encodeURIComponent(jobId)}`);
+  }
+
+  async uninstall(name: string): Promise<unknown> {
+    return this.request('DELETE', `/${encodeURIComponent(name)}`);
+  }
+
+  async update(name: string): Promise<unknown> {
+    return this.request('POST', `/${encodeURIComponent(name)}/update`);
+  }
+
+  async startStop(name: string, action: 'start' | 'stop' | 'restart'): Promise<unknown> {
+    return this.request('POST', `/${encodeURIComponent(name)}/${action}`);
+  }
+}

package/mcp/tools/apps/module.ts

@@ -0,0 +1,211 @@
+/**
+ * Apps tool module — install, list, and manage app store apps via gateway REST API.
+ */
+
+import * as path from 'path';
+import type {
+  ToolModule,
+  McpToolDefinition,
+  McpToolResult,
+  ToolVisibility,
+} from '../../types';
+import { AppsClient } from './client';
+
+export class AppsModule implements ToolModule {
+  id = 'apps';
+  toolVisibility: ToolVisibility = 'all-configured';
+  skillsDir = path.join(__dirname, 'skills');
+
+  private client: AppsClient | null = null;
+
+  isEnabled(): boolean {
+    return Boolean(process.env.GATEWAY_API_URL);
+  }
+
+  private getClient(): AppsClient {
+    if (!this.client) {
+      const apiUrl = process.env.GATEWAY_API_URL!;
+      const apiKey = process.env.GATEWAY_API_KEY;
+      this.client = new AppsClient(apiUrl, apiKey);
+    }
+    return this.client;
+  }
+
+  getTools(): McpToolDefinition[] {
+    return [
+      {
+        name: 'browse_registry',
+        description: 'Browse the community app registry. Omit name to list all apps; provide name to get versions for a specific app.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'App name to look up. Omit to list all.' },
+          },
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'install_app',
+        description: 'Install an app from the registry or a GitHub URL. Returns a jobId to poll with poll_install_job.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            registry_app: { type: 'string', description: 'Registry app name (e.g. "getpod-manager")' },
+            version: { type: 'string', description: 'Registry version to install (default: latest)' },
+            github_url: { type: 'string', description: 'GitHub repo URL (requires commit)' },
+            commit: { type: 'string', description: '40-char hex commit hash (required with github_url)' },
+            local_path: { type: 'string', description: 'Local app path within ~/.claude-gateway/apps/' },
+            env_vars: {
+              type: 'object',
+              description: 'Environment variables / secrets to inject',
+              additionalProperties: { type: 'string' },
+            },
+          },
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'poll_install_job',
+        description: 'Poll the status of an app install job. Returns status (pending/running/completed/failed), logs, and result on completion.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            job_id: { type: 'string', description: 'Job ID returned by install_app' },
+          },
+          required: ['job_id'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'list_apps',
+        description: 'List all installed apps with their status and proxy URLs.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'app_status',
+        description: 'Get detailed status and version info for an installed app.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'App name' },
+          },
+          required: ['name'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'update_app',
+        description: 'Update a registry-installed app to its latest version. Returns a jobId.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'App name to update' },
+          },
+          required: ['name'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'uninstall_app',
+        description: 'Uninstall an app — stops containers, removes images, deletes files.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'App name to uninstall' },
+          },
+          required: ['name'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'start_stop_app',
+        description: 'Start, stop, or restart an installed app.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'App name' },
+            action: { type: 'string', enum: ['start', 'stop', 'restart'], description: 'Action to perform' },
+          },
+          required: ['name', 'action'],
+          additionalProperties: false,
+        },
+      },
+    ];
+  }
+
+  async handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+    const client = this.getClient();
+
+    switch (name) {
+      case 'browse_registry': {
+        const appName = args['name'] as string | undefined;
+        const data = appName
+          ? await client.getRegistry(appName)
+          : await client.listRegistry();
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
+      case 'install_app': {
+        const params: Record<string, unknown> = {};
+        if (args['registry_app']) params['registry_app'] = args['registry_app'];
+        if (args['version']) params['version'] = args['version'];
+        if (args['github_url']) params['github_url'] = args['github_url'];
+        if (args['commit']) params['commit'] = args['commit'];
+        if (args['local_path']) params['local_path'] = args['local_path'];
+        if (args['env_vars']) params['env_vars'] = args['env_vars'];
+        const data = await client.install(params);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
+      case 'poll_install_job': {
+        const jobId = args['job_id'] as string;
+        const data = await client.pollJob(jobId);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
+      case 'list_apps': {
+        const data = await client.listApps();
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
+      case 'app_status': {
+        const appName = args['name'] as string;
+        const [entry, version] = await Promise.all([
+          client.getApp(appName),
+          client.getVersion(appName).catch(() => null),
+        ]);
+        const result = { ...(entry as object), version_info: version };
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+      }
+
+      case 'update_app': {
+        const appName = args['name'] as string;
+        const data = await client.update(appName);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
+      case 'uninstall_app': {
+        const appName = args['name'] as string;
+        const data = await client.uninstall(appName);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
+      case 'start_stop_app': {
+        const appName = args['name'] as string;
+        const action = args['action'] as 'start' | 'stop' | 'restart';
+        const data = await client.startStop(appName, action);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+      }
+
+      default:
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  }
+}

package/mcp/tools/apps/skills/app-status/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: app-status
+description: Show detailed status, version info, and update availability for an installed app.
+user-invocable: true
+allowed-tools:
+  - mcp__gateway__app_status
+---
+
+# /app-status — App Status
+
+Arguments passed: `$ARGUMENTS`
+
+---
+
+## Usage
+
+`/app-status <app-name>`
+
+---
+
+## Steps
+
+1. Call `app_status` with the app name.
+
+2. Format and present:
+
+```
+App: <name>
+Status: running ✓  (or stopped / error / building)
+Version: 1.2.0
+Commit: abc123de
+Source: registry  (or custom / local)
+Installed: 2026-05-01T10:00:00Z
+
+Proxy routes:
+  api → /app/<name>/api/
+  web → /app/<name>/web/
+
+Version info:
+  Installed: 1.2.0
+  Latest:    1.3.0  ← update available
+  Behind: yes
+```
+
+3. If an update is available and source is `registry`, offer:
+   > Run `/install-app <name>` after uninstalling, or use the update API.
+
+If the app is not found (404), say so clearly.