@0xmaxma/claude-gateway 1.0.0

package/mcp/tools/agent/module.ts

@@ -0,0 +1,163 @@
+import type { ToolModule, McpToolDefinition, McpToolResult, ToolVisibility } from '../../types';
+import { createAgent, updateAgent } from './handlers';
+import type { CreateAgentArgs, UpdateAgentArgs } from './handlers';
+
+export class AgentModule implements ToolModule {
+  id = 'agent';
+  toolVisibility: ToolVisibility = 'all-configured';
+
+  isEnabled(): boolean {
+    return true;
+  }
+
+  getTools(): McpToolDefinition[] {
+    return [
+      {
+        name: 'agent_create',
+        description:
+          'Create a new Claude Gateway agent with a workspace and channel configuration. The gateway hot-adds the agent without requiring a restart.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: {
+              type: 'string',
+              description:
+                'Agent ID: starts with a letter, 2-32 chars, letters/numbers/underscores/hyphens. Stored lowercase.',
+            },
+            description: {
+              type: 'string',
+              description:
+                "One-paragraph description of the agent's role, personality, and capabilities.",
+            },
+            channel: {
+              type: 'string',
+              enum: ['telegram', 'discord'],
+              description: 'Primary channel for this agent.',
+            },
+            bot_token: {
+              type: 'string',
+              description:
+                'Bot token. Telegram: 123456789:AAHfiq... Discord: MTAxMTk....AAAA.xxx.',
+            },
+            telegram_user_id: {
+              type: 'string',
+              description:
+                'Telegram numeric chat_id (6–15 digits, e.g. "99000000"). ONLY pass here when channel=telegram. IMPORTANT: If you are responding to a Telegram message, use the sender chat_id from the inbound message context directly — do NOT ask the user for it. NEVER put a Discord Snowflake (17–19 digits) here.',
+            },
+            discord_user_id: {
+              type: 'string',
+              description:
+                'Discord Snowflake user ID (17–19 digits, e.g. "932651528878194749"). ONLY pass here when channel=discord. IMPORTANT: If you are responding to a Discord message, use the sender user ID from the inbound message context directly — do NOT ask the user for it. NEVER put a Telegram chat_id (6–15 digits) here.',
+            },
+            dm_policy: {
+              type: 'string',
+              enum: ['open', 'allowlist', 'pairing'],
+              description: 'DM access policy. Default: allowlist.',
+            },
+            model: {
+              type: 'string',
+              description: 'Claude model to use. Default: claude-sonnet-4-6.',
+            },
+            signature_emoji: {
+              type: 'string',
+              description: 'Optional emoji the agent uses as a signature.',
+            },
+            agents_md: {
+              type: 'string',
+              description:
+                'Full AGENTS.md content (AI-generated by caller). If omitted, a stub is created from description.',
+            },
+            soul_md: {
+              type: 'string',
+              description: 'Full SOUL.md content. If omitted, an empty stub is created.',
+            },
+            user_md: {
+              type: 'string',
+              description: 'Full USER.md content. If omitted, an empty stub is created.',
+            },
+          },
+          required: ['id', 'description', 'channel', 'bot_token'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'agent_update',
+        description:
+          'Update an existing agent: add a new channel, remove a channel, or update a workspace file.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: {
+              type: 'string',
+              description: 'Agent ID to update.',
+            },
+            action: {
+              type: 'string',
+              enum: ['add_channel', 'remove_channel', 'update_workspace_file'],
+              description: 'Operation to perform.',
+            },
+            channel: {
+              type: 'string',
+              enum: ['telegram', 'discord'],
+              description: 'Channel (required for add_channel and remove_channel).',
+            },
+            bot_token: {
+              type: 'string',
+              description: 'Bot token (required for add_channel).',
+            },
+            telegram_user_id: {
+              type: 'string',
+              description:
+                'Telegram numeric chat_id (6–15 digits). add_channel only, when channel=telegram. IMPORTANT: If responding to a Telegram message, use the sender chat_id directly — do NOT ask the user for it. NEVER put a Discord Snowflake (17–19 digits) here.',
+            },
+            discord_user_id: {
+              type: 'string',
+              description:
+                'Discord Snowflake user ID (17–19 digits). add_channel only, when channel=discord. IMPORTANT: If responding to a Discord message, use the sender user ID directly — do NOT ask the user for it. NEVER put a Telegram chat_id (6–15 digits) here.',
+            },
+            dm_policy: {
+              type: 'string',
+              enum: ['open', 'allowlist', 'pairing'],
+              description: 'DM policy for the new channel (add_channel only). Default: allowlist.',
+            },
+            filename: {
+              type: 'string',
+              description:
+                'Workspace file to write (update_workspace_file only). E.g. "SOUL.md". No path traversal allowed.',
+            },
+            content: {
+              type: 'string',
+              description: 'New file content (update_workspace_file only).',
+            },
+          },
+          required: ['id', 'action'],
+          additionalProperties: false,
+        },
+      },
+    ];
+  }
+
+  async handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+    try {
+      let result: string;
+
+      if (name === 'agent_create') {
+        result = await createAgent(args as unknown as CreateAgentArgs);
+      } else if (name === 'agent_update') {
+        result = await updateAgent(args as unknown as UpdateAgentArgs);
+      } else {
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+      }
+
+      return { content: [{ type: 'text', text: result }] };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: (err as Error).message }],
+        isError: true,
+      };
+    }
+  }
+}

package/mcp/tools/browser/module.ts

@@ -0,0 +1,321 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { ToolModule, McpToolDefinition, McpToolResult, ToolVisibility } from '../../types';
+
+let _reqId = 1;
+
+export class BrowserModule implements ToolModule {
+  id = 'browser';
+  toolVisibility: ToolVisibility = 'all-configured';
+
+  isEnabled(): boolean {
+    return process.env.GETPOD_BROWSER_DISABLED !== 'true';
+  }
+
+  getTools(): McpToolDefinition[] {
+    return browserToolDefs;
+  }
+
+  async handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+    const sessionId = process.env.GATEWAY_SESSION_ID;
+    const agentId = process.env.GATEWAY_AGENT_ID;
+    if (sessionId) args = { ...args, session_id: sessionId };
+    if (agentId) args = { ...args, agent_id: agentId };
+
+    const result = await callGetpodBrowser(name, args);
+
+    if (name === 'browser_screenshot' && !result.isError) {
+      // getpod-browser returns {type:"image", data: base64, mimeType:"image/jpeg"}.
+      // Decode and save to /tmp so callers can attach the file path directly.
+      const block = result.content[0] as Record<string, string> | undefined;
+      const b64 = block?.['data'] ?? '';
+      const mime = block?.['mimeType'] ?? 'image/jpeg';
+      if (b64) {
+        const ext = mime.includes('png') ? 'png' : 'jpg';
+        const sid = (args.session_id as string | undefined) ?? 'default';
+        const filePath = path.join('/tmp', `browser_shot_${sid}.${ext}`);
+        fs.writeFileSync(filePath, Buffer.from(b64, 'base64'));
+        return { content: [{ type: 'text', text: filePath }] };
+      }
+    }
+
+    return result;
+  }
+}
+
+async function readFirstDataLine(res: Response): Promise<string | undefined> {
+  if (!res.body) return undefined;
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = '';
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      // Scan all complete \n-terminated lines; return the first data: line found
+      let newlineIdx: number;
+      while ((newlineIdx = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, newlineIdx);
+        buf = buf.slice(newlineIdx + 1);
+        if (line.startsWith('data: ')) return line;
+      }
+    }
+  } finally {
+    reader.cancel();
+  }
+  return buf.startsWith('data: ') ? buf : undefined;
+}
+
+async function callGetpodBrowser(
+  toolName: string,
+  args: Record<string, unknown>,
+): Promise<McpToolResult> {
+  const id = _reqId++;
+  const body = JSON.stringify({
+    jsonrpc: '2.0',
+    id,
+    method: 'tools/call',
+    params: { name: toolName, arguments: args },
+  });
+
+  const baseUrl = process.env.GETPOD_BROWSER_URL ?? 'http://127.0.0.1:10880';
+  const apiKey = process.env.GETPOD_BROWSER_API_KEY ?? '';
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (apiKey) {
+    headers['Authorization'] = `Bearer ${apiKey}`;
+  }
+  let res: Response;
+  try {
+    res = await fetch(`${baseUrl}/mcp`, {
+      method: 'POST',
+      headers,
+      body,
+    });
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `getpod-browser unavailable: ${(err as Error).message}` }],
+      isError: true,
+    };
+  }
+
+  const dataLine = await readFirstDataLine(res);
+  if (!dataLine) {
+    return {
+      content: [{ type: 'text', text: 'empty response from getpod-browser' }],
+      isError: true,
+    };
+  }
+
+  let rpc: {
+    result?: { content: Array<Record<string, string>>; isError?: boolean };
+    error?: { message: string };
+  };
+  try {
+    rpc = JSON.parse(dataLine.slice('data: '.length));
+  } catch {
+    return {
+      content: [{ type: 'text', text: 'invalid JSON from getpod-browser' }],
+      isError: true,
+    };
+  }
+
+  if (rpc.error) {
+    return { content: [{ type: 'text', text: rpc.error.message }], isError: true };
+  }
+  if (!rpc.result) {
+    return { content: [{ type: 'text', text: 'no result in response' }], isError: true };
+  }
+
+  return {
+    content: rpc.result.content as Array<{ type: 'text'; text: string }>,
+    isError: rpc.result.isError,
+  };
+}
+
+const browserToolDefs: McpToolDefinition[] = [
+  {
+    name: 'browser_create_session',
+    description:
+      'Create or resume a browser session. Returns stream_url and status. ' +
+      'IMPORTANT: After creating a session, always share the stream_url with the user so they can open the browser in their client.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Unique session identifier' },
+        idle_timeout_seconds: {
+          type: 'integer',
+          description: 'Idle timeout in seconds (0 = no timeout)',
+        },
+      },
+    },
+  },
+  {
+    name: 'browser_close_session',
+    description: 'Close a browser session, killing the process and removing session data.',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' } },
+    },
+  },
+  {
+    name: 'browser_get_stream_url',
+    description: 'Get the WebSocket stream URL for an active session (for frontend live view).',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' } },
+    },
+  },
+  {
+    name: 'browser_navigate',
+    description: 'Navigate to a URL. If tab_id is provided, navigates that specific tab; otherwise navigates the active tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string' },
+        url: { type: 'string' },
+        tab_id: {
+          type: 'string',
+          description: 'Tab ID to navigate (optional, from browser_tabs); omit to use the active tab',
+        },
+        wait: {
+          type: 'string',
+          description: 'Wait condition: load, domcontentloaded, networkidle',
+        },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'browser_snapshot',
+    description: 'Return the accessibility tree of the current page.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string' },
+        interactive_only: { type: 'boolean' },
+      },
+    },
+  },
+  {
+    name: 'browser_click',
+    description: 'Click an element by accessibility ref or CSS selector.',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' }, ref: { type: 'string' } },
+      required: ['ref'],
+    },
+  },
+  {
+    name: 'browser_fill',
+    description: 'Fill an input element with a value.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string' },
+        ref: { type: 'string' },
+        value: { type: 'string' },
+      },
+      required: ['ref', 'value'],
+    },
+  },
+  {
+    name: 'browser_type',
+    description: 'Type text into the currently focused element.',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' }, text: { type: 'string' } },
+      required: ['text'],
+    },
+  },
+  {
+    name: 'browser_evaluate',
+    description: 'Evaluate JavaScript in the browser and return the result.',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' }, script: { type: 'string' } },
+      required: ['script'],
+    },
+  },
+  {
+    name: 'browser_scroll',
+    description: 'Scroll the page at (x, y) by (deltaX, deltaY).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string' },
+        x: { type: 'integer' },
+        y: { type: 'integer' },
+        deltaX: { type: 'integer' },
+        deltaY: { type: 'integer' },
+      },
+      required: ['x', 'y', 'deltaX', 'deltaY'],
+    },
+  },
+  {
+    name: 'browser_wait',
+    description: 'Wait for a condition: element selector, networkidle, or URL pattern.',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' }, condition: { type: 'string' } },
+      required: ['condition'],
+    },
+  },
+  {
+    name: 'browser_get_text',
+    description: 'Get text content of an element matching the selector.',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' }, selector: { type: 'string' } },
+      required: ['selector'],
+    },
+  },
+  {
+    name: 'browser_new_tab',
+    description: 'Open a new browser tab, optionally navigating to a URL. Returns tab_id.',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' }, url: { type: 'string' } },
+    },
+  },
+  {
+    name: 'browser_close_tab',
+    description: 'Close a browser tab by tab_id.',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' }, tab_id: { type: 'string' } },
+      required: ['tab_id'],
+    },
+  },
+  {
+    name: 'browser_tabs',
+    description: 'List all open browser tabs.',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' } },
+    },
+  },
+  {
+    name: 'browser_screenshot',
+    description:
+      'Capture the current viewport as JPEG. Returns the absolute file path of the saved image (ready to attach to Telegram).',
+    inputSchema: {
+      type: 'object',
+      properties: { session_id: { type: 'string' } },
+    },
+  },
+  {
+    name: 'browser_navigate_tab',
+    description: 'Navigate a specific tab (by tab_id) to a URL.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string' },
+        tab_id: { type: 'string', description: 'Tab ID returned by browser_tabs or browser_new_tab' },
+        url: { type: 'string' },
+        wait: { type: 'string', description: 'Wait condition: load, domcontentloaded, networkidle' },
+      },
+      required: ['tab_id', 'url'],
+    },
+  },
+];

package/mcp/tools/browser/skills/open-browser/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: open-browser
+description: "Open a URL in the agent's persistent browser session via MCP browser tools"
+user-invocable: true
+---
+
+# open-browser
+
+When user says "เปิด X", "navigate to X", "open X in browser", "switch to tab X", etc.
+
+## Rules
+
+- Use ONLY `mcp__gateway__browser_*` tools — never Python, never CDP direct, never filesystem
+- NEVER use `wait: "networkidle"` — it hangs on SPAs. Omit `wait` entirely (fire-and-forget)
+- Always check tab state before navigating — tab IDs change between sessions
+- Do NOT pass `session_id` — it is injected automatically from agent context
+
+## Fast Open Flow
+
+### Step 1 — Create/resume session
+
+Call `mcp__gateway__browser_create_session` with NO arguments (session_id is auto-injected).
+
+Result contains `stream_url` — use it to build the browser URL for the user.
+
+### Step 2 — Send browser URL to user IMMEDIATELY (no waiting)
+
+Reply on Telegram right away with the stream_url so the user can open the browser.
+
+### Step 3 — Check current tabs
+
+Call `mcp__gateway__browser_tabs` — returns list of `{tab_id, url, title}`.
+
+Use this to:
+- Know which tab is active / which tab to navigate
+- Decide whether to open a new tab or reuse existing one
+
+### Step 4 — Navigate (fire-and-forget)
+
+**Option A — Navigate active tab** (no tab_id):
+```
+browser_navigate(url)
+```
+
+**Option B — Navigate specific tab**:
+```
+browser_navigate(url, tab_id="t1")
+```
+
+**Option C — Open in new tab**:
+```
+browser_new_tab()  → returns tab_id
+browser_navigate(url, tab_id=<new_tab_id>)
+```
+
+If `browser_navigate` or `browser_navigate_tab` returns error like `tab "t99" not found (available: [t1, t2])` → call `browser_tabs` again and pick correct tab_id.
+
+### Step 5 — Screenshot and confirm
+
+Call `mcp__gateway__browser_screenshot` — result is absolute file path.
+
+Send to Telegram with the screenshot attached.
+
+## Multi-tab Management
+
+- `browser_tabs` — list all tabs with tab_id, url, title
+- `browser_new_tab()` — open new blank tab, returns tab_id
+- `browser_navigate(url, tab_id)` — navigate specific tab (optional tab_id)
+- `browser_close_tab(tab_id)` — close tab
+
+## Available MCP tools (complete list)
+
+- `browser_create_session` — create/resume session, returns stream_url
+- `browser_close_session` — close session
+- `browser_get_stream_url` — get stream URL for active session
+- `browser_navigate` — navigate to URL; optional tab_id to target specific tab
+- `browser_navigate_tab` — navigate specific tab by tab_id (legacy, prefer browser_navigate with tab_id)
+- `browser_snapshot` — accessibility tree of current page
+- `browser_click` — click element by ref or CSS selector
+- `browser_fill` — fill input element
+- `browser_type` — type text into focused element
+- `browser_evaluate` — run JavaScript in browser
+- `browser_scroll` — scroll page
+- `browser_wait` — wait for element/networkidle/URL
+- `browser_get_text` — get text content of element
+- `browser_new_tab` — open new tab, returns tab_id
+- `browser_close_tab` — close tab by tab_id
+- `browser_tabs` — list all open tabs with tab_id + url + title
+- `browser_screenshot` — capture viewport as JPEG, returns absolute file path

package/mcp/tools/cron/client.ts

@@ -0,0 +1,65 @@
+/**
+ * HTTP client for gateway cron REST API.
+ */
+
+export class CronClient {
+  private readonly baseUrl: string;
+  private readonly agentId: string;
+  private readonly apiKey: string;
+
+  constructor(apiUrl: string, agentId: string, apiKey?: string) {
+    this.baseUrl = apiUrl.replace(/\/$/, '');
+    this.agentId = agentId;
+    this.apiKey = apiKey ?? '';
+  }
+
+  private url(path: string, query?: Record<string, string>): string {
+    const base = `${this.baseUrl}/api/v1/crons${path}`;
+    if (!query) return base;
+    const qs = new URLSearchParams(query).toString();
+    return `${base}?${qs}`;
+  }
+
+  private async request(method: string, path: string, body?: unknown, query?: Record<string, string>): Promise<unknown> {
+    const headers: Record<string, string> = {};
+    if (body) headers['Content-Type'] = 'application/json';
+    if (this.apiKey) headers['X-Api-Key'] = this.apiKey;
+
+    const res = await fetch(this.url(path, query), {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`API ${method} ${path} failed: HTTP ${res.status} ${text}`);
+    }
+
+    const contentType = res.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+      return res.json();
+    }
+    return res.text();
+  }
+
+  async list(): Promise<unknown> {
+    return this.request('GET', '', undefined, { agent: this.agentId });
+  }
+
+  async create(params: Record<string, unknown>): Promise<unknown> {
+    return this.request('POST', '', { ...params, agentId: this.agentId });
+  }
+
+  async delete(jobId: string): Promise<void> {
+    await this.request('DELETE', `/${jobId}`);
+  }
+
+  async run(jobId: string): Promise<unknown> {
+    return this.request('POST', `/${jobId}/run`);
+  }
+
+  async getRuns(jobId: string): Promise<unknown> {
+    return this.request('GET', `/${jobId}/runs`);
+  }
+}