twinclaw 1.0.0

package/dist/core/gateway.js

@@ -0,0 +1,416 @@
+import { randomUUID } from 'node:crypto';
+import { createSession, getSessionMessages, saveMessage } from '../services/db.js';
+import { ModelRouter } from '../services/model-router.js';
+import { indexConversationTurn, retrieveEvidenceAwareMemoryContext, } from '../services/semantic-memory.js';
+import { OrchestrationService } from '../services/orchestration-service.js';
+import { assembleContext } from './context-assembly.js';
+import { LaneExecutor } from './lane-executor.js';
+import { PolicyEngine } from '../services/policy-engine.js';
+import { logThought } from '../utils/logger.js';
+import { ContextLifecycleOrchestrator } from '../services/context-lifecycle.js';
+const DEFAULT_MAX_TOOL_ROUNDS = 6;
+const DEFAULT_IDENTICAL_TOOL_CALL_LIMIT = 3;
+const DEFAULT_DELEGATION_MIN_SCORE = 2;
+const DELEGATION_KEYWORDS = [
+    'complex',
+    'analyze',
+    'analysis',
+    'reasoning',
+    'investigate',
+    'architecture',
+    'tradeoff',
+    'plan',
+    'design',
+    'multi-step',
+    'parallel',
+];
+function isConversationRole(value) {
+    return value === 'user' || value === 'assistant' || value === 'tool';
+}
+function toConversationHistory(rows) {
+    return rows
+        .filter((row) => isConversationRole(row.role))
+        .map((row) => ({
+        role: row.role,
+        content: row.content,
+    }));
+}
+function skillToTool(skill) {
+    return {
+        name: skill.name,
+        description: skill.description,
+        parameters: skill.parameters ?? {
+            type: 'object',
+            properties: {},
+            required: [],
+            additionalProperties: true,
+        },
+        execute: async (args) => {
+            const result = await skill.execute(args);
+            return result.output;
+        },
+    };
+}
+function normalizeToolSelectors(values) {
+    if (!values || values.length === 0) {
+        return [];
+    }
+    return values
+        .map((value) => value.trim().toLowerCase())
+        .filter((value, index, all) => value.length > 0 && all.indexOf(value) === index);
+}
+function matchesToolSelector(skill, selector) {
+    const normalizedName = skill.name.toLowerCase();
+    if (selector === normalizedName) {
+        return true;
+    }
+    if (selector.startsWith('group:')) {
+        return skill.group?.toLowerCase() === selector;
+    }
+    if (selector.startsWith('source:')) {
+        return `${skill.source ?? 'builtin'}`.toLowerCase() === selector.slice('source:'.length);
+    }
+    if (selector.startsWith('mcp:')) {
+        return (skill.serverId ?? '').toLowerCase() === selector.slice('mcp:'.length);
+    }
+    return false;
+}
+export class Gateway {
+    #router;
+    #orchestration;
+    #laneExecutor;
+    #policyEngine;
+    #registry;
+    #tools = [];
+    #maxToolRounds;
+    #identicalToolCallLimit;
+    #enableDelegation;
+    #delegationMinScore;
+    #contextLifecycle;
+    #toolPolicy;
+    #degradationCounts = new Map();
+    constructor(registry, options = {}) {
+        this.#router = options.router ?? new ModelRouter();
+        this.#orchestration = options.orchestration ?? new OrchestrationService();
+        this.#policyEngine = options.policyEngine ?? new PolicyEngine();
+        this.#registry = registry;
+        this.#laneExecutor = new LaneExecutor();
+        this.#maxToolRounds =
+            Number.isFinite(options.maxToolRounds) && (options.maxToolRounds ?? 0) > 0
+                ? Number(options.maxToolRounds)
+                : DEFAULT_MAX_TOOL_ROUNDS;
+        this.#identicalToolCallLimit =
+            Number.isFinite(options.identicalToolCallLimit) && (options.identicalToolCallLimit ?? 0) > 1
+                ? Math.floor(Number(options.identicalToolCallLimit))
+                : DEFAULT_IDENTICAL_TOOL_CALL_LIMIT;
+        this.#enableDelegation = options.enableDelegation ?? true;
+        this.#delegationMinScore = Math.max(1, Number(options.delegationMinScore ?? DEFAULT_DELEGATION_MIN_SCORE));
+        this.#contextLifecycle = new ContextLifecycleOrchestrator(options.contextBudgetConfig);
+        this.#toolPolicy = {
+            allow: normalizeToolSelectors(options.toolPolicy?.allow),
+            deny: normalizeToolSelectors(options.toolPolicy?.deny),
+        };
+        this.refreshTools();
+    }
+    #filterSkillsByToolPolicy(skills) {
+        if (this.#toolPolicy.allow.length === 0 && this.#toolPolicy.deny.length === 0) {
+            return skills;
+        }
+        const allowFiltered = this.#toolPolicy.allow.length > 0
+            ? skills.filter((skill) => this.#toolPolicy.allow.some((selector) => matchesToolSelector(skill, selector)))
+            : skills;
+        if (this.#toolPolicy.deny.length === 0) {
+            return allowFiltered;
+        }
+        return allowFiltered.filter((skill) => !this.#toolPolicy.deny.some((selector) => matchesToolSelector(skill, selector)));
+    }
+    #buildToolCallSignature(toolCalls) {
+        return toolCalls
+            .map((toolCall) => `${toolCall.function.name}:${toolCall.function.arguments?.trim() ?? ''}`)
+            .join('|');
+    }
+    /** Sync the gateway's tool definitions with the current state of the skill registry. */
+    refreshTools() {
+        const skills = this.#registry.list();
+        const filteredSkills = this.#filterSkillsByToolPolicy(skills);
+        this.#tools = filteredSkills.map(skillToTool);
+        this.#laneExecutor.syncSkills(filteredSkills);
+    }
+    getContextDegradationSnapshot(limit = 8) {
+        const ranked = [...this.#degradationCounts.entries()]
+            .filter(([, count]) => count > 0)
+            .sort((a, b) => b[1] - a[1]);
+        const sessions = ranked.slice(0, Math.max(1, limit)).map(([sessionId, consecutiveDegradation]) => ({
+            sessionId,
+            consecutiveDegradation,
+        }));
+        return {
+            degradedSessions: ranked.length,
+            maxConsecutiveDegradation: ranked[0]?.[1] ?? 0,
+            sessions,
+        };
+    }
+    resetContextDegradation(sessionId) {
+        if (sessionId) {
+            this.#degradationCounts.delete(sessionId);
+            return;
+        }
+        this.#degradationCounts.clear();
+    }
+    async processMessage(message) {
+        const normalizedText = message.text?.trim();
+        if (!normalizedText) {
+            return 'I could not find any text content to process.';
+        }
+        const sessionId = `${message.platform}:${message.senderId}`;
+        return this.processText(sessionId, normalizedText);
+    }
+    async processText(sessionId, text) {
+        const normalizedText = text.trim();
+        if (!normalizedText) {
+            return 'Please provide a non-empty prompt.';
+        }
+        createSession(sessionId);
+        const historyRows = getSessionMessages(sessionId);
+        const conversationHistory = toConversationHistory(historyRows);
+        const historyPlan = this.#contextLifecycle.planHistoryWindow(conversationHistory);
+        await this.#persistTurn(sessionId, 'user', normalizedText);
+        const memoryRetrieval = await retrieveEvidenceAwareMemoryContext(sessionId, normalizedText, historyPlan.memoryTopK);
+        const memoryContext = memoryRetrieval.context;
+        const delegationContext = await this.#runDelegationIfNeeded(sessionId, normalizedText, historyPlan.hotHistory, memoryContext);
+        const runtimePlan = this.#contextLifecycle.planRuntimeContext({
+            memoryContext,
+            delegationContext,
+            warmSummary: historyPlan.warmSummary,
+            archivedSummary: historyPlan.archivedSummary,
+        });
+        const systemPrompt = await assembleContext(runtimePlan.runtimeContext);
+        const compactSystemPrompt = this.#contextLifecycle.compactSystemPrompt(systemPrompt);
+        this.#recordContextBudgetDiagnostics(sessionId, historyPlan, runtimePlan, compactSystemPrompt, memoryRetrieval.diagnostics);
+        const messages = [
+            { role: 'system', content: compactSystemPrompt.content },
+            ...historyPlan.hotHistory,
+            { role: 'user', content: normalizedText },
+        ];
+        return this.#runConversationLoop(sessionId, messages);
+    }
+    async #runConversationLoop(sessionId, messages) {
+        // Refresh tools at the start of each loop to catch newly connected MCP servers
+        this.refreshTools();
+        let previousToolCallSignature = null;
+        let repeatedToolCallCount = 0;
+        for (let round = 0; round < this.#maxToolRounds; round++) {
+            const assistantMessage = (await this.#router.createChatCompletion(messages, this.#tools, { sessionId }));
+            const assistantContent = assistantMessage.content ?? '';
+            messages.push({
+                role: 'assistant',
+                content: assistantContent,
+                tool_calls: assistantMessage.tool_calls,
+            });
+            await this.#persistTurn(sessionId, 'assistant', assistantContent || '[assistant returned tool calls without text content]');
+            if (!assistantMessage.tool_calls || assistantMessage.tool_calls.length === 0) {
+                return assistantContent || 'Done.';
+            }
+            const toolSignature = this.#buildToolCallSignature(assistantMessage.tool_calls);
+            if (toolSignature === previousToolCallSignature) {
+                repeatedToolCallCount += 1;
+            }
+            else {
+                previousToolCallSignature = toolSignature;
+                repeatedToolCallCount = 1;
+            }
+            if (repeatedToolCallCount >= this.#identicalToolCallLimit) {
+                const diagnostic = `Tool-call loop guard triggered after ${repeatedToolCallCount} repeated identical ` +
+                    `tool batches. Last signature: ${toolSignature}`;
+                await this.#persistTurn(sessionId, 'tool', diagnostic);
+                return `${diagnostic}. Stopping execution to prevent an infinite loop.`;
+            }
+            const toolResults = await this.#laneExecutor.executeToolCalls(assistantMessage, sessionId, this.#policyEngine);
+            for (const toolMessage of toolResults) {
+                messages.push(toolMessage);
+                await this.#persistTurn(sessionId, 'tool', toolMessage.content ?? '');
+            }
+        }
+        return `Stopped after ${this.#maxToolRounds} tool-execution rounds without a final text response.`;
+    }
+    async #persistTurn(sessionId, role, content) {
+        saveMessage(randomUUID(), sessionId, role, content);
+        if (role !== 'tool') {
+            await indexConversationTurn(sessionId, role, content);
+        }
+    }
+    #recordContextBudgetDiagnostics(sessionId, historyPlan, runtimePlan, systemPromptSection, retrievalDiagnostics) {
+        const degraded = historyPlan.stats.wasCompacted ||
+            runtimePlan.stats.wasCompacted ||
+            systemPromptSection.wasCompacted ||
+            systemPromptSection.wasOmitted;
+        const previousCount = this.#degradationCounts.get(sessionId) ?? 0;
+        const nextCount = degraded ? previousCount + 1 : 0;
+        this.#degradationCounts.set(sessionId, nextCount);
+        const diagnostics = [
+            ...retrievalDiagnostics,
+            ...historyPlan.diagnostics,
+            ...runtimePlan.diagnostics,
+            systemPromptSection.note ?? '',
+        ]
+            .filter(Boolean)
+            .join(' | ');
+        const alertMessage = degraded && nextCount >= 3
+            ? ` ALERT: sustained context degradation detected for ${nextCount} consecutive turn(s).`
+            : '';
+        const report = `[ContextBudget] session=${sessionId} ` +
+            `history hot/warm/archived=${historyPlan.stats.hotMessages}/${historyPlan.stats.warmMessages}/${historyPlan.stats.archivedMessages} ` +
+            `memoryTopK=${historyPlan.memoryTopK} ` +
+            `runtimeTokens(memory/delegation/warm/archive)=${runtimePlan.stats.memoryTokens}/${runtimePlan.stats.delegationTokens}/${runtimePlan.stats.warmTokens}/${runtimePlan.stats.archivedTokens} ` +
+            `systemTokens=${systemPromptSection.usedTokens}/${this.#contextLifecycle.config.systemBudgetTokens}. ` +
+            `${diagnostics}${alertMessage}`;
+        void logThought(report.trim());
+    }
+    async #runDelegationIfNeeded(sessionId, userText, history, memoryContext) {
+        if (!this.#enableDelegation) {
+            return '';
+        }
+        const request = this.#planDelegationRequest(sessionId, userText, history, memoryContext);
+        if (!request) {
+            return '';
+        }
+        try {
+            const result = await this.#orchestration.runDelegation(request, async ({ request: delegationRequest, job, signal }) => this.#executeDelegatedJob(delegationRequest, job, signal));
+            const report = `Delegation report\n${result.summary}`;
+            await this.#persistTurn(sessionId, 'tool', report);
+            return report;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const degraded = `Delegation failed and was skipped: ${message}`;
+            await this.#persistTurn(sessionId, 'tool', degraded);
+            return degraded;
+        }
+    }
+    #planDelegationRequest(sessionId, userText, history, memoryContext) {
+        const complexityScore = this.#scorePromptComplexity(userText);
+        if (complexityScore < this.#delegationMinScore) {
+            return null;
+        }
+        const recentMessages = history
+            .slice(-6)
+            .filter((message) => isConversationRole(message.role))
+            .map((message) => ({
+            role: message.role,
+            content: message.content ?? '',
+        }));
+        const recentConversationBlock = recentMessages
+            .map((message, index) => `${index + 1}. ${message.role.toUpperCase()}: ${message.content}`)
+            .join('\n');
+        const scopedContextParts = [
+            memoryContext ? `Retrieved memory context:\n${memoryContext}` : '',
+            recentConversationBlock ? `Recent conversation:\n${recentConversationBlock}` : '',
+        ].filter(Boolean);
+        const scopedContext = scopedContextParts.join('\n\n');
+        const briefs = [
+            {
+                id: 'decompose',
+                dependsOn: [],
+                title: 'Problem decomposition',
+                objective: 'Break down the parent request into the smallest reliable execution steps and identify critical dependencies.',
+                scopedContext,
+                expectedOutput: 'Return concise numbered steps and explicitly call out blockers or unknowns.',
+                constraints: {
+                    toolBudget: 0,
+                    timeoutMs: 12_000,
+                    maxTurns: 1,
+                },
+            },
+            {
+                id: 'risk-analysis',
+                dependsOn: ['decompose'],
+                title: 'Failure modes and safeguards',
+                objective: 'Identify likely failure paths, edge cases, and reliability safeguards needed before execution.',
+                scopedContext,
+                expectedOutput: 'Return bullet points grouped into risks, mitigations, and monitoring signals.',
+                constraints: {
+                    toolBudget: 0,
+                    timeoutMs: 12_000,
+                    maxTurns: 1,
+                },
+            },
+        ];
+        if (userText.length > 420) {
+            briefs.push({
+                id: 'synthesis',
+                dependsOn: ['decompose', 'risk-analysis'],
+                title: 'Integration synthesis',
+                objective: 'Produce a merged implementation outline balancing speed, correctness, and rollback safety.',
+                scopedContext,
+                expectedOutput: 'Return a practical execution sequence with explicit checkpoints and fallback behavior.',
+                constraints: {
+                    toolBudget: 0,
+                    timeoutMs: 14_000,
+                    maxTurns: 1,
+                },
+            });
+        }
+        return {
+            sessionId,
+            parentMessage: userText,
+            scope: {
+                sessionId,
+                memoryContext,
+                recentMessages,
+            },
+            briefs,
+        };
+    }
+    #scorePromptComplexity(prompt) {
+        const lower = prompt.toLowerCase();
+        const tokenCount = prompt.split(/\s+/).filter(Boolean).length;
+        let score = 0;
+        if (tokenCount >= 55) {
+            score += 1;
+        }
+        if (/\b(and|then|after that|while)\b/.test(lower)) {
+            score += 1;
+        }
+        for (const keyword of DELEGATION_KEYWORDS) {
+            if (lower.includes(keyword)) {
+                score += 1;
+            }
+        }
+        return score;
+    }
+    async #executeDelegatedJob(request, job, signal) {
+        if (signal.aborted) {
+            throw new Error(`Delegated job '${job.id}' was cancelled before execution.`);
+        }
+        const scopedMessages = request.scope.recentMessages
+            .map((item, index) => `${index + 1}. ${item.role.toUpperCase()}: ${item.content}`)
+            .join('\n');
+        const systemPrompt = [
+            'You are a focused TwinBot sub-agent.',
+            'Do not ask follow-up questions.',
+            'Do not invoke tools.',
+            `Expected output contract: ${job.brief.expectedOutput}`,
+        ].join('\n');
+        const userPrompt = [
+            `Parent objective: ${request.parentMessage}`,
+            `Delegated brief: ${job.brief.title}`,
+            `Sub-task objective: ${job.brief.objective}`,
+            `Scoped context:\n${job.brief.scopedContext}`,
+            scopedMessages ? `Scoped message history:\n${scopedMessages}` : '',
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+        const response = (await this.#router.createChatCompletion([
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: userPrompt },
+        ], undefined, { sessionId: request.sessionId }));
+        if (signal.aborted) {
+            throw new Error(`Delegated job '${job.id}' was cancelled during execution.`);
+        }
+        const content = response.content?.trim();
+        if (!content) {
+            throw new Error(`Delegated job '${job.id}' returned empty content.`);
+        }
+        return content;
+    }
+}

package/dist/core/heartbeat.js

@@ -0,0 +1,54 @@
+import { JobScheduler } from '../services/job-scheduler.js';
+import { logThought } from '../utils/logger.js';
+import { getConfigValue } from '../config/config-loader.js';
+const DEFAULT_CRON = '0 9 * * *';
+const DEFAULT_MESSAGE = 'TwinBot heartbeat: daily proactive check-in.';
+const HEARTBEAT_JOB_ID = 'twinbot-heartbeat';
+/**
+ * Proactive heartbeat service.
+ *
+ * Now delegates to the centralized {@link JobScheduler} so heartbeat intervals
+ * are managed alongside other repeating background jobs. The external API
+ * remains identical to the original implementation for backward compatibility.
+ */
+export class HeartbeatService {
+    #scheduler;
+    #onHeartbeat;
+    #cronExpression;
+    #message;
+    /**
+     * @param onHeartbeat - callback invoked on every heartbeat tick.
+     * @param config      - optional cron and message overrides.
+     * @param scheduler   - optional external scheduler instance (for shared management).
+     *                      If omitted, a private scheduler is created internally.
+     */
+    constructor(onHeartbeat, config = {}, scheduler) {
+        this.#onHeartbeat = onHeartbeat;
+        this.#cronExpression = config.cronExpression ?? getConfigValue('HEARTBEAT_CRON') ?? DEFAULT_CRON;
+        this.#message = config.message ?? getConfigValue('HEARTBEAT_MESSAGE') ?? DEFAULT_MESSAGE;
+        this.#scheduler = scheduler ?? new JobScheduler();
+    }
+    /** Expose the underlying scheduler so callers can register additional jobs. */
+    get scheduler() {
+        return this.#scheduler;
+    }
+    start() {
+        // Guard against double-start
+        if (this.#scheduler.getJob(HEARTBEAT_JOB_ID)) {
+            return;
+        }
+        this.#scheduler.register({
+            id: HEARTBEAT_JOB_ID,
+            cronExpression: this.#cronExpression,
+            description: this.#message,
+            handler: async () => {
+                await logThought(`Heartbeat fired with schedule: ${this.#cronExpression}`);
+                await this.#onHeartbeat(this.#message);
+            },
+            autoStart: true,
+        });
+    }
+    stop() {
+        this.#scheduler.unregister(HEARTBEAT_JOB_ID);
+    }
+}