twinclaw 1.0.0

package/dist/services/skill-registry.js

@@ -0,0 +1,122 @@
+import { logThought } from '../utils/logger.js';
+/**
+ * Centralized skill registry for TwinBot.
+ *
+ * Serves as a single catalog for all available tools — both local builtins
+ * and MCP-backed remote skills. The lane executor queries this registry
+ * to build the tool list sent to the model router.
+ *
+ * Usage:
+ * ```ts
+ * const registry = new SkillRegistry();
+ * registry.registerMany(createBuiltinSkills());
+ * registry.register(mcpBackedSkill);
+ * const allTools = registry.list();
+ * ```
+ */
+export class SkillRegistry {
+    #skills = new Map();
+    #aliases = new Map();
+    #removeAliasesForCanonical(canonicalName) {
+        for (const [alias, mappedCanonical] of this.#aliases.entries()) {
+            if (mappedCanonical === canonicalName) {
+                this.#aliases.delete(alias);
+            }
+        }
+    }
+    #resolveCanonicalName(name) {
+        return this.#aliases.get(name) ?? name;
+    }
+    /** Register a single skill. Overwrites if a skill with the same name already exists. */
+    register(skill) {
+        const source = skill.source ?? 'builtin';
+        const canonicalName = skill.name;
+        this.#removeAliasesForCanonical(canonicalName);
+        const normalized = { ...skill, source };
+        this.#skills.set(canonicalName, normalized);
+        for (const alias of skill.aliases ?? []) {
+            const normalizedAlias = alias.trim();
+            if (!normalizedAlias || normalizedAlias === canonicalName) {
+                continue;
+            }
+            if (this.#skills.has(normalizedAlias)) {
+                continue;
+            }
+            this.#aliases.set(normalizedAlias, canonicalName);
+        }
+        void logThought(`[SkillRegistry] Registered skill '${skill.name}' (source: ${source}, aliases: ${skill.aliases?.length ?? 0}).`);
+    }
+    /** Register multiple skills at once. */
+    registerMany(skills) {
+        for (const skill of skills) {
+            this.register(skill);
+        }
+    }
+    /** Unregister a skill by name. Returns true if the skill was found and removed. */
+    unregister(name) {
+        const canonicalName = this.#resolveCanonicalName(name);
+        const removed = this.#skills.delete(canonicalName);
+        if (removed) {
+            this.#removeAliasesForCanonical(canonicalName);
+        }
+        return removed;
+    }
+    /** Unregister all skills from a specific MCP server. */
+    unregisterByServer(serverId) {
+        const namesToRemove = [];
+        for (const [name, skill] of this.#skills.entries()) {
+            if (skill.serverId === serverId) {
+                namesToRemove.push(name);
+            }
+        }
+        for (const name of namesToRemove) {
+            this.unregister(name);
+        }
+        return namesToRemove.length;
+    }
+    /** Look up a skill by its unique name. */
+    get(name) {
+        return this.#skills.get(this.#resolveCanonicalName(name));
+    }
+    /** Check if a skill with the given name exists in the registry. */
+    has(name) {
+        return this.get(name) !== undefined;
+    }
+    /** List all registered skills, optionally filtered by source or server. */
+    list(filter) {
+        const all = [...this.#skills.values()];
+        if (!filter)
+            return all;
+        return all.filter((skill) => {
+            if (filter.source && skill.source !== filter.source)
+                return false;
+            if (filter.serverId && skill.serverId !== filter.serverId)
+                return false;
+            if (filter.group && skill.group !== filter.group)
+                return false;
+            return true;
+        });
+    }
+    /** Return the total number of registered skills. */
+    get size() {
+        return this.#skills.size;
+    }
+    /** Return a summary of skills grouped by source. */
+    summary() {
+        const counts = {
+            builtin: 0,
+            mcp: 0,
+            groups: {},
+        };
+        for (const skill of this.#skills.values()) {
+            const source = skill.source ?? 'builtin';
+            if (source === 'builtin' || source === 'mcp') {
+                counts[source] += 1;
+            }
+            if (skill.group) {
+                counts.groups[skill.group] = (counts.groups[skill.group] ?? 0) + 1;
+            }
+        }
+        return counts;
+    }
+}

package/dist/services/streaming-output.js

@@ -0,0 +1,75 @@
+import { EmbeddedBlockChunker } from './block-chunker.js';
+const DEFAULT_HUMAN_DELAY_MS = 800;
+export class StreamingOutputService {
+    #enabled;
+    #humanDelayMs;
+    #chunker;
+    #queue;
+    #now;
+    #sleep;
+    #activeStreams = new Map();
+    constructor(queue, options = {}) {
+        this.#queue = queue;
+        this.#enabled = options.enabled ?? true;
+        this.#humanDelayMs = Math.max(0, Math.floor(options.humanDelayMs ?? DEFAULT_HUMAN_DELAY_MS));
+        this.#chunker = new EmbeddedBlockChunker(options.chunkerOptions);
+        this.#now = options.now ?? (() => Date.now());
+        this.#sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    get enabled() {
+        return this.#enabled;
+    }
+    startStream(streamId, platform, chatId) {
+        this.#activeStreams.set(streamId, {
+            platform,
+            chatId,
+            buffer: '',
+            chunks: [],
+        });
+    }
+    handleDelta(streamId, delta) {
+        const context = this.#activeStreams.get(streamId);
+        if (!context)
+            return;
+        if (delta.type === 'text_delta' && delta.content) {
+            context.buffer += delta.content;
+        }
+    }
+    async finalizeStream(streamId) {
+        const context = this.#activeStreams.get(streamId);
+        if (!context)
+            return;
+        this.#activeStreams.delete(streamId);
+        const fullText = context.buffer.trim();
+        if (!fullText)
+            return;
+        if (!this.#enabled) {
+            this.#queue.enqueue(context.platform, context.chatId, fullText);
+            return;
+        }
+        const chunks = this.#chunker.chunk(fullText);
+        for (let i = 0; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            const closedChunk = EmbeddedBlockChunker.ensureCodeFenceClosed(chunk);
+            if (i > 0 && this.#humanDelayMs > 0) {
+                await this.#sleep(this.#humanDelayMs);
+            }
+            this.#queue.enqueue(context.platform, context.chatId, closedChunk);
+        }
+    }
+    async streamAndDispatch(streamId, platform, chatId, streamFn) {
+        this.startStream(streamId, platform, chatId);
+        try {
+            await streamFn((delta) => this.handleDelta(streamId, delta));
+        }
+        finally {
+            await this.finalizeStream(streamId);
+        }
+    }
+    getActiveStreamCount() {
+        return this.#activeStreams.size;
+    }
+    getChunker() {
+        return this.#chunker;
+    }
+}

package/dist/services/stt-service.js

@@ -0,0 +1,39 @@
+import Groq from 'groq-sdk';
+import { createReadStream } from 'node:fs';
+const DEFAULT_MODEL = 'whisper-large-v3-turbo';
+/**
+ * Speech-to-Text service backed by Groq's hosted Whisper API (free tier).
+ *
+ * Multimodal queuing contract: transcription is fully awaited before the
+ * caller receives the text, ensuring audio processing completes before any
+ * downstream text handling begins.
+ */
+export class SttService {
+    #client;
+    #model;
+    /**
+     * @param apiKey - Groq API key (GROQ_API_KEY).
+     * @param model  - Whisper model variant; defaults to `whisper-large-v3-turbo`.
+     */
+    constructor(apiKey, model = DEFAULT_MODEL) {
+        this.#client = new Groq({ apiKey });
+        this.#model = model;
+    }
+    /**
+     * Transcribe a local audio file to text.
+     *
+     * @param filePath - Absolute path to a supported audio file
+     *                   (flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm).
+     * @returns The transcribed text string.
+     * @throws If the Groq API call fails or the file cannot be read.
+     */
+    async transcribeFile(filePath) {
+        const audioStream = createReadStream(filePath);
+        const result = await this.#client.audio.transcriptions.create({
+            file: audioStream,
+            model: this.#model,
+            response_format: 'json',
+        });
+        return result.text;
+    }
+}

package/dist/services/tts-service.js

@@ -0,0 +1,44 @@
+import Groq from 'groq-sdk';
+const DEFAULT_MODEL_ID = 'canopylabs/orpheus-v1-english';
+const DEFAULT_VOICE = 'autumn';
+const DEFAULT_FORMAT = 'wav';
+/**
+ * Text-to-Speech service backed by the Groq Audio Speech API.
+ *
+ * Returns a raw WAV Buffer that can be sent directly as a Telegram voice message
+ * or written to disk for further processing.
+ */
+export class TtsService {
+    #client;
+    #modelId;
+    #voice;
+    #outputFormat;
+    /**
+     * @param apiKey       - Groq API key (GROQ_API_KEY).
+     * @param modelId      - Model to use for synthesis; defaults to `canopylabs/orpheus-v1-english`.
+     * @param voice        - Voice preset to use; defaults to `autumn`.
+     * @param outputFormat - Audio encoding; defaults to `wav`.
+     */
+    constructor(apiKey, modelId = DEFAULT_MODEL_ID, voice = DEFAULT_VOICE, outputFormat = DEFAULT_FORMAT) {
+        this.#client = new Groq({ apiKey });
+        this.#modelId = modelId;
+        this.#voice = voice;
+        this.#outputFormat = outputFormat;
+    }
+    /**
+     * Convert text to a synthesized WAV audio buffer.
+     *
+     * @param text - The text to synthesize.
+     * @returns A Buffer containing the full WAV audio.
+     * @throws If the Groq API call fails.
+     */
+    async synthesize(text) {
+        const wav = await this.#client.audio.speech.create({
+            model: this.#modelId,
+            voice: this.#voice,
+            response_format: this.#outputFormat,
+            input: text,
+        });
+        return Buffer.from(await wav.arrayBuffer());
+    }
+}

package/dist/skills/builtin.js

@@ -0,0 +1,250 @@
+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 { executeShell } from './shell.js';
+import { logToolCall } from '../utils/logger.js';
+function resolveWorkspacePath(inputPath) {
+    return path.resolve(process.cwd(), inputPath);
+}
+function quoteShellArg(value) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+function buildReadFileSkill() {
+    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() {
+    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() {
+    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() {
+    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) {
+    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() {
+    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() {
+    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() {
+    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) => 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() {
+    return [
+        buildReadFileSkill(),
+        buildListFilesSkill(),
+        buildWriteFileSkill(),
+        buildApplyPatchSkill(),
+        buildRuntimeExecSkill(),
+        buildRuntimePowerShellSkill(),
+        buildRuntimeProcessSkill(),
+    ];
+}

package/dist/skills/shell.js

@@ -0,0 +1,87 @@
+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 = [
+    { 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' },
+];
+function truncateOutput(output) {
+    if (output.length <= MAX_OUTPUT_LENGTH) {
+        return output;
+    }
+    return `${output.slice(0, MAX_OUTPUT_LENGTH)}\n...[truncated]`;
+}
+function resolveTimeout(timeoutMs) {
+    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) {
+    for (const entry of BLOCKED_COMMAND_PATTERNS) {
+        if (entry.pattern.test(command)) {
+            return entry.reason;
+        }
+    }
+    return null;
+}
+export async function executeShell(command, cwd, options = {}) {
+    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) {
+        const err = error;
+        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/dist/skills/types.js

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

package/dist/types/api.js

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

package/dist/types/context-budget.js

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

package/dist/types/doctor.js

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

package/dist/types/file-watcher.js

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

package/dist/types/incident.js

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

package/dist/types/local-state-backup.js

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

package/dist/types/mcp.js

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

package/dist/types/messaging.js

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

package/dist/types/model-routing.js

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

package/dist/types/mvp-gate.js

@@ -0,0 +1,2 @@
+// ─── MVP Gate Criterion IDs ──────────────────────────────────────────────────
+export {};

package/dist/types/orchestration.js

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

package/dist/types/persona-state.js

@@ -0,0 +1,22 @@
+export const PERSONA_DOCUMENT_KEYS = ['soul', 'identity', 'user'];
+export class PersonaValidationError extends Error {
+    hints;
+    constructor(hints) {
+        super('Persona state validation failed.');
+        this.name = 'PersonaValidationError';
+        this.hints = hints;
+    }
+}
+export class PersonaConflictError extends Error {
+    latestRevision;
+    hints;
+    constructor(latestRevision) {
+        super('Persona state is stale. Reload and retry.');
+        this.name = 'PersonaConflictError';
+        this.latestRevision = latestRevision;
+        this.hints = [
+            'Reload persona state before saving again.',
+            'Re-apply your edits on top of the latest revision.',
+        ];
+    }
+}

package/dist/types/policy.js

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