@juspay/neurolink 9.83.0 → 9.84.0

package/dist/lib/types/agentNetwork.js

@@ -0,0 +1,8 @@
+/**
+ * Agent Network Types for Multi-Agent Orchestration
+ *
+ * These types define the core abstractions for NeuroLink's multi-agent system,
+ * enabling intelligent routing, agent collaboration, and hierarchical networks.
+ */
+export {};
+//# sourceMappingURL=agentNetwork.js.map

package/dist/lib/types/cli.d.ts

@@ -1550,3 +1550,69 @@ export type CliClassifierRouterFlags = {
     /** LLM-classifier hard timeout in ms (--classifier-timeout). */
     classifierTimeout?: number;
 };
+/**
+ * Agent command arguments for multi-agent orchestration
+ */
+export type CliAgentCommandArgs = BaseCommandArgs & {
+    /** Agent ID */
+    id?: string;
+    /** Agent name */
+    name?: string;
+    /** Agent description */
+    description?: string;
+    /** Agent instructions/system prompt */
+    instructions?: string;
+    /** AI provider to use */
+    provider?: string;
+    /** Model name */
+    model?: string;
+    /** Tools available to the agent */
+    tools?: string[];
+    /** Maximum execution steps */
+    maxSteps?: number;
+    /** Temperature setting */
+    temperature?: number;
+    /** Input prompt for execution */
+    input?: string;
+    /** Context data as JSON */
+    context?: string;
+    /** Agent definition file path */
+    file?: string;
+    /** Output file path */
+    output?: string;
+    /** Enable streaming output */
+    stream?: boolean;
+    /** Show detailed information */
+    detailed?: boolean;
+};
+/**
+ * Network command arguments for agent network orchestration
+ */
+export type CliNetworkCommandArgs = BaseCommandArgs & {
+    /** Network ID */
+    id?: string;
+    /** Network name */
+    name?: string;
+    /** Network description */
+    description?: string;
+    /** Network configuration file path */
+    file?: string;
+    /** Input message for execution */
+    input?: string;
+    /** Maximum execution steps */
+    maxSteps?: number;
+    /** Execution timeout in ms */
+    timeout?: number;
+    /** Context data as JSON */
+    context?: string;
+    /** Output file path */
+    output?: string;
+    /** Enable streaming output */
+    stream?: boolean;
+    /** Router provider */
+    routerProvider?: string;
+    /** Router model */
+    routerModel?: string;
+    /** Show detailed information */
+    detailed?: boolean;
+};

package/dist/lib/types/generate.d.ts

@@ -18,6 +18,7 @@ import type { FileWithMetadata } from "./file.js";
 import type { WorkflowConfig } from "./workflow.js";
 import type { Schema, Tool, ToolChoice } from "./tools.js";
 import type { StepResult, LanguageModel } from "./providers.js";
+import type { ProcessorPipelineConfig } from "./ioProcessor.js";
 /**
  * Generate function options type - Primary method for content generation
  * Supports multimodal content while maintaining backward compatibility
@@ -570,6 +571,50 @@ export type GenerateOptions = {
          */
         additionalUsers?: AdditionalMemoryUser[];
     };
+    /**
+     * PII detection — scans and optionally redacts PII from input before the LLM call.
+     * @example { enabled: true, action: "redact", detectTypes: ["ssn", "email"] }
+     */
+    piiDetection?: {
+        enabled?: boolean;
+        action?: "redact" | "abort" | "warn";
+        detectTypes?: Array<"email" | "phone" | "ssn" | "creditCard" | "ipAddress" | "address" | "name" | "dateOfBirth" | "passport" | "driversLicense">;
+        customPatterns?: RegExp[];
+        allowList?: string[];
+        redactionText?: string;
+    };
+    /**
+     * Response validation — validates and optionally transforms the LLM response.
+     * Supports retry-with-feedback when `retryOnFailure: true`.
+     * @example { maxLength: 5000, truncationAction: "truncate", retryOnFailure: true }
+     */
+    responseValidation?: {
+        minLength?: number;
+        maxLength?: number;
+        requiredPhrases?: string[];
+        forbiddenPhrases?: string[];
+        jsonSchema?: Record<string, unknown>;
+        customValidator?: (text: string) => {
+            category: string;
+            severity: "error" | "warning" | "info";
+            message: string;
+        } | null;
+        truncationAction?: "abort" | "retry" | "truncate" | "warn";
+        truncationSuffix?: string;
+        retryOnFailure?: boolean;
+        maxRetries?: number;
+    };
+    /** Input validation — validates input text before any processing. */
+    inputValidation?: {
+        trimWhitespace?: boolean;
+        minLength?: number;
+        maxLength?: number;
+        requireContent?: boolean;
+    };
+    /**
+     * @deprecated Use `piiDetection`, `responseValidation`, and `inputValidation` instead.
+     */
+    processors?: ProcessorPipelineConfig;
 };
 /**
  * Represents an additional user whose memory should be included in a generate/stream call.
@@ -1192,6 +1237,14 @@ export type TextGenerationOptions = {
      * callers can correlate generation traces back to their own request lifecycle.
      */
     requestId?: string;
+    /** PII detection config — forwarded from GenerateOptions/StreamOptions. */
+    piiDetection?: GenerateOptions["piiDetection"];
+    /** Response validation config — forwarded from GenerateOptions/StreamOptions. */
+    responseValidation?: GenerateOptions["responseValidation"];
+    /** Input validation config — forwarded from GenerateOptions/StreamOptions. */
+    inputValidation?: GenerateOptions["inputValidation"];
+    /** @deprecated Use `piiDetection`, `responseValidation`, `inputValidation` instead. */
+    processors?: ProcessorPipelineConfig;
 };
 /**
  * Text generation result (consolidated from core types)

package/dist/lib/types/index.d.ts

@@ -57,6 +57,7 @@ export * from "./voice.js";
 export * from "./universalProviderOptions.js";
 export * from "./utilities.js";
 export * from "./workflow.js";
+export * from "./ioProcessor.js";
 export * from "./exporter.js";
 export * from "./span.js";
 export * from "./imageGen.js";
@@ -72,3 +73,4 @@ export * from "./safeFetch.js";
 export * from "./modelPool.js";
 export * from "./requestRouter.js";
 export * from "./classifierRouter.js";
+export * from "./agentNetwork.js";

package/dist/lib/types/index.js

@@ -59,6 +59,7 @@ export * from "./universalProviderOptions.js";
 export * from "./utilities.js";
 export * from "./workflow.js";
 // Processor base types are re-exported via ./processor.js
+export * from "./ioProcessor.js";
 export * from "./exporter.js";
 export * from "./span.js";
 export * from "./imageGen.js";
@@ -82,4 +83,6 @@ export * from "./modelPool.js";
 export * from "./requestRouter.js";
 // ClassifierRouter — classify → pick model + tools from a base pool (M9.x+)
 export * from "./classifierRouter.js";
+// Multi-Agent orchestration types
+export * from "./agentNetwork.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/types/ioProcessor.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Safety Utility Types for NeuroLink
+ *
+ * Types used by the PII detection, response validation, and tripwire
+ * evaluation utilities wired into generate() and stream().
+ *
+ * @module ioProcessor
+ */
+export type PiiType = "email" | "phone" | "ssn" | "creditCard" | "ipAddress" | "address" | "name" | "dateOfBirth" | "passport" | "driversLicense";
+export type PiiDetectionConfig = {
+    enabled?: boolean;
+    action: "redact" | "abort" | "warn";
+    detectTypes?: PiiType[];
+    customPatterns?: RegExp[];
+    allowList?: string[];
+    redactionText?: string;
+};
+export type DetectedPII = {
+    type: PiiType | "custom";
+    value: string;
+    position: {
+        start: number;
+        end: number;
+    };
+    /** Which field the PII was found in (e.g. "text", "messages[2]") */
+    field: string;
+};
+export type PiiDetectionResult = {
+    /** Redacted text when action=redact, otherwise the original text */
+    text: string;
+    detectedPII: DetectedPII[];
+    action: "continue" | "abort";
+    /** Human-readable message about what was found */
+    feedback?: string;
+};
+export type ResponseValidationConfig = {
+    /** Minimum required character length for the response */
+    minLength?: number;
+    /** Maximum allowed character length for the response */
+    maxLength?: number;
+    /** Phrases that must appear in the response (case-insensitive) */
+    requiredPhrases?: string[];
+    /** Phrases that must NOT appear in the response (case-insensitive) */
+    forbiddenPhrases?: string[];
+    /** JSON Schema to validate the response against (response must be valid JSON) */
+    jsonSchema?: Record<string, unknown>;
+    /** Custom validation function; return a ValidationIssue to signal failure, null to pass */
+    customValidator?: (text: string) => ValidationIssue | null;
+    /**
+     * Action to take when maxLength is exceeded:
+     * - "truncate" — slice text to maxLength + suffix (default)
+     * - "abort"    — return action:"abort"
+     * - "retry"    — return action:"retry" with feedback
+     * - "warn"     — log a warning but return the unmodified text
+     */
+    truncationAction?: "abort" | "retry" | "truncate" | "warn";
+    /** Suffix appended when truncating (default: "..."). Never causes the final string to exceed maxLength. */
+    truncationSuffix?: string;
+    /** Return action:"retry" when any error-severity issue is found */
+    retryOnFailure?: boolean;
+    /** Maximum allowed retry count (informational — caller enforces the loop) */
+    maxRetries?: number;
+};
+export type ValidationIssue = {
+    /** Short machine-readable category (e.g., "length", "json_schema", "phrase") */
+    category: string;
+    severity: "error" | "warning" | "info";
+    message: string;
+    /** Optional field path (useful for JSON schema errors) */
+    field?: string;
+};
+export type ResponseValidationResult = {
+    /** Possibly-mutated response text (truncation may shorten it) */
+    text: string;
+    /** What the caller should do next */
+    action: "continue" | "abort" | "retry";
+    /** All issues found during validation */
+    issues: ValidationIssue[];
+    /** Human-readable summary suitable for inclusion in a retry prompt */
+    feedback?: string;
+    /** The retryCount that was passed in (echoed back for convenience) */
+    retryCount?: number;
+};
+export type TripwireAction = "abort" | "warn" | "log";
+export type TripwireData = {
+    responseText?: string;
+    inputText?: string;
+    latencyMs?: number;
+    tokenUsage?: {
+        input?: number;
+        output?: number;
+        total?: number;
+    };
+    messageCount?: number;
+    finishReason?: string;
+};
+export type TripwireConfig = {
+    id: string;
+    name: string;
+    description: string;
+    action: TripwireAction;
+    condition: (data: TripwireData) => boolean;
+    message?: string | ((data: TripwireData) => string);
+};
+export type TripwireResult = {
+    triggered: boolean;
+    tripwire?: TripwireConfig;
+    message?: string;
+    action?: TripwireAction;
+};
+/** @deprecated Use piiDetection/responseValidation/inputValidation on GenerateOptions instead */
+export type ProcessorPipelineConfig = {
+    name?: string;
+    stopOnAbort?: boolean;
+    pipelineTimeoutMs?: number;
+    inputProcessors?: unknown[];
+    outputProcessors?: unknown[];
+    settings?: Record<string, unknown>;
+};

package/dist/lib/types/ioProcessor.js

@@ -0,0 +1,10 @@
+/**
+ * Safety Utility Types for NeuroLink
+ *
+ * Types used by the PII detection, response validation, and tripwire
+ * evaluation utilities wired into generate() and stream().
+ *
+ * @module ioProcessor
+ */
+export {};
+//# sourceMappingURL=ioProcessor.js.map

package/dist/lib/types/stream.d.ts

@@ -17,6 +17,7 @@ import type { FileWithMetadata } from "./file.js";
 import type { WorkflowConfig } from "./workflow.js";
 import type { LanguageModel, StepResult } from "./providers.js";
 import type { Tool, ToolChoice } from "./tools.js";
+import type { ProcessorPipelineConfig } from "./ioProcessor.js";
 /**
  * Progress tracking and metadata for streaming operations
  */
@@ -498,6 +499,41 @@ export type StreamOptions = {
          */
         additionalUsers?: AdditionalMemoryUser[];
     };
+    /** PII detection — scans and optionally redacts PII from input before the LLM call. */
+    piiDetection?: {
+        enabled?: boolean;
+        action?: "redact" | "abort" | "warn";
+        detectTypes?: Array<"email" | "phone" | "ssn" | "creditCard" | "ipAddress" | "address" | "name" | "dateOfBirth" | "passport" | "driversLicense">;
+        customPatterns?: RegExp[];
+        allowList?: string[];
+        redactionText?: string;
+    };
+    /** Response validation — validates accumulated stream content after completion. */
+    responseValidation?: {
+        minLength?: number;
+        maxLength?: number;
+        requiredPhrases?: string[];
+        forbiddenPhrases?: string[];
+        jsonSchema?: Record<string, unknown>;
+        customValidator?: (text: string) => {
+            category: string;
+            severity: "error" | "warning" | "info";
+            message: string;
+        } | null;
+        truncationAction?: "abort" | "retry" | "truncate" | "warn";
+        truncationSuffix?: string;
+        retryOnFailure?: boolean;
+        maxRetries?: number;
+    };
+    /** Input validation — validates input text before any processing. */
+    inputValidation?: {
+        trimWhitespace?: boolean;
+        minLength?: number;
+        maxLength?: number;
+        requireContent?: boolean;
+    };
+    /** @deprecated Use `piiDetection`, `responseValidation`, and `inputValidation` instead. */
+    processors?: ProcessorPipelineConfig;
 };
 /**
  * Stream function result type - Primary output format for streaming

package/dist/lib/utils/piiDetector.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PII Detection Utility
+ *
+ * Standalone utility for detecting and redacting personally identifiable
+ * information (PII) from text. Used by generate() and stream() directly.
+ *
+ * @module piiDetector
+ */
+import type { PiiDetectionConfig, PiiDetectionResult } from "../types/index.js";
+/**
+ * Detect and optionally redact PII from a text string.
+ *
+ * Detection runs per-field (each named segment scanned independently) so that
+ * offset positions always refer to the correct field's text — not a concatenated
+ * blob (Bug C3 fix).
+ *
+ * Custom patterns are validated before execution to prevent catastrophic
+ * backtracking (Bug C10 fix).
+ *
+ * @param text - The input text to scan
+ * @param config - PII detection configuration
+ * @returns Detection result with (optionally) redacted text and found PII
+ */
+export declare function detectAndRedactPII(text: string, config: PiiDetectionConfig): Promise<PiiDetectionResult>;

package/dist/lib/utils/piiDetector.js

@@ -0,0 +1,221 @@
+/**
+ * PII Detection Utility
+ *
+ * Standalone utility for detecting and redacting personally identifiable
+ * information (PII) from text. Used by generate() and stream() directly.
+ *
+ * @module piiDetector
+ */
+import { logger } from "./logger.js";
+// ============================================================================
+// Built-in patterns
+// ============================================================================
+const PII_PATTERNS = {
+    email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/gi,
+    phone: /\b(\+?1[-.\s]?)?(\(?\d{3}\)?[-.\s]?)?\d{3}[-.\s]?\d{4}\b/g,
+    ssn: /\b\d{3}[-\s]?\d{2}[-\s]?\d{4}\b/g,
+    creditCard: /\b(?:\d{4}[-\s]?){3}\d{4}\b/g,
+    ipAddress: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+    address: /\b\d+\s+[\w\s]+(?:street|st|avenue|ave|road|rd|boulevard|blvd|drive|dr|lane|ln|court|ct)\b/gi,
+    name: /\b[A-Z][a-z]+\s+[A-Z][a-z]+\b/g,
+    dateOfBirth: /\b(?:0?[1-9]|1[0-2])[-/](?:0?[1-9]|[12]\d|3[01])[-/](?:19|20)\d{2}\b/g,
+    passport: /\b[A-Z]{1,2}\d{6,9}\b/g,
+    driversLicense: /\b[A-Z]{1,2}\d{5,8}\b/g,
+};
+const DEFAULT_PII_TYPES = ["email", "phone", "ssn", "creditCard"];
+// ============================================================================
+// Catastrophic backtracking detection (Bug C10)
+// ============================================================================
+/**
+ * Heuristic check for patterns that can cause catastrophic backtracking.
+ * Looks for nested quantifiers such as (a+)+ or (a*)* and similar structures.
+ */
+function hasCatastrophicBacktracking(pattern) {
+    const src = pattern.source;
+    // Simple string-based check for nested quantifiers: (X+)+ (X*)+ etc.
+    // Avoids using a regex here (CodeQL flags polynomial regex on untrusted input).
+    for (let i = 0; i < src.length - 1; i++) {
+        if (src[i] === ")" && (src[i + 1] === "+" || src[i + 1] === "*")) {
+            // Found a closing group followed by a quantifier — check if the group
+            // itself contains a quantifier.
+            const groupEnd = i;
+            let depth = 1;
+            let j = groupEnd - 1;
+            while (j >= 0 && depth > 0) {
+                if (src[j] === ")") {
+                    depth++;
+                }
+                if (src[j] === "(") {
+                    depth--;
+                }
+                j--;
+            }
+            const groupStart = j + 1;
+            const groupBody = src.slice(groupStart + 1, groupEnd);
+            if (groupBody.includes("+") || groupBody.includes("*")) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Validate a custom RegExp before use (Bug C10).
+ * Returns an error string if invalid, or null if safe.
+ */
+function validateCustomPattern(pattern) {
+    if (!(pattern instanceof RegExp)) {
+        return "Custom pattern is not a RegExp instance";
+    }
+    if (hasCatastrophicBacktracking(pattern)) {
+        return `Custom pattern /${pattern.source}/ contains nested quantifiers that may cause catastrophic backtracking`;
+    }
+    return null;
+}
+// ============================================================================
+// Per-field detection helpers (Bug C3 fix)
+// ============================================================================
+/**
+ * Scan a single field's text with one regex pattern.
+ * Returns DetectedPII entries with field-local offsets.
+ */
+function scanField(fieldText, fieldName, type, pattern) {
+    // Reset lastIndex to avoid cross-call state leaking between scans.
+    // We mutate the pattern's lastIndex directly rather than constructing a new
+    // RegExp from .source/.flags (which CodeQL flags as regex injection).
+    pattern.lastIndex = 0;
+    const regex = pattern;
+    const results = [];
+    let match = regex.exec(fieldText);
+    while (match !== null) {
+        results.push({
+            type,
+            value: match[0],
+            position: { start: match.index, end: match.index + match[0].length },
+            field: fieldName,
+        });
+        // Guard against zero-width matches causing infinite loops
+        if (match[0].length === 0) {
+            regex.lastIndex++;
+        }
+        match = regex.exec(fieldText);
+    }
+    return results;
+}
+/**
+ * Apply redactions to a single field's text given its DetectedPII entries.
+ * Redacts in reverse position order so earlier offsets stay valid.
+ */
+function redactField(fieldText, hits, redactionText) {
+    // Sort descending by start position
+    const sorted = [...hits].sort((a, b) => b.position.start - a.position.start);
+    let result = fieldText;
+    for (const hit of sorted) {
+        result =
+            result.slice(0, hit.position.start) +
+                redactionText +
+                result.slice(hit.position.end);
+    }
+    return result;
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Detect and optionally redact PII from a text string.
+ *
+ * Detection runs per-field (each named segment scanned independently) so that
+ * offset positions always refer to the correct field's text — not a concatenated
+ * blob (Bug C3 fix).
+ *
+ * Custom patterns are validated before execution to prevent catastrophic
+ * backtracking (Bug C10 fix).
+ *
+ * @param text - The input text to scan
+ * @param config - PII detection configuration
+ * @returns Detection result with (optionally) redacted text and found PII
+ */
+export async function detectAndRedactPII(text, config) {
+    const { action, detectTypes = DEFAULT_PII_TYPES, customPatterns = [], allowList = [], redactionText = "[REDACTED]", } = config;
+    if (!text) {
+        return { text, detectedPII: [], action: "continue" };
+    }
+    // Validate custom patterns up-front (Bug C10)
+    const validatedCustomPatterns = [];
+    for (const pattern of customPatterns) {
+        const err = validateCustomPattern(pattern);
+        if (err) {
+            logger.warn(`piiDetector: skipping invalid custom pattern — ${err}`);
+            continue;
+        }
+        validatedCustomPatterns.push(pattern);
+    }
+    const allDetected = [];
+    // Scan built-in PII types (Bug C3: scan the field in isolation)
+    for (const piiType of detectTypes) {
+        if (allowList.includes(piiType)) {
+            continue;
+        }
+        const pattern = PII_PATTERNS[piiType];
+        if (!pattern) {
+            continue;
+        }
+        const hits = scanField(text, "text", piiType, pattern);
+        allDetected.push(...hits);
+    }
+    // Scan custom patterns
+    for (const pattern of validatedCustomPatterns) {
+        let hits = [];
+        try {
+            hits = scanField(text, "text", "custom", pattern);
+        }
+        catch (err) {
+            logger.warn(`piiDetector: custom pattern /${pattern.source}/ threw during execution — skipping`, err);
+        }
+        allDetected.push(...hits);
+    }
+    if (allDetected.length === 0) {
+        if (logger.shouldLog("debug")) {
+            logger.debug("piiDetector: no PII detected in input");
+        }
+        return { text, detectedPII: [], action: "continue" };
+    }
+    if (logger.shouldLog("debug")) {
+        logger.debug(`piiDetector: detected ${allDetected.length} PII occurrence(s) — action=${action}`);
+    }
+    // Summarise findings for feedback
+    const typeCounts = allDetected.reduce((acc, d) => {
+        acc[d.type] = (acc[d.type] ?? 0) + 1;
+        return acc;
+    }, {});
+    const summary = Object.entries(typeCounts)
+        .map(([t, n]) => `${t} (${n})`)
+        .join(", ");
+    if (action === "abort") {
+        return {
+            text,
+            detectedPII: allDetected,
+            action: "abort",
+            feedback: `PII detected: ${summary}. Request blocked for security.`,
+        };
+    }
+    if (action === "redact") {
+        // Redact per-field (Bug C3: field hits already carry field-local offsets)
+        const fieldHits = allDetected.filter((d) => d.field === "text");
+        const redactedText = redactField(text, fieldHits, redactionText);
+        return {
+            text: redactedText,
+            detectedPII: allDetected,
+            action: "continue",
+            feedback: `PII redacted: ${summary}.`,
+        };
+    }
+    // action === "warn"
+    return {
+        text,
+        detectedPII: allDetected,
+        action: "continue",
+        feedback: `PII detected (not redacted): ${summary}.`,
+    };
+}
+//# sourceMappingURL=piiDetector.js.map

package/dist/lib/utils/responseValidator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Response Validator
+ *
+ * Standalone utility for validating and optionally mutating LLM response text.
+ * Handles length checks (including truncation), phrase checks, JSON schema
+ * validation, and custom validators.  Returns a structured result telling the
+ * caller whether to continue, abort, or retry — the caller owns the retry loop.
+ *
+ * No async I/O, no telemetry spans, no processor classes.
+ */
+import type { ResponseValidationConfig, ResponseValidationResult } from "../types/index.js";
+/**
+ * Validate (and optionally mutate) an LLM response.
+ *
+ * @param responseText - The raw text returned by the model.
+ * @param config       - Validation rules and action preferences.
+ * @param retryCount   - Current retry iteration (passed through to result).
+ * @returns A {@link ResponseValidationResult} with the (possibly truncated)
+ *          text, a disposition action, all issues found, and optional feedback.
+ */
+export declare function validateResponse(responseText: string, config: ResponseValidationConfig, retryCount?: number): ResponseValidationResult;