twinclaw 1.0.0

package/skill-packages.json

@@ -0,0 +1,92 @@
+{
+  "packages": [
+    {
+      "name": "filesystem",
+      "version": "1.0.0",
+      "metadata": {
+        "displayName": "Filesystem MCP Skill Pack",
+        "description": "Local filesystem operations through MCP."
+      },
+      "dependencies": {},
+      "compatibility": {
+        "node": ">=22.0.0",
+        "runtimeApi": "^1.0.0",
+        "requiredTools": [
+          "npx"
+        ]
+      },
+      "server": {
+        "id": "filesystem",
+        "name": "Filesystem",
+        "description": "Read, write, and manage local files and directories securely.",
+        "transport": "stdio",
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-filesystem",
+          "."
+        ],
+        "autoConnect": true,
+        "enabled": true
+      }
+    },
+    {
+      "name": "fetch",
+      "version": "1.0.0",
+      "metadata": {
+        "displayName": "Fetch MCP Skill Pack",
+        "description": "HTTP request and web resource retrieval skills."
+      },
+      "dependencies": {},
+      "compatibility": {
+        "node": ">=22.0.0",
+        "runtimeApi": "^1.0.0",
+        "requiredTools": [
+          "npx"
+        ]
+      },
+      "server": {
+        "id": "fetch",
+        "name": "Fetch (HTTP)",
+        "description": "Make HTTP requests to external APIs and web resources with content extraction.",
+        "transport": "stdio",
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-fetch"
+        ],
+        "autoConnect": true,
+        "enabled": true
+      }
+    },
+    {
+      "name": "sequential-thinking",
+      "version": "1.0.0",
+      "metadata": {
+        "displayName": "Sequential Thinking MCP Skill Pack",
+        "description": "Structured decomposition and reasoning assistant tools."
+      },
+      "dependencies": {},
+      "compatibility": {
+        "node": ">=22.0.0",
+        "runtimeApi": "^1.0.0",
+        "requiredTools": [
+          "npx"
+        ]
+      },
+      "server": {
+        "id": "sequential-thinking",
+        "name": "Sequential Thinking",
+        "description": "Structured, step-by-step reasoning and problem decomposition for complex tasks.",
+        "transport": "stdio",
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-sequential-thinking"
+        ],
+        "autoConnect": true,
+        "enabled": true
+      }
+    }
+  ]
+}

package/skill-packages.lock.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "generatedAt": "1970-01-01T00:00:00.000Z",
+  "packages": {}
+}

package/src/skills/builtin.ts

@@ -0,0 +1,275 @@
+import { appendFile, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { Skill } from './types.js';
+import { executeShell } from './shell.js';
+import { logToolCall } from '../utils/logger.js';
+
+function resolveWorkspacePath(inputPath: string): string {
+  return path.resolve(process.cwd(), inputPath);
+}
+
+function quoteShellArg(value: string): string {
+  return `"${value.replace(/"/g, '\\"')}"`;
+}
+
+function buildReadFileSkill(): Skill {
+  return {
+    name: 'fs.read',
+    group: 'group:fs',
+    aliases: ['read_file'],
+    description: 'Read a UTF-8 text file from disk.',
+    parameters: {
+      type: 'object',
+      properties: {
+        filePath: { type: 'string' },
+      },
+      required: ['filePath'],
+    },
+    async execute(input) {
+      const filePathValue = input.filePath;
+      if (typeof filePathValue !== 'string' || filePathValue.trim().length === 0) {
+        return { ok: false, output: 'filePath must be a non-empty string.' };
+      }
+
+      const absolutePath = resolveWorkspacePath(filePathValue);
+      const content = await readFile(absolutePath, 'utf8');
+
+      await logToolCall('fs.read', input, `Read ${content.length} chars from ${absolutePath}`);
+      return { ok: true, output: content };
+    },
+  };
+}
+
+function buildListFilesSkill(): Skill {
+  return {
+    name: 'fs.list',
+    group: 'group:fs',
+    aliases: ['list_files'],
+    description: 'List files and folders in a directory.',
+    parameters: {
+      type: 'object',
+      properties: {
+        dirPath: { type: 'string' },
+      },
+      required: [],
+    },
+    async execute(input) {
+      const dirPathValue = typeof input.dirPath === 'string' ? input.dirPath : '.';
+      const absolutePath = resolveWorkspacePath(dirPathValue);
+
+      const entries = await readdir(absolutePath, { withFileTypes: true });
+      const output = entries
+        .map((entry) => `${entry.name}${entry.isDirectory() ? '/' : ''}`)
+        .join('\n');
+
+      await logToolCall('fs.list', input, `Listed ${entries.length} entries from ${absolutePath}`);
+      return { ok: true, output };
+    },
+  };
+}
+
+function buildWriteFileSkill(): Skill {
+  return {
+    name: 'fs.write',
+    group: 'group:fs',
+    description: 'Write UTF-8 text content to a file path.',
+    parameters: {
+      type: 'object',
+      properties: {
+        filePath: { type: 'string' },
+        content: { type: 'string' },
+        append: { type: 'boolean' },
+      },
+      required: ['filePath', 'content'],
+    },
+    async execute(input) {
+      const filePathValue = input.filePath;
+      if (typeof filePathValue !== 'string' || filePathValue.trim().length === 0) {
+        return { ok: false, output: 'filePath must be a non-empty string.' };
+      }
+
+      const contentValue = input.content;
+      if (typeof contentValue !== 'string') {
+        return { ok: false, output: 'content must be a string.' };
+      }
+
+      const absolutePath = resolveWorkspacePath(filePathValue);
+      if (input.append === true) {
+        await appendFile(absolutePath, contentValue, 'utf8');
+      } else {
+        await writeFile(absolutePath, contentValue, 'utf8');
+      }
+      await logToolCall('fs.write', input, `Wrote ${contentValue.length} chars to ${absolutePath}`);
+      return { ok: true, output: `Updated ${absolutePath}.` };
+    },
+  };
+}
+
+function buildApplyPatchSkill(): Skill {
+  return {
+    name: 'fs.apply_patch',
+    group: 'group:fs',
+    aliases: ['apply_patch'],
+    description: 'Apply a unified diff patch to files in the current workspace using git apply.',
+    parameters: {
+      type: 'object',
+      properties: {
+        patch: { type: 'string' },
+      },
+      required: ['patch'],
+    },
+    async execute(input) {
+      const patchValue = input.patch;
+      if (typeof patchValue !== 'string' || patchValue.trim().length === 0) {
+        return { ok: false, output: 'patch must be a non-empty string.' };
+      }
+
+      const tempPatchPath = path.join(tmpdir(), `twinbot-${randomUUID()}.patch`);
+      try {
+        await writeFile(tempPatchPath, patchValue, 'utf8');
+        const result = await executeShell(
+          `git apply --whitespace=nowarn ${quoteShellArg(tempPatchPath)}`,
+          process.cwd(),
+          { timeoutMs: 20_000 },
+        );
+        if (!result.ok) {
+          await logToolCall('fs.apply_patch', input, `Patch apply failed: ${result.output}`);
+          return {
+            ok: false,
+            output: `Failed to apply patch: ${result.output || 'git apply returned a non-zero exit code.'}`,
+          };
+        }
+
+        await logToolCall('fs.apply_patch', input, 'Patch applied successfully.');
+        return { ok: true, output: 'Patch applied successfully.' };
+      } finally {
+        await rm(tempPatchPath, { force: true }).catch(() => undefined);
+      }
+    },
+  };
+}
+
+function resolveShellOptions(input: Record<string, unknown>): { timeoutMs?: number; allowUnsafe?: boolean } {
+  const timeoutMs =
+    typeof input.timeoutMs === 'number' && Number.isFinite(input.timeoutMs)
+      ? Math.floor(input.timeoutMs)
+      : undefined;
+  const allowUnsafe = input.allowUnsafe === true;
+  return { timeoutMs, allowUnsafe };
+}
+
+function buildRuntimeExecSkill(): Skill {
+  return {
+    name: 'runtime.exec',
+    group: 'group:runtime',
+    aliases: ['shell_execute'],
+    description: 'Execute a shell command with timeout and safety checks.',
+    parameters: {
+      type: 'object',
+      properties: {
+        command: { type: 'string' },
+        cwd: { type: 'string' },
+        timeoutMs: { type: 'number' },
+        allowUnsafe: { type: 'boolean' },
+      },
+      required: ['command'],
+    },
+    async execute(input) {
+      const commandValue = input.command;
+      if (typeof commandValue !== 'string' || commandValue.trim().length === 0) {
+        return { ok: false, output: 'command must be a non-empty string.' };
+      }
+      const cwd = typeof input.cwd === 'string' ? resolveWorkspacePath(input.cwd) : undefined;
+      const result = await executeShell(commandValue, cwd, resolveShellOptions(input));
+      await logToolCall('runtime.exec', input, result.output || '(no output)');
+
+      return {
+        ok: result.ok,
+        output: result.output,
+      };
+    },
+  };
+}
+
+function buildRuntimePowerShellSkill(): Skill {
+  return {
+    name: 'runtime.powershell',
+    group: 'group:runtime',
+    description: 'Execute a script using Windows PowerShell with timeout and safety checks.',
+    parameters: {
+      type: 'object',
+      properties: {
+        script: { type: 'string' },
+        cwd: { type: 'string' },
+        timeoutMs: { type: 'number' },
+        allowUnsafe: { type: 'boolean' },
+      },
+      required: ['script'],
+    },
+    async execute(input) {
+      const scriptValue = input.script;
+      if (typeof scriptValue !== 'string' || scriptValue.trim().length === 0) {
+        return { ok: false, output: 'script must be a non-empty string.' };
+      }
+      const cwd = typeof input.cwd === 'string' ? resolveWorkspacePath(input.cwd) : undefined;
+      const command = `powershell -NoProfile -ExecutionPolicy Bypass -Command ${quoteShellArg(scriptValue)}`;
+      const result = await executeShell(command, cwd, resolveShellOptions(input));
+      await logToolCall('runtime.powershell', input, result.output || '(no output)');
+      return {
+        ok: result.ok,
+        output: result.output,
+      };
+    },
+  };
+}
+
+function buildRuntimeProcessSkill(): Skill {
+  return {
+    name: 'runtime.process',
+    group: 'group:runtime',
+    description: 'Execute an executable with argument array under shell safety constraints.',
+    parameters: {
+      type: 'object',
+      properties: {
+        executable: { type: 'string' },
+        args: { type: 'array', items: { type: 'string' } },
+        cwd: { type: 'string' },
+        timeoutMs: { type: 'number' },
+        allowUnsafe: { type: 'boolean' },
+      },
+      required: ['executable'],
+    },
+    async execute(input) {
+      const executableValue = input.executable;
+      if (typeof executableValue !== 'string' || executableValue.trim().length === 0) {
+        return { ok: false, output: 'executable must be a non-empty string.' };
+      }
+
+      const argsValue = Array.isArray(input.args)
+        ? input.args.filter((arg): arg is string => typeof arg === 'string')
+        : [];
+      const command = [quoteShellArg(executableValue), ...argsValue.map(quoteShellArg)].join(' ');
+      const cwd = typeof input.cwd === 'string' ? resolveWorkspacePath(input.cwd) : undefined;
+      const result = await executeShell(command, cwd, resolveShellOptions(input));
+      await logToolCall('runtime.process', input, result.output || '(no output)');
+      return {
+        ok: result.ok,
+        output: result.output,
+      };
+    },
+  };
+}
+
+export function createBuiltinSkills(): Skill[] {
+  return [
+    buildReadFileSkill(),
+    buildListFilesSkill(),
+    buildWriteFileSkill(),
+    buildApplyPatchSkill(),
+    buildRuntimeExecSkill(),
+    buildRuntimePowerShellSkill(),
+    buildRuntimeProcessSkill(),
+  ];
+}

package/src/skills/shell.ts

@@ -0,0 +1,118 @@
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { logSystemCommand, scrubSensitiveText } from '../utils/logger.js';
+
+const execAsync = promisify(exec);
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_LENGTH = 8_000;
+const BLOCKED_COMMAND_PATTERNS: Array<{ pattern: RegExp; reason: string }> = [
+  { pattern: /\brm\s+-rf\s+\/\b/i, reason: 'destructive root delete' },
+  { pattern: /\brm\s+-rf\s+\*/i, reason: 'destructive wildcard delete' },
+  { pattern: /\bdel\s+\/[A-Za-z]*\s+\/[A-Za-z]*\s+[A-Za-z]:\\/i, reason: 'destructive windows delete' },
+  { pattern: /\bformat\s+[A-Za-z]:/i, reason: 'disk format command' },
+  { pattern: /\bshutdown\b/i, reason: 'system shutdown command' },
+  { pattern: /\breboot\b/i, reason: 'system reboot command' },
+  { pattern: /\bpoweroff\b/i, reason: 'system poweroff command' },
+];
+
+export interface ShellExecutionOptions {
+  timeoutMs?: number;
+  allowUnsafe?: boolean;
+}
+
+interface ExecError extends Error {
+  code?: number | string;
+  stdout?: string;
+  stderr?: string;
+}
+
+
+function truncateOutput(output: string): string {
+  if (output.length <= MAX_OUTPUT_LENGTH) {
+    return output;
+  }
+
+  return `${output.slice(0, MAX_OUTPUT_LENGTH)}\n...[truncated]`;
+}
+
+function resolveTimeout(timeoutMs?: number): number {
+  if (!Number.isFinite(timeoutMs)) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+
+  const parsed = Math.floor(Number(timeoutMs));
+  if (parsed < 1) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+  return Math.min(MAX_TIMEOUT_MS, parsed);
+}
+
+function detectBlockedCommand(command: string): string | null {
+  for (const entry of BLOCKED_COMMAND_PATTERNS) {
+    if (entry.pattern.test(command)) {
+      return entry.reason;
+    }
+  }
+  return null;
+}
+
+export async function executeShell(
+  command: string,
+  cwd?: string,
+  options: ShellExecutionOptions = {},
+): Promise<{ ok: boolean; output: string; exitCode: number }> {
+  const normalizedCommand = command.trim();
+  if (normalizedCommand.length === 0) {
+    return {
+      ok: false,
+      output: 'Command must be a non-empty string.',
+      exitCode: 1,
+    };
+  }
+
+  const blockedReason = options.allowUnsafe ? null : detectBlockedCommand(normalizedCommand);
+  if (blockedReason) {
+    const blockedOutput = `Blocked unsafe command (${blockedReason}). Set allowUnsafe=true to override.`;
+    await logSystemCommand(normalizedCommand, blockedOutput, 126);
+    return {
+      ok: false,
+      output: blockedOutput,
+      exitCode: 126,
+    };
+  }
+
+  const timeout = resolveTimeout(options.timeoutMs);
+
+  try {
+    const { stdout, stderr } = await execAsync(normalizedCommand, {
+      cwd,
+      timeout,
+      windowsHide: true,
+      maxBuffer: 1024 * 1024,
+    });
+
+    const mergedOutput = truncateOutput(scrubSensitiveText(`${stdout}${stderr}`.trim()));
+    await logSystemCommand(normalizedCommand, mergedOutput || '(no output)', 0);
+
+    return {
+      ok: true,
+      output: mergedOutput,
+      exitCode: 0,
+    };
+  } catch (error: unknown) {
+    const err = error as ExecError;
+    const mergedOutput = truncateOutput(
+      scrubSensitiveText(`${err.stdout ?? ''}${err.stderr ?? ''}${err.message ?? ''}`.trim()),
+    );
+
+    const exitCode = typeof err.code === 'number' ? err.code : 1;
+    await logSystemCommand(normalizedCommand, mergedOutput || '(no output)', exitCode);
+
+    return {
+      ok: false,
+      output: mergedOutput,
+      exitCode,
+    };
+  }
+}

package/src/skills/types.ts

@@ -0,0 +1,30 @@
+import type { JsonSchema, McpCapabilityScope, McpScopeAuditAdapter } from '../types/mcp.js';
+
+export interface SkillExecutionResult {
+  ok: boolean;
+  output: string;
+}
+
+/** Source origin of a skill — local builtin or MCP-backed. */
+export type SkillSource = 'builtin' | 'mcp';
+export type SkillGroup = `group:${string}`;
+
+export interface Skill {
+  name: string;
+  description: string;
+  /** Native tool grouping (for example: group:fs, group:runtime). */
+  group?: SkillGroup;
+  /** Optional legacy aliases that should resolve to this canonical skill. */
+  aliases?: string[];
+  /** JSON Schema describing the tool's input parameters. */
+  parameters?: JsonSchema;
+  /** Where this skill originates from. @default 'builtin' */
+  source?: SkillSource;
+  /** If source is 'mcp', which server ID provides this tool. */
+  serverId?: string;
+  /** If source is 'mcp', the adapter instance for auditing/health. */
+  adapter?: McpScopeAuditAdapter;
+  /** If source is 'mcp', what capability scope this tool has. */
+  mcpScope?: McpCapabilityScope;
+  execute(input: Record<string, unknown>): Promise<SkillExecutionResult>;
+}