twinclaw 1.0.0

package/dist/release/twinbot-config-schema.js

@@ -0,0 +1,162 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readRequiredObject(parent, key, path, errors) {
+    const value = parent[key];
+    if (!isRecord(value)) {
+        errors.push(`${path} must be an object.`);
+        return null;
+    }
+    return value;
+}
+function readRequiredString(parent, key, path, errors, allowEmpty = false) {
+    const value = parent[key];
+    if (typeof value !== 'string') {
+        errors.push(`${path} must be a string.`);
+        return null;
+    }
+    if (!allowEmpty && value.trim().length === 0) {
+        errors.push(`${path} must be a non-empty string.`);
+    }
+    return value;
+}
+function readRequiredBoolean(parent, key, path, errors) {
+    const value = parent[key];
+    if (typeof value !== 'boolean') {
+        errors.push(`${path} must be a boolean.`);
+        return null;
+    }
+    return value;
+}
+function readRequiredIntegerInRange(parent, key, path, min, max, errors) {
+    const value = parent[key];
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        errors.push(`${path} must be an integer.`);
+        return null;
+    }
+    if (value < min || value > max) {
+        errors.push(`${path} must be between ${min} and ${max}.`);
+    }
+    return value;
+}
+function readStringArray(parent, key, path, errors) {
+    const value = parent[key];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        errors.push(`${path} must be an array of strings.`);
+        return null;
+    }
+    return value;
+}
+function validateRuntime(root, errors) {
+    const runtime = readRequiredObject(root, 'runtime', 'runtime', errors);
+    if (!runtime) {
+        return;
+    }
+    readRequiredString(runtime, 'apiSecret', 'runtime.apiSecret', errors, false);
+    readRequiredIntegerInRange(runtime, 'apiPort', 'runtime.apiPort', 1, 65535, errors);
+    readStringArray(runtime, 'secretVaultRequired', 'runtime.secretVaultRequired', errors);
+}
+function validateModels(root, errors) {
+    const models = readRequiredObject(root, 'models', 'models', errors);
+    if (!models) {
+        return;
+    }
+    const modalApiKey = readRequiredString(models, 'modalApiKey', 'models.modalApiKey', errors, true);
+    const openRouterApiKey = readRequiredString(models, 'openRouterApiKey', 'models.openRouterApiKey', errors, true);
+    const geminiApiKey = readRequiredString(models, 'geminiApiKey', 'models.geminiApiKey', errors, true);
+    const hasModelKey = [modalApiKey, openRouterApiKey, geminiApiKey].some((value) => typeof value === 'string' && value.trim().length > 0);
+    if (!hasModelKey) {
+        errors.push('At least one model API key must be configured in models.*ApiKey.');
+    }
+}
+function validateMessaging(root, errors) {
+    const messaging = readRequiredObject(root, 'messaging', 'messaging', errors);
+    if (!messaging) {
+        return;
+    }
+    const telegram = readRequiredObject(messaging, 'telegram', 'messaging.telegram', errors);
+    if (telegram) {
+        readRequiredBoolean(telegram, 'enabled', 'messaging.telegram.enabled', errors);
+        readRequiredString(telegram, 'botToken', 'messaging.telegram.botToken', errors, true);
+        const userId = telegram['userId'];
+        if (!(typeof userId === 'number' || userId === null)) {
+            errors.push('messaging.telegram.userId must be a number or null.');
+        }
+    }
+    const whatsapp = readRequiredObject(messaging, 'whatsapp', 'messaging.whatsapp', errors);
+    if (whatsapp) {
+        readRequiredBoolean(whatsapp, 'enabled', 'messaging.whatsapp.enabled', errors);
+        readRequiredString(whatsapp, 'phoneNumber', 'messaging.whatsapp.phoneNumber', errors, true);
+    }
+    const voice = readRequiredObject(messaging, 'voice', 'messaging.voice', errors);
+    if (voice) {
+        readRequiredString(voice, 'groqApiKey', 'messaging.voice.groqApiKey', errors, true);
+    }
+    const inbound = readRequiredObject(messaging, 'inbound', 'messaging.inbound', errors);
+    if (inbound) {
+        readRequiredBoolean(inbound, 'enabled', 'messaging.inbound.enabled', errors);
+        readRequiredIntegerInRange(inbound, 'debounceMs', 'messaging.inbound.debounceMs', 0, 60_000, errors);
+    }
+    const streaming = readRequiredObject(messaging, 'streaming', 'messaging.streaming', errors);
+    if (streaming) {
+        readRequiredBoolean(streaming, 'blockStreamingDefault', 'messaging.streaming.blockStreamingDefault', errors);
+        const breakMode = readRequiredString(streaming, 'blockStreamingBreak', 'messaging.streaming.blockStreamingBreak', errors, false);
+        if (breakMode && breakMode !== 'paragraph' && breakMode !== 'sentence') {
+            errors.push("messaging.streaming.blockStreamingBreak must be 'paragraph' or 'sentence'.");
+        }
+        readRequiredIntegerInRange(streaming, 'blockStreamingMinChars', 'messaging.streaming.blockStreamingMinChars', 1, 50_000, errors);
+        readRequiredIntegerInRange(streaming, 'blockStreamingMaxChars', 'messaging.streaming.blockStreamingMaxChars', 1, 200_000, errors);
+        readRequiredBoolean(streaming, 'blockStreamingCoalesce', 'messaging.streaming.blockStreamingCoalesce', errors);
+        readRequiredIntegerInRange(streaming, 'humanDelayMs', 'messaging.streaming.humanDelayMs', 0, 120_000, errors);
+    }
+}
+function validateStorage(root, errors) {
+    const storage = readRequiredObject(root, 'storage', 'storage', errors);
+    if (!storage) {
+        return;
+    }
+    readRequiredIntegerInRange(storage, 'embeddingDim', 'storage.embeddingDim', 1, 1_000_000, errors);
+}
+function validateIntegration(root, errors) {
+    const integration = readRequiredObject(root, 'integration', 'integration', errors);
+    if (!integration) {
+        return;
+    }
+    const provider = readRequiredString(integration, 'embeddingProvider', 'integration.embeddingProvider', errors, false);
+    if (provider && provider !== 'openai' && provider !== 'ollama') {
+        errors.push("integration.embeddingProvider must be 'openai' or 'ollama'.");
+    }
+    readRequiredString(integration, 'embeddingApiKey', 'integration.embeddingApiKey', errors, true);
+    readRequiredString(integration, 'openaiApiKey', 'integration.openaiApiKey', errors, true);
+    readRequiredString(integration, 'embeddingApiUrl', 'integration.embeddingApiUrl', errors, false);
+    readRequiredString(integration, 'embeddingModel', 'integration.embeddingModel', errors, false);
+    readRequiredString(integration, 'ollamaBaseUrl', 'integration.ollamaBaseUrl', errors, false);
+    readRequiredString(integration, 'ollamaEmbeddingModel', 'integration.ollamaEmbeddingModel', errors, false);
+}
+function validateTools(root, errors) {
+    const tools = readRequiredObject(root, 'tools', 'tools', errors);
+    if (!tools) {
+        return;
+    }
+    readStringArray(tools, 'allow', 'tools.allow', errors);
+    readStringArray(tools, 'deny', 'tools.deny', errors);
+}
+export function validateTwinBotConfigSchema(value) {
+    if (!isRecord(value)) {
+        return {
+            valid: false,
+            errors: ['Root config must be a JSON object.'],
+        };
+    }
+    const errors = [];
+    validateRuntime(value, errors);
+    validateModels(value, errors);
+    validateMessaging(value, errors);
+    validateStorage(value, errors);
+    validateIntegration(value, errors);
+    validateTools(value, errors);
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/dist/release/twinclaw-config-schema.js

@@ -0,0 +1,162 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readRequiredObject(parent, key, path, errors) {
+    const value = parent[key];
+    if (!isRecord(value)) {
+        errors.push(`${path} must be an object.`);
+        return null;
+    }
+    return value;
+}
+function readRequiredString(parent, key, path, errors, allowEmpty = false) {
+    const value = parent[key];
+    if (typeof value !== 'string') {
+        errors.push(`${path} must be a string.`);
+        return null;
+    }
+    if (!allowEmpty && value.trim().length === 0) {
+        errors.push(`${path} must be a non-empty string.`);
+    }
+    return value;
+}
+function readRequiredBoolean(parent, key, path, errors) {
+    const value = parent[key];
+    if (typeof value !== 'boolean') {
+        errors.push(`${path} must be a boolean.`);
+        return null;
+    }
+    return value;
+}
+function readRequiredIntegerInRange(parent, key, path, min, max, errors) {
+    const value = parent[key];
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        errors.push(`${path} must be an integer.`);
+        return null;
+    }
+    if (value < min || value > max) {
+        errors.push(`${path} must be between ${min} and ${max}.`);
+    }
+    return value;
+}
+function readStringArray(parent, key, path, errors) {
+    const value = parent[key];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        errors.push(`${path} must be an array of strings.`);
+        return null;
+    }
+    return value;
+}
+function validateRuntime(root, errors) {
+    const runtime = readRequiredObject(root, 'runtime', 'runtime', errors);
+    if (!runtime) {
+        return;
+    }
+    readRequiredString(runtime, 'apiSecret', 'runtime.apiSecret', errors, false);
+    readRequiredIntegerInRange(runtime, 'apiPort', 'runtime.apiPort', 1, 65535, errors);
+    readStringArray(runtime, 'secretVaultRequired', 'runtime.secretVaultRequired', errors);
+}
+function validateModels(root, errors) {
+    const models = readRequiredObject(root, 'models', 'models', errors);
+    if (!models) {
+        return;
+    }
+    const modalApiKey = readRequiredString(models, 'modalApiKey', 'models.modalApiKey', errors, true);
+    const openRouterApiKey = readRequiredString(models, 'openRouterApiKey', 'models.openRouterApiKey', errors, true);
+    const geminiApiKey = readRequiredString(models, 'geminiApiKey', 'models.geminiApiKey', errors, true);
+    const hasModelKey = [modalApiKey, openRouterApiKey, geminiApiKey].some((value) => typeof value === 'string' && value.trim().length > 0);
+    if (!hasModelKey) {
+        errors.push('At least one model API key must be configured in models.*ApiKey.');
+    }
+}
+function validateMessaging(root, errors) {
+    const messaging = readRequiredObject(root, 'messaging', 'messaging', errors);
+    if (!messaging) {
+        return;
+    }
+    const telegram = readRequiredObject(messaging, 'telegram', 'messaging.telegram', errors);
+    if (telegram) {
+        readRequiredBoolean(telegram, 'enabled', 'messaging.telegram.enabled', errors);
+        readRequiredString(telegram, 'botToken', 'messaging.telegram.botToken', errors, true);
+        const userId = telegram['userId'];
+        if (!(typeof userId === 'number' || userId === null)) {
+            errors.push('messaging.telegram.userId must be a number or null.');
+        }
+    }
+    const whatsapp = readRequiredObject(messaging, 'whatsapp', 'messaging.whatsapp', errors);
+    if (whatsapp) {
+        readRequiredBoolean(whatsapp, 'enabled', 'messaging.whatsapp.enabled', errors);
+        readRequiredString(whatsapp, 'phoneNumber', 'messaging.whatsapp.phoneNumber', errors, true);
+    }
+    const voice = readRequiredObject(messaging, 'voice', 'messaging.voice', errors);
+    if (voice) {
+        readRequiredString(voice, 'groqApiKey', 'messaging.voice.groqApiKey', errors, true);
+    }
+    const inbound = readRequiredObject(messaging, 'inbound', 'messaging.inbound', errors);
+    if (inbound) {
+        readRequiredBoolean(inbound, 'enabled', 'messaging.inbound.enabled', errors);
+        readRequiredIntegerInRange(inbound, 'debounceMs', 'messaging.inbound.debounceMs', 0, 60_000, errors);
+    }
+    const streaming = readRequiredObject(messaging, 'streaming', 'messaging.streaming', errors);
+    if (streaming) {
+        readRequiredBoolean(streaming, 'blockStreamingDefault', 'messaging.streaming.blockStreamingDefault', errors);
+        const breakMode = readRequiredString(streaming, 'blockStreamingBreak', 'messaging.streaming.blockStreamingBreak', errors, false);
+        if (breakMode && breakMode !== 'paragraph' && breakMode !== 'sentence') {
+            errors.push("messaging.streaming.blockStreamingBreak must be 'paragraph' or 'sentence'.");
+        }
+        readRequiredIntegerInRange(streaming, 'blockStreamingMinChars', 'messaging.streaming.blockStreamingMinChars', 1, 50_000, errors);
+        readRequiredIntegerInRange(streaming, 'blockStreamingMaxChars', 'messaging.streaming.blockStreamingMaxChars', 1, 200_000, errors);
+        readRequiredBoolean(streaming, 'blockStreamingCoalesce', 'messaging.streaming.blockStreamingCoalesce', errors);
+        readRequiredIntegerInRange(streaming, 'humanDelayMs', 'messaging.streaming.humanDelayMs', 0, 120_000, errors);
+    }
+}
+function validateStorage(root, errors) {
+    const storage = readRequiredObject(root, 'storage', 'storage', errors);
+    if (!storage) {
+        return;
+    }
+    readRequiredIntegerInRange(storage, 'embeddingDim', 'storage.embeddingDim', 1, 1_000_000, errors);
+}
+function validateIntegration(root, errors) {
+    const integration = readRequiredObject(root, 'integration', 'integration', errors);
+    if (!integration) {
+        return;
+    }
+    const provider = readRequiredString(integration, 'embeddingProvider', 'integration.embeddingProvider', errors, false);
+    if (provider && provider !== 'openai' && provider !== 'ollama') {
+        errors.push("integration.embeddingProvider must be 'openai' or 'ollama'.");
+    }
+    readRequiredString(integration, 'embeddingApiKey', 'integration.embeddingApiKey', errors, true);
+    readRequiredString(integration, 'openaiApiKey', 'integration.openaiApiKey', errors, true);
+    readRequiredString(integration, 'embeddingApiUrl', 'integration.embeddingApiUrl', errors, false);
+    readRequiredString(integration, 'embeddingModel', 'integration.embeddingModel', errors, false);
+    readRequiredString(integration, 'ollamaBaseUrl', 'integration.ollamaBaseUrl', errors, false);
+    readRequiredString(integration, 'ollamaEmbeddingModel', 'integration.ollamaEmbeddingModel', errors, false);
+}
+function validateTools(root, errors) {
+    const tools = readRequiredObject(root, 'tools', 'tools', errors);
+    if (!tools) {
+        return;
+    }
+    readStringArray(tools, 'allow', 'tools.allow', errors);
+    readStringArray(tools, 'deny', 'tools.deny', errors);
+}
+export function validateTwinclawConfigSchema(value) {
+    if (!isRecord(value)) {
+        return {
+            valid: false,
+            errors: ['Root config must be a JSON object.'],
+        };
+    }
+    const errors = [];
+    validateRuntime(value, errors);
+    validateModels(value, errors);
+    validateMessaging(value, errors);
+    validateStorage(value, errors);
+    validateIntegration(value, errors);
+    validateTools(value, errors);
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/dist/services/block-chunker.js

@@ -0,0 +1,174 @@
+const DEFAULT_OPTIONS = {
+    minChars: 50,
+    maxChars: 800,
+    breakOn: 'paragraph',
+    coalesce: true,
+};
+const CODE_FENCE_PATTERN = /```[\s\S]*?```/g;
+const CODE_FENCE_START = '```';
+const CODE_FENCE_END = '```';
+export class EmbeddedBlockChunker {
+    #minChars;
+    #maxChars;
+    #breakOn;
+    #coalesce;
+    constructor(options = {}) {
+        this.#minChars = Math.max(1, Math.floor(options.minChars ?? DEFAULT_OPTIONS.minChars));
+        this.#maxChars = Math.max(this.#minChars + 1, Math.floor(options.maxChars ?? DEFAULT_OPTIONS.maxChars));
+        this.#breakOn = options.breakOn ?? DEFAULT_OPTIONS.breakOn;
+        this.#coalesce = options.coalesce ?? DEFAULT_OPTIONS.coalesce;
+    }
+    get minChars() {
+        return this.#minChars;
+    }
+    get maxChars() {
+        return this.#maxChars;
+    }
+    chunk(text) {
+        if (!text || text.trim().length === 0) {
+            return [];
+        }
+        const result = this.#chunkText(text);
+        if (this.#coalesce) {
+            return this.#coalesceChunks(result.chunks);
+        }
+        return result.chunks;
+    }
+    #chunkText(text) {
+        const codeBlockRanges = this.#findCodeBlockRanges(text);
+        if (this.#breakOn === 'paragraph') {
+            return this.#chunkByParagraph(text, codeBlockRanges);
+        }
+        return this.#chunkBySentence(text, codeBlockRanges);
+    }
+    #findCodeBlockRanges(text) {
+        const ranges = [];
+        let match;
+        CODE_FENCE_PATTERN.lastIndex = 0;
+        while ((match = CODE_FENCE_PATTERN.exec(text)) !== null) {
+            ranges.push({ start: match.index, end: match.index + match[0].length });
+        }
+        return ranges;
+    }
+    #isInsideCodeBlock(index, ranges) {
+        for (const range of ranges) {
+            if (index >= range.start && index < range.end) {
+                return true;
+            }
+        }
+        return false;
+    }
+    #chunkByParagraph(text, codeBlockRanges) {
+        const paragraphs = text.split(/\n\n+/);
+        const chunks = [];
+        let currentChunk = '';
+        let wasSplit = false;
+        for (const paragraph of paragraphs) {
+            const trimmed = paragraph.trim();
+            if (!trimmed)
+                continue;
+            const wouldExceed = currentChunk.length + trimmed.length + 2 > this.#maxChars;
+            if (wouldExceed && currentChunk.length >= this.#minChars) {
+                chunks.push(currentChunk.trim());
+                currentChunk = trimmed;
+                wasSplit = true;
+            }
+            else if (wouldExceed && currentChunk.length > 0) {
+                const sentenceChunks = this.#chunkBySentence(trimmed, codeBlockRanges);
+                if (sentenceChunks.wasSplit) {
+                    wasSplit = true;
+                }
+                for (const sentence of sentenceChunks.chunks) {
+                    if (currentChunk.length + sentence.length + 1 <= this.#maxChars) {
+                        currentChunk += (currentChunk ? ' ' : '') + sentence;
+                    }
+                    else {
+                        if (currentChunk)
+                            chunks.push(currentChunk.trim());
+                        currentChunk = sentence;
+                        wasSplit = true;
+                    }
+                }
+            }
+            else {
+                currentChunk += (currentChunk ? '\n\n' : '') + trimmed;
+            }
+        }
+        if (currentChunk.trim()) {
+            chunks.push(currentChunk.trim());
+        }
+        return { chunks, wasSplit };
+    }
+    #chunkBySentence(text, codeBlockRanges) {
+        const sentenceEndPattern = /([.!?])\s+/g;
+        const chunks = [];
+        let currentChunk = '';
+        let wasSplit = false;
+        let lastIndex = 0;
+        let match;
+        const globalIndex = text;
+        sentenceEndPattern.lastIndex = 0;
+        while ((match = sentenceEndPattern.exec(globalIndex)) !== null) {
+            const sentenceEnd = match.index + 1;
+            const sentence = globalIndex.slice(lastIndex, sentenceEnd).trim();
+            if (!sentence) {
+                lastIndex = match.index + match[0].length;
+                continue;
+            }
+            const wouldExceed = currentChunk.length + sentence.length + 1 > this.#maxChars;
+            if (wouldExceed && currentChunk.length >= this.#minChars) {
+                chunks.push(currentChunk.trim());
+                currentChunk = sentence;
+                wasSplit = true;
+            }
+            else {
+                currentChunk += (currentChunk ? ' ' : '') + sentence;
+            }
+            lastIndex = match.index + match[0].length;
+        }
+        const remaining = globalIndex.slice(lastIndex).trim();
+        if (remaining) {
+            if (currentChunk.length + remaining.length + 1 <= this.#maxChars) {
+                currentChunk += (currentChunk ? ' ' : '') + remaining;
+            }
+            else {
+                if (currentChunk)
+                    chunks.push(currentChunk.trim());
+                currentChunk = remaining;
+                wasSplit = true;
+            }
+        }
+        if (currentChunk.trim()) {
+            chunks.push(currentChunk.trim());
+        }
+        return { chunks, wasSplit };
+    }
+    #coalesceChunks(chunks) {
+        if (chunks.length <= 1)
+            return chunks;
+        const result = [];
+        for (const chunk of chunks) {
+            const lastChunk = result[result.length - 1];
+            if (lastChunk && lastChunk.length < this.#minChars && lastChunk.length + chunk.length + 1 <= this.#maxChars) {
+                result[result.length - 1] = lastChunk + ' ' + chunk;
+            }
+            else if (chunk.length < this.#minChars && result.length === 0) {
+                result.push(chunk);
+            }
+            else if (chunk.length < this.#minChars && result.length > 0) {
+                result[result.length - 1] = result[result.length - 1] + ' ' + chunk;
+            }
+            else {
+                result.push(chunk);
+            }
+        }
+        return result;
+    }
+    static ensureCodeFenceClosed(text) {
+        const openCount = (text.match(/```/g) || []).length;
+        if (openCount % 2 === 1) {
+            return text + '\n```';
+        }
+        return text;
+    }
+}