@ismaelsoilet/synapsejs 1.3.0 → 1.8.0

package/src/mcp/server.ts

@@ -8,9 +8,13 @@
 
 import {
   type AbortGateResult,
+  type ModelRouteResult,
   modulateReasoningEffort,
+  type NudgeGateResult,
   type ReasoningEffortResult,
+  routeModelTier,
   shouldAbortTrajectory,
+  shouldNudgeContinuation,
   type TestTriageResult,
   triageTestFailure,
   type VerificationResult,
@@ -28,6 +32,7 @@ import { type SliceTemplate, scaffoldCrud, scaffoldSlice } from '../compiler/sca
 import { checkSchemaDrift } from '../compiler/schema-drift';
 import { findSliceFiles, resolveSlicesDir } from '../compiler/slice-discovery';
 import { artifactDirectory, splitSlice, verifySplit, writeSplitArtifacts } from '../compiler/slice-splitter';
+import { SYNAPSE_VERSION } from '../version';
 
 interface JsonRpcRequest {
   jsonrpc: string;
@@ -90,7 +95,7 @@ export class SynapseMcpServer {
             },
             serverInfo: {
               name: 'synapse-mcp',
-              version: '1.2.0'
+              version: SYNAPSE_VERSION
             }
           }
         };
@@ -272,6 +277,51 @@ export class SynapseMcpServer {
                     }
                   }
                 }
+              },
+              {
+                name: 'synapse_triage_error',
+                description:
+                  'Triage an arbitrary test failure or execution error log using Jev System One to classify root causes (env_missing vs flaky_transient vs deep_logic) and avoid token waste',
+                inputSchema: {
+                  type: 'object',
+                  required: ['failureLog'],
+                  properties: {
+                    failureLog: {
+                      type: 'string',
+                      description: 'Error log, stack trace or terminal output to triage'
+                    }
+                  }
+                }
+              },
+              {
+                name: 'synapse_route_task',
+                description:
+                  'Semantically route a development task to the optimal model/reasoning tier via Jev System One',
+                inputSchema: {
+                  type: 'object',
+                  required: ['task'],
+                  properties: {
+                    task: {
+                      type: 'string',
+                      description: 'Description of the coding, refactoring, or diagnostic task'
+                    }
+                  }
+                }
+              },
+              {
+                name: 'synapse_evaluate_nudge',
+                description:
+                  'Evaluate whether an agent is prematurely stopping or needs a proactive nudge to continue verification',
+                inputSchema: {
+                  type: 'object',
+                  required: ['transcriptTail'],
+                  properties: {
+                    transcriptTail: {
+                      type: 'string',
+                      description: 'Recent transcript steps or conversation history tail'
+                    }
+                  }
+                }
               }
             ]
           }
@@ -597,6 +647,18 @@ export class SynapseMcpServer {
               sessionContextTokens
             });
             contentText = JSON.stringify(result, null, 2);
+          } else if (toolName === 'synapse_triage_error') {
+            const failureLog = String(args.failureLog || '');
+            const result: TestTriageResult = await triageTestFailure(failureLog);
+            contentText = JSON.stringify(result, null, 2);
+          } else if (toolName === 'synapse_route_task') {
+            const task = String(args.task || '');
+            const result: ModelRouteResult = await routeModelTier(task);
+            contentText = JSON.stringify(result, null, 2);
+          } else if (toolName === 'synapse_evaluate_nudge') {
+            const transcriptTail = String(args.transcriptTail || '');
+            const result: NudgeGateResult = await shouldNudgeContinuation(transcriptTail);
+            contentText = JSON.stringify(result, null, 2);
           } else {
             return {
               jsonrpc: '2.0',

package/src/runtime/discovery-rules.ts

@@ -13,7 +13,11 @@ export const WEBHOOK_SUFFIX = 'Webhook';
 export const LOADER_SUFFIX = 'Loader';
 export const SCHEMA_SUFFIX = 'Schema';
 export const META_SUFFIX = 'Meta';
+export const CACHE_SUFFIX = 'Cache';
+export const SOCKET_SUFFIX = 'Socket';
 export const SLICE_META_EXPORT = 'sliceMeta';
+export const SLICE_CACHE_EXPORT = 'sliceCache';
+export const SLICE_SOCKET_EXPORT = 'sliceSocket';
 export const SLICE_DDL_EXPORT = 'sliceSchema';
 export const SLICE_ORACLE_EXPORT = 'sliceTests';
 
@@ -21,7 +25,14 @@ export const SLICE_ORACLE_EXPORT = 'sliceTests';
 export const COMPONENT_SUFFIXES = ['Trigger', 'View', 'Form', 'Component'] as const;
 
 /** Everything the server side of a slice is built from. */
-export const SERVER_ROOT_SUFFIXES = [ACTION_SUFFIX, JOB_SUFFIX, WEBHOOK_SUFFIX, META_SUFFIX] as const;
+export const SERVER_ROOT_SUFFIXES = [
+  ACTION_SUFFIX,
+  JOB_SUFFIX,
+  WEBHOOK_SUFFIX,
+  META_SUFFIX,
+  CACHE_SUFFIX,
+  SOCKET_SUFFIX
+] as const;
 
 /** Test-only exports, dropped from both runtime bundles. */
 export const TEST_ONLY_EXPORTS = [SLICE_ORACLE_EXPORT] as const;
@@ -58,6 +69,14 @@ export function isMeta(name: string): boolean {
   return name === SLICE_META_EXPORT || name.endsWith(META_SUFFIX);
 }
 
+export function isCache(name: string): boolean {
+  return name === SLICE_CACHE_EXPORT || name.endsWith(CACHE_SUFFIX);
+}
+
+export function isSocket(name: string): boolean {
+  return name === SLICE_SOCKET_EXPORT || name.endsWith(SOCKET_SUFFIX);
+}
+
 export function isTestOnly(name: string): boolean {
   return hasSuffix(name, TEST_ONLY_EXPORTS);
 }

package/src/runtime/event-hub.ts

@@ -46,7 +46,12 @@ export class EventHub {
     let notified = 0;
     for (const listener of listeners) {
       try {
-        listener(data);
+        const result: unknown = listener(data);
+        if (result && typeof (result as { catch?: unknown }).catch === 'function') {
+          (result as { catch: (fn: (err: unknown) => void) => void }).catch((err: unknown) => {
+            console.error(`[EventHub] Erro assíncrono no listener do tópico "${topic}":`, err);
+          });
+        }
         notified++;
       } catch (err) {
         console.error(`[EventHub] Erro no listener do tópico "${topic}":`, err);

package/src/runtime/network-guard.ts

@@ -0,0 +1,180 @@
+import dns from 'node:dns';
+import net from 'node:net';
+
+/**
+ * Checks whether an IP address (IPv4 or IPv6) belongs to a private, loopback,
+ * link-local, or cloud-provider metadata address space.
+ */
+export function isPrivateOrReservedIp(ip: string): boolean {
+  const version = net.isIP(ip);
+  if (version === 0) {
+    return false;
+  }
+
+  if (version === 4) {
+    const parts = ip.split('.').map((p) => parseInt(p, 10));
+    if (parts.length !== 4 || parts.some(Number.isNaN)) return true;
+
+    const [a, b] = parts;
+
+    // 0.0.0.0/8 (Broadcast/Current network)
+    if (a === 0) return true;
+
+    // 10.0.0.0/8 (Private)
+    if (a === 10) return true;
+
+    // 100.64.0.0/10 (Carrier-grade NAT)
+    if (a === 100 && b >= 64 && b <= 127) return true;
+
+    // 127.0.0.0/8 (Loopback)
+    if (a === 127) return true;
+
+    // 169.254.0.0/16 (Link-local & Cloud Metadata: AWS, GCP, Azure, DO)
+    if (a === 169 && b === 254) return true;
+
+    // 172.16.0.0/12 (Private)
+    if (a === 172 && b >= 16 && b <= 31) return true;
+
+    // 192.0.0.0/24 (IETF Protocol Assignments)
+    // 192.0.2.0/24 (TEST-NET-1)
+    if (a === 192 && b === 0) return true;
+
+    // 192.168.0.0/16 (Private)
+    if (a === 192 && b === 168) return true;
+
+    // 198.18.0.0/15 (Benchmarking)
+    if (a === 198 && (b === 18 || b === 19)) return true;
+
+    // 198.51.100.0/24 (TEST-NET-2)
+    if (a === 198 && b === 51) return true;
+
+    // 203.0.113.0/24 (TEST-NET-3)
+    if (a === 203 && b === 0) return true;
+
+    // 224.0.0.0/4 (Multicast) & 240.0.0.0/4 (Reserved)
+    if (a >= 224) return true;
+
+    return false;
+  }
+
+  // IPv6 checks
+  const normalized = ip.toLowerCase();
+
+  // ::1 (Loopback)
+  if (normalized === '::1' || normalized === '0:0:0:0:0:0:0:1') return true;
+
+  // :: (Unspecified)
+  if (normalized === '::' || normalized === '0:0:0:0:0:0:0:0') return true;
+
+  // IPv4-mapped IPv6 (e.g. ::ffff:127.0.0.1)
+  if (normalized.startsWith('::ffff:')) {
+    const v4Part = normalized.slice(7);
+    if (net.isIPv4(v4Part)) {
+      return isPrivateOrReservedIp(v4Part);
+    }
+  }
+
+  // fc00::/7 (Unique Local Address ULA)
+  if (normalized.startsWith('fc') || normalized.startsWith('fd')) return true;
+
+  // fe80::/10 (Link-Local Unicast)
+  if (/^fe[89ab]/.test(normalized)) return true;
+
+  // ff00::/8 (Multicast)
+  if (normalized.startsWith('ff')) return true;
+
+  return false;
+}
+
+export interface ValidateUrlOptions {
+  allowedDomains?: string[];
+  allowLocalhost?: boolean;
+}
+
+export interface ValidateUrlResult {
+  ok: boolean;
+  error?: string;
+  resolvedIp?: string;
+}
+
+/**
+ * Validates a remote URL against SSRF vulnerabilities:
+ * - Scheme must be http or https
+ * - Hostname cannot be localhost or known cloud metadata domains (unless allowLocalhost is true)
+ * - Domain must match allowedDomains list if specified
+ * - Pre-resolves DNS to ensure target IP is not private, loopback, or cloud metadata
+ */
+export async function validateExternalUrl(
+  rawUrl: string,
+  options: ValidateUrlOptions = {}
+): Promise<ValidateUrlResult> {
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    return { ok: false, error: 'INVALID_URL' };
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return { ok: false, error: 'INVALID_PROTOCOL' };
+  }
+
+  const hostname = parsed.hostname.toLowerCase();
+
+  // Disallow user/password in URL for SSRF protection
+  if (parsed.username || parsed.password) {
+    return { ok: false, error: 'CREDENTIALS_IN_URL_FORBIDDEN' };
+  }
+
+  // Common metadata and internal hosts
+  if (
+    hostname === 'metadata.google.internal' ||
+    hostname === 'instance-data' ||
+    hostname.endsWith('.internal') ||
+    hostname.endsWith('.local')
+  ) {
+    return { ok: false, error: 'FORBIDDEN_METADATA_HOST' };
+  }
+
+  if (!options.allowLocalhost && (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1')) {
+    return { ok: false, error: 'LOOPBACK_FORBIDDEN' };
+  }
+
+  // Allowed domains enforcement
+  if (options.allowedDomains && options.allowedDomains.length > 0) {
+    const isAllowed = options.allowedDomains.some((d) => {
+      const dom = d.toLowerCase().trim();
+      return hostname === dom || hostname.endsWith(`.${dom}`);
+    });
+    if (!isAllowed) {
+      return { ok: false, error: 'DOMAIN_NOT_ALLOWED' };
+    }
+  }
+
+  // If hostname is directly an IP literal
+  if (net.isIP(hostname)) {
+    if (!options.allowLocalhost && isPrivateOrReservedIp(hostname)) {
+      return { ok: false, error: 'FORBIDDEN_TARGET_IP', resolvedIp: hostname };
+    }
+    return { ok: true, resolvedIp: hostname };
+  }
+
+  // DNS Pre-check to prevent DNS rebinding
+  try {
+    const records = await dns.promises.lookup(hostname, { all: true });
+    if (!records || records.length === 0) {
+      return { ok: false, error: 'DNS_LOOKUP_EMPTY' };
+    }
+
+    for (const record of records) {
+      if (!options.allowLocalhost && isPrivateOrReservedIp(record.address)) {
+        return { ok: false, error: 'FORBIDDEN_TARGET_IP', resolvedIp: record.address };
+      }
+    }
+
+    return { ok: true, resolvedIp: records[0].address };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: `DNS_LOOKUP_FAILED: ${message}` };
+  }
+}

package/src/runtime/queue-engine.ts

@@ -31,6 +31,7 @@ export interface JobRecord {
   run_at: number;
   created_at: number;
   updated_at: number;
+  locked_at?: number | null;
   last_error: string | null;
 }
 
@@ -38,15 +39,23 @@ export interface QueueEngineOptions {
   /** Path to SQLite database file or ':memory:' */
   dbPath?: string;
   logger?: StructuredLogger;
+  /** Inactivity window in ms before a 'running' job without heartbeat is recovered (default: 300_000ms = 5m) */
+  visibilityTimeoutMs?: number;
+  /** Inactivity window in seconds (alternative to visibilityTimeoutMs) */
+  visibilityTimeoutSeconds?: number;
 }
 
 export class QueueEngine {
   private db: Database;
   private registry: Map<string, JobDefinition<unknown>> = new Map();
   private logger: StructuredLogger;
+  private visibilityTimeoutMs: number;
 
   constructor(options: QueueEngineOptions = {}) {
     this.logger = options.logger || createDefaultLogger('QueueEngine');
+    this.visibilityTimeoutMs =
+      options.visibilityTimeoutMs ??
+      (options.visibilityTimeoutSeconds !== undefined ? options.visibilityTimeoutSeconds * 1000 : 300_000);
     const dbPath = options.dbPath || path.join(process.cwd(), '.synapse/queue.sqlite');
 
     if (dbPath !== ':memory:') {
@@ -80,11 +89,22 @@ export class QueueEngine {
         run_at INTEGER NOT NULL,
         created_at INTEGER NOT NULL,
         updated_at INTEGER NOT NULL,
+        locked_at INTEGER,
         last_error TEXT
       );
       CREATE INDEX IF NOT EXISTS idx_synapse_jobs_pending 
       ON _synapse_jobs (status, run_at, priority DESC);
     `);
+    try {
+      this.db.run('ALTER TABLE _synapse_jobs ADD COLUMN locked_at INTEGER;');
+    } catch {
+      // Column already exists
+    }
+    try {
+      this.db.run('CREATE INDEX IF NOT EXISTS idx_synapse_jobs_stale ON _synapse_jobs (status, locked_at);');
+    } catch {
+      // Index already exists
+    }
   }
 
   /**
@@ -123,23 +143,37 @@ export class QueueEngine {
   }
 
   /**
-   * Atomically claims the next pending job eligible for execution.
+   * Atomically claims the next pending job eligible for execution, or recovers
+   * any stale 'running' job whose worker has died (visibility timeout exceeded).
    */
-  claimNextJob(): JobRecord | null {
+  claimNextJob(visibilityTimeoutMs?: number): JobRecord | null {
     const now = Date.now();
+    const timeout = visibilityTimeoutMs ?? this.visibilityTimeoutMs;
+    const staleThreshold = now - timeout;
+
+    // Fail expired zombie jobs that already exhausted max_attempts
+    this.db
+      .prepare(`
+      UPDATE _synapse_jobs
+      SET status = 'failed', locked_at = NULL, updated_at = ?1, last_error = 'Visibility timeout exceeded max attempts'
+      WHERE status = 'running' AND (locked_at IS NULL OR locked_at < ?2) AND attempts >= max_attempts
+    `)
+      .run(now, staleThreshold);
+
     const stmt = this.db.prepare(`
       UPDATE _synapse_jobs
-      SET status = 'running', updated_at = ?1
+      SET status = 'running', locked_at = ?1, updated_at = ?1, attempts = attempts + 1
       WHERE id = (
         SELECT id FROM _synapse_jobs
-        WHERE status = 'pending' AND run_at <= ?1
+        WHERE (status = 'pending' AND run_at <= ?1)
+           OR (status = 'running' AND (locked_at IS NULL OR locked_at < ?2) AND attempts < max_attempts)
         ORDER BY priority DESC, run_at ASC, created_at ASC
         LIMIT 1
       )
       RETURNING *;
     `);
 
-    const row = stmt.get(now) as JobRecord | undefined;
+    const row = stmt.get(now, staleThreshold) as JobRecord | undefined;
     return row || null;
   }
 
@@ -158,7 +192,7 @@ export class QueueEngine {
     }
 
     const jobDef = this.registry.get(job.name);
-    const attempts = job.attempts + 1;
+    const attempts = job.attempts;
     const now = Date.now();
 
     if (!jobDef) {
@@ -166,10 +200,10 @@ export class QueueEngine {
       this.logger.error(errorMsg);
       const updateStmt = this.db.prepare(`
         UPDATE _synapse_jobs
-        SET status = 'failed', attempts = ?1, updated_at = ?2, last_error = ?3
-        WHERE id = ?4
+        SET status = 'failed', locked_at = NULL, updated_at = ?1, last_error = ?2
+        WHERE id = ?3 AND (locked_at = ?4 OR locked_at IS NULL)
       `);
-      updateStmt.run(attempts, now, errorMsg, job.id);
+      updateStmt.run(now, errorMsg, job.id, job.locked_at ?? null);
       return true;
     }
 
@@ -180,10 +214,10 @@ export class QueueEngine {
       const errorMsg = `Falha ao desserializar payload JSON do job: ${String(parseErr)}`;
       const updateStmt = this.db.prepare(`
         UPDATE _synapse_jobs
-        SET status = 'failed', attempts = ?1, updated_at = ?2, last_error = ?3
-        WHERE id = ?4
+        SET status = 'failed', locked_at = NULL, updated_at = ?1, last_error = ?2
+        WHERE id = ?3 AND (locked_at = ?4 OR locked_at IS NULL)
       `);
-      updateStmt.run(attempts, now, errorMsg, job.id);
+      updateStmt.run(now, errorMsg, job.id, job.locked_at ?? null);
       return true;
     }
 
@@ -199,10 +233,10 @@ export class QueueEngine {
       await jobDef.handler(parsedPayload, actionCtx);
       const completeStmt = this.db.prepare(`
         UPDATE _synapse_jobs
-        SET status = 'completed', attempts = ?1, updated_at = ?2, last_error = NULL
-        WHERE id = ?3
+        SET status = 'completed', locked_at = NULL, updated_at = ?1, last_error = NULL
+        WHERE id = ?2 AND (locked_at = ?3 OR locked_at IS NULL)
       `);
-      completeStmt.run(attempts, now, job.id);
+      completeStmt.run(now, job.id, job.locked_at ?? null);
       return true;
     } catch (handlerErr: unknown) {
       const errorMsg = handlerErr instanceof Error ? handlerErr.message : String(handlerErr);
@@ -214,17 +248,17 @@ export class QueueEngine {
         const nextRunAt = now + backoffMs;
         const retryStmt = this.db.prepare(`
           UPDATE _synapse_jobs
-          SET status = 'pending', attempts = ?1, run_at = ?2, updated_at = ?3, last_error = ?4
-          WHERE id = ?5
+          SET status = 'pending', locked_at = NULL, run_at = ?1, updated_at = ?2, last_error = ?3
+          WHERE id = ?4 AND (locked_at = ?5 OR locked_at IS NULL)
         `);
-        retryStmt.run(attempts, nextRunAt, now, errorMsg, job.id);
+        retryStmt.run(nextRunAt, now, errorMsg, job.id, job.locked_at ?? null);
       } else {
         const failStmt = this.db.prepare(`
           UPDATE _synapse_jobs
-          SET status = 'failed', attempts = ?1, updated_at = ?2, last_error = ?3
-          WHERE id = ?4
+          SET status = 'failed', locked_at = NULL, updated_at = ?1, last_error = ?2
+          WHERE id = ?3 AND (locked_at = ?4 OR locked_at IS NULL)
         `);
-        failStmt.run(attempts, now, errorMsg, job.id);
+        failStmt.run(now, errorMsg, job.id, job.locked_at ?? null);
       }
       return true;
     }

package/src/runtime/rate-limiter.ts

@@ -18,6 +18,8 @@ export interface RateLimitOptions {
   refillRate?: number;
   /** Inactivity window in ms before bucket is evicted (default: 60,000ms = 1m) */
   idleTimeoutMs?: number;
+  /** Maximum tracked buckets in memory before LRU eviction (default: 10,000) */
+  maxBuckets?: number;
 }
 
 export interface RateLimitResult {
@@ -37,6 +39,7 @@ export class TokenBucketRateLimiter {
   private capacity: number;
   private refillRate: number;
   private idleTimeoutMs: number;
+  private maxBuckets: number;
   private buckets: Map<string, Bucket> = new Map();
   private cleanupTimer: ReturnType<typeof setInterval> | null = null;
 
@@ -47,6 +50,7 @@ export class TokenBucketRateLimiter {
     this.refillRate = options.refillRate ?? (Number.isFinite(envRps) && envRps > 0 ? envRps : 100);
     this.capacity = options.capacity ?? (Number.isFinite(envBurst) && envBurst > 0 ? envBurst : 150);
     this.idleTimeoutMs = options.idleTimeoutMs ?? 60_000;
+    this.maxBuckets = options.maxBuckets ?? 10_000;
 
     // Run background prune of idle buckets every minute
     this.cleanupTimer = setInterval(() => this.pruneIdleBuckets(), this.idleTimeoutMs);
@@ -63,12 +67,22 @@ export class TokenBucketRateLimiter {
     let bucket = this.buckets.get(key);
 
     if (!bucket) {
+      if (this.buckets.size >= this.maxBuckets) {
+        const oldest = this.buckets.keys().next().value;
+        if (oldest !== undefined) {
+          this.buckets.delete(oldest);
+        }
+      }
       bucket = {
         tokens: this.capacity,
         lastRefill: now,
         lastAccess: now
       };
       this.buckets.set(key, bucket);
+    } else {
+      // Move to end to track recency (LRU)
+      this.buckets.delete(key);
+      this.buckets.set(key, bucket);
     }
 
     // Refill tokens based on elapsed time