twinclaw 1.1.5 → 1.1.7

package/dist/api/handlers/agents.js

@@ -37,7 +37,7 @@ export function handleAgentsGet(deps) {
             id: agent.id,
             name: agent.name,
             model: agent.model,
-            systemPrompt: agent.systemPrompt,
+            hasSystemPrompt: Boolean(agent.systemPrompt && agent.systemPrompt.trim().length > 0),
             maxSteps: agent.maxSteps,
             timeoutMs: agent.timeoutMs,
             reportBackTo: agent.reportBackTo,

package/dist/api/handlers/browser.js

@@ -2,7 +2,18 @@ import { BrowserReferenceError } from '../../services/browser-service.js';
 import { sendOk, sendError, mapError } from '../shared.js';
 import { logThought } from '../../utils/logger.js';
 import path from 'node:path';
+import { isIP } from 'node:net';
+import { unlink } from 'node:fs/promises';
 const DEFAULT_BROWSER_ALLOWED_HOSTS = ['example.com'];
+const SNAPSHOT_CLEANUP_DELAY_MS = 5 * 60 * 1000;
+const BLOCKED_METADATA_HOSTS = new Set([
+    'metadata.google.internal',
+    'metadata.azure.internal',
+    'metadata',
+    '169.254.169.254',
+    '169.254.170.2',
+    '100.100.100.200',
+]);
 function resolveAllowedBrowserHosts() {
     const configured = (process.env.BROWSER_ALLOWED_HOSTS ?? '')
         .split(',')
@@ -24,21 +35,37 @@ function isPrivateIpv4(hostname) {
         a === 127 ||
         a === 0 ||
         (a === 169 && b === 254) ||
+        (a === 100 && b >= 64 && b <= 127) ||
         (a === 172 && b >= 16 && b <= 31) ||
         (a === 192 && b === 168));
 }
+function isBlockedIpv6(hostname) {
+    const normalized = hostname.toLowerCase();
+    if (normalized === '::1' || normalized === '::') {
+        return true;
+    }
+    if (normalized.startsWith('fe80:') || normalized.startsWith('fc') || normalized.startsWith('fd')) {
+        return true;
+    }
+    if (normalized.startsWith('::ffff:')) {
+        return isPrivateIpv4(normalized.slice('::ffff:'.length));
+    }
+    return false;
+}
 function isPrivateOrLocalHost(hostname) {
     const normalized = hostname.toLowerCase();
+    if (BLOCKED_METADATA_HOSTS.has(normalized)) {
+        return true;
+    }
     if (normalized === 'localhost' ||
         normalized.endsWith('.localhost') ||
-        normalized.endsWith('.local') ||
-        normalized === '::1' ||
-        normalized === '::' ||
-        normalized.startsWith('fe80:') ||
-        normalized.startsWith('fc') ||
-        normalized.startsWith('fd')) {
+        normalized.endsWith('.local')) {
         return true;
     }
+    const ipKind = isIP(normalized);
+    if (ipKind === 6) {
+        return isBlockedIpv6(normalized);
+    }
     return isPrivateIpv4(normalized);
 }
 function hostMatchesAllowRule(hostname, rule) {
@@ -56,7 +83,7 @@ function validateNavigationUrl(inputUrl) {
     try {
         parsed = new URL(inputUrl);
     }
-    catch {
+    catch (_error) {
         return { ok: false, status: 400, error: 'Field "url" must be a valid absolute URL.' };
     }
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
@@ -80,6 +107,18 @@ function validateNavigationUrl(inputUrl) {
     }
     return { ok: true, url: parsed.toString() };
 }
+function scheduleSnapshotCleanup(screenshotPath) {
+    const timeout = setTimeout(() => {
+        void unlink(screenshotPath).catch((error) => {
+            const fsError = error;
+            if (fsError.code !== 'ENOENT') {
+                const message = fsError instanceof Error ? fsError.message : String(fsError);
+                void logThought(`[API] Snapshot cleanup failed for ${screenshotPath}: ${message}`);
+            }
+        });
+    }, SNAPSHOT_CLEANUP_DELAY_MS);
+    timeout.unref();
+}
 /**
  * POST /browser/snapshot
  *
@@ -116,6 +155,7 @@ export function handleBrowserSnapshot(deps) {
             const result = await deps.browserService.takeScreenshotForVlm(screenshotPath, fullPage);
             const tree = await deps.browserService.getAccessibilityTree();
             const referenceContext = await deps.browserService.captureSnapshotReferenceContext();
+            scheduleSnapshotCleanup(result.path);
             const data = {
                 snapshotId: referenceContext.snapshotId,
                 screenshotPath: result.path,

package/dist/api/handlers/callback.js

@@ -1,6 +1,6 @@
 import { sendOk, sendError } from '../shared.js';
 import { logThought } from '../../utils/logger.js';
-import { recordCallbackReceipt, getCallbackReceipt, getDelivery, updateDeliveryState } from '../../services/db.js';
+import { recordCallbackReceipt, getCallbackReceipt, getDelivery, updateDeliveryState } from '../../services/db-delivery-callback.js';
 const MAX_SANITIZED_STRING_LENGTH = 512;
 const MAX_SANITIZED_ARRAY_ITEMS = 25;
 const MAX_SANITIZED_OBJECT_KEYS = 40;
@@ -107,8 +107,8 @@ export function handleWebhookCallback(deps) {
                 updateDeliveryState(body.taskId, newState, newState === 'sent' ? new Date().toISOString() : null);
                 await logThought(`[API] Webhook reconciled delivery queue item: ${body.taskId} -> ${newState}`);
             }
-            // Fire-and-forget: process the webhook payload as a conversation turn
-            void deps.gateway.processText(sessionId, summaryText);
+            const gatewayResult = await deps.gateway.processText(sessionId, summaryText);
+            await logThought(`[API] Webhook payload processed by gateway for task ${body.taskId} (responseLength=${gatewayResult.length}).`);
             recordCallbackReceipt(idempotencyKey, 202, 'accepted');
             const data = {
                 accepted: true,

package/dist/api/handlers/debug.js

@@ -45,25 +45,30 @@ export function handleDebug(deps) {
     };
 }
 async function getRecentLogs(limit) {
+    const dateIso = new Date().toISOString().slice(0, 10);
+    const logPath = path.resolve('memory', `${dateIso}.md`);
+    let content = '';
     try {
-        const dateIso = new Date().toISOString().slice(0, 10);
-        const logPath = path.resolve('memory', `${dateIso}.md`);
-        const content = await readFile(logPath, 'utf8').catch(() => '');
-        if (!content) {
+        content = await readFile(logPath, 'utf8');
+    }
+    catch (error) {
+        const fsError = error;
+        if (fsError.code === 'ENOENT') {
             return [];
         }
-        const sections = content.split(/\n## /).filter(Boolean);
-        return sections.slice(-limit).map((s) => {
-            const [header, ...bodyLines] = s.split('\n');
-            const [type, timestamp] = header.split(' @ ');
-            return {
-                timestamp: timestamp || new Date().toISOString(),
-                level: type.toUpperCase(),
-                message: bodyLines.join('\n').trim(),
-            };
-        }).reverse();
+        throw new Error(`Failed to read debug logs from ${logPath}: ${fsError.message}`);
     }
-    catch {
+    if (!content.trim()) {
         return [];
     }
+    const sections = content.split(/\n## /).filter(Boolean);
+    return sections.slice(-limit).map((s) => {
+        const [header, ...bodyLines] = s.split('\n');
+        const [type, timestamp] = header.split(' @ ');
+        return {
+            timestamp: timestamp || new Date().toISOString(),
+            level: type.toUpperCase(),
+            message: bodyLines.join('\n').trim(),
+        };
+    }).reverse();
 }

package/dist/api/handlers/devices.js

@@ -68,7 +68,8 @@ export function handleDevicesCommand(deps) {
                 });
             }
             else {
-                sendError(res, result.error || 'Command execution failed', 400);
+                const status = result.error && /not implemented/i.test(result.error) ? 501 : 400;
+                sendError(res, result.error || 'Command execution failed', status);
             }
         }
         catch (err) {

package/dist/api/handlers/health-data.js

@@ -0,0 +1,87 @@
+import { getSecretVaultService } from '../../services/secret-vault.js';
+export async function buildHealthData(deps, startTimeMs) {
+    const summary = deps.skillRegistry.summary();
+    const servers = deps.mcpManager.listServers();
+    const packageDiagnostics = await deps.mcpManager.getSkillPackageDiagnostics();
+    const secretDiagnostics = getSecretVaultService().getDiagnostics(['API_SECRET']);
+    const budgetSnapshot = deps.budgetGovernor?.getSnapshot('health');
+    const routingSnapshot = deps.modelRouter?.getHealthSnapshot();
+    const backupDiagnostics = deps.localStateBackup
+        ? await deps.localStateBackup.getDiagnostics(5)
+        : null;
+    const heartbeatRunning = deps.heartbeat.scheduler
+        .listJobs()
+        .some((j) => j.status === 'running');
+    return {
+        status: servers.some((s) => s.state === 'error') ||
+            packageDiagnostics.blockedPackageCount > 0 ||
+            secretDiagnostics.health.hasIssues ||
+            budgetSnapshot?.directive.severity === 'hard_limit' ||
+            (routingSnapshot?.consecutiveFailures ?? 0) >= 3 ||
+            backupDiagnostics?.status === 'degraded'
+            ? 'degraded'
+            : 'ok',
+        uptimeSec: Math.floor((Date.now() - startTimeMs) / 1000),
+        memoryUsageMb: Math.round(process.memoryUsage().rss / 1024 / 1024),
+        heartbeat: { running: heartbeatRunning },
+        skills: {
+            builtin: summary.builtin ?? 0,
+            mcp: summary.mcp ?? 0,
+            total: deps.skillRegistry.size,
+        },
+        skillPackages: {
+            installed: packageDiagnostics.installed.length,
+            active: packageDiagnostics.activePackageCount,
+            blocked: packageDiagnostics.blockedPackageCount,
+            warnings: packageDiagnostics.warnings,
+            violations: packageDiagnostics.violations.map((violation) => ({
+                packageName: violation.packageName,
+                version: violation.version,
+                code: violation.code,
+                message: violation.message,
+                remediation: violation.remediation,
+            })),
+        },
+        secrets: {
+            status: secretDiagnostics.health.hasIssues ? 'degraded' : 'ok',
+            missingRequired: secretDiagnostics.health.missingRequired,
+            expired: secretDiagnostics.health.expired,
+            warnings: secretDiagnostics.health.warnings,
+            total: secretDiagnostics.total,
+            active: secretDiagnostics.active,
+            dueForRotation: secretDiagnostics.dueForRotation,
+        },
+        budget: budgetSnapshot
+            ? {
+                severity: budgetSnapshot.directive.severity,
+                profile: budgetSnapshot.directive.profile,
+                pacingDelayMs: budgetSnapshot.directive.pacingDelayMs,
+                manualProfile: budgetSnapshot.manualProfile,
+                daily: budgetSnapshot.daily,
+                session: budgetSnapshot.session,
+                providers: budgetSnapshot.providers,
+            }
+            : undefined,
+        routing: routingSnapshot,
+        backups: backupDiagnostics
+            ? {
+                status: backupDiagnostics.status,
+                lastSnapshotAt: backupDiagnostics.lastSnapshotAt,
+                lastRestoreAt: backupDiagnostics.lastRestoreAt,
+                validationFailureCount: backupDiagnostics.validationFailureCount,
+                recommendationCount: backupDiagnostics.recommendations.length,
+            }
+            : undefined,
+        mcpServers: servers.map((s) => ({
+            id: s.id,
+            name: s.name,
+            state: s.state,
+            toolCount: s.toolCount,
+            health: {
+                circuit: s.health.state,
+                failureCount: s.health.metrics.failureCount,
+                remainingCooldownMs: s.health.remainingCooldownMs,
+            },
+        })),
+    };
+}

package/dist/api/handlers/health.js

@@ -1,93 +1,11 @@
 import { getSecretVaultService } from '../../services/secret-vault.js';
 import { sendOk } from '../shared.js';
+import { buildHealthData } from './health-data.js';
 const startTime = Date.now();
 /** GET /health — Returns system health status and subsystem summaries. */
 export function handleHealth(deps) {
     return async (_req, res) => {
-        const summary = deps.skillRegistry.summary();
-        const servers = deps.mcpManager.listServers();
-        const packageDiagnostics = await deps.mcpManager.getSkillPackageDiagnostics();
-        const secretDiagnostics = getSecretVaultService().getDiagnostics(['API_SECRET']);
-        const budgetSnapshot = deps.budgetGovernor?.getSnapshot('health');
-        const routingSnapshot = deps.modelRouter?.getHealthSnapshot();
-        const backupDiagnostics = deps.localStateBackup
-            ? await deps.localStateBackup.getDiagnostics(5)
-            : null;
-        const heartbeatRunning = deps.heartbeat.scheduler
-            .listJobs()
-            .some((j) => j.status === 'running');
-        const data = {
-            status: servers.some((s) => s.state === 'error') ||
-                packageDiagnostics.blockedPackageCount > 0 ||
-                secretDiagnostics.health.hasIssues ||
-                budgetSnapshot?.directive.severity === 'hard_limit' ||
-                (routingSnapshot?.consecutiveFailures ?? 0) >= 3 ||
-                backupDiagnostics?.status === 'degraded'
-                ? 'degraded'
-                : 'ok',
-            uptimeSec: Math.floor((Date.now() - startTime) / 1000),
-            memoryUsageMb: Math.round(process.memoryUsage().rss / 1024 / 1024),
-            heartbeat: { running: heartbeatRunning },
-            skills: {
-                builtin: summary.builtin ?? 0,
-                mcp: summary.mcp ?? 0,
-                total: deps.skillRegistry.size,
-            },
-            skillPackages: {
-                installed: packageDiagnostics.installed.length,
-                active: packageDiagnostics.activePackageCount,
-                blocked: packageDiagnostics.blockedPackageCount,
-                warnings: packageDiagnostics.warnings,
-                violations: packageDiagnostics.violations.map((violation) => ({
-                    packageName: violation.packageName,
-                    version: violation.version,
-                    code: violation.code,
-                    message: violation.message,
-                    remediation: violation.remediation,
-                })),
-            },
-            secrets: {
-                status: secretDiagnostics.health.hasIssues ? 'degraded' : 'ok',
-                missingRequired: secretDiagnostics.health.missingRequired,
-                expired: secretDiagnostics.health.expired,
-                warnings: secretDiagnostics.health.warnings,
-                total: secretDiagnostics.total,
-                active: secretDiagnostics.active,
-                dueForRotation: secretDiagnostics.dueForRotation,
-            },
-            budget: budgetSnapshot
-                ? {
-                    severity: budgetSnapshot.directive.severity,
-                    profile: budgetSnapshot.directive.profile,
-                    pacingDelayMs: budgetSnapshot.directive.pacingDelayMs,
-                    manualProfile: budgetSnapshot.manualProfile,
-                    daily: budgetSnapshot.daily,
-                    session: budgetSnapshot.session,
-                    providers: budgetSnapshot.providers,
-                }
-                : undefined,
-            routing: routingSnapshot,
-            backups: backupDiagnostics
-                ? {
-                    status: backupDiagnostics.status,
-                    lastSnapshotAt: backupDiagnostics.lastSnapshotAt,
-                    lastRestoreAt: backupDiagnostics.lastRestoreAt,
-                    validationFailureCount: backupDiagnostics.validationFailureCount,
-                    recommendationCount: backupDiagnostics.recommendations.length,
-                }
-                : undefined,
-            mcpServers: servers.map((s) => ({
-                id: s.id,
-                name: s.name,
-                state: s.state,
-                toolCount: s.toolCount,
-                health: {
-                    circuit: s.health.state,
-                    failureCount: s.health.metrics.failureCount,
-                    remainingCooldownMs: s.health.remainingCooldownMs,
-                },
-            })),
-        };
+        const data = await buildHealthData(deps, startTime);
         sendOk(res, data);
     };
 }

package/dist/api/handlers/self-routes.js

@@ -0,0 +1,144 @@
+import { sendError, sendOk } from '../shared.js';
+import { getLearningSystem } from '../../services/learning-system.js';
+import { getSkillBuilder } from '../../services/skill-builder.js';
+import { getAutoConfigurer } from '../../services/auto-configurer.js';
+import { getSelfHealingService } from '../../services/self-healing.js';
+import { getAgentImprovementTool } from '../../tools/agent-improvement.js';
+export function registerSelfRoutes(app) {
+    app.get('/self/stats', (_req, res) => {
+        try {
+            const learning = getLearningSystem();
+            const stats = learning.getStats();
+            sendOk(res, stats);
+        }
+        catch (err) {
+            sendError(res, `Failed to get stats: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    app.get('/self/health', async (_req, res) => {
+        try {
+            const healer = getSelfHealingService();
+            const metrics = await healer.performHealthCheck();
+            sendOk(res, { metrics });
+        }
+        catch (err) {
+            sendError(res, `Health check failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    app.get('/self/learn', (req, res) => {
+        const query = typeof req.query.q === 'string' ? req.query.q : '';
+        if (!query) {
+            sendError(res, 'Query parameter "q" is required.', 400);
+            return;
+        }
+        try {
+            const learning = getLearningSystem();
+            const result = learning.query(query);
+            sendOk(res, result);
+        }
+        catch (err) {
+            sendError(res, `Query failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    app.post('/self/learn', async (req, res) => {
+        const { pattern, solution, type } = req.body ?? {};
+        if (!pattern || !solution) {
+            sendError(res, 'Required fields: pattern, solution', 400);
+            return;
+        }
+        try {
+            let entryType = 'fix';
+            if (type === 'success' ||
+                type === 'failure' ||
+                type === 'pattern' ||
+                type === 'fix' ||
+                type === 'config') {
+                entryType = type;
+            }
+            const learning = getLearningSystem();
+            await learning.learn(entryType, pattern, {}, solution, 'success');
+            sendOk(res, { message: `Learned: ${pattern} -> ${solution}` });
+        }
+        catch (err) {
+            sendError(res, `Learn failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    app.get('/self/services', (_req, res) => {
+        try {
+            const configurer = getAutoConfigurer();
+            const services = configurer.listKnownServices();
+            sendOk(res, { services });
+        }
+        catch (err) {
+            sendError(res, `Failed to list services: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    app.get('/self/configure/:service', async (req, res) => {
+        const service = req.params.service;
+        try {
+            const configurer = getAutoConfigurer();
+            const { config, steps } = await configurer.fetchDocsAndConfig(service);
+            sendOk(res, { service, config, steps });
+        }
+        catch (err) {
+            sendError(res, `Configure failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    app.post('/self/configure/:service', async (req, res) => {
+        const service = req.params.service;
+        const config = req.body;
+        try {
+            const configurer = getAutoConfigurer();
+            const result = await configurer.saveServiceConfig(service, config);
+            sendOk(res, result);
+        }
+        catch (err) {
+            sendError(res, `Save config failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    app.post('/self/build-skill', async (req, res) => {
+        const { description, purpose } = req.body ?? {};
+        if (!description) {
+            sendError(res, 'Required field: description', 400);
+            return;
+        }
+        try {
+            const builder = getSkillBuilder();
+            const skill = await builder.buildFromRequest({ description, purpose });
+            sendOk(res, {
+                id: skill.id,
+                name: skill.name,
+                category: skill.category,
+                location: `${builder.getCustomSkillsDir()}/${skill.id}.ts`,
+            });
+        }
+        catch (err) {
+            sendError(res, `Build skill failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    app.get('/self/skills', (_req, res) => {
+        try {
+            const builder = getSkillBuilder();
+            const skills = builder.getCustomSkills();
+            sendOk(res, { skills });
+        }
+        catch (err) {
+            sendError(res, `Failed to list skills: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    app.post('/self/improve', async (req, res) => {
+        const { goal, context } = req.body ?? {};
+        if (!goal) {
+            sendError(res, 'Required field: goal', 400);
+            return;
+        }
+        try {
+            const tool = getAgentImprovementTool();
+            const result = await tool.handleImprovementRequest({ goal, context });
+            sendOk(res, result);
+        }
+        catch (err) {
+            sendError(res, `Improve request failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+}

package/dist/api/handlers/skill-acquisition-routes.js

@@ -0,0 +1,90 @@
+import { sendError, sendOk } from '../shared.js';
+import { getSkillBuilder } from '../../services/skill-builder.js';
+import { getIntentParser } from '../../services/skill-acquisition/intent-parser.js';
+import { getResearchEngine } from '../../services/skill-acquisition/research-engine.js';
+export function registerSkillAcquisitionRoutes(app) {
+    // POST /api/skills/acquire - Start acquiring a new skill
+    app.post('/skills/acquire', async (req, res) => {
+        const { request } = req.body ?? {};
+        if (!request) {
+            sendError(res, 'Required field: request (natural language description)', 400);
+            return;
+        }
+        try {
+            const intentParser = getIntentParser();
+            const intent = await intentParser.parseIntent(request);
+            const researchEngine = getResearchEngine();
+            const research = await researchEngine.research(intent);
+            const skillBuilder = getSkillBuilder();
+            const skill = await skillBuilder.buildFromRequest({
+                description: request,
+                purpose: 'user requested',
+            });
+            sendOk(res, {
+                status: 'generated',
+                intent,
+                research,
+                skill: {
+                    id: skill.id,
+                    name: skill.name,
+                    description: skill.description,
+                    category: skill.category,
+                },
+                nextSteps: [
+                    'Review the generated skill',
+                    'Provide credentials if needed',
+                    'Approve to activate the skill',
+                ],
+            });
+        }
+        catch (err) {
+            sendError(res, `Skill acquisition failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    // GET /api/skills - List all custom skills
+    app.get('/skills', (_req, res) => {
+        try {
+            const builder = getSkillBuilder();
+            const customSkills = builder.getCustomSkills();
+            sendOk(res, {
+                customSkills,
+                total: customSkills.length,
+            });
+        }
+        catch (err) {
+            sendError(res, `Failed to list skills: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    // GET /api/skills/:id - Get skill details
+    app.get('/skills/:id', (req, res) => {
+        const { id } = req.params;
+        try {
+            const builder = getSkillBuilder();
+            const skill = builder.getSkill(id);
+            if (!skill) {
+                sendError(res, 'Skill not found', 404);
+                return;
+            }
+            sendOk(res, skill);
+        }
+        catch (err) {
+            sendError(res, `Failed to get skill: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    // DELETE /api/skills/:id - Delete a custom skill
+    app.delete('/skills/:id', async (req, res) => {
+        const { id } = req.params;
+        try {
+            const builder = getSkillBuilder();
+            const deleted = await builder.deleteSkill(id);
+            if (!deleted) {
+                sendError(res, 'Skill not found or could not be deleted', 404);
+                return;
+            }
+            sendOk(res, { message: 'Skill deleted successfully' });
+        }
+        catch (err) {
+            sendError(res, `Failed to delete skill: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+}