twinclaw 1.0.0

package/dist/types/reasoning-graph.js

@@ -0,0 +1 @@
+export {};

package/dist/types/release.js

@@ -0,0 +1 @@
+export {};

package/dist/types/reliability.js

@@ -0,0 +1 @@
+export {};

package/dist/types/runtime-budget.js

@@ -0,0 +1 @@
+export {};

package/dist/types/scheduler.js

@@ -0,0 +1 @@
+export {};

package/dist/types/secret-vault.js

@@ -0,0 +1 @@
+export {};

package/dist/types/skill-packages.js

@@ -0,0 +1 @@
+export {};

package/dist/types/websocket.js

@@ -0,0 +1,14 @@
+// ── Close Codes ────────────────────────────────────────────────────────────────
+/** Deterministic close codes for WebSocket control-plane lifecycle events. */
+export const WsCloseCode = {
+    /** Authentication token missing or invalid. */
+    AuthFailed: 4001,
+    /** Client did not complete auth handshake within the required window. */
+    AuthRequired: 4002,
+    /** Subscription request contains an unrecognised topic. */
+    InvalidSubscription: 4003,
+    /** Client failed to respond to ping heartbeats (stale). */
+    StaleConnection: 4004,
+    /** Server is shutting down gracefully. */
+    ServerShutdown: 4005,
+};

package/dist/utils/logger.js

@@ -0,0 +1,57 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { getSecretVaultService } from '../services/secret-vault.js';
+function currentDateIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function transcriptPath(dateIso) {
+    return path.resolve('memory', `${dateIso}.md`);
+}
+async function ensureTranscriptDir() {
+    await mkdir(path.resolve('memory'), { recursive: true });
+}
+export function scrubSensitiveText(raw) {
+    let sanitized = raw;
+    sanitized = sanitized.replace(/(api[_-]?key|token|secret|password)\s*[:=]\s*[^\s\n]+/gi, '$1=[REDACTED]');
+    sanitized = sanitized.replace(/Bearer\s+[A-Za-z0-9._\-]+/g, 'Bearer [REDACTED]');
+    sanitized = sanitized.replace(/[A-Za-z0-9_\-]{20,}\.[A-Za-z0-9_\-]{20,}\.[A-Za-z0-9_\-]{20,}/g, '[REDACTED_JWT]');
+    try {
+        sanitized = getSecretVaultService().redact(sanitized);
+    }
+    catch (error) {
+        // Redaction fallback keeps logger resilient in test/mocked environments.
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[Logger] Secret-vault redaction skipped: ${message}`);
+    }
+    return sanitized;
+}
+async function appendSection(title, body) {
+    await ensureTranscriptDir();
+    const line = `\n## ${title} @ ${nowIso()}\n\n${body}\n`;
+    await appendFile(transcriptPath(currentDateIso()), line, 'utf8');
+}
+export async function logThought(note) {
+    await appendSection('Thought', scrubSensitiveText(note));
+}
+export async function logToolCall(toolName, args, result) {
+    const payload = [
+        `- Tool: ${toolName}`,
+        `- Args: ${scrubSensitiveText(JSON.stringify(args))}`,
+        `- Result: ${scrubSensitiveText(result)}`,
+    ].join('\n');
+    await appendSection('Tool Call', payload);
+}
+export async function logSystemCommand(command, output, exitCode) {
+    const payload = [
+        `- Command: ${scrubSensitiveText(command)}`,
+        `- ExitCode: ${exitCode}`,
+        `- Output:`,
+        '```text',
+        scrubSensitiveText(output),
+        '```',
+    ].join('\n');
+    await appendSection('System Command', payload);
+}

package/dist/utils/retry.js

@@ -0,0 +1,61 @@
+import { logThought } from './logger.js';
+const DEFAULTS = {
+    maxAttempts: 3,
+    baseDelayMs: 1000,
+    backoffFactor: 2,
+    maxDelayMs: 15_000,
+};
+/**
+ * Execute an async function with bounded exponential backoff retry.
+ *
+ * - Retries up to `maxAttempts` times on failure.
+ * - Delay doubles after each attempt (capped at `maxDelayMs`).
+ * - All attempts are logged for postmortem traceability.
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *   () => telegram.sendText(chatId, text),
+ *   { maxAttempts: 3, label: 'telegram:sendText' },
+ * );
+ * ```
+ */
+export async function withRetry(fn, options = {}) {
+    const maxAttempts = options.maxAttempts ?? DEFAULTS.maxAttempts;
+    const baseDelayMs = options.baseDelayMs ?? DEFAULTS.baseDelayMs;
+    const backoffFactor = options.backoffFactor ?? DEFAULTS.backoffFactor;
+    const maxDelayMs = options.maxDelayMs ?? DEFAULTS.maxDelayMs;
+    const label = options.label ?? 'unnamed';
+    const start = Date.now();
+    let lastError = '';
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const value = await fn();
+            const totalDurationMs = Date.now() - start;
+            if (attempt > 1) {
+                void logThought(`[Retry] ${label} succeeded on attempt ${attempt}/${maxAttempts} (${totalDurationMs}ms).`);
+            }
+            return { ok: true, value, attempts: attempt, totalDurationMs };
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err.message : String(err);
+            if (attempt < maxAttempts) {
+                const delay = Math.min(baseDelayMs * backoffFactor ** (attempt - 1), maxDelayMs);
+                void logThought(`[Retry] ${label} attempt ${attempt}/${maxAttempts} failed: ${lastError}. Retrying in ${delay}ms.`);
+                await sleep(delay);
+            }
+            else {
+                void logThought(`[Retry] ${label} exhausted all ${maxAttempts} attempts. Last error: ${lastError}.`);
+            }
+        }
+    }
+    return {
+        ok: false,
+        error: lastError,
+        attempts: maxAttempts,
+        totalDurationMs: Date.now() - start,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/utils/secret-scan.js

@@ -0,0 +1,208 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const SCAN_FILE_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.cjs',
+    '.mjs',
+    '.json',
+    '.md',
+    '.yaml',
+    '.yml',
+    '.env',
+    '.txt',
+]);
+const EXCLUDED_PATH_SEGMENTS = new Set([
+    '.git',
+    '.github\\workflows\\node_modules',
+    'node_modules',
+    'dist',
+    'coverage',
+    '.next',
+    '.vite',
+    '.turbo',
+    'memory',
+]);
+const IGNORED_FILE_NAMES = new Set([
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+]);
+const PLACEHOLDER_MARKERS = [
+    '<YOUR_',
+    '<REDACTED',
+    'YOUR_API_KEY',
+    'YOUR_TOKEN',
+    'EXAMPLE_',
+    'TEST_',
+    'DUMMY_',
+    'PLACEHOLDER',
+];
+const SECRET_PATTERNS = [
+    {
+        name: 'OpenRouter API key',
+        severity: 'high',
+        expression: /\bsk-or-v1-[A-Za-z0-9]{32,}\b/g,
+    },
+    {
+        name: 'Telegram bot token',
+        severity: 'high',
+        expression: /\b\d{8,10}:[A-Za-z0-9_-]{35,}\b/g,
+    },
+    {
+        name: 'Google API key',
+        severity: 'high',
+        expression: /\bAIza[0-9A-Za-z_-]{35}\b/g,
+    },
+    {
+        name: 'GitHub personal access token',
+        severity: 'high',
+        expression: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g,
+    },
+    {
+        name: 'AWS access key ID',
+        severity: 'high',
+        expression: /\bAKIA[0-9A-Z]{16}\b/g,
+    },
+    {
+        name: 'Private key block',
+        severity: 'high',
+        expression: /-----BEGIN [A-Z ]+ PRIVATE KEY-----/g,
+    },
+    {
+        name: 'Suspicious key assignment',
+        severity: 'medium',
+        expression: /\b(api[_-]?key|token|secret)\b\s*[:=]\s*["'][A-Za-z0-9._-]{20,}["']/gi,
+    },
+];
+function toRelativePath(rootDir, filePath) {
+    return path.relative(rootDir, filePath).replace(/\\/g, '/');
+}
+function isExcludedPath(relativePath) {
+    const normalized = relativePath.toLowerCase();
+    if (normalized.length === 0) {
+        return false;
+    }
+    if (IGNORED_FILE_NAMES.has(path.basename(normalized))) {
+        return true;
+    }
+    for (const segment of EXCLUDED_PATH_SEGMENTS) {
+        const normalizedSegment = segment.replace(/\\/g, '/').toLowerCase();
+        if (normalized === normalizedSegment ||
+            normalized.startsWith(`${normalizedSegment}/`) ||
+            normalized.includes(`/${normalizedSegment}/`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function shouldScanFile(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    return SCAN_FILE_EXTENSIONS.has(extension) || path.basename(filePath).startsWith('.env');
+}
+function hasPlaceholderMarker(value) {
+    const upper = value.toUpperCase();
+    return PLACEHOLDER_MARKERS.some((marker) => upper.includes(marker));
+}
+function isIntentionalExample(line) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('#')) {
+        return true;
+    }
+    if (trimmed.includes('example.com')) {
+        return true;
+    }
+    if (trimmed.includes('REDACTED') || trimmed.includes('redacted')) {
+        return true;
+    }
+    if (hasPlaceholderMarker(trimmed)) {
+        return true;
+    }
+    return false;
+}
+function maskMatch(value) {
+    if (value.length <= 8) {
+        return '********';
+    }
+    return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}
+function scanFile(filePath, rootDir) {
+    const hits = [];
+    const relativePath = toRelativePath(rootDir, filePath);
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const lines = raw.split(/\r?\n/);
+    lines.forEach((line, index) => {
+        if (isIntentionalExample(line)) {
+            return;
+        }
+        for (const pattern of SECRET_PATTERNS) {
+            pattern.expression.lastIndex = 0;
+            for (const match of line.matchAll(pattern.expression)) {
+                const matched = match[0];
+                if (!matched) {
+                    continue;
+                }
+                if (hasPlaceholderMarker(matched)) {
+                    continue;
+                }
+                hits.push({
+                    file: relativePath,
+                    line: index + 1,
+                    pattern: pattern.name,
+                    severity: pattern.severity,
+                    preview: maskMatch(matched),
+                });
+            }
+        }
+    });
+    return hits;
+}
+function walkDirectory(rootDir, currentDir, hits) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry.name);
+        const relativePath = toRelativePath(rootDir, fullPath);
+        if (isExcludedPath(relativePath)) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            walkDirectory(rootDir, fullPath, hits);
+            continue;
+        }
+        if (!entry.isFile() || !shouldScanFile(fullPath)) {
+            continue;
+        }
+        hits.push(...scanFile(fullPath, rootDir));
+    }
+}
+export function runSecretScan(rootDir = process.cwd()) {
+    const absoluteRoot = path.resolve(rootDir);
+    const hits = [];
+    walkDirectory(absoluteRoot, absoluteRoot, hits);
+    const high = hits.filter((hit) => hit.severity === 'high');
+    const medium = hits.filter((hit) => hit.severity === 'medium');
+    const passed = high.length === 0;
+    if (high.length === 0 && medium.length === 0) {
+        console.log('Secret scan passed: no suspicious credentials detected.');
+        return { high, medium, passed };
+    }
+    if (high.length > 0) {
+        console.error('High-severity secret findings detected:');
+        for (const hit of high) {
+            console.error(`  [HIGH] ${hit.file}:${hit.line} ${hit.pattern} (${hit.preview})`);
+        }
+    }
+    if (medium.length > 0) {
+        console.warn('Medium-severity secret findings detected:');
+        for (const hit of medium) {
+            console.warn(`  [MEDIUM] ${hit.file}:${hit.line} ${hit.pattern} (${hit.preview})`);
+        }
+    }
+    return { high, medium, passed };
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const rootArg = process.argv[2] ?? process.cwd();
+    const result = runSecretScan(rootArg);
+    process.exit(result.passed ? 0 : 1);
+}

package/mcp-servers.json

@@ -0,0 +1,179 @@
+{
+    "servers": [
+        {
+            "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
+        },
+        {
+            "id": "memory",
+            "name": "Memory (Knowledge Graph)",
+            "description": "Persistent knowledge graph for long-term factual memory and entity relationships.",
+            "transport": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@modelcontextprotocol/server-memory"
+            ],
+            "autoConnect": true,
+            "enabled": true
+        },
+        {
+            "id": "brave-search",
+            "name": "Brave Search",
+            "description": "Web and local search via Brave Search API for real-time information retrieval.",
+            "transport": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@modelcontextprotocol/server-brave-search"
+            ],
+            "env": {
+                "BRAVE_API_KEY": ""
+            },
+            "autoConnect": false,
+            "enabled": false
+        },
+        {
+            "id": "github",
+            "name": "GitHub",
+            "description": "Interact with GitHub repositories, issues, pull requests, and code management.",
+            "transport": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@modelcontextprotocol/server-github"
+            ],
+            "env": {
+                "GITHUB_PERSONAL_ACCESS_TOKEN": ""
+            },
+            "autoConnect": false,
+            "enabled": false
+        },
+        {
+            "id": "puppeteer",
+            "name": "Puppeteer (Browser Automation)",
+            "description": "Control a Chromium browser for web scraping, screenshots, and automated UI interaction.",
+            "transport": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@modelcontextprotocol/server-puppeteer"
+            ],
+            "autoConnect": false,
+            "enabled": true
+        },
+        {
+            "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
+        },
+        {
+            "id": "sqlite",
+            "name": "SQLite",
+            "description": "Query and manage SQLite databases with schema inspection and analysis capabilities.",
+            "transport": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@modelcontextprotocol/server-sqlite",
+                "--db-path",
+                "./memory/twinclaw.db"
+            ],
+            "autoConnect": false,
+            "enabled": true
+        },
+        {
+            "id": "postgres",
+            "name": "PostgreSQL",
+            "description": "Connect to PostgreSQL databases for data querying and schema analysis.",
+            "transport": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@modelcontextprotocol/server-postgres"
+            ],
+            "env": {
+                "POSTGRES_CONNECTION_STRING": ""
+            },
+            "autoConnect": false,
+            "enabled": false
+        },
+        {
+            "id": "slack",
+            "name": "Slack",
+            "description": "Send messages, read channels, and manage Slack workspace interactions.",
+            "transport": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@modelcontextprotocol/server-slack"
+            ],
+            "env": {
+                "SLACK_BOT_TOKEN": "",
+                "SLACK_TEAM_ID": ""
+            },
+            "autoConnect": false,
+            "enabled": false
+        },
+        {
+            "id": "google-maps",
+            "name": "Google Maps",
+            "description": "Geocoding, directions, place search, and distance calculations via Google Maps API.",
+            "transport": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@modelcontextprotocol/server-google-maps"
+            ],
+            "env": {
+                "GOOGLE_MAPS_API_KEY": ""
+            },
+            "autoConnect": false,
+            "enabled": false
+        },
+        {
+            "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
+        },
+        {
+            "id": "everything",
+            "name": "Everything (Test Server)",
+            "description": "Reference MCP server implementing all protocol features — for testing and debugging.",
+            "transport": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@modelcontextprotocol/server-everything"
+            ],
+            "autoConnect": false,
+            "enabled": false
+        }
+    ]
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "twinclaw",
+  "version": "1.0.0",
+  "description": "TwinClaw - Windows-first agentic AI gateway with proactive memory and multimodal hooks.",
+  "main": "dist/index.js",
+  "bin": {
+    "twinclaw": "./bin/twinclaw.js",
+    "npm-twinclaw": "./bin/npm-twinclaw.js"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "src/types/",
+    "src/skills/",
+    "node_modules/",
+    "mcp-servers.json",
+    "skill-packages.json",
+    "skill-packages.lock.json",
+    "twinclaw.default.json"
+  ],
+  "scripts": {
+    "twinclaw": "tsx src/index.ts",
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts",
+    "build": "tsc",
+    "check": "npm run check:types && npm run check:secrets",
+    "check:types": "tsc --noEmit",
+    "check:secrets": "tsx src/utils/secret-scan.ts",
+    "setup:hooks": "git config core.hooksPath .githooks",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:ci": "vitest run --coverage --reporter json --outputFile=test-results.json",
+    "test:release": "vitest run tests/harness/release-pipeline.spec.ts",
+    "release:preflight": "tsx src/release/cli.ts preflight",
+    "release:prepare": "tsx src/release/cli.ts prepare",
+    "release:rollback": "tsx src/release/cli.ts rollback",
+    "release:drill": "tsx src/release/cli.ts drill",
+    "mvp:gate": "tsx src/release/mvp-gate-cli.ts",
+    "mvp:gate:local": "tsx src/release/mvp-gate-cli.ts --skip-health"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "@elevenlabs/elevenlabs-js": "^2.36.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@types/node-telegram-bot-api": "^0.64.13",
+    "better-sqlite3": "^12.6.2",
+    "blessed": "^0.1.81",
+    "blessed-contrib": "^1.0.11",
+    "chokidar": "^5.0.0",
+    "express": "^5.2.1",
+    "groq-sdk": "^0.37.0",
+    "node-cron": "^4.2.1",
+    "node-telegram-bot-api": "^0.63.0",
+    "node-windows": "^1.0.0-beta.8",
+    "playwright": "^1.58.2",
+    "playwright-core": "^1.58.2",
+    "qrcode-terminal": "^0.12.0",
+    "sqlite-vec": "^0.1.7-alpha.2",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "whatsapp-web.js": "^1.17.1",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/blessed": "^0.1.27",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.3.0",
+    "@types/node-windows": "^0.1.6",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/supertest": "^6.0.3",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "supertest": "^7.2.2",
+    "vitest": "^4.0.18"
+  }
+}