@0xmaxma/claude-gateway 1.1.9 → 1.2.0

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.

package/mcp/tools/apps/skills/create-app-yaml/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: create-app-yaml
+description: Scan Dockerfile(s) in the current directory and generate a draft app.yaml for the gateway app store.
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Bash(ls *)
+  - Bash(find * -name Dockerfile*)
+---
+
+# /create-app-yaml — Generate Draft app.yaml
+
+Arguments passed: `$ARGUMENTS`
+
+Reads Dockerfile(s) in the current working directory and generates a draft `app.yaml`.
+
+---
+
+## Step 1 — Discover Dockerfiles
+
+```bash
+find . -name "Dockerfile*" -not -path "*/node_modules/*" -not -path "*/.git/*"
+```
+
+List what you found. If none, tell the user and stop.
+
+---
+
+## Step 2 — Infer services
+
+For each Dockerfile, infer:
+- **Service name** from the directory name or `Dockerfile.<name>` suffix
+- **Exposed ports** from `EXPOSE` instructions — pick the first as the main port
+- **Environment variables** from `ENV` instructions — these become `env:` entries
+- Whether it looks like a web app (serves HTML/static files) vs an API
+
+---
+
+## Step 3 — Generate app.yaml
+
+Write a draft `app.yaml` to the current directory:
+
+```yaml
+apiVersion: apps.getpod.ai/v1
+name: <inferred-from-dirname>      # lowercase, hyphens only
+version: 1.0.0
+commit: ""                          # fill in the 40-char commit hash before release
+
+services:
+  <service-name>:
+    build: .                        # or ./subdir if not root
+    ports:
+      - name: <api|web>
+        container: <port>
+        type: <api|web>             # api = REST/backend, web = serves HTML
+        rate_limit: 60              # requests per second
+    environment:
+      # Secrets (no default value) — users will be prompted at install time
+      - MY_SECRET_KEY
+      # Variables with defaults
+      - LOG_LEVEL=info
+    healthcheck:
+      test: wget -qO- http://localhost:<port>/health || exit 1
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+Rules for port type:
+- `type: web` if Dockerfile serves static HTML, runs Next.js/React/Vite, or uses nginx/caddy
+- `type: api` otherwise
+
+Rules for environment variables:
+- If the Dockerfile has `ENV FOO=bar` → `FOO=bar` (has default)
+- If you see `ARG FOO` or `ENV FOO` with no value → `FOO` (secret, no default)
+
+---
+
+## Step 4 — Show and explain
+
+Show the generated `app.yaml` to the user and explain:
+1. They must fill in `commit:` with a 40-char hex commit hash before publishing
+2. They can add a `healthcheck:` if the service has a health endpoint
+3. If the app has an agent, they can add an `agent:` service block
+4. The `rate_limit` is requests per second — adjust to match expected load
+
+---
+
+## Notes
+
+- Never write `network_mode`, `privileged`, or `cap_add` — these are blocked by the gateway
+- Do not use floating `:latest` image tags — warn the user to pin versions
+- The `commit:` field is intentionally left empty as a placeholder

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

@@ -0,0 +1,102 @@
+---
+name: install-app
+description: Install an app from the registry or a GitHub URL. Interactive — shows permissions summary, prompts for env vars, polls to completion, and reports proxy URLs.
+user-invocable: true
+allowed-tools:
+  - mcp__gateway__install_app
+  - mcp__gateway__poll_install_job
+  - mcp__gateway__browse_registry
+---
+
+# /install-app — Install an App Store App
+
+Arguments passed: `$ARGUMENTS`
+
+---
+
+## Argument formats
+
+- `/install-app <registry-name>` — install latest version from registry
+- `/install-app <registry-name> <version>` — install specific version
+- `/install-app <github-url> <40-hex-commit>` — custom GitHub install (pinned commit)
+
+---
+
+## Step 1 — Resolve the app
+
+**Registry install:** call `browse_registry` with the app name to get its versions list.
+Show the user:
+- App name and description
+- Repo URL
+- Version you will install (and whether it is latest)
+
+**GitHub install:** validate that the commit is a 40-char hex string. If not, tell the user
+and stop.
+
+If the app is not found in the registry and no GitHub URL given, stop with a helpful message.
+
+---
+
+## Step 2 — Check for required env vars
+
+Call `browse_registry` to get the app definition. If the app has `secretKeys` listed, those
+env vars must be supplied. Prompt the user for each missing secret before proceeding:
+
+```
+This app requires the following environment variables:
+  MY_API_KEY — (no default)
+  SOME_TOKEN — (no default)
+
+Please provide values, e.g.:
+  MY_API_KEY=xxx
+  SOME_TOKEN=yyy
+```
+
+Wait for the user's reply. Parse key=value pairs.
+
+If no secrets are needed, proceed immediately.
+
+---
+
+## Step 3 — Show permissions summary
+
+Before installing, show a brief summary:
+
+```
+Installing: <app-name> v<version>
+Source: <registry|github>
+Repo: <url>
+Commit: <first 8 chars>
+Proxy routes: (from registry metadata if available)
+Secrets to inject: <list or "none">
+
+Proceed? (yes/no)
+```
+
+Wait for confirmation.
+
+---
+
+## Step 4 — Install
+
+Call `install_app` with the resolved parameters and any collected env vars.
+
+Store the returned `jobId`.
+
+---
+
+## Step 5 — Poll to completion
+
+Poll `poll_install_job` every 3 seconds. Show a brief progress line after each poll
+(use the last log entry from the job). Stop when status is `completed` or `failed`.
+
+On **completed**: show proxy URLs from `result.proxyUrls`.
+On **failed**: show the error message and last 5 log entries.
+
+---
+
+## Notes
+
+- Never pass branch names as `commit` — only 40-char hex strings are valid.
+- `env_vars` values should not be echoed back to the user after collection.
+- If the user cancels at any confirmation step, say so and stop.

package/mcp/tools/apps/skills/list-apps/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: list-apps
+description: List all installed apps with their status, version, and proxy URLs.
+user-invocable: true
+allowed-tools:
+  - mcp__gateway__list_apps
+---
+
+# /list-apps — List Installed Apps
+
+Arguments passed: `$ARGUMENTS`
+
+---
+
+Call `list_apps` and format the result as a readable table:
+
+```
+Installed Apps
+──────────────────────────────────────────────
+NAME              VERSION   STATUS    SOURCE
+my-app            1.2.0     running   registry
+another-app       0.3.1     stopped   custom
+──────────────────────────────────────────────
+Total: 2 app(s)
+```
+
+For each app also show its proxy URLs if it has ports:
+```
+  Proxy routes:
+    api  → /app/my-app/api/
+    web  → /app/my-app/web/
+```
+
+If no apps are installed, say so clearly.

package/mcp/tools/telegram/receiver-server.ts

@@ -35,6 +35,7 @@ import { hasMarkdown, toTelegramHtml } from './pure'
 const STATE_DIR = process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
 const ACCESS_FILE = join(STATE_DIR, 'access.json')
 const APPROVED_DIR = join(STATE_DIR, 'approved')
+const AWAITING_OWNER_FILE = join(STATE_DIR, 'awaiting-owner')
 const ENV_FILE = join(STATE_DIR, '.env')
 
 // Load .env fallback when token not injected via env block (standalone mode).
@@ -114,7 +115,7 @@ type GroupPolicy = {
 }
 
 type Access = {
-  dmPolicy: 'pairing' | 'allowlist' | 'disabled'
+  dmPolicy: 'open' | 'pairing' | 'allowlist' | 'disabled'
   allowFrom: string[]
   groups: Record<string, GroupPolicy>
   pending: Record<string, PendingEntry>
@@ -232,7 +233,40 @@ function gate(ctx: Context): GateResult {
   const senderId = String(from.id)
   const chatType = ctx.chat?.type
 
+  // Owner init-pairing sentinel: first private message auto-approves sender as owner.
   if (chatType === 'private') {
+    try {
+      const stat = statSync(AWAITING_OWNER_FILE)
+      const age = Date.now() - stat.mtimeMs
+      if (age < 10 * 60 * 1000) {
+        // Sentinel is valid — approve this sender as owner
+        if (!access.allowFrom.includes(senderId)) access.allowFrom.push(senderId)
+        saveAccess(access)
+        rmSync(AWAITING_OWNER_FILE, { force: true })
+        // Write approved file so receiver sends confirmation message
+        mkdirSync(APPROVED_DIR, { recursive: true })
+        writeFileSync(join(APPROVED_DIR, senderId), String(ctx.chat!.id))
+        return { action: 'deliver', access }
+      } else {
+        rmSync(AWAITING_OWNER_FILE, { force: true })
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+        // Unexpected I/O error — deny to be safe rather than silently allowing
+        return { action: 'drop' }
+      }
+      // ENOENT — no sentinel, continue normal gate logic
+    }
+  }
+
+  if (chatType === 'private') {
+    if (access.dmPolicy === 'open') {
+      if (!access.allowFrom.includes(senderId)) {
+        access.allowFrom.push(senderId)
+        saveAccess(access)
+      }
+      return { action: 'deliver', access }
+    }
     if (access.allowFrom.includes(senderId)) return { action: 'deliver', access }
     if (access.dmPolicy === 'allowlist') return { action: 'drop' }
 
@@ -1592,7 +1626,7 @@ if (RECEIVER_MODE) {
         }
         if (err instanceof Error && err.message === 'Aborted delay') return
         process.stderr.write(`telegram channel (receiver): polling failed: ${err}\n`)
-        return
+        process.exit(1)
       }
     }
   })()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xmaxma/claude-gateway",
-  "version": "1.1.9",
+  "version": "1.2.0",
   "description": "Multi-agent gateway for Claude",
   "repository": {
     "type": "git",