twinclaw 1.0.0

package/dist/services/policy-engine.js

@@ -0,0 +1,92 @@
+export class PolicyEngine {
+    globalProfile;
+    sessionOverrides = new Map();
+    // Optional hook for logging all policy decisions
+    onDecision;
+    constructor(globalProfile) {
+        this.globalProfile = globalProfile ?? {
+            id: 'global-default',
+            defaultAction: 'allow', // By default TwinBot allows if no rule matches
+            rules: [],
+        };
+    }
+    setGlobalProfile(profile) {
+        this.globalProfile = profile;
+    }
+    setSessionOverride(sessionId, profile) {
+        this.sessionOverrides.set(sessionId, profile);
+    }
+    removeSessionOverride(sessionId) {
+        this.sessionOverrides.delete(sessionId);
+    }
+    getSessionOverride(sessionId) {
+        return this.sessionOverrides.get(sessionId);
+    }
+    /**
+     * Evaluates the policy for a given tool execution.
+     * Deterministically orders checks: Session Override rules -> Session Default -> Global Rules -> Global Default.
+     */
+    evaluate(sessionId, skillName) {
+        const sessionProfile = this.sessionOverrides.get(sessionId);
+        // 1. Session Override rules
+        if (sessionProfile) {
+            const ruleMatch = this.#findRuleMatch(sessionProfile, skillName);
+            if (ruleMatch) {
+                return this.#finalizeDecision(sessionId, {
+                    action: ruleMatch.action,
+                    reason: ruleMatch.reason ?? `Matched specific override rule in profile '${sessionProfile.id}'`,
+                    skillName,
+                    profileId: sessionProfile.id,
+                });
+            }
+            // 2. Session Profile default (if not fallback)
+            if (sessionProfile.defaultAction !== 'fallback') {
+                return this.#finalizeDecision(sessionId, {
+                    action: sessionProfile.defaultAction,
+                    reason: `Fell back to default action in profile '${sessionProfile.id}'`,
+                    skillName,
+                    profileId: sessionProfile.id,
+                });
+            }
+        }
+        // 3. Global Profile rules
+        const globalRuleMatch = this.#findRuleMatch(this.globalProfile, skillName);
+        if (globalRuleMatch) {
+            return this.#finalizeDecision(sessionId, {
+                action: globalRuleMatch.action,
+                reason: globalRuleMatch.reason ?? `Matched specific rule in global profile '${this.globalProfile.id}'`,
+                skillName,
+                profileId: this.globalProfile.id,
+            });
+        }
+        // 4. Global Default action
+        return this.#finalizeDecision(sessionId, {
+            action: this.globalProfile.defaultAction === 'fallback' ? 'allow' : this.globalProfile.defaultAction,
+            reason: `Fell back to global default action in profile '${this.globalProfile.id}'`,
+            skillName,
+            profileId: this.globalProfile.id,
+        });
+    }
+    #findRuleMatch(profile, skillName) {
+        // Exact match first
+        const exact = profile.rules.find((r) => r.skillName === skillName);
+        if (exact)
+            return exact;
+        // Wildcard match
+        const wildcard = profile.rules.find((r) => r.skillName === '*');
+        if (wildcard)
+            return wildcard;
+        return undefined;
+    }
+    #finalizeDecision(sessionId, decision) {
+        if (this.onDecision) {
+            try {
+                this.onDecision(sessionId, decision);
+            }
+            catch (e) {
+                console.error(`[PolicyEngine] Error in decision reporting hook:`, e);
+            }
+        }
+        return decision;
+    }
+}

package/dist/services/proactive-notifier.js

@@ -0,0 +1,94 @@
+import { logThought } from '../utils/logger.js';
+/**
+ * Manages proactive (agent-initiated) outbound notifications.
+ *
+ * Acts as the bridge between background event sources (scheduler, file watcher)
+ * and the dispatcher's outbound delivery. The notifier decides *what* to say,
+ * and the dispatcher decides *how* to send it.
+ *
+ * Usage:
+ * ```ts
+ * const notifier = new ProactiveNotifier(sendFn, defaultTarget);
+ * scheduler.on('job:error', (e) => notifier.onSchedulerEvent(e));
+ * fileWatcher.onEvent((e) => notifier.onFileEvent(e));
+ * ```
+ */
+export class ProactiveNotifier {
+    #send;
+    #defaultTarget;
+    #enabled;
+    constructor(send, defaultTarget, enabled = true) {
+        this.#send = send;
+        this.#defaultTarget = defaultTarget;
+        this.#enabled = enabled;
+    }
+    /** Enable or disable proactive notifications at runtime. */
+    setEnabled(value) {
+        this.#enabled = value;
+    }
+    get enabled() {
+        return this.#enabled;
+    }
+    /**
+     * Handle a scheduler event. Only job errors trigger proactive alerts.
+     * Job starts/completions are logged but not dispatched to the user.
+     */
+    async onSchedulerEvent(event) {
+        if (!this.#enabled)
+            return;
+        switch (event.type) {
+            case 'job:error': {
+                const message = `⚠️ **Background Job Failed**\n` +
+                    `Job: \`${event.jobId}\`\n` +
+                    `Error: ${event.error ?? 'Unknown error'}\n` +
+                    `Time: ${event.timestamp.toISOString()}`;
+                await this.#dispatch(message);
+                break;
+            }
+            case 'job:done': {
+                // Silently log — don't notify user for routine completions.
+                await logThought(`[ProactiveNotifier] Job '${event.jobId}' completed successfully.`);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    /**
+     * Handle a file-system event. Only file additions and changes are reported
+     * to avoid flooding the user with noise from deletions or directory events.
+     */
+    async onFileEvent(event) {
+        if (!this.#enabled)
+            return;
+        if (event.type !== 'add' && event.type !== 'change')
+            return;
+        const label = event.type === 'add' ? '📄 New File Detected' : '✏️ File Modified';
+        const message = `${label}\n` +
+            `Path: \`${event.path}\`\n` +
+            `Time: ${event.timestamp}`;
+        await this.#dispatch(message);
+    }
+    /**
+     * Send an arbitrary proactive message. This is the public API for
+     * any subsystem that needs to push an agent-initiated notification.
+     */
+    async notify(text, target) {
+        if (!this.#enabled)
+            return;
+        await this.#dispatch(text, target);
+    }
+    // ── Private Helpers ────────────────────────────────────────────────────────
+    async #dispatch(text, target) {
+        const destination = target ?? this.#defaultTarget;
+        try {
+            await logThought(`[ProactiveNotifier] Sending proactive message to ${destination.platform}:${destination.chatId}`);
+            await this.#send(destination, text);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error('[ProactiveNotifier] Failed to deliver proactive message:', message);
+            await logThought(`[ProactiveNotifier] Delivery failed: ${message}`);
+        }
+    }
+}

package/dist/services/queue-service.js

@@ -0,0 +1,146 @@
+import { randomUUID } from 'node:crypto';
+import { logThought } from '../utils/logger.js';
+import { enqueueDelivery, dequeueDeliveries, updateDeliveryState, updateDeliveryAttempts, recordDeliveryAttemptStart, recordDeliveryAttemptEnd, getDeliveryStateCounts, getDeadLetters, getDeliveryMetrics, } from './db.js';
+const DEFAULTS = {
+    maxAttempts: 3,
+    baseDelayMs: 1000,
+    backoffFactor: 2,
+    maxDelayMs: 15_000,
+    batchSize: 10,
+    pollIntervalCron: '*/2 * * * * *', // Every 2 seconds
+};
+/**
+ * Durable queue service for outbound message delivery.
+ */
+export class QueueService {
+    #dispatchFn;
+    #maxAttempts;
+    #baseDelayMs;
+    #backoffFactor;
+    #maxDelayMs;
+    #batchSize;
+    #scheduler;
+    #pollIntervalCron;
+    #processingMode = 'normal';
+    #retryWindowMultiplier = 1;
+    constructor(dispatchFn, scheduler, options = {}) {
+        this.#dispatchFn = dispatchFn;
+        this.#scheduler = scheduler;
+        this.#maxAttempts = options.maxAttempts ?? DEFAULTS.maxAttempts;
+        this.#baseDelayMs = options.baseDelayMs ?? DEFAULTS.baseDelayMs;
+        this.#backoffFactor = options.backoffFactor ?? DEFAULTS.backoffFactor;
+        this.#maxDelayMs = options.maxDelayMs ?? DEFAULTS.maxDelayMs;
+        this.#batchSize = options.batchSize ?? DEFAULTS.batchSize;
+        this.#pollIntervalCron = options.pollIntervalCron ?? DEFAULTS.pollIntervalCron;
+    }
+    start() {
+        this.#scheduler.register({
+            id: 'queue-processor',
+            cronExpression: this.#pollIntervalCron,
+            description: 'Process pending delivery queue items',
+            handler: async () => {
+                await this.processQueue();
+            },
+            autoStart: true,
+        });
+    }
+    stop() {
+        this.#scheduler.unregister('queue-processor');
+    }
+    enqueue(platform, chatId, textPayload) {
+        const id = randomUUID();
+        enqueueDelivery(id, platform, String(chatId), textPayload);
+        // Soft trigger for low latency
+        setTimeout(() => void this.processQueue(), 50);
+        return id;
+    }
+    async processQueue() {
+        const batch = dequeueDeliveries(this.#resolveBatchSize());
+        if (!batch || batch.length === 0)
+            return;
+        // Process all picked deliveries concurrently
+        await Promise.allSettled(batch.map((job) => this.#processJob(job)));
+    }
+    async #processJob(job) {
+        const attemptId = randomUUID();
+        const start = Date.now();
+        const startedAt = new Date(start).toISOString();
+        recordDeliveryAttemptStart(attemptId, job.id, job.attempts, startedAt);
+        let success = false;
+        let lastError = '';
+        try {
+            await this.#dispatchFn(job.platform, job.chat_id, job.text_payload);
+            success = true;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err.message : String(err);
+        }
+        const end = Date.now();
+        const completedAt = new Date(end).toISOString();
+        const durationMs = end - start;
+        recordDeliveryAttemptEnd(attemptId, completedAt, success ? null : lastError, durationMs);
+        if (success) {
+            updateDeliveryState(job.id, 'sent', completedAt);
+        }
+        else {
+            if (job.attempts >= this.#maxAttempts) {
+                updateDeliveryState(job.id, 'dead_letter', completedAt);
+                void logThought(`[QueueService] Message ${job.id} dead-lettered after ${job.attempts} attempts. Last error: ${lastError}`);
+            }
+            else {
+                const delayMs = Math.min(this.#baseDelayMs * this.#backoffFactor ** (job.attempts - 1) * this.#retryWindowMultiplier, this.#maxDelayMs);
+                const nextAttemptAt = new Date(Date.now() + delayMs).toISOString();
+                updateDeliveryAttempts(job.id, job.attempts, nextAttemptAt);
+                updateDeliveryState(job.id, 'failed', null);
+                void logThought(`[QueueService] Message ${job.id} failed attempt ${job.attempts}/${this.#maxAttempts}: ${lastError}. Retrying at ${nextAttemptAt}.`);
+            }
+        }
+    }
+    /** Requeue a dead letter for another set of attempts. */
+    requeueDeadLetter(id) {
+        const now = new Date().toISOString();
+        updateDeliveryAttempts(id, 0, now);
+        updateDeliveryState(id, 'queued', null);
+        void logThought(`[QueueService] Requeued dead-letter message ${id}.`);
+        setTimeout(() => void this.processQueue(), 50);
+    }
+    setProcessingMode(mode) {
+        this.#processingMode = mode;
+        void logThought(`[QueueService] Processing mode set to '${mode}'.`);
+    }
+    setRetryWindowMultiplier(multiplier) {
+        const clamped = Math.max(0.5, Math.min(6, Number.isFinite(multiplier) ? multiplier : 1));
+        this.#retryWindowMultiplier = clamped;
+        void logThought(`[QueueService] Retry window multiplier set to ${clamped}.`);
+    }
+    getRuntimeControls() {
+        return {
+            mode: this.#processingMode,
+            retryWindowMultiplier: this.#retryWindowMultiplier,
+        };
+    }
+    /** Expose stats for dashboard/metrics. */
+    getStats(limit = 50) {
+        const recent = getDeliveryMetrics(limit);
+        const counts = getDeliveryStateCounts();
+        const deadLetters = getDeadLetters();
+        return {
+            totalQueued: counts.queued ?? 0,
+            totalDispatching: counts.dispatching ?? 0,
+            totalSent: counts.sent ?? 0,
+            totalFailed: counts.failed ?? 0,
+            totalDeadLetters: counts.dead_letter ?? deadLetters.length,
+            recentRecords: recent,
+            deadLetterRecords: deadLetters.slice(0, limit),
+        };
+    }
+    #resolveBatchSize() {
+        if (this.#processingMode === 'throttled') {
+            return Math.max(1, Math.floor(this.#batchSize / 2));
+        }
+        if (this.#processingMode === 'drain') {
+            return Math.min(this.#batchSize * 2, 100);
+        }
+        return this.#batchSize;
+    }
+}