@0xmaxma/claude-gateway 1.0.0

package/mcp/tools/discord/skills/configure/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: discord-configure
+description: Configure the Discord channel — save bot token, set auto-thread, embed options.
+user-invocable: true
+---
+
+# /gateway:discord-configure — Configure Discord
+
+Use this skill to set up the Discord channel for an agent.
+
+## Required setup
+
+### 1. Save the bot token
+```
+/gateway:discord-configure token <BOT_TOKEN>
+```
+Writes `DISCORD_BOT_TOKEN=<token>` to `$DISCORD_STATE_DIR/.env`.
+
+### 2. Set required env vars in agent config
+Add to the agent's `.env` file:
+```
+DISCORD_BOT_TOKEN=<your-bot-token>
+DISCORD_STATE_DIR=~/.claude-gateway/agents/<id>/.discord-state
+DISCORD_DM_POLICY=disabled        # open | allowlist | disabled
+DISCORD_GUILD_ALLOWLIST=          # comma-separated guild IDs (empty = all)
+DISCORD_CHANNEL_ALLOWLIST=        # comma-separated channel IDs (empty = all)
+DISCORD_AUTO_THREAD=false         # create thread per conversation
+DISCORD_USE_EMBEDS=false          # use embeds for long responses
+```
+
+## Discord Developer Portal checklist
+
+1. Go to https://discord.com/developers/applications
+2. Select your application → Bot settings
+3. Enable **MESSAGE CONTENT INTENT** (privileged intent)
+4. Required bot permissions:
+   - Send Messages
+   - Read Message History
+   - Create Public Threads
+   - Send Messages in Threads
+   - Attach Files
+   - Embed Links
+   - Add Reactions
+   - Use Application Commands
+
+## Implementation
+
+Parse the subcommand and act accordingly:
+- `token <value>` — write `.env` file to DISCORD_STATE_DIR
+- `show` — display current env vars (mask the token)
+- `check` — verify the bot can connect (call discord_reply to a test channel if provided)
+
+Confirm each action and display what was changed.

package/mcp/tools/discord/threading.ts

@@ -0,0 +1,37 @@
+/**
+ * Discord thread management — openclaw pattern from threading.ts.
+ * Uses local DiscordMessage interface; no top-level discord.js import.
+ */
+
+import type { DiscordMessage } from './types';
+
+export async function maybeCreateThread(
+  message: DiscordMessage,
+  autoThread: boolean,
+  autoArchiveDuration: number,
+): Promise<{ id: string } | null> {
+  if (!autoThread) return null;
+  if (message.channel.isThread()) return null;
+  if (!message.guild) return null;
+
+  const name = sanitizeThreadName(message.content);
+  return message.startThread({ name, autoArchiveDuration });
+}
+
+export function sanitizeThreadName(text: string): string {
+  return text
+    .replace(/<@!?\d+>/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 100) || 'conversation';
+}
+
+export function buildSessionKey(
+  agentId: string,
+  channelId: string,
+  userId: string,
+  threadId?: string | null,
+): string {
+  const chatId = threadId ?? channelId;
+  return `${agentId}:discord:${userId}:${chatId}`;
+}

package/mcp/tools/discord/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Discord-specific types. No discord.js imports — pure TypeScript.
+ */
+
+export interface DiscordPending {
+  senderId: string;
+  channelId: string;
+  createdAt: number;
+  expiresAt: number;
+  replies: number;
+}
+
+export interface DiscordAccess {
+  dmPolicy: 'pairing' | 'allowlist' | 'disabled';
+  allowFrom: string[];
+  guildAllowlist: string[];
+  channelAllowlist: string[];
+  roleAllowlist: string[];
+  pending: Record<string, DiscordPending>;
+}
+
+export type DiscordGateResult =
+  | { action: 'deliver' }
+  | { action: 'drop' }
+  | { action: 'pair'; code: string; isResend: boolean };
+
+export type DiscordConfig = {
+  botToken: string;
+  guildAllowlist?: string[];
+  channelAllowlist?: string[];
+  dmPolicy: 'open' | 'allowlist' | 'disabled';
+  dmAllowlist?: string[];
+  autoThread: boolean;
+  autoThreadArchiveMinutes: 60 | 1440 | 4320 | 10080;
+  maxMessageLength: number;
+  useEmbeds: boolean;
+};
+
+export type DiscordMessageContext = {
+  guildId: string | null;
+  channelId: string;
+  threadId: string | null;
+  userId: string;
+  username: string;
+  messageId: string;
+  isDM: boolean;
+  isThread: boolean;
+};
+
+export type DiscordAccessConfig = {
+  dmPolicy: 'open' | 'allowlist' | 'disabled';
+  dmAllowlist: string[];
+  guildAllowlist: string[];
+  channelAllowlist: string[];
+  roleAllowlist: string[];
+};
+
+/** Minimal interface for a Discord text-based channel send operation. */
+export interface SendableChannel {
+  send(options: SendOptions): Promise<SentMessage>;
+}
+
+export type SendOptions = {
+  content?: string;
+  embeds?: EmbedData[];
+  files?: FileAttachment[];
+  reply?: { messageReference: string };
+};
+
+export type SentMessage = { id: string };
+
+export type EmbedData = { description: string };
+
+export type FileAttachment = { attachment: string; name?: string };
+
+/** Minimal interface for a Discord message (for inbound handler). */
+export interface DiscordMessage {
+  id: string;
+  content: string;
+  author: { id: string; username: string; bot: boolean };
+  system: boolean;
+  guild: { id: string } | null;
+  guildId: string | null;
+  channelId: string;
+  channel: {
+    isThread(): boolean;
+    parentId?: string | null;
+  };
+  createdTimestamp: number;
+  attachments: { first(): { url: string } | undefined };
+  client: { user: { id: string } | null };
+  startThread(options: { name: string; autoArchiveDuration: number }): Promise<{ id: string }>;
+}
+
+export type SlashCommandDef = {
+  name: string;
+  description: string;
+  options?: SlashCommandOption[];
+};
+
+export type SlashCommandOption = {
+  name: string;
+  description: string;
+  required: boolean;
+  type: 'STRING';
+};

package/mcp/tools/skills/handlers.ts

@@ -0,0 +1,196 @@
+/**
+ * Skill management handlers: create, delete, install.
+ * Pure functions operating on the filesystem — no MCP dependency.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Skill name validation: lowercase alphanumeric + hyphens, 1-64 chars
+const VALID_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// Reserved names that conflict with system commands
+const RESERVED_NAMES = new Set([
+  'help', 'sessions', 'session', 'new', 'clear', 'compact',
+  'rename', 'model', 'restart', 'access', 'configure',
+]);
+
+const MAX_SKILL_SIZE = 100 * 1024; // 100KB
+
+function validateName(name: string): string | null {
+  if (!VALID_NAME_RE.test(name)) {
+    return `Invalid skill name "${name}". Must be lowercase alphanumeric with hyphens, 1-64 chars.`;
+  }
+  if (RESERVED_NAMES.has(name)) {
+    return `Skill name "${name}" is reserved. Choose a different name.`;
+  }
+  return null;
+}
+
+function getSkillDir(scope: 'workspace' | 'shared', name: string, workspaceDir: string, sharedSkillsDir: string): string {
+  if (scope === 'workspace') {
+    return path.join(workspaceDir, 'skills', name);
+  }
+  return path.join(sharedSkillsDir, name);
+}
+
+export interface CreateSkillParams {
+  name: string;
+  description: string;
+  content: string;
+  scope: 'workspace' | 'shared';
+  workspaceDir: string;
+  sharedSkillsDir: string;
+}
+
+/**
+ * Create a new skill by writing a SKILL.md file with proper frontmatter.
+ */
+export async function createSkill(params: CreateSkillParams): Promise<string> {
+  const { name, description, content, scope, workspaceDir, sharedSkillsDir } = params;
+
+  const nameError = validateName(name);
+  if (nameError) throw new Error(nameError);
+
+  const skillDir = getSkillDir(scope, name, workspaceDir, sharedSkillsDir);
+  const skillFile = path.join(skillDir, 'SKILL.md');
+
+  if (fs.existsSync(skillFile)) {
+    throw new Error(`Skill "${name}" already exists at ${skillDir}. Use skill_delete first or choose a different name.`);
+  }
+
+  // Build SKILL.md with frontmatter
+  const skillMd = [
+    '---',
+    `name: ${name}`,
+    `description: "${description.replace(/"/g, '\\"')}"`,
+    '---',
+    '',
+    content,
+  ].join('\n');
+
+  // Atomic write: create dir, write to .tmp, rename
+  fs.mkdirSync(skillDir, { recursive: true });
+  const tmpFile = skillFile + '.tmp';
+  fs.writeFileSync(tmpFile, skillMd, 'utf-8');
+  fs.renameSync(tmpFile, skillFile);
+
+  return `Skill "${name}" created at ${skillFile} (scope: ${scope})`;
+}
+
+export interface DeleteSkillParams {
+  name: string;
+  scope: 'workspace' | 'shared';
+  workspaceDir: string;
+  sharedSkillsDir: string;
+}
+
+/**
+ * Delete a skill by removing its directory.
+ */
+export async function deleteSkill(params: DeleteSkillParams): Promise<string> {
+  const { name, scope, workspaceDir, sharedSkillsDir } = params;
+
+  const skillDir = getSkillDir(scope, name, workspaceDir, sharedSkillsDir);
+  const skillFile = path.join(skillDir, 'SKILL.md');
+
+  if (!fs.existsSync(skillFile)) {
+    throw new Error(`Skill "${name}" not found in ${scope} (looked at ${skillDir})`);
+  }
+
+  fs.rmSync(skillDir, { recursive: true, force: true });
+
+  return `Skill "${name}" deleted from ${scope}`;
+}
+
+export interface InstallSkillParams {
+  url: string;
+  scope: 'workspace' | 'shared';
+  name?: string;
+  force?: boolean;
+  workspaceDir: string;
+  sharedSkillsDir: string;
+}
+
+/**
+ * Convert a github.com URL to raw.githubusercontent.com.
+ * e.g. https://github.com/user/repo/tree/main/skills/foo/SKILL.md
+ *   -> https://raw.githubusercontent.com/user/repo/main/skills/foo/SKILL.md
+ */
+export function toRawGitHubUrl(url: string): string {
+  // Already raw
+  if (url.includes('raw.githubusercontent.com')) return url;
+
+  // GitHub blob/tree URL pattern
+  const match = url.match(
+    /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/(tree|blob)\/([^/]+)\/(.+)$/
+  );
+  if (match) {
+    const [, owner, repo, , branch, filePath] = match;
+    // If the URL points to a directory, append /SKILL.md
+    const finalPath = filePath.endsWith('SKILL.md') ? filePath : `${filePath}/SKILL.md`;
+    return `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${finalPath}`;
+  }
+
+  return url;
+}
+
+/**
+ * Install a skill from a URL by fetching SKILL.md and writing it locally.
+ */
+export async function installSkill(params: InstallSkillParams): Promise<string> {
+  const { url, scope, force, workspaceDir, sharedSkillsDir } = params;
+
+  // Security: only allow HTTPS
+  if (!url.startsWith('https://')) {
+    throw new Error('Only HTTPS URLs are supported for security.');
+  }
+
+  const rawUrl = toRawGitHubUrl(url);
+
+  // Fetch content
+  const response = await fetch(rawUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${rawUrl}: ${response.status} ${response.statusText}`);
+  }
+
+  const content = await response.text();
+
+  // Size check
+  if (content.length > MAX_SKILL_SIZE) {
+    throw new Error(`SKILL.md exceeds ${MAX_SKILL_SIZE / 1024}KB limit (${(content.length / 1024).toFixed(1)}KB)`);
+  }
+
+  // Parse frontmatter to extract name
+  const { extractFrontmatter } = await import('../../../src/skills/parser');
+  const extracted = extractFrontmatter(content);
+  if (!extracted) {
+    throw new Error('Invalid SKILL.md: no valid YAML frontmatter found.');
+  }
+
+  const fm = extracted.frontmatter;
+  const skillName = params.name || (typeof fm.name === 'string' ? fm.name : '');
+  if (!skillName) {
+    throw new Error('Invalid SKILL.md: missing "name" in frontmatter. Use the name parameter to override.');
+  }
+
+  const nameError = validateName(skillName);
+  if (nameError) throw new Error(nameError);
+
+  const skillDir = getSkillDir(scope, skillName, workspaceDir, sharedSkillsDir);
+  const skillFile = path.join(skillDir, 'SKILL.md');
+
+  if (fs.existsSync(skillFile) && !force) {
+    throw new Error(`Skill "${skillName}" already exists. Use force: true to overwrite.`);
+  }
+
+  // Write skill file (atomic)
+  fs.mkdirSync(skillDir, { recursive: true });
+  const tmpFile = skillFile + '.tmp';
+  fs.writeFileSync(tmpFile, content, 'utf-8');
+  fs.renameSync(tmpFile, skillFile);
+
+  const description = typeof fm.description === 'string' ? fm.description : '(no description)';
+
+  return `Skill "${skillName}" installed from ${rawUrl} (scope: ${scope})\nDescription: ${description}`;
+}

package/mcp/tools/skills/module.ts

@@ -0,0 +1,163 @@
+/**
+ * Skills tool module — implements ToolModule interface.
+ * Provides skill management tools: skill_create, skill_delete, skill_install.
+ * Tool-only module with "all-configured" visibility.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type {
+  ToolModule,
+  McpToolDefinition,
+  McpToolResult,
+  ToolVisibility,
+} from '../../types';
+import {
+  createSkill,
+  deleteSkill,
+  installSkill,
+  type CreateSkillParams,
+  type DeleteSkillParams,
+  type InstallSkillParams,
+} from './handlers';
+
+export class SkillsModule implements ToolModule {
+  id = 'skills';
+  toolVisibility: ToolVisibility = 'all-configured';
+
+  isEnabled(): boolean {
+    // Skills tools are available when workspace dir is known
+    return Boolean(process.env.GATEWAY_WORKSPACE_DIR);
+  }
+
+  getTools(): McpToolDefinition[] {
+    return [
+      {
+        name: 'skill_create',
+        description: 'Create a new skill from content. The skill will be available immediately via hot-reload.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'Skill slug name (lowercase, hyphens allowed, e.g. "my-helper")',
+            },
+            description: {
+              type: 'string',
+              description: 'One-line description of what the skill does',
+            },
+            content: {
+              type: 'string',
+              description: 'Full SKILL.md body content (instructions for the agent)',
+            },
+            scope: {
+              type: 'string',
+              enum: ['workspace', 'shared'],
+              description: 'Where to save: "workspace" (this agent only) or "shared" (all agents). Default: workspace',
+            },
+          },
+          required: ['name', 'description', 'content'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'skill_delete',
+        description: 'Delete a skill by name.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'Skill name to delete',
+            },
+            scope: {
+              type: 'string',
+              enum: ['workspace', 'shared'],
+              description: 'Where to look: "workspace" or "shared". Default: workspace',
+            },
+          },
+          required: ['name'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'skill_install',
+        description: 'Install a skill from a GitHub URL or raw URL pointing to a SKILL.md file.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            url: {
+              type: 'string',
+              description: 'URL to SKILL.md (GitHub URLs auto-converted to raw)',
+            },
+            scope: {
+              type: 'string',
+              enum: ['workspace', 'shared'],
+              description: 'Where to install: "workspace" or "shared". Default: workspace',
+            },
+            name: {
+              type: 'string',
+              description: 'Override skill name (default: parsed from frontmatter)',
+            },
+            force: {
+              type: 'boolean',
+              description: 'Overwrite if skill already exists. Default: false',
+            },
+          },
+          required: ['url'],
+          additionalProperties: false,
+        },
+      },
+    ];
+  }
+
+  async handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+    const workspaceDir = process.env.GATEWAY_WORKSPACE_DIR!;
+    const sharedSkillsDir = process.env.GATEWAY_SHARED_SKILLS_DIR ||
+      path.join(process.env.HOME || '/tmp', '.claude-gateway', 'shared-skills');
+
+    try {
+      switch (name) {
+        case 'skill_create': {
+          const params: CreateSkillParams = {
+            name: args.name as string,
+            description: args.description as string,
+            content: args.content as string,
+            scope: (args.scope as 'workspace' | 'shared') || 'workspace',
+            workspaceDir,
+            sharedSkillsDir,
+          };
+          const result = await createSkill(params);
+          return { content: [{ type: 'text', text: result }] };
+        }
+        case 'skill_delete': {
+          const params: DeleteSkillParams = {
+            name: args.name as string,
+            scope: (args.scope as 'workspace' | 'shared') || 'workspace',
+            workspaceDir,
+            sharedSkillsDir,
+          };
+          const result = await deleteSkill(params);
+          return { content: [{ type: 'text', text: result }] };
+        }
+        case 'skill_install': {
+          const params: InstallSkillParams = {
+            url: args.url as string,
+            scope: (args.scope as 'workspace' | 'shared') || 'workspace',
+            name: args.name as string | undefined,
+            force: args.force as boolean | undefined,
+            workspaceDir,
+            sharedSkillsDir,
+          };
+          const result = await installSkill(params);
+          return { content: [{ type: 'text', text: result }] };
+        }
+        default:
+          return { content: [{ type: 'text', text: `unknown tool: ${name}` }], isError: true };
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: 'text', text: `${name} failed: ${msg}` }], isError: true };
+    }
+  }
+}